more function signature docs

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

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`<!-- -->).
+
 <b>Signature:</b>
 
 ```typescript

docs/api/js-utils.checklist.md

@@ -30,5 +30,5 @@ export declare class Checklist<T> implements ChecklistOptions<T>
 
 |  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 <code>mode</code>). |
 

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).
+
 <b>Signature:</b>
 
 ```typescript

docs/api/js-utils.checklistoptions.md

@@ -4,6 +4,8 @@
 
 ## ChecklistOptions interface
 
+Mode of operation and items to check.
+
 <b>Signature:</b>
 
 ```typescript

docs/api/js-utils.isarray_1.md

@@ -4,6 +4,8 @@
 
 ## isArray() function
 
+Wrapper for `Array.isArray` with better readonly type handling.
+
 <b>Signature:</b>
 
 ```typescript

docs/api/js-utils.isempty.md

@@ -4,6 +4,8 @@
 
 ## isEmpty() function
 
+Check if a `Maybe<Array<T>>` does in fact contain an array, and that array has items.
+
 <b>Signature:</b>
 
 ```typescript

docs/api/js-utils.isnone.md

@@ -4,6 +4,8 @@
 
 ## isNone() function
 
+Typeguard to check if a `Maybe` is `None` (null or undefined).
+
 <b>Signature:</b>
 
 ```typescript

docs/api/js-utils.issome.md

@@ -4,6 +4,8 @@
 
 ## isSome() function
 
+Typeguard to check if a `Maybe` is `Some` value (not `None`<!-- -->).
+
 <b>Signature:</b>
 
 ```typescript

docs/api/js-utils.leftpad.md

@@ -4,6 +4,8 @@
 
 ## leftPad() function
 
+Prefix `val` with `fill` until it is at least `min` characters.
+
 <b>Signature:</b>
 
 ```typescript

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 &gt; 0).<!-- -->This is not a general replacement for <code>.length &gt; 0</code>, since it is also a typeguard: <code>if (hasItems(val)) else { val }</code> will complain that <code>val</code> is <code>never</code> in the <code>else</code> branch, since it was proven not to be an array by this function, even if <code>val</code> is simply empty. |
 |  [hasItems(val)](./js-utils.hasitems_1.md) |  |
 |  [isArray(list)](./js-utils.isarray.md) | Wrapper for <code>Array.isArray</code> with better readonly type handling. |
-|  [isArray(list)](./js-utils.isarray_1.md) |  |
+|  [isArray(list)](./js-utils.isarray_1.md) | Wrapper for <code>Array.isArray</code> 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 <code>Maybe&lt;Array&lt;T&gt;&gt;</code> 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 <code>Maybe</code> is <code>None</code> (null or undefined). |
+|  [isSome(val)](./js-utils.issome.md) | Typeguard to check if a <code>Maybe</code> is <code>Some</code> value (not <code>None</code>). |
+|  [leftPad(val, min, fill)](./js-utils.leftpad.md) | Prefix <code>val</code> with <code>fill</code> until it is at least <code>min</code> 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 <code>None</code> and return the value. Throw if it is <code>None</code>. |
 |  [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) | <b><i>(BETA)</i></b> 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<!-- -->&lt;<!-- -->number, number<!-- -->&gt; |
 |  [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 <code>val</code>, up to <code>max</code> characters. If <code>val</code> is longer than <code>max</code> and there is room, suffix with <code>tail</code>. |
 |  [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) |  |

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.
 > 
 > 

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.
+
 <b>Signature:</b>
 
 ```typescript

docs/api/js-utils.signal.md

@@ -4,6 +4,8 @@
 
 ## signal() function
 
+Wait for an OS signal.
+
 <b>Signature:</b>
 
 ```typescript
@@ -20,3 +22,5 @@ export declare function signal(...signals: Array<NodeJS.Signals>): Promise<NodeJ
 
 Promise&lt;NodeJS.Signals&gt;
 
+the fired signal
+

docs/api/js-utils.toarray_1.md

@@ -4,6 +4,8 @@
 
 ## toArray() function
 
+Copy an existing readonly array-like or convert a single value to a readonly array.
+
 <b>Signature:</b>
 
 ```typescript

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`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript

src/Array.ts

@@ -57,6 +57,9 @@ export function ensureArray<T>(val: Maybe<ReadonlyArray<T>>): ReadonlyArray<T> {
  * Copy an existing array-like or convert a single value to an array.
  */
 export function toArray<TVal>(val: Maybe<TVal | Array<TVal>>): Array<TVal>;
+/**
+ * Copy an existing readonly array-like or convert a single value to a readonly array.
+ */
 export function toArray<TVal>(val: Maybe<TVal | ReadonlyArray<TVal>>): ReadonlyArray<TVal>;
 export function toArray<TVal>(val: Maybe<TVal | ReadonlyArray<TVal>>): ReadonlyArray<TVal> {
   if (isArray(val)) {
@@ -72,13 +75,25 @@ export function toArray<TVal>(val: Maybe<TVal | ReadonlyArray<TVal>>): ReadonlyA
 
 /**
  * Wrapper for `Array.isArray` with better readonly type handling.
+ *
+ * @public
  */
 export function isArray<TVal>(list: TVal | Array<TVal>): list is Array<TVal>;
+/**
+ * Wrapper for `Array.isArray` with better readonly type handling.
+ *
+ * @public
+ */
 export function isArray<TVal>(list: TVal | ReadonlyArray<TVal>): list is ReadonlyArray<TVal>;
 export function isArray<TVal>(list: TVal | ReadonlyArray<TVal>): list is ReadonlyArray<TVal> {
   return Array.isArray(list);
 }
 
+/**
+ * Check if a `Maybe<Array<T>>` does in fact contain an array, and that array has items.
+ *
+ * @public
+ */
 export function isEmpty(val: Maybe<Array<unknown> | ReadonlyArray<unknown>>): boolean {
   return isNone(val) || lengthOf(val) === 0;
 }

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<T> {
   data: Array<T>;
   mode: ChecklistMode;
@@ -23,6 +29,9 @@ export class Checklist<T> implements ChecklistOptions<T> {
     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:

src/Map.ts

@@ -113,6 +113,11 @@ export function mergeMap<TKey, TVal>(target: Map<TKey, TVal>, source: Map<TKey,
  * @public
  */
 export function pushMergeMap<TKey, TVal>(...args: Array<Map<TKey, TVal | Array<TVal>>>): Map<TKey, Array<TVal>>;
+/**
+ * Merge the provided maps into a new map, merging keys that already exist by pushing new items.
+ *
+ * @public
+ */
 export function pushMergeMap<TKey, TVal>(...args: ReadonlyArray<Map<TKey, TVal | ReadonlyArray<TVal>>>): Map<TKey, ReadonlyArray<TVal>>;
 export function pushMergeMap<TKey, TVal>(...args: ReadonlyArray<Map<TKey, TVal | ReadonlyArray<TVal>>>): Map<TKey, ReadonlyArray<TVal>> {
   const out = new Map();
@@ -199,7 +204,7 @@ export function dictValuesToArrays<TVal>(map: MapLike<TVal>): Dict<Array<TVal>>
 /**
  * Normalize a map-like of values into a dict of lists of strings.
  *
- * @beta
+ * @public
  * @deprecated
  */
 export function normalizeMap(map: MapLike<unknown>): Dict<Array<string>> {

src/Maybe.ts

@@ -16,11 +16,21 @@ export type None = null | undefined;
  */
 export type Maybe<T> = T | None;
 
+/**
+ * Typeguard to check if a `Maybe` is `None` (null or undefined).
+ *
+ * @public
+ */
 export function isNone<T>(val: Maybe<T>): 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<T>(val: Maybe<T>): val is T {
   return isNone(val) === false;
 }

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<NodeJS.Signals>): Promise<NodeJS.Signals> {
   return new Promise((res, _rej) => {
     function handler(fired: NodeJS.Signals) {

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;