ssube
/
js-utils
1
0
Fork 0
Code

fix(docs): describe exports and mark with release status

This commit is contained in:
ssube 2020-03-31 08:49:18 -05:00
parent 6d7e72e1a8
commit e4958ee6f0
Signed by: ssube
GPG Key ID: 3EED7B957D362AF1
46 changed files with 257 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/api/js-utils.arraymapper.map.md
View File

@ -4,6 +4,8 @@
## ArrayMapper.map() method
Transform the input list into a map, extracting elements using the mapper's options.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.arraymapper.md
View File

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

2
docs/api/js-utils.asynctracker.dump.md
View File

@ -4,6 +4,8 @@
## AsyncTracker.dump() method
Print a listing of all tracked resources. When debug mode is enabled (DEBUG=TRUE), include stack traces.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.asynctracker.getstack.md
View File

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

4
docs/api/js-utils.asynctracker.md
View File

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

2
docs/api/js-utils.checklist.data.md
View File

@ -4,6 +4,8 @@
## Checklist.data property
TODO: switch to Set
<b>Signature:</b>
```typescript

4
docs/api/js-utils.checklist.md
View File

@ -4,6 +4,8 @@
## Checklist class
Check whether items are included or not (blacklist or whitelist, depending on `mode`<!-- -->).
<b>Signature:</b>
```typescript
@ -20,7 +22,7 @@ export declare class Checklist<T> implements ChecklistOptions<T>
| Property | Modifiers | Type | Description |
| --- | --- | --- | --- |
| [data](./js-utils.checklist.data.md) | | <code>Array&lt;T&gt;</code> | |
| [data](./js-utils.checklist.data.md) | | <code>Array&lt;T&gt;</code> | TODO: switch to Set |
| [mode](./js-utils.checklist.mode.md) | | <code>ChecklistMode</code> | |
## Methods

2
docs/api/js-utils.childprocesserror.md
View File

@ -4,6 +4,8 @@
## ChildProcessError class
Error indicating that a child process exited with an error status.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.concat.md
View File

@ -4,6 +4,8 @@
## concat() function
Concatenate a list of buffers.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.constructorname.md
View File

@ -4,6 +4,8 @@
## constructorName() function
Get the constructor name from an instance.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.defaultwhen.md
View File

@ -4,6 +4,8 @@
## defaultWhen() function
Return the first element when `condition` is true and the second element when `condition` is false.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.encode.md
View File

@ -4,6 +4,8 @@
## encode() function
Concatenate then encode a list of buffers.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.getconstructor.md
View File

@ -4,6 +4,8 @@
## getConstructor() function
Get the constructor from an instance.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.getmethods.md
View File

@ -4,6 +4,8 @@
## getMethods() function
Get the methods from an instance and its prototypes.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.gettestlogger.md
View File

@ -4,6 +4,8 @@
## getTestLogger() function
Get a test logger. Returns a null logger unless `verbose` is true or run under debug mode.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.invalidargumenterror.md
View File

@ -4,6 +4,8 @@
## InvalidArgumentError class
Error indicating that an invalid argument was passed to a function call.
<b>Signature:</b>
```typescript

4
docs/api/js-utils.isdebug.md
View File

@ -4,6 +4,10 @@
## isDebug() function
Test if DEBUG mode is set.
TODO: check variable value as well
<b>Signature:</b>
```typescript

42
docs/api/js-utils.md
View File

@ -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 <code>skip</code> initial items and gather remaining items into a <code>rest</code> 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 <code>mode</code>). |
| [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 <code>condition</code> is true and the second element when <code>condition</code> 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 <code>verbose</code> 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 <code>source</code> map into the <code>target</code> 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) | <b><i>(BETA)</i></b> 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 <code>path</code>. |
| [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 <code>path</code>. |
| [writeValue(stream, value)](./js-utils.writevalue.md) | |
## Interfaces

4
docs/api/js-utils.missingkeyerror.md
View File

@ -4,10 +4,12 @@
## MissingKeyError class
Error indicating that a required key did not exist in a map-like.
<b>Signature:</b>
```typescript
export declare class MissingKeyError extends BaseError
export declare class MissingKeyError extends NotFoundError
```
## Constructors

2
docs/api/js-utils.mustcoalesce.md
View File

@ -6,7 +6,7 @@
Return the first value that is not nil.
TODO: rename to mustDefault
@<!-- -->todo: rename to mustDefault
<b>Signature:</b>

5
docs/api/js-utils.normalizemap.md
View File

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

2
docs/api/js-utils.notfounderror.md
View File

@ -4,6 +4,8 @@
## NotFoundError class
Error indicating that some value was not found.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.notimplementederror.md
View File

@ -4,6 +4,8 @@
## NotImplementedError class
Error indicating that a function has not been implemented yet.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.removepid.md
View File

@ -4,6 +4,8 @@
## removePid() function
Remove the file at the given `path`<!-- -->.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.spylogger.md
View File

@ -4,6 +4,8 @@
## spyLogger() function
Create a spy logger using the provided methods, which returns itself as a child.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.timeouterror.md
View File

@ -4,6 +4,8 @@
## TimeoutError class
Error indicating that a promise timed out.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.waitforchild.md
View File

@ -4,6 +4,8 @@
## waitForChild() function
Wait for a child process to exit, collecting output, errors, and exit status.
<b>Signature:</b>
```typescript

2
docs/api/js-utils.writepid.md
View File

@ -4,6 +4,8 @@
## writePid() function
Write the current process ID to a file at the given `path`<!-- -->.
<b>Signature:</b>
```typescript

7
src/ArrayMapper.ts
View File

@ -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<string>): Map<string, Array<string>> {
const result = new Map();
input.forEach((it, idx) => {

7
src/Async.ts
View File

@ -3,6 +3,7 @@ import { PredicateC0 } from './utils';
/**
* Resolve after a set amount of time.
* @public
*/
export function defer<T = undefined>(ms: number, val?: T): Promise<T> {
return new Promise((res, rej) => {
@ -14,6 +15,7 @@ export function defer<T = undefined>(ms: number, val?: T): Promise<T> {
/**
* Reject after a set amount of time if the original promise has not yet resolved.
* @public
*/
export function timeout<T>(ms: number, oper: Promise<T>): Promise<T> {
const limit = new Promise<T>((res, rej) => {
@ -25,6 +27,11 @@ export function timeout<T>(ms: number, oper: Promise<T>): Promise<T> {
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<void> {
let accum = 0;
while (accum < count) {

10
src/AsyncTracker.ts
View File

@ -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<StackFilter>;
@ -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`);

10
src/Buffer.ts
View File

@ -1,8 +1,18 @@
/**
* Concatenate a list of buffers.
*
* @public
*/
export function concat(chunks: Array<Buffer>): 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<Buffer>, encoding: string): string {
if (chunks.length === 0) {
return '';

6
src/Checklist.ts
View File

@ -8,7 +8,13 @@ export interface ChecklistOptions<T> {
mode: ChecklistMode;
}
/**
* Check whether items are included or not (blacklist or whitelist, depending on `mode`).
*/
export class Checklist<T> implements ChecklistOptions<T> {
/**
* TODO: switch to Set
*/
public readonly data: Array<T>;
public readonly mode: ChecklistMode;

5
src/Child.ts
View File

@ -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<ChildResult> {
return new Promise((res, rej) => {
const stderr: Array<Buffer> = [];

5
src/Env.ts
View File

@ -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);
}

6
src/Logger.ts
View File

@ -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>): Logger {
const logger = {
...spies,

29
src/Map.ts
View File

@ -9,11 +9,15 @@ export interface Dict<TVal> {
/**
* A `Map` or dictionary object with string keys and `TVal` values.
*
* @public
*/
export type MapLike<TVal> = Map<string, TVal> | Dict<TVal>;
/**
* Get an element from a Map and guard against nil values.
*
* @public
*/
export function mustGet<TKey, TVal>(map: Map<TKey, TVal>, key: TKey): TVal {
const val = map.get(key);
@ -22,6 +26,8 @@ export function mustGet<TKey, TVal>(map: Map<TKey, TVal>, key: TKey): TVal {
/**
* Get a map key or default value when the key does not exist or is nil.
*
* @public
*/
export function getOrDefault<TKey, TVal>(map: Map<TKey, TVal>, key: TKey, defaultValue: TVal): TVal {
if (map.has(key)) {
@ -36,6 +42,8 @@ export function getOrDefault<TKey, TVal>(map: Map<TKey, TVal>, key: TKey, defaul
/**
* Get the first element from the specified key within a map of lists.
*
* @public
*/
export function getHead<TKey, TVal>(map: Map<TKey, Array<TVal>>, key: TKey): TVal {
const value = map.get(key);
@ -48,6 +56,8 @@ export function getHead<TKey, TVal>(map: Map<TKey, Array<TVal>>, 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<TKey, TVal>(map: Map<TKey, Array<Optional<TVal>>>, key: TKey, defaultValue: TVal): TVal {
if (!map.has(key)) {
@ -72,6 +82,8 @@ export function getHeadOrDefault<TKey, TVal>(map: Map<TKey, Array<Optional<TVal>
* @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<TKey, TVal>(map: Map<TKey, Array<TVal>>, key: TKey, val: TVal | Array<TVal>) {
const prev = map.get(key);
@ -88,6 +100,8 @@ export function setOrPush<TKey, TVal>(map: Map<TKey, Array<TVal>>, key: TKey, va
/**
* Merge the `source` map into the `target` map, replacing keys that already exist.
*
* @public
*/
export function mergeMap<TKey, TVal>(target: Map<TKey, TVal>, source: Map<TKey, TVal> | Array<[TKey, TVal]>) {
for (const [k, v] of source) {
@ -99,6 +113,8 @@ export function mergeMap<TKey, TVal>(target: Map<TKey, TVal>, source: Map<TKey,
/**
* Merge the provided maps into a new map, merging keys that already exist by pushing new items.
*
* @public
*/
export function pushMergeMap<TKey, TVal>(...args: Array<Map<TKey, TVal | Array<TVal>>>): Map<TKey, Array<TVal>> {
const out = new Map();
@ -112,6 +128,8 @@ export function pushMergeMap<TKey, TVal>(...args: Array<Map<TKey, TVal | Array<T
/**
* Clone a map or map-like object into a new map.
*
* @public
*/
export function makeMap<TVal>(val: Optional<MapLike<TVal>>): Map<string, TVal> {
// nil: empty map
@ -130,6 +148,8 @@ export function makeMap<TVal>(val: Optional<MapLike<TVal>>): Map<string, TVal> {
/**
* Turns a map or dict into a dict
*
* @public
*/
export function makeDict<TVal>(map: Optional<MapLike<TVal>>): Dict<TVal> {
if (isNil(map)) {
@ -154,6 +174,8 @@ export interface NameValuePair<TVal> {
/**
* Turns a list of name-value pairs into a map.
*
* @public
*/
export function pairsToMap<TVal>(pairs: Array<NameValuePair<TVal>>): Map<string, TVal> {
const map = new Map();
@ -176,6 +198,11 @@ export function dictValuesToArrays<TVal>(map: MapLike<TVal>): Dict<Array<TVal>>
return data;
}
/**
* Normalize a map-like of values into a dict of lists of strings.
*
* @beta
*/
export function normalizeMap(map: MapLike<unknown>): Dict<Array<string>> {
const data: Dict<Array<string>> = {};
for (const [key, value] of makeMap(map)) {
@ -193,6 +220,8 @@ export function normalizeMap(map: MapLike<unknown>): Dict<Array<string>> {
/**
* Get entries of a map-like.
*
* @public
*/
export function entriesOf<TVal>(map: Optional<MapLike<TVal>>): Array<[string, TVal]> {
if (map instanceof Map) {

8
src/PidFile.ts
View File

@ -5,6 +5,11 @@ import { doesExist, Optional } from './utils';
type OptionalErrno = Optional<NodeJS.ErrnoException>;
/**
* Write the current process ID to a file at the given `path`.
*
* @public
*/
export async function writePid(path: string): Promise<void> {
return new Promise((res, rej) => {
open(path, 'wx', (openErr: OptionalErrno, fd: number) => {
@ -23,6 +28,9 @@ export async function writePid(path: string): Promise<void> {
});
}
/**
* Remove the file at the given `path`.
*/
export async function removePid(path: string): Promise<void> {
return new Promise((res, rej) => {
unlink(path, (err: OptionalErrno) => {

15
src/Reflect.ts
View File

@ -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<TValue extends object>(value: TValue): Set<Function> {
const methods = new Set<Function>();
@ -31,6 +41,11 @@ export function getMethods<TValue extends object>(value: TValue): Set<Function>
return methods;
}
/**
* Get the constructor name from an instance.
*
* @public
*/
export function constructorName(val: object) {
return getConstructor(Reflect.getPrototypeOf(val)).name;
}

5
src/error/ChildProcessError.ts
View File

@ -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<Error>) {
super(msg, ...nested);

5
src/error/InvalidArgumentError.ts
View File

@ -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<Error>) {
super(msg, ...nested);

9
src/error/MissingKeyError.ts
View File

@ -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<Error>) {
super(msg, ...nested);
}

5
src/error/NotFoundError.ts
View File

@ -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<Error>) {
super(msg, ...nested);

5
src/error/NotImplementedError.ts
View File

@ -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<Error>) {
super(msg, ...nested);

5
src/error/TimeoutError.ts
View File

@ -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<Error>) {
super(msg, ...nested);

38
src/utils/index.ts
View File

@ -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> = T | Nil;
/**
* Comparison predicate for arity 0 - assert?
*
* @beta
*/
export type PredicateC0 = () => boolean;
/**
* Comparison predicate for arity 1 - filter.
*
* @beta
*/
export type PredicateC1<TVal> = (val: TVal, idx: number, list: Array<TVal>) => boolean;
/**
* Comparison predicate for arity 2 - sort.
*
* @beta
*/
export type PredicateC2<TVal> = (pval: TVal, nval: TVal, idx: number, list: Array<TVal>) => SortOrder;
/**
* Transform predicate for arity 0 - constructor.
*
* @beta
*/
export type PredicateR0<TVal> = () => TVal;
/**
* Transform predicate for arity 1 - map.
*
* @beta
*/
export type PredicateR1<TVal> = (val: TVal, idx: number, list: Array<TVal>) => TVal;
/**
* Transform predicate for arity 2 - reduce.
*
* @beta
*/
export type PredicateR2<TVal> = (pval: TVal, nval: TVal, idx: number, list: Array<TVal>) => TVal;
/**
* Check if a value is nil.
*
* @public
*/
/* eslint-disable-next-line @typescript-eslint/ban-types */
export function isNil<T>(val: Optional<T>): val is Nil {
@ -60,6 +78,8 @@ export function isNil<T>(val: Optional<T>): 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<TVal>(condition: boolean, ...items: Array<TVal>): TVal {
if (condition) {
return items[0];
@ -83,6 +108,8 @@ export function defaultWhen<TVal>(condition: boolean, ...items: Array<TVal>): TV
/**
* Remove any null or undefined items from the list.
*
* @public
*/
export function filterNil<TItem>(list: ArrayLike<Optional<TItem>>): Array<TItem> {
return Array.from(list).filter(doesExist);
@ -90,6 +117,8 @@ export function filterNil<TItem>(list: ArrayLike<Optional<TItem>>): Array<TItem>
/**
* Merge arguments, which may or may not be arrays, into one return that is definitely an array.
*
* @public
*/
export function mergeList<TItem>(...parts: Array<TItem | Array<TItem>>): Array<TItem> {
const out = [];
@ -107,6 +136,8 @@ export function mergeList<TItem>(...parts: Array<TItem | Array<TItem>>): Array<T
/**
* Find a value matching the given predicate or throw.
*
* @public
*/
export function mustFind<TVal>(list: Array<Optional<TVal>>, predicate: PredicateC1<TVal>): TVal {
const val = filterNil(list).find(predicate);
@ -115,6 +146,8 @@ export function mustFind<TVal>(list: Array<Optional<TVal>>, predicate: Predicate
/**
* Check if a variable is not nil.
*
* @public
*/
export function doesExist<T>(val: Optional<T>): val is T {
return !isNil(val);
@ -125,6 +158,8 @@ export function doesExist<T>(val: Optional<T>): val is T {
*
* @throws NotFoundError
* @returns val
*
* @public
*/
export function mustExist<T>(val: Optional<T>): T {
if (isNil(val)) {
@ -137,7 +172,8 @@ export function mustExist<T>(val: Optional<T>): T {
/**
* Return the first value that is not nil.
*
* TODO: rename to mustDefault
* @public
* @todo: rename to mustDefault
*/
export function mustCoalesce<T>(...values: Array<Optional<T>>): T {
return mustFind(values, doesExist);