@gtkx/utils 0.21.0

package/src/graceful-shutdown.ts

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ */
+
+const HANDLED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const satisfies readonly NodeJS.Signals[];
+const DEFAULT_FORCE_KILL_TIMEOUT_MS = 5000;
+
+/**
+ * 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`.
+ */
+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;
+};
+
+/**
+ * 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`.
+ *
+ * @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;
+
+    let firstSignal: NodeJS.Signals | null = null;
+    let exited = false;
+    let forceTimer: NodeJS.Timeout | null = null;
+
+    const clearTimer = (): void => {
+        if (forceTimer) {
+            clearTimeout(forceTimer);
+            forceTimer = null;
+        }
+    };
+
+    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 = (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);
+        }
+    };
+
+    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);
+    }
+
+    return {
+        uninstall: () => {
+            for (const [sig, listener] of handlers) {
+                process.removeListener(sig, listener);
+            }
+            handlers.clear();
+            clearTimer();
+        },
+    };
+};

package/src/index.ts

@@ -0,0 +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";

package/src/source.ts

@@ -0,0 +1,103 @@
+/**
+ * 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.
+ */
+
+/** Reserved words and global identifiers a generated identifier must not collide with. */
+const RESERVED: ReadonlySet<string> = new Set([
+    "arguments",
+    "await",
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "eval",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "interface",
+    "let",
+    "new",
+    "null",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "return",
+    "static",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+]);
+
+/**
+ * Rewrites a candidate name into a JavaScript identifier safe to use at
+ * variable, parameter, or property position.
+ *
+ * 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.
+ */
+export const toIdentifier = (name: string): string => (RESERVED.has(name) ? `${name}_` : name);
+
+const UNSAFE_SOURCE_CHARS = /[<>\u2028\u2029]/g;
+
+const escapeSourceChar = (char: string): string => {
+    switch (char) {
+        case "<":
+            return "\\u003C";
+        case ">":
+            return "\\u003E";
+        case "\u2028":
+            return "\\u2028";
+        case "\u2029":
+            return "\\u2029";
+        default:
+            return char;
+    }
+};
+
+/**
+ * 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.
+ *
+ * @param value - The string to embed.
+ * @returns A source-safe double-quoted string literal.
+ */
+export const quote = (value: string): string => JSON.stringify(value).replace(UNSAFE_SOURCE_CHARS, escapeSourceChar);

package/src/string.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure, runtime-agnostic string-case helpers.
+ *
+ * The conversions translate between snake_case, kebab-case, camelCase, and
+ * PascalCase. They split only on underscores and hyphens and preserve the case
+ * of each segment, so they are not a substitute for a full Unicode-aware case
+ * transform.
+ */
+
+/**
+ * Uppercases the first character of `value`, leaving the remaining characters
+ * untouched.
+ *
+ * The tail is preserved verbatim rather than lowercased, so
+ * `toUpperFirst("fooBar")` is `"FooBar"` and `toUpperFirst("URL")` is `"URL"`. An
+ * empty string returns an empty string.
+ *
+ * @param value - The string to transform.
+ * @returns `value` with its first character uppercased.
+ */
+export const toUpperFirst = (value: string): string => value.charAt(0).toUpperCase() + value.slice(1);
+
+/**
+ * Converts a snake_case or kebab-case string to camelCase.
+ *
+ * The input is split on underscores and hyphens, dropping empty segments from
+ * leading, trailing, or repeated separators. The first segment is kept
+ * verbatim and every later segment is {@link toUpperFirst}-cased before joining,
+ * so `toCamelCase("icon_name")` is `"iconName"` and `toCamelCase("Box")` is
+ * `"Box"`. A string with no separators is returned unchanged.
+ *
+ * @param input - The snake_case or kebab-case identifier.
+ * @returns The camelCase form of `input`.
+ */
+export const toCamelCase = (input: string): string => {
+    const parts = input.split(/[_-]/g).filter((part) => part.length > 0);
+    if (parts.length === 0) return input;
+    const [first, ...rest] = parts;
+    const head = first ?? "";
+    return head + rest.map(toUpperFirst).join("");
+};
+
+/**
+ * Converts a snake_case, kebab-case, or already-PascalCase string to
+ * PascalCase.
+ *
+ * The input is split on underscores and hyphens, dropping empty segments, and
+ * every remaining segment is {@link toUpperFirst}-cased before joining, so
+ * `toPascalCase("icon_name")` is `"IconName"` and `toPascalCase("Box")` is
+ * `"Box"`. An empty string is returned unchanged.
+ *
+ * @param input - The identifier to transform.
+ * @returns The PascalCase form of `input`.
+ */
+export const toPascalCase = (input: string): string => {
+    if (input.length === 0) return input;
+    const parts = input.split(/[_-]/g).filter((part) => part.length > 0);
+    if (parts.length === 0) return input;
+    return parts.map(toUpperFirst).join("");
+};
+
+/**
+ * Converts a camelCase or PascalCase string to kebab-case.
+ *
+ * Each uppercase character is lowercased; every uppercase character other than
+ * the first is additionally prefixed with a hyphen, so `toKebabCase("iconName")`
+ * is `"icon-name"` and `toKebabCase("Title")` is `"title"`. The leading
+ * character is never prefixed with a hyphen.
+ *
+ * @param input - The camelCase or PascalCase identifier.
+ * @returns The kebab-case form of `input`.
+ */
+export const toKebabCase = (input: string): string =>
+    input.replaceAll(/[A-Z]/g, (char, index: number) => (index === 0 ? char.toLowerCase() : `-${char.toLowerCase()}`));