@ix-xs/node-comfort 2.1.0 → 2.2.0

package/src/Str.js

@@ -87,6 +87,13 @@
  * @typedef {object} ClosestOptions
  * @property {number} [threshold] Minimum similarity (0 to 1) to accept a match. Defaults to `0.4`.
  * @property {boolean} [caseSensitive] Take case into account.
+ * @property {number} [maxDistance] Ignore candidates more than this many edits away. The search also gets faster.
+ */
+
+/**
+ * Options for `levenshtein()`.
+ * @typedef {object} LevenshteinOptions
+ * @property {number} [maxDistance] Stop counting past this many edits, which is much faster on long texts. A larger distance then comes back as `maxDistance + 1`.
  */
 
 /**
@@ -108,13 +115,14 @@ const SPECIAL_LATIN = /[\u00df\u1e9e\u00e6\u00c6\u0153\u0152\u00f8\u00d8\u0111\u
 const HTML_UNSAFE = /[&<>"']/;
 const HTML_UNSAFE_ALL = /[&<>"']/g;
 const HTML_ESCAPES = /** @type {Record<string, string>} */ ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" });
-const HTML_ENTITIES = /** @type {Record<string, string>} */ ({
+// No prototype, so "&constructor;" finds nothing.
+const HTML_ENTITIES = /** @type {Record<string, string>} */ (Object.assign(Object.create(null), {
   amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: "\u00a0",
   copy: "\u00a9", reg: "\u00ae", trade: "\u2122", hellip: "\u2026", mdash: "\u2014", ndash: "\u2013",
   lsquo: "\u2018", rsquo: "\u2019", ldquo: "\u201c", rdquo: "\u201d", laquo: "\u00ab", raquo: "\u00bb",
   euro: "\u20ac", pound: "\u00a3", yen: "\u00a5", cent: "\u00a2", deg: "\u00b0", middot: "\u00b7",
   bull: "\u2022", times: "\u00d7", divide: "\u00f7", sect: "\u00a7", para: "\u00b6",
-});
+}));
 const TEMPLATE_DEFAULT = /\{\s*([\w$.-]+)\s*\}/g;
 /** @type {Map<string, RegExp>} */
 const _templateRegexes = new Map();
@@ -133,7 +141,8 @@ const _SPECIAL_LATIN = /** @type {Record<string, string>} */ ({
 const _words = (input) =>
   String(input)
     .replace(/(\p{Ll}|\p{N})(\p{Lu})/gu, "$1 $2")
-    .replace(/(\p{Lu}+)(\p{Lu}\p{Ll})/gu, "$1 $2")
+    // A lookahead, not "(\p{Lu}+)(\p{Lu}\p{Ll})": that one is quadratic on a long run of capitals.
+    .replace(/(\p{Lu})(?=\p{Lu}\p{Ll})/gu, "$1 ")
     .replace(/[^\p{L}\p{N}]+/gu, " ")
     .trim()
     .split(/\s+/)
@@ -182,45 +191,65 @@ const _templateValue = (value, key) => {
   return typeof found === "function" ? undefined : found;
 };
 
-/** One row of the edit-distance table, reused between calls. */
+/** One row of the edit-distance table, reused between calls for short texts. */
 let _row = new Uint32Array(64);
+/** Longer rows are allocated for the call, so a huge text doesn't keep its memory. */
+const _ROW_REUSE = 4096;
 
 /**
- * Levenshtein distance between two sequences of characters.
+ * Levenshtein distance between two sequences of characters. Past `max`, it
+ * stops and returns `max + 1`.
  * @param {ArrayLike<string>} s
  * @param {ArrayLike<string>} t
+ * @param {number} [max]
  * @returns {number}
  */
-const _distance = (s, t) => {
+const _distance = (s, t, max = Infinity) => {
+  // The row follows the shorter text.
+  if (t.length > s.length) [s, t] = [t, s];
   let sLength = s.length;
   let tLength = t.length;
+  if (sLength - tLength > max) return max + 1;
   let start = 0;
-  while (start < sLength && start < tLength && s[start] === t[start]) start++;
-  while (sLength > start && tLength > start && s[sLength - 1] === t[tLength - 1]) {
+  while (start < tLength && s[start] === t[start]) start++;
+  while (tLength > start && s[sLength - 1] === t[tLength - 1]) {
     sLength--;
     tLength--;
   }
   sLength -= start;
   tLength -= start;
-  if (sLength === 0) return tLength;
-  if (tLength === 0) return sLength;
-  if (_row.length <= tLength) _row = new Uint32Array(tLength * 2);
-  const row = _row;
+  if (tLength === 0) return sLength > max ? max + 1 : sLength;
+  /** @type {Uint32Array} */
+  let row;
+  if (tLength >= _ROW_REUSE) row = new Uint32Array(tLength + 1);
+  else {
+    if (_row.length <= tLength) _row = new Uint32Array(Math.min(tLength * 2, _ROW_REUSE));
+    row = _row;
+  }
   for (let j = 0; j <= tLength; j++) row[j] = j;
+  // Only cells within `max` of the diagonal can stay under `max`: the others are skipped.
+  const banded = max < sLength;
   for (let i = 1; i <= sLength; i++) {
     const char = s[start + i - 1];
-    let diagonal = row[0];
-    row[0] = i;
-    for (let j = 1; j <= tLength; j++) {
+    const from = banded && i > max ? i - max : 1;
+    const to = banded && i + max < tLength ? i + max : tLength;
+    let diagonal = row[from - 1];
+    let left = from === 1 ? i : max + 1;
+    if (from === 1) row[0] = i;
+    let lowest = left;
+    for (let j = from; j <= to; j++) {
       const above = row[j];
       let best = char === t[start + j - 1] ? diagonal : diagonal + 1;
       if (above + 1 < best) best = above + 1;
-      if (row[j - 1] + 1 < best) best = row[j - 1] + 1;
+      if (left + 1 < best) best = left + 1;
       row[j] = best;
+      left = best;
       diagonal = above;
+      if (best < lowest) lowest = best;
     }
+    if (lowest > max) return max + 1;
   }
-  return row[tLength];
+  return row[tLength] > max ? max + 1 : row[tLength];
 };
 
 /**
@@ -426,7 +455,9 @@ function words(input) {
 
 /**
  * Removes accents (`é` becomes `e`) and spells out special Latin letters
- * (`ß` becomes `ss`, `æ` becomes `ae`).
+ * (`ß` becomes `ss`, `æ` becomes `ae`). Look-alike forms become plain ones
+ * too (Unicode NFKD), so a fullwidth `＜` becomes `<`: deburr before
+ * escaping HTML, never after.
  *
  * @example
  * str.deburr("Crème brûlée"); // "Creme brulee"
@@ -490,7 +521,8 @@ function squish(input) {
 
 /**
  * Removes HTML tags and keeps the text. This is not a sanitizer: to show
- * untrusted text in HTML, use `escapeHTML()`.
+ * untrusted text in HTML, use `escapeHTML()`. Broken markup can even leave
+ * a tag behind: `"<<a>script>"` gives `"<script>"`.
  *
  * @example
  * str.stripTags("<p>Hello <b>world</b></p>"); // "Hello world"
@@ -503,7 +535,9 @@ function stripTags(input) {
 }
 
 /**
- * Escapes `& < > " '` so the text is safe inside HTML content and attributes.
+ * Escapes `& < > " '` so the text is safe inside HTML content and quoted
+ * attribute values. It is not enough for an unquoted attribute, a URL
+ * (`javascript:` stays as it is), a script or a style.
  *
  * @example
  * str.escapeHTML('<a href="x">Tom & Jerry</a>');
@@ -895,12 +929,14 @@ function reverse(input) {
 }
 
 /**
- * Hides part of a string, like a card number or a token.
+ * Hides part of a string, like a card number or a token. When `start` and
+ * `end` would leave the whole text visible, all of it is hidden instead.
  *
  * @example
  * str.mask("4242424242424242");                           // "************4242"
  * str.mask("4242 4242 4242 4242", { keepSpaces: true });   // "**** **** **** 4242"
  * str.mask("secret-token", { start: 2, end: 2, char: "•" }); // "se••••••••en"
+ * str.mask("1234");                                         // "****"
  *
  * @param {unknown} input
  * @param {MaskOptions} [options]
@@ -908,10 +944,11 @@ function reverse(input) {
  */
 function mask(input, options = {}) {
   const chars = _graphemes(String(input));
-  const start = Math.max(0, options.start ?? 0);
-  const end = Math.max(0, options.end ?? 4);
+  let start = Math.max(0, options.start ?? 0);
+  let end = Math.max(0, options.end ?? 4);
   const char = options.char ?? "*";
-  if (start + end >= chars.length) return chars.join("");
+  // Too short to show anything safely: hide it all rather than reveal it all.
+  if (start + end >= chars.length) start = end = 0;
   return chars
     .map((c, i) => {
       if (i < start || i >= chars.length - end) return c;
@@ -965,7 +1002,8 @@ function plural(value, forms, options = {}) {
 
 /**
  * Fills `{placeholders}` with values. Dotted paths like `{user.name}` work,
- * and missing values are left alone unless you give a `fallback`.
+ * and missing values are left alone unless you give a `fallback`. Values
+ * are not escaped: to build HTML, pass them through `escapeHTML()` first.
  *
  * @example
  * str.template("Hi {name}, you have {count} messages", { name: "Jo", count: 3 });
@@ -1091,18 +1129,23 @@ function compare(a, b, options = {}) {
 
 /**
  * The number of single-character edits needed to turn `a` into `b`.
+ * The work grows with the product of both lengths: on long or untrusted
+ * texts, set `maxDistance`.
  *
  * @example
- * str.levenshtein("kitten", "sitting"); // 3
+ * str.levenshtein("kitten", "sitting");                     // 3
+ * str.levenshtein("kitten", "sitting", { maxDistance: 1 }); // 2, which means "more than 1"
  *
  * @param {unknown} a
  * @param {unknown} b
+ * @param {LevenshteinOptions} [options]
  * @returns {number}
  */
-function levenshtein(a, b) {
+function levenshtein(a, b, options = {}) {
   const x = String(a);
   const y = String(b);
-  return x === y ? 0 : _distance(_units(x), _units(y));
+  const max = options.maxDistance;
+  return x === y ? 0 : _distance(_units(x), _units(y), max === undefined || !(max >= 0) ? Infinity : Math.floor(max));
 }
 
 /**
@@ -1140,6 +1183,7 @@ function similarity(a, b) {
  */
 function closest(input, candidates, options = {}) {
   const threshold = options.threshold ?? 0.4;
+  const maxDistance = options.maxDistance === undefined || !(options.maxDistance >= 0) ? Infinity : Math.floor(options.maxDistance);
   const norm = (/** @type {string} */ s) => (options.caseSensitive ? s : s.toLowerCase());
   const needle = _units(norm(String(input)));
   let best;
@@ -1149,7 +1193,11 @@ function closest(input, candidates, options = {}) {
     const longest = Math.max(needle.length, units.length);
     // The length gap alone bounds the score: skip candidates that can't win.
     if (longest > 0 && 1 - Math.abs(needle.length - units.length) / longest <= bestScore) continue;
-    const score = longest === 0 ? 1 : 1 - _distance(needle, units) / longest;
+    // Neither can a candidate further away than the threshold or the best so far allows (rounded up, to stay exact).
+    const max = Math.min(maxDistance, Math.ceil((1 - Math.max(threshold, bestScore)) * longest));
+    const distance = longest === 0 ? 0 : _distance(needle, units, max);
+    if (distance > max) continue;
+    const score = longest === 0 ? 1 : 1 - distance / longest;
     if (score > bestScore) {
       bestScore = score;
       best = candidate;

package/src/Sys.js

@@ -18,7 +18,7 @@ const fs = require("node:fs");
 const os = require("node:os");
 const nodePath = require("node:path");
 const { ProcessError, AbortError } = require("./errors.js");
-const { toMs } = require("./internal/shared.js");
+const { toMs, disposable } = require("./internal/shared.js");
 
 // Loaded on first use: most programs never start another one.
 /** @type {typeof import("node:child_process") | undefined} */
@@ -30,14 +30,14 @@ const _cp = () => (_childProcess ??= require("node:child_process"));
  * @typedef {object} RunOptions
  * @property {string} [cwd] Where to run the command.
  * @property {Record<string, string | undefined>} [env] Extra environment variables, added to `process.env`. `undefined` removes one.
- * @property {boolean} [extendEnv] Set to `false` to pass only `env`, without `process.env`.
+ * @property {boolean} [extendEnv] Set to `false` to pass only `env`, without `process.env`. Without `env`, the command then gets an empty environment.
  * @property {string | Buffer} [input] Written to the command's stdin.
  * @property {number | string} [timeout] Kill the command after this long, like `"30s"`. On Windows, what it started is stopped with it.
  * @property {AbortSignal} [signal] Kills the command when aborted. On Windows, what it started is stopped with it.
  * @property {"pipe" | "inherit"} [stdio] `"inherit"` shows the output live instead of capturing it. Defaults to `"pipe"`.
  * @property {(line: string) => void} [onStdout] Called for each line of stdout.
  * @property {(line: string) => void} [onStderr] Called for each line of stderr.
- * @property {boolean} [reject] Throw when the exit code isn't 0. Defaults to `true`.
+ * @property {boolean} [reject] Reject when the exit code isn't 0. Defaults to `true`.
  * @property {boolean} [trim] Drop the final newline of the output. Defaults to `true`.
  */
 
@@ -66,6 +66,19 @@ const _cp = () => (_childProcess ??= require("node:child_process"));
  * @typedef {NodeJS.Signals | "shutdown"} ShutdownReason
  */
 
+/**
+ * Options for `which()`.
+ * @typedef {object} WhichOptions
+ * @property {string} [cwd] Where a relative path like `"./bin/tool"`, or a relative folder in `PATH`, is looked up from. Defaults to `process.cwd()`.
+ */
+
+/**
+ * Options for `open()`.
+ * @typedef {object} OpenOptions
+ * @property {string[]} [protocols] The URL schemes that may be opened, like `"https:"` or `"vscode:"`. Defaults to `["http:", "https:", "mailto:"]`: `file:`, `search-ms:` and the schemes other apps register can start programs, so they're refused unless you name them. An allowed `file:` URL is checked like a path.
+ * @property {boolean} [allowUNC] Allow a Windows network path like `\\server\share\file`. Defaults to `false`: just looking one up can send your Windows credentials to that server.
+ */
+
 /**
  * Returned by `info()`.
  * @typedef {object} SystemInfo
@@ -101,18 +114,58 @@ const _escapeArg = (arg, doubleEscape) => {
   return doubleEscape ? out.replace(META, "^$1") : out;
 };
 
+/** @type {Map<string, boolean>} */
+const _forwarding = new Map();
+
+/**
+ * Does this batch file pass its arguments on with `%*`? cmd.exe then reads
+ * them a second time, so they need a second escape.
+ * @param {string} file
+ * @returns {boolean}
+ */
+const _forwardsArgs = (file) => {
+  const known = _forwarding.get(file);
+  if (known !== undefined) return known;
+  let forwards = /node_modules[\\/]\.bin[\\/]/i.test(file);
+  if (!forwards) {
+    try {
+      const head = Buffer.alloc(8192);
+      const fd = fs.openSync(file, "r");
+      try {
+        forwards = /%\*/.test(head.toString("latin1", 0, fs.readSync(fd, head, 0, head.length, 0)));
+      } finally {
+        fs.closeSync(fd);
+      }
+    } catch {
+      // Unreadable: the second escape is the one that lets nothing through.
+      forwards = true;
+    }
+  }
+  if (_forwarding.size >= 200) _forwarding.clear();
+  _forwarding.set(file, forwards);
+  return forwards;
+};
+
 /**
  * Handles Windows `.cmd` and `.bat` files.
  * @param {string} file
  * @param {string[]} args
+ * @param {string | undefined} cwd
+ * @param {string} display
  * @returns {{ file: string, args: string[], verbatim: boolean }}
  */
-const _prepare = (file, args) => {
+const _prepare = (file, args, cwd, display) => {
   if (process.platform !== "win32") return { file, args, verbatim: false };
-  const resolved = which(file) ?? file;
+  const resolved = which(file, { cwd }) ?? file;
   if (!/\.(cmd|bat)$/i.test(resolved)) return { file: resolved, args, verbatim: false };
-  const shim = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i.test(resolved);
-  const line = [_escapeCommand(nodePath.normalize(resolved)), ...args.map((a) => _escapeArg(a, shim))].join(" ");
+  const forwards = _forwardsArgs(resolved);
+  for (const arg of args) {
+    // Like Rust, refuse what cmd.exe can't be given safely: it ends the command
+    // at a line break, and a file that reads %1 splits quotes its own way.
+    if (/[\r\n]/.test(arg)) throw new ProcessError(`Can't pass a line break to a batch file: ${display}`, { command: display });
+    if (!forwards && arg.includes('"')) throw new ProcessError(`Can't pass a quote to a batch file that doesn't use %*: ${display}`, { command: display });
+  }
+  const line = [_escapeCommand(nodePath.normalize(resolved)), ...args.map((a) => _escapeArg(a, forwards))].join(" ");
   return { file: process.env.comspec || "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], verbatim: true };
 };
 
@@ -121,7 +174,7 @@ const _prepare = (file, args) => {
  * @returns {Record<string, string | undefined> | undefined}
  */
 const _env = (options) => {
-  if (options.extendEnv === false) return options.env;
+  if (options.extendEnv === false) return options.env ?? {};
   if (!options.env) return process.env;
   /** @type {Record<string, string | undefined>} */
   const merged = { ...process.env };
@@ -145,7 +198,7 @@ const _spawn = (file, args, shell, display, options) =>
   new Promise((resolve, reject) => {
     const started = Date.now();
     const inherit = options.stdio === "inherit";
-    const prepared = shell ? { file, args, verbatim: false } : _prepare(file, args);
+    const prepared = shell ? { file, args, verbatim: false } : _prepare(file, args, options.cwd, display);
     const timeoutMs = options.timeout === undefined ? undefined : toMs(options.timeout, "timeout");
     if (options.signal?.aborted) return reject(new AbortError(`Command aborted: ${display}`, { cause: options.signal.reason }));
 
@@ -266,7 +319,7 @@ const _spawn = (file, args, shell, display, options) =>
  * @param {string[]} [args=[]]
  * @param {RunOptions} [options]
  * @returns {Promise<RunResult>}
- * @throws {ProcessError} If it can't start, fails (unless `reject: false`) or times out.
+ * @throws {ProcessError} If it can't start, fails (unless `reject: false`) or times out. On Windows, also when a `.cmd` or `.bat` file would get an argument with a line break, or with a quote when the file doesn't pass its arguments on with `%*`: cmd.exe can't be given those safely.
  */
 function run(file, args = [], options = {}) {
   const display = [file, ...args.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a))].join(" ");
@@ -305,20 +358,24 @@ const _runnable = (file) => {
 };
 
 /**
- * Finds an executable in `PATH`, like the `which` command.
+ * Finds an executable in `PATH`, like the `which` command. A path, like
+ * `"./bin/tool"`, is looked up from `cwd` instead.
  *
  * @example
  * sys.which("git");  // "/usr/bin/git"
  * sys.which("nope"); // undefined
+ * sys.which("./tool", { cwd: "./app" });
  *
  * @param {string} command
+ * @param {WhichOptions} [options]
  * @returns {string | undefined}
  */
-function which(command) {
+function which(command, options = {}) {
   if (typeof command !== "string" || !command) return undefined;
   const isWin = process.platform === "win32";
   const searchPath = process.env.PATH ?? process.env.Path ?? "";
-  const key = `${command}\0${searchPath}\0${process.cwd()}`;
+  const cwd = nodePath.resolve(options.cwd ?? process.cwd());
+  const key = `${command}\0${searchPath}\0${cwd}`;
   const known = _found.get(key);
   // A found program is checked again with one call, in case it was removed since.
   if (known !== undefined && _runnable(known)) return known;
@@ -327,11 +384,11 @@ function which(command) {
   /** @type {string | undefined} */
   let found;
   if (command.includes("/") || command.includes("\\")) {
-    found = candidates(nodePath.resolve(command)).find(_runnable);
+    found = candidates(nodePath.resolve(cwd, command)).find(_runnable);
   } else {
     for (const dir of searchPath.split(nodePath.delimiter)) {
       if (!dir) continue;
-      found = candidates(nodePath.join(dir.replace(/^"|"$/g, ""), command)).find(_runnable);
+      found = candidates(nodePath.resolve(cwd, dir.replace(/^"|"$/g, ""), command)).find(_runnable);
       if (found) break;
     }
   }
@@ -345,20 +402,64 @@ function which(command) {
 }
 
 /**
- * Opens a URL, file or folder with the default app.
+ * The absolute path that `open()` may hand to the opener.
+ * @param {string} target
+ * @param {OpenOptions} options
+ * @returns {string}
+ */
+const _openPath = (target, options) => {
+  const full = nodePath.resolve(target);
+  // Checked before anything touches the disk: looking up a network path is enough to leak credentials.
+  if (process.platform === "win32" && /^[\\/]{2}/.test(full) && !options.allowUNC) {
+    throw new TypeError(`open(): network paths are refused without allowUNC: ${full}`);
+  }
+  try {
+    fs.statSync(full);
+  } catch (error) {
+    throw new Error(`open(): no file or folder at ${full}`, { cause: error });
+  }
+  return full;
+};
+
+/**
+ * Opens a URL, file or folder with the default app. Only `http:`,
+ * `https:` and `mailto:` URLs are opened unless you allow more with
+ * `protocols`; anything else is a path, which must exist. A program is
+ * started, as with a double click: don't pass a path you didn't choose.
  *
  * @example
  * sys.open("http://localhost:3000");
+ * sys.open("./report.html");
+ * sys.open("vscode://file/C:/app/index.js", { protocols: ["vscode:"] });
  *
- * @param {string} target
+ * @param {string} target A URL, or the path of a file or folder.
+ * @param {OpenOptions} [options]
  * @returns {boolean} `true` if the opener started.
+ * @throws {TypeError} If the URL's scheme isn't allowed, the target holds a control character (or a double quote, on Windows), or it's a network path without `allowUNC`.
+ * @throws {Error} If the path doesn't exist.
  */
-function open(target) {
+function open(target, options = {}) {
+  if (typeof target !== "string" || !target) throw new TypeError("open(): expected a URL or a path");
+  // Control characters have no business in a URL or a file name.
+  if (/[\x00-\x1f\x7f]/.test(target)) throw new TypeError(`open(): control characters are refused: ${JSON.stringify(target)}`);
+  // A quote ends the target early for Windows' start. open and xdg-open get it as an argument, and it's legal in a file name there.
+  if (process.platform === "win32" && target.includes('"')) throw new TypeError(`open(): quotes are refused on Windows: ${JSON.stringify(target)}`);
+  const allowed = (options.protocols ?? ["http:", "https:", "mailto:"]).map((p) => String(p).toLowerCase().replace(/:?$/, ":"));
+  /** @type {string} */
+  let value;
+  // A single letter before the colon is a Windows drive, not a scheme.
+  if (/^[a-z][a-z\d+.-]+:/i.test(target)) {
+    const url = new URL(target);
+    if (!allowed.includes(url.protocol)) throw new TypeError(`open(): the ${url.protocol} scheme isn't allowed (allowed: ${allowed.join(", ")})`);
+    // href encodes spaces and quotes, so the opener gets a single argument.
+    value = url.protocol === "file:" ? _openPath(require("node:url").fileURLToPath(url), options) : url.href;
+  } else {
+    value = _openPath(target, options);
+  }
   try {
-    const value = /^[a-z][a-z\d+.-]*:/i.test(target) ? target : nodePath.resolve(target);
     const child =
       process.platform === "win32"
-        ? _cp().spawn(process.env.comspec || "cmd.exe", ["/d", "/s", "/c", `start "" ${_escapeArg(value, false)}`], { detached: true, stdio: "ignore", windowsHide: true, windowsVerbatimArguments: true })
+        ? _cp().spawn(process.env.comspec || "cmd.exe", ["/d", "/s", "/c", `start "" ${`"${value}"`.replace(META, "^$1")}`], { detached: true, stdio: "ignore", windowsHide: true, windowsVerbatimArguments: true })
         : _cp().spawn(process.platform === "darwin" ? "open" : "xdg-open", [value], { detached: true, stdio: "ignore" });
     child.on("error", () => {});
     child.unref();
@@ -389,7 +490,7 @@ const _shutdownConfig = { timeout: 10_000, exitCode: 0 };
  *
  * @param {(reason: ShutdownReason) => unknown} handler Can be async. Gets the signal that stopped the process.
  * @param {ShutdownOptions} [options]
- * @returns {() => void} Removes the handler.
+ * @returns {(() => void) & Disposable} Removes the handler. With `using`, at the end of the block.
  */
 function onShutdown(handler, options = {}) {
   if (options.timeout !== undefined) _shutdownConfig.timeout = toMs(options.timeout, "timeout");
@@ -407,10 +508,10 @@ function onShutdown(handler, options = {}) {
       // unsupported signal on this platform
     }
   }
-  return () => {
+  return disposable(() => {
     const index = _shutdownHandlers.lastIndexOf(handler);
     if (index !== -1) _shutdownHandlers.splice(index, 1);
-  };
+  });
 }
 
 /**