From a9d49cd41dbac0e79ecd835807c1dd76979d4e63 Mon Sep 17 00:00:00 2001
From: Sean Sube <seansube@gmail.com>
Date: Sat, 8 Oct 2022 14:19:55 -0500
Subject: [PATCH] fix: add missing typedef visibility comments

---
 src/Array.ts       |  2 ++
 src/ArrayMapper.ts |  3 +++
 src/Async.ts       |  2 +-
 src/Buffer.ts      |  3 +++
 src/Checklist.ts   |  8 +++++++-
 src/Child.ts       | 24 ++++++++++++++++++++++--
 src/Env.ts         |  2 ++
 src/Logger.ts      |  3 +++
 src/Map.ts         | 11 +++++++----
 src/Math.ts        |  1 +
 src/Maybe.ts       |  2 +-
 src/Optional.ts    |  7 +++----
 src/Signal.ts      | 12 ++++++++++++
 src/String.ts      |  4 ++++
 14 files changed, 71 insertions(+), 13 deletions(-)

diff --git a/src/Array.ts b/src/Array.ts
index 2163882f..338e86fa 100644
--- a/src/Array.ts
+++ b/src/Array.ts
@@ -23,6 +23,7 @@ export function mergeArray<TItem>(...parts: ReadonlyArray<TItem | ReadonlyArray<
 
 /**
  * @deprecated renamed to `mergeArray`
+ * @public
  */
 export function mergeArrays<TItem>(...parts: Array<TItem | Array<TItem>>): Array<TItem>;
 export function mergeArrays<TItem>(...parts: ReadonlyArray<TItem | ReadonlyArray<TItem>>): ReadonlyArray<TItem>;
@@ -48,6 +49,7 @@ export function hasItems<T>(val: Maybe<ReadonlyArray<T>>): val is ReadonlyArray<
 
 /**
  * @deprecated renamed to `toArray`
+ * @public
  */
 export function ensureArray<T>(val: Maybe<Array<T>>): Array<T>;
 export function ensureArray<T>(val: Maybe<ReadonlyArray<T>>): ReadonlyArray<T>;
diff --git a/src/ArrayMapper.ts b/src/ArrayMapper.ts
index 022b42eb..594ec6d8 100644
--- a/src/ArrayMapper.ts
+++ b/src/ArrayMapper.ts
@@ -1,5 +1,8 @@
 import { setOrPush } from './Map.js';
 
+/**
+ * @public
+ */
 export interface ArrayMapperOptions {
   /**
    * Key for any remaining, unmatched elements.
diff --git a/src/Async.ts b/src/Async.ts
index bfc9a4d5..4ce623db 100644
--- a/src/Async.ts
+++ b/src/Async.ts
@@ -63,7 +63,7 @@ export async function deferUntil(cb: PredicateC0, step: number, max: number): Pr
 
 /**
  * @public
- * @deprecated
+ * @deprecated use `deferUntil` instead
  */
 export async function waitFor(cb: PredicateC0, step: number, tries: number): Promise<void> {
   return deferUntil(cb, step, tries);
diff --git a/src/Buffer.ts b/src/Buffer.ts
index fb0e71ad..9d36a811 100644
--- a/src/Buffer.ts
+++ b/src/Buffer.ts
@@ -1,5 +1,8 @@
 import { sum } from './Math.js';
 
+/**
+ * @public
+ */
 export type AllowedBufferEncoding = 'ascii' | 'utf-8';
 
 /**
diff --git a/src/Checklist.ts b/src/Checklist.ts
index 995afc68..81f6675d 100644
--- a/src/Checklist.ts
+++ b/src/Checklist.ts
@@ -1,5 +1,7 @@
 /**
  * Whether items should be checked for inclusion (allow list) or exclusion (deny list).
+ *
+ * @public
  */
 export enum ChecklistMode {
   INCLUDE = 'include',
@@ -8,6 +10,8 @@ export enum ChecklistMode {
 
 /**
  * Mode of operation and items to check.
+ *
+ * @public
  */
 export interface ChecklistOptions<T> {
   data: Array<T>;
@@ -15,7 +19,9 @@ export interface ChecklistOptions<T> {
 }
 
 /**
- * Check whether items are included or not (blacklist or whitelist, depending on `mode`).
+ * Check whether items are included or not.
+ *
+ * @public
  */
 export class Checklist<T> implements ChecklistOptions<T> {
   /**
diff --git a/src/Child.ts b/src/Child.ts
index 69a4adc7..ed0d8536 100644
--- a/src/Child.ts
+++ b/src/Child.ts
@@ -7,24 +7,40 @@ import { ChildProcessError } from './error/ChildProcessError.js';
 import { NameValuePair } from './Map.js';
 import { doesExist, Maybe } from './Maybe.js';
 
+/**
+ * @public
+ */
 export interface ChildProcessOptions {
   cwd: string;
   env: Array<NameValuePair<string>>;
   timeout: number;
 }
 
+/**
+ * @public
+ */
 export interface ChildOptions extends ChildProcessOptions {
   args: Array<string>;
   command: string;
 }
 
+/**
+ * @public
+ */
 export interface ChildResult {
   status: number;
   stderr: string;
   stdout: string;
 }
 
+/**
+ * @public
+ */
 export type ChildStreams = ChildProcessWithoutNullStreams;
+
+/**
+ * @public
+ */
 export type ChildSpawner = typeof spawn;
 
 const CHILD_ENCODING = 'utf-8';
@@ -36,6 +52,7 @@ const CHILD_OUTPUT = 'child process emitted error output';
  * Wait for a child process to exit, collecting output, errors, and exit status.
  *
  * @public
+ * @deprecated there are better libraries for this, like zx
  */
 export function childResult(child: ChildStreams): Promise<ChildResult> {
   return new Promise((res, rej) => {
@@ -80,12 +97,15 @@ export function childResult(child: ChildStreams): Promise<ChildResult> {
 
 /**
  * @public
- * @deprecated
+ * @deprecated there are better libraries for this, like zx
  */
 export function waitForChild(child: ChildStreams): Promise<ChildResult> {
   return childResult(child);
 }
 
+/**
+ * @public
+ */
 export function writeInput(stream: Writable, value: string): Promise<boolean> {
   return new Promise<boolean>((res, rej) => {
     stream.write(value, (err: Maybe<Error>) => {
@@ -102,7 +122,7 @@ export function writeInput(stream: Writable, value: string): Promise<boolean> {
 
 /**
  * @public
- * @deprecated
+ * @deprecated call `writeInput` directly instead
  */
 export function writeValue(stream: Writable, value: string): Promise<boolean> {
   return writeInput(stream, value);
diff --git a/src/Env.ts b/src/Env.ts
index c379f742..bcf7d7bb 100644
--- a/src/Env.ts
+++ b/src/Env.ts
@@ -4,6 +4,8 @@ const ENV_DEBUG = 'DEBUG';
  * Test if DEBUG mode is set.
  *
  * TODO: check variable value as well
+ *
+ * @internal
  */
 export function isDebug(): boolean {
   return Reflect.has(process.env, ENV_DEBUG);
diff --git a/src/Logger.ts b/src/Logger.ts
index c7ff6350..467f3f4f 100644
--- a/src/Logger.ts
+++ b/src/Logger.ts
@@ -4,6 +4,8 @@ import { isDebug } from './Env.js';
 
 /**
  * Get a test logger. Returns a null logger unless `verbose` is true or run under debug mode.
+ *
+ * @public
  */
 export function getTestLogger(verbose = false): Logger {
   if (verbose || isDebug()) {
@@ -16,6 +18,7 @@ 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>): Logger {
diff --git a/src/Map.ts b/src/Map.ts
index 68bdd3ee..dc533bb8 100644
--- a/src/Map.ts
+++ b/src/Map.ts
@@ -2,6 +2,9 @@ import { mergeArrays, toArray } from './Array.js';
 import { NotFoundError } from './error/NotFoundError.js';
 import { doesExist, isNone, Maybe, mustExist } from './Maybe.js';
 
+/**
+ * @public
+ */
 export interface Dict<TVal> {
   [key: string]: TVal;
 }
@@ -78,9 +81,9 @@ export function getHeadOrDefault<TKey, TVal>(map: Map<TKey, ReadonlyArray<Maybe<
 
 /**
  * Set a map key to a new array or push to the existing value.
- * @param map The destination map and source of existing values.
- * @param key The key to get and set.
- * @param val The value to add.
+ * @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
  */
@@ -205,7 +208,7 @@ export function dictValuesToArrays<TVal>(map: MapLike<TVal>): Dict<Array<TVal>>
  * Normalize a map-like of values into a dict of lists of strings.
  *
  * @public
- * @deprecated
+ * @deprecated the conversion behavior here was not reliable, better to provide your own `T -> string` mapper
  */
 export function normalizeMap(map: MapLike<unknown>): Dict<Array<string>> {
   const data: Dict<Array<string>> = {};
diff --git a/src/Math.ts b/src/Math.ts
index 38050e9e..7c8c8aa8 100644
--- a/src/Math.ts
+++ b/src/Math.ts
@@ -2,6 +2,7 @@
  * Add numbers.
  *
  * @implements PredicateR2<number, number>
+ * @public
  */
 export function sum(a: number, b: number): number {
   return a + b;
diff --git a/src/Maybe.ts b/src/Maybe.ts
index 31896e7d..08084ad0 100644
--- a/src/Maybe.ts
+++ b/src/Maybe.ts
@@ -78,7 +78,7 @@ export function mustExist<T>(val: Maybe<T>, err?: string): T {
  * Return the first value that is not nil.
  *
  * @public
- * @deprecated
+ * @deprecated use `mustDefault` instead
  */
 export function mustCoalesce<T>(...values: Array<Maybe<T>>): T {
   return mustDefault(...values);
diff --git a/src/Optional.ts b/src/Optional.ts
index 48426de6..fc25df6a 100644
--- a/src/Optional.ts
+++ b/src/Optional.ts
@@ -1,11 +1,10 @@
 // deprecated alternative names for Maybe
 import { isNone, Maybe, None } from './Maybe.js';
 
-
 /**
  * Old name for None.
  *
- * @deprecated
+ * @deprecated use `None` instead
  * @public
  */
 export type Nil = None;
@@ -13,7 +12,7 @@ export type Nil = None;
 /**
  * Old name for Maybe.
  *
- * @deprecated
+ * @deprecated use Maybe instead
  * @public
  */
 export type Optional<T> = Maybe<T>;
@@ -21,7 +20,7 @@ export type Optional<T> = Maybe<T>;
 /**
  * Check if a value is nil.
  *
- * @deprecated
+ * @deprecated use `isNone` instead
  * @public
  */
 export function isNil<T>(val: Maybe<T>): val is Nil {
diff --git a/src/Signal.ts b/src/Signal.ts
index 1d8f80e5..fbabe3e5 100644
--- a/src/Signal.ts
+++ b/src/Signal.ts
@@ -1,11 +1,23 @@
+/**
+ * @public
+ */
 export const SIGNAL_RELOAD: NodeJS.Signals = 'SIGHUP';
+
+/**
+ * @public
+ */
 export const SIGNAL_RESET: NodeJS.Signals = 'SIGINT';
+
+/**
+ * @public
+ */
 export const SIGNAL_STOP: NodeJS.Signals = 'SIGTERM';
 
 /**
  * Wait for an OS signal.
  *
  * @returns the fired signal
+ * @public
  */
 export function signal(...signals: Array<NodeJS.Signals>): Promise<NodeJS.Signals> {
   return new Promise((res, _rej) => {
diff --git a/src/String.ts b/src/String.ts
index b021d538..a827deb1 100644
--- a/src/String.ts
+++ b/src/String.ts
@@ -2,6 +2,8 @@ export const DEFAULT_TRIM = 8;
 
 /**
  * Prefix `val` with `fill` until it is at least `min` characters.
+ *
+ * @public
  */
 export function leftPad(val: string, min = DEFAULT_TRIM, fill = '0'): string {
   if (val.length < min) {
@@ -16,6 +18,8 @@ export function leftPad(val: string, min = DEFAULT_TRIM, fill = '0'): string {
 /**
  * Return the start of `val`, up to `max` characters. If `val` is longer than `max` and there is room,
  * suffix with `tail`.
+ *
+ * @public
  */
 export function trim(val: string, max: number, tail = '...'): string {
   if (val.length <= max) {