@ix-xs/node-comfort 1.2.0 → 2.1.0

package/types/src/Func.d.ts

@@ -1,210 +1,583 @@
 /**
- * Creates a debounced version of a function that delays invocation until
- * `wait` ms have elapsed since the last call.
- *
- * The returned function exposes `.cancel()` and `.flush()`.
+ * Options for `debounce()`.
+ */
+export type DebounceOptions = {
+    /**
+     * Call right away at the start of a burst.
+     */
+    leading?: boolean | undefined;
+    /**
+     * Call once the burst is over. Defaults to `true`.
+     */
+    trailing?: boolean | undefined;
+    /**
+     * Never postpone a call longer than this, even if calls keep coming. In ms, or like `"2s"`.
+     */
+    maxWait?: string | number | undefined;
+};
+/**
+ * A debounced function. `flush()` runs the pending call now, `cancel()`
+ * drops it, `pending()` tells you if there's one.
+ */
+export type DebouncedFunction<F extends (...args: any[]) => any> = ((...args: Parameters<F>) => void) & {
+    cancel(): void;
+    flush(): void;
+    pending(): boolean;
+};
+/**
+ * Options for `throttle()`.
+ */
+export type ThrottleOptions = {
+    /**
+     * Call right away on the first call. Defaults to `true`.
+     */
+    leading?: boolean | undefined;
+    /**
+     * Make a last call with the latest arguments at the end of the interval. Defaults to `true`.
+     */
+    trailing?: boolean | undefined;
+};
+/**
+ * A throttled function, with `cancel()`.
+ */
+export type ThrottledFunction<F extends (...args: any[]) => any> = ((...args: Parameters<F>) => void) & {
+    cancel(): void;
+};
+/**
+ * Options for `memoize()`.
+ */
+export type MemoizeOptions = {
+    /**
+     * Builds the cache key from the arguments. By default, primitives are compared by value, plain objects and arrays by content, anything else by identity.
+     */
+    resolver?: ((...args: any[]) => unknown) | undefined;
+    /**
+     * How long a result stays cached, in ms or like `"5m"`.
+     */
+    ttl?: string | number | undefined;
+    /**
+     * Maximum number of results; the least recently used goes first.
+     */
+    max?: number | undefined;
+    /**
+     * Keep rejected promises. By default they're dropped so the next call tries again.
+     */
+    cacheRejections?: boolean | undefined;
+};
+/**
+ * A memoized function, with its `cache`, `clear()` and `delete(...args)`.
+ */
+export type MemoizedFunction<F extends (...args: any[]) => any> = F & {
+    cache: Map<unknown, {
+        value: ReturnType<F>;
+        expires: number;
+    }>;
+    clear(): void;
+    delete(...args: Parameters<F>): boolean;
+};
+/**
+ * Options for `retry()`.
+ */
+export type RetryOptions = {
+    /**
+     * Total attempts, the first one included. Defaults to `3`.
+     */
+    attempts?: number | undefined;
+    /**
+     * Wait before the next attempt, in ms or like `"1s"`, or a function that computes it.
+     */
+    delay?: string | number | ((attempt: number, error: unknown) => number) | undefined;
+    /**
+     * Multiplies the delay after each failure: `2` gives 200, 400, 800... Defaults to `1`.
+     */
+    backoff?: number | undefined;
+    /**
+     * Cap for the computed delay.
+     */
+    maxDelay?: string | number | undefined;
+    /**
+     * Randomizes the delay, from `0` (none) to `1` (anywhere between 0 and 2x). Stops many clients from retrying in sync.
+     */
+    jitter?: number | undefined;
+    /**
+     * Return `false` to give up early, for example on a 4xx error.
+     */
+    shouldRetry?: ((error: unknown, attempt: number) => boolean | Promise<boolean>) | undefined;
+    /**
+     * Called before each wait, for logs or metrics.
+     */
+    onRetry?: ((error: unknown, attempt: number, delay: number) => void) | undefined;
+    /**
+     * Stops retrying. The attempt in progress isn't interrupted.
+     */
+    signal?: AbortSignal | undefined;
+};
+/**
+ * Options for `batch()`.
+ */
+export type BatchOptions = {
+    /**
+     * How long to collect calls before running. By default, calls made in the same tick go together.
+     */
+    wait?: string | number | undefined;
+    /**
+     * Run as soon as this many calls are waiting.
+     */
+    max?: number | undefined;
+};
+/**
+ * A batched function. `flush()` runs the waiting calls now.
+ */
+export type BatchedFunction<I, R> = ((item: I) => Promise<R>) & {
+    flush(): void;
+};
+/**
+ * Options for `debounce()`.
+ * @typedef {object} DebounceOptions
+ * @property {boolean} [leading] Call right away at the start of a burst.
+ * @property {boolean} [trailing] Call once the burst is over. Defaults to `true`.
+ * @property {number | string} [maxWait] Never postpone a call longer than this, even if calls keep coming. In ms, or like `"2s"`.
+ */
+/**
+ * A debounced function. `flush()` runs the pending call now, `cancel()`
+ * drops it, `pending()` tells you if there's one.
+ * @template {(...args: any[]) => any} F
+ * @typedef {((...args: Parameters<F>) => void) & { cancel(): void, flush(): void, pending(): boolean }} DebouncedFunction
+ */
+/**
+ * Options for `throttle()`.
+ * @typedef {object} ThrottleOptions
+ * @property {boolean} [leading] Call right away on the first call. Defaults to `true`.
+ * @property {boolean} [trailing] Make a last call with the latest arguments at the end of the interval. Defaults to `true`.
+ */
+/**
+ * A throttled function, with `cancel()`.
+ * @template {(...args: any[]) => any} F
+ * @typedef {((...args: Parameters<F>) => void) & { cancel(): void }} ThrottledFunction
+ */
+/**
+ * Options for `memoize()`.
+ * @typedef {object} MemoizeOptions
+ * @property {(...args: any[]) => unknown} [resolver] Builds the cache key from the arguments. By default, primitives are compared by value, plain objects and arrays by content, anything else by identity.
+ * @property {number | string} [ttl] How long a result stays cached, in ms or like `"5m"`.
+ * @property {number} [max] Maximum number of results; the least recently used goes first.
+ * @property {boolean} [cacheRejections] Keep rejected promises. By default they're dropped so the next call tries again.
+ */
+/**
+ * A memoized function, with its `cache`, `clear()` and `delete(...args)`.
+ * @template {(...args: any[]) => any} F
+ * @typedef {F & { cache: Map<unknown, { value: ReturnType<F>, expires: number }>, clear(): void, delete(...args: Parameters<F>): boolean }} MemoizedFunction
+ */
+/**
+ * Options for `retry()`.
+ * @typedef {object} RetryOptions
+ * @property {number} [attempts] Total attempts, the first one included. Defaults to `3`.
+ * @property {number | string | ((attempt: number, error: unknown) => number)} [delay] Wait before the next attempt, in ms or like `"1s"`, or a function that computes it.
+ * @property {number} [backoff] Multiplies the delay after each failure: `2` gives 200, 400, 800... Defaults to `1`.
+ * @property {number | string} [maxDelay] Cap for the computed delay.
+ * @property {number} [jitter] Randomizes the delay, from `0` (none) to `1` (anywhere between 0 and 2x). Stops many clients from retrying in sync.
+ * @property {(error: unknown, attempt: number) => boolean | Promise<boolean>} [shouldRetry] Return `false` to give up early, for example on a 4xx error.
+ * @property {(error: unknown, attempt: number, delay: number) => void} [onRetry] Called before each wait, for logs or metrics.
+ * @property {AbortSignal} [signal] Stops retrying. The attempt in progress isn't interrupted.
+ */
+/**
+ * Options for `batch()`.
+ * @typedef {object} BatchOptions
+ * @property {number | string} [wait] How long to collect calls before running. By default, calls made in the same tick go together.
+ * @property {number} [max] Run as soon as this many calls are waiting.
+ */
+/**
+ * A batched function. `flush()` runs the waiting calls now.
+ * @template I
+ * @template R
+ * @typedef {((item: I) => Promise<R>) & { flush(): void }} BatchedFunction
+ */
+/**
+ * Waits for a pause of `wait` ms between calls, then runs once with the
+ * latest arguments. For search boxes, resizing, auto-saving...
  *
  * @example
- * const onResize = nodeComfort.func.debounce(() => render(), 200);
- * window.on("resize", onResize);
- * onResize.cancel(); // drop any pending call
+ * const search = func.debounce((query) => api.search(query), 300);
+ * input.on("input", (e) => search(e.target.value));
+ *
+ * const save = func.debounce(persist, 1000, { maxWait: 5000 }); // saves at least every 5s
  *
  * @template {(...args: any[]) => any} F
- * @param {F} fn - Function to debounce.
- * @param {number} wait - Delay in milliseconds.
- * @param {{ leading?: boolean }} [options] - Set `leading` to fire on the first call.
- * @returns {F & { cancel: () => void, flush: () => void }} The debounced function.
- */
-export function debounce<F extends (...args: any[]) => any>(fn: F, wait: number, options?: {
-    leading?: boolean;
-}): F & {
-    cancel: () => void;
-    flush: () => void;
-};
+ * @param {F} fn
+ * @param {number | string} wait Pause needed, in ms or like `"300ms"`.
+ * @param {DebounceOptions} [options]
+ * @returns {DebouncedFunction<F>}
+ */
+export function debounce<F extends (...args: any[]) => any>(fn: F, wait: number | string, options?: DebounceOptions): DebouncedFunction<F>;
 /**
- * Creates a throttled version of a function that runs at most once per
- * `wait` ms.
+ * Runs at most once every `wait` ms, however often it's called. For scroll
+ * handlers, progress reports, rate-limited APIs...
  *
  * @example
- * const onScroll = nodeComfort.func.throttle(() => update(), 100);
+ * const report = func.throttle((pct) => console.log(`${pct}%`), 1000);
  *
  * @template {(...args: any[]) => any} F
- * @param {F} fn - Function to throttle.
- * @param {number} wait - Minimum interval in milliseconds.
- * @param {{ trailing?: boolean }} [options] - Set `trailing` (default true) to run a final call.
- * @returns {F & { cancel: () => void }} The throttled function.
- */
-export function throttle<F extends (...args: any[]) => any>(fn: F, wait: number, options?: {
-    trailing?: boolean;
-}): F & {
-    cancel: () => void;
-};
+ * @param {F} fn
+ * @param {number | string} interval Minimum gap between calls, in ms or like `"1s"`.
+ * @param {ThrottleOptions} [options]
+ * @returns {ThrottledFunction<F>}
+ */
+export function throttle<F extends (...args: any[]) => any>(fn: F, interval: number | string, options?: ThrottleOptions): ThrottledFunction<F>;
 /**
- * Wraps a function so it can only ever run once; subsequent calls return
- * the first result.
+ * Runs `fn` the first time only; later calls return the same result.
  *
  * @example
- * const init = nodeComfort.func.once(() => expensiveSetup());
+ * const connect = func.once(() => createPool(config));
  *
  * @template {(...args: any[]) => any} F
- * @param {F} fn - Function to wrap.
- * @returns {F} The single-call function.
+ * @param {F} fn
+ * @returns {F}
  */
 export function once<F extends (...args: any[]) => any>(fn: F): F;
 /**
- * Memoizes a function, caching results by argument key.
- *
- * By default the cache key is a JSON serialization of the arguments; pass a
- * `resolver` for custom keys.
+ * Caches results by arguments. Supports expiry (`ttl`), a size limit
+ * (`max`) and async functions: a failed promise isn't cached, so the next
+ * call tries again.
  *
  * @example
- * const fib = nodeComfort.func.memoize((n) => (n < 2 ? n : fib(n - 1) + fib(n - 2)));
+ * const getUser = func.memoize((id) => db.users.find(id), { ttl: 60_000, max: 1000 });
+ * getUser.delete(42); // forget one entry
+ * getUser.clear();    // forget everything
  *
  * @template {(...args: any[]) => any} F
- * @param {F} fn - Function to memoize.
- * @param {(...args: any[]) => any} [resolver] - Cache-key resolver.
- * @returns {F & { cache: Map<any, any> }} The memoized function.
+ * @param {F} fn
+ * @param {MemoizeOptions | ((...args: Parameters<F>) => unknown)} [options] Options, or a function that builds the cache key.
+ * @returns {MemoizedFunction<F>}
  */
-export function memoize<F extends (...args: any[]) => any>(fn: F, resolver?: (...args: any[]) => any): F & {
-    cache: Map<any, any>;
-};
+export function memoize<F extends (...args: any[]) => any>(fn: F, options?: MemoizeOptions | ((...args: Parameters<F>) => unknown)): MemoizedFunction<F>;
 /**
- * Retries an async function until it succeeds or the attempt budget runs out.
- *
- * Supports fixed or exponential backoff and a `shouldRetry` guard.
+ * Calls `fn` until it succeeds, waiting between attempts. If every attempt
+ * fails, the last error is thrown.
  *
  * @example
- * const data = await nodeComfort.func.retry(() => fetch(url), {
+ * const data = await func.retry(() => fetchJSON(url), {
  *   attempts: 5,
  *   delay: 200,
- *   backoff: 2, // 200, 400, 800, ...
+ *   backoff: 2, // 200, 400, 800, 1600 ms
+ *   shouldRetry: (error) => !(error instanceof nc.errors.HttpError && error.status < 500),
  * });
  *
  * @template T
- * @param {() => T|Promise<T>} fn - Function to run.
- * @param {{
- *   attempts?: number,
- *   delay?: number,
- *   backoff?: number,
- *   maxDelay?: number,
- *   shouldRetry?: (error: unknown, attempt: number) => boolean,
- *   onRetry?: (error: unknown, attempt: number) => void
- * }} [options] - Retry options.
- * @returns {Promise<T>} The resolved value.
- * @throws Re-throws the last error if all attempts fail.
- */
-export function retry<T>(fn: () => T | Promise<T>, options?: {
-    attempts?: number;
-    delay?: number;
-    backoff?: number;
-    maxDelay?: number;
-    shouldRetry?: (error: unknown, attempt: number) => boolean;
-    onRetry?: (error: unknown, attempt: number) => void;
-}): Promise<T>;
-/**
- * Runs a promise (or async function) with a timeout, rejecting if it takes
- * too long.
- *
- * @example
- * await nodeComfort.func.timeout(fetch(url), 5000, "fetch too slow");
+ * @param {(attempt: number) => T | PromiseLike<T>} fn Receives the attempt number, starting at 1.
+ * @param {RetryOptions} [options]
+ * @returns {Promise<Awaited<T>>}
+ * @throws The last error, or an `AbortError` if the signal fires.
+ */
+export function retry<T>(fn: (attempt: number) => T | PromiseLike<T>, options?: RetryOptions): Promise<Awaited<T>>;
+/**
+ * Rejects with a `TimeoutError` if the promise takes longer than `ms`. Pass
+ * a function to get an `AbortSignal` that fires when time is up, so the work
+ * actually stops instead of running on in the background.
+ *
+ * @example
+ * const res = await func.timeout(fetch(url), 5000);
+ * const rows = await func.timeout(() => slowQuery(), 2000, "Database too slow");
+ *
+ * @template T
+ * @param {PromiseLike<T> | ((signal: AbortSignal) => PromiseLike<T> | T)} promise A promise, or a function that returns one. The function gets a signal that aborts on timeout.
+ * @param {number | string} ms The limit, in ms or like `"5s"`. `Infinity` means no limit.
+ * @param {string} [message]
+ * @returns {Promise<Awaited<T>>}
+ * @throws {TimeoutError}
+ */
+export function timeout<T>(promise: PromiseLike<T> | ((signal: AbortSignal) => PromiseLike<T> | T), ms: number | string, message?: string): Promise<Awaited<T>>;
+/**
+ * Waits `ms`, then calls `fn` with the arguments and resolves with its result.
+ *
+ * @example
+ * await func.delay(() => console.log("1s later"), 1000);
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn
+ * @param {number | string} ms In ms, or like `"2s"`.
+ * @param {Parameters<F>} args
+ * @returns {Promise<Awaited<ReturnType<F>>>}
+ */
+export function delay<F extends (...args: any[]) => any>(fn: F, ms: number | string, ...args: Parameters<F>): Promise<Awaited<ReturnType<F>>>;
+/**
+ * Awaits a promise and gives you `[error, value]` instead of throwing, so
+ * you don't need a try/catch.
+ *
+ * @example
+ * const [error, user] = await func.to(db.users.find(id));
+ * if (error) return res.status(500).send(error.message);
  *
  * @template T
- * @param {Promise<T>|(() => Promise<T>)} promise - Promise or async function.
- * @param {number} ms - Timeout in milliseconds.
- * @param {string} [message="Operation timed out"] - Error message on timeout.
- * @returns {Promise<T>} The resolved value.
- * @throws {Error} If the timeout elapses first.
+ * @template [E=Error]
+ * @param {PromiseLike<T> | (() => PromiseLike<T> | T)} promise A promise, or a function (sync errors are caught too).
+ * @returns {Promise<[E, undefined] | [null, Awaited<T>]>}
  */
-export function timeout<T>(promise: Promise<T> | (() => Promise<T>), ms: number, message?: string): Promise<T>;
+export function to<T, E = Error>(promise: PromiseLike<T> | (() => PromiseLike<T> | T)): Promise<[E, undefined] | [null, Awaited<T>]>;
 /**
- * Composes functions left-to-right: `pipe(f, g)(x)` is `g(f(x))`.
+ * Wraps a function so it resolves to `[error, value]` instead of throwing.
  *
- * The first function may take multiple arguments; the rest take one.
+ * @example
+ * const safeParse = func.attempt(JSON.parse);
+ * const [error, data] = await safeParse(input);
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn
+ * @returns {(...args: Parameters<F>) => Promise<[unknown, undefined] | [null, Awaited<ReturnType<F>>]>}
+ */
+export function attempt<F extends (...args: any[]) => any>(fn: F): (...args: Parameters<F>) => Promise<[unknown, undefined] | [null, Awaited<ReturnType<F>>]>;
+/**
+ * Turns a callback-style function into one that returns a promise.
  *
  * @example
- * const process = nodeComfort.func.pipe(
- *   (s) => s.trim(),
- *   (s) => s.toUpperCase(),
- * );
- * process("  hi  "); // "HI"
+ * const lookup = func.promisify(dns.lookup);
+ * const address = await lookup("nodejs.org");
  *
- * @param {...((arg: any) => any)} fns - Functions to compose.
- * @returns {(...args: any[]) => any} The composed function.
+ * @param {(...args: any[]) => void} fn
+ * @returns {(...args: any[]) => Promise<any>}
+ */
+export function promisify(fn: (...args: any[]) => void): (...args: any[]) => Promise<any>;
+/**
+ * Turns many single calls into few grouped ones. Calls made close together
+ * are collected, `fn` runs once with all their items, and each caller gets
+ * its own result. The classic cure for "N+1 queries".
+ *
+ * @example
+ * const loadUser = func.batch(async (ids) => {
+ *   const users = await db.getAll("users", { id: ids });
+ *   return ids.map((id) => users.find((user) => user.id === id));
+ * });
+ * // One query, however many places ask at once:
+ * const [ada, bob] = await Promise.all([loadUser(1), loadUser(2)]);
+ *
+ * @template I
+ * @template R
+ * @param {(items: I[]) => ReadonlyArray<R | Error> | Map<I, R | Error> | PromiseLike<ReadonlyArray<R | Error> | Map<I, R | Error>>} fn Gets every waiting item and returns one result per item, in the same order, or a `Map` keyed by item. An `Error` as a result rejects that call only.
+ * @param {BatchOptions} [options]
+ * @returns {BatchedFunction<I, R>}
+ */
+export function batch<I, R>(fn: (items: I[]) => ReadonlyArray<R | Error> | Map<I, R | Error> | PromiseLike<ReadonlyArray<R | Error> | Map<I, R | Error>>, options?: BatchOptions): BatchedFunction<I, R>;
+/**
+ * Makes concurrent calls with the same arguments share one run. Once it
+ * settles, the next call starts a new one: nothing is cached.
+ *
+ * @example
+ * const refreshToken = func.dedupe(async () => (await api.post("auth/refresh")).data);
+ * // Ten requests hit a 401 at once: one refresh, ten answers.
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn
+ * @param {(...args: Parameters<F>) => unknown} [keyOf] Builds the key that identifies a call. Defaults to its arguments.
+ * @returns {(...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>}
+ */
+export function dedupe<F extends (...args: any[]) => any>(fn: F, keyOf?: (...args: Parameters<F>) => unknown): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;
+/**
+ * Chains functions from left to right: `pipe(f, g)(x)` is `g(f(x))`.
+ * Types flow through up to 6 functions.
+ *
+ * @example
+ * const toSlug = func.pipe(nc.str.deburr, nc.str.kebabCase);
+ * toSlug("Crème Brûlée"); // "creme-brulee"
+ *
+ * @template {any[]} A
+ * @template B
+ * @overload
+ * @param {(...args: A) => B} f1
+ * @returns {(...args: A) => B}
+ */
+export function pipe<A extends any[], B>(f1: (...args: A) => B): (...args: A) => B;
+/**
+ * Chains functions from left to right.
+ *
+ * @template {any[]} A
+ * @template B
+ * @template C
+ * @overload
+ * @param {(...args: A) => B} f1
+ * @param {(b: B) => C} f2
+ * @returns {(...args: A) => C}
+ */
+export function pipe<A extends any[], B, C>(f1: (...args: A) => B, f2: (b: B) => C): (...args: A) => C;
+/**
+ * Chains functions from left to right.
+ *
+ * @template {any[]} A
+ * @template B
+ * @template C
+ * @template D
+ * @overload
+ * @param {(...args: A) => B} f1
+ * @param {(b: B) => C} f2
+ * @param {(c: C) => D} f3
+ * @returns {(...args: A) => D}
+ */
+export function pipe<A extends any[], B, C, D>(f1: (...args: A) => B, f2: (b: B) => C, f3: (c: C) => D): (...args: A) => D;
+/**
+ * Chains functions from left to right.
+ *
+ * @template {any[]} A
+ * @template B
+ * @template C
+ * @template D
+ * @template E
+ * @overload
+ * @param {(...args: A) => B} f1
+ * @param {(b: B) => C} f2
+ * @param {(c: C) => D} f3
+ * @param {(d: D) => E} f4
+ * @returns {(...args: A) => E}
+ */
+export function pipe<A extends any[], B, C, D, E>(f1: (...args: A) => B, f2: (b: B) => C, f3: (c: C) => D, f4: (d: D) => E): (...args: A) => E;
+/**
+ * Chains functions from left to right.
+ *
+ * @template {any[]} A
+ * @template B
+ * @template C
+ * @template D
+ * @template E
+ * @template F
+ * @overload
+ * @param {(...args: A) => B} f1
+ * @param {(b: B) => C} f2
+ * @param {(c: C) => D} f3
+ * @param {(d: D) => E} f4
+ * @param {(e: E) => F} f5
+ * @returns {(...args: A) => F}
+ */
+export function pipe<A extends any[], B, C, D, E, F>(f1: (...args: A) => B, f2: (b: B) => C, f3: (c: C) => D, f4: (d: D) => E, f5: (e: E) => F): (...args: A) => F;
+/**
+ * Chains functions from left to right.
+ *
+ * @template {any[]} A
+ * @template B
+ * @template C
+ * @template D
+ * @template E
+ * @template F
+ * @template G
+ * @overload
+ * @param {(...args: A) => B} f1
+ * @param {(b: B) => C} f2
+ * @param {(c: C) => D} f3
+ * @param {(d: D) => E} f4
+ * @param {(e: E) => F} f5
+ * @param {(f: F) => G} f6
+ * @returns {(...args: A) => G}
+ */
+export function pipe<A extends any[], B, C, D, E, F, G>(f1: (...args: A) => B, f2: (b: B) => C, f3: (c: C) => D, f4: (d: D) => E, f5: (e: E) => F, f6: (f: F) => G): (...args: A) => G;
+/**
+ * Chains any number of functions from left to right.
+ *
+ * @overload
+ * @param {...((arg: any) => any)} fns
+ * @returns {(...args: any[]) => any}
  */
 export function pipe(...fns: ((arg: any) => any)[]): (...args: any[]) => any;
 /**
- * Composes functions right-to-left: `compose(f, g)(x)` is `f(g(x))`.
+ * Like `pipe()`, for functions that may be async: each one is awaited
+ * before the next runs.
  *
  * @example
- * const process = nodeComfort.func.compose(
- *   (s) => s.toUpperCase(),
- *   (s) => s.trim(),
- * );
- * process("  hi  "); // "HI"
+ * const publish = func.pipeAsync(loadDraft, renderMarkdown, uploadToCDN);
+ * const url = await publish(postId);
  *
- * @param {...((arg: any) => any)} fns - Functions to compose.
- * @returns {(...args: any[]) => any} The composed function.
+ * @param {...((...args: any[]) => any)} fns
+ * @returns {(...args: any[]) => Promise<any>}
  */
-export function compose(...fns: ((arg: any) => any)[]): (...args: any[]) => any;
+export function pipeAsync(...fns: ((...args: any[]) => any)[]): (...args: any[]) => Promise<any>;
 /**
- * Curries a function so it can be called with arguments one (or a few) at a time.
+ * Chains functions from right to left: `compose(f, g)(x)` is `f(g(x))`.
+ * `pipe()` reads in execution order and is better typed.
  *
  * @example
- * const add = nodeComfort.func.curry((a, b, c) => a + b + c);
- * add(1)(2)(3);   // 6
- * add(1, 2)(3);   // 6
+ * const shout = func.compose((s) => s + "!", (s) => s.toUpperCase());
+ * shout("hi"); // "HI!"
  *
- * @param {(...args: any[]) => any} fn - Function to curry.
- * @param {number} [arity=fn.length] - Number of arguments to wait for.
- * @returns {(...args: any[]) => any} The curried function.
+ * @param {...((...args: any[]) => any)} fns
+ * @returns {(...args: any[]) => any}
+ */
+export function compose(...fns: ((...args: any[]) => any)[]): (...args: any[]) => any;
+/**
+ * Lets you pass a function's arguments a few at a time.
+ *
+ * @example
+ * const add = func.curry((a, b, c) => a + b + c);
+ * add(1)(2)(3); // 6
+ * add(1, 2)(3); // 6
+ *
+ * @param {(...args: any[]) => any} fn
+ * @param {number} [arity=fn.length] How many arguments to collect before calling.
+ * @returns {(...args: any[]) => any}
  */
 export function curry(fn: (...args: any[]) => any, arity?: number): (...args: any[]) => any;
 /**
- * Returns a function that negates the result of `predicate`.
+ * Fixes the first arguments of a function.
+ *
+ * @example
+ * const hello = func.partial((greeting, name) => `${greeting}, ${name}!`, "Hello");
+ * hello("Ada"); // "Hello, Ada!"
+ *
+ * @template {any[]} P
+ * @template {any[]} R
+ * @template T
+ * @param {(...args: [...P, ...R]) => T} fn
+ * @param {P} preset
+ * @returns {(...args: R) => T}
+ */
+export function partial<P extends any[], R extends any[], T>(fn: (...args: [...P, ...R]) => T, ...preset: P): (...args: R) => T;
+/**
+ * The opposite of a predicate.
  *
  * @example
- * const isOdd = nodeComfort.func.negate((n) => n % 2 === 0);
+ * files.filter(func.negate((name) => name.startsWith(".")));
  *
- * @param {(...args: any[]) => boolean} predicate - Predicate to negate.
- * @returns {(...args: any[]) => boolean} The negated predicate.
+ * @template {any[]} A
+ * @param {(...args: A) => unknown} predicate
+ * @returns {(...args: A) => boolean}
  */
-export function negate(predicate: (...args: any[]) => boolean): (...args: any[]) => boolean;
+export function negate<A extends any[]>(predicate: (...args: A) => unknown): (...args: A) => boolean;
 /**
- * Wraps a function so that it is only actually invoked from the `n`-th call on.
+ * Does nothing for the first `n - 1` calls, then calls `fn` every time.
  *
  * @example
- * const save = nodeComfort.func.after(2, () => persist());
- * save(); save(); // persists on the 2nd call
+ * const done = func.after(3, () => console.log("All 3 uploads finished"));
+ * uploads.forEach((upload) => upload.on("end", done));
  *
  * @template {(...args: any[]) => any} F
- * @param {number} n - Number of calls before `fn` fires.
- * @param {F} fn - Function to wrap.
- * @returns {F} The wrapped function.
+ * @param {number} n
+ * @param {F} fn
+ * @returns {(...args: Parameters<F>) => ReturnType<F> | undefined}
  */
-export function after<F extends (...args: any[]) => any>(n: number, fn: F): F;
+export function after<F extends (...args: any[]) => any>(n: number, fn: F): (...args: Parameters<F>) => ReturnType<F> | undefined;
 /**
- * Turns a Node-style callback function (`(err, result) => ...`) into one that
- * returns a Promise.
+ * Calls `fn` for the first `n - 1` calls, then keeps returning the last
+ * result.
  *
  * @example
- * const readFile = nodeComfort.func.promisify(fs.readFile);
- * const data = await readFile("a.txt", "utf8");
+ * const tryLogin = func.before(4, login); // 3 real attempts at most
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {number} n
+ * @param {F} fn
+ * @returns {(...args: Parameters<F>) => ReturnType<F> | undefined}
+ */
+export function before<F extends (...args: any[]) => any>(n: number, fn: F): (...args: Parameters<F>) => ReturnType<F> | undefined;
+/**
+ * Does nothing. Useful as a default callback.
  *
- * @param {(...args: any[]) => void} fn - Callback-style function.
- * @returns {(...args: any[]) => Promise<any>} A promise-returning function.
+ * @param {...unknown} _args
+ * @returns {void}
  */
-export function promisify(fn: (...args: any[]) => void): (...args: any[]) => Promise<any>;
+export function noop(..._args: unknown[]): void;
 /**
- * Wraps an async function so it resolves to a `[error, result]` tuple instead
- * of throwing • Go-style error handling.
+ * Returns its argument.
  *
  * @example
- * const [err, user] = await nodeComfort.func.attempt(() => getUser(id))();
- * if (err) return handle(err);
+ * [0, 1, 2].filter(func.identity); // [1, 2]
  *
  * @template T
- * @param {(...args: any[]) => Promise<T>|T} fn - Function to wrap.
- * @returns {(...args: any[]) => Promise<[unknown, T|undefined]>} The safe function.
+ * @param {T} value
+ * @returns {T}
  */
-export function attempt<T>(fn: (...args: any[]) => Promise<T> | T): (...args: any[]) => Promise<[unknown, T | undefined]>;
+export function identity<T>(value: T): T;
 //# sourceMappingURL=Func.d.ts.map