From e4958ee6f06c54bcb73c089c1000e708fb81983a Mon Sep 17 00:00:00 2001 From: ssube Date: Tue, 31 Mar 2020 08:49:18 -0500 Subject: [PATCH] fix(docs): describe exports and mark with release status --- docs/api/js-utils.arraymapper.map.md | 2 ++ docs/api/js-utils.arraymapper.md | 2 +- docs/api/js-utils.asynctracker.dump.md | 2 ++ docs/api/js-utils.asynctracker.getstack.md | 2 ++ docs/api/js-utils.asynctracker.md | 4 +-- docs/api/js-utils.checklist.data.md | 2 ++ docs/api/js-utils.checklist.md | 4 ++- docs/api/js-utils.childprocesserror.md | 2 ++ docs/api/js-utils.concat.md | 2 ++ docs/api/js-utils.constructorname.md | 2 ++ docs/api/js-utils.defaultwhen.md | 2 ++ docs/api/js-utils.encode.md | 2 ++ docs/api/js-utils.getconstructor.md | 2 ++ docs/api/js-utils.getmethods.md | 2 ++ docs/api/js-utils.gettestlogger.md | 2 ++ docs/api/js-utils.invalidargumenterror.md | 2 ++ docs/api/js-utils.isdebug.md | 4 +++ docs/api/js-utils.md | 42 +++++++++++----------- docs/api/js-utils.missingkeyerror.md | 4 ++- docs/api/js-utils.mustcoalesce.md | 2 +- docs/api/js-utils.normalizemap.md | 5 +++ docs/api/js-utils.notfounderror.md | 2 ++ docs/api/js-utils.notimplementederror.md | 2 ++ docs/api/js-utils.removepid.md | 2 ++ docs/api/js-utils.spylogger.md | 2 ++ docs/api/js-utils.timeouterror.md | 2 ++ docs/api/js-utils.waitforchild.md | 2 ++ docs/api/js-utils.writepid.md | 2 ++ src/ArrayMapper.ts | 7 ++++ src/Async.ts | 7 ++++ src/AsyncTracker.ts | 10 ++++++ src/Buffer.ts | 10 ++++++ src/Checklist.ts | 6 ++++ src/Child.ts | 5 +++ src/Env.ts | 5 +++ src/Logger.ts | 6 ++++ src/Map.ts | 29 +++++++++++++++ src/PidFile.ts | 8 +++++ src/Reflect.ts | 15 ++++++++ src/error/ChildProcessError.ts | 5 +++ src/error/InvalidArgumentError.ts | 5 +++ src/error/MissingKeyError.ts | 9 +++-- src/error/NotFoundError.ts | 5 +++ src/error/NotImplementedError.ts | 5 +++ src/error/TimeoutError.ts | 5 +++ src/utils/index.ts | 38 +++++++++++++++++++- 46 files changed, 257 insertions(+), 30 deletions(-) diff --git a/docs/api/js-utils.arraymapper.map.md b/docs/api/js-utils.arraymapper.map.md index a7b672c..d002561 100644 --- a/docs/api/js-utils.arraymapper.map.md +++ b/docs/api/js-utils.arraymapper.map.md @@ -4,6 +4,8 @@ ## ArrayMapper.map() method +Transform the input list into a map, extracting elements using the mapper's options. + Signature: ```typescript diff --git a/docs/api/js-utils.arraymapper.md b/docs/api/js-utils.arraymapper.md index 5efda4a..45f29a8 100644 --- a/docs/api/js-utils.arraymapper.md +++ b/docs/api/js-utils.arraymapper.md @@ -30,5 +30,5 @@ export declare class ArrayMapper | Method | Modifiers | Description | | --- | --- | --- | -| [map(input)](./js-utils.arraymapper.map.md) | | | +| [map(input)](./js-utils.arraymapper.map.md) | | Transform the input list into a map, extracting elements using the mapper's options. | diff --git a/docs/api/js-utils.asynctracker.dump.md b/docs/api/js-utils.asynctracker.dump.md index 16e432a..9e337aa 100644 --- a/docs/api/js-utils.asynctracker.dump.md +++ b/docs/api/js-utils.asynctracker.dump.md @@ -4,6 +4,8 @@ ## AsyncTracker.dump() method +Print a listing of all tracked resources. When debug mode is enabled (DEBUG=TRUE), include stack traces. + Signature: ```typescript diff --git a/docs/api/js-utils.asynctracker.getstack.md b/docs/api/js-utils.asynctracker.getstack.md index fe53ee3..7395a90 100644 --- a/docs/api/js-utils.asynctracker.getstack.md +++ b/docs/api/js-utils.asynctracker.getstack.md @@ -4,6 +4,8 @@ ## AsyncTracker.getStack() method +Get a filtered version of the current call stack. This creates a new error to generate the stack trace and will be quite slow. + Signature: ```typescript diff --git a/docs/api/js-utils.asynctracker.md b/docs/api/js-utils.asynctracker.md index e27054e..5b24646 100644 --- a/docs/api/js-utils.asynctracker.md +++ b/docs/api/js-utils.asynctracker.md @@ -33,7 +33,7 @@ export declare class AsyncTracker | --- | --- | --- | | [clear()](./js-utils.asynctracker.clear.md) | | | | [disable()](./js-utils.asynctracker.disable.md) | | | -| [dump()](./js-utils.asynctracker.dump.md) | | | +| [dump()](./js-utils.asynctracker.dump.md) | | Print a listing of all tracked resources. When debug mode is enabled (DEBUG=TRUE), include stack traces. | | [enable()](./js-utils.asynctracker.enable.md) | | | -| [getStack()](./js-utils.asynctracker.getstack.md) | | | +| [getStack()](./js-utils.asynctracker.getstack.md) | | Get a filtered version of the current call stack. This creates a new error to generate the stack trace and will be quite slow. | diff --git a/docs/api/js-utils.checklist.data.md b/docs/api/js-utils.checklist.data.md index 3d994b9..d851635 100644 --- a/docs/api/js-utils.checklist.data.md +++ b/docs/api/js-utils.checklist.data.md @@ -4,6 +4,8 @@ ## Checklist.data property +TODO: switch to Set + Signature: ```typescript diff --git a/docs/api/js-utils.checklist.md b/docs/api/js-utils.checklist.md index 063b4c0..271252e 100644 --- a/docs/api/js-utils.checklist.md +++ b/docs/api/js-utils.checklist.md @@ -4,6 +4,8 @@ ## Checklist class +Check whether items are included or not (blacklist or whitelist, depending on `mode`). + Signature: ```typescript @@ -20,7 +22,7 @@ export declare class Checklist implements ChecklistOptions | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [data](./js-utils.checklist.data.md) | | Array<T> | | +| [data](./js-utils.checklist.data.md) | | Array<T> | TODO: switch to Set | | [mode](./js-utils.checklist.mode.md) | | ChecklistMode | | ## Methods diff --git a/docs/api/js-utils.childprocesserror.md b/docs/api/js-utils.childprocesserror.md index 73e40eb..7241bb8 100644 --- a/docs/api/js-utils.childprocesserror.md +++ b/docs/api/js-utils.childprocesserror.md @@ -4,6 +4,8 @@ ## ChildProcessError class +Error indicating that a child process exited with an error status. + Signature: ```typescript diff --git a/docs/api/js-utils.concat.md b/docs/api/js-utils.concat.md index b3dc778..faa1f5e 100644 --- a/docs/api/js-utils.concat.md +++ b/docs/api/js-utils.concat.md @@ -4,6 +4,8 @@ ## concat() function +Concatenate a list of buffers. + Signature: ```typescript diff --git a/docs/api/js-utils.constructorname.md b/docs/api/js-utils.constructorname.md index 85967a8..c0583e3 100644 --- a/docs/api/js-utils.constructorname.md +++ b/docs/api/js-utils.constructorname.md @@ -4,6 +4,8 @@ ## constructorName() function +Get the constructor name from an instance. + Signature: ```typescript diff --git a/docs/api/js-utils.defaultwhen.md b/docs/api/js-utils.defaultwhen.md index 789c455..222305b 100644 --- a/docs/api/js-utils.defaultwhen.md +++ b/docs/api/js-utils.defaultwhen.md @@ -4,6 +4,8 @@ ## defaultWhen() function +Return the first element when `condition` is true and the second element when `condition` is false. + Signature: ```typescript diff --git a/docs/api/js-utils.encode.md b/docs/api/js-utils.encode.md index a69a62c..d66653f 100644 --- a/docs/api/js-utils.encode.md +++ b/docs/api/js-utils.encode.md @@ -4,6 +4,8 @@ ## encode() function +Concatenate then encode a list of buffers. + Signature: ```typescript diff --git a/docs/api/js-utils.getconstructor.md b/docs/api/js-utils.getconstructor.md index 357efc6..8e52cb6 100644 --- a/docs/api/js-utils.getconstructor.md +++ b/docs/api/js-utils.getconstructor.md @@ -4,6 +4,8 @@ ## getConstructor() function +Get the constructor from an instance. + Signature: ```typescript diff --git a/docs/api/js-utils.getmethods.md b/docs/api/js-utils.getmethods.md index 559d1e9..2456a3e 100644 --- a/docs/api/js-utils.getmethods.md +++ b/docs/api/js-utils.getmethods.md @@ -4,6 +4,8 @@ ## getMethods() function +Get the methods from an instance and its prototypes. + Signature: ```typescript diff --git a/docs/api/js-utils.gettestlogger.md b/docs/api/js-utils.gettestlogger.md index 729bfbf..412f993 100644 --- a/docs/api/js-utils.gettestlogger.md +++ b/docs/api/js-utils.gettestlogger.md @@ -4,6 +4,8 @@ ## getTestLogger() function +Get a test logger. Returns a null logger unless `verbose` is true or run under debug mode. + Signature: ```typescript diff --git a/docs/api/js-utils.invalidargumenterror.md b/docs/api/js-utils.invalidargumenterror.md index a4f9056..149773a 100644 --- a/docs/api/js-utils.invalidargumenterror.md +++ b/docs/api/js-utils.invalidargumenterror.md @@ -4,6 +4,8 @@ ## InvalidArgumentError class +Error indicating that an invalid argument was passed to a function call. + Signature: ```typescript diff --git a/docs/api/js-utils.isdebug.md b/docs/api/js-utils.isdebug.md index d9a0305..131b4f7 100644 --- a/docs/api/js-utils.isdebug.md +++ b/docs/api/js-utils.isdebug.md @@ -4,6 +4,10 @@ ## isDebug() function +Test if DEBUG mode is set. + +TODO: check variable value as well + Signature: ```typescript diff --git a/docs/api/js-utils.md b/docs/api/js-utils.md index ef8aa0f..05f5b52 100644 --- a/docs/api/js-utils.md +++ b/docs/api/js-utils.md @@ -10,13 +10,13 @@ | --- | --- | | [ArrayMapper](./js-utils.arraymapper.md) | Map an array of items into a map of arrays using the specified keys, able to skip initial items and gather remaining items into a rest key. | | [AsyncTracker](./js-utils.asynctracker.md) | Async resource tracker using node's internal hooks.This probably won't work in a browser. It does not hold references to the resource, to avoid leaks. Adapted from https://gist.github.com/boneskull/7fe75b63d613fa940db7ec990a5f5843\#file-async-dump-js | -| [Checklist](./js-utils.checklist.md) | | -| [ChildProcessError](./js-utils.childprocesserror.md) | | -| [InvalidArgumentError](./js-utils.invalidargumenterror.md) | | -| [MissingKeyError](./js-utils.missingkeyerror.md) | | -| [NotFoundError](./js-utils.notfounderror.md) | | -| [NotImplementedError](./js-utils.notimplementederror.md) | | -| [TimeoutError](./js-utils.timeouterror.md) | | +| [Checklist](./js-utils.checklist.md) | Check whether items are included or not (blacklist or whitelist, depending on mode). | +| [ChildProcessError](./js-utils.childprocesserror.md) | Error indicating that a child process exited with an error status. | +| [InvalidArgumentError](./js-utils.invalidargumenterror.md) | Error indicating that an invalid argument was passed to a function call. | +| [MissingKeyError](./js-utils.missingkeyerror.md) | Error indicating that a required key did not exist in a map-like. | +| [NotFoundError](./js-utils.notfounderror.md) | Error indicating that some value was not found. | +| [NotImplementedError](./js-utils.notimplementederror.md) | Error indicating that a function has not been implemented yet. | +| [TimeoutError](./js-utils.timeouterror.md) | Error indicating that a promise timed out. | ## Enumerations @@ -28,43 +28,43 @@ | Function | Description | | --- | --- | -| [concat(chunks)](./js-utils.concat.md) | | -| [constructorName(val)](./js-utils.constructorname.md) | | +| [concat(chunks)](./js-utils.concat.md) | Concatenate a list of buffers. | +| [constructorName(val)](./js-utils.constructorname.md) | Get the constructor name from an instance. | | [countOf(val)](./js-utils.countof.md) | Calculate the "length" of an array or value.Arrays return their length, single values return 1, and nil values return 0. This counts the number of elements that setOrPush would add. | -| [defaultWhen(condition, items)](./js-utils.defaultwhen.md) | | +| [defaultWhen(condition, items)](./js-utils.defaultwhen.md) | Return the first element when condition is true and the second element when condition is false. | | [defer(ms, val)](./js-utils.defer.md) | Resolve after a set amount of time. | | [doesExist(val)](./js-utils.doesexist.md) | Check if a variable is not nil. | -| [encode(chunks, encoding)](./js-utils.encode.md) | | +| [encode(chunks, encoding)](./js-utils.encode.md) | Concatenate then encode a list of buffers. | | [entriesOf(map)](./js-utils.entriesof.md) | Get entries of a map-like. | | [filterNil(list)](./js-utils.filternil.md) | Remove any null or undefined items from the list. | -| [getConstructor(val)](./js-utils.getconstructor.md) | | +| [getConstructor(val)](./js-utils.getconstructor.md) | Get the constructor from an instance. | | [getHead(map, key)](./js-utils.gethead.md) | Get the first element from the specified key within a map of lists. | | [getHeadOrDefault(map, key, defaultValue)](./js-utils.getheadordefault.md) | Get the first element from the specified key, within a map of lists, or a default value when the key does not exist or is nil. | -| [getMethods(value)](./js-utils.getmethods.md) | | +| [getMethods(value)](./js-utils.getmethods.md) | Get the methods from an instance and its prototypes. | | [getOrDefault(map, key, defaultValue)](./js-utils.getordefault.md) | Get a map key or default value when the key does not exist or is nil. | -| [getTestLogger(verbose)](./js-utils.gettestlogger.md) | | -| [isDebug()](./js-utils.isdebug.md) | | +| [getTestLogger(verbose)](./js-utils.gettestlogger.md) | Get a test logger. Returns a null logger unless verbose is true or run under debug mode. | +| [isDebug()](./js-utils.isdebug.md) | Test if DEBUG mode is set.TODO: check variable value as well | | [isNil(val)](./js-utils.isnil.md) | Check if a value is nil. | | [leftPad(val, min, fill)](./js-utils.leftpad.md) | | | [makeDict(map)](./js-utils.makedict.md) | Turns a map or dict into a dict | | [makeMap(val)](./js-utils.makemap.md) | Clone a map or map-like object into a new map. | | [mergeList(parts)](./js-utils.mergelist.md) | Merge arguments, which may or may not be arrays, into one return that is definitely an array. | | [mergeMap(target, source)](./js-utils.mergemap.md) | Merge the source map into the target map, replacing keys that already exist. | -| [mustCoalesce(values)](./js-utils.mustcoalesce.md) | Return the first value that is not nil.TODO: rename to mustDefault | +| [mustCoalesce(values)](./js-utils.mustcoalesce.md) | Return the first value that is not nil.@todo: rename to mustDefault | | [mustExist(val)](./js-utils.mustexist.md) | Assert that a variable is not nil and return the value. | | [mustFind(list, predicate)](./js-utils.mustfind.md) | Find a value matching the given predicate or throw. | | [mustGet(map, key)](./js-utils.mustget.md) | Get an element from a Map and guard against nil values. | -| [normalizeMap(map)](./js-utils.normalizemap.md) | | +| [normalizeMap(map)](./js-utils.normalizemap.md) | (BETA) Normalize a map-like of values into a dict of lists of strings. | | [pairsToMap(pairs)](./js-utils.pairstomap.md) | Turns a list of name-value pairs into a map. | | [pushMergeMap(args)](./js-utils.pushmergemap.md) | Merge the provided maps into a new map, merging keys that already exist by pushing new items. | -| [removePid(path)](./js-utils.removepid.md) | | +| [removePid(path)](./js-utils.removepid.md) | Remove the file at the given path. | | [setOrPush(map, key, val)](./js-utils.setorpush.md) | Set a map key to a new array or push to the existing value. | | [signal(signals)](./js-utils.signal.md) | | -| [spyLogger(spies)](./js-utils.spylogger.md) | | +| [spyLogger(spies)](./js-utils.spylogger.md) | Create a spy logger using the provided methods, which returns itself as a child. | | [timeout(ms, oper)](./js-utils.timeout.md) | Reject after a set amount of time if the original promise has not yet resolved. | | [trim(val, max, tail)](./js-utils.trim.md) | | -| [waitForChild(child)](./js-utils.waitforchild.md) | | -| [writePid(path)](./js-utils.writepid.md) | | +| [waitForChild(child)](./js-utils.waitforchild.md) | Wait for a child process to exit, collecting output, errors, and exit status. | +| [writePid(path)](./js-utils.writepid.md) | Write the current process ID to a file at the given path. | | [writeValue(stream, value)](./js-utils.writevalue.md) | | ## Interfaces diff --git a/docs/api/js-utils.missingkeyerror.md b/docs/api/js-utils.missingkeyerror.md index ab29b2d..53e4d54 100644 --- a/docs/api/js-utils.missingkeyerror.md +++ b/docs/api/js-utils.missingkeyerror.md @@ -4,10 +4,12 @@ ## MissingKeyError class +Error indicating that a required key did not exist in a map-like. + Signature: ```typescript -export declare class MissingKeyError extends BaseError +export declare class MissingKeyError extends NotFoundError ``` ## Constructors diff --git a/docs/api/js-utils.mustcoalesce.md b/docs/api/js-utils.mustcoalesce.md index 9cf17f8..94db16c 100644 --- a/docs/api/js-utils.mustcoalesce.md +++ b/docs/api/js-utils.mustcoalesce.md @@ -6,7 +6,7 @@ Return the first value that is not nil. -TODO: rename to mustDefault +@todo: rename to mustDefault Signature: diff --git a/docs/api/js-utils.normalizemap.md b/docs/api/js-utils.normalizemap.md index cae9d45..fe8d4cc 100644 --- a/docs/api/js-utils.normalizemap.md +++ b/docs/api/js-utils.normalizemap.md @@ -4,6 +4,11 @@ ## normalizeMap() function +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Normalize a map-like of values into a dict of lists of strings. + Signature: ```typescript diff --git a/docs/api/js-utils.notfounderror.md b/docs/api/js-utils.notfounderror.md index a6d7e29..c19f1bb 100644 --- a/docs/api/js-utils.notfounderror.md +++ b/docs/api/js-utils.notfounderror.md @@ -4,6 +4,8 @@ ## NotFoundError class +Error indicating that some value was not found. + Signature: ```typescript diff --git a/docs/api/js-utils.notimplementederror.md b/docs/api/js-utils.notimplementederror.md index f370cd6..75460fe 100644 --- a/docs/api/js-utils.notimplementederror.md +++ b/docs/api/js-utils.notimplementederror.md @@ -4,6 +4,8 @@ ## NotImplementedError class +Error indicating that a function has not been implemented yet. + Signature: ```typescript diff --git a/docs/api/js-utils.removepid.md b/docs/api/js-utils.removepid.md index f725802..1bbb330 100644 --- a/docs/api/js-utils.removepid.md +++ b/docs/api/js-utils.removepid.md @@ -4,6 +4,8 @@ ## removePid() function +Remove the file at the given `path`. + Signature: ```typescript diff --git a/docs/api/js-utils.spylogger.md b/docs/api/js-utils.spylogger.md index f17033c..dcbb925 100644 --- a/docs/api/js-utils.spylogger.md +++ b/docs/api/js-utils.spylogger.md @@ -4,6 +4,8 @@ ## spyLogger() function +Create a spy logger using the provided methods, which returns itself as a child. + Signature: ```typescript diff --git a/docs/api/js-utils.timeouterror.md b/docs/api/js-utils.timeouterror.md index 5ba9aeb..2f49330 100644 --- a/docs/api/js-utils.timeouterror.md +++ b/docs/api/js-utils.timeouterror.md @@ -4,6 +4,8 @@ ## TimeoutError class +Error indicating that a promise timed out. + Signature: ```typescript diff --git a/docs/api/js-utils.waitforchild.md b/docs/api/js-utils.waitforchild.md index 6adac2d..e797c4e 100644 --- a/docs/api/js-utils.waitforchild.md +++ b/docs/api/js-utils.waitforchild.md @@ -4,6 +4,8 @@ ## waitForChild() function +Wait for a child process to exit, collecting output, errors, and exit status. + Signature: ```typescript diff --git a/docs/api/js-utils.writepid.md b/docs/api/js-utils.writepid.md index ec3a7eb..9653efe 100644 --- a/docs/api/js-utils.writepid.md +++ b/docs/api/js-utils.writepid.md @@ -4,6 +4,8 @@ ## writePid() function +Write the current process ID to a file at the given `path`. + Signature: ```typescript diff --git a/src/ArrayMapper.ts b/src/ArrayMapper.ts index bcf3ed7..5bca57a 100644 --- a/src/ArrayMapper.ts +++ b/src/ArrayMapper.ts @@ -18,6 +18,8 @@ export interface ArrayMapperOptions { /** * Map an array of items into a map of arrays using the specified keys, able to `skip` initial items and gather * remaining items into a `rest` key. + * + * @public */ export class ArrayMapper { public readonly rest: string; @@ -30,6 +32,11 @@ export class ArrayMapper { this.take = Array.from(options.take); } + /** + * Transform the input list into a map, extracting elements using the mapper's options. + * + * @public + */ public map(input: Array): Map> { const result = new Map(); input.forEach((it, idx) => { diff --git a/src/Async.ts b/src/Async.ts index 7861b65..36e244a 100644 --- a/src/Async.ts +++ b/src/Async.ts @@ -3,6 +3,7 @@ import { PredicateC0 } from './utils'; /** * Resolve after a set amount of time. + * @public */ export function defer(ms: number, val?: T): Promise { return new Promise((res, rej) => { @@ -14,6 +15,7 @@ export function defer(ms: number, val?: T): Promise { /** * Reject after a set amount of time if the original promise has not yet resolved. + * @public */ export function timeout(ms: number, oper: Promise): Promise { const limit = new Promise((res, rej) => { @@ -25,6 +27,11 @@ export function timeout(ms: number, oper: Promise): Promise { return Promise.race([limit, oper]); } +/** + * Reject after a set number of attempts if the given predicate does not return true. + * @public + * @throws TimeoutError + */ export async function waitFor(cb: PredicateC0, step: number, count: number): Promise { let accum = 0; while (accum < count) { diff --git a/src/AsyncTracker.ts b/src/AsyncTracker.ts index e72e2dc..a69e3c2 100644 --- a/src/AsyncTracker.ts +++ b/src/AsyncTracker.ts @@ -16,6 +16,8 @@ export type StackFilter = (stack: string) => string; * * This probably won't work in a browser. It does not hold references to the resource, to avoid leaks. * Adapted from https://gist.github.com/boneskull/7fe75b63d613fa940db7ec990a5f5843#file-async-dump-js + * + * @public */ export class AsyncTracker { public filter: Optional; @@ -43,6 +45,10 @@ export class AsyncTracker { }); } + /** + * Get a filtered version of the current call stack. This creates a new error to generate the + * stack trace and will be quite slow. + */ public getStack(): string { const err = new Error(); if (isNil(err.stack)) { @@ -64,6 +70,10 @@ export class AsyncTracker { this.hook.disable(); } + /** + * Print a listing of all tracked resources. When debug mode is enabled (DEBUG=TRUE), include + * stack traces. + */ /* eslint-disable no-console, no-invalid-this */ public dump() { console.error(`tracking ${this.resources.size} async resources`); diff --git a/src/Buffer.ts b/src/Buffer.ts index 3b2b11d..f336504 100644 --- a/src/Buffer.ts +++ b/src/Buffer.ts @@ -1,8 +1,18 @@ +/** + * Concatenate a list of buffers. + * + * @public + */ export function concat(chunks: Array): Buffer { const sum = chunks.map((it) => it.length).reduce((p, c) => p + c, 0); return Buffer.concat(chunks, sum); } +/** + * Concatenate then encode a list of buffers. + * + * @public + */ export function encode(chunks: Array, encoding: string): string { if (chunks.length === 0) { return ''; diff --git a/src/Checklist.ts b/src/Checklist.ts index 8256d84..c9961ec 100644 --- a/src/Checklist.ts +++ b/src/Checklist.ts @@ -8,7 +8,13 @@ export interface ChecklistOptions { mode: ChecklistMode; } +/** + * Check whether items are included or not (blacklist or whitelist, depending on `mode`). + */ export class Checklist implements ChecklistOptions { + /** + * TODO: switch to Set + */ public readonly data: Array; public readonly mode: ChecklistMode; diff --git a/src/Child.ts b/src/Child.ts index cb79538..3071944 100644 --- a/src/Child.ts +++ b/src/Child.ts @@ -37,6 +37,11 @@ const CHILD_EVENT = 'child process emitted error event'; const CHILD_STATUS = 'child process exited with error status'; const CHILD_OUTPUT = 'child process emitted error output'; +/** + * Wait for a child process to exit, collecting output, errors, and exit status. + * + * @public + */ export function waitForChild(child: ChildStreams): Promise { return new Promise((res, rej) => { const stderr: Array = []; diff --git a/src/Env.ts b/src/Env.ts index 3020c07..908bc23 100644 --- a/src/Env.ts +++ b/src/Env.ts @@ -1,5 +1,10 @@ const ENV_DEBUG = 'DEBUG'; +/** + * Test if DEBUG mode is set. + * + * TODO: check variable value as well + */ export function isDebug() { return Reflect.has(process.env, ENV_DEBUG); } diff --git a/src/Logger.ts b/src/Logger.ts index 53a8fb0..60eabf5 100644 --- a/src/Logger.ts +++ b/src/Logger.ts @@ -1,6 +1,9 @@ import { ConsoleLogger, Logger, NullLogger } from 'noicejs'; import { isDebug } from './Env'; +/** + * Get a test logger. Returns a null logger unless `verbose` is true or run under debug mode. + */ export function getTestLogger(verbose = false): Logger { if (verbose || isDebug()) { return ConsoleLogger.global; @@ -9,6 +12,9 @@ export function getTestLogger(verbose = false): Logger { } } +/** + * Create a spy logger using the provided methods, which returns itself as a child. + */ export function spyLogger(spies: Partial): Logger { const logger = { ...spies, diff --git a/src/Map.ts b/src/Map.ts index 289bbed..4258c6f 100644 --- a/src/Map.ts +++ b/src/Map.ts @@ -9,11 +9,15 @@ export interface Dict { /** * A `Map` or dictionary object with string keys and `TVal` values. + * + * @public */ export type MapLike = Map | Dict; /** * Get an element from a Map and guard against nil values. + * + * @public */ export function mustGet(map: Map, key: TKey): TVal { const val = map.get(key); @@ -22,6 +26,8 @@ export function mustGet(map: Map, key: TKey): TVal { /** * Get a map key or default value when the key does not exist or is nil. + * + * @public */ export function getOrDefault(map: Map, key: TKey, defaultValue: TVal): TVal { if (map.has(key)) { @@ -36,6 +42,8 @@ export function getOrDefault(map: Map, key: TKey, defaul /** * Get the first element from the specified key within a map of lists. + * + * @public */ export function getHead(map: Map>, key: TKey): TVal { const value = map.get(key); @@ -48,6 +56,8 @@ export function getHead(map: Map>, key: TKey): TVa /** * Get the first element from the specified key, within a map of lists, or a default value when * the key does not exist or is nil. + * + * @public */ export function getHeadOrDefault(map: Map>>, key: TKey, defaultValue: TVal): TVal { if (!map.has(key)) { @@ -72,6 +82,8 @@ export function getHeadOrDefault(map: Map * @param map The destination map and source of existing values. * @param key The key to get and set. * @param val The value to add. + * + * @public */ export function setOrPush(map: Map>, key: TKey, val: TVal | Array) { const prev = map.get(key); @@ -88,6 +100,8 @@ export function setOrPush(map: Map>, key: TKey, va /** * Merge the `source` map into the `target` map, replacing keys that already exist. + * + * @public */ export function mergeMap(target: Map, source: Map | Array<[TKey, TVal]>) { for (const [k, v] of source) { @@ -99,6 +113,8 @@ export function mergeMap(target: Map, source: Map(...args: Array>>): Map> { const out = new Map(); @@ -112,6 +128,8 @@ export function pushMergeMap(...args: Array(val: Optional>): Map { // nil: empty map @@ -130,6 +148,8 @@ export function makeMap(val: Optional>): Map { /** * Turns a map or dict into a dict + * + * @public */ export function makeDict(map: Optional>): Dict { if (isNil(map)) { @@ -154,6 +174,8 @@ export interface NameValuePair { /** * Turns a list of name-value pairs into a map. + * + * @public */ export function pairsToMap(pairs: Array>): Map { const map = new Map(); @@ -176,6 +198,11 @@ export function dictValuesToArrays(map: MapLike): Dict> return data; } +/** + * Normalize a map-like of values into a dict of lists of strings. + * + * @beta + */ export function normalizeMap(map: MapLike): Dict> { const data: Dict> = {}; for (const [key, value] of makeMap(map)) { @@ -193,6 +220,8 @@ export function normalizeMap(map: MapLike): Dict> { /** * Get entries of a map-like. + * + * @public */ export function entriesOf(map: Optional>): Array<[string, TVal]> { if (map instanceof Map) { diff --git a/src/PidFile.ts b/src/PidFile.ts index 7469166..7d44350 100644 --- a/src/PidFile.ts +++ b/src/PidFile.ts @@ -5,6 +5,11 @@ import { doesExist, Optional } from './utils'; type OptionalErrno = Optional; +/** + * Write the current process ID to a file at the given `path`. + * + * @public + */ export async function writePid(path: string): Promise { return new Promise((res, rej) => { open(path, 'wx', (openErr: OptionalErrno, fd: number) => { @@ -23,6 +28,9 @@ export async function writePid(path: string): Promise { }); } +/** + * Remove the file at the given `path`. + */ export async function removePid(path: string): Promise { return new Promise((res, rej) => { unlink(path, (err: OptionalErrno) => { diff --git a/src/Reflect.ts b/src/Reflect.ts index 3f90f00..412477e 100644 --- a/src/Reflect.ts +++ b/src/Reflect.ts @@ -2,10 +2,20 @@ import { isFunction } from 'lodash'; import { doesExist, isNil } from './utils'; +/** + * Get the constructor from an instance. + * + * @public + */ export function getConstructor(val: object) { return val.constructor; } +/** + * Get the methods from an instance and its prototypes. + * + * @public + */ export function getMethods(value: TValue): Set { const methods = new Set(); @@ -31,6 +41,11 @@ export function getMethods(value: TValue): Set return methods; } +/** + * Get the constructor name from an instance. + * + * @public + */ export function constructorName(val: object) { return getConstructor(Reflect.getPrototypeOf(val)).name; } diff --git a/src/error/ChildProcessError.ts b/src/error/ChildProcessError.ts index bb8160b..bf0a81c 100644 --- a/src/error/ChildProcessError.ts +++ b/src/error/ChildProcessError.ts @@ -1,5 +1,10 @@ import { BaseError } from 'noicejs'; +/** + * Error indicating that a child process exited with an error status. + * + * @public + */ export class ChildProcessError extends BaseError { constructor(msg = 'child process exited with error status', ...nested: Array) { super(msg, ...nested); diff --git a/src/error/InvalidArgumentError.ts b/src/error/InvalidArgumentError.ts index b81c474..557000a 100644 --- a/src/error/InvalidArgumentError.ts +++ b/src/error/InvalidArgumentError.ts @@ -1,5 +1,10 @@ import { BaseError } from 'noicejs'; +/** + * Error indicating that an invalid argument was passed to a function call. + * + * @public + */ export class InvalidArgumentError extends BaseError { constructor(msg = 'invalid argument passed', ...nested: Array) { super(msg, ...nested); diff --git a/src/error/MissingKeyError.ts b/src/error/MissingKeyError.ts index 9fb32f1..8a51591 100644 --- a/src/error/MissingKeyError.ts +++ b/src/error/MissingKeyError.ts @@ -1,6 +1,11 @@ -import { BaseError } from 'noicejs'; +import { NotFoundError } from './NotFoundError'; -export class MissingKeyError extends BaseError { +/** + * Error indicating that a required key did not exist in a map-like. + * + * @public + */ +export class MissingKeyError extends NotFoundError { constructor(msg = 'missing key', ...nested: Array) { super(msg, ...nested); } diff --git a/src/error/NotFoundError.ts b/src/error/NotFoundError.ts index d5b179c..ca66b9e 100644 --- a/src/error/NotFoundError.ts +++ b/src/error/NotFoundError.ts @@ -1,5 +1,10 @@ import { BaseError } from 'noicejs'; +/** + * Error indicating that some value was not found. + * + * @public + */ export class NotFoundError extends BaseError { constructor(msg = 'value not found', ...nested: Array) { super(msg, ...nested); diff --git a/src/error/NotImplementedError.ts b/src/error/NotImplementedError.ts index cf211d3..f62ebbe 100644 --- a/src/error/NotImplementedError.ts +++ b/src/error/NotImplementedError.ts @@ -1,5 +1,10 @@ import { BaseError } from 'noicejs'; +/** + * Error indicating that a function has not been implemented yet. + * + * @public + */ export class NotImplementedError extends BaseError { constructor(msg = 'method not implemented', ...nested: Array) { super(msg, ...nested); diff --git a/src/error/TimeoutError.ts b/src/error/TimeoutError.ts index 5481eaf..c3d4b88 100644 --- a/src/error/TimeoutError.ts +++ b/src/error/TimeoutError.ts @@ -1,5 +1,10 @@ import { BaseError } from 'noicejs'; +/** + * Error indicating that a promise timed out. + * + * @public + */ export class TimeoutError extends BaseError { constructor(msg = 'operation timed out', ...nested: Array) { super(msg, ...nested); diff --git a/src/utils/index.ts b/src/utils/index.ts index 76937ed..72efc30 100644 --- a/src/utils/index.ts +++ b/src/utils/index.ts @@ -2,6 +2,8 @@ import { NotFoundError } from '../error/NotFoundError'; /** * Unset value. + * + * @public */ /* eslint-disable-next-line @typescript-eslint/ban-types */ export type Nil = null | undefined; @@ -13,41 +15,57 @@ export type SortOrder = SortAfter | SortBefore | SortEqual; /** * Value that may be nil. + * + * @public */ export type Optional = T | Nil; /** * Comparison predicate for arity 0 - assert? + * + * @beta */ export type PredicateC0 = () => boolean; /** * Comparison predicate for arity 1 - filter. + * + * @beta */ export type PredicateC1 = (val: TVal, idx: number, list: Array) => boolean; /** * Comparison predicate for arity 2 - sort. + * + * @beta */ export type PredicateC2 = (pval: TVal, nval: TVal, idx: number, list: Array) => SortOrder; /** * Transform predicate for arity 0 - constructor. + * + * @beta */ export type PredicateR0 = () => TVal; /** * Transform predicate for arity 1 - map. + * + * @beta */ export type PredicateR1 = (val: TVal, idx: number, list: Array) => TVal; /** * Transform predicate for arity 2 - reduce. + * + * @beta */ export type PredicateR2 = (pval: TVal, nval: TVal, idx: number, list: Array) => TVal; /** * Check if a value is nil. + * + * @public */ /* eslint-disable-next-line @typescript-eslint/ban-types */ export function isNil(val: Optional): val is Nil { @@ -60,6 +78,8 @@ export function isNil(val: Optional): val is Nil { * * Arrays return their length, single values return 1, and nil values return 0. * This counts the number of elements that setOrPush would add. + * + * @public */ export function countOf(val: unknown): number { if (Array.isArray(val)) { @@ -73,6 +93,11 @@ export function countOf(val: unknown): number { return 0; } +/** + * Return the first element when `condition` is true and the second element when `condition` is false. + * + * @public + */ export function defaultWhen(condition: boolean, ...items: Array): TVal { if (condition) { return items[0]; @@ -83,6 +108,8 @@ export function defaultWhen(condition: boolean, ...items: Array): TV /** * Remove any null or undefined items from the list. + * + * @public */ export function filterNil(list: ArrayLike>): Array { return Array.from(list).filter(doesExist); @@ -90,6 +117,8 @@ export function filterNil(list: ArrayLike>): Array /** * Merge arguments, which may or may not be arrays, into one return that is definitely an array. + * + * @public */ export function mergeList(...parts: Array>): Array { const out = []; @@ -107,6 +136,8 @@ export function mergeList(...parts: Array>): Array(list: Array>, predicate: PredicateC1): TVal { const val = filterNil(list).find(predicate); @@ -115,6 +146,8 @@ export function mustFind(list: Array>, predicate: Predicate /** * Check if a variable is not nil. + * + * @public */ export function doesExist(val: Optional): val is T { return !isNil(val); @@ -125,6 +158,8 @@ export function doesExist(val: Optional): val is T { * * @throws NotFoundError * @returns val + * + * @public */ export function mustExist(val: Optional): T { if (isNil(val)) { @@ -137,7 +172,8 @@ export function mustExist(val: Optional): T { /** * Return the first value that is not nil. * - * TODO: rename to mustDefault + * @public + * @todo: rename to mustDefault */ export function mustCoalesce(...values: Array>): T { return mustFind(values, doesExist);