From d3e52d9363425ca9862bbcbf088fac8d19755ef1 Mon Sep 17 00:00:00 2001 From: Sean Sube Date: Sat, 8 Oct 2022 14:52:35 -0500 Subject: [PATCH] fix(docs): typedef and doc warnings --- config/api-extractor.json | 6 +- docs/api/js-utils.allowedbufferencoding.md | 1 + docs/api/js-utils.arraymapper.md | 6 +- docs/api/js-utils.arraymapperoptions.md | 11 +- docs/api/js-utils.checklist.md | 6 +- docs/api/js-utils.checklistoptions.md | 8 +- docs/api/js-utils.childoptions.md | 9 +- ...s-utils.childprocesserror._constructor_.md | 2 +- docs/api/js-utils.childresult.md | 11 +- docs/api/js-utils.childspawner.md | 1 + docs/api/js-utils.dict.md | 1 + docs/api/js-utils.ensurearray_1.md | 1 + docs/api/js-utils.filterzip_1.md | 1 + docs/api/js-utils.filterzip_2.md | 1 + docs/api/js-utils.filterzip_3.md | 1 + docs/api/js-utils.gettestlogger.md | 2 +- docs/api/js-utils.hasitems_1.md | 1 + ...tils.invalidargumenterror._constructor_.md | 2 +- docs/api/js-utils.isdebug.md | 19 - docs/api/js-utils.isnil.md | 1 + docs/api/js-utils.leftpad.md | 4 +- docs/api/js-utils.md | 10 +- docs/api/js-utils.mergearray_1.md | 1 + docs/api/js-utils.mergearrays_1.md | 1 + .../js-utils.missingkeyerror._constructor_.md | 2 +- docs/api/js-utils.mustcoalesce.md | 1 + docs/api/js-utils.mustexist.md | 2 +- docs/api/js-utils.nil.md | 1 + docs/api/js-utils.normalizemap.md | 1 + .../js-utils.notfounderror._constructor_.md | 2 +- ...utils.notimplementederror._constructor_.md | 2 +- docs/api/js-utils.optional.md | 1 + docs/api/js-utils.signal_reload.md | 1 + docs/api/js-utils.signal_reset.md | 1 + docs/api/js-utils.signal_stop.md | 1 + docs/api/js-utils.spylogger.md | 26 -- docs/api/js-utils.sum.md | 2 - .../js-utils.timeouterror._constructor_.md | 2 +- docs/api/js-utils.trim.md | 2 +- docs/api/js-utils.waitfor.md | 1 + docs/api/js-utils.waitforchild.md | 1 + docs/api/js-utils.writeinput.md | 1 + docs/api/js-utils.writevalue.md | 1 + docs/js-utils.api.md | 349 ++++++++++++++++++ src/Array.ts | 21 ++ src/Logger.ts | 2 +- src/Math.ts | 1 - 47 files changed, 436 insertions(+), 95 deletions(-) delete mode 100644 docs/api/js-utils.isdebug.md delete mode 100644 docs/api/js-utils.spylogger.md create mode 100644 docs/js-utils.api.md diff --git a/config/api-extractor.json b/config/api-extractor.json index 2bbeed9..6cfa5cf 100644 --- a/config/api-extractor.json +++ b/config/api-extractor.json @@ -4,31 +4,27 @@ "mainEntryPointFilePath": "/out/src/index.d.ts", "apiReport": { "enabled": true, - "reportFolder": "/out/", + "reportFolder": "/docs/", "reportTempFolder": "/out/tmp/" }, "docModel": { "enabled": true, "apiJsonFilePath": "/out/api/.api.json" }, - "dtsRollup": { "enabled": true, "untrimmedFilePath": "/out/index.d.ts", "betaTrimmedFilePath": "/out/index-beta.d.ts", "publicTrimmedFilePath": "/out/index-public.d.ts" }, - "tsdocMetadata": { }, - "messages": { "compilerMessageReporting": { "default": { "logLevel": "warning" } }, - "extractorMessageReporting": { "default": { "logLevel": "warning" diff --git a/docs/api/js-utils.allowedbufferencoding.md b/docs/api/js-utils.allowedbufferencoding.md index fd5fe50..37802ba 100644 --- a/docs/api/js-utils.allowedbufferencoding.md +++ b/docs/api/js-utils.allowedbufferencoding.md @@ -4,6 +4,7 @@ ## AllowedBufferEncoding type + Signature: ```typescript diff --git a/docs/api/js-utils.arraymapper.md b/docs/api/js-utils.arraymapper.md index fa1b2ff..bfa424a 100644 --- a/docs/api/js-utils.arraymapper.md +++ b/docs/api/js-utils.arraymapper.md @@ -22,9 +22,9 @@ export declare class ArrayMapper | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [rest](./js-utils.arraymapper.rest.md) | | string | | -| [skip](./js-utils.arraymapper.skip.md) | | number | | -| [take](./js-utils.arraymapper.take.md) | | Array<string> | | +| [rest](./js-utils.arraymapper.rest.md) | readonly | string | | +| [skip](./js-utils.arraymapper.skip.md) | readonly | number | | +| [take](./js-utils.arraymapper.take.md) | readonly | Array<string> | | ## Methods diff --git a/docs/api/js-utils.arraymapperoptions.md b/docs/api/js-utils.arraymapperoptions.md index d69d1cd..ebee2fe 100644 --- a/docs/api/js-utils.arraymapperoptions.md +++ b/docs/api/js-utils.arraymapperoptions.md @@ -4,6 +4,7 @@ ## ArrayMapperOptions interface + Signature: ```typescript @@ -12,9 +13,9 @@ export interface ArrayMapperOptions ## Properties -| Property | Type | Description | -| --- | --- | --- | -| [rest](./js-utils.arraymapperoptions.rest.md) | string | Key for any remaining, unmatched elements. | -| [skip](./js-utils.arraymapperoptions.skip.md) | number | Number of initial elements to skip. | -| [take](./js-utils.arraymapperoptions.take.md) | Array<string> | List of element keys. | +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [rest](./js-utils.arraymapperoptions.rest.md) | | string | Key for any remaining, unmatched elements. | +| [skip](./js-utils.arraymapperoptions.skip.md) | | number | Number of initial elements to skip. | +| [take](./js-utils.arraymapperoptions.take.md) | | Array<string> | List of element keys. | diff --git a/docs/api/js-utils.checklist.md b/docs/api/js-utils.checklist.md index 777f659..30acbe4 100644 --- a/docs/api/js-utils.checklist.md +++ b/docs/api/js-utils.checklist.md @@ -4,7 +4,7 @@ ## Checklist class -Check whether items are included or not (blacklist or whitelist, depending on `mode`). +Check whether items are included or not. Signature: @@ -23,8 +23,8 @@ export declare class Checklist implements ChecklistOptions | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [data](./js-utils.checklist.data.md) | | Array<T> | TODO: switch to Set | -| [mode](./js-utils.checklist.mode.md) | | [ChecklistMode](./js-utils.checklistmode.md) | | +| [data](./js-utils.checklist.data.md) | readonly | Array<T> | TODO: switch to Set | +| [mode](./js-utils.checklist.mode.md) | readonly | [ChecklistMode](./js-utils.checklistmode.md) | | ## Methods diff --git a/docs/api/js-utils.checklistoptions.md b/docs/api/js-utils.checklistoptions.md index 435c3d9..bbfece5 100644 --- a/docs/api/js-utils.checklistoptions.md +++ b/docs/api/js-utils.checklistoptions.md @@ -14,8 +14,8 @@ export interface ChecklistOptions ## Properties -| Property | Type | Description | -| --- | --- | --- | -| [data](./js-utils.checklistoptions.data.md) | Array<T> | | -| [mode](./js-utils.checklistoptions.mode.md) | [ChecklistMode](./js-utils.checklistmode.md) | | +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [data](./js-utils.checklistoptions.data.md) | | Array<T> | | +| [mode](./js-utils.checklistoptions.mode.md) | | [ChecklistMode](./js-utils.checklistmode.md) | | diff --git a/docs/api/js-utils.childoptions.md b/docs/api/js-utils.childoptions.md index a099310..3bdcc00 100644 --- a/docs/api/js-utils.childoptions.md +++ b/docs/api/js-utils.childoptions.md @@ -4,6 +4,7 @@ ## ChildOptions interface + Signature: ```typescript @@ -13,8 +14,8 @@ export interface ChildOptions extends ChildProcessOptions ## Properties -| Property | Type | Description | -| --- | --- | --- | -| [args](./js-utils.childoptions.args.md) | Array<string> | | -| [command](./js-utils.childoptions.command.md) | string | | +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [args](./js-utils.childoptions.args.md) | | Array<string> | | +| [command](./js-utils.childoptions.command.md) | | string | | diff --git a/docs/api/js-utils.childprocesserror._constructor_.md b/docs/api/js-utils.childprocesserror._constructor_.md index 33f6bb1..b48992d 100644 --- a/docs/api/js-utils.childprocesserror._constructor_.md +++ b/docs/api/js-utils.childprocesserror._constructor_.md @@ -16,6 +16,6 @@ constructor(msg?: string, ...nested: Array); | Parameter | Type | Description | | --- | --- | --- | -| msg | string | | +| msg | string | (Optional) | | nested | Array<Error> | | diff --git a/docs/api/js-utils.childresult.md b/docs/api/js-utils.childresult.md index 4657a2b..809f61d 100644 --- a/docs/api/js-utils.childresult.md +++ b/docs/api/js-utils.childresult.md @@ -4,6 +4,7 @@ ## ChildResult interface + Signature: ```typescript @@ -12,9 +13,9 @@ export interface ChildResult ## Properties -| Property | Type | Description | -| --- | --- | --- | -| [status](./js-utils.childresult.status.md) | number | | -| [stderr](./js-utils.childresult.stderr.md) | string | | -| [stdout](./js-utils.childresult.stdout.md) | string | | +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [status](./js-utils.childresult.status.md) | | number | | +| [stderr](./js-utils.childresult.stderr.md) | | string | | +| [stdout](./js-utils.childresult.stdout.md) | | string | | diff --git a/docs/api/js-utils.childspawner.md b/docs/api/js-utils.childspawner.md index 4d062bd..ecfdd57 100644 --- a/docs/api/js-utils.childspawner.md +++ b/docs/api/js-utils.childspawner.md @@ -4,6 +4,7 @@ ## ChildSpawner type + Signature: ```typescript diff --git a/docs/api/js-utils.dict.md b/docs/api/js-utils.dict.md index 985d78b..13df8f4 100644 --- a/docs/api/js-utils.dict.md +++ b/docs/api/js-utils.dict.md @@ -4,6 +4,7 @@ ## Dict interface + Signature: ```typescript diff --git a/docs/api/js-utils.ensurearray_1.md b/docs/api/js-utils.ensurearray_1.md index 4207115..c8b52a4 100644 --- a/docs/api/js-utils.ensurearray_1.md +++ b/docs/api/js-utils.ensurearray_1.md @@ -4,6 +4,7 @@ ## ensureArray() function + Signature: ```typescript diff --git a/docs/api/js-utils.filterzip_1.md b/docs/api/js-utils.filterzip_1.md index 288e646..5d7ea68 100644 --- a/docs/api/js-utils.filterzip_1.md +++ b/docs/api/js-utils.filterzip_1.md @@ -4,6 +4,7 @@ ## filterZip() function + Signature: ```typescript diff --git a/docs/api/js-utils.filterzip_2.md b/docs/api/js-utils.filterzip_2.md index c4df3ba..a80b72c 100644 --- a/docs/api/js-utils.filterzip_2.md +++ b/docs/api/js-utils.filterzip_2.md @@ -4,6 +4,7 @@ ## filterZip() function + Signature: ```typescript diff --git a/docs/api/js-utils.filterzip_3.md b/docs/api/js-utils.filterzip_3.md index 63057c5..3b4e492 100644 --- a/docs/api/js-utils.filterzip_3.md +++ b/docs/api/js-utils.filterzip_3.md @@ -4,6 +4,7 @@ ## filterZip() function + Signature: ```typescript diff --git a/docs/api/js-utils.gettestlogger.md b/docs/api/js-utils.gettestlogger.md index b72b795..47962ae 100644 --- a/docs/api/js-utils.gettestlogger.md +++ b/docs/api/js-utils.gettestlogger.md @@ -16,7 +16,7 @@ export declare function getTestLogger(verbose?: boolean): Logger; | Parameter | Type | Description | | --- | --- | --- | -| verbose | boolean | | +| verbose | boolean | (Optional) | Returns: diff --git a/docs/api/js-utils.hasitems_1.md b/docs/api/js-utils.hasitems_1.md index 526fe8b..7cbe4c5 100644 --- a/docs/api/js-utils.hasitems_1.md +++ b/docs/api/js-utils.hasitems_1.md @@ -4,6 +4,7 @@ ## hasItems() function + Signature: ```typescript diff --git a/docs/api/js-utils.invalidargumenterror._constructor_.md b/docs/api/js-utils.invalidargumenterror._constructor_.md index 5e3946b..9a9ec99 100644 --- a/docs/api/js-utils.invalidargumenterror._constructor_.md +++ b/docs/api/js-utils.invalidargumenterror._constructor_.md @@ -16,6 +16,6 @@ constructor(msg?: string, ...nested: Array); | Parameter | Type | Description | | --- | --- | --- | -| msg | string | | +| msg | string | (Optional) | | nested | Array<Error> | | diff --git a/docs/api/js-utils.isdebug.md b/docs/api/js-utils.isdebug.md deleted file mode 100644 index e50bbe7..0000000 --- a/docs/api/js-utils.isdebug.md +++ /dev/null @@ -1,19 +0,0 @@ - - -[Home](./index.md) > [@apextoaster/js-utils](./js-utils.md) > [isDebug](./js-utils.isdebug.md) - -## isDebug() function - -Test if DEBUG mode is set. - -TODO: check variable value as well - -Signature: - -```typescript -export declare function isDebug(): boolean; -``` -Returns: - -boolean - diff --git a/docs/api/js-utils.isnil.md b/docs/api/js-utils.isnil.md index 1ab9725..bd5d733 100644 --- a/docs/api/js-utils.isnil.md +++ b/docs/api/js-utils.isnil.md @@ -6,6 +6,7 @@ > Warning: This API is now obsolete. > +> use `isNone` instead > Check if a value is nil. diff --git a/docs/api/js-utils.leftpad.md b/docs/api/js-utils.leftpad.md index b6ab980..2679a69 100644 --- a/docs/api/js-utils.leftpad.md +++ b/docs/api/js-utils.leftpad.md @@ -17,8 +17,8 @@ export declare function leftPad(val: string, min?: number, fill?: string): strin | Parameter | Type | Description | | --- | --- | --- | | val | string | | -| min | number | | -| fill | string | | +| min | number | (Optional) | +| fill | string | (Optional) | Returns: diff --git a/docs/api/js-utils.md b/docs/api/js-utils.md index b1ee295..d0f08a4 100644 --- a/docs/api/js-utils.md +++ b/docs/api/js-utils.md @@ -9,7 +9,7 @@ | Class | Description | | --- | --- | | [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. | -| [Checklist](./js-utils.checklist.md) | Check whether items are included or not (blacklist or whitelist, depending on mode). | +| [Checklist](./js-utils.checklist.md) | Check whether items are included or not. | | [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. | @@ -49,17 +49,16 @@ | [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) | Get a test logger. Returns a null logger unless verbose is true or run under debug mode. | -| [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.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) | 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) | 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) | 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. | +| [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. | | [mergeArray(parts)](./js-utils.mergearray.md) | Merge arguments, which may or may not be arrays, into one return that is definitely an array. | @@ -79,8 +78,7 @@ | [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) | 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> | +| [sum(a, b)](./js-utils.sum.md) | Add numbers. | | [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) | Copy an existing readonly array-like or convert a single value to a readonly array. | diff --git a/docs/api/js-utils.mergearray_1.md b/docs/api/js-utils.mergearray_1.md index b00b9c9..80a3212 100644 --- a/docs/api/js-utils.mergearray_1.md +++ b/docs/api/js-utils.mergearray_1.md @@ -4,6 +4,7 @@ ## mergeArray() function + Signature: ```typescript diff --git a/docs/api/js-utils.mergearrays_1.md b/docs/api/js-utils.mergearrays_1.md index 641cce9..233023c 100644 --- a/docs/api/js-utils.mergearrays_1.md +++ b/docs/api/js-utils.mergearrays_1.md @@ -4,6 +4,7 @@ ## mergeArrays() function + Signature: ```typescript diff --git a/docs/api/js-utils.missingkeyerror._constructor_.md b/docs/api/js-utils.missingkeyerror._constructor_.md index 76d4930..d944352 100644 --- a/docs/api/js-utils.missingkeyerror._constructor_.md +++ b/docs/api/js-utils.missingkeyerror._constructor_.md @@ -16,6 +16,6 @@ constructor(msg?: string, ...nested: Array); | Parameter | Type | Description | | --- | --- | --- | -| msg | string | | +| msg | string | (Optional) | | nested | Array<Error> | | diff --git a/docs/api/js-utils.mustcoalesce.md b/docs/api/js-utils.mustcoalesce.md index 8696ae8..6848acd 100644 --- a/docs/api/js-utils.mustcoalesce.md +++ b/docs/api/js-utils.mustcoalesce.md @@ -6,6 +6,7 @@ > Warning: This API is now obsolete. > +> use `mustDefault` instead > Return the first value that is not nil. diff --git a/docs/api/js-utils.mustexist.md b/docs/api/js-utils.mustexist.md index 276f5c4..7b583b3 100644 --- a/docs/api/js-utils.mustexist.md +++ b/docs/api/js-utils.mustexist.md @@ -17,7 +17,7 @@ export declare function mustExist(val: Maybe, err?: string): T; | Parameter | Type | Description | | --- | --- | --- | | val | [Maybe](./js-utils.maybe.md)<T> | | -| err | string | | +| err | string | (Optional) | Returns: diff --git a/docs/api/js-utils.nil.md b/docs/api/js-utils.nil.md index 8b0d5be..8ae386b 100644 --- a/docs/api/js-utils.nil.md +++ b/docs/api/js-utils.nil.md @@ -6,6 +6,7 @@ > Warning: This API is now obsolete. > +> use `None` instead > Old name for None. diff --git a/docs/api/js-utils.normalizemap.md b/docs/api/js-utils.normalizemap.md index 1fbbbfe..85aab06 100644 --- a/docs/api/js-utils.normalizemap.md +++ b/docs/api/js-utils.normalizemap.md @@ -6,6 +6,7 @@ > Warning: This API is now obsolete. > +> the conversion behavior here was not reliable, better to provide your own `T -> string` mapper > Normalize a map-like of values into a dict of lists of strings. diff --git a/docs/api/js-utils.notfounderror._constructor_.md b/docs/api/js-utils.notfounderror._constructor_.md index e899f15..105eea8 100644 --- a/docs/api/js-utils.notfounderror._constructor_.md +++ b/docs/api/js-utils.notfounderror._constructor_.md @@ -16,6 +16,6 @@ constructor(msg?: string, ...nested: Array); | Parameter | Type | Description | | --- | --- | --- | -| msg | string | | +| msg | string | (Optional) | | nested | Array<Error> | | diff --git a/docs/api/js-utils.notimplementederror._constructor_.md b/docs/api/js-utils.notimplementederror._constructor_.md index 26a0cc7..2830d03 100644 --- a/docs/api/js-utils.notimplementederror._constructor_.md +++ b/docs/api/js-utils.notimplementederror._constructor_.md @@ -16,6 +16,6 @@ constructor(msg?: string, ...nested: Array); | Parameter | Type | Description | | --- | --- | --- | -| msg | string | | +| msg | string | (Optional) | | nested | Array<Error> | | diff --git a/docs/api/js-utils.optional.md b/docs/api/js-utils.optional.md index b305748..41c1a32 100644 --- a/docs/api/js-utils.optional.md +++ b/docs/api/js-utils.optional.md @@ -6,6 +6,7 @@ > Warning: This API is now obsolete. > +> use Maybe instead > Old name for Maybe. diff --git a/docs/api/js-utils.signal_reload.md b/docs/api/js-utils.signal_reload.md index ed4b2d7..a034a0f 100644 --- a/docs/api/js-utils.signal_reload.md +++ b/docs/api/js-utils.signal_reload.md @@ -4,6 +4,7 @@ ## SIGNAL\_RELOAD variable + Signature: ```typescript diff --git a/docs/api/js-utils.signal_reset.md b/docs/api/js-utils.signal_reset.md index 810bc3a..9b5e564 100644 --- a/docs/api/js-utils.signal_reset.md +++ b/docs/api/js-utils.signal_reset.md @@ -4,6 +4,7 @@ ## SIGNAL\_RESET variable + Signature: ```typescript diff --git a/docs/api/js-utils.signal_stop.md b/docs/api/js-utils.signal_stop.md index 5624c2d..15e3089 100644 --- a/docs/api/js-utils.signal_stop.md +++ b/docs/api/js-utils.signal_stop.md @@ -4,6 +4,7 @@ ## SIGNAL\_STOP variable + Signature: ```typescript diff --git a/docs/api/js-utils.spylogger.md b/docs/api/js-utils.spylogger.md deleted file mode 100644 index 9d85a41..0000000 --- a/docs/api/js-utils.spylogger.md +++ /dev/null @@ -1,26 +0,0 @@ - - -[Home](./index.md) > [@apextoaster/js-utils](./js-utils.md) > [spyLogger](./js-utils.spylogger.md) - -## spyLogger() function - -Create a spy logger using the provided methods, which returns itself as a child. - - ensure all methods are present by extending null logger - -Signature: - -```typescript -export declare function spyLogger(spies: Partial): Logger; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| spies | Partial<Logger> | | - -Returns: - -Logger - diff --git a/docs/api/js-utils.sum.md b/docs/api/js-utils.sum.md index 4ddac18..2abc2ce 100644 --- a/docs/api/js-utils.sum.md +++ b/docs/api/js-utils.sum.md @@ -6,8 +6,6 @@ Add numbers. - PredicateR2<number, number> - Signature: ```typescript diff --git a/docs/api/js-utils.timeouterror._constructor_.md b/docs/api/js-utils.timeouterror._constructor_.md index ca8328c..8fd953d 100644 --- a/docs/api/js-utils.timeouterror._constructor_.md +++ b/docs/api/js-utils.timeouterror._constructor_.md @@ -16,6 +16,6 @@ constructor(msg?: string, ...nested: Array); | Parameter | Type | Description | | --- | --- | --- | -| msg | string | | +| msg | string | (Optional) | | nested | Array<Error> | | diff --git a/docs/api/js-utils.trim.md b/docs/api/js-utils.trim.md index 9d0a436..ee25127 100644 --- a/docs/api/js-utils.trim.md +++ b/docs/api/js-utils.trim.md @@ -18,7 +18,7 @@ export declare function trim(val: string, max: number, tail?: string): string; | --- | --- | --- | | val | string | | | max | number | | -| tail | string | | +| tail | string | (Optional) | Returns: diff --git a/docs/api/js-utils.waitfor.md b/docs/api/js-utils.waitfor.md index 5414beb..5a27296 100644 --- a/docs/api/js-utils.waitfor.md +++ b/docs/api/js-utils.waitfor.md @@ -6,6 +6,7 @@ > Warning: This API is now obsolete. > +> use `deferUntil` instead > Signature: diff --git a/docs/api/js-utils.waitforchild.md b/docs/api/js-utils.waitforchild.md index fb964e5..dad743b 100644 --- a/docs/api/js-utils.waitforchild.md +++ b/docs/api/js-utils.waitforchild.md @@ -6,6 +6,7 @@ > Warning: This API is now obsolete. > +> there are better libraries for this, like zx > Signature: diff --git a/docs/api/js-utils.writeinput.md b/docs/api/js-utils.writeinput.md index f26808b..3c8bf71 100644 --- a/docs/api/js-utils.writeinput.md +++ b/docs/api/js-utils.writeinput.md @@ -4,6 +4,7 @@ ## writeInput() function + Signature: ```typescript diff --git a/docs/api/js-utils.writevalue.md b/docs/api/js-utils.writevalue.md index ff3c466..fa328d7 100644 --- a/docs/api/js-utils.writevalue.md +++ b/docs/api/js-utils.writevalue.md @@ -6,6 +6,7 @@ > Warning: This API is now obsolete. > +> call `writeInput` directly instead > Signature: diff --git a/docs/js-utils.api.md b/docs/js-utils.api.md new file mode 100644 index 0000000..055eb0d --- /dev/null +++ b/docs/js-utils.api.md @@ -0,0 +1,349 @@ +## API Report File for "@apextoaster/js-utils" + +> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). + +```ts + +/// + +import { BaseError } from 'noicejs'; +import { ChildProcessWithoutNullStreams } from 'child_process'; +import { Logger } from 'noicejs'; +import { spawn } from 'child_process'; +import { Writable } from 'stream'; + +// @public (undocumented) +export type AllowedBufferEncoding = 'ascii' | 'utf-8'; + +// @public +export class ArrayMapper { + constructor(options: ArrayMapperOptions); + map(input: Array): Map>; + // (undocumented) + readonly rest: string; + // (undocumented) + readonly skip: number; + // (undocumented) + readonly take: Array; +} + +// @public (undocumented) +export interface ArrayMapperOptions { + rest: string; + skip: number; + take: Array; +} + +// @public +export class Checklist implements ChecklistOptions { + constructor(options: ChecklistOptions); + check(value: T): boolean; + readonly data: Array; + // (undocumented) + readonly mode: ChecklistMode; +} + +// @public +export enum ChecklistMode { + // (undocumented) + EXCLUDE = "exclude", + // (undocumented) + INCLUDE = "include" +} + +// @public +export interface ChecklistOptions { + // (undocumented) + data: Array; + // (undocumented) + mode: ChecklistMode; +} + +// Warning: (ae-forgotten-export) The symbol "ChildProcessOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +export interface ChildOptions extends ChildProcessOptions { + // (undocumented) + args: Array; + // (undocumented) + command: string; +} + +// @public +export class ChildProcessError extends BaseError { + constructor(msg?: string, ...nested: Array); +} + +// @public (undocumented) +export interface ChildResult { + // (undocumented) + status: number; + // (undocumented) + stderr: string; + // (undocumented) + stdout: string; +} + +// Warning: (ae-forgotten-export) The symbol "ChildStreams" needs to be exported by the entry point index.d.ts +// +// @public @deprecated +export function childResult(child: ChildStreams): Promise; + +// @public (undocumented) +export type ChildSpawner = typeof spawn; + +// @public +export function concat(chunks: Array): Buffer; + +// Warning: (ae-forgotten-export) The symbol "Reflectable" needs to be exported by the entry point index.d.ts +// +// @public +export function constructorName(val: Reflectable): string; + +// @public +export function defaultWhen(condition: boolean, ...items: Array): TVal; + +// @public +export function defer(ms: number): Promise; + +// Warning: (ae-forgotten-export) The symbol "PredicateC0" needs to be exported by the entry point index.d.ts +// +// @public +export function deferUntil(cb: PredicateC0, step: number, max: number): Promise; + +// @public +export function deferValue(ms: number, val: T): Promise; + +// @public (undocumented) +export interface Dict { + // (undocumented) + [key: string]: TVal; +} + +// @public +export function doesExist(val: Maybe): val is T; + +// @public +export function encode(chunks: Array, encoding: AllowedBufferEncoding): string; + +// @public @deprecated (undocumented) +export function ensureArray(val: Maybe>): Array; + +// @public (undocumented) +export function ensureArray(val: Maybe>): ReadonlyArray; + +// @public +export function entriesOf(map: Maybe>): Array<[string, TVal]>; + +// @public +export function filterZip(cb: (a: T1) => boolean, l1: Array): Array; + +// @public (undocumented) +export function filterZip(cb: (a: T1, b: T2) => boolean, l1: Array, l2: Array): [Array, Array]; + +// @public (undocumented) +export function filterZip(cb: (a: T1, b: T2) => boolean, l1: Array, l2: Array, l3: Array): [Array, Array, Array]; + +// @public (undocumented) +export function filterZip(cb: (a: T1, b: T2) => boolean, l1: Array, l2: Array, l3: Array, l4: Array): [Array, Array, Array, Array]; + +// @public +export function getConstructor(val: Reflectable): Function; + +// @public +export function getHead(map: Map>, key: TKey): TVal; + +// @public +export function getHeadOrDefault(map: Map>>, key: TKey, defaultValue: TVal): TVal; + +// Warning: (ae-forgotten-export) The symbol "Method" needs to be exported by the entry point index.d.ts +// +// @public +export function getMethods(value: TValue): Set>; + +// @public +export function getOrDefault(map: Map, key: TKey, defaultValue: TVal): TVal; + +// @public +export function getTestLogger(verbose?: boolean): Logger; + +// @public +export function hasItems(val: Maybe>): val is Array; + +// @public (undocumented) +export function hasItems(val: Maybe>): val is ReadonlyArray; + +// @public +export class InvalidArgumentError extends BaseError { + constructor(msg?: string, ...nested: Array); +} + +// @public +export function isArray(list: TVal | Array): list is Array; + +// @public +export function isArray(list: TVal | ReadonlyArray): list is ReadonlyArray; + +// Warning: (ae-internal-missing-underscore) The name "isDebug" should be prefixed with an underscore because the declaration is marked as @internal +// +// @internal +export function isDebug(): boolean; + +// @public +export function isEmpty(val: Maybe | ReadonlyArray>): boolean; + +// @public @deprecated +export function isNil(val: Maybe): val is Nil; + +// @public +export function isNone(val: Maybe): val is None; + +// @public +export function isSome(val: Maybe): val is T; + +// @public +export function leftPad(val: string, min?: number, fill?: string): string; + +// @public +export function lengthOf(val: Maybe): number; + +// @public +export function makeDict(map: Maybe>): Dict; + +// @public +export function makeMap(val: Maybe>): Map; + +// @public +export type MapLike = Map | Dict; + +// @public +export type Maybe = T | None; + +// @public +export function mergeArray(...parts: Array>): Array; + +// @public (undocumented) +export function mergeArray(...parts: ReadonlyArray>): ReadonlyArray; + +// @public @deprecated (undocumented) +export function mergeArrays(...parts: Array>): Array; + +// @public (undocumented) +export function mergeArrays(...parts: ReadonlyArray>): ReadonlyArray; + +// @public +export function mergeMap(target: Map, source: Map | ReadonlyArray<[TKey, TVal]>): Map; + +// @public +export class MissingKeyError extends NotFoundError { + constructor(msg?: string, ...nested: Array); +} + +// @public @deprecated +export function mustCoalesce(...values: Array>): T; + +// @public +export function mustDefault(...values: Array>): T; + +// @public +export function mustExist(val: Maybe, err?: string): T; + +// Warning: (ae-forgotten-export) The symbol "PredicateC1" needs to be exported by the entry point index.d.ts +// +// @public +export function mustFind(list: Array>, predicate: PredicateC1): TVal; + +// @public +export function mustGet(map: Map, key: TKey): TVal; + +// @public @deprecated +export type Nil = None; + +// @public +export type None = null | undefined; + +// @public @deprecated +export function normalizeMap(map: MapLike): Dict>; + +// @public +export class NotFoundError extends BaseError { + constructor(msg?: string, ...nested: Array); +} + +// @public +export class NotImplementedError extends BaseError { + constructor(msg?: string, ...nested: Array); +} + +// @public @deprecated +export type Optional = Maybe; + +// Warning: (ae-forgotten-export) The symbol "NameValuePair" needs to be exported by the entry point index.d.ts +// +// @public +export function pairsToMap(pairs: ReadonlyArray>): Map; + +// @public +export function pushMergeMap(...args: Array>>): Map>; + +// @public +export function pushMergeMap(...args: ReadonlyArray>>): Map>; + +// @public +export function removeNone(list: ArrayLike>): Array; + +// @public +export function setOrPush(map: Map>, key: TKey, val: TVal | ReadonlyArray): Map>; + +// @public +export function signal(...signals: Array): Promise; + +// @public (undocumented) +export const SIGNAL_RELOAD: NodeJS.Signals; + +// @public (undocumented) +export const SIGNAL_RESET: NodeJS.Signals; + +// @public (undocumented) +export const SIGNAL_STOP: NodeJS.Signals; + +// Warning: (ae-internal-missing-underscore) The name "spyLogger" should be prefixed with an underscore because the declaration is marked as @internal +// +// @internal +export function spyLogger(spies: Partial): Logger; + +// @public +export function sum(a: number, b: number): number; + +// @public +export function timeout(ms: number, inner: Promise): Promise; + +// @public +export class TimeoutError extends BaseError { + constructor(msg?: string, ...nested: Array); +} + +// @public +export function toArray(val: Maybe>): Array; + +// @public +export function toArray(val: Maybe>): ReadonlyArray; + +// @public +export function trim(val: string, max: number, tail?: string): string; + +// @public @deprecated (undocumented) +export function waitFor(cb: PredicateC0, step: number, tries: number): Promise; + +// @public @deprecated (undocumented) +export function waitForChild(child: ChildStreams): Promise; + +// @public (undocumented) +export function writeInput(stream: Writable, value: string): Promise; + +// @public @deprecated (undocumented) +export function writeValue(stream: Writable, value: string): Promise; + +// (No @packageDocumentation comment for this package) + +``` diff --git a/src/Array.ts b/src/Array.ts index 338e86f..93316ff 100644 --- a/src/Array.ts +++ b/src/Array.ts @@ -6,6 +6,9 @@ import { doesExist, isNone, Maybe } from './Maybe.js'; * @public */ export function mergeArray(...parts: Array>): Array; +/** + * @public + */ export function mergeArray(...parts: ReadonlyArray>): ReadonlyArray; export function mergeArray(...parts: ReadonlyArray>): ReadonlyArray { const out = []; @@ -26,6 +29,9 @@ export function mergeArray(...parts: ReadonlyArray(...parts: Array>): Array; +/** + * @public + */ export function mergeArrays(...parts: ReadonlyArray>): ReadonlyArray; export function mergeArrays(...parts: ReadonlyArray>): ReadonlyArray { return mergeArray(...parts); @@ -42,6 +48,9 @@ export function mergeArrays(...parts: ReadonlyArray(val: Maybe>): val is Array; +/** + * @public + */ export function hasItems(val: Maybe>): val is ReadonlyArray; export function hasItems(val: Maybe>): val is ReadonlyArray { return isArray(val) && lengthOf(val) > 0; @@ -52,6 +61,9 @@ export function hasItems(val: Maybe>): val is ReadonlyArray< * @public */ export function ensureArray(val: Maybe>): Array; +/** + * @public + */ export function ensureArray(val: Maybe>): ReadonlyArray; export function ensureArray(val: Maybe>): ReadonlyArray { return toArray(val); @@ -112,8 +124,17 @@ export function isEmpty(val: Maybe | ReadonlyArray>): bo * @public */ export function filterZip(cb: (a: T1) => boolean, l1: Array): Array; +/** + * @public + */ export function filterZip(cb: (a: T1, b: T2) => boolean, l1: Array, l2: Array): [Array, Array]; +/** + * @public + */ export function filterZip(cb: (a: T1, b: T2) => boolean, l1: Array, l2: Array, l3: Array): [Array, Array, Array]; +/** + * @public + */ export function filterZip(cb: (a: T1, b: T2) => boolean, l1: Array, l2: Array, l3: Array, l4: Array): [Array, Array, Array, Array]; export function filterZip(cb: (...d: Array) => boolean, ...l: Array>): Array> { const results = []; diff --git a/src/Logger.ts b/src/Logger.ts index 467f3f4..76089e5 100644 --- a/src/Logger.ts +++ b/src/Logger.ts @@ -19,9 +19,9 @@ export function getTestLogger(verbose = false): Logger { * Create a spy logger using the provided methods, which returns itself as a child. * * @internal - * @todo ensure all methods are present by extending null logger */ export function spyLogger(spies: Partial): Logger { + // TODO: ensure all methods are present by extending null logger const logger = { ...spies, child: () => logger, diff --git a/src/Math.ts b/src/Math.ts index 7c8c8aa..dd7f767 100644 --- a/src/Math.ts +++ b/src/Math.ts @@ -1,7 +1,6 @@ /** * Add numbers. * - * @implements PredicateR2 * @public */ export function sum(a: number, b: number): number {