@ix-xs/node-comfort 2.1.1 → 2.2.0

package/src/Time.js

@@ -17,9 +17,10 @@
 const { types } = require("node:util");
 
 /**
- * A date: a `Date`, a timestamp in ms, or a string `new Date()` understands
- * (ISO 8601 is safest).
- * @typedef {Date | number | string} DateInput
+ * A date: a `Date`, a timestamp in ms, a string `new Date()` understands
+ * (ISO 8601 is safest), or an instant from `Temporal`, like a
+ * `Temporal.Instant` or a `Temporal.ZonedDateTime`.
+ * @typedef {Date | number | string | { readonly epochMilliseconds: number }} DateInput
  */
 
 /**
@@ -117,8 +118,13 @@ const { types } = require("node:util");
  */
 
 /**
- * A schedule returned by `every()` and `cron()`.
- * @typedef {object} ScheduledTask
+ * A schedule returned by `every()` and `cron()`. With `using`, it stops at
+ * the end of the block.
+ * @typedef {_ScheduledTaskMethods & Disposable} ScheduledTask
+ */
+
+/**
+ * @typedef {object} _ScheduledTaskMethods
  * @property {() => void} stop Stops the schedule. A run in progress finishes.
  * @property {() => Date | undefined} next When the next run is planned.
  * @property {() => boolean} isRunning Whether a run is in progress.
@@ -145,7 +151,13 @@ const _config = shared.timeConfig;
  * @param {DateInput | undefined} value
  * @returns {Date}
  */
-const _toDate = (value) => (types.isDate(value) ? new Date(value.getTime()) : value === undefined ? new Date() : new Date(value));
+const _toDate = (value) => {
+  if (types.isDate(value)) return new Date(value.getTime());
+  if (value === undefined) return new Date();
+  // Temporal.Instant and Temporal.ZonedDateTime say which instant they are.
+  if (typeof value === "object" && value !== null && typeof value.epochMilliseconds === "number") return new Date(value.epochMilliseconds);
+  return new Date(/** @type {string | number} */ (value));
+};
 
 /**
  * @param {number} n
@@ -157,6 +169,34 @@ const _pad = (n, len = 2) => String(Math.abs(n)).padStart(len, "0");
 /** @type {Map<string, Intl.DateTimeFormat>} */
 const _dtfCache = new Map();
 
+/**
+ * Temporal, where the runtime has it. Each zone is tried once: one that
+ * Temporal refuses goes through Intl, which then says what is wrong with it.
+ * @type {any}
+ */
+const _temporal = typeof (/** @type {any} */ (globalThis).Temporal) === "object" ? /** @type {any} */ (globalThis).Temporal : undefined;
+/** @type {Map<string, boolean>} */
+const _temporalZones = new Map();
+/**
+ * @param {string} timeZone
+ * @returns {boolean}
+ */
+const _byTemporal = (timeZone) => {
+  if (!_temporal) return false;
+  let ok = _temporalZones.get(timeZone);
+  if (ok === undefined) {
+    try {
+      _temporal.Instant.fromEpochMilliseconds(0).toZonedDateTimeISO(timeZone);
+      ok = true;
+    } catch {
+      ok = false;
+    }
+    if (_temporalZones.size >= 500) _temporalZones.clear();
+    _temporalZones.set(timeZone, ok);
+  }
+  return ok;
+};
+
 /**
  * Calendar parts of a date in a time zone.
  * @param {Date} d
@@ -170,6 +210,10 @@ const _parts = (d, timeZone) => {
       minute: d.getMinutes(), second: d.getSeconds(), ms: d.getMilliseconds(), weekday: d.getDay(),
     };
   }
+  if (_byTemporal(timeZone)) {
+    const z = _temporal.Instant.fromEpochMilliseconds(d.getTime()).toZonedDateTimeISO(timeZone);
+    return { year: z.year, month: z.month, day: z.day, hour: z.hour, minute: z.minute, second: z.second, ms: z.millisecond, weekday: z.dayOfWeek % 7 };
+  }
   let dtf = _dtfCache.get(timeZone);
   if (!dtf) {
     dtf = new Intl.DateTimeFormat("en-US", {
@@ -196,6 +240,7 @@ const _parts = (d, timeZone) => {
  */
 const _offset = (d, timeZone) => {
   if (!timeZone) return -d.getTimezoneOffset();
+  if (_byTemporal(timeZone)) return Math.round(_temporal.Instant.fromEpochMilliseconds(d.getTime()).toZonedDateTimeISO(timeZone).offsetNanoseconds / 6e10);
   const p = _parts(d, timeZone);
   const asUTC = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second, p.ms);
   return Math.round((asUTC - d.getTime()) / 60_000);
@@ -246,6 +291,16 @@ const _daysIn = (year, month) => (month === 2 ? ((year % 4 === 0 && year % 100 !
 const _instantOf = (year, month, day, hour, minute, second, ms, timeZone) => {
   if (!timeZone) return new Date(year, month - 1, day, hour, minute, second, ms);
   const guess = Date.UTC(year, month - 1, day, hour, minute, second, ms);
+  if (_byTemporal(timeZone) && Number.isFinite(guess)) {
+    // Date.UTC carries what overflows (day 32, hour 24) like the code below does.
+    const at = new Date(guess);
+    const wall = _temporal.PlainDateTime.from({
+      year: at.getUTCFullYear(), month: at.getUTCMonth() + 1, day: at.getUTCDate(),
+      hour: at.getUTCHours(), minute: at.getUTCMinutes(), second: at.getUTCSeconds(), millisecond: at.getUTCMilliseconds(),
+    });
+    // "compatible": a time that happens twice keeps the first one, a skipped time moves past the gap.
+    return new Date(wall.toZonedDateTime(timeZone, { disambiguation: "compatible" }).epochMilliseconds);
+  }
   // The offsets a day before and a day after frame any clock change.
   const early = guess - _offset(new Date(guess - MS.d), timeZone) * 60_000;
   const late = guess - _offset(new Date(guess + MS.d), timeZone) * 60_000;
@@ -337,6 +392,12 @@ const _addMonths = (d, months, timeZone) => {
   return _instantOf(year, month, Math.min(at.day, _daysIn(year, month)), at.hour, at.minute, at.second, at.ms, timeZone);
 };
 
+const _MAX_DURATION_TEXT = 256;
+
+// One "1.5h" of a text duration, with the spaces, commas and "and" around it.
+// Anchored, and run on what is left of the text: it never starts again further on.
+const _DURATION_TOKEN = /^(?:[\s,]|and)*([-+]?(?:\d+(?:\.\d+)?|\.\d+))\s*([a-zA-Z]+)(?:[\s,]|and)*/;
+
 /**
  * Adds a duration written as text: a fixed one (`"1h30m"`) or one with
  * calendar units (`"1 month"`, `"2y 3d"`).
@@ -347,16 +408,20 @@ const _addMonths = (d, months, timeZone) => {
  * @returns {Date}
  */
 const _addText = (d, text, sign, timeZone) => {
+  // No duration is that long: a longer text is refused before any regex reads it.
+  if (text.length > _MAX_DURATION_TEXT && text.trim().length > _MAX_DURATION_TEXT) throw new TypeError(`Invalid duration: longer than ${_MAX_DURATION_TEXT} characters`);
   const fixed = shared.parseDuration(text);
   // Under a day there is no calendar to follow.
   if (fixed !== null && Math.abs(fixed) < MS.d) return new Date(d.getTime() + sign * fixed);
-  const regex = /([-+]?\d*\.?\d+)\s*([a-zA-Z]+)/g;
   let months = 0;
   let days = 0;
   let ms = 0;
-  let consumed = "";
-  let match;
-  while ((match = regex.exec(text)) !== null) {
+  let tokens = 0;
+  let at = 0;
+  // The tokens must follow each other and cover the whole text.
+  while (at < text.length) {
+    const match = _DURATION_TOKEN.exec(text.slice(at));
+    if (match === null) break;
     const unit = _unit(match[2]);
     if (!unit) break;
     const amount = Number(match[1]);
@@ -364,9 +429,10 @@ const _addText = (d, text, sign, timeZone) => {
     else if (unit === "y") months += amount * 12;
     else if ((unit === "d" || unit === "w") && Number.isInteger(amount)) days += unit === "w" ? amount * 7 : amount;
     else ms += amount * MS[unit];
-    consumed += match[0];
+    tokens++;
+    at += match[0].length;
   }
-  if (!consumed || consumed.replace(/\s+/g, "") !== text.replace(/[\s,]+|and/g, "")) {
+  if (!tokens || at !== text.length) {
     // A bare number of milliseconds, as text.
     if (fixed !== null) return new Date(d.getTime() + sign * fixed);
     throw new TypeError(`Invalid duration: ${JSON.stringify(text)}`);
@@ -802,7 +868,11 @@ function parse(text, pattern, options = {}) {
       if (expression.startsWith("(")) tokens.push(compiled[i]);
       source += expression + escape(compiled[i + 1]);
     }
-    parser = { regex: new RegExp(`^\\s*${source}\\s*$`), tokens };
+    // Spaces at the ends of the text are allowed. Next to a pattern that starts or ends with a space,
+    // that "\s*" would make "\s+\s*", which takes a time that grows with the square of a run of spaces.
+    const lead = source.startsWith("\\s+") ? "" : "\\s*";
+    const trail = source.endsWith("\\s+") ? "" : "\\s*";
+    parser = { regex: new RegExp(`^${lead}${source}${trail}$`), tokens };
     if (_parsers.size >= 200) _parsers.clear();
     _parsers.set(pattern, parser);
   }
@@ -1385,14 +1455,16 @@ function every(interval, task, options = {}) {
   };
   cancel = _longTimeout(tick, nextAt - Date.now(), options.unref ?? false);
 
+  const stop = () => {
+    stopped = true;
+    cancel();
+  };
   return {
-    stop: () => {
-      stopped = true;
-      cancel();
-    },
+    stop,
     next: () => (stopped ? undefined : new Date(nextAt)),
     isRunning: () => running,
     runs: () => runs,
+    [Symbol.dispose]: stop,
   };
 }
 
@@ -1521,15 +1593,17 @@ function cron(expression, task, options = {}) {
     });
   }
 
+  const stop = () => {
+    stopped = true;
+    nextDate = undefined;
+    cancel();
+  };
   return {
-    stop: () => {
-      stopped = true;
-      nextDate = undefined;
-      cancel();
-    },
+    stop,
     next: () => (stopped ? undefined : nextDate),
     isRunning: () => running,
     runs: () => runs,
+    [Symbol.dispose]: stop,
   };
 }
 

package/src/Utils.js

@@ -29,7 +29,12 @@ const { sleep, toMs } = require("./internal/shared.js");
 
 /**
  * The task returned by `when()`. Every method returns the task, so calls chain.
- * @typedef {object} WhenTask
+ * With `using`, it stops at the end of the block.
+ * @typedef {_WhenTaskMethods & Disposable} WhenTask
+ */
+
+/**
+ * @typedef {object} _WhenTaskMethods
  * @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"`.
@@ -41,8 +46,12 @@ const { sleep, toMs } = require("./internal/shared.js");
  */
 
 /**
- * Returned by `dontCrash()`.
- * @typedef {object} DontCrashController
+ * Returned by `dontCrash()`. With `using`, what it installed goes at the end of the block.
+ * @typedef {_DontCrashMethods & Disposable} DontCrashController
+ */
+
+/**
+ * @typedef {object} _DontCrashMethods
  * @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.
  */
@@ -155,6 +164,9 @@ function when(predicate, payload = {}, options = {}) {
       listeners[event]?.add(handler);
       return task;
     },
+    [Symbol.dispose]() {
+      halt();
+    },
   };
   return task;
 }
@@ -239,6 +251,9 @@ function dontCrash() {
       unlisten(installed.map(([event]) => event));
       if (_dontCrashDispose === controller.dispose) _dontCrashDispose = undefined;
     },
+    [Symbol.dispose]() {
+      controller.dispose();
+    },
   };
   _dontCrashDispose = controller.dispose;
   controller.on("error").on("exit").on("sig");

package/src/errors.js

@@ -200,10 +200,65 @@ class ValidationError extends NodeComfortError {
   }
 }
 
+// Query parameters whose value is likely a secret: api_key, access_token, sig, code...
+const SECRET_PARAM = /key|token|secret|password|passwd|pwd|auth|sig|signature|session|credential|code/i;
+// Headers `HttpError.toJSON()` leaves out: cookies and credentials, either way.
+const SECRET_HEADERS = new Set(["set-cookie", "cookie", "authorization", "proxy-authorization", "www-authenticate", "proxy-authenticate", "x-api-key", "x-auth-token", "api-key"]);
+// A body larger than this, in bytes, stays out of `HttpError.toJSON()`.
+const JSON_DATA_LIMIT = 4096;
+
+/** @param {string} name */
+const _decodeName = (name) => {
+  try {
+    return decodeURIComponent(name.replace(/\+/g, " "));
+  } catch {
+    return name;
+  }
+};
+
+/**
+ * A URL with `***` for the values of the query parameters that look secret.
+ * The rest is left exactly as it was.
+ * @param {string} url
+ * @returns {string}
+ */
+const _maskURL = (url) => {
+  const start = url.indexOf("?");
+  if (start === -1) return url;
+  const hash = url.indexOf("#", start);
+  const end = hash === -1 ? url.length : hash;
+  const query = url.slice(start + 1, end).split("&").map((pair) => {
+    const equals = pair.indexOf("=");
+    if (equals === -1 || equals === pair.length - 1) return pair;
+    const name = pair.slice(0, equals);
+    return SECRET_PARAM.test(_decodeName(name)) ? `${name}=***` : pair;
+  });
+  return `${url.slice(0, start + 1)}${query.join("&")}${url.slice(end)}`;
+};
+
+/**
+ * @param {unknown} data
+ * @returns {number} Roughly how many bytes it takes as JSON.
+ */
+const _sizeOf = (data) => {
+  if (data === undefined || data === null) return 0;
+  if (typeof data === "string") return Buffer.byteLength(data);
+  if (ArrayBuffer.isView(data) || data instanceof ArrayBuffer) return data.byteLength;
+  try {
+    return Buffer.byteLength(JSON.stringify(data) ?? "");
+  } catch {
+    return Infinity;
+  }
+};
+
 /**
  * Thrown by `nc.http` when the response status isn't 2xx (unless you pass
  * `throwHttpErrors: false`), and for network failures (`status` 0).
  *
+ * The values of query parameters that look secret (`api_key`, `token`,
+ * `sig`...) read `***` in the message and in `url`, so the error can go to
+ * logs as it is.
+ *
  * @example
  * try {
  *   await nc.http.get(url);
@@ -213,17 +268,18 @@ class ValidationError extends NodeComfortError {
  */
 class HttpError extends NodeComfortError {
   /**
-   * @param {string} message
+   * @param {string} message URLs in it have their secret query values masked.
    * @param {NodeComfortErrorOptions & { status?: number, statusText?: string, url?: string, method?: string, headers?: Record<string, string>, data?: unknown }} [options]
    */
   constructor(message, options = {}) {
-    super(message, { ...options, code: options.code ?? "ERR_HTTP" });
+    // The lookbehind keeps it linear on a long "a.a.a..." (the server picks statusText).
+    super(String(message).replace(/(?<![a-z\d+.-])[a-z][a-z\d+.-]*:\/\/\S+/gi, _maskURL), { ...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"`. */
     this.statusText = options.statusText ?? "";
-    /** The requested URL. */
-    this.url = options.url ?? "";
+    /** The requested URL, with `***` for the values of query parameters that look secret. */
+    this.url = _maskURL(String(options.url ?? ""));
     /** The HTTP method, like `"GET"`. */
     this.method = options.method ?? "GET";
     /** Response headers, with lower-cased names. */
@@ -231,6 +287,21 @@ class HttpError extends NodeComfortError {
     /** The response body: parsed JSON when possible, text otherwise. */
     this.data = options.data;
   }
+
+  /**
+   * Like the base `toJSON()`, without what shouldn't reach a log or an API
+   * response: cookie and credential headers, and a body larger than 4 KB.
+   * `error.headers` and `error.data` themselves stay whole.
+   *
+   * @override
+   * @returns {Record<string, unknown>}
+   */
+  toJSON() {
+    const out = super.toJSON();
+    out.headers = Object.fromEntries(Object.entries(this.headers ?? {}).filter(([name]) => !SECRET_HEADERS.has(name.toLowerCase())));
+    if (_sizeOf(this.data) > JSON_DATA_LIMIT) delete out.data;
+    return out;
+  }
 }
 
 /**

package/src/internal/shared.js

@@ -43,7 +43,20 @@ const UNIT_ALIASES = {
  * @param {string} unit
  * @returns {keyof typeof MS | "M" | "y" | undefined}
  */
-const unitOf = (unit) => UNIT_ALIASES[unit] ?? UNIT_ALIASES[unit.toLowerCase()];
+const unitOf = (unit) => {
+  // Own keys only: "constructor" or "toString" are not units.
+  if (Object.hasOwn(UNIT_ALIASES, unit)) return UNIT_ALIASES[unit];
+  const lower = unit.toLowerCase();
+  return Object.hasOwn(UNIT_ALIASES, lower) ? UNIT_ALIASES[lower] : undefined;
+};
+
+// Longer texts are refused, and never cached: no real duration or cron
+// expression comes close, so they can only be junk or an attack.
+const MAX_TEXT = 256;
+
+// One "1.5h" of a text duration, with the spaces, commas and "and" around it.
+// Sticky, so the tokens must follow each other and cover the whole text.
+const DURATION_TOKEN = /(?:[\s,]|and)*(-?(?:\d+(?:\.\d+)?|\.\d+))\s*([a-zA-Z]+)(?:[\s,]|and)*/y;
 
 /** @type {Map<string, number | null>} */
 const _durations = new Map();
@@ -53,6 +66,7 @@ const _durations = new Map();
  * @returns {number | null}
  */
 const _readDuration = (text) => {
+  if (text.length > MAX_TEXT) return null;
   if (/^[-+]?\d+(?:\.\d+)?$/.test(text)) return Number(text);
 
   const iso = /^([-+])?P(?:(\d+(?:[.,]\d+)?)W)?(?:(\d+(?:[.,]\d+)?)D)?(?:T(?:(\d+(?:[.,]\d+)?)H)?(?:(\d+(?:[.,]\d+)?)M)?(?:(\d+(?:[.,]\d+)?)S)?)?$/i.exec(text);
@@ -70,18 +84,16 @@ const _readDuration = (text) => {
     return sign === "-" ? -total : total;
   }
 
-  const regex = /(-?\d*\.?\d+)\s*([a-zA-Z]+)/g;
   let total = 0;
-  let consumed = "";
   let match;
-  while ((match = regex.exec(text)) !== null) {
+  DURATION_TOKEN.lastIndex = 0;
+  while (DURATION_TOKEN.lastIndex < text.length && (match = DURATION_TOKEN.exec(text)) !== null) {
     const unit = unitOf(match[2]);
     if (!unit || unit === "M" || unit === "y") return null;
     total += Number(match[1]) * MS[unit];
-    consumed += match[0];
   }
-  if (!consumed || consumed.replace(/\s+/g, "") !== text.replace(/[\s,]+|and/g, "")) return null;
-  return total;
+  // A token that doesn't fit stops the loop before the end.
+  return match && DURATION_TOKEN.lastIndex === text.length ? total : null;
 };
 
 /**
@@ -97,8 +109,10 @@ const parseDuration = (input) => {
   const text = input.trim();
   const result = text ? _readDuration(text) : null;
   // Durations are almost always literals, so a handful of entries covers a whole program.
-  if (_durations.size >= 500) _durations.clear();
-  _durations.set(input, result);
+  if (input.length <= MAX_TEXT) {
+    if (_durations.size >= 500) _durations.clear();
+    _durations.set(input, result);
+  }
   return result;
 };
 
@@ -253,6 +267,30 @@ const _identity = (value) => {
   return id;
 };
 
+/**
+ * The replacer of `_keyPart()`. It reads the raw value (JSON has already
+ * called `toJSON()` on the one it passes) and tags it, so `"u"` and
+ * `undefined`, `"i1"` and `1n`, or a date and its ISO string stay apart.
+ * Only plain objects and arrays are read by content: a `Set`, a `Map` or a
+ * class instance is keyed by identity, like at the top level.
+ * @this {any}
+ * @param {string} key
+ * @returns {unknown}
+ */
+const _replacer = function(key) {
+  const value = this[key];
+  switch (typeof value) {
+    case "string": return `s${value}`;
+    case "number": return Number.isFinite(value) && !Object.is(value, -0) ? value : _keyPart(value);
+    case "boolean": return value;
+    case "object": {
+      if (value === null || Array.isArray(value) || isPlainObject(value)) return value;
+      return types.isDate(value) ? `d${value.getTime()}` : `O${_identity(value)}`;
+    }
+    default: return _keyPart(value);
+  }
+};
+
 /**
  * @param {unknown} value
  * @returns {string}
@@ -276,8 +314,9 @@ const _keyPart = (value) => {
       if (types.isDate(object)) return `d${object.getTime()}`;
       if (!Array.isArray(object) && !isPlainObject(object)) return `O${_identity(object)}`;
       try {
-        // The replacer keeps what JSON drops or refuses: undefined, bigint, functions, symbols.
-        return `j${JSON.stringify(object, (_, v) => (v !== null && typeof v === "object" ? v : typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? v : _keyPart(v)))}`;
+        // Every value comes out tagged: strings start with "s", everything JSON
+        // would drop or change (undefined, bigint, dates, NaN...) has its own tag.
+        return `j${JSON.stringify(object, _replacer)}`;
       } catch {
         return `O${_identity(object)}`;
       }
@@ -328,7 +367,9 @@ const _cronSpecs = new Map();
 const parseCron = (expression) => {
   const cached = _cronSpecs.get(expression);
   if (cached) return cached;
-  const text = CRON_MACROS[expression.trim().toLowerCase()] ?? expression.trim();
+  const trimmed = expression.trim();
+  const macro = trimmed.toLowerCase();
+  const text = Object.hasOwn(CRON_MACROS, macro) ? CRON_MACROS[macro] : trimmed;
   const fields = text.split(/\s+/);
   if (fields.length !== 5 && fields.length !== 6) throw new SyntaxError(`Invalid cron expression "${expression}": expected 5 or 6 fields`);
   if (fields.length === 5) fields.unshift("0");
@@ -337,6 +378,8 @@ const parseCron = (expression) => {
     /** @type {Set<number>} */
     const values = new Set();
     for (const part of field.split(",")) {
+      // "*/5/x" or "1-5-x" is a typo, not a step or a range with something extra.
+      if (part.split("/").length > 2 || part.split("/")[0].split("-").length > 2) throw new SyntaxError(`Invalid field "${part}" in cron expression "${expression}"`);
       const [rangePart, stepPart] = part.split("/");
       const step = stepPart === undefined ? 1 : Number(stepPart);
       if (!Number.isInteger(step) || step < 1) throw new SyntaxError(`Invalid step "${part}" in cron expression "${expression}"`);
@@ -379,8 +422,10 @@ const parseCron = (expression) => {
     anyWeekday: fields[5] === "*" || fields[5] === "?",
     lastDay,
   };
-  if (_cronSpecs.size >= 200) _cronSpecs.clear();
-  _cronSpecs.set(expression, spec);
+  if (expression.length <= MAX_TEXT) {
+    if (_cronSpecs.size >= 200) _cronSpecs.clear();
+    _cronSpecs.set(expression, spec);
+  }
   return spec;
 };
 
@@ -393,7 +438,16 @@ const sleepSync = (ms) => {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 };
 
+/**
+ * A function that undoes something, usable with `using` too: the undoing then
+ * happens at the end of the block.
+ * @param {() => void} fn
+ * @returns {(() => void) & Disposable}
+ */
+const disposable = (fn) => /** @type {(() => void) & Disposable} */ (Object.defineProperty(fn, Symbol.dispose, { value: fn }));
+
 module.exports = {
+  disposable,
   UNSAFE_KEYS,
   MS,
   timeConfig,

package/src/internal/terminal.js

@@ -0,0 +1,49 @@
+"use strict";
+
+// What the logger and the CLI print goes through here, so a value can't
+// drive the terminal.
+
+// What a terminal could act on, once colors, links, new lines and tabs are set aside.
+const _UNSAFE = /[\x00-\x08\x0b-\x1f\x7f-\x9f\u{2028}\u{2029}]/u;
+// A whole link (opened, text, closed: one left open would take in everything
+// printed after it), a color, a Windows new line, or one control character.
+const _TERMINAL = /\x1b\]8;[^;\x00-\x1f\x7f-\x9f]*;([^\x00-\x1f\x7f-\x9f]+)(?:\x07|\x1b\\)((?:[^\x00-\x1f\x7f-\x9f\u{2028}\u{2029}]|\x1b\[[\d;:]*m)*?)\x1b\]8;;(?:\x07|\x1b\\)|\x1b\[[\d;:]*m|\r\n|[\x00-\x08\x0b-\x1f\x7f-\x9f\u{2028}\u{2029}]/gu;
+const _SGR = /\x1b\[[\d;:]*m/g;
+/** @type {Record<string, string>} */
+const _NAMED = { "\b": "\\b", "\v": "\\v", "\f": "\\f", "\r": "\\r" };
+
+/**
+ * A control character as text, like `\x1b` or `\r`.
+ * @param {string} char
+ */
+const _visible = (char) => {
+  const code = char.charCodeAt(0);
+  return _NAMED[char] ?? (code > 0xff ? `\\u${code.toString(16).padStart(4, "0")}` : `\\x${code.toString(16).padStart(2, "0")}`);
+};
+
+/** @param {string} match */
+const _keepStyles = (match) => (match.length > 1 ? match : _visible(match));
+
+/**
+ * @param {string} match
+ * @param {string | undefined} url
+ * @param {string} label
+ */
+const _dropStyles = (match, url, label) => {
+  if (url !== undefined) return `${label.replace(_SGR, "")} (${url})`;
+  return match === "\r\n" ? match : match.length > 1 ? "" : _visible(match);
+};
+
+/**
+ * Text that can't drive the terminal: every control character and escape
+ * sequence is shown as text (`\x1b`, `\r`), except new lines, tabs, colors
+ * and whole links like `link()` makes. Without colors, colors are removed
+ * too, and a link becomes `text (url)`. Used by the logger and the CLI on
+ * what they print.
+ * @param {string} text
+ * @param {boolean} colors
+ * @returns {string}
+ */
+const _safe = (text, colors) => (_UNSAFE.test(text) ? text.replace(_TERMINAL, colors ? _keepStyles : _dropStyles) : text);
+
+module.exports = { safe: _safe };