lint: organize files, document exported

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

docs/api/js-utils.arraymapperoptions.md

@@ -14,7 +14,7 @@ export interface ArrayMapperOptions
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [rest](./js-utils.arraymapperoptions.rest.md) | <code>string</code> |  |
-|  [skip](./js-utils.arraymapperoptions.skip.md) | <code>number</code> |  |
-|  [take](./js-utils.arraymapperoptions.take.md) | <code>Array&lt;string&gt;</code> |  |
+|  [rest](./js-utils.arraymapperoptions.rest.md) | <code>string</code> | Key for any remaining, unmatched elements. |
+|  [skip](./js-utils.arraymapperoptions.skip.md) | <code>number</code> | Number of initial elements to skip. |
+|  [take](./js-utils.arraymapperoptions.take.md) | <code>Array&lt;string&gt;</code> | List of element keys. |
 

docs/api/js-utils.arraymapperoptions.rest.md

@@ -4,6 +4,8 @@
 
 ## ArrayMapperOptions.rest property
 
+Key for any remaining, unmatched elements.
+
 <b>Signature:</b>
 
 ```typescript

docs/api/js-utils.arraymapperoptions.skip.md

@@ -4,6 +4,8 @@
 
 ## ArrayMapperOptions.skip property
 
+Number of initial elements to skip.
+
 <b>Signature:</b>
 
 ```typescript

docs/api/js-utils.arraymapperoptions.take.md

@@ -4,6 +4,8 @@
 
 ## ArrayMapperOptions.take property
 
+List of element keys.
+
 <b>Signature:</b>
 
 ```typescript

docs/api/js-utils.entriesof.md

@@ -4,6 +4,8 @@
 
 ## entriesOf() function
 
+Get entries of a map-like.
+
 <b>Signature:</b>
 
 ```typescript

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

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

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

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 <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) |  |
@@ -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 <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 |
 |  [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) |  |

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

docs/api/js-utils.pairstomap.md

@@ -4,6 +4,8 @@
 
 ## pairsToMap() function
 
+Turns a list of name-value pairs into a map.
+
 <b>Signature:</b>
 
 ```typescript

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

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<string>;
 }
 
+/**
+ * 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;

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.

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;

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';
 

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()) {

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<TVal> {
   [key: string]: TVal;
@@ -20,6 +20,9 @@ export function mustGet<TKey, TVal>(map: Map<TKey, TVal>, 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<TKey, TVal>(map: Map<TKey, TVal>, key: TKey, defaultValue: TVal): TVal {
   if (map.has(key)) {
     const data = map.get(key);
@@ -31,6 +34,9 @@ export function getOrDefault<TKey, TVal>(map: Map<TKey, TVal>, key: TKey, defaul
   return defaultValue;
 }
 
+/**
+ * Get the first element from the specified key within a map of lists.
+ */
 export function getHead<TKey, TVal>(map: Map<TKey, Array<TVal>>, key: TKey): TVal {
   const value = map.get(key);
   if (isNil(value) || value.length === 0) {
@@ -39,6 +45,10 @@ export function getHead<TKey, TVal>(map: Map<TKey, Array<TVal>>, 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<TKey, TVal>(map: Map<TKey, Array<Optional<TVal>>>, key: TKey, defaultValue: TVal): TVal {
   if (!map.has(key)) {
     return defaultValue;
@@ -76,6 +86,9 @@ 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.
+ */
 export function mergeMap<TKey, TVal>(target: Map<TKey, TVal>, source: Map<TKey, TVal> | Array<[TKey, TVal]>) {
   for (const [k, v] of source) {
     target.set(k, v);
@@ -84,6 +97,9 @@ export function mergeMap<TKey, TVal>(target: Map<TKey, TVal>, source: Map<TKey,
   return target;
 }
 
+/**
+ * Merge the provided maps into a new map, merging keys that already exist by pushing new items.
+ */
 export function pushMergeMap<TKey, TVal>(...args: Array<Map<TKey, TVal | Array<TVal>>>): Map<TKey, Array<TVal>> {
   const out = new Map();
   for (const arg of args) {
@@ -136,6 +152,9 @@ export interface NameValuePair<TVal> {
   value: TVal;
 }
 
+/**
+ * Turns a list of name-value pairs into a map.
+ */
 export function pairsToMap<TVal>(pairs: Array<NameValuePair<TVal>>): Map<string, TVal> {
   const map = new Map();
   for (const p of pairs) {
@@ -172,6 +191,9 @@ export function normalizeMap(map: MapLike<unknown>): Dict<Array<string>> {
   return data;
 }
 
+/**
+ * Get entries of a map-like.
+ */
 export function entriesOf<TVal>(map: Optional<MapLike<TVal>>): Array<[string, TVal]> {
   if (map instanceof Map) {
     return Array.from(map.entries());

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<NodeJS.ErrnoException>;
 

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;

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';

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<void>;
 type AsyncMochaSuite = (this: Mocha.Suite) => Promise<void>;
@@ -16,6 +15,7 @@ type AsyncMochaSuite = (this: Mocha.Suite) => Promise<void>;
 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();

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 () => {

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 () => {

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 () => {

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';

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';
 

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';

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 */ }

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;

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';