ssube
/
js-utils
1
0
Fork 0
Code

continue name fixes, list methods in readme

This commit is contained in:
ssube 2021-08-07 19:34:19 -05:00
parent 04de2b2bd5
commit 4ae509ce0c
Signed by: ssube
GPG Key ID: 3EED7B957D362AF1
20 changed files with 192 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
README.md
View File

@ -63,55 +63,79 @@ The library is bundled and has no dependencies.
## Features
- array mapper
- map elements to keys by order
- skip initial, gather remaining
- async
- defer
- promise timeout
- wait for predicate
- async tracker
- track and log leaking async resources for tests
- buffer
- checklist
- include/exclude mode (whitelist/blacklist)
- child process
- wait for exit and gather output
- write and flush
- env
- check `DEBUG`
- list
- concat lists
- logger
- get test logger (null or console depending on `DEBUG`)
- map
- must get (assertion)
- get or default
- get head from list value
- get head or default
- set or push to key
- merge maps
- push-merge maps
- convert dict to map and vice versa
- normalize map values to lists
- create map from name-value pairs
- maybe
- is nil test (negative nil test)
- count array or maybe
- filter nil from list
- must find (assertion)
- does exist (positive nil test)
- must exist (assertion)
- must default (assertion)
- pid file
- write pid file
- delete pid file
- reflect
- get constructor name
- get methods from prototype chain
- signals
- wait for OS signal
- string
- left pad (please don't import just for this)
- trim with suffix
Features utilities and helpers for:
- Array
- assertions/guards:
- `hasItems`
- `isArray` for both `Array`/`ReadonlyArray`
- `isEmpty`
- `lengthOf`
- conversion
- `filterZip`
- `toArray`
- Array Mapper
- array-to-map converter, reduces an array of values to a map, using an array of keys
- Async
- timed promises
- `defer`/`deferValue`
- `deferUntil`
- `timeout`
- Buffer
- concatenation
- `concat`
- `encode`
- Checklist
- allow/deny list
- Child Process
- `childResult`
- `writeInput`
- Env Vars
- `isDebug`
- Logger
- test logging helpers
- Map
- types
- `MapLike`
- assertions/guards:
- `mustGet`
- null-safe helpers
- `getOrDefault`
- helpers for `Map<K, Array<V>>`
- `getHead`/`getHeadOrDefault`
- `setOrPush`
- concat/merge
- `mergeMap`
- `pushMergeMap`
- conversion
- `entriesOf`
- `makeDict`
- `makeMap`
- `pairsToMap`
- Math
- predicates for functional methods
- `sum`
- Maybe
- types
- `Maybe`
- `None`
- assertions/guards
- `doesExist`
- `mustExist`
- `mustDefault`
- `mustFind`
- `removeNone`
- null-safe helpers
- `isNone`
- `isSome`
- Predicate
- types for functional methods
- Reflect
- `getConstructor`
- `getMethods`
- Signal
- wait for OS signal
- `signal`
- String
- `leftPad`
- `trim` with suffix

30
docs/api/js-utils.deferuntil.md Normal file
View File

@ -0,0 +1,30 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [@apextoaster/js-utils](./js-utils.md) &gt; [deferUntil](./js-utils.deferuntil.md)
## deferUntil() function
Reject after a set number of attempts if the given predicate does not return true.
<b>Signature:</b>
```typescript
export declare function deferUntil(cb: PredicateC0, step: number, tries: number): Promise<void>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| cb | PredicateC0 | |
| step | number | |
| tries | number | |
<b>Returns:</b>
Promise&lt;void&gt;
## Exceptions
TimeoutError

11
docs/api/js-utils.externalmodule.data.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [@apextoaster/js-utils](./js-utils.md) &gt; [ExternalModule](./js-utils.externalmodule.md) &gt; [data](./js-utils.externalmodule.data.md)
## ExternalModule.data property
<b>Signature:</b>
```typescript
data?: unknown;
```

11
docs/api/js-utils.externalmodule.export.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [@apextoaster/js-utils](./js-utils.md) &gt; [ExternalModule](./js-utils.externalmodule.md) &gt; [export](./js-utils.externalmodule.export.md)
## ExternalModule.export property
<b>Signature:</b>
```typescript
export: string;
```

20
docs/api/js-utils.externalmodule.md
View File

@ -1,20 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [@apextoaster/js-utils](./js-utils.md) &gt; [ExternalModule](./js-utils.externalmodule.md)
## ExternalModule interface
<b>Signature:</b>
```typescript
export interface ExternalModule
```
## Properties
| Property | Type | Description |
| --- | --- | --- |
| [data?](./js-utils.externalmodule.data.md) | unknown | <i>(Optional)</i> |
| [export](./js-utils.externalmodule.export.md) | string | |
| [require](./js-utils.externalmodule.require.md) | string | |

11
docs/api/js-utils.externalmodule.require.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [@apextoaster/js-utils](./js-utils.md) &gt; [ExternalModule](./js-utils.externalmodule.md) &gt; [require](./js-utils.externalmodule.require.md)
## ExternalModule.require property
<b>Signature:</b>
```typescript
require: string;
```

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

@ -27,10 +27,12 @@
| Function | Description |
| --- | --- |
| [childResult(child)](./js-utils.childresult.md) | Wait for a child process to exit, collecting output, errors, and exit status. |
| [concat(chunks)](./js-utils.concat.md) | Concatenate a list of buffers. |
| [constructorName(val)](./js-utils.constructorname.md) | Get the constructor name from an instance. |
| [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)](./js-utils.defer.md) | Resolve after a set amount of time. |
| [deferUntil(cb, step, tries)](./js-utils.deferuntil.md) | Reject after a set number of attempts if the given predicate does not return true. |
| [deferValue(ms, val)](./js-utils.defervalue.md) | |
| [doesExist(val)](./js-utils.doesexist.md) | Check if a variable is some <code>T</code>. |
| [encode(chunks, encoding)](./js-utils.encode.md) | Concatenate then encode a list of buffers. |
@ -77,14 +79,15 @@
| [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) | |
| [spyLogger(spies)](./js-utils.spylogger.md) | Create a spy logger using the provided methods, which returns itself as a child. |
| [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, oper)](./js-utils.timeout.md) | Reject after a set amount of time if the original promise has not yet resolved. |
| [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) | |
| [toArray(val)](./js-utils.toarray_1.md) | |
| [trim(val, max, tail)](./js-utils.trim.md) | |
| [waitFor(cb, step, count)](./js-utils.waitfor.md) | Reject after a set number of attempts if the given predicate does not return true. |
| [waitForChild(child)](./js-utils.waitforchild.md) | Wait for a child process to exit, collecting output, errors, and exit status. |
| [waitFor(cb, step, tries)](./js-utils.waitfor.md) | |
| [waitForChild(child)](./js-utils.waitforchild.md) | |
| [writeInput(stream, value)](./js-utils.writeinput.md) | |
| [writeValue(stream, value)](./js-utils.writevalue.md) | |
## Interfaces
@ -96,7 +99,6 @@
| [ChildOptions](./js-utils.childoptions.md) | |
| [ChildResult](./js-utils.childresult.md) | |
| [Dict](./js-utils.dict.md) | |
| [ExternalModule](./js-utils.externalmodule.md) | |
## Variables
@ -114,7 +116,6 @@
| [ChildSpawner](./js-utils.childspawner.md) | |
| [MapLike](./js-utils.maplike.md) | A <code>Map</code> or dictionary object with string keys and <code>TVal</code> values. |
| [Maybe](./js-utils.maybe.md) | Value that may be nil. |
| [ModuleCtor](./js-utils.modulector.md) | |
| [Nil](./js-utils.nil.md) | Old name for None. |
| [None](./js-utils.none.md) | Unset value. |
| [Optional](./js-utils.optional.md) | Old name for Maybe. |

11
docs/api/js-utils.modulector.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [@apextoaster/js-utils](./js-utils.md) &gt; [ModuleCtor](./js-utils.modulector.md)
## ModuleCtor type
<b>Signature:</b>
```typescript
export declare type ModuleCtor = new (data: unknown) => Module;
```

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

@ -6,6 +6,8 @@
Create a spy logger using the provided methods, which returns itself as a child.
ensure all methods are present by extending null logger
<b>Signature:</b>
```typescript

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

@ -9,7 +9,7 @@ Reject after a set amount of time if the original promise has not yet resolved.
<b>Signature:</b>
```typescript
export declare function timeout<T>(ms: number, oper: Promise<T>): Promise<T>;
export declare function timeout<T>(ms: number, inner: Promise<T>): Promise<T>;
```
## Parameters
@ -17,7 +17,7 @@ export declare function timeout<T>(ms: number, oper: Promise<T>): Promise<T>;
| Parameter | Type | Description |
| --- | --- | --- |
| ms | number | |
| oper | Promise&lt;T&gt; | |
| inner | Promise&lt;T&gt; | |
<b>Returns:</b>

12
docs/api/js-utils.waitfor.md
View File

@ -4,12 +4,14 @@
## waitFor() function
Reject after a set number of attempts if the given predicate does not return true.
> Warning: This API is now obsolete.
>
>
<b>Signature:</b>
```typescript
export declare function waitFor(cb: PredicateC0, step: number, count: number): Promise<void>;
export declare function waitFor(cb: PredicateC0, step: number, tries: number): Promise<void>;
```
## Parameters
@ -18,13 +20,9 @@ export declare function waitFor(cb: PredicateC0, step: number, count: number): P
| --- | --- | --- |
| cb | PredicateC0 | |
| step | number | |
| count | number | |
| tries | number | |
<b>Returns:</b>
Promise&lt;void&gt;
## Exceptions
TimeoutError

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

@ -4,7 +4,9 @@
## waitForChild() function
Wait for a child process to exit, collecting output, errors, and exit status.
> Warning: This API is now obsolete.
>
>
<b>Signature:</b>

23
docs/api/js-utils.writeinput.md Normal file
View File

@ -0,0 +1,23 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [@apextoaster/js-utils](./js-utils.md) &gt; [writeInput](./js-utils.writeinput.md)
## writeInput() function
<b>Signature:</b>
```typescript
export declare function writeInput(stream: Writable, value: string): Promise<boolean>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| stream | Writable | |
| value | string | |
<b>Returns:</b>
Promise&lt;boolean&gt;

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

@ -4,6 +4,10 @@
## writeValue() function
> Warning: This API is now obsolete.
>
>
<b>Signature:</b>
```typescript

20
src/Async.ts
View File

@ -25,14 +25,14 @@ export function deferValue<T>(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> {
export function timeout<T>(ms: number, inner: Promise<T>): Promise<T> {
const limit = new Promise<T>((_res, rej) => {
setTimeout(() => {
rej(new TimeoutError());
}, ms);
});
return Promise.race([limit, oper]);
return Promise.race([limit, inner]);
}
/**
@ -40,15 +40,23 @@ export function timeout<T>(ms: number, oper: Promise<T>): Promise<T> {
* @public
* @throws TimeoutError
*/
export async function waitFor(cb: PredicateC0, step: number, count: number): Promise<void> {
let accum = 0;
while (accum < count) {
export async function deferUntil(cb: PredicateC0, step: number, tries: number): Promise<void> {
let count = 0;
while (count < tries) {
await defer(step);
if (cb()) {
return;
}
accum += 1;
count += 1;
}
throw new TimeoutError();
}
/**
* @public
* @deprecated
*/
export async function waitFor(cb: PredicateC0, step: number, tries: number): Promise<void> {
return deferUntil(cb, step, tries);
}

20
src/Child.ts
View File

@ -37,7 +37,7 @@ const CHILD_OUTPUT = 'child process emitted error output';
*
* @public
*/
export function waitForChild(child: ChildStreams): Promise<ChildResult> {
export function childResult(child: ChildStreams): Promise<ChildResult> {
return new Promise((res, rej) => {
const stderr: Array<Buffer> = [];
const stdout: Array<Buffer> = [];
@ -78,7 +78,15 @@ export function waitForChild(child: ChildStreams): Promise<ChildResult> {
});
}
export function writeValue(stream: Writable, value: string): Promise<boolean> {
/**
* @public
* @deprecated
*/
export function waitForChild(child: ChildStreams): Promise<ChildResult> {
return childResult(child);
}
export function writeInput(stream: Writable, value: string): Promise<boolean> {
return new Promise<boolean>((res, rej) => {
stream.write(value, (err: Maybe<Error>) => {
if (doesExist(err)) {
@ -91,3 +99,11 @@ export function writeValue(stream: Writable, value: string): Promise<boolean> {
});
});
}
/**
* @public
* @deprecated
*/
export function writeValue(stream: Writable, value: string): Promise<boolean> {
return writeInput(stream, value);
}

14
src/ExternalModule.ts
View File

@ -1,14 +0,0 @@
import { Module } from 'noicejs';
export interface ExternalModule {
data?: unknown;
export: string;
require: string;
}
export type ModuleCtor = new (data: unknown) => Module;
export function isModule(it: object): it is ModuleCtor {
const p = Reflect.getPrototypeOf(it);
return p === Module || p instanceof Module;
}

3
src/Logger.ts
View File

@ -14,11 +14,14 @@ export function getTestLogger(verbose = false): Logger {
/**
* Create a spy logger using the provided methods, which returns itself as a child.
*
* @todo ensure all methods are present by extending null logger
*/
export function spyLogger(spies: Partial<Logger>): Logger {
const logger = {
...spies,
child: () => logger,
} as Logger;
return logger;
}

7
src/index.ts
View File

@ -24,6 +24,7 @@ export {
defer,
deferValue,
timeout,
deferUntil,
waitFor,
} from './Async';
export {
@ -40,16 +41,14 @@ export {
ChildOptions,
ChildResult,
ChildSpawner,
childResult,
waitForChild,
writeInput,
writeValue,
} from './Child';
export {
isDebug
} from './Env';
export {
ExternalModule,
ModuleCtor,
} from './ExternalModule';
export {
getTestLogger,
spyLogger,

6
test/utils/TestChild.ts
View File

@ -1,7 +1,7 @@
import { expect } from 'chai';
import { ChildProcessError } from '../../src';
import { ChildStreams, waitForChild } from '../../src/Child';
import { ChildStreams, childResult } from '../../src/Child';
import { Maybe, mustExist } from '../../src/Maybe';
type Closer = (status: number) => Promise<void>;
@ -33,7 +33,7 @@ describe('child process utils', async () => {
it('should read stdout data', async () => {
const child = createChild();
const resultPromise = waitForChild(child);
const resultPromise = childResult(child);
await mustExist(child.closer)(0);
const result = await resultPromise;
@ -46,7 +46,7 @@ describe('child process utils', async () => {
it('should reject on failure status', async () => {
const child = createChild();
const resultPromise = waitForChild(child);
const resultPromise = childResult(child);
await mustExist(child.closer)(1);
return expect(resultPromise).to.eventually.be.rejectedWith(ChildProcessError);