@ix-xs/node-comfort 2.0.0 → 2.1.0

package/src/Utils.js

@@ -9,8 +9,8 @@
  * const settings = nc.JSONParse(text, {});
  */
 
-const { AbortError } = require("./errors.js");
 const { types } = require("node:util");
+const { sleep, toMs } = require("./internal/shared.js");
 
 /**
  * Options for `wait()`.
@@ -22,8 +22,8 @@ const { types } = require("node:util");
 /**
  * Options for `when()`.
  * @typedef {object} WhenOptions
- * @property {number} [interval] Milliseconds between two checks. Defaults to `50`.
- * @property {number | null} [timeout] Give up after this many milliseconds and emit `"timeout"`.
+ * @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.
  */
 
@@ -62,22 +62,14 @@ const { types } = require("node:util");
  * @throws {TypeError} If the duration can't be parsed.
  */
 function wait(duration, options = {}) {
-  const ms = typeof duration === "number" ? duration : require("./Time.js").parseDuration(duration);
-  if (ms === null || !Number.isFinite(ms)) return Promise.reject(new TypeError(`Invalid duration: ${String(duration)}`));
-  const { signal } = options;
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) return reject(new AbortError(undefined, { cause: signal.reason }));
-    const onAbort = () => {
-      clearTimeout(timer);
-      reject(new AbortError(undefined, { cause: signal?.reason }));
-    };
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, Math.max(0, ms));
-    if (options.unref) timer.unref();
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
+  let ms;
+  try {
+    ms = toMs(duration);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+  if (!Number.isFinite(ms)) return Promise.reject(new TypeError(`Invalid duration: ${String(duration)}`));
+  return sleep(ms, options.signal, options.unref ?? false);
 }
 
 /**
@@ -86,7 +78,7 @@ function wait(duration, options = {}) {
  * await a condition, `nc.async.poll()` is simpler.
  *
  * @example
- * nc.when(() => queue.length > 0, { reason: "jobs waiting" }, { interval: 500, max: 1, timeout: 10_000 })
+ * 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();
@@ -97,8 +89,8 @@ function wait(duration, options = {}) {
  * @returns {WhenTask}
  */
 function when(predicate, payload = {}, options = {}) {
-  const interval = options.interval ?? 50;
-  const timeout = options.timeout ?? null;
+  const interval = options.interval === undefined ? 50 : toMs(options.interval, "interval");
+  const timeout = options.timeout === undefined || options.timeout === null ? null : toMs(options.timeout, "timeout");
   const max = options.max ?? null;
   /** @type {Record<"trigger" | "error" | "timeout", Set<Function>>} */
   const listeners = { trigger: new Set(), error: new Set(), timeout: new Set() };
@@ -258,12 +250,13 @@ let _dontCrashDispose;
 
 /**
  * `JSON.stringify` that never throws. Circular references become
- * `"[Circular]"`, bigints become strings, Maps become objects and Sets become
- * arrays.
+ * `"[Circular]"`, bigints become strings, Maps become objects, Sets become
+ * arrays, and errors keep their name, message and stack.
  *
  * @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.
@@ -272,41 +265,69 @@ let _dontCrashDispose;
 function JSONString(value, spaces = 4) {
   /** @type {Array<[holder: object, original: object]>} ancestors of the value being serialized */
   const stack = [];
-  const text = JSON.stringify(
-    value,
-    /** @this {any} */ function(_, raw) {
-      if (typeof raw === "bigint") return raw.toString();
-      if (raw === null || typeof raw !== "object") return raw;
-      while (stack.length && stack[stack.length - 1][0] !== this) stack.pop();
-      if (stack.some(([, original]) => original === raw)) return "[Circular]";
-      const v = types.isMap(raw) ? Object.fromEntries(raw) : types.isSet(raw) ? [...raw] : raw;
-      stack.push([v, raw]);
-      return v;
-    },
-    spaces,
-  );
+  let text;
+  try {
+    text = JSON.stringify(
+      value,
+      /** @this {any} */ function(_, raw) {
+        if (typeof raw === "bigint") return raw.toString();
+        if (raw === null || typeof raw !== "object") return raw;
+        while (stack.length && stack[stack.length - 1][0] !== this) stack.pop();
+        for (let i = 0; i < stack.length; i++) if (stack[i][1] === raw) return "[Circular]";
+        const v = types.isMap(raw) ? Object.fromEntries(raw) : types.isSet(raw) ? [...raw] : types.isNativeError(raw) ? _plainError(raw) : raw;
+        stack.push([v, raw]);
+        return v;
+      },
+      spaces,
+    );
+  } catch (error) {
+    // A getter or a toJSON() threw: describe the value instead of failing.
+    try {
+      text = JSON.stringify(require("node:util").inspect(value, { depth: 4, breakLength: Infinity }));
+    } catch {
+      text = JSON.stringify(`[Unserializable: ${error instanceof Error ? error.message : String(error)}]`);
+    }
+  }
   return text ?? String(text);
 }
 
+/**
+ * The fields of an error that `JSON.stringify` would drop.
+ * @param {Error} error
+ * @returns {Record<string, unknown>}
+ */
+const _plainError = (error) => {
+  /** @type {Record<string, unknown>} */
+  const out = { name: error.name, message: error.message };
+  for (const key of Object.keys(error)) out[key] = /** @type {any} */ (error)[key];
+  if (error.cause !== undefined) out.cause = error.cause;
+  if (error.stack) out.stack = error.stack;
+  return out;
+};
+
 /**
  * `JSON.parse` with an optional fallback. With a fallback, invalid input
- * returns it instead of throwing.
+ * returns it instead of throwing. A leading byte order mark, which Windows
+ * editors like to add, is ignored.
  *
  * @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.
  */
-function JSONParse(text, fallback) {
-  if (arguments.length < 2) return JSON.parse(text);
+function JSONParse(text, fallback, reviver) {
+  const clean = typeof text === "string" && text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+  if (arguments.length < 2) return JSON.parse(clean);
   try {
-    return JSON.parse(text);
+    return JSON.parse(clean, reviver);
   } catch {
     return /** @type {T} */ (fallback);
   }

package/src/errors.js

@@ -1,9 +1,13 @@
 "use strict";
 
 /**
- * The errors node-comfort throws. 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.
+ * 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 {
@@ -40,6 +44,40 @@ class NodeComfortError extends Error {
     /** Stable, machine-readable code. */
     this.code = options.code ?? "ERR_NODE_COMFORT";
   }
+
+  /**
+   * 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() {
+    /** @type {Record<string, unknown>} */
+    const out = { name: this.name, code: this.code, message: this.message };
+    for (const key of Object.keys(this)) if (!(key in out)) out[key] = /** @type {any} */ (this)[key];
+    const cause = /** @type {any} */ (this.cause);
+    if (cause !== undefined) out.cause = cause instanceof Error ? { name: cause.name, message: cause.message, code: /** @type {any} */ (cause).code } : cause;
+    return out;
+  }
+
+  /**
+   * 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 [Symbol.hasInstance](value) {
+    if (Function.prototype[Symbol.hasInstance].call(this, value)) return true;
+    const brand = Symbol.for(`@ix-xs/node-comfort/${this.name}`);
+    if (!Object.prototype.hasOwnProperty.call(this.prototype, brand)) return false;
+    return value !== null && typeof value === "object" && /** @type {any} */ (value)[brand] === true;
+  }
 }
 
 /**
@@ -54,7 +92,7 @@ class AssertionError extends NodeComfortError {
    * @param {NodeComfortErrorOptions} [options]
    */
   constructor(message = "Assertion failed", options = {}) {
-    super(message, { code: "ERR_ASSERTION", ...options });
+    super(message, { ...options, code: options.code ?? "ERR_ASSERTION" });
   }
 }
 
@@ -75,7 +113,7 @@ class TimeoutError extends NodeComfortError {
    * @param {NodeComfortErrorOptions & { timeout?: number }} [options] Can include the time limit in milliseconds.
    */
   constructor(message = "Operation timed out", options = {}) {
-    super(message, { code: "ETIMEDOUT", ...options });
+    super(message, { ...options, code: options.code ?? "ETIMEDOUT" });
     /** The time limit in milliseconds, when known. */
     this.timeout = options.timeout;
   }
@@ -91,7 +129,7 @@ class AbortError extends NodeComfortError {
    * @param {NodeComfortErrorOptions} [options] Usually `{ cause: signal.reason }`.
    */
   constructor(message = "The operation was aborted", options = {}) {
-    super(message, { code: "ABORT_ERR", ...options });
+    super(message, { ...options, code: options.code ?? "ABORT_ERR" });
   }
 }
 
@@ -123,7 +161,7 @@ class ValidationError extends NodeComfortError {
    * @param {NodeComfortErrorOptions & { message?: string }} [options]
    */
   constructor(issues, options = {}) {
-    super(options.message ?? ValidationError.format(issues), { code: "ERR_VALIDATION", ...options });
+    super(options.message ?? ValidationError.format(issues), { ...options, code: options.code ?? "ERR_VALIDATION" });
     /** Every problem found, in order. */
     this.issues = issues;
   }
@@ -179,7 +217,7 @@ class HttpError extends NodeComfortError {
    * @param {NodeComfortErrorOptions & { status?: number, statusText?: string, url?: string, method?: string, headers?: Record<string, string>, data?: unknown }} [options]
    */
   constructor(message, options = {}) {
-    super(message, { code: "ERR_HTTP", ...options });
+    super(message, { ...options, code: options.code ?? "ERR_HTTP" });
     /** HTTP status, like `404`. `0` when no response came back. */
     this.status = options.status ?? 0;
     /** HTTP status text, like `"Not Found"`. */
@@ -214,7 +252,7 @@ class JWTError extends NodeComfortError {
    * @param {NodeComfortErrorOptions & { expiredAt?: Date }} [options]
    */
   constructor(message, options = {}) {
-    super(message, { code: "ERR_JWT", ...options });
+    super(message, { ...options, code: options.code ?? "ERR_JWT" });
     /** When the token expired. Only set for `ERR_JWT_EXPIRED`. */
     this.expiredAt = options.expiredAt;
   }
@@ -237,7 +275,7 @@ class ProcessError extends NodeComfortError {
    * @param {NodeComfortErrorOptions & { command?: string, exitCode?: number | null, signal?: string | null, stdout?: string, stderr?: string, timedOut?: boolean }} [options]
    */
   constructor(message, options = {}) {
-    super(message, { code: options.timedOut ? "ETIMEDOUT" : "ERR_PROCESS", ...options });
+    super(message, { ...options, code: options.code ?? (options.timedOut ? "ETIMEDOUT" : "ERR_PROCESS") });
     /** The command that ran. */
     this.command = options.command ?? "";
     /** Exit code, or `null` if a signal killed the process. */
@@ -271,7 +309,7 @@ class SQLiteError extends NodeComfortError {
    * @param {NodeComfortErrorOptions & { sql?: string, sqliteCode?: string }} [options]
    */
   constructor(message, options = {}) {
-    super(message, { code: "ERR_SQLITE", ...options });
+    super(message, { ...options, code: options.code ?? "ERR_SQLITE" });
     /** The SQL that failed, when there is one. */
     this.sql = options.sql;
     /** SQLite's error code, like `"SQLITE_CONSTRAINT_UNIQUE"`, when known. */
@@ -279,6 +317,11 @@ class SQLiteError extends NodeComfortError {
   }
 }
 
+const _classes = [NodeComfortError, AssertionError, TimeoutError, AbortError, ValidationError, HttpError, JWTError, ProcessError, SQLiteError];
+for (const Class of _classes) {
+  Object.defineProperty(Class.prototype, Symbol.for(`@ix-xs/node-comfort/${Class.name}`), { value: true });
+}
+
 module.exports = {
   NodeComfortError,
   AssertionError,