@gtkx/utils 0.21.0 → 1.0.0-rc.1

package/src/error.ts

@@ -1,12 +1,42 @@
+const isObject = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null;
+
+const isErrorLike = (value: unknown): value is { message: string } =>
+    isObject(value) && "message" in value && typeof value.message === "string";
+
 /**
- * Coerces an unknown thrown value into a human-readable string.
+ * Extracts a human-readable message from an unknown thrown value, falling back to its string form.
  *
- * Returns `error.message` when `error` is an `Error` instance, otherwise
- * delegates to `String(error)`. Use at boundaries where exceptions are
- * surfaced to logs, IPC frames, or user-facing output and the type cannot
- * be narrowed otherwise.
+ * @param error The caught value to describe.
+ */
+export const errorMessage = (error: unknown): string =>
+    Error.isError(error) || isErrorLike(error) ? error.message : String(error);
+
+/**
+ * Coerces an unknown thrown value into an `Error`, reusing it if it already is one and otherwise
+ * wrapping its message while copying any error-like own properties.
+ *
+ * @param error The caught value to normalize.
+ */
+export const normalizeError = (error: unknown): Error => {
+    if (Error.isError(error)) return error;
+    return Object.assign(new Error(errorMessage(error)), isErrorLike(error) ? error : {});
+};
+
+const readStream = (value: unknown): string => {
+    if (typeof value === "string") return value;
+    if (value instanceof Uint8Array || Buffer.isBuffer(value)) return value.toString();
+    return "";
+};
+
+/**
+ * Combines the `stderr` and `stdout` fields of a failed child-process error into a single trimmed string.
  *
- * @param error - The caught value of unknown shape.
- * @returns A string describing the error.
+ * @param error The child-process error to read output from.
+ * @returns The joined output, or `undefined` when neither stream carried any text.
  */
-export const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+export const formatChildProcessError = (error: unknown): string | undefined => {
+    if (!isObject(error)) return undefined;
+    const { stderr, stdout } = error;
+    const details = [readStream(stderr), readStream(stdout)].filter(Boolean).join("\n").trim();
+    return details.length > 0 ? details : undefined;
+};

package/src/graceful-shutdown.ts

@@ -1,141 +1,114 @@
-/**
- * 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"] as const satisfies readonly NodeJS.Signals[];
+const HANDLED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const satisfies NodeJS.Signals[];
 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: NodeJS.Signals | null): number => {
     if (!signal) return 0;
     return signal === "SIGINT" ? 130 : 143;
 };
 
-/**
- * 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;
+type ShutdownState = {
+    options: GracefulShutdownOptions;
+    forceKillMs: number;
+    coalesceWindowMs: number;
+    firstSignal: NodeJS.Signals | null;
+    exited: boolean;
+    coalescing: boolean;
+    forceTimer: NodeJS.Timeout | null;
+    coalesceTimer: NodeJS.Timeout | null;
 };
 
-/**
- * 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`.
- *
- * @param options - Shutdown behaviour.
- * @returns A handle that detaches the installed signal handlers.
- */
-export const installGracefulShutdown = (options: GracefulShutdownOptions): GracefulShutdownHandle => {
-    const forceKillMs = options.forceKillAfterMs ?? DEFAULT_FORCE_KILL_TIMEOUT_MS;
+const clearTimers = (state: ShutdownState): void => {
+    if (state.forceTimer) {
+        clearTimeout(state.forceTimer);
+        state.forceTimer = null;
+    }
+    if (state.coalesceTimer) {
+        clearTimeout(state.coalesceTimer);
+        state.coalesceTimer = null;
+    }
+};
 
-    let firstSignal: NodeJS.Signals | null = null;
-    let exited = false;
-    let forceTimer: NodeJS.Timeout | null = null;
+const finish = (state: ShutdownState, signal: NodeJS.Signals, graceful: boolean): void => {
+    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 clearTimer = (): void => {
-        if (forceTimer) {
-            clearTimeout(forceTimer);
-            forceTimer = null;
-        }
-    };
+const beginShutdown = (state: ShutdownState, signal: NodeJS.Signals): void => {
+    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: unknown) => {
+                error("graceful shutdown failed", reason);
+                finish(state, signal, false);
+            },
+        );
+};
 
-    const finish = (signal: NodeJS.Signals): void => {
-        if (exited) return;
-        exited = true;
-        clearTimer();
-        const code = options.exitCode ? options.exitCode(signal) : exitCodeForSignal(signal);
-        process.exit(code);
-    };
+const handle = (state: ShutdownState, signal: NodeJS.Signals): void => {
+    if (state.firstSignal === null) {
+        beginShutdown(state, signal);
+        return;
+    }
+    if (state.coalescing) return;
+    state.options.onForce?.();
+    finish(state, signal, false);
+};
 
-    const handle = (signal: NodeJS.Signals): void => {
-        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: unknown) => {
-                    console.error("Graceful shutdown error:", error);
-                })
-                .finally(() => finish(signal));
-            return;
-        }
-        if (signal === "SIGINT" && firstSignal === "SIGINT") {
-            options.onForce?.();
-            finish(signal);
-        }
+/**
+ * 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 The shutdown callbacks and timing configuration.
+ */
+export const installGracefulShutdown = (options: GracefulShutdownOptions): void => {
+    const state: ShutdownState = {
+        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 handlers = new Map<NodeJS.Signals, () => void>();
     for (const sig of HANDLED_SIGNALS) {
-        const listener = (): void => 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();
-        },
-    };
 };

package/src/index.ts

@@ -1,10 +1,19 @@
-export type { AnyClass } from "./class.js";
-export { isShallowArrayEqual, isShallowEqual, omit, reverseNumericEnum } from "./collection.js";
-export { errorMessage } from "./error.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 {
-    exitCodeForSignal,
-    type GracefulShutdownHandle,
-    installGracefulShutdown,
-} from "./graceful-shutdown.js";
-export { quote, toIdentifier } from "./source.js";
-export { toCamelCase, toKebabCase, toPascalCase, toUpperFirst } from "./string.js";
+    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";

package/src/log.ts

@@ -0,0 +1,164 @@
+import pc from "picocolors";
+
+const BASE_PREFIX = "[gtkx]";
+
+type Colors = ReturnType<typeof pc.createColors>;
+
+/**
+ * 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;
+};
+
+const colorsFor = (stream: OutputStream): Colors => pc.createColors(pc.isColorSupported && stream.isTTY === true);
+
+const formatValue = (value: unknown): string => {
+    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: string | undefined, argv: string[], env: NodeJS.ProcessEnv): boolean => {
+    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: string | undefined): string =>
+    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 {
+    private stream: OutputStream;
+    private prefix: string;
+    private debugEnabled: boolean;
+    private colors: Colors;
+
+    /**
+     * @param options Namespace, target stream, and debug configuration for the logger.
+     */
+    constructor(options: LoggerOptions = {}) {
+        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);
+    }
+
+    private write(message: string, rest: unknown[]): void {
+        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: string, ...rest: unknown[]): void {
+        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: string, ...rest: unknown[]): void {
+        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: string, ...rest: unknown[]): void {
+        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: string, ...rest: unknown[]): void {
+        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: string, options: Omit<LoggerOptions, "namespace"> = {}): Logger =>
+    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: 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: string, ...rest: unknown[]): void => 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: string, ...rest: unknown[]): void => 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: string, ...rest: unknown[]): void => 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: string, ...rest: unknown[]): void => logger.debug(message, ...rest);

package/src/package-version.ts

@@ -0,0 +1,9 @@
+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: string): string =>
+    (createRequire(importMetaUrl)("../package.json") as { version: string }).version;

package/src/reflect.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 const callMethod = (target: object, method: string, args: unknown[]): unknown => {
+    const fn = Reflect.get(target, method);
+    return typeof fn === "function" ? Reflect.apply(fn, target, args) : undefined;
+};

package/src/source.ts

@@ -1,11 +1,6 @@
-/**
- * Helpers for shaping values into safe JavaScript/TypeScript source fragments:
- * a reserved-word-safe identifier and a source-safe string literal. Both are
- * pure and runtime-agnostic, intended for code generators that emit TypeScript.
- */
+import { toCamelCase } from "./string.js";
 
-/** Reserved words and global identifiers a generated identifier must not collide with. */
-const RESERVED: ReadonlySet<string> = new Set([
+const RESERVED: Set<string> = new Set([
     "arguments",
     "await",
     "break",
@@ -56,48 +51,34 @@ const RESERVED: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Rewrites a candidate name into a JavaScript identifier safe to use at
- * variable, parameter, or property position.
+ * Returns the name unchanged, or with a trailing underscore when it collides with a reserved word,
+ * so it is safe to emit as a JavaScript identifier.
  *
- * The input is expected to already use valid identifier characters (for
- * example the output of a case-conversion helper); the only transformation
- * applied is appending an underscore when `name` collides with a reserved
- * word or global identifier, so `toIdentifier("class")` is `"class_"` and
- * `toIdentifier("iconName")` is `"iconName"`.
- *
- * @param name - The candidate identifier.
- * @returns A reserved-word-safe identifier.
+ * @param name The candidate identifier.
  */
-export const toIdentifier = (name: string): string => (RESERVED.has(name) ? `${name}_` : name);
+export const sanitizeIdentifier = (name: string): string => (RESERVED.has(name) ? `${name}_` : name);
 
-const UNSAFE_SOURCE_CHARS = /[<>\u2028\u2029]/g;
+/**
+ * Converts a name to camelCase and sanitizes it into a valid JavaScript identifier.
+ *
+ * @param name The name to convert.
+ */
+export const toCamelIdentifier = (name: string): string => sanitizeIdentifier(toCamelCase(name));
 
-const escapeSourceChar = (char: string): string => {
-    switch (char) {
-        case "<":
-            return "\\u003C";
-        case ">":
-            return "\\u003E";
-        case "\u2028":
-            return "\\u2028";
-        case "\u2029":
-            return "\\u2029";
-        default:
-            return char;
-    }
+const SOURCE_ESCAPES: Record<string, string> = {
+    "<": "\\u003C",
+    ">": "\\u003E",
+    "\u2028": "\\u2028",
+    "\u2029": "\\u2029",
 };
 
+const UNSAFE_SOURCE_CHARS = new RegExp(`[${Object.keys(SOURCE_ESCAPES).join("")}]`, "g");
+
 /**
- * Quotes a string for safe embedding as a literal in generated TypeScript
- * source.
- *
- * Builds a double-quoted literal with `JSON.stringify`, then escapes the
- * characters that are valid inside a JSON string yet unsafe inside JavaScript
- * source: the angle brackets that could otherwise break out of an enclosing
- * `</script>` and the U+2028/U+2029 line separators that prematurely terminate
- * a string literal. The escaped form parses back to the original value.
+ * Encodes a string as a JavaScript string literal, additionally escaping characters that are unsafe
+ * to embed in generated source (angle brackets and the line and paragraph separators).
  *
- * @param value - The string to embed.
- * @returns A source-safe double-quoted string literal.
+ * @param value The string to encode.
  */
-export const quote = (value: string): string => JSON.stringify(value).replace(UNSAFE_SOURCE_CHARS, escapeSourceChar);
+export const sourceStringLiteral = (value: string): string =>
+    JSON.stringify(value).replace(UNSAFE_SOURCE_CHARS, (char) => SOURCE_ESCAPES[char] ?? char);