From 5d87ac13d99f53cbdafd1e5b2cf4b8f1c979da36 Mon Sep 17 00:00:00 2001 From: Jake Jarvis Date: Tue, 5 Oct 2021 11:26:23 -0400 Subject: [PATCH] documentation! --- README.md | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- index.d.ts | 11 +++--- index.js | 2 +- 3 files changed, 104 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index ff4932f..1d5de93 100644 --- a/README.md +++ b/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 diff --git a/index.d.ts b/index.d.ts index ed77aea..7b026bc 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,14 +1,15 @@ export interface Options { /** - * Filename of the download, helpful if the one provided by the server doesn't - * match the name listed in the checksum file. + * 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. * * @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; +export default function downloader(downloadUrl: string, checksumUrl: string, options: Options): Promise; diff --git a/index.js b/index.js index 5d9852b..cec8d7f 100644 --- a/index.js +++ b/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(),