diff --git a/README.md b/README.md index ec6f1a3..ba16c64 100644 --- a/README.md +++ b/README.md @@ -33,171 +33,35 @@ additional snippets follow the links below. ## index.js Main exports for cross-platform addon configuration. - -``` -export const paths: (dir: string) => Readonly<{ - bin: string; - include: string; -}>; -export const bin: string; -export const platform: string; -export const include: string; -``` - -* `paths` - Returns a set of platform dependent paths depending on -input `dir`. - * `bin` - platform binary directory absolute path. - * `include` - include directory for this `dir`. -* `bin` - platform-dependent binary directory name. -* `platform` - platform name: `'windows', 'linux', 'osx'`. -* `include` - both `'addon-tools-raub'` and `'node-addon-api'` include paths. -Use with `node -p` through list context command expansion ` Promise; -export default download; -``` - -Accepts an **URL**, and returns an in-memory file Buffer, -when the file is loaded. Use for small files, as the whole -file will be loaded into memory at once. - -Example: -``` -download(srcUrl).then( - data => useData(data), - err => emit('error', err) -); -// or -const data = await download(srcUrl); -useData(data); -``` +See [TypeScript definitions](/downloads.d.ts). ## cpbin.js -Copies the addon binary from `src/build/Release` to the platform folder. - -``` -declare const cpbin: (name: string) => Promise; -export default cpbin; -``` - -It is useful for development builds. Use it in your **src/package.json**: -``` -"scripts": { - "build": "node-gyp rebuild && node -e \"require('addon-tools-raub/cpbin')('ADDON')\"" -}, -``` -Here ADDON should be replaced with the name of your addon, without `.node` extension. +Downloads a file into the memory, **HTTP** or **HTTPS**. +See [TypeScript definitions](/cpbin.d.ts). ## install.js Downloads and unzips the platform specific binary for the calling package. - -``` -declare const install: (folder: string) => void; -export default install; -``` - -To use it, create a new script for your package, which may as well be named -**install.js**, with the following content: - -``` -'use strict'; -const install = require('addon-tools-raub/install'); -const prefix = 'https://github.com/USER/ADDON-NAME/releases/download'; -const tag = 'v1.0.0'; -install(`${prefix}/${tag}`); -``` - -* `prefix` - the constant base part of the download url. -* `tag` - the version-dependent part of the url, -here `process.env.npm_package_config_install` is taken -([automatically](https://docs.npmjs.com/misc/config#per-package-config-settings)) -from **package.json**: - -``` - "config": { - "install": "v2.0.0" - }, - "scripts": { - "postinstall": "node install" - }, -``` +See [TypeScript definitions](/install.d.ts). ## writable-buffer.js A [Writable](https://nodejs.org/api/stream.html#stream_writable_streams) -stream buffer, that is stored in-memory and can be fully -obtained when writing was finished. It is equivalent to stream-writing -a temporary file and then reading it into a `Buffer`. - -``` -import type { Writable } from 'stream'; -export class WritableBuffer extends Writable { - constructor(); - get(): Buffer; -}; -``` - -Use `stream.get()` to obtain the data when writing was finished: -``` -const stream = new WritableBuffer(); -// ... -sourceStream.pipe(stream); -sourceStream.on('end', () => useData(stream.get())); -``` +stream buffer. +See [TypeScript definitions](/writable-buffer.d.ts). ## utils.js Async `fs` based helpers for common addon-related file operations. - -``` -import type { Stats } from 'fs'; -export const read: (name: string) => Promise; -export const write: (name: string, text: string) => Promise; -export const copy: (src: string, dest: string) => Promise; -export const exists: (name: string) => Promise; -export const mkdir: (name: string) => Promise; -export const stat: (name: string) => Promise; -export const isDir: (name: string) => Promise; -export const isFile: (name: string) => Promise; -export const dirUp: (dir: string) => string; -export const ensuredir: (dir: string) => Promise; -export const copysafe: (src: string, dest: string) => Promise; -export const readdir: (src: string, dest: string) => Promise>; -export const subdirs: (name: string) => Promise>; -export const subfiles: (name: string) => Promise>; -export const traverse: (name: string, showDirs?: boolean) => Promise>; -export const copyall: (src: string, dest: string) => Promise; -export const rmdir: (name: string) => Promise; -export const rm: (name: string) => Promise; -``` - -* `read` - (async) Reads a whole file to string, NOT a Buffer. -* `write` - (async) Write a file. -* `copy` - (async) Copy a file. -* `exists` - (async) Check if a file/folder exists. -* `mkdir` - (async) Create an empty folder. -* `stat` - (async) Get status on a file. -* `isDir` - (async) Check if the path is a folder. -* `isFile` - (async) Check if the path is a file. -* `dirUp` - Cut the path one folder up. -* `ensuredir` - (async) Like `mkdir -p`, makes sure a directory exists. -* `copysafe` - (async) Copy a file, `dest` folder is created if needed. -* `readdir` - (async) Get file/folder names of the 1st level. -* `subdirs` - (async) Get folder paths (concatenated with input) of the 1st level. -* `subfiles` - (async) Get file paths (concatenated with input) of the 1st level. -* `traverse` - (async) Get all nested files recursively. -* `copyall` - (async) Copy a folder with all the contained files. -* `rmdir` - (async) Like `rm -rf`, removes everything recursively. -* `rm` - (async) Remove a file. Must be a file, not a folder. Just `fs.unlink`. +See [TypeScript definitions](/writable-buffer.d.ts). diff --git a/cpbin.d.ts b/cpbin.d.ts index 77cbd86..bf0716f 100644 --- a/cpbin.d.ts +++ b/cpbin.d.ts @@ -1,2 +1,19 @@ -declare const cpbin: (name: string) => Promise; -export default cpbin; +declare module "addon-tools-raub/cpbin" { + /** + * Copy binary + * Copies the addon binary from `src/build/Release` to the platform folder. + * ``` + * declare const cpbin: (name: string) => Promise; + * export default cpbin; + * ``` + * It is useful for development builds. Use it in your **src/package.json**: + * ``` + * "scripts": { + * * "build": "node-gyp rebuild && node -e \"require('addon-tools-raub/cpbin')('ADDON')\"" + * }, + * ``` + * Here ADDON should be replaced with the name of your addon, without `.node` extension. + */ + const cpbin: (name: string) => Promise; + export = cpbin; +} diff --git a/download.d.ts b/download.d.ts index 4cd30c2..088a8b5 100644 --- a/download.d.ts +++ b/download.d.ts @@ -1,2 +1,19 @@ -declare const download: (url: string) => Promise; -export default download; +declare module "addon-tools-raub/download" { + /** + * Download to memory + * Accepts an **URL**, and returns an in-memory file Buffer, + * when the file is loaded. Use for small files, as the whole + * file will be loaded into memory at once. + * + * ``` + * download(srcUrl).then(data => useData(data), err => emit('error', err)); + * ``` + * or + * ``` + * const data = await download(srcUrl); + * useData(data); + * ``` + */ + const download: (url: string) => Promise; + export = download; +} diff --git a/index.d.ts b/index.d.ts index aef56a5..172bb19 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,7 +1,34 @@ -export const paths: (dir: string) => Readonly<{ - bin: string; - include: string; -}>; -export const bin: string; -export const platform: string; -export const include: string; +declare module "addon-tools-raub" { + /** + * Addon paths + * Returns a set of platform dependent paths depending on input dir + */ + export const paths: (dir: string) => Readonly<{ + /** + * Path to binaries + * Platform binary directory absolute path + */ + bin: string; + /** + * Path to include + * Include directory for this dir + */ + include: string; + }>; + /** + * Binary folder name + * Platform-dependent binary directory name + */ + export const bin: string; + /** + * Platform name + * One of: 'windows', 'linux', 'osx' + */ + export const platform: string; + /** + * Main include directories + * Both 'addon-tools-raub' and 'node-addon-api' include paths. + * Use with node -p through list context command expansion void; -export default install; +declare module "addon-tools-raub/install" { + /** + * Install binaries + * Downloads and unzips the platform specific binary for the calling package. + * To use it, create a new script for your package, which may as well be named + * **install.js**, with the following content: + * ``` + * 'use strict'; + * const install = require('addon-tools-raub/install'); + * const prefix = 'https://github.com/USER/ADDON-NAME/releases/download'; + * const tag = 'v1.0.0'; + * install(`${prefix}/${tag}`); + * ``` + * * `prefix` - the constant base part of the download url. + * * `tag` - the version-dependent part of the url. + * ``` + * "scripts": { + * "postinstall": "node install" + * }, + * ``` + */ + const install: (folder: string) => void; + export = install; +} diff --git a/package-lock.json b/package-lock.json index 6e6519d..ded1f35 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "addon-tools-raub", - "version": "5.3.0", + "version": "5.3.2", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 021ee21..eedd1a1 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "author": "Luis Blanco ", "name": "addon-tools-raub", - "version": "5.3.0", + "version": "5.3.2", "description": "Helpers for Node.js addons and dependency packages", "license": "MIT", "main": "index.js", diff --git a/utils.d.ts b/utils.d.ts index 19dbe5f..0b4d03b 100644 --- a/utils.d.ts +++ b/utils.d.ts @@ -1,75 +1,105 @@ import type { Stats } from 'fs'; - -// (async) Reads a whole file to string, NOT A Buffer -export const read: (name: string) => Promise; - - -// (async) Write a file -export const write: (name: string, text: string) => Promise; - - -// (async) Copy a file -export const copy: (src: string, dest: string) => Promise; - - -// (async) Check if a file/folder exists -export const exists: (name: string) => Promise; - - -// (async) Create an empty folder -export const mkdir: (name: string) => Promise; - - -// (async) Get status on a file -export const stat: (name: string) => Promise; - - -// (async) Check if the path is a folder -export const isDir: (name: string) => Promise; - - -// (async) Check if the path is a file -export const isFile: (name: string) => Promise; - - -// Cut the path one folder up -export const dirUp: (dir: string) => string; - - -// (async) Like `mkdir -p`, makes sure a directory exists -export const ensuredir: (dir: string) => Promise; - - -// (async) Copy a file, `dest` folder is created if needed -export const copysafe: (src: string, dest: string) => Promise; - - -// (async) Get file/folder names of the 1st level -export const readdir: (src: string, dest: string) => Promise>; - - -// (async) Get folder paths (concatenated with input) of the 1st level -export const subdirs: (name: string) => Promise>; - - -// (async) Get file paths (concatenated with input) of the 1st level -export const subfiles: (name: string) => Promise>; - - -// (async) Get all nested files recursively -// Folder paths are omitted by default -// Order is: shallow-to-deep, each subdirectory lists dirs-then-files. -export const traverse: (name: string, showDirs?: boolean) => Promise>; - - -// (async) Copy a folder with all the contained files -export const copyall: (src: string, dest: string) => Promise; - - -// (async) Like `rm -rf`, removes everything recursively -export const rmdir: (name: string) => Promise; - - -// (async) Remove a file. Must be a file, not a folder. Just `fs.unlink`. -export const rm: (name: string) => Promise; +declare module "addon-tools-raub/utils" { + /** + * (async) Read a file + * Reads a whole file to string, NOT A Buffer + */ + export const read: (name: string) => Promise; + + /** + * (async) Write a file + */ + export const write: (name: string, text: string) => Promise; + + /** + * (async) Copy a file + */ + export const copy: (src: string, dest: string) => Promise; + + /** + * (async) Check if a file/folder exists + */ + export const exists: (name: string) => Promise; + + /** + * (async) Create an empty folder + */ + export const mkdir: (name: string) => Promise; + + /** + * (async) Get status on a file + */ + export const stat: (name: string) => Promise; + + /** + * (async) Check if the path is a folder + */ + export const isDir: (name: string) => Promise; + + /** + * (async) Check if the path is a file + */ + export const isFile: (name: string) => Promise; + + /** + * Cut the path one folder up + */ + export const dirUp: (dir: string) => string; + + /** + * (async) Create a directory + * Like `mkdir -p`, makes sure a directory exists + */ + export const ensuredir: (dir: string) => Promise; + + /** + * (async) Copy a file + * Copy a file, `dest` folder is created if needed + */ + export const copysafe: (src: string, dest: string) => Promise; + + /** + * (async) Read a directory + * Get file/folder names of the 1st level + */ + export const readdir: (src: string, dest: string) => Promise>; + + /** + * (async) List subdirectories + * Get folder paths (concatenated with input) of the 1st level + */ + export const subdirs: (name: string) => Promise>; + + /** + * (async) List nested files + * Get file paths (concatenated with input) of the 1st level + */ + export const subfiles: (name: string) => Promise>; + + /** + * (async) Get all nested files recursively + * Folder paths are omitted by default. + * Order is: shallow-to-deep, each subdirectory lists dirs-then-files. + */ + export const traverse: (name: string, showDirs?: boolean) => Promise>; + + /** + * (async) Copy a directory + * Copy a folder with all the contained files + */ + export const copyall: (src: string, dest: string) => Promise; + + /** + * (async) Remove a directory + * Like `rm -rf`, removes everything recursively + */ + export const rmdir: (name: string) => Promise; + + /** + * (async) Remove a file + * Must be a file, not a folder. Just `fs.unlink`. + */ + export const rm: (name: string) => Promise; + +} diff --git a/writable-buffer.d.ts b/writable-buffer.d.ts index 2714440..59b6610 100644 --- a/writable-buffer.d.ts +++ b/writable-buffer.d.ts @@ -1,6 +1,22 @@ import type { Writable } from 'stream'; -export class WritableBuffer extends Writable { - constructor(); - get(): Buffer; -}; + +declare module "addon-tools-raub/writable-buffer" { + /** + * WritableBuffer + * A [Writable](https://nodejs.org/api/stream.html#stream_writable_streams) + * stream buffer, that is stored in-memory and can be fully + * obtained when writing was finished. It is equivalent to stream-writing + * a temporary file and then reading it into a `Buffer`. + */ + export class WritableBuffer extends Writable { + constructor(); + /** + * Get the downloaded data + * Use `stream.get()` to obtain the data when writing was finished + */ + get(): Buffer; + } + + export = WritableBuffer; +}