fix: add missing typedef visibility comments

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

src/ArrayMapper.ts

@@ -1,5 +1,8 @@
 import { setOrPush } from './Map.js';
 
+/**
+ * @public
+ */
 export interface ArrayMapperOptions {
   /**
    * Key for any remaining, unmatched elements.

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

src/Buffer.ts

@@ -1,5 +1,8 @@
 import { sum } from './Math.js';
 
+/**
+ * @public
+ */
 export type AllowedBufferEncoding = 'ascii' | 'utf-8';
 
 /**

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,14 +10,18 @@ export enum ChecklistMode {
 
 /**
  * Mode of operation and items to check.
+ *
+ * @public
  */
 export interface ChecklistOptions<T> {
   data: Array<T>;
   mode: ChecklistMode;
 }
 
 /**
- * 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> {
   /**

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

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

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 {

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>> = {};

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;

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

src/Optional.ts

@@ -1,27 +1,26 @@
 // 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;
 
 /**
  * Old name for Maybe.
  *
- * @deprecated
+ * @deprecated use Maybe instead
  * @public
  */
 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 {

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

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