@gtkx/utils 0.21.0 → 1.0.0-rc.2

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 };

package/src/string/index.ts

@@ -0,0 +1,5 @@
+export { camelCase } from "./camel-case.js";
+export { kebabCase } from "./kebab-case.js";
+export { lowerFirst } from "./lower-first.js";
+export { pascalCase } from "./pascal-case.js";
+export { upperFirst } from "./upper-first.js";

package/src/string/kebab-case.ts

@@ -0,0 +1,18 @@
+/**
+ * Converts a camelCase or PascalCase string to kebab case by lower-casing uppercase letters and
+ * inserting hyphens before interior ones.
+ *
+ * @param str - The string to convert.
+ * @returns The kebab-cased string.
+ *
+ * @example
+ * kebabCase("iconName"); // "icon-name"
+ * kebabCase("Title"); // "title"
+ */
+function kebabCase(str: string): string {
+    return str.replaceAll(/[A-Z]/g, (char, index: number) =>
+        index === 0 ? char.toLowerCase() : `-${char.toLowerCase()}`,
+    );
+}
+
+export { kebabCase };

package/src/string/lower-first.ts

@@ -0,0 +1,15 @@
+/**
+ * Converts the first character of a string to lower case.
+ *
+ * @param str - The string to transform.
+ * @returns The string with its first character lower-cased.
+ *
+ * @example
+ * lowerFirst("Fred"); // "fred"
+ * lowerFirst("FRED"); // "fRED"
+ */
+function lowerFirst(str: string): string {
+    return str.charAt(0).toLowerCase() + str.slice(1);
+}
+
+export { lowerFirst };

package/src/string/pascal-case.ts

@@ -0,0 +1,21 @@
+import { upperFirst } from "./upper-first.js";
+import { mapWordSegments } from "./word-segments.js";
+
+/**
+ * Converts an underscore- or hyphen-delimited string to Pascal case.
+ *
+ * Splits only on `_` and `-` and capitalizes each segment's first character, so GObject acronyms
+ * are preserved (`pascalCase("GLArea")` stays `"GLArea"`).
+ *
+ * @param str - The string to convert.
+ * @returns The Pascal-cased string.
+ *
+ * @example
+ * pascalCase("icon_name"); // "IconName"
+ * pascalCase("scrolled-window"); // "ScrolledWindow"
+ */
+function pascalCase(str: string): string {
+    return mapWordSegments(str, upperFirst);
+}
+
+export { pascalCase };

package/src/string/upper-first.ts

@@ -0,0 +1,15 @@
+/**
+ * Converts the first character of a string to upper case.
+ *
+ * @param str - The string to transform.
+ * @returns The string with its first character upper-cased.
+ *
+ * @example
+ * upperFirst("fred"); // "Fred"
+ * upperFirst("Fred"); // "Fred"
+ */
+function upperFirst(str: string): string {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+export { upperFirst };

package/src/string/word-segments.ts

@@ -0,0 +1,15 @@
+function splitWords(input: string): string[] {
+    return input.split(/[_-]/g).filter((part) => part.length > 0);
+}
+
+function mapWordSegments(input: string, mapSegment: (part: string, index: number) => string): string {
+    const parts = splitWords(input);
+
+    if (parts.length === 0) {
+        return input;
+    }
+
+    return parts.map((part, index) => mapSegment(part, index)).join("");
+}
+
+export { mapWordSegments };

package/src/util/index.ts

@@ -0,0 +1 @@
+export { packageVersion } from "./package-version.js";

package/src/util/package-version.ts

@@ -0,0 +1,16 @@
+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`.
+ * @returns The package's version string.
+ *
+ * @example
+ * packageVersion(import.meta.url); // "1.2.3"
+ */
+function packageVersion(importMetaUrl: string): string {
+    return (createRequire(importMetaUrl)("../package.json") as { version: string }).version;
+}
+
+export { packageVersion };

package/dist/class.d.ts

@@ -1,16 +0,0 @@
-/**
- * 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;
-};
-//# sourceMappingURL=class.d.ts.map

package/dist/class.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"class.d.ts","sourceRoot":"","sources":["../src/class.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,MACvD,GAAG,IAAI,EAAE,KAAK,EAAE,KACf,CAAC,CAAC,GAAG;IACN,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;CACzB,CAAC"}

package/dist/class.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=class.js.map

package/dist/class.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"class.js","sourceRoot":"","sources":["../src/class.ts"],"names":[],"mappings":""}

package/dist/collection.d.ts

@@ -1,58 +0,0 @@
-/**
- * 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 declare const omit: <T extends Record<string, unknown>>(record: T, keys: readonly string[]) => 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 declare const isShallowEqual: <T extends string | number | boolean>(a: readonly T[] | null | undefined, b: readonly T[] | null | undefined) => boolean;
-/**
- * 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 declare const isShallowArrayEqual: <T extends Record<string, unknown>>(a: readonly T[], b: readonly T[]) => boolean;
-/**
- * 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 declare const reverseNumericEnum: (enumObject: Record<string, string | number>) => Map<number, string>;
-//# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,KAAG,CAQ5F,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,EAC9D,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,EAClC,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,KACnC,OAQF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,SAAS,CAAC,EAAE,EAAE,GAAG,SAAS,CAAC,EAAE,KAAG,OAkBzG,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,YAAY,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAK9F,CAAC"}

package/dist/collection.js

@@ -1,98 +0,0 @@
-/**
- * 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 = (record, keys) => {
-    const result = {};
-    for (const key of Object.keys(record)) {
-        if (!keys.includes(key)) {
-            result[key] = record[key];
-        }
-    }
-    return result;
-};
-/**
- * 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 = (a, b) => {
-    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 = (a, b) => {
-    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) => new Map(Object.entries(enumObject)
-    .filter((entry) => typeof entry[1] === "number")
-    .map(([name, value]) => [value, name]));
-//# sourceMappingURL=collection.js.map

package/dist/collection.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"collection.js","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAoC,MAAS,EAAE,IAAuB,EAAK,EAAE;IAC7F,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC;IACL,CAAC;IACD,OAAO,MAAW,CAAC;AACvB,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC1B,CAAkC,EAClC,CAAkC,EAC3B,EAAE;IACT,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAoC,CAAe,EAAE,CAAe,EAAW,EAAE;IAChH,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAExC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACnB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QAEnC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAEhD,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;YACtB,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC;QAChD,CAAC;IACL,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,UAA2C,EAAuB,EAAE,CACnG,IAAI,GAAG,CACH,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;KACrB,MAAM,CAAC,CAAC,KAAK,EAA6B,EAAE,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC;KAC1E,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAC7C,CAAC"}

package/dist/error.d.ts

@@ -1,13 +0,0 @@
-/**
- * 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 declare const errorMessage: (error: unknown) => string;
-//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,MAAkE,CAAC"}

package/dist/error.js

@@ -1,13 +0,0 @@
-/**
- * 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) => (error instanceof Error ? error.message : String(error));
-//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAc,EAAU,EAAE,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC"}

package/dist/graceful-shutdown.d.ts

@@ -1,70 +0,0 @@
-/**
- * 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.
- */
-/**
- * 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 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;
-};
-/**
- * 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 declare const installGracefulShutdown: (options: GracefulShutdownOptions) => GracefulShutdownHandle;
-//# sourceMappingURL=graceful-shutdown.d.ts.map

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

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

@@ -1,94 +0,0 @@
-/**
- * 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