From b91e13fc914828dc399413e2946929e9c60d64b5 Mon Sep 17 00:00:00 2001 From: ssube Date: Sun, 8 Aug 2021 15:11:23 -0500 Subject: [PATCH] more function signature docs --- README.md | 3 +++ docs/api/js-utils.checklist.check.md | 2 ++ docs/api/js-utils.checklist.md | 2 +- docs/api/js-utils.checklistmode.md | 2 ++ docs/api/js-utils.checklistoptions.md | 2 ++ docs/api/js-utils.isarray_1.md | 2 ++ docs/api/js-utils.isempty.md | 2 ++ docs/api/js-utils.isnone.md | 2 ++ docs/api/js-utils.issome.md | 2 ++ docs/api/js-utils.leftpad.md | 2 ++ docs/api/js-utils.md | 24 ++++++++++++------------ docs/api/js-utils.normalizemap.md | 3 --- docs/api/js-utils.pushmergemap_1.md | 2 ++ docs/api/js-utils.signal.md | 4 ++++ docs/api/js-utils.toarray_1.md | 2 ++ docs/api/js-utils.trim.md | 2 ++ src/Array.ts | 15 +++++++++++++++ src/Checklist.ts | 9 +++++++++ src/Map.ts | 7 ++++++- src/Maybe.ts | 10 ++++++++++ src/Signal.ts | 5 +++++ src/String.ts | 7 +++++++ 22 files changed, 94 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 0a46b50..5b21099 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,9 @@ The library is bundled and has no dependencies. ## Features +[Please see the complete API docs](https://github.com/ssube/js-utils/blob/master/docs/api/js-utils.md) for the full +function list. + Features utilities and helpers for: - Array diff --git a/docs/api/js-utils.checklist.check.md b/docs/api/js-utils.checklist.check.md index f9260b7..8144785 100644 --- a/docs/api/js-utils.checklist.check.md +++ b/docs/api/js-utils.checklist.check.md @@ -4,6 +4,8 @@ ## Checklist.check() method +Check whether a value is included or excluded from this checklist (depending on `mode`). + Signature: ```typescript diff --git a/docs/api/js-utils.checklist.md b/docs/api/js-utils.checklist.md index 2185afa..777f659 100644 --- a/docs/api/js-utils.checklist.md +++ b/docs/api/js-utils.checklist.md @@ -30,5 +30,5 @@ export declare class Checklist implements ChecklistOptions | Method | Modifiers | Description | | --- | --- | --- | -| [check(value)](./js-utils.checklist.check.md) | | | +| [check(value)](./js-utils.checklist.check.md) | | Check whether a value is included or excluded from this checklist (depending on mode). | diff --git a/docs/api/js-utils.checklistmode.md b/docs/api/js-utils.checklistmode.md index 78460d7..6bc7784 100644 --- a/docs/api/js-utils.checklistmode.md +++ b/docs/api/js-utils.checklistmode.md @@ -4,6 +4,8 @@ ## ChecklistMode enum +Whether items should be checked for inclusion (allow list) or exclusion (deny list). + Signature: ```typescript diff --git a/docs/api/js-utils.checklistoptions.md b/docs/api/js-utils.checklistoptions.md index 4b39f6d..435c3d9 100644 --- a/docs/api/js-utils.checklistoptions.md +++ b/docs/api/js-utils.checklistoptions.md @@ -4,6 +4,8 @@ ## ChecklistOptions interface +Mode of operation and items to check. + Signature: ```typescript diff --git a/docs/api/js-utils.isarray_1.md b/docs/api/js-utils.isarray_1.md index 3186ce2..0de4494 100644 --- a/docs/api/js-utils.isarray_1.md +++ b/docs/api/js-utils.isarray_1.md @@ -4,6 +4,8 @@ ## isArray() function +Wrapper for `Array.isArray` with better readonly type handling. + Signature: ```typescript diff --git a/docs/api/js-utils.isempty.md b/docs/api/js-utils.isempty.md index 27f42f9..dbde1e1 100644 --- a/docs/api/js-utils.isempty.md +++ b/docs/api/js-utils.isempty.md @@ -4,6 +4,8 @@ ## isEmpty() function +Check if a `Maybe>` does in fact contain an array, and that array has items. + Signature: ```typescript diff --git a/docs/api/js-utils.isnone.md b/docs/api/js-utils.isnone.md index ec710d2..5498024 100644 --- a/docs/api/js-utils.isnone.md +++ b/docs/api/js-utils.isnone.md @@ -4,6 +4,8 @@ ## isNone() function +Typeguard to check if a `Maybe` is `None` (null or undefined). + Signature: ```typescript diff --git a/docs/api/js-utils.issome.md b/docs/api/js-utils.issome.md index 9157a5a..f183e40 100644 --- a/docs/api/js-utils.issome.md +++ b/docs/api/js-utils.issome.md @@ -4,6 +4,8 @@ ## isSome() function +Typeguard to check if a `Maybe` is `Some` value (not `None`). + Signature: ```typescript diff --git a/docs/api/js-utils.leftpad.md b/docs/api/js-utils.leftpad.md index 6af610b..b6ab980 100644 --- a/docs/api/js-utils.leftpad.md +++ b/docs/api/js-utils.leftpad.md @@ -4,6 +4,8 @@ ## leftPad() function +Prefix `val` with `fill` until it is at least `min` characters. + Signature: ```typescript diff --git a/docs/api/js-utils.md b/docs/api/js-utils.md index b89188f..1297580 100644 --- a/docs/api/js-utils.md +++ b/docs/api/js-utils.md @@ -21,7 +21,7 @@ | Enumeration | Description | | --- | --- | -| [ChecklistMode](./js-utils.checklistmode.md) | | +| [ChecklistMode](./js-utils.checklistmode.md) | Whether items should be checked for inclusion (allow list) or exclusion (deny list). | ## Functions @@ -52,13 +52,13 @@ | [hasItems(val)](./js-utils.hasitems.md) | Test if a value is an array with some items (length > 0).This is not a general replacement for .length > 0, since it is also a typeguard: if (hasItems(val)) else { val } will complain that val is never in the else branch, since it was proven not to be an array by this function, even if val is simply empty. | | [hasItems(val)](./js-utils.hasitems_1.md) | | | [isArray(list)](./js-utils.isarray.md) | Wrapper for Array.isArray with better readonly type handling. | -| [isArray(list)](./js-utils.isarray_1.md) | | +| [isArray(list)](./js-utils.isarray_1.md) | Wrapper for Array.isArray with better readonly type handling. | | [isDebug()](./js-utils.isdebug.md) | Test if DEBUG mode is set.TODO: check variable value as well | -| [isEmpty(val)](./js-utils.isempty.md) | | +| [isEmpty(val)](./js-utils.isempty.md) | Check if a Maybe<Array<T>> does in fact contain an array, and that array has items. | | [isNil(val)](./js-utils.isnil.md) | Check if a value is nil. | -| [isNone(val)](./js-utils.isnone.md) | | -| [isSome(val)](./js-utils.issome.md) | | -| [leftPad(val, min, fill)](./js-utils.leftpad.md) | | +| [isNone(val)](./js-utils.isnone.md) | Typeguard to check if a Maybe is None (null or undefined). | +| [isSome(val)](./js-utils.issome.md) | Typeguard to check if a Maybe is Some value (not None). | +| [leftPad(val, min, fill)](./js-utils.leftpad.md) | Prefix val with fill until it is at least min characters. | | [lengthOf(val)](./js-utils.lengthof.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. | | [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. | @@ -72,19 +72,19 @@ | [mustExist(val, err)](./js-utils.mustexist.md) | Assert that a variable is not None and return the value. Throw if it is None. | | [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) | (BETA) Normalize a map-like of values into a dict of lists of strings. | +| [normalizeMap(map)](./js-utils.normalizemap.md) | 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. | -| [pushMergeMap(args)](./js-utils.pushmergemap_1.md) | | +| [pushMergeMap(args)](./js-utils.pushmergemap_1.md) | Merge the provided maps into a new map, merging keys that already exist by pushing new items. | | [removeNone(list)](./js-utils.removenone.md) | Remove any null or undefined items from the list. | | [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) | | +| [signal(signals)](./js-utils.signal.md) | Wait for an OS signal. | | [spyLogger(spies)](./js-utils.spylogger.md) | Create a spy logger using the provided methods, which returns itself as a child. ensure all methods are present by extending null logger | | [sum(a, b)](./js-utils.sum.md) | Add numbers. PredicateR2<number, number> | | [timeout(ms, inner)](./js-utils.timeout.md) | Reject after a set amount of time if the original promise has not yet resolved. | | [toArray(val)](./js-utils.toarray.md) | Copy an existing array-like or convert a single value to an array. | -| [toArray(val)](./js-utils.toarray_1.md) | | -| [trim(val, max, tail)](./js-utils.trim.md) | | +| [toArray(val)](./js-utils.toarray_1.md) | Copy an existing readonly array-like or convert a single value to a readonly array. | +| [trim(val, max, tail)](./js-utils.trim.md) | Return the start of val, up to max characters. If val is longer than max and there is room, suffix with tail. | | [waitFor(cb, step, tries)](./js-utils.waitfor.md) | | | [waitForChild(child)](./js-utils.waitforchild.md) | | | [writeInput(stream, value)](./js-utils.writeinput.md) | | @@ -95,7 +95,7 @@ | Interface | Description | | --- | --- | | [ArrayMapperOptions](./js-utils.arraymapperoptions.md) | | -| [ChecklistOptions](./js-utils.checklistoptions.md) | | +| [ChecklistOptions](./js-utils.checklistoptions.md) | Mode of operation and items to check. | | [ChildOptions](./js-utils.childoptions.md) | | | [ChildResult](./js-utils.childresult.md) | | | [Dict](./js-utils.dict.md) | | diff --git a/docs/api/js-utils.normalizemap.md b/docs/api/js-utils.normalizemap.md index 4c5b8df..1fbbbfe 100644 --- a/docs/api/js-utils.normalizemap.md +++ b/docs/api/js-utils.normalizemap.md @@ -4,9 +4,6 @@ ## 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. -> - > Warning: This API is now obsolete. > > diff --git a/docs/api/js-utils.pushmergemap_1.md b/docs/api/js-utils.pushmergemap_1.md index 8b81bff..7a9c4d2 100644 --- a/docs/api/js-utils.pushmergemap_1.md +++ b/docs/api/js-utils.pushmergemap_1.md @@ -4,6 +4,8 @@ ## pushMergeMap() function +Merge the provided maps into a new map, merging keys that already exist by pushing new items. + Signature: ```typescript diff --git a/docs/api/js-utils.signal.md b/docs/api/js-utils.signal.md index db418d0..a32ac77 100644 --- a/docs/api/js-utils.signal.md +++ b/docs/api/js-utils.signal.md @@ -4,6 +4,8 @@ ## signal() function +Wait for an OS signal. + Signature: ```typescript @@ -20,3 +22,5 @@ export declare function signal(...signals: Array): PromiseSignature: ```typescript diff --git a/docs/api/js-utils.trim.md b/docs/api/js-utils.trim.md index eec7c1d..9d0a436 100644 --- a/docs/api/js-utils.trim.md +++ b/docs/api/js-utils.trim.md @@ -4,6 +4,8 @@ ## trim() function +Return the start of `val`, up to `max` characters. If `val` is longer than `max` and there is room, suffix with `tail`. + Signature: ```typescript diff --git a/src/Array.ts b/src/Array.ts index 30d3d61..b784920 100644 --- a/src/Array.ts +++ b/src/Array.ts @@ -57,6 +57,9 @@ export function ensureArray(val: Maybe>): ReadonlyArray { * Copy an existing array-like or convert a single value to an array. */ export function toArray(val: Maybe>): Array; +/** + * Copy an existing readonly array-like or convert a single value to a readonly array. + */ export function toArray(val: Maybe>): ReadonlyArray; export function toArray(val: Maybe>): ReadonlyArray { if (isArray(val)) { @@ -72,13 +75,25 @@ export function toArray(val: Maybe>): ReadonlyA /** * Wrapper for `Array.isArray` with better readonly type handling. + * + * @public */ export function isArray(list: TVal | Array): list is Array; +/** + * Wrapper for `Array.isArray` with better readonly type handling. + * + * @public + */ export function isArray(list: TVal | ReadonlyArray): list is ReadonlyArray; export function isArray(list: TVal | ReadonlyArray): list is ReadonlyArray { return Array.isArray(list); } +/** + * Check if a `Maybe>` does in fact contain an array, and that array has items. + * + * @public + */ export function isEmpty(val: Maybe | ReadonlyArray>): boolean { return isNone(val) || lengthOf(val) === 0; } diff --git a/src/Checklist.ts b/src/Checklist.ts index b5dc774..995afc6 100644 --- a/src/Checklist.ts +++ b/src/Checklist.ts @@ -1,8 +1,14 @@ +/** + * Whether items should be checked for inclusion (allow list) or exclusion (deny list). + */ export enum ChecklistMode { INCLUDE = 'include', EXCLUDE = 'exclude', } +/** + * Mode of operation and items to check. + */ export interface ChecklistOptions { data: Array; mode: ChecklistMode; @@ -23,6 +29,9 @@ export class Checklist implements ChecklistOptions { this.mode = options.mode; } + /** + * Check whether a value is included or excluded from this checklist (depending on `mode`). + */ public check(value: T): boolean { switch (this.mode) { case ChecklistMode.INCLUDE: diff --git a/src/Map.ts b/src/Map.ts index 7370a26..06a7e34 100644 --- a/src/Map.ts +++ b/src/Map.ts @@ -113,6 +113,11 @@ export function mergeMap(target: Map, source: Map(...args: Array>>): Map>; +/** + * Merge the provided maps into a new map, merging keys that already exist by pushing new items. + * + * @public + */ export function pushMergeMap(...args: ReadonlyArray>>): Map>; export function pushMergeMap(...args: ReadonlyArray>>): Map> { const out = new Map(); @@ -199,7 +204,7 @@ export function dictValuesToArrays(map: MapLike): Dict> /** * Normalize a map-like of values into a dict of lists of strings. * - * @beta + * @public * @deprecated */ export function normalizeMap(map: MapLike): Dict> { diff --git a/src/Maybe.ts b/src/Maybe.ts index 41dc486..6989aff 100644 --- a/src/Maybe.ts +++ b/src/Maybe.ts @@ -16,11 +16,21 @@ export type None = null | undefined; */ export type Maybe = T | None; +/** + * Typeguard to check if a `Maybe` is `None` (null or undefined). + * + * @public + */ export function isNone(val: Maybe): val is None { /* eslint-disable-next-line no-null/no-null */ return val === null || val === undefined; } +/** + * Typeguard to check if a `Maybe` is `Some` value (not `None`). + * + * @public + */ export function isSome(val: Maybe): val is T { return isNone(val) === false; } diff --git a/src/Signal.ts b/src/Signal.ts index 8173015..1d8f80e 100644 --- a/src/Signal.ts +++ b/src/Signal.ts @@ -2,6 +2,11 @@ export const SIGNAL_RELOAD: NodeJS.Signals = 'SIGHUP'; export const SIGNAL_RESET: NodeJS.Signals = 'SIGINT'; export const SIGNAL_STOP: NodeJS.Signals = 'SIGTERM'; +/** + * Wait for an OS signal. + * + * @returns the fired signal + */ export function signal(...signals: Array): Promise { return new Promise((res, _rej) => { function handler(fired: NodeJS.Signals) { diff --git a/src/String.ts b/src/String.ts index 150555e..b021d53 100644 --- a/src/String.ts +++ b/src/String.ts @@ -1,5 +1,8 @@ export const DEFAULT_TRIM = 8; +/** + * Prefix `val` with `fill` until it is at least `min` characters. + */ export function leftPad(val: string, min = DEFAULT_TRIM, fill = '0'): string { if (val.length < min) { const len = min - val.length; @@ -10,6 +13,10 @@ export function leftPad(val: string, min = DEFAULT_TRIM, fill = '0'): string { } } +/** + * Return the start of `val`, up to `max` characters. If `val` is longer than `max` and there is room, + * suffix with `tail`. + */ export function trim(val: string, max: number, tail = '...'): string { if (val.length <= max) { return val;