@gtkx/utils 1.0.0-rc.1 → 1.0.0-rc.2

package/src/object/omit.ts

@@ -0,0 +1,26 @@
+/**
+ * Creates a new object holding every entry of `obj` except the named keys.
+ *
+ * @template T - The type of the source object.
+ * @template K - The keys to leave out.
+ * @param obj - The object to copy entries from.
+ * @param keys - The keys to leave out of the result.
+ * @returns A new object without the named keys.
+ *
+ * @example
+ * omit({ a: 1, b: 2 }, ["a"]); // { b: 2 }
+ */
+function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K> {
+    const excluded: Set<PropertyKey> = new Set(keys);
+    const result: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(obj)) {
+        if (!excluded.has(key)) {
+            result[key] = value;
+        }
+    }
+
+    return result as Omit<T, K>;
+}
+
+export { omit };

package/src/object/pick-by.ts

@@ -0,0 +1,30 @@
+/**
+ * Creates a new object of the entries of `obj` that satisfy the predicate.
+ *
+ * @template T - The type of the source object.
+ * @param obj - The object to pick entries from.
+ * @param shouldPick - Called with each value and key; return `true` to keep the entry.
+ * @returns A new object holding only the entries the predicate kept.
+ *
+ * @example
+ * pickBy({ a: 1, b: 2 }, (value) => value > 1); // { b: 2 }
+ * pickBy({ a: 1, b: 2 }, (_value, key) => key !== "a"); // { b: 2 }
+ */
+function pickBy<T extends Record<string, unknown>>(
+    obj: T,
+    shouldPick: (value: T[keyof T], key: keyof T) => boolean,
+): Partial<T> {
+    const result: Partial<T> = {};
+
+    for (const key of Object.keys(obj) as (keyof T)[]) {
+        const value = obj[key];
+
+        if (shouldPick(value, key)) {
+            result[key] = value;
+        }
+    }
+
+    return result;
+}
+
+export { pickBy };

package/src/object/structured-clone.ts

@@ -0,0 +1,31 @@
+import { isPlainObject } from "../predicate/is-plain-object.js";
+
+/**
+ * Recursively copies arrays and plain objects, sharing every other value by reference. The result
+ * mirrors exactly the structure `isDeepEqual` traverses, so comparing a value against its earlier
+ * clone detects in-place mutations of the original. Unlike the global of the same name, class
+ * instances such as `Date` and `Map` are shared rather than copied, and no value is ever rejected.
+ *
+ * @template T - The type of the value.
+ * @param value - The value to clone.
+ * @returns A clone whose arrays and plain objects are fresh and whose other values are shared.
+ *
+ * @example
+ * const source = { a: [{ b: 1 }] };
+ * const copy = structuredClone(source);
+ * source.a[0].b = 2;
+ * copy.a[0].b; // 1
+ */
+function structuredClone<T>(value: T): T {
+    if (Array.isArray(value)) {
+        return value.map((item: unknown) => structuredClone(item)) as T;
+    }
+
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, structuredClone(entry)])) as T;
+    }
+
+    return value;
+}
+
+export { structuredClone };

package/src/predicate/are-object-keys-equal.ts

@@ -0,0 +1,15 @@
+const areObjectKeysEqual = (
+    a: Record<string, unknown>,
+    b: Record<string, unknown>,
+    isValueEqual: (a: unknown, b: unknown) => boolean,
+): boolean => {
+    const keysA = Object.keys(a);
+
+    if (keysA.length !== Object.keys(b).length) {
+        return false;
+    }
+
+    return keysA.every((key) => Object.hasOwn(b, key) && isValueEqual(a[key], b[key]));
+};
+
+export { areObjectKeysEqual };

package/src/predicate/index.ts

@@ -0,0 +1,6 @@
+export { isDeepEqual } from "./is-deep-equal.js";
+export { isPlainObject } from "./is-plain-object.js";
+export { isRecord } from "./is-record.js";
+export { isSameArrayBy } from "./is-same-array-by.js";
+export { isSameArray } from "./is-same-array.js";
+export { isShallowEqual } from "./is-shallow-equal.js";

package/src/predicate/is-deep-equal.ts

@@ -0,0 +1,41 @@
+import { areObjectKeysEqual } from "./are-object-keys-equal.js";
+import { isPlainObject } from "./is-plain-object.js";
+
+/**
+ * Checks whether two values are deeply equal: identical, arrays of the same length whose elements
+ * are deeply equal in order, or plain objects with the same own enumerable keys and deeply equal
+ * values. Values that are neither both arrays nor both plain objects are equal only when identical.
+ *
+ * @param a - The first value.
+ * @param b - The second value.
+ * @returns `true` when the values are deeply equal.
+ *
+ * @example
+ * isDeepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] }); // true
+ * isDeepEqual({ a: [1] }, { a: [2] }); // false
+ */
+const isDeepArrayEqual = (a: unknown, b: unknown): boolean => {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+        return false;
+    }
+
+    return a.every((item, index) => isDeepEqual(item, b[index]));
+};
+
+function isDeepEqual(a: unknown, b: unknown): boolean {
+    if (a === b) {
+        return true;
+    }
+
+    if (Array.isArray(a) || Array.isArray(b)) {
+        return isDeepArrayEqual(a, b);
+    }
+
+    if (isPlainObject(a) && isPlainObject(b)) {
+        return areObjectKeysEqual(a, b, isDeepEqual);
+    }
+
+    return false;
+}
+
+export { isDeepEqual };

package/src/predicate/is-plain-object.ts

@@ -0,0 +1,25 @@
+/**
+ * Checks whether a value is a plain object, i.e. one whose prototype is `Object.prototype` or `null`.
+ *
+ * Class instances, arrays, and other exotic objects return `false`.
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` is a plain object.
+ *
+ * @example
+ * isPlainObject({ a: 1 }); // true
+ * isPlainObject(Object.create(null)); // true
+ * isPlainObject([1, 2]); // false
+ * isPlainObject(new Date()); // false
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+
+    const proto: unknown = Object.getPrototypeOf(value);
+
+    return proto === Object.prototype || proto === null;
+}
+
+export { isPlainObject };

package/src/predicate/is-record.ts

@@ -0,0 +1,16 @@
+/**
+ * Checks whether a value is a non-null object (including arrays and class instances, excluding `null`).
+ *
+ * @param value - The value to test.
+ * @returns `true` when `value` is a non-null object.
+ *
+ * @example
+ * isRecord({ a: 1 }); // true
+ * isRecord(null); // false
+ * isRecord("x"); // false
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null;
+}
+
+export { isRecord };

package/src/predicate/is-same-array-by.ts

@@ -0,0 +1,21 @@
+/**
+ * Checks whether two arrays have the same length and elements the comparator treats as equal, in order.
+ *
+ * @template T - The type of the array elements.
+ * @param a - The first array.
+ * @param b - The second array.
+ * @param isEqual - Compares elements at the same index; return `true` when they are equal.
+ * @returns `true` when the arrays are element-wise equal under `isEqual`.
+ *
+ * @example
+ * isSameArrayBy([{ id: 1 }], [{ id: 1 }], (x, y) => x.id === y.id); // true
+ */
+function isSameArrayBy<T>(a: T[], b: T[], isEqual: (x: T, y: T) => boolean): boolean {
+    if (a.length !== b.length) {
+        return false;
+    }
+
+    return a.every((item, index) => isEqual(item, b[index] as T));
+}
+
+export { isSameArrayBy };

package/src/predicate/is-same-array.ts

@@ -0,0 +1,19 @@
+import { isSameArrayBy } from "./is-same-array-by.js";
+
+/**
+ * Checks whether two arrays have the same length and strictly equal (`===`) elements in order.
+ *
+ * @template T - The type of the array elements.
+ * @param a - The first array.
+ * @param b - The second array.
+ * @returns `true` when the arrays are element-wise strictly equal.
+ *
+ * @example
+ * isSameArray([1, 2], [1, 2]); // true
+ * isSameArray([1, 2], [2, 1]); // false
+ */
+function isSameArray<T>(a: T[], b: T[]): boolean {
+    return isSameArrayBy(a, b, (x, y) => x === y);
+}
+
+export { isSameArray };

package/src/predicate/is-shallow-equal.ts

@@ -0,0 +1,32 @@
+import { areObjectKeysEqual } from "./are-object-keys-equal.js";
+import { isPlainObject } from "./is-plain-object.js";
+
+/**
+ * Checks whether two values are shallowly equal: identical, or plain objects with the same own
+ * enumerable keys and strictly equal (`===`) values. Values that are not both plain objects are
+ * equal only when identical.
+ *
+ * @param a - The first value.
+ * @param b - The second value.
+ * @returns `true` when the values are shallowly equal.
+ *
+ * @example
+ * isShallowEqual({ a: 1 }, { a: 1 }); // true
+ * isShallowEqual({ a: 1 }, { a: 2 }); // false
+ * isShallowEqual(3, 3); // true
+ */
+const isStrictEqual = (a: unknown, b: unknown): boolean => a === b;
+
+function isShallowEqual(a: unknown, b: unknown): boolean {
+    if (a === b) {
+        return true;
+    }
+
+    if (isPlainObject(a) && isPlainObject(b)) {
+        return areObjectKeysEqual(a, b, isStrictEqual);
+    }
+
+    return false;
+}
+
+export { isShallowEqual };

package/src/process/exit-code-for-signal.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 that triggered termination, or `null`.
+ * @returns The conventional exit code for the signal.
+ *
+ * @example
+ * exitCodeForSignal("SIGINT"); // 130
+ * exitCodeForSignal(null); // 0
+ */
+function exitCodeForSignal(signal: NodeJS.Signals | null): number {
+    if (!signal) {
+        return 0;
+    }
+
+    return signal === "SIGINT" ? 130 : 143;
+}
+
+export { exitCodeForSignal };

package/src/process/index.ts

@@ -0,0 +1,3 @@
+export { exitCodeForSignal } from "./exit-code-for-signal.js";
+export { installGracefulShutdown } from "./install-graceful-shutdown.js";
+export { resolveExecutable } from "./resolve-executable.js";

package/src/{graceful-shutdown.ts → process/install-graceful-shutdown.ts}

@@ -1,26 +1,12 @@
-import { error } from "./log.js";
+import { error } from "../log/default-logger.js";
+import { exitCodeForSignal } from "./exit-code-for-signal.js";
 
-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 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 that triggered termination, or `null`.
- */
-export const exitCodeForSignal = (signal: NodeJS.Signals | null): number => {
-    if (!signal) return 0;
-    return signal === "SIGINT" ? 130 : 143;
-};
-
-export type GracefulShutdownOptions = {
+type GracefulShutdownOptions = {
     onSignal: (signal: NodeJS.Signals) => void | Promise<void>;
     onForce?: () => void;
     forceKillAfterMs?: number;
     coalesceWindowMs?: number;
-    exitCode?: (signal: NodeJS.Signals, graceful: boolean) => number;
+    exitCode?: (signal: NodeJS.Signals, isGraceful: boolean) => number;
 };
 
 type ShutdownState = {
@@ -34,59 +20,80 @@ type ShutdownState = {
     coalesceTimer: NodeJS.Timeout | null;
 };
 
+const HANDLED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const satisfies NodeJS.Signals[];
+const DEFAULT_FORCE_KILL_TIMEOUT_MS = 5000;
+const DEFAULT_COALESCE_WINDOW_MS = 500;
+
 const clearTimers = (state: ShutdownState): void => {
     if (state.forceTimer) {
         clearTimeout(state.forceTimer);
         state.forceTimer = null;
     }
+
     if (state.coalesceTimer) {
         clearTimeout(state.coalesceTimer);
         state.coalesceTimer = null;
     }
 };
 
-const finish = (state: ShutdownState, signal: NodeJS.Signals, graceful: boolean): void => {
-    if (state.exited) return;
+const finish = (state: ShutdownState, signal: NodeJS.Signals, isGraceful: 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 defaultCode = isGraceful ? 0 : exitCodeForSignal(signal);
+    process.exit(exitCode ? exitCode(signal, isGraceful) : defaultCode);
+};
+
+const runShutdown = async (state: ShutdownState, signal: NodeJS.Signals): Promise<void> => {
+    try {
+        await state.options.onSignal(signal);
+        finish(state, signal, true);
+    } catch (error_) {
+        error("graceful shutdown failed", error_);
+        finish(state, signal, false);
+    }
 };
 
 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);
-            },
-        );
+
+    void runShutdown(state, signal);
 };
 
 const handle = (state: ShutdownState, signal: NodeJS.Signals): void => {
     if (state.firstSignal === null) {
         beginShutdown(state, signal);
+
+        return;
+    }
+
+    if (state.coalescing) {
         return;
     }
-    if (state.coalescing) return;
+
     state.options.onForce?.();
     finish(state, signal, false);
 };
@@ -95,9 +102,9 @@ const handle = (state: ShutdownState, signal: NodeJS.Signals): void => {
  * 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.
+ * @param options - The shutdown callbacks and timing configuration.
  */
-export const installGracefulShutdown = (options: GracefulShutdownOptions): void => {
+function installGracefulShutdown(options: GracefulShutdownOptions): void {
     const state: ShutdownState = {
         options,
         forceKillMs: options.forceKillAfterMs ?? DEFAULT_FORCE_KILL_TIMEOUT_MS,
@@ -108,7 +115,12 @@ export const installGracefulShutdown = (options: GracefulShutdownOptions): void
         forceTimer: null,
         coalesceTimer: null,
     };
+
     for (const sig of HANDLED_SIGNALS) {
-        process.on(sig, () => handle(state, sig));
+        process.on(sig, () => {
+            handle(state, sig);
+        });
     }
-};
+}
+
+export { installGracefulShutdown, type GracefulShutdownOptions };

package/src/process/resolve-executable.ts

@@ -0,0 +1,57 @@
+import { accessSync, constants } from "node:fs";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+
+const isExecutable = (path: string): boolean => {
+    try {
+        accessSync(path, constants.X_OK);
+
+        return true;
+    } catch {
+        return false;
+    }
+};
+
+const findOnPath = (command: string): string | undefined => {
+    const searchPaths = (process.env.PATH ?? "").split(delimiter).filter((entry) => entry.length > 0);
+
+    for (const directory of searchPaths) {
+        const candidate = join(directory, command);
+
+        if (isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+
+    return undefined;
+};
+
+/**
+ * Resolves an executable to an absolute path, searching `PATH` only for a bare command name, so
+ * spawning it never re-runs a lookup against a `PATH` that may have changed.
+ *
+ * @param command - An executable name, or a path to one.
+ * @returns The absolute path of the executable.
+ * @throws When a bare command name is not found on `PATH`.
+ *
+ * @example
+ * resolveExecutable("weston"); // "/usr/bin/weston"
+ */
+function resolveExecutable(command: string): string {
+    if (isAbsolute(command)) {
+        return command;
+    }
+
+    if (command.includes("/")) {
+        return resolve(command);
+    }
+
+    const found = findOnPath(command);
+
+    if (found === undefined) {
+        throw new Error(`Cannot find the "${command}" executable on PATH`);
+    }
+
+    return found;
+}
+
+export { resolveExecutable };

package/src/set/drain.ts

@@ -0,0 +1,17 @@
+/**
+ * Iterates every item currently in `set`, then clears it. Use it to drain a set of pending work
+ * accumulated since the last drain.
+ *
+ * @template T - The set item type.
+ * @param set - The set to drain and clear.
+ * @param visit - Called with each item before the set is cleared.
+ */
+const drain = <T>(set: Set<T>, visit: (item: T) => void): void => {
+    for (const item of set) {
+        visit(item);
+    }
+
+    set.clear();
+};
+
+export { drain };

package/src/set/index.ts

@@ -0,0 +1 @@
+export { drain } from "./drain.js";

package/src/source/index.ts

@@ -0,0 +1,3 @@
+export { sanitizeIdentifier } from "./sanitize-identifier.js";
+export { sourceStringLiteral } from "./source-string-literal.js";
+export { toCamelIdentifier } from "./to-camel-identifier.js";

package/src/source/sanitize-identifier.ts

@@ -0,0 +1,66 @@
+const RESERVED: Set<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",
+]);
+
+/**
+ * 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.
+ *
+ * @param name - The candidate identifier.
+ * @returns The name, suffixed with `_` when it is a reserved word.
+ *
+ * @example
+ * sanitizeIdentifier("iconName"); // "iconName"
+ * sanitizeIdentifier("class"); // "class_"
+ */
+function sanitizeIdentifier(name: string): string {
+    return RESERVED.has(name) ? `${name}_` : name;
+}
+
+export { sanitizeIdentifier };

package/src/source/source-string-literal.ts

@@ -0,0 +1,27 @@
+const LINE_SEPARATOR = String.fromCodePoint(0x20_28);
+const PARAGRAPH_SEPARATOR = String.fromCodePoint(0x20_29);
+
+const SOURCE_ESCAPES: Record<string, string> = {
+    "<": String.raw`\u003C`,
+    ">": String.raw`\u003E`,
+    [LINE_SEPARATOR]: String.raw`\u2028`,
+    [PARAGRAPH_SEPARATOR]: String.raw`\u2029`,
+};
+
+const UNSAFE_SOURCE_CHARS = new RegExp(`[${Object.keys(SOURCE_ESCAPES).join("")}]`, "g");
+
+/**
+ * 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 encode.
+ * @returns The quoted, source-safe string literal.
+ *
+ * @example
+ * sourceStringLiteral("hello"); // '"hello"'
+ */
+function sourceStringLiteral(value: string): string {
+    return JSON.stringify(value).replaceAll(UNSAFE_SOURCE_CHARS, (char) => SOURCE_ESCAPES[char] ?? char);
+}
+
+export { sourceStringLiteral };

package/src/source/to-camel-identifier.ts

@@ -0,0 +1,18 @@
+import { camelCase } from "../string/camel-case.js";
+import { sanitizeIdentifier } from "./sanitize-identifier.js";
+
+/**
+ * Converts a name to camel case and sanitizes it into a valid JavaScript identifier.
+ *
+ * @param name - The name to convert.
+ * @returns The camel-cased, reserved-word-safe identifier.
+ *
+ * @example
+ * toCamelIdentifier("icon_name"); // "iconName"
+ * toCamelIdentifier("class"); // "class_"
+ */
+function toCamelIdentifier(name: string): string {
+    return sanitizeIdentifier(camelCase(name));
+}
+
+export { toCamelIdentifier };

package/src/string/camel-case.ts

@@ -0,0 +1,22 @@
+import { upperFirst } from "./upper-first.js";
+import { mapWordSegments } from "./word-segments.js";
+
+/**
+ * Converts an underscore- or hyphen-delimited string to camel case.
+ *
+ * Unlike a general-purpose converter, this splits only on `_` and `-` and keeps the first segment
+ * verbatim, so GObject acronyms are preserved (`camelCase("GLArea")` stays `"GLArea"`).
+ *
+ * @param str - The string to convert.
+ * @returns The camel-cased string.
+ *
+ * @example
+ * camelCase("icon_name"); // "iconName"
+ * camelCase("start-widget"); // "startWidget"
+ * camelCase("Box"); // "Box"
+ */
+function camelCase(str: string): string {
+    return mapWordSegments(str, (part, index) => (index === 0 ? part : upperFirst(part)));
+}
+
+export { camelCase };