diff --git a/docs/api/js-utils.arraymapper.md b/docs/api/js-utils.arraymapper.md index 552a004..5efda4a 100644 --- a/docs/api/js-utils.arraymapper.md +++ b/docs/api/js-utils.arraymapper.md @@ -4,6 +4,8 @@ ## ArrayMapper class +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. + Signature: ```typescript diff --git a/docs/api/js-utils.arraymapperoptions.md b/docs/api/js-utils.arraymapperoptions.md index 453ed0d..6995cec 100644 --- a/docs/api/js-utils.arraymapperoptions.md +++ b/docs/api/js-utils.arraymapperoptions.md @@ -14,7 +14,7 @@ export interface ArrayMapperOptions | Property | Type | Description | | --- | --- | --- | -| [rest](./js-utils.arraymapperoptions.rest.md) | string | | -| [skip](./js-utils.arraymapperoptions.skip.md) | number | | -| [take](./js-utils.arraymapperoptions.take.md) | Array<string> | | +| [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.arraymapperoptions.rest.md b/docs/api/js-utils.arraymapperoptions.rest.md index 2e807ab..3b86dfa 100644 --- a/docs/api/js-utils.arraymapperoptions.rest.md +++ b/docs/api/js-utils.arraymapperoptions.rest.md @@ -4,6 +4,8 @@ ## ArrayMapperOptions.rest property +Key for any remaining, unmatched elements. + Signature: ```typescript diff --git a/docs/api/js-utils.arraymapperoptions.skip.md b/docs/api/js-utils.arraymapperoptions.skip.md index b9ebd0e..14f0bd2 100644 --- a/docs/api/js-utils.arraymapperoptions.skip.md +++ b/docs/api/js-utils.arraymapperoptions.skip.md @@ -4,6 +4,8 @@ ## ArrayMapperOptions.skip property +Number of initial elements to skip. + Signature: ```typescript diff --git a/docs/api/js-utils.arraymapperoptions.take.md b/docs/api/js-utils.arraymapperoptions.take.md index adb4a64..ac93d4d 100644 --- a/docs/api/js-utils.arraymapperoptions.take.md +++ b/docs/api/js-utils.arraymapperoptions.take.md @@ -4,6 +4,8 @@ ## ArrayMapperOptions.take property +List of element keys. + Signature: ```typescript diff --git a/docs/api/js-utils.entriesof.md b/docs/api/js-utils.entriesof.md index 75c899e..f85979d 100644 --- a/docs/api/js-utils.entriesof.md +++ b/docs/api/js-utils.entriesof.md @@ -4,6 +4,8 @@ ## entriesOf() function +Get entries of a map-like. + Signature: ```typescript diff --git a/docs/api/js-utils.gethead.md b/docs/api/js-utils.gethead.md index d0703f9..3a81a2f 100644 --- a/docs/api/js-utils.gethead.md +++ b/docs/api/js-utils.gethead.md @@ -4,6 +4,8 @@ ## getHead() function +Get the first element from the specified key within a map of lists. + Signature: ```typescript diff --git a/docs/api/js-utils.getheadordefault.md b/docs/api/js-utils.getheadordefault.md index b77594d..ee8311e 100644 --- a/docs/api/js-utils.getheadordefault.md +++ b/docs/api/js-utils.getheadordefault.md @@ -4,6 +4,8 @@ ## getHeadOrDefault() function +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. + Signature: ```typescript diff --git a/docs/api/js-utils.getordefault.md b/docs/api/js-utils.getordefault.md index 2af9fa9..824835b 100644 --- a/docs/api/js-utils.getordefault.md +++ b/docs/api/js-utils.getordefault.md @@ -4,6 +4,8 @@ ## getOrDefault() function +Get a map key or default value when the key does not exist or is nil. + Signature: ```typescript diff --git a/docs/api/js-utils.md b/docs/api/js-utils.md index fceeb7d..ef8aa0f 100644 --- a/docs/api/js-utils.md +++ b/docs/api/js-utils.md @@ -8,7 +8,7 @@ | Class | Description | | --- | --- | -| [ArrayMapper](./js-utils.arraymapper.md) | | +| [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. | | [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) | | @@ -35,13 +35,13 @@ | [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) | | -| [entriesOf(map)](./js-utils.entriesof.md) | | +| [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) | | -| [getHead(map, key)](./js-utils.gethead.md) | | -| [getHeadOrDefault(map, key, defaultValue)](./js-utils.getheadordefault.md) | | +| [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) | | -| [getOrDefault(map, key, defaultValue)](./js-utils.getordefault.md) | | +| [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) | | | [isNil(val)](./js-utils.isnil.md) | Check if a value is nil. | @@ -49,14 +49,14 @@ | [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) | | +| [mergeMap(target, source)](./js-utils.mergemap.md) | Merge the source map into the target map, replacing keys that already exist. | | [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) | | -| [pairsToMap(pairs)](./js-utils.pairstomap.md) | | -| [pushMergeMap(args)](./js-utils.pushmergemap.md) | | +| [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) | | | [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) | | diff --git a/docs/api/js-utils.mergemap.md b/docs/api/js-utils.mergemap.md index 2be0058..4b774c6 100644 --- a/docs/api/js-utils.mergemap.md +++ b/docs/api/js-utils.mergemap.md @@ -4,6 +4,8 @@ ## mergeMap() function +Merge the `source` map into the `target` map, replacing keys that already exist. + Signature: ```typescript diff --git a/docs/api/js-utils.pairstomap.md b/docs/api/js-utils.pairstomap.md index 52720a4..6a851f7 100644 --- a/docs/api/js-utils.pairstomap.md +++ b/docs/api/js-utils.pairstomap.md @@ -4,6 +4,8 @@ ## pairsToMap() function +Turns a list of name-value pairs into a map. + Signature: ```typescript diff --git a/docs/api/js-utils.pushmergemap.md b/docs/api/js-utils.pushmergemap.md index a96e0ad..ef780a6 100644 --- a/docs/api/js-utils.pushmergemap.md +++ b/docs/api/js-utils.pushmergemap.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/src/utils/ArrayMapper.ts b/src/ArrayMapper.ts similarity index 74% rename from src/utils/ArrayMapper.ts rename to src/ArrayMapper.ts index 2944346..bcf3ed7 100644 --- a/src/utils/ArrayMapper.ts +++ b/src/ArrayMapper.ts @@ -1,11 +1,24 @@ import { setOrPush } from './Map'; export interface ArrayMapperOptions { + /** + * Key for any remaining, unmatched elements. + */ rest: string; + /** + * Number of initial elements to skip. + */ skip: number; + /** + * List of element keys. + */ take: Array; } +/** + * 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. + */ export class ArrayMapper { public readonly rest: string; public readonly skip: number; diff --git a/src/utils/Async.ts b/src/Async.ts similarity index 89% rename from src/utils/Async.ts rename to src/Async.ts index 78100a2..7861b65 100644 --- a/src/utils/Async.ts +++ b/src/Async.ts @@ -1,5 +1,5 @@ -import { TimeoutError } from '../error/TimeoutError'; -import { PredicateC0 } from '.'; +import { TimeoutError } from './error/TimeoutError'; +import { PredicateC0 } from './utils'; /** * Resolve after a set amount of time. diff --git a/src/AsyncTracker.ts b/src/AsyncTracker.ts index b8b7419..e72e2dc 100644 --- a/src/AsyncTracker.ts +++ b/src/AsyncTracker.ts @@ -1,7 +1,7 @@ import { AsyncHook, createHook } from 'async_hooks'; import { isNil, Optional } from './utils'; -import { isDebug } from './utils/Env'; +import { isDebug } from './Env'; export interface TrackedResource { source: string; diff --git a/src/utils/Buffer.ts b/src/Buffer.ts similarity index 100% rename from src/utils/Buffer.ts rename to src/Buffer.ts diff --git a/src/utils/Checklist.ts b/src/Checklist.ts similarity index 100% rename from src/utils/Checklist.ts rename to src/Checklist.ts diff --git a/src/utils/Child.ts b/src/Child.ts similarity index 95% rename from src/utils/Child.ts rename to src/Child.ts index 05b6274..cb79538 100644 --- a/src/utils/Child.ts +++ b/src/Child.ts @@ -2,8 +2,8 @@ import { ChildProcessWithoutNullStreams, spawn, ChildProcess } from 'child_proce import { BaseError } from 'noicejs'; import { Writable } from 'stream'; -import { doesExist, Optional } from '.'; -import { ChildProcessError } from '../error/ChildProcessError'; +import { doesExist, Optional } from './utils'; +import { ChildProcessError } from './error/ChildProcessError'; import { encode } from './Buffer'; import { NameValuePair } from './Map'; diff --git a/src/utils/Env.ts b/src/Env.ts similarity index 100% rename from src/utils/Env.ts rename to src/Env.ts diff --git a/src/utils/ExternalModule.ts b/src/ExternalModule.ts similarity index 100% rename from src/utils/ExternalModule.ts rename to src/ExternalModule.ts diff --git a/src/Logger.ts b/src/Logger.ts index 12668c3..53a8fb0 100644 --- a/src/Logger.ts +++ b/src/Logger.ts @@ -1,5 +1,5 @@ import { ConsoleLogger, Logger, NullLogger } from 'noicejs'; -import { isDebug } from './utils/Env'; +import { isDebug } from './Env'; export function getTestLogger(verbose = false): Logger { if (verbose || isDebug()) { diff --git a/src/utils/Map.ts b/src/Map.ts similarity index 86% rename from src/utils/Map.ts rename to src/Map.ts index 34e531c..289bbed 100644 --- a/src/utils/Map.ts +++ b/src/Map.ts @@ -1,7 +1,7 @@ import { isMap, isObject, isString } from 'lodash'; -import { doesExist, isNil, mergeList, mustExist, Optional } from '.'; -import { NotFoundError } from '../error/NotFoundError'; +import { doesExist, isNil, mergeList, mustExist, Optional } from './utils'; +import { NotFoundError } from './error/NotFoundError'; export interface Dict { [key: string]: TVal; @@ -20,6 +20,9 @@ export function mustGet(map: Map, key: TKey): TVal { return mustExist(val); } +/** + * Get a map key or default value when the key does not exist or is nil. + */ export function getOrDefault(map: Map, key: TKey, defaultValue: TVal): TVal { if (map.has(key)) { const data = map.get(key); @@ -31,6 +34,9 @@ export function getOrDefault(map: Map, key: TKey, defaul return defaultValue; } +/** + * Get the first element from the specified key within a map of lists. + */ export function getHead(map: Map>, key: TKey): TVal { const value = map.get(key); if (isNil(value) || value.length === 0) { @@ -39,6 +45,10 @@ export function getHead(map: Map>, key: TKey): TVa return value[0]; } +/** + * 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. + */ export function getHeadOrDefault(map: Map>>, key: TKey, defaultValue: TVal): TVal { if (!map.has(key)) { return defaultValue; @@ -76,6 +86,9 @@ export function setOrPush(map: Map>, key: TKey, va } } +/** + * Merge the `source` map into the `target` map, replacing keys that already exist. + */ export function mergeMap(target: Map, source: Map | Array<[TKey, TVal]>) { for (const [k, v] of source) { target.set(k, v); @@ -84,6 +97,9 @@ export function mergeMap(target: Map, source: Map(...args: Array>>): Map> { const out = new Map(); for (const arg of args) { @@ -136,6 +152,9 @@ export interface NameValuePair { value: TVal; } +/** + * Turns a list of name-value pairs into a map. + */ export function pairsToMap(pairs: Array>): Map { const map = new Map(); for (const p of pairs) { @@ -172,6 +191,9 @@ export function normalizeMap(map: MapLike): Dict> { return data; } +/** + * Get entries of a map-like. + */ export function entriesOf(map: Optional>): Array<[string, TVal]> { if (map instanceof Map) { return Array.from(map.entries()); diff --git a/src/utils/PidFile.ts b/src/PidFile.ts similarity index 94% rename from src/utils/PidFile.ts rename to src/PidFile.ts index 0fd5e39..7469166 100644 --- a/src/utils/PidFile.ts +++ b/src/PidFile.ts @@ -1,7 +1,7 @@ import { open, unlink, write } from 'fs'; import { pid } from 'process'; -import { doesExist, Optional } from '.'; +import { doesExist, Optional } from './utils'; type OptionalErrno = Optional; diff --git a/src/utils/Reflect.ts b/src/Reflect.ts similarity index 94% rename from src/utils/Reflect.ts rename to src/Reflect.ts index b693004..3f90f00 100644 --- a/src/utils/Reflect.ts +++ b/src/Reflect.ts @@ -1,6 +1,6 @@ import { isFunction } from 'lodash'; -import { doesExist, isNil } from '.'; +import { doesExist, isNil } from './utils'; export function getConstructor(val: object) { return val.constructor; diff --git a/src/utils/Signal.ts b/src/Signal.ts similarity index 100% rename from src/utils/Signal.ts rename to src/Signal.ts diff --git a/src/utils/String.ts b/src/String.ts similarity index 100% rename from src/utils/String.ts rename to src/String.ts diff --git a/src/index.ts b/src/index.ts index 7f673ed..5844f9b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -8,11 +8,6 @@ export { TimeoutError } from './error/TimeoutError'; export { AsyncTracker, } from './AsyncTracker'; -export { - getTestLogger, - spyLogger, -} from './Logger'; - export { Nil, Optional, @@ -29,29 +24,33 @@ export { export { ArrayMapper, ArrayMapperOptions, -} from './utils/ArrayMapper'; +} from './ArrayMapper'; export { defer, timeout, -} from './utils/Async'; +} from './Async'; export { concat, encode, -} from './utils/Buffer'; +} from './Buffer'; export { Checklist, ChecklistMode, ChecklistOptions, -} from './utils/Checklist'; +} from './Checklist'; export { ChildOptions, ChildResult, ChildSpawner, waitForChild, writeValue, -} from './utils/Child'; -export { ExternalModule, ModuleCtor } from './utils/ExternalModule'; -export { isDebug } from './utils/Env'; +} from './Child'; +export { ExternalModule, ModuleCtor } from './ExternalModule'; +export { isDebug } from './Env'; +export { + getTestLogger, + spyLogger, +} from './Logger'; export { Dict, MapLike, @@ -67,23 +66,23 @@ export { pairsToMap, pushMergeMap, setOrPush, -} from './utils/Map'; +} from './Map'; export { removePid, writePid, -} from './utils/PidFile'; +} from './PidFile'; export { constructorName, getConstructor, getMethods, -} from './utils/Reflect'; +} from './Reflect'; export { SIGNAL_RELOAD, SIGNAL_RESET, SIGNAL_STOP, signal, -} from './utils/Signal'; +} from './Signal'; export { leftPad, trim, -} from './utils/String'; +} from './String'; diff --git a/test/helpers/async.ts b/test/helpers/async.ts index cb3abc4..28c41cb 100644 --- a/test/helpers/async.ts +++ b/test/helpers/async.ts @@ -1,11 +1,10 @@ import { AsyncTracker } from '../../src/AsyncTracker'; import { isNil } from '../../src/utils'; -import { isDebug } from '../../src/utils/Env'; +import { isDebug } from '../../src/Env'; // this will pull Mocha internals out of the stacks /* eslint-disable-next-line @typescript-eslint/no-var-requires */ const { stackTraceFilter } = require('mocha/lib/utils'); -const filterStack = stackTraceFilter(); type AsyncMochaTest = (this: Mocha.Context | void) => Promise; type AsyncMochaSuite = (this: Mocha.Suite) => Promise; @@ -16,6 +15,7 @@ type AsyncMochaSuite = (this: Mocha.Suite) => Promise; export function describeLeaks(description: string, cb: AsyncMochaSuite): Mocha.Suite { return describe(description, function trackSuite(this: Mocha.Suite) { const tracker = new AsyncTracker(); + tracker.filter = stackTraceFilter; beforeEach(() => { tracker.enable(); diff --git a/test/utils/TestArrayMapper.ts b/test/utils/TestArrayMapper.ts index 3b0a9a8..6194fd1 100644 --- a/test/utils/TestArrayMapper.ts +++ b/test/utils/TestArrayMapper.ts @@ -1,6 +1,6 @@ import { expect } from 'chai'; -import { ArrayMapper } from '../../src/utils/ArrayMapper'; +import { ArrayMapper } from '../../src/ArrayMapper'; import { describeLeaks, itLeaks } from '../helpers/async'; describeLeaks('utils', async () => { diff --git a/test/utils/TestAsync.ts b/test/utils/TestAsync.ts index 9737282..193522c 100644 --- a/test/utils/TestAsync.ts +++ b/test/utils/TestAsync.ts @@ -1,8 +1,8 @@ import { expect } from 'chai'; -import { defer, timeout } from '../../src/utils/Async'; +import { defer, timeout } from '../../src/Async'; +import { TimeoutError } from '../../src/error/TimeoutError'; import { describeLeaks, itLeaks } from '../helpers/async'; -import { TimeoutError } from '../../src'; describeLeaks('async utils', async () => { describeLeaks('defer', async () => { diff --git a/test/utils/TestBuffer.ts b/test/utils/TestBuffer.ts index 8658681..950d62a 100644 --- a/test/utils/TestBuffer.ts +++ b/test/utils/TestBuffer.ts @@ -1,6 +1,6 @@ import { expect } from 'chai'; -import { concat, encode } from '../../src/utils/Buffer'; +import { concat, encode } from '../../src/Buffer'; import { describeLeaks, itLeaks } from '../helpers/async'; describeLeaks('buffer utils', async () => { diff --git a/test/utils/TestChecklist.ts b/test/utils/TestChecklist.ts index 052dcae..d62d0f8 100644 --- a/test/utils/TestChecklist.ts +++ b/test/utils/TestChecklist.ts @@ -1,6 +1,6 @@ import { expect } from 'chai'; -import { Checklist, ChecklistMode } from '../../src/utils/Checklist'; +import { Checklist, ChecklistMode } from '../../src/Checklist'; import { describeLeaks, itLeaks } from '../helpers/async'; const EXISTING_ITEM = 'foo'; diff --git a/test/utils/TestChild.ts b/test/utils/TestChild.ts index 69f49d1..fdc5f66 100644 --- a/test/utils/TestChild.ts +++ b/test/utils/TestChild.ts @@ -1,7 +1,7 @@ import { expect } from 'chai'; import { mustExist, Optional } from '../../src/utils'; -import { ChildStreams, waitForChild } from '../../src/utils/Child'; +import { ChildStreams, waitForChild } from '../../src/Child'; import { describeLeaks, itLeaks } from '../helpers/async'; import { ChildProcessError } from '../../src'; diff --git a/test/utils/TestMap.ts b/test/utils/TestMap.ts index 1bfa4ee..c8717d4 100644 --- a/test/utils/TestMap.ts +++ b/test/utils/TestMap.ts @@ -14,7 +14,7 @@ import { mergeMap, pushMergeMap, normalizeMap, -} from '../../src/utils/Map'; +} from '../../src/Map'; import { describeLeaks, itLeaks } from '../helpers/async'; const DEFAULT_VALUE = 'default'; diff --git a/test/utils/TestReflect.ts b/test/utils/TestReflect.ts index e4c1f1b..90aa88e 100644 --- a/test/utils/TestReflect.ts +++ b/test/utils/TestReflect.ts @@ -1,5 +1,5 @@ import { expect } from 'chai'; -import { getMethods, getConstructor, constructorName } from '../../src/utils/Reflect'; +import { getMethods, getConstructor, constructorName } from '../../src/Reflect'; class Test { public foo() { /* noop */ } diff --git a/test/utils/TestSignal.ts b/test/utils/TestSignal.ts index 62f2f58..26be9e6 100644 --- a/test/utils/TestSignal.ts +++ b/test/utils/TestSignal.ts @@ -1,7 +1,7 @@ import { expect } from 'chai'; -import { timeout } from '../../src/utils/Async'; -import { signal, SIGNAL_RESET } from '../../src/utils/Signal'; +import { timeout } from '../../src/Async'; +import { signal, SIGNAL_RESET } from '../../src/Signal'; import { describeLeaks, itLeaks } from '../helpers/async'; const MAX_SIGNAL_TIME = 500; diff --git a/test/utils/TestString.ts b/test/utils/TestString.ts index 8793c17..c6bb1fc 100644 --- a/test/utils/TestString.ts +++ b/test/utils/TestString.ts @@ -1,6 +1,6 @@ import { expect } from 'chai'; -import { leftPad, trim } from '../../src/utils/String'; +import { leftPad, trim } from '../../src/String'; import { describeLeaks, itLeaks } from '../helpers/async'; const TEST_SHORT = 'hello';