@gtkx/utils 0.21.0 → 1.0.0-rc.1

package/dist/graceful-shutdown.d.ts

@@ -1,70 +1,22 @@
 /**
- * Cross-process graceful shutdown primitive for long-running Node processes.
+ * Maps a terminating signal to its conventional process exit code (130 for `SIGINT`, 143 otherwise),
+ * or 0 when no signal is given.
  *
- * The helper installs `SIGINT`/`SIGTERM`/`SIGHUP` handlers, routes the first
- * delivered signal through a user-supplied close callback, and escalates either
- * on a second `SIGINT` or after a configurable timeout. On completion it calls
- * `process.exit` with the canonical exit code for the signal.
- */
-/**
- * Maps the POSIX signal that ended a process into the exit code shells use to
- * report it. `SIGINT` yields `130` (Ctrl-C), every other tracked signal yields
- * `143` (`SIGTERM`). A `null` signal — i.e. a clean exit — yields `0`.
- *
- * @param signal - The signal name, or `null` for a clean exit.
- * @returns The exit code shells expect for `signal`.
+ * @param signal The signal that triggered termination, or `null`.
  */
 export declare const exitCodeForSignal: (signal: NodeJS.Signals | null) => number;
-/**
- * Caller-supplied behaviour for {@link installGracefulShutdown}.
- */
 export type GracefulShutdownOptions = {
-    /**
-     * Invoked once on the first delivered signal. Its returned promise is
-     * awaited before {@link process.exit} fires; rejection is logged but does
-     * not block the exit.
-     */
     onSignal: (signal: NodeJS.Signals) => void | Promise<void>;
-    /**
-     * Invoked when escalation is required: on a second `SIGINT`, or when
-     * {@link GracefulShutdownOptions.forceKillAfterMs} elapses before the
-     * primary close finishes.
-     */
     onForce?: () => void;
-    /**
-     * Milliseconds to wait for the primary close before invoking `onForce`
-     * and exiting. Defaults to {@link DEFAULT_FORCE_KILL_TIMEOUT_MS}. Set to
-     * `0` to disable timeout-based escalation.
-     */
     forceKillAfterMs?: number;
-    /**
-     * Overrides the exit code computed from the triggering signal. Use this
-     * when the caller wants to propagate a child's own exit code instead.
-     */
-    exitCode?: (signal: NodeJS.Signals) => number;
+    coalesceWindowMs?: number;
+    exitCode?: (signal: NodeJS.Signals, graceful: boolean) => number;
 };
 /**
- * Handle returned by {@link installGracefulShutdown}, used to detach the
- * helper's signal handlers (for example in tests).
- */
-export type GracefulShutdownHandle = {
-    /**
-     * Removes the installed signal handlers and cancels any pending
-     * escalation timer. Idempotent.
-     */
-    uninstall: () => void;
-};
-/**
- * Installs the graceful-shutdown primitive on the current process.
- *
- * On the first matching signal: invokes `onSignal`, optionally schedules
- * `onForce` after `forceKillAfterMs`, awaits the close, then exits. A second
- * `SIGINT` (the canonical "force-kill" gesture) invokes `onForce`
- * immediately. The exit code defaults to {@link exitCodeForSignal} but can
- * be overridden by `exitCode`.
+ * Registers handlers for `SIGINT`, `SIGTERM`, and `SIGHUP` that run the given cleanup callback once
+ * and then exit, forcing exit if a repeated signal arrives or the cleanup exceeds its timeout.
  *
- * @param options - Shutdown behaviour.
- * @returns A handle that detaches the installed signal handlers.
+ * @param options The shutdown callbacks and timing configuration.
  */
-export declare const installGracefulShutdown: (options: GracefulShutdownOptions) => GracefulShutdownHandle;
+export declare const installGracefulShutdown: (options: GracefulShutdownOptions) => void;
 //# sourceMappingURL=graceful-shutdown.d.ts.map

package/dist/graceful-shutdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graceful-shutdown.d.ts","sourceRoot":"","sources":["../src/graceful-shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,MAAM,CAAC,OAAO,GAAG,IAAI,KAAG,MAGjE,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IAClC;;;;OAIG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,MAAM,CAAC;CACjD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACjC;;;OAGG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,uBAAuB,KAAG,sBA8D1E,CAAC"}
+{"version":3,"file":"graceful-shutdown.d.ts","sourceRoot":"","sources":["../src/graceful-shutdown.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,WAAY,MAAM,CAAC,OAAO,GAAG,IAAI,KAAG,MAGjE,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IAClC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,KAAK,MAAM,CAAC;CACpE,CAAC;AAsEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,YAAa,uBAAuB,KAAG,IAc1E,CAAC"}

package/dist/graceful-shutdown.js

@@ -1,94 +1,89 @@
-/**
- * Cross-process graceful shutdown primitive for long-running Node processes.
- *
- * The helper installs `SIGINT`/`SIGTERM`/`SIGHUP` handlers, routes the first
- * delivered signal through a user-supplied close callback, and escalates either
- * on a second `SIGINT` or after a configurable timeout. On completion it calls
- * `process.exit` with the canonical exit code for the signal.
- */
+import { error } from "./log.js";
 const HANDLED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
 const DEFAULT_FORCE_KILL_TIMEOUT_MS = 5000;
+const DEFAULT_COALESCE_WINDOW_MS = 500;
 /**
- * Maps the POSIX signal that ended a process into the exit code shells use to
- * report it. `SIGINT` yields `130` (Ctrl-C), every other tracked signal yields
- * `143` (`SIGTERM`). A `null` signal — i.e. a clean exit — yields `0`.
+ * Maps a terminating signal to its conventional process exit code (130 for `SIGINT`, 143 otherwise),
+ * or 0 when no signal is given.
  *
- * @param signal - The signal name, or `null` for a clean exit.
- * @returns The exit code shells expect for `signal`.
+ * @param signal The signal that triggered termination, or `null`.
  */
 export const exitCodeForSignal = (signal) => {
     if (!signal)
         return 0;
     return signal === "SIGINT" ? 130 : 143;
 };
+const clearTimers = (state) => {
+    if (state.forceTimer) {
+        clearTimeout(state.forceTimer);
+        state.forceTimer = null;
+    }
+    if (state.coalesceTimer) {
+        clearTimeout(state.coalesceTimer);
+        state.coalesceTimer = null;
+    }
+};
+const finish = (state, signal, graceful) => {
+    if (state.exited)
+        return;
+    state.exited = true;
+    clearTimers(state);
+    const { exitCode } = state.options;
+    const code = exitCode ? exitCode(signal, graceful) : graceful ? 0 : exitCodeForSignal(signal);
+    process.exit(code);
+};
+const beginShutdown = (state, signal) => {
+    state.firstSignal = signal;
+    if (state.coalesceWindowMs > 0) {
+        state.coalescing = true;
+        state.coalesceTimer = setTimeout(() => {
+            state.coalescing = false;
+        }, state.coalesceWindowMs);
+        state.coalesceTimer.unref();
+    }
+    if (state.options.onForce && state.forceKillMs > 0) {
+        state.forceTimer = setTimeout(() => {
+            state.options.onForce?.();
+            finish(state, signal, false);
+        }, state.forceKillMs);
+        state.forceTimer.unref();
+    }
+    Promise.resolve()
+        .then(() => state.options.onSignal(signal))
+        .then(() => finish(state, signal, true), (reason) => {
+        error("graceful shutdown failed", reason);
+        finish(state, signal, false);
+    });
+};
+const handle = (state, signal) => {
+    if (state.firstSignal === null) {
+        beginShutdown(state, signal);
+        return;
+    }
+    if (state.coalescing)
+        return;
+    state.options.onForce?.();
+    finish(state, signal, false);
+};
 /**
- * Installs the graceful-shutdown primitive on the current process.
+ * Registers handlers for `SIGINT`, `SIGTERM`, and `SIGHUP` that run the given cleanup callback once
+ * and then exit, forcing exit if a repeated signal arrives or the cleanup exceeds its timeout.
  *
- * On the first matching signal: invokes `onSignal`, optionally schedules
- * `onForce` after `forceKillAfterMs`, awaits the close, then exits. A second
- * `SIGINT` (the canonical "force-kill" gesture) invokes `onForce`
- * immediately. The exit code defaults to {@link exitCodeForSignal} but can
- * be overridden by `exitCode`.
- *
- * @param options - Shutdown behaviour.
- * @returns A handle that detaches the installed signal handlers.
+ * @param options The shutdown callbacks and timing configuration.
  */
 export const installGracefulShutdown = (options) => {
-    const forceKillMs = options.forceKillAfterMs ?? DEFAULT_FORCE_KILL_TIMEOUT_MS;
-    let firstSignal = null;
-    let exited = false;
-    let forceTimer = null;
-    const clearTimer = () => {
-        if (forceTimer) {
-            clearTimeout(forceTimer);
-            forceTimer = null;
-        }
-    };
-    const finish = (signal) => {
-        if (exited)
-            return;
-        exited = true;
-        clearTimer();
-        const code = options.exitCode ? options.exitCode(signal) : exitCodeForSignal(signal);
-        process.exit(code);
+    const state = {
+        options,
+        forceKillMs: options.forceKillAfterMs ?? DEFAULT_FORCE_KILL_TIMEOUT_MS,
+        coalesceWindowMs: options.coalesceWindowMs ?? DEFAULT_COALESCE_WINDOW_MS,
+        firstSignal: null,
+        exited: false,
+        coalescing: false,
+        forceTimer: null,
+        coalesceTimer: null,
     };
-    const handle = (signal) => {
-        if (firstSignal === null) {
-            firstSignal = signal;
-            if (options.onForce && forceKillMs > 0) {
-                forceTimer = setTimeout(() => {
-                    options.onForce?.();
-                    finish(signal);
-                }, forceKillMs);
-                forceTimer.unref?.();
-            }
-            Promise.resolve()
-                .then(() => options.onSignal(signal))
-                .catch((error) => {
-                console.error("Graceful shutdown error:", error);
-            })
-                .finally(() => finish(signal));
-            return;
-        }
-        if (signal === "SIGINT" && firstSignal === "SIGINT") {
-            options.onForce?.();
-            finish(signal);
-        }
-    };
-    const handlers = new Map();
     for (const sig of HANDLED_SIGNALS) {
-        const listener = () => handle(sig);
-        handlers.set(sig, listener);
-        process.on(sig, listener);
+        process.on(sig, () => handle(state, sig));
     }
-    return {
-        uninstall: () => {
-            for (const [sig, listener] of handlers) {
-                process.removeListener(sig, listener);
-            }
-            handlers.clear();
-            clearTimer();
-        },
-    };
 };
 //# sourceMappingURL=graceful-shutdown.js.map

package/dist/graceful-shutdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"graceful-shutdown.js","sourceRoot":"","sources":["../src/graceful-shutdown.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graceful-shutdown.js","sourceRoot":"","sources":["../src/graceful-shutdown.ts"],"names":[],"mappings":"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","sourcesContent":["import { error } from \"./log.js\";\n\nconst HANDLED_SIGNALS = [\"SIGINT\", \"SIGTERM\", \"SIGHUP\"] as const satisfies NodeJS.Signals[];\nconst DEFAULT_FORCE_KILL_TIMEOUT_MS = 5000;\nconst DEFAULT_COALESCE_WINDOW_MS = 500;\n\n/**\n * Maps a terminating signal to its conventional process exit code (130 for `SIGINT`, 143 otherwise),\n * or 0 when no signal is given.\n *\n * @param signal The signal that triggered termination, or `null`.\n */\nexport const exitCodeForSignal = (signal: NodeJS.Signals | null): number => {\n    if (!signal) return 0;\n    return signal === \"SIGINT\" ? 130 : 143;\n};\n\nexport type GracefulShutdownOptions = {\n    onSignal: (signal: NodeJS.Signals) => void | Promise<void>;\n    onForce?: () => void;\n    forceKillAfterMs?: number;\n    coalesceWindowMs?: number;\n    exitCode?: (signal: NodeJS.Signals, graceful: boolean) => number;\n};\n\ntype ShutdownState = {\n    options: GracefulShutdownOptions;\n    forceKillMs: number;\n    coalesceWindowMs: number;\n    firstSignal: NodeJS.Signals | null;\n    exited: boolean;\n    coalescing: boolean;\n    forceTimer: NodeJS.Timeout | null;\n    coalesceTimer: NodeJS.Timeout | null;\n};\n\nconst clearTimers = (state: ShutdownState): void => {\n    if (state.forceTimer) {\n        clearTimeout(state.forceTimer);\n        state.forceTimer = null;\n    }\n    if (state.coalesceTimer) {\n        clearTimeout(state.coalesceTimer);\n        state.coalesceTimer = null;\n    }\n};\n\nconst finish = (state: ShutdownState, signal: NodeJS.Signals, graceful: boolean): void => {\n    if (state.exited) return;\n    state.exited = true;\n    clearTimers(state);\n    const { exitCode } = state.options;\n    const code = exitCode ? exitCode(signal, graceful) : graceful ? 0 : exitCodeForSignal(signal);\n    process.exit(code);\n};\n\nconst beginShutdown = (state: ShutdownState, signal: NodeJS.Signals): void => {\n    state.firstSignal = signal;\n    if (state.coalesceWindowMs > 0) {\n        state.coalescing = true;\n        state.coalesceTimer = setTimeout(() => {\n            state.coalescing = false;\n        }, state.coalesceWindowMs);\n        state.coalesceTimer.unref();\n    }\n    if (state.options.onForce && state.forceKillMs > 0) {\n        state.forceTimer = setTimeout(() => {\n            state.options.onForce?.();\n            finish(state, signal, false);\n        }, state.forceKillMs);\n        state.forceTimer.unref();\n    }\n    Promise.resolve()\n        .then(() => state.options.onSignal(signal))\n        .then(\n            () => finish(state, signal, true),\n            (reason: unknown) => {\n                error(\"graceful shutdown failed\", reason);\n                finish(state, signal, false);\n            },\n        );\n};\n\nconst handle = (state: ShutdownState, signal: NodeJS.Signals): void => {\n    if (state.firstSignal === null) {\n        beginShutdown(state, signal);\n        return;\n    }\n    if (state.coalescing) return;\n    state.options.onForce?.();\n    finish(state, signal, false);\n};\n\n/**\n * Registers handlers for `SIGINT`, `SIGTERM`, and `SIGHUP` that run the given cleanup callback once\n * and then exit, forcing exit if a repeated signal arrives or the cleanup exceeds its timeout.\n *\n * @param options The shutdown callbacks and timing configuration.\n */\nexport const installGracefulShutdown = (options: GracefulShutdownOptions): void => {\n    const state: ShutdownState = {\n        options,\n        forceKillMs: options.forceKillAfterMs ?? DEFAULT_FORCE_KILL_TIMEOUT_MS,\n        coalesceWindowMs: options.coalesceWindowMs ?? DEFAULT_COALESCE_WINDOW_MS,\n        firstSignal: null,\n        exited: false,\n        coalescing: false,\n        forceTimer: null,\n        coalesceTimer: null,\n    };\n    for (const sig of HANDLED_SIGNALS) {\n        process.on(sig, () => handle(state, sig));\n    }\n};\n"]}

package/dist/index.d.ts

@@ -1,7 +1,10 @@
-export type { AnyClass } from "./class.js";
-export { isShallowArrayEqual, isShallowEqual, omit, reverseNumericEnum } from "./collection.js";
-export { errorMessage } from "./error.js";
-export { exitCodeForSignal, type GracefulShutdownHandle, installGracefulShutdown, } from "./graceful-shutdown.js";
-export { quote, toIdentifier } from "./source.js";
-export { toCamelCase, toKebabCase, toPascalCase, toUpperFirst } from "./string.js";
+export { type AnyClass, getParentClass, walkClassChain } from "./class.js";
+export { isSameArray, isShallowEqual, sortStrings, sortStringsBy, uniqBy } from "./collection.js";
+export { errorMessage, formatChildProcessError, normalizeError } from "./error.js";
+export { exitCodeForSignal, installGracefulShutdown } from "./graceful-shutdown.js";
+export { createLogger, debug, error, info, Logger, type LoggerOptions, logger, type OutputStream, warn, } from "./log.js";
+export { packageVersion } from "./package-version.js";
+export { callMethod } from "./reflect.js";
+export { sanitizeIdentifier, sourceStringLiteral, toCamelIdentifier } from "./source.js";
+export { lowerFirst, toCamelCase, toKebabCase, toPascalCase, upperFirst } from "./string.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAChG,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EACH,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,uBAAuB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAClG,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACpF,OAAO,EACH,YAAY,EACZ,KAAK,EACL,KAAK,EACL,IAAI,EACJ,MAAM,EACN,KAAK,aAAa,EAClB,MAAM,EACN,KAAK,YAAY,EACjB,IAAI,GACP,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACzF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,6 +1,10 @@
-export { isShallowArrayEqual, isShallowEqual, omit, reverseNumericEnum } from "./collection.js";
-export { errorMessage } from "./error.js";
-export { exitCodeForSignal, installGracefulShutdown, } from "./graceful-shutdown.js";
-export { quote, toIdentifier } from "./source.js";
-export { toCamelCase, toKebabCase, toPascalCase, toUpperFirst } from "./string.js";
+export { getParentClass, walkClassChain } from "./class.js";
+export { isSameArray, isShallowEqual, sortStrings, sortStringsBy, uniqBy } from "./collection.js";
+export { errorMessage, formatChildProcessError, normalizeError } from "./error.js";
+export { exitCodeForSignal, installGracefulShutdown } from "./graceful-shutdown.js";
+export { createLogger, debug, error, info, Logger, logger, warn, } from "./log.js";
+export { packageVersion } from "./package-version.js";
+export { callMethod } from "./reflect.js";
+export { sanitizeIdentifier, sourceStringLiteral, toCamelIdentifier } from "./source.js";
+export { lowerFirst, toCamelCase, toKebabCase, toPascalCase, upperFirst } from "./string.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAChG,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EACH,iBAAiB,EAEjB,uBAAuB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAClG,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACpF,OAAO,EACH,YAAY,EACZ,KAAK,EACL,KAAK,EACL,IAAI,EACJ,MAAM,EAEN,MAAM,EAEN,IAAI,GACP,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACzF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC","sourcesContent":["export { type AnyClass, getParentClass, walkClassChain } from \"./class.js\";\nexport { isSameArray, isShallowEqual, sortStrings, sortStringsBy, uniqBy } from \"./collection.js\";\nexport { errorMessage, formatChildProcessError, normalizeError } from \"./error.js\";\nexport { exitCodeForSignal, installGracefulShutdown } from \"./graceful-shutdown.js\";\nexport {\n    createLogger,\n    debug,\n    error,\n    info,\n    Logger,\n    type LoggerOptions,\n    logger,\n    type OutputStream,\n    warn,\n} from \"./log.js\";\nexport { packageVersion } from \"./package-version.js\";\nexport { callMethod } from \"./reflect.js\";\nexport { sanitizeIdentifier, sourceStringLiteral, toCamelIdentifier } from \"./source.js\";\nexport { lowerFirst, toCamelCase, toKebabCase, toPascalCase, upperFirst } from \"./string.js\";\n"]}

package/dist/log.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Minimal writable-stream shape a {@link Logger} writes formatted lines to.
+ */
+export type OutputStream = {
+    write(chunk: string): unknown;
+    /** Whether the stream is a terminal, used to decide if colored output is emitted. */
+    isTTY?: boolean | undefined;
+};
+/**
+ * Options for constructing a {@link Logger}.
+ */
+export type LoggerOptions = {
+    /** Namespace appended to the log prefix and matched against debug configuration. */
+    namespace?: string | undefined;
+    /** Stream to write log lines to; defaults to `process.stderr`. */
+    stream?: OutputStream | undefined;
+    /** Forces debug output on or off; when omitted it is resolved from `--debug` and `GTKX_DEBUG`. */
+    debugEnabled?: boolean | undefined;
+};
+/**
+ * Writes prefixed, optionally colored log lines to an output stream, with debug lines gated by
+ * command-line and environment configuration.
+ */
+export declare class Logger {
+    private stream;
+    private prefix;
+    private debugEnabled;
+    private colors;
+    /**
+     * @param options Namespace, target stream, and debug configuration for the logger.
+     */
+    constructor(options?: LoggerOptions);
+    private write;
+    /**
+     * Writes an informational line.
+     *
+     * @param message The message text.
+     * @param rest Extra values appended after the message, formatted for display.
+     */
+    info(message: string, ...rest: unknown[]): void;
+    /**
+     * Writes a line marked as a warning.
+     *
+     * @param message The message text.
+     * @param rest Extra values appended after the message, formatted for display.
+     */
+    warn(message: string, ...rest: unknown[]): void;
+    /**
+     * Writes a line marked as an error.
+     *
+     * @param message The message text.
+     * @param rest Extra values appended after the message, formatted for display.
+     */
+    error(message: string, ...rest: unknown[]): void;
+    /**
+     * Writes a line only when debug output is enabled for this logger.
+     *
+     * @param message The message text.
+     * @param rest Extra values appended after the message, formatted for display.
+     */
+    debug(message: string, ...rest: unknown[]): void;
+}
+/**
+ * Creates a {@link Logger} scoped to the given namespace.
+ *
+ * @param namespace Namespace added to the log prefix and matched against debug configuration.
+ * @param options Further logger options excluding the namespace.
+ */
+export declare const createLogger: (namespace: string, options?: Omit<LoggerOptions, "namespace">) => Logger;
+/**
+ * The default namespace-less {@link Logger} backing the module-level {@link info}, {@link warn},
+ * {@link error}, and {@link debug} functions.
+ */
+export declare const logger: Logger;
+/**
+ * Writes an informational line through the shared {@link logger}.
+ *
+ * @param message The message text.
+ * @param rest Extra values appended after the message, formatted for display.
+ */
+export declare const info: (message: string, ...rest: unknown[]) => void;
+/**
+ * Writes a warning line through the shared {@link logger}.
+ *
+ * @param message The message text.
+ * @param rest Extra values appended after the message, formatted for display.
+ */
+export declare const warn: (message: string, ...rest: unknown[]) => void;
+/**
+ * Writes an error line through the shared {@link logger}.
+ *
+ * @param message The message text.
+ * @param rest Extra values appended after the message, formatted for display.
+ */
+export declare const error: (message: string, ...rest: unknown[]) => void;
+/**
+ * Writes a debug line through the shared {@link logger} when debug output is enabled.
+ *
+ * @param message The message text.
+ * @param rest Extra values appended after the message, formatted for display.
+ */
+export declare const debug: (message: string, ...rest: unknown[]) => void;
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACvB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,qFAAqF;IACrF,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IACxB,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,kEAAkE;IAClE,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAClC,kGAAkG;IAClG,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC,CAAC;AA0BF;;;GAGG;AACH,qBAAa,MAAM;IACf,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,MAAM,CAAS;IAEvB;;OAEG;IACH,YAAY,OAAO,GAAE,aAAkB,EAKtC;IAED,OAAO,CAAC,KAAK;IAKb;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAE9C;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAE9C;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAE/C;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAG/C;CACJ;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,cAAe,MAAM,YAAW,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,KAAQ,MACxD,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,MAAqB,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,IAAI,YAAa,MAAM,WAAW,OAAO,EAAE,KAAG,IAAqC,CAAC;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,IAAI,YAAa,MAAM,WAAW,OAAO,EAAE,KAAG,IAAqC,CAAC;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,KAAK,YAAa,MAAM,WAAW,OAAO,EAAE,KAAG,IAAsC,CAAC;AAEnG;;;;;GAKG;AACH,eAAO,MAAM,KAAK,YAAa,MAAM,WAAW,OAAO,EAAE,KAAG,IAAsC,CAAC"}

package/dist/log.js

@@ -0,0 +1,129 @@
+import pc from "picocolors";
+const BASE_PREFIX = "[gtkx]";
+const colorsFor = (stream) => pc.createColors(pc.isColorSupported && stream.isTTY === true);
+const formatValue = (value) => {
+    if (typeof value === "string")
+        return value;
+    if (value instanceof Error)
+        return value.stack ?? value.message;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+};
+const resolveDebugEnabled = (namespace, argv, env) => {
+    if (argv.includes("--debug"))
+        return true;
+    const spec = env.GTKX_DEBUG;
+    if (!spec)
+        return false;
+    const names = spec.split(/[\s,]+/).filter((name) => name.length > 0);
+    if (names.includes("1") || names.includes("*"))
+        return true;
+    return namespace !== undefined && names.includes(namespace);
+};
+const prefixFor = (namespace) => namespace === undefined ? BASE_PREFIX : `[gtkx:${namespace}]`;
+/**
+ * Writes prefixed, optionally colored log lines to an output stream, with debug lines gated by
+ * command-line and environment configuration.
+ */
+export class Logger {
+    stream;
+    prefix;
+    debugEnabled;
+    colors;
+    /**
+     * @param options Namespace, target stream, and debug configuration for the logger.
+     */
+    constructor(options = {}) {
+        this.stream = options.stream ?? process.stderr;
+        this.prefix = prefixFor(options.namespace);
+        this.debugEnabled = options.debugEnabled ?? resolveDebugEnabled(options.namespace, process.argv, process.env);
+        this.colors = colorsFor(this.stream);
+    }
+    write(message, rest) {
+        const suffix = rest.length === 0 ? "" : ` ${rest.map(formatValue).join(" ")}`;
+        this.stream.write(`${this.prefix} ${message}${suffix}\n`);
+    }
+    /**
+     * Writes an informational line.
+     *
+     * @param message The message text.
+     * @param rest Extra values appended after the message, formatted for display.
+     */
+    info(message, ...rest) {
+        this.write(message, rest);
+    }
+    /**
+     * Writes a line marked as a warning.
+     *
+     * @param message The message text.
+     * @param rest Extra values appended after the message, formatted for display.
+     */
+    warn(message, ...rest) {
+        this.write(`${this.colors.yellow("warn")} ${message}`, rest);
+    }
+    /**
+     * Writes a line marked as an error.
+     *
+     * @param message The message text.
+     * @param rest Extra values appended after the message, formatted for display.
+     */
+    error(message, ...rest) {
+        this.write(`${this.colors.red("error")} ${message}`, rest);
+    }
+    /**
+     * Writes a line only when debug output is enabled for this logger.
+     *
+     * @param message The message text.
+     * @param rest Extra values appended after the message, formatted for display.
+     */
+    debug(message, ...rest) {
+        if (!this.debugEnabled)
+            return;
+        this.write(message, rest);
+    }
+}
+/**
+ * Creates a {@link Logger} scoped to the given namespace.
+ *
+ * @param namespace Namespace added to the log prefix and matched against debug configuration.
+ * @param options Further logger options excluding the namespace.
+ */
+export const createLogger = (namespace, options = {}) => new Logger({ ...options, namespace });
+/**
+ * The default namespace-less {@link Logger} backing the module-level {@link info}, {@link warn},
+ * {@link error}, and {@link debug} functions.
+ */
+export const logger = new Logger();
+/**
+ * Writes an informational line through the shared {@link logger}.
+ *
+ * @param message The message text.
+ * @param rest Extra values appended after the message, formatted for display.
+ */
+export const info = (message, ...rest) => logger.info(message, ...rest);
+/**
+ * Writes a warning line through the shared {@link logger}.
+ *
+ * @param message The message text.
+ * @param rest Extra values appended after the message, formatted for display.
+ */
+export const warn = (message, ...rest) => logger.warn(message, ...rest);
+/**
+ * Writes an error line through the shared {@link logger}.
+ *
+ * @param message The message text.
+ * @param rest Extra values appended after the message, formatted for display.
+ */
+export const error = (message, ...rest) => logger.error(message, ...rest);
+/**
+ * Writes a debug line through the shared {@link logger} when debug output is enabled.
+ *
+ * @param message The message text.
+ * @param rest Extra values appended after the message, formatted for display.
+ */
+export const debug = (message, ...rest) => logger.debug(message, ...rest);
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"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","sourcesContent":["import pc from \"picocolors\";\n\nconst BASE_PREFIX = \"[gtkx]\";\n\ntype Colors = ReturnType<typeof pc.createColors>;\n\n/**\n * Minimal writable-stream shape a {@link Logger} writes formatted lines to.\n */\nexport type OutputStream = {\n    write(chunk: string): unknown;\n    /** Whether the stream is a terminal, used to decide if colored output is emitted. */\n    isTTY?: boolean | undefined;\n};\n\n/**\n * Options for constructing a {@link Logger}.\n */\nexport type LoggerOptions = {\n    /** Namespace appended to the log prefix and matched against debug configuration. */\n    namespace?: string | undefined;\n    /** Stream to write log lines to; defaults to `process.stderr`. */\n    stream?: OutputStream | undefined;\n    /** Forces debug output on or off; when omitted it is resolved from `--debug` and `GTKX_DEBUG`. */\n    debugEnabled?: boolean | undefined;\n};\n\nconst colorsFor = (stream: OutputStream): Colors => pc.createColors(pc.isColorSupported && stream.isTTY === true);\n\nconst formatValue = (value: unknown): string => {\n    if (typeof value === \"string\") return value;\n    if (value instanceof Error) return value.stack ?? value.message;\n    try {\n        return JSON.stringify(value);\n    } catch {\n        return String(value);\n    }\n};\n\nconst resolveDebugEnabled = (namespace: string | undefined, argv: string[], env: NodeJS.ProcessEnv): boolean => {\n    if (argv.includes(\"--debug\")) return true;\n    const spec = env.GTKX_DEBUG;\n    if (!spec) return false;\n    const names = spec.split(/[\\s,]+/).filter((name) => name.length > 0);\n    if (names.includes(\"1\") || names.includes(\"*\")) return true;\n    return namespace !== undefined && names.includes(namespace);\n};\n\nconst prefixFor = (namespace: string | undefined): string =>\n    namespace === undefined ? BASE_PREFIX : `[gtkx:${namespace}]`;\n\n/**\n * Writes prefixed, optionally colored log lines to an output stream, with debug lines gated by\n * command-line and environment configuration.\n */\nexport class Logger {\n    private stream: OutputStream;\n    private prefix: string;\n    private debugEnabled: boolean;\n    private colors: Colors;\n\n    /**\n     * @param options Namespace, target stream, and debug configuration for the logger.\n     */\n    constructor(options: LoggerOptions = {}) {\n        this.stream = options.stream ?? process.stderr;\n        this.prefix = prefixFor(options.namespace);\n        this.debugEnabled = options.debugEnabled ?? resolveDebugEnabled(options.namespace, process.argv, process.env);\n        this.colors = colorsFor(this.stream);\n    }\n\n    private write(message: string, rest: unknown[]): void {\n        const suffix = rest.length === 0 ? \"\" : ` ${rest.map(formatValue).join(\" \")}`;\n        this.stream.write(`${this.prefix} ${message}${suffix}\\n`);\n    }\n\n    /**\n     * Writes an informational line.\n     *\n     * @param message The message text.\n     * @param rest Extra values appended after the message, formatted for display.\n     */\n    info(message: string, ...rest: unknown[]): void {\n        this.write(message, rest);\n    }\n\n    /**\n     * Writes a line marked as a warning.\n     *\n     * @param message The message text.\n     * @param rest Extra values appended after the message, formatted for display.\n     */\n    warn(message: string, ...rest: unknown[]): void {\n        this.write(`${this.colors.yellow(\"warn\")} ${message}`, rest);\n    }\n\n    /**\n     * Writes a line marked as an error.\n     *\n     * @param message The message text.\n     * @param rest Extra values appended after the message, formatted for display.\n     */\n    error(message: string, ...rest: unknown[]): void {\n        this.write(`${this.colors.red(\"error\")} ${message}`, rest);\n    }\n\n    /**\n     * Writes a line only when debug output is enabled for this logger.\n     *\n     * @param message The message text.\n     * @param rest Extra values appended after the message, formatted for display.\n     */\n    debug(message: string, ...rest: unknown[]): void {\n        if (!this.debugEnabled) return;\n        this.write(message, rest);\n    }\n}\n\n/**\n * Creates a {@link Logger} scoped to the given namespace.\n *\n * @param namespace Namespace added to the log prefix and matched against debug configuration.\n * @param options Further logger options excluding the namespace.\n */\nexport const createLogger = (namespace: string, options: Omit<LoggerOptions, \"namespace\"> = {}): Logger =>\n    new Logger({ ...options, namespace });\n\n/**\n * The default namespace-less {@link Logger} backing the module-level {@link info}, {@link warn},\n * {@link error}, and {@link debug} functions.\n */\nexport const logger: Logger = new Logger();\n\n/**\n * Writes an informational line through the shared {@link logger}.\n *\n * @param message The message text.\n * @param rest Extra values appended after the message, formatted for display.\n */\nexport const info = (message: string, ...rest: unknown[]): void => logger.info(message, ...rest);\n\n/**\n * Writes a warning line through the shared {@link logger}.\n *\n * @param message The message text.\n * @param rest Extra values appended after the message, formatted for display.\n */\nexport const warn = (message: string, ...rest: unknown[]): void => logger.warn(message, ...rest);\n\n/**\n * Writes an error line through the shared {@link logger}.\n *\n * @param message The message text.\n * @param rest Extra values appended after the message, formatted for display.\n */\nexport const error = (message: string, ...rest: unknown[]): void => logger.error(message, ...rest);\n\n/**\n * Writes a debug line through the shared {@link logger} when debug output is enabled.\n *\n * @param message The message text.\n * @param rest Extra values appended after the message, formatted for display.\n */\nexport const debug = (message: string, ...rest: unknown[]): void => logger.debug(message, ...rest);\n"]}

package/dist/package-version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reads the `version` field from the `package.json` next to the calling module.
+ *
+ * @param importMetaUrl The caller's `import.meta.url`, used to resolve the sibling `package.json`.
+ */
+export declare const packageVersion: (importMetaUrl: string) => string;
+//# sourceMappingURL=package-version.d.ts.map

package/dist/package-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.d.ts","sourceRoot":"","sources":["../src/package-version.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,eAAO,MAAM,cAAc,kBAAmB,MAAM,KAAG,MAC6B,CAAC"}

package/dist/package-version.js

@@ -0,0 +1,8 @@
+import { createRequire } from "node:module";
+/**
+ * Reads the `version` field from the `package.json` next to the calling module.
+ *
+ * @param importMetaUrl The caller's `import.meta.url`, used to resolve the sibling `package.json`.
+ */
+export const packageVersion = (importMetaUrl) => createRequire(importMetaUrl)("../package.json").version;
+//# sourceMappingURL=package-version.js.map

package/dist/package-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version.js","sourceRoot":"","sources":["../src/package-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,aAAqB,EAAU,EAAE,CAC3D,aAAa,CAAC,aAAa,CAAC,CAAC,iBAAiB,CAAyB,CAAC,OAAO,CAAC","sourcesContent":["import { createRequire } from \"node:module\";\n\n/**\n * Reads the `version` field from the `package.json` next to the calling module.\n *\n * @param importMetaUrl The caller's `import.meta.url`, used to resolve the sibling `package.json`.\n */\nexport const packageVersion = (importMetaUrl: string): string =>\n    (createRequire(importMetaUrl)(\"../package.json\") as { version: string }).version;\n"]}

package/dist/reflect.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Calls the named method on `target` with the given arguments, returning `undefined` when the
+ * property is missing or not callable.
+ *
+ * @param target The object to read the method from and bind as `this`.
+ * @param method The method name to look up.
+ * @param args Arguments passed to the method.
+ * @returns The method's return value, or `undefined` when it is not a function.
+ */
+export declare const callMethod: (target: object, method: string, args: unknown[]) => unknown;
+//# sourceMappingURL=reflect.d.ts.map

package/dist/reflect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflect.d.ts","sourceRoot":"","sources":["../src/reflect.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,WAAY,MAAM,UAAU,MAAM,QAAQ,OAAO,EAAE,KAAG,OAG5E,CAAC"}