documentation!

README.md

@@ -1,8 +1,103 @@
 # 🕵️‍♀️ careful-download
 
-**🚧 Work in progress!**
+[![CI](https://github.com/jakejarvis/careful-download/actions/workflows/ci.yml/badge.svg)](https://github.com/jakejarvis/careful-download/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/careful-download?logo=npm)](https://www.npmjs.com/package/careful-download)
+[![MIT License](https://img.shields.io/github/license/jakejarvis/careful-download?color=red)](LICENSE)
 
-A wrapper around [`got`](https://github.com/sindresorhus/got), [`sumchecker`](https://github.com/malept/sumchecker), and [`decompress`](https://github.com/kevva/decompress). Downloads a file and its checksums to a temporary directory, validates the hash, and optionally extracts it if safe.
+Downloads a file and its checksums to a temporary directory, validates the hash, and optionally extracts it if safe. A headache-averting wrapper around [`got`](https://github.com/sindresorhus/got), [`sumchecker`](https://github.com/malept/sumchecker), and [`decompress`](https://github.com/kevva/decompress).
+
+## Install
+
+```sh
+npm install careful-download
+# or...
+yarn add careful-download
+```
+
+## Usage
+
+```js
+import downloader from "careful-download";
+
+await downloader(
+  "https://github.com/gohugoio/hugo/releases/download/v0.88.1/hugo_extended_0.88.1_Windows-64bit.zip",
+  "https://github.com/gohugoio/hugo/releases/download/v0.88.1/hugo_0.88.1_checksums.txt",
+  {
+    destDir: "./vendor",
+    algorithm: "sha256",
+    encoding: "binary",
+    extract: true,
+  },
+);
+//=> '/Users/jake/src/carefully-downloaded/vendor/hugo.exe'
+```
+
+## API
+
+### downloader(downloadUrl, checksumUrl, options?)
+
+#### downloadUrl
+
+Type: `string`
+
+#### checksumUrl
+
+Type: `string`
+
+#### options
+
+Type: `object`
+
+##### filename
+
+Type: `string`\
+Default: Extracted from the download URL.
+
+Manually set the filename of the download, helpful if the one provided by the server doesn't match the filename listed in the checksum file.
+
+##### extract
+
+Type: `boolean`\
+Default: `false`
+
+Use [`decompress`](https://github.com/kevva/decompress) to extract the final download to the destination directory (assuming it's a `.zip`, `.tar`, `.tar.gz`, etc.).
+
+##### tempDir
+
+Type: `string`\
+Default: [`tempy.directory()`](https://github.com/sindresorhus/tempy#tempydirectoryoptions)
+
+Path to temporary directory for unverified and/or unextracted downloads. Automatically generated if not set (recommended).
+
+##### destDir
+
+Type: `string`\
+Default: `"./downloads"`
+
+Full path or directory name relative to module to store the validated download.
+
+##### cleanDestDir
+
+Type: `boolean`\
+Default: `false`
+
+Delete any existing files in the destination directory before downloading.
+
+##### algorithm
+
+Type: `string`\
+Default: `"sha256"`
+
+The algorithm used by the checksum file. Available options are dependent on the version of OpenSSL on the platform. Examples are 'SHA1', 'SHA256', 'SHA512', 'MD5', etc.
+
+On recent releases of OpenSSL, `openssl list -digest-algorithms` will display the available digest algorithms. [Read more about `crypto.createHash()`.](https://nodejs.org/dist/latest-v14.x/docs/api/crypto.html#crypto_crypto_createhash_algorithm_options)
+
+##### encoding
+
+Type: `string`\
+Default: `"binary"`
+
+Tell the file stream to read the download as a binary, UTF-8 text file, base64, etc.
 
 ## License
 

index.d.ts

@@ -1,14 +1,15 @@
 export interface Options {
   /**
-   * Filename of the download, helpful if the one provided by the server doesn't
+   * Manually set the filename of the download, helpful if the one provided by
-   * match the name listed in the checksum file.
+   * the server doesn't match the filename listed in the checksum file.
    *
    * @default Extracted from the download URL.
    */
   readonly filename?: string;
 
   /**
-   * Use decompress to extract the final download to the destination directory.
+   * Use [`decompress`](https://github.com/kevva/decompress) to extract the
+   * final download to the destination directory.
    *
    * @default false
    */
@@ -45,7 +46,7 @@ export interface Options {
    * On recent releases of OpenSSL, `openssl list -digest-algorithms` will
    * display the available digest algorithms:
    *
-   * https://nodejs.org/dist/latest-v4.x/docs/api/crypto.html#crypto_crypto_createhash_algorithm
+   * https://nodejs.org/dist/latest-v14.x/docs/api/crypto.html#crypto_crypto_createhash_algorithm_options
    *
    * @default "sha256"
    */
@@ -63,4 +64,4 @@ export interface Options {
 /**
  * Download a file and validate it with its corresponding checksum file.
  */
-export default function downloadAndCheck(downloadUrl: string, checksumUrl: string, options: Options): Promise<string>;
+export default function downloader(downloadUrl: string, checksumUrl: string, options: Options): Promise<string>;

index.js

@@ -12,7 +12,7 @@ import urlParse from "url-parse";
 // https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c#what-do-i-use-instead-of-__dirname-and-__filename
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-export default async function downloadAndCheck(downloadUrl, checksumUrl, options) {
+export default async function downloader(downloadUrl, checksumUrl, options) {
   // normalize options and set defaults
   options = {
     filename: options.filename ?? urlParse(downloadUrl).pathname.split("/").pop(),