@gtkx/utils 0.21.0

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

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

package/dist/graceful-shutdown.js

@@ -0,0 +1,94 @@
+/**
+ * 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"];
+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) => {
+    if (!signal)
+        return 0;
+    return signal === "SIGINT" ? 130 : 143;
+};
+/**
+ * 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) => {
+    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 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);
+    }
+    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

@@ -0,0 +1 @@
+{"version":3,"file":"graceful-shutdown.js","sourceRoot":"","sources":["../src/graceful-shutdown.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,6 @@
+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";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/source.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare const toIdentifier: (name: string) => string;
+/**
+ * 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 declare const quote: (value: string) => string;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqDH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAAkD,CAAC;AAmB/F;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,KAAG,MAA8E,CAAC"}

package/dist/source.js

@@ -0,0 +1,99 @@
+/**
+ * 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 = 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) => (RESERVED.has(name) ? `${name}_` : name);
+const UNSAFE_SOURCE_CHARS = /[<>\u2028\u2029]/g;
+const escapeSourceChar = (char) => {
+    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) => JSON.stringify(value).replace(UNSAFE_SOURCE_CHARS, escapeSourceChar);
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,0FAA0F;AAC1F,MAAM,QAAQ,GAAwB,IAAI,GAAG,CAAC;IAC1C,WAAW;IACX,OAAO;IACP,OAAO;IACP,MAAM;IACN,OAAO;IACP,OAAO;IACP,OAAO;IACP,UAAU;IACV,UAAU;IACV,SAAS;IACT,QAAQ;IACR,IAAI;IACJ,MAAM;IACN,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,OAAO;IACP,SAAS;IACT,KAAK;IACL,UAAU;IACV,IAAI;IACJ,QAAQ;IACR,IAAI;IACJ,YAAY;IACZ,WAAW;IACX,KAAK;IACL,KAAK;IACL,MAAM;IACN,SAAS;IACT,SAAS;IACT,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,MAAM;IACN,OAAO;IACP,MAAM;IACN,KAAK;IACL,QAAQ;IACR,KAAK;IACL,MAAM;IACN,OAAO;IACP,MAAM;IACN,OAAO;CACV,CAAC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAE/F,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;AAEhD,MAAM,gBAAgB,GAAG,CAAC,IAAY,EAAU,EAAE;IAC9C,QAAQ,IAAI,EAAE,CAAC;QACX,KAAK,GAAG;YACJ,OAAO,SAAS,CAAC;QACrB,KAAK,GAAG;YACJ,OAAO,SAAS,CAAC;QACrB,KAAK,QAAQ;YACT,OAAO,SAAS,CAAC;QACrB,KAAK,QAAQ;YACT,OAAO,SAAS,CAAC;QACrB;YACI,OAAO,IAAI,CAAC;IACpB,CAAC;AACL,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,CAAC"}

package/dist/string.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 declare const toUpperFirst: (value: string) => string;
+/**
+ * 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 declare const toCamelCase: (input: string) => string;
+/**
+ * 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 declare const toPascalCase: (input: string) => string;
+/**
+ * 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 declare const toKebabCase: (input: string) => string;
+//# sourceMappingURL=string.d.ts.map

package/dist/string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../src/string.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAAwD,CAAC;AAEtG;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,MAM3C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAK5C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,MAC0E,CAAC"}

package/dist/string.js

@@ -0,0 +1,73 @@
+/**
+ * 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) => 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) => {
+    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) => {
+    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) => input.replaceAll(/[A-Z]/g, (char, index) => (index === 0 ? char.toLowerCase() : `-${char.toLowerCase()}`));
+//# sourceMappingURL=string.js.map

package/dist/string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.js","sourceRoot":"","sources":["../src/string.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEtG;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAa,EAAU,EAAE;IACjD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC;IAC/B,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;IACzB,OAAO,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAClD,CAAC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAa,EAAU,EAAE;IAClD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5C,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAa,EAAU,EAAE,CACjD,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAa,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@gtkx/utils",
+  "version": "0.21.0",
+  "description": "Cross-package utilities shared by GTKX runtime entry points",
+  "homepage": "https://gtkx.dev",
+  "bugs": {
+    "url": "https://github.com/gtkx-org/gtkx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gtkx-org/gtkx.git",
+    "directory": "packages/utils"
+  },
+  "license": "MPL-2.0",
+  "author": "Eugenio Depalo <eugeniodepalo@gmail.com>",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run",
+    "typecheck": "tsc -b --emitDeclarationOnly"
+  }
+}

package/src/class.ts

@@ -0,0 +1,17 @@
+/**
+ * Structural type matching any class — abstract or concrete — whose instances
+ * have type `T`.
+ *
+ * A class value carries a construct signature plus a `prototype`, but a bare
+ * construct signature types `prototype` as `any`. The `& { prototype: T }`
+ * intersection recovers the precise instance type so callers can read
+ * `cls.prototype` as `T`, and the `abstract new` form accepts both abstract and
+ * concrete classes, making this the widest supertype of every class value. The
+ * `never[]` constructor parameters admit any class while documenting that the
+ * type is used as an identity token, not to construct instances.
+ */
+export type AnyClass<T extends object = object> = (abstract new (
+    ...args: never[]
+) => T) & {
+    readonly prototype: T;
+};

package/src/collection.ts

@@ -0,0 +1,103 @@
+/**
+ * Pure, runtime-agnostic collection helpers shared across GTKX packages.
+ */
+
+/**
+ * Returns a shallow copy of `record` with the given `keys` removed.
+ *
+ * Keys absent from `record` are ignored, and `record` is not mutated. The
+ * result is typed as the input shape because callers treat the excluded keys
+ * as runtime-only concerns absent from the static type.
+ *
+ * @typeParam T - The record shape.
+ * @param record - The source object.
+ * @param keys - The keys to exclude from the copy.
+ * @returns A new object holding every own enumerable key of `record` except
+ *   those listed in `keys`.
+ */
+export const omit = <T extends Record<string, unknown>>(record: T, keys: readonly string[]): T => {
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(record)) {
+        if (!keys.includes(key)) {
+            result[key] = record[key];
+        }
+    }
+    return result as T;
+};
+
+/**
+ * Compares two arrays of primitives for element-wise strict equality.
+ *
+ * Returns `true` when both arguments are the same reference (including both
+ * being `null` or `undefined`), or when they have equal length and every
+ * element is strictly equal (`===`) at the same index. A `null`/`undefined`
+ * argument is equal only to another `null`/`undefined` argument.
+ *
+ * @typeParam T - The primitive element type.
+ * @param a - The first array, or `null`/`undefined`.
+ * @param b - The second array, or `null`/`undefined`.
+ * @returns Whether the two arrays are shallowly equal.
+ */
+export const isShallowEqual = <T extends string | number | boolean>(
+    a: readonly T[] | null | undefined,
+    b: readonly T[] | null | undefined,
+): boolean => {
+    if (a === b) return true;
+    if (!a || !b) return false;
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) return false;
+    }
+    return true;
+};
+
+/**
+ * Compares two arrays of records by shallow per-element equality.
+ *
+ * Returns `true` when both arrays have equal length and, at every index, the
+ * two records expose the same set of keys with strictly equal (`===`) values.
+ * Values are compared one level deep only; nested objects are compared by
+ * reference.
+ *
+ * @typeParam T - The record element type.
+ * @param a - The first array of records.
+ * @param b - The second array of records.
+ * @returns Whether the two arrays are element-wise shallowly equal.
+ */
+export const isShallowArrayEqual = <T extends Record<string, unknown>>(a: readonly T[], b: readonly T[]): boolean => {
+    if (a.length !== b.length) return false;
+
+    for (let i = 0; i < a.length; i++) {
+        const itemA = a[i];
+        const itemB = b[i];
+        if (!itemA || !itemB) return false;
+
+        const keysA = Object.keys(itemA);
+        const keysB = Object.keys(itemB);
+        if (keysA.length !== keysB.length) return false;
+
+        for (const key of keysA) {
+            if (itemA[key] !== itemB[key]) return false;
+        }
+    }
+
+    return true;
+};
+
+/**
+ * Builds a reverse lookup from a numeric enum's values to their member names.
+ *
+ * A TypeScript numeric enum's runtime object carries both name-to-value and
+ * value-to-name entries; this keeps only the name-to-value direction and
+ * inverts it, yielding a `Map` from each numeric value to the name that
+ * declared it.
+ *
+ * @param enumObject - A numeric enum's runtime object.
+ * @returns A map from each numeric enum value to its declared member name.
+ */
+export const reverseNumericEnum = (enumObject: Record<string, string | number>): Map<number, string> =>
+    new Map<number, string>(
+        Object.entries(enumObject)
+            .filter((entry): entry is [string, number] => typeof entry[1] === "number")
+            .map(([name, value]) => [value, name]),
+    );

package/src/error.ts

@@ -0,0 +1,12 @@
+/**
+ * Coerces an unknown thrown value into a human-readable string.
+ *
+ * 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 of unknown shape.
+ * @returns A string describing the error.
+ */
+export const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));