@ix-xs/node-comfort 1.2.0 → 2.1.0

package/types/src/Time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.js"],"names":[],"mappings":";;;;IA2HE;;;;;;;;;OASG;IACH,2BAHW,MAAM,GACJ,UAAU,CAKtB;IAED;;;;;;;;;OASG;IACH,+BAHW,MAAM,GAAC,SAAS,GACd,UAAU,CAKtB;IAED;;;;OAIG;IACH,sBAFa;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAC,SAAS,CAAA;KAAE,CAI1D;IAED;;;;;;;;;;;;OAYG;IACH,8BAHW,MAAM,GAAC,MAAM,GACX,MAAM,GAAC,IAAI,CAkBvB;IAED;;;;;;;;;;;;;;;OAeG;IACH,4BAJW,MAAM,YACN;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACjD,MAAM,CAgClB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,wBALW,IAAI,GAAC,MAAM,GAAC,MAAM,SAClB,IAAI,GAAC,MAAM,GAAC,MAAM,YAClB;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,QAAQ,GAAC,MAAM,CAAA;KAAE,GAC5C,MAAM,CAgClB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,sBALW,IAAI,GAAC,MAAM,GAAC,MAAM,YAClB,MAAM,YACN;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GACpC,MAAM,CA0ClB;IAED;;;;;;;;;;;;;OAaG;IACH,mBALW,IAAI,GAAC,MAAM,GAAC,MAAM,UAClB,MAAM,GAAC,MAAM,SACb,IAAI,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GACtB,IAAI,CAWhB;IAED;;;;;;;OAOG;IACH,wBALW,IAAI,GAAC,MAAM,GAAC,MAAM,UAClB,MAAM,GAAC,MAAM,SACb,IAAI,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GACtB,IAAI,CAMhB;IAED;;;;;;;;;;OAUG;IACH,iBALW,IAAI,GAAC,MAAM,GAAC,MAAM,KAClB,IAAI,GAAC,MAAM,GAAC,MAAM,SAClB,IAAI,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GACtB,MAAM,CAKlB;IAED;;;;;;;;;;OAUG;IACH,sBALW,IAAI,GAAC,MAAM,GAAC,MAAM,KAClB,IAAI,GAAC,MAAM,GAAC,MAAM,YAClB;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GACnB,OAAO,CAOnB;IAED;;;;;;;;;OASG;IACH,uBAJW,IAAI,GAAC,MAAM,GAAC,MAAM,QAClB,MAAM,GAAC,OAAO,GAAC,KAAK,GAAC,MAAM,GAAC,QAAQ,GAAC,QAAQ,GAC3C,IAAI,CAkBhB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;;;;;;;;OAUG;IACH,sBAFa;QAAE,OAAO,EAAE,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,MAAM,GAAC,MAAM,CAAA;KAAE,CAYhF;;;;;;;kBAxcU,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.js"],"names":[],"mappings":"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"}

package/types/src/Utils.d.ts

@@ -1,124 +1,180 @@
 /**
- * Waits for a given number of milliseconds.
- *
- * @example
- * await nodeComfort.wait(500); // waits 500 ms
- *
- * @param {number} ms - Delay in milliseconds.
- * @returns {Promise<void>} A promise that resolves after the delay.
+ * Options for `wait()`.
  */
-export function wait(ms: number): Promise<void>;
+export type WaitOptions = {
+    /**
+     * Cancels the wait; the promise rejects with an `AbortError`.
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * Let the process exit even if the timer is still pending.
+     */
+    unref?: boolean | undefined;
+};
 /**
- * Polls a predicate at a given interval and emits events when it matches or times out.
- *
- * The predicate is evaluated every `options.interval` milliseconds (default: 50 ms).
- * Be careful with the default interval: 50 ms is very frequent polling and can be
- * unnecessarily CPU‑intensive if your predicate or trigger handlers are heavy.
- * When `options.max` is `null`, the predicate can match indefinitely (infinite triggers),
- * so you should choose an interval that makes sense for your use‑case.
- *
- * A `when(...)` task is one‑shot: once it has been stopped (manually or via `max`/`timeout`),
- * calling `.start()` again on the same task will not restart it.
- *
- * @param {boolean|Promise<boolean>|(() => boolean|Promise<boolean>)} predicate
- *        Condition to evaluate at each tick, or a function returning it.
- * @param {*} [payload={}]
- *        Value passed to listeners when events are emitted (e.g. an object or message).
- * @param {object} [options]
- * @param {number} [options.interval=50]
- *        Polling interval in milliseconds. Increase this value if your predicate is
- *        expensive or you expect many triggers without a `max` limit.
- * @param {number|null} [options.timeout=null]
- *        Maximum time in milliseconds before emitting a "timeout" event and stopping.
- *        If `null`, no timeout is applied.
- * @param {number|null} [options.max=null]
- *        Maximum number of successful predicate evaluations ("trigger" events) before
- *        automatically stopping. If `null`, triggers are infinite until `stop()` is called.
+ * Options for `when()`.
+ */
+export type WhenOptions = {
+    /**
+     * Time between two checks, in ms or like `"1s"`. Defaults to `50`.
+     */
+    interval?: string | number | undefined;
+    /**
+     * Give up after this long, in ms or like `"10s"`, and emit `"timeout"`.
+     */
+    timeout?: string | number | null | undefined;
+    /**
+     * Stop after this many triggers.
+     */
+    max?: number | null | undefined;
+};
+/**
+ * The task returned by `when()`. Every method returns the task, so calls chain.
+ */
+export type WhenTask = {
+    /**
+     * Starts checking. A stopped task can't be restarted.
+     */
+    start: () => WhenTask;
+    /**
+     * Stops checking and clears the timers.
+     */
+    stop: () => WhenTask;
+    /**
+     * Listens to `"trigger"` (the condition is true), `"error"` (it threw) or `"timeout"`.
+     */
+    on: <E extends "trigger" | "error" | "timeout">(event: E, handler: E extends "error" ? (error: unknown) => void : (payload: any) => void) => WhenTask;
+};
+/**
+ * Events you can customize on `dontCrash()`.
+ */
+export type DontCrashEvent = "error" | "exit" | "sig" | "beforeExit";
+/**
+ * Returned by `dontCrash()`.
+ */
+export type DontCrashController = {
+    /**
+     * Replaces the handler for an event. Call it without a handler to restore the default one.
+     */
+    on: <E extends DontCrashEvent>(event: E, handler?: E extends "error" ? (error: unknown) => void : E extends "sig" ? (signal: NodeJS.Signals) => void : (code: number) => void) => DontCrashController;
+    /**
+     * Removes everything `dontCrash()` installed.
+     */
+    dispose: () => void;
+};
+/**
+ * Options for `wait()`.
+ * @typedef {object} WaitOptions
+ * @property {AbortSignal} [signal] Cancels the wait; the promise rejects with an `AbortError`.
+ * @property {boolean} [unref] Let the process exit even if the timer is still pending.
+ */
+/**
+ * Options for `when()`.
+ * @typedef {object} WhenOptions
+ * @property {number | string} [interval] Time between two checks, in ms or like `"1s"`. Defaults to `50`.
+ * @property {number | string | null} [timeout] Give up after this long, in ms or like `"10s"`, and emit `"timeout"`.
+ * @property {number | null} [max] Stop after this many triggers.
+ */
+/**
+ * The task returned by `when()`. Every method returns the task, so calls chain.
+ * @typedef {object} WhenTask
+ * @property {() => WhenTask} start Starts checking. A stopped task can't be restarted.
+ * @property {() => WhenTask} stop Stops checking and clears the timers.
+ * @property {<E extends "trigger" | "error" | "timeout">(event: E, handler: E extends "error" ? (error: unknown) => void : (payload: any) => void) => WhenTask} on Listens to `"trigger"` (the condition is true), `"error"` (it threw) or `"timeout"`.
+ */
+/**
+ * Events you can customize on `dontCrash()`.
+ * @typedef {"error" | "exit" | "sig" | "beforeExit"} DontCrashEvent
+ */
+/**
+ * Returned by `dontCrash()`.
+ * @typedef {object} DontCrashController
+ * @property {<E extends DontCrashEvent>(event: E, handler?: E extends "error" ? (error: unknown) => void : E extends "sig" ? (signal: NodeJS.Signals) => void : (code: number) => void) => DontCrashController} on Replaces the handler for an event. Call it without a handler to restore the default one.
+ * @property {() => void} dispose Removes everything `dontCrash()` installed.
+ */
+/**
+ * Resolves after a delay, given in milliseconds or as a duration string.
  *
  * @example
- * // Basic usage: infinite triggers every 50 ms (default interval) – use with caution.
- * const task = nodeComfort.when(() => true, { message: "Ok" });
- *
- * task
- *   .on("trigger", (payload) => {
- *     console.log(payload.message);
- *     // task.stop(); // stop when you’re done
- *   })
- *   .start();
+ * await nc.wait(500);
+ * await nc.wait("2s");
+ * await nc.wait("1m", { signal: controller.signal });
+ *
+ * @param {number | string} duration Milliseconds, or a string like `"250ms"`, `"2s"`, `"1m30s"`.
+ * @param {WaitOptions} [options]
+ * @returns {Promise<void>}
+ * @throws {AbortError} If the signal is aborted.
+ * @throws {TypeError} If the duration can't be parsed.
+ */
+export function wait(duration: number | string, options?: WaitOptions): Promise<void>;
+/**
+ * Checks a condition at a regular interval and tells you when it's true.
+ * Call `.start()` once your listeners are in place. If you just want to
+ * await a condition, `nc.async.poll()` is simpler.
  *
  * @example
- * // Safer usage: limit triggers and/or lower polling frequency.
- * nodeComfort.when(() => true, { message: "Ok" }, { max: 1, interval: 500 })
- *   .on("trigger", (payload) => {
- *     console.log(payload.message);
- *   })
- *   .on("timeout", (payload) => {
- *     console.log("Timed out", payload);
- *   })
+ * nc.when(() => queue.length > 0, { reason: "jobs waiting" }, { interval: 500, max: 1, timeout: "10s" })
+ *   .on("trigger", (payload) => nc.info(payload.reason))
+ *   .on("timeout", () => nc.warn("Nothing happened in 10s"))
  *   .start();
  *
- * @returns {{
- *   start: () => any,
- *   stop: () => any,
- *   on: <E extends "error"|"trigger"|"timeout">(event: E, handler: E extends "error"
- *       ? (error: unknown) => void|Promise<void>
- *       : (payload: any) => void|Promise<void>) => any
- * }} A small task controller with `start`, `stop` and `on`.
+ * @param {boolean | PromiseLike<boolean> | (() => unknown)} predicate The condition, or a function (sync or async) that returns it.
+ * @param {any} [payload={}] Passed to the `"trigger"` and `"timeout"` listeners.
+ * @param {WhenOptions} [options]
+ * @returns {WhenTask}
  */
-export function when(predicate: boolean | Promise<boolean> | (() => boolean | Promise<boolean>), payload?: any, options?: {
-    interval?: number | undefined;
-    timeout?: number | null | undefined;
-    max?: number | null | undefined;
-}): {
-    start: () => any;
-    stop: () => any;
-    on: <E extends "error" | "trigger" | "timeout">(event: E, handler: E extends "error" ? (error: unknown) => void | Promise<void> : (payload: any) => void | Promise<void>) => any;
-};
+export function when(predicate: boolean | PromiseLike<boolean> | (() => unknown), payload?: any, options?: WhenOptions): WhenTask;
 /**
- * Installs process-level safety nets for errors, exits and signals.
- *
- * By default, it:
- * - logs uncaught exceptions and unhandled rejections,
- * - logs process exit codes,
- * - logs SIGINT/SIGTERM/SIGQUIT and exits with code 0.
+ * Keeps the process alive when something goes wrong. Uncaught exceptions and
+ * unhandled rejections are logged instead of crashing, and `SIGINT`/`SIGTERM`
+ * are logged before a clean exit. Customize any of it with `.on()`.
  *
- * You can override each handler with `.on(event, handler)`.
- *
- * @example
- * // Use defaults:
- * nodeComfort.dontCrash();
+ * Only its own handlers are ever removed; listeners added by your code or by
+ * other libraries are left alone.
  *
  * @example
- * // Custom error handler:
- * nodeComfort.dontCrash().on("error", (err) => {
- *   console.error("Global error:", err);
- *   process.exit(1);
- * });
- *
- * @returns {{
- *   on: <E extends "error"|"exit"|"sig"|"beforeExit">(event: E, handler?: (
- *     E extends "error" ? (error: Error|unknown) => void|Promise<void> :
- *     E extends "exit" ? (code: number) => void|Promise<void> :
- *     E extends "sig" ? (signal: "SIGINT"|"SIGTERM"|"SIGQUIT") => void|Promise<void> :
- *     (code: number) => void|Promise<void>
- *   )) => any
- * }} A small controller to configure global handlers.
+ * nc.dontCrash()
+ *   .on("error", (error) => sentry.captureException(error))
+ *   .on("sig", async () => {
+ *     await server.close();
+ *     process.exit(0);
+ *   });
+ *
+ * @returns {DontCrashController}
  */
-export function dontCrash(): {
-    on: <E extends "error" | "exit" | "sig" | "beforeExit">(event: E, handler?: (E extends "error" ? (error: Error | unknown) => void | Promise<void> : E extends "exit" ? (code: number) => void | Promise<void> : E extends "sig" ? (signal: "SIGINT" | "SIGTERM" | "SIGQUIT") => void | Promise<void> : (code: number) => void | Promise<void>)) => any;
-};
+export function dontCrash(): DontCrashController;
 /**
- * Safely stringifies a value to pretty-printed JSON (4 spaces indent).
+ * `JSON.stringify` that never throws. Circular references become
+ * `"[Circular]"`, bigints become strings, Maps become objects, Sets become
+ * arrays, and errors keep their name, message and stack.
  *
- * @param {*} value - Value to stringify.
- * @returns {string} JSON string representation.
+ * @example
+ * nc.JSONString({ a: 1 });                          // '{\n    "a": 1\n}'
+ * nc.JSONString({ id: 10n, tags: new Set(["x"]) }, 0); // '{"id":"10","tags":["x"]}'
+ * nc.JSONString({ error: new Error("boom") }, 0);   // '{"error":{"name":"Error","message":"boom","stack":"..."}}'
+ *
+ * @param {unknown} value
+ * @param {number} [spaces=4] Indentation. Use `0` for a single line.
+ * @returns {string} The JSON text, or `"undefined"` for values JSON can't represent.
  */
-export function JSONString(value: any): string;
+export function JSONString(value: unknown, spaces?: number): string;
 /**
- * Parses a JSON string.
+ * `JSON.parse` with an optional fallback. With a fallback, invalid input
+ * returns it instead of throwing. A leading byte order mark, which Windows
+ * editors like to add, is ignored.
  *
- * @param {string} value - JSON string to parse.
- * @returns {*} Parsed value.
+ * @example
+ * nc.JSONParse('{"a":1}');    // { a: 1 }
+ * nc.JSONParse("oops", null); // null
+ * nc.JSONParse("oops");       // throws SyntaxError
+ * nc.JSONParse(text, {}, (key, value) => (key === "at" ? new Date(value) : value));
+ *
+ * @template [T=any]
+ * @param {string} text
+ * @param {T} [fallback] Returned when `text` isn't valid JSON.
+ * @param {(this: any, key: string, value: any) => any} [reviver] Passed to `JSON.parse`.
+ * @returns {T}
+ * @throws {SyntaxError} If `text` is invalid and there's no fallback.
  */
-export function JSONParse(value: string): any;
+export function JSONParse<T = any>(text: string, fallback?: T, reviver?: (this: any, key: string, value: any) => any, ...args: any[]): T;
 //# sourceMappingURL=Utils.d.ts.map

package/types/src/Utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Utils.d.ts","sourceRoot":"","sources":["../../src/Utils.js"],"names":[],"mappings":"AAME;;;;;;;;GAQG;AACH,yBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAIzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,gCA7CW,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,CAAC,MAAM,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,CAAC,YAEzD,GAAC,YAGT;IAAyB,QAAQ;IAGH,OAAO;IAGP,GAAG;CAIjC,GAsBU;IACR,KAAK,EAAE,MAAM,GAAG,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,CAAC;IAChB,EAAE,EAAE,CAAC,CAAC,SAAS,OAAO,GAAC,SAAS,GAAC,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,SAAS,OAAO,GAC1E,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GACtC,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,CAAA;CACnD,CAsIH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,6BATa;IACR,EAAE,EAAE,CAAC,CAAC,SAAS,OAAO,GAAC,MAAM,GAAC,KAAK,GAAC,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CACpE,CAAC,SAAS,OAAO,GAAG,CAAC,KAAK,EAAE,KAAK,GAAC,OAAO,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GAChE,CAAC,SAAS,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GACvD,CAAC,SAAS,KAAK,GAAG,CAAC,MAAM,EAAE,QAAQ,GAAC,SAAS,GAAC,SAAS,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GACpF,CAAO,IAAI,EAAE,MAAM,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,CACrC,KAAK,GAAG,CAAA;CACV,CAiEH;AAED;;;;;GAKG;AACH,kCAHW,GAAC,GACC,MAAM,CAIlB;AAED;;;;;GAKG;AACH,iCAHW,MAAM,GACJ,GAAC,CAIb"}
+{"version":3,"file":"Utils.d.ts","sourceRoot":"","sources":["../../src/Utils.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAgCc,MAAM,QAAQ;;;;UACd,MAAM,QAAQ;;;;QACd,CAAC,CAAC,SAAS,SAAS,GAAG,OAAO,GAAG,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,SAAS,OAAO,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,KAAK,QAAQ;;;;;6BAKlJ,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,YAAY;;;;;;;;QAMtC,CAAC,CAAC,SAAS,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,OAAO,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,CAAC,SAAS,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,KAAK,mBAAmB;;;;aACjM,MAAM,IAAI;;AAhCxB;;;;;GAKG;AAEH;;;;;;GAMG;AAEH;;;;;;GAMG;AAEH;;;GAGG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;;;GAaG;AACH,+BANW,MAAM,GAAG,MAAM,YACf,WAAW,GACT,OAAO,CAAC,IAAI,CAAC,CAazB;AAED;;;;;;;;;;;;;;;GAeG;AACH,gCALW,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,YAChD,GAAG,YACH,WAAW,GACT,QAAQ,CAuEpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,6BAFa,mBAAmB,CAoE/B;AAKD;;;;;;;;;;;;;GAaG;AACH,kCAJW,OAAO,WACP,MAAM,GACJ,MAAM,CA6BlB;AAgBD;;;;;;;;;;;;;;;;;GAiBG;AACH,0BAPc,CAAC,cACJ,MAAM,aACN,CAAC,YACD,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG,mBACzC,CAAC,CAWb"}

package/types/src/errors.d.ts

@@ -0,0 +1,316 @@
+/**
+ * Options shared by every error constructor.
+ */
+export type NodeComfortErrorOptions = {
+    /**
+     * Machine-readable code, like `"ETIMEDOUT"`.
+     */
+    code?: string | undefined;
+    /**
+     * The error that caused this one, kept as `error.cause`.
+     */
+    cause?: unknown;
+};
+/**
+ * One problem found while validating data.
+ */
+export type ValidationIssue = {
+    /**
+     * Where the problem is, like `["user", "emails", 0]`. Empty for the root value.
+     */
+    path: Array<string | number>;
+    /**
+     * What went wrong: `"invalid_type"`, `"too_small"`, `"invalid_string"`, `"custom"`...
+     */
+    code: string;
+    /**
+     * A message you can show to users.
+     */
+    message: string;
+    /**
+     * The expected type, for type errors.
+     */
+    expected?: string | undefined;
+    /**
+     * The received type, for type errors.
+     */
+    received?: string | undefined;
+};
+/**
+ * The errors node-comfort throws when something goes wrong at run time: a
+ * request fails, data is invalid, a command exits badly. They all extend
+ * `NodeComfortError` (itself a regular `Error`) and carry a stable `code`,
+ * so you can branch on the kind of failure without parsing messages.
+ *
+ * A mistake in your own code, like a wrong argument, still throws a plain
+ * `TypeError` or `RangeError`, as it does everywhere in JavaScript.
+ *
+ * @example
+ * try {
+ *   await nc.http.get("https://api.example.com/users/42");
+ * } catch (error) {
+ *   if (error instanceof nc.errors.HttpError && error.status === 404) return null;
+ *   throw error;
+ * }
+ */
+/**
+ * Options shared by every error constructor.
+ * @typedef {object} NodeComfortErrorOptions
+ * @property {string} [code] Machine-readable code, like `"ETIMEDOUT"`.
+ * @property {unknown} [cause] The error that caused this one, kept as `error.cause`.
+ */
+/**
+ * Base class of every node-comfort error. `name` is the class name and
+ * `code` a stable identifier.
+ *
+ * @example
+ * if (error instanceof nc.errors.NodeComfortError) logger.warn(error.code);
+ */
+export class NodeComfortError extends Error {
+    /**
+     * Makes `instanceof` work when two copies of the package are installed,
+     * which would otherwise give two unrelated `HttpError` classes.
+     *
+     * @override
+     * @param {unknown} value
+     * @returns {boolean}
+     */
+    static override [Symbol.hasInstance](value: unknown): boolean;
+    /**
+     * @param {string} message
+     * @param {NodeComfortErrorOptions} [options]
+     */
+    constructor(message: string, options?: NodeComfortErrorOptions);
+    /** Stable, machine-readable code. */
+    code: string;
+    /**
+     * What `JSON.stringify()` writes for the error: its name, code, message
+     * and own fields, without the stack. Handy for API responses and logs.
+     *
+     * @example
+     * res.status(400).json({ error });
+     * // {"error":{"name":"ValidationError","code":"ERR_VALIDATION","message":"...","issues":[...]}}
+     *
+     * @returns {Record<string, unknown>}
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Thrown by `nc.assert()` and `nc.assertType()`.
+ *
+ * @example
+ * nc.assert(user, "User is required");
+ */
+export class AssertionError extends NodeComfortError {
+    /**
+     * @param {string} [message="Assertion failed"]
+     * @param {NodeComfortErrorOptions} [options]
+     */
+    constructor(message?: string, options?: NodeComfortErrorOptions);
+}
+/**
+ * Thrown when something takes too long: `func.timeout`, `async.poll`, HTTP
+ * requests, `emitter.waitFor`...
+ *
+ * @example
+ * try {
+ *   await nc.func.timeout(slowTask(), 1000);
+ * } catch (error) {
+ *   if (error instanceof nc.errors.TimeoutError) console.log(`Gave up after ${error.timeout}ms`);
+ * }
+ */
+export class TimeoutError extends NodeComfortError {
+    /**
+     * @param {string} [message="Operation timed out"]
+     * @param {NodeComfortErrorOptions & { timeout?: number }} [options] Can include the time limit in milliseconds.
+     */
+    constructor(message?: string, options?: NodeComfortErrorOptions & {
+        timeout?: number;
+    });
+    /** The time limit in milliseconds, when known. */
+    timeout: number | undefined;
+}
+/**
+ * Thrown when an operation is cancelled with an `AbortSignal`. Its name is
+ * `"AbortError"`, like native abort errors, so existing checks keep working.
+ */
+export class AbortError extends NodeComfortError {
+    /**
+     * @param {string} [message="The operation was aborted"]
+     * @param {NodeComfortErrorOptions} [options] Usually `{ cause: signal.reason }`.
+     */
+    constructor(message?: string, options?: NodeComfortErrorOptions);
+}
+/**
+ * One problem found while validating data.
+ * @typedef {object} ValidationIssue
+ * @property {Array<string|number>} path Where the problem is, like `["user", "emails", 0]`. Empty for the root value.
+ * @property {string} code What went wrong: `"invalid_type"`, `"too_small"`, `"invalid_string"`, `"custom"`...
+ * @property {string} message A message you can show to users.
+ * @property {string} [expected] The expected type, for type errors.
+ * @property {string} [received] The received type, for type errors.
+ */
+/**
+ * Thrown when data doesn't match a schema or when environment variables are
+ * invalid. `issues` lists every problem, not just the first one.
+ *
+ * @example
+ * try {
+ *   User.parse(body);
+ * } catch (error) {
+ *   if (error instanceof nc.errors.ValidationError) return res.status(400).json(error.flatten());
+ *   throw error;
+ * }
+ */
+export class ValidationError extends NodeComfortError {
+    /**
+     * Turns issues into a readable message, one line per issue.
+     *
+     * @param {ValidationIssue[]} issues
+     * @returns {string}
+     */
+    static format(issues: ValidationIssue[]): string;
+    /**
+     * @param {ValidationIssue[]} issues
+     * @param {NodeComfortErrorOptions & { message?: string }} [options]
+     */
+    constructor(issues: ValidationIssue[], options?: NodeComfortErrorOptions & {
+        message?: string;
+    });
+    /** Every problem found, in order. */
+    issues: ValidationIssue[];
+    /**
+     * Groups messages by path, which is handy for forms.
+     *
+     * @example
+     * error.flatten(); // { email: ["Invalid email address"], age: ["Must be at least 18"] }
+     *
+     * @returns {Record<string, string[]>} Messages by dotted path (`""` for the root).
+     */
+    flatten(): Record<string, string[]>;
+}
+/**
+ * Thrown by `nc.http` when the response status isn't 2xx (unless you pass
+ * `throwHttpErrors: false`), and for network failures (`status` 0).
+ *
+ * @example
+ * try {
+ *   await nc.http.get(url);
+ * } catch (error) {
+ *   if (error instanceof nc.errors.HttpError) console.log(error.status, error.data);
+ * }
+ */
+export class HttpError extends NodeComfortError {
+    /**
+     * @param {string} message
+     * @param {NodeComfortErrorOptions & { status?: number, statusText?: string, url?: string, method?: string, headers?: Record<string, string>, data?: unknown }} [options]
+     */
+    constructor(message: string, options?: NodeComfortErrorOptions & {
+        status?: number;
+        statusText?: string;
+        url?: string;
+        method?: string;
+        headers?: Record<string, string>;
+        data?: unknown;
+    });
+    /** HTTP status, like `404`. `0` when no response came back. */
+    status: number;
+    /** HTTP status text, like `"Not Found"`. */
+    statusText: string;
+    /** The requested URL. */
+    url: string;
+    /** The HTTP method, like `"GET"`. */
+    method: string;
+    /** Response headers, with lower-cased names. */
+    headers: Record<string, string>;
+    /** The response body: parsed JSON when possible, text otherwise. */
+    data: unknown;
+}
+/**
+ * Thrown by `nc.crypto.verifyJWT()`. The `code` tells you why:
+ * `ERR_JWT_MALFORMED`, `ERR_JWT_ALGORITHM`, `ERR_JWT_SIGNATURE`,
+ * `ERR_JWT_EXPIRED`, `ERR_JWT_NOT_BEFORE` or `ERR_JWT_CLAIM`.
+ *
+ * @example
+ * try {
+ *   return nc.crypto.verifyJWT(token, secret);
+ * } catch (error) {
+ *   if (error.code === "ERR_JWT_EXPIRED") return refreshSession();
+ *   throw error;
+ * }
+ */
+export class JWTError extends NodeComfortError {
+    /**
+     * @param {string} message
+     * @param {NodeComfortErrorOptions & { expiredAt?: Date }} [options]
+     */
+    constructor(message: string, options?: NodeComfortErrorOptions & {
+        expiredAt?: Date;
+    });
+    /** When the token expired. Only set for `ERR_JWT_EXPIRED`. */
+    expiredAt: Date | undefined;
+}
+/**
+ * Thrown by `nc.sys.run()` and `nc.sys.exec()` when a command fails, is
+ * killed or times out. Its output is kept on the error.
+ *
+ * @example
+ * try {
+ *   await nc.sys.run("git", ["push"]);
+ * } catch (error) {
+ *   console.error(error.exitCode, error.stderr);
+ * }
+ */
+export class ProcessError extends NodeComfortError {
+    /**
+     * @param {string} message
+     * @param {NodeComfortErrorOptions & { command?: string, exitCode?: number | null, signal?: string | null, stdout?: string, stderr?: string, timedOut?: boolean }} [options]
+     */
+    constructor(message: string, options?: NodeComfortErrorOptions & {
+        command?: string;
+        exitCode?: number | null;
+        signal?: string | null;
+        stdout?: string;
+        stderr?: string;
+        timedOut?: boolean;
+    });
+    /** The command that ran. */
+    command: string;
+    /** Exit code, or `null` if a signal killed the process. */
+    exitCode: number | null;
+    /** The signal that killed the process, like `"SIGTERM"`. */
+    signal: string | null;
+    /** Everything written to stdout. */
+    stdout: string;
+    /** Everything written to stderr. */
+    stderr: string;
+    /** `true` if the process was killed for exceeding its `timeout`. */
+    timedOut: boolean;
+}
+/**
+ * Thrown by `nc.SQLite` when a statement fails. Check `sqliteCode` to handle
+ * specific cases like a duplicate value.
+ *
+ * @example
+ * try {
+ *   db.insert("users", { email });
+ * } catch (error) {
+ *   if (error.sqliteCode === "SQLITE_CONSTRAINT_UNIQUE") return "Email already taken";
+ *   throw error;
+ * }
+ */
+export class SQLiteError extends NodeComfortError {
+    /**
+     * @param {string} message
+     * @param {NodeComfortErrorOptions & { sql?: string, sqliteCode?: string }} [options]
+     */
+    constructor(message: string, options?: NodeComfortErrorOptions & {
+        sql?: string;
+        sqliteCode?: string;
+    });
+    /** The SQL that failed, when there is one. */
+    sql: string | undefined;
+    /** SQLite's error code, like `"SQLITE_CONSTRAINT_UNIQUE"`, when known. */
+    sqliteCode: string | undefined;
+}
+//# sourceMappingURL=errors.d.ts.map

package/types/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.js"],"names":[],"mappings":"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"}