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