@gtkx/utils 0.21.0 → 1.0.0-rc.1

package/README.md

@@ -0,0 +1,173 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gtkx-org/gtkx/main/logo.svg" alt="GTKX" width="100" />
+</p>
+
+<h1 align="center">GTKX</h1>
+
+<p align="center">
+  The React framework for Linux.<br />
+  Build GTK4 and Adwaita apps in TypeScript, with React components and hooks driving GNOME's own widgets. What you ship is a GNOME app.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/create-gtkx"><img src="https://img.shields.io/npm/v/create-gtkx?color=cb3837&logo=npm&label=create-gtkx" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/create-gtkx"><img src="https://img.shields.io/npm/dm/create-gtkx?color=cb3837&logo=npm&label=downloads" alt="npm downloads" /></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A524-339933?logo=node.js&logoColor=white" alt="Node >= 24" />
+  <a href="https://github.com/gtkx-org/gtkx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue.svg" alt="License: MPL-2.0" /></a>
+  <a href="https://github.com/gtkx-org/gtkx/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/gtkx-org/gtkx/ci.yml?branch=main&logo=github&label=CI" alt="CI status" /></a>
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white" alt="TypeScript" />
+</p>
+
+<p align="center">
+  <a href="https://gtkx.dev">Homepage</a> &middot;
+  <a href="https://gtkx.dev/guide/why-gtkx">Documentation</a> &middot;
+  <a href="https://github.com/gtkx-org/gtkx/tree/main/examples">Examples</a> &middot;
+  <a href="https://github.com/gtkx-org/gtkx/blob/main/CONTRIBUTING.md">Contributing</a>
+</p>
+
+---
+
+GTKX generates fully typed bindings for the entire GTK4 and Adwaita surface directly from GObject-Introspection. On top of those bindings you get the React programming model: components and hooks driving GObject instances, with Fast Refresh while you develop.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gtkx-org/gtkx/main/examples/tutorial/assets/screenshot.png" alt="The Tasks app: an Adwaita window with a sidebar of smart views and colored lists on the left, and a boxed task list on the right." />
+</p>
+
+<p align="center">
+  <em>The Tasks app you build in the <a href="https://gtkx.dev/tutorial/">tutorial</a>.</em>
+</p>
+
+## Demo
+
+The intrinsic elements in this snippet render GTK4 widgets, and ordinary React hooks and events drive them:
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkApplication, GtkApplicationWindow, GtkBox, GtkButton, GtkLabel } from "@gtkx/jsx/gtk";
+import { createRoot, quit } from "@gtkx/react";
+import { useState } from "react";
+
+const Counter = () => {
+  const [count, setCount] = useState(0);
+
+  return (
+    <GtkApplicationWindow
+      title="Hello GTKX"
+      defaultWidth={400}
+      defaultHeight={300}
+      onCloseRequest={quit}
+    >
+      <GtkBox
+        orientation={Gtk.Orientation.VERTICAL}
+        spacing={20}
+        marginTop={40}
+        marginBottom={40}
+        marginStart={40}
+        marginEnd={40}
+        valign={Gtk.Align.CENTER}
+        halign={Gtk.Align.CENTER}
+      >
+        <GtkLabel cssClasses={["title-1"]}>Welcome to GTKX!</GtkLabel>
+        <GtkLabel cssClasses={["title-2"]}>{`Count: ${count}`}</GtkLabel>
+        <GtkButton
+          label="Increment"
+          onClicked={() => setCount((c) => c + 1)}
+          cssClasses={["suggested-action", "pill"]}
+        />
+      </GtkBox>
+    </GtkApplicationWindow>
+  );
+};
+
+const App = () => (
+  <GtkApplication>
+    <Counter />
+  </GtkApplication>
+);
+
+createRoot().render(<App />);
+```
+
+This is the [`hello-world`](https://github.com/gtkx-org/gtkx/tree/main/examples/hello-world) example, with `app.tsx` and `index.tsx` combined into a single snippet. `@gtkx/gi` and `@gtkx/jsx` are per-project bindings generated by the CLI, not packages you install from npm.
+
+## Why GTKX
+
+### A declarative layer for the GNOME stack
+
+GTK4 is mature, and GtkBuilder XML can lay out a static interface, but nothing re-renders that interface when your application state changes, and nothing hot-reloads it as you work. GTKX adds that missing layer, and the tooling around it, on top of the stack you already know:
+
+- a React reconciler that exposes every GObject as a JSX element,
+- a CLI for scaffolding, development, and production builds,
+- a dev server with Fast Refresh that patches your running UI in place,
+- CSS-in-JS styling and high-level list, grid, and dialog components,
+- a Testing Library-style API for querying and driving your widgets in tests,
+- and a Model Context Protocol (MCP) server that exposes your live app to AI agents.
+
+### The full GNOME API surface
+
+React Native and similar frameworks hide the native toolkit so one API can run everywhere. GTKX exposes it: GTK4, Adwaita, and any other GObject-Introspection library on your system. Linux-only by design.
+
+### Why Node.js, and why generated bindings
+
+GTKX runs on Node.js, which puts native modules, the npm ecosystem, and the tooling built for Node.js APIs within reach. GJS is GNOME's own runtime, built on SpiderMonkey rather than V8; node-gtk runs on Node.js but is lightly maintained, on the older nan/V8 ABI rather than N-API, and still centered on GTK3. The [why-gtkx guide](https://gtkx.dev/guide/why-gtkx) covers the comparison in full.
+
+GTKX generates the TypeScript types and the native FFI calls from the same GObject-Introspection data, so the types cannot drift from the calls they back. Codegen covers the whole GTK4 and Adwaita surface.
+
+At runtime, the native Rust core calls straight into the system GTK4, Adwaita, and GLib libraries through libffi, without loading libgirepository at all.
+
+## Quick start
+
+GTKX is Linux-only and needs Node.js 24 or later. See [Requirements](#requirements).
+
+Scaffold a new app with the `create-gtkx` initializer:
+
+```sh
+npm create gtkx@rc
+```
+
+The same command works with other package managers: `pnpm create gtkx@rc` or `yarn create gtkx@rc`.
+
+Then run your new app:
+
+```sh
+cd my-app
+npm run dev
+```
+
+To go further, follow the [tutorial](https://gtkx.dev/tutorial/).
+
+## Documentation
+
+The documentation at **[gtkx.dev](https://gtkx.dev)** includes a step-by-step tutorial that builds a complete GNOME app, from scaffolding to packaging and shipping, plus guides and a full API reference.
+
+**[Read the docs &rarr;](https://gtkx.dev/guide/why-gtkx)**
+
+## Requirements
+
+GTKX is Linux-only. You need:
+
+- Linux with the GTK4 (4.20 or later), Adwaita (1.8 or later), and GLib development libraries
+- Node.js 24 or later
+
+The `@gtkx/native` addon ships prebuilt for x64 and arm64 glibc Linux; other targets need to build it from the GTKX repository, which requires a Rust toolchain.
+
+## Examples
+
+Explore the [example apps](https://github.com/gtkx-org/gtkx/tree/main/examples):
+
+- [`hello-world`](https://github.com/gtkx-org/gtkx/tree/main/examples/hello-world): the counter above.
+- [`gtk-demo`](https://github.com/gtkx-org/gtkx/tree/main/examples/gtk-demo): a React port of the official GTK4 widget showcase, covering lists, dialogs, gestures, CSS, and OpenGL.
+- [`browser`](https://github.com/gtkx-org/gtkx/tree/main/examples/browser): a WebKitWebView-based web browser.
+- [`tutorial`](https://github.com/gtkx-org/gtkx/tree/main/examples/tutorial): the Tasks app the documentation builds.
+
+## Status
+
+GTKX 1.0 is at the release candidate stage.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](https://github.com/gtkx-org/gtkx/blob/main/CONTRIBUTING.md), the [Code of Conduct](https://github.com/gtkx-org/gtkx/blob/main/CODE_OF_CONDUCT.md), and the [security policy](https://github.com/gtkx-org/gtkx/blob/main/SECURITY.md). Building the repo needs Node.js 24 or later, pnpm, and a Rust toolchain.
+
+## License
+
+GTKX is licensed under [MPL-2.0](https://github.com/gtkx-org/gtkx/blob/main/LICENSE).

package/dist/class.d.ts

@@ -1,16 +1,22 @@
 /**
- * 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.
+ * A constructor value of any (possibly abstract) class producing instances of `T`.
  */
 export type AnyClass<T extends object = object> = (abstract new (...args: never[]) => T) & {
-    readonly prototype: T;
+    prototype: T;
 };
+/**
+ * Returns the direct superclass of `cls`, or `null` when it has no class ancestor.
+ *
+ * @param cls The class whose prototype parent to inspect.
+ */
+export declare function getParentClass(cls: AnyClass): AnyClass | null;
+/**
+ * Walks the class chain from `cls` up through its ancestors, calling `visit` on each and
+ * returning the first result that is not `undefined`.
+ *
+ * @param cls The class to start from, or `null` to visit nothing.
+ * @param visit Called with each class in the chain; a defined return value stops the walk.
+ * @returns The first defined result from `visit`, or `undefined` if none was produced.
+ */
+export declare function walkClassChain<T>(cls: AnyClass | null, visit: (ancestor: AnyClass) => T | undefined): T | undefined;
 //# sourceMappingURL=class.d.ts.map

package/dist/class.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"class.d.ts","sourceRoot":"","sources":["../src/class.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,MACvD,GAAG,IAAI,EAAE,KAAK,EAAE,KACf,CAAC,CAAC,GAAG;IACN,SAAS,EAAE,CAAC,CAAC;CAChB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAG7D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,CAAC,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAQnH"}

package/dist/class.js

@@ -1,2 +1,28 @@
-export {};
+/**
+ * Returns the direct superclass of `cls`, or `null` when it has no class ancestor.
+ *
+ * @param cls The class whose prototype parent to inspect.
+ */
+export function getParentClass(cls) {
+    const parent = Object.getPrototypeOf(cls);
+    return typeof parent === "function" && parent !== Function.prototype ? parent : null;
+}
+/**
+ * Walks the class chain from `cls` up through its ancestors, calling `visit` on each and
+ * returning the first result that is not `undefined`.
+ *
+ * @param cls The class to start from, or `null` to visit nothing.
+ * @param visit Called with each class in the chain; a defined return value stops the walk.
+ * @returns The first defined result from `visit`, or `undefined` if none was produced.
+ */
+export function walkClassChain(cls, visit) {
+    let current = cls;
+    while (current !== null) {
+        const result = visit(current);
+        if (result !== undefined)
+            return result;
+        current = getParentClass(current);
+    }
+    return undefined;
+}
 //# sourceMappingURL=class.js.map

package/dist/class.js.map

@@ -1 +1 @@
-{"version":3,"file":"class.js","sourceRoot":"","sources":["../src/class.ts"],"names":[],"mappings":""}
+{"version":3,"file":"class.js","sourceRoot":"","sources":["../src/class.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAa;IACxC,MAAM,MAAM,GAAY,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IACnD,OAAO,OAAO,MAAM,KAAK,UAAU,IAAI,MAAM,KAAK,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAE,MAAmB,CAAC,CAAC,CAAC,IAAI,CAAC;AACvG,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAI,GAAoB,EAAE,KAA4C;IAChG,IAAI,OAAO,GAAG,GAAG,CAAC;IAClB,OAAO,OAAO,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9B,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QACxC,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,SAAS,CAAC;AACrB,CAAC","sourcesContent":["/**\n * A constructor value of any (possibly abstract) class producing instances of `T`.\n */\nexport type AnyClass<T extends object = object> = (abstract new (\n    ...args: never[]\n) => T) & {\n    prototype: T;\n};\n\n/**\n * Returns the direct superclass of `cls`, or `null` when it has no class ancestor.\n *\n * @param cls The class whose prototype parent to inspect.\n */\nexport function getParentClass(cls: AnyClass): AnyClass | null {\n    const parent: unknown = Object.getPrototypeOf(cls);\n    return typeof parent === \"function\" && parent !== Function.prototype ? (parent as AnyClass) : null;\n}\n\n/**\n * Walks the class chain from `cls` up through its ancestors, calling `visit` on each and\n * returning the first result that is not `undefined`.\n *\n * @param cls The class to start from, or `null` to visit nothing.\n * @param visit Called with each class in the chain; a defined return value stops the walk.\n * @returns The first defined result from `visit`, or `undefined` if none was produced.\n */\nexport function walkClassChain<T>(cls: AnyClass | null, visit: (ancestor: AnyClass) => T | undefined): T | undefined {\n    let current = cls;\n    while (current !== null) {\n        const result = visit(current);\n        if (result !== undefined) return result;\n        current = getParentClass(current);\n    }\n    return undefined;\n}\n"]}

package/dist/collection.d.ts

@@ -1,58 +1,30 @@
 /**
- * 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.
+ * Returns the items with duplicates removed, keeping the first item for each distinct key.
  *
- * @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`.
+ * @param items The items to deduplicate.
+ * @param key Computes the identity string used to detect duplicates.
  */
-export declare const omit: <T extends Record<string, unknown>>(record: T, keys: readonly string[]) => T;
+export declare const uniqBy: <T>(items: T[], key: (item: T) => string) => T[];
+export declare const isSameArray: <T>(a: T[], b: T[]) => boolean;
 /**
- * Compares two arrays of primitives for element-wise strict equality.
+ * Returns a new array of the given strings sorted with locale-aware comparison.
  *
- * 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.
+ * @param values The strings to sort.
  */
-export declare const isShallowEqual: <T extends string | number | boolean>(a: readonly T[] | null | undefined, b: readonly T[] | null | undefined) => boolean;
+export declare const sortStrings: (values: Iterable<string>) => string[];
 /**
- * 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.
+ * Returns a new array of the given items sorted by a locale-aware comparison of their keys.
  *
- * @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.
+ * @param items The items to sort.
+ * @param key Computes the string to sort each item by.
  */
-export declare const isShallowArrayEqual: <T extends Record<string, unknown>>(a: readonly T[], b: readonly T[]) => boolean;
+export declare const sortStringsBy: <T>(items: Iterable<T>, key: (item: T) => string) => T[];
 /**
- * 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.
+ * Determines whether two records have the same keys and strictly equal values.
  *
- * @param enumObject - A numeric enum's runtime object.
- * @returns A map from each numeric enum value to its declared member name.
+ * @param a The first record, or `undefined`.
+ * @param b The second record, or `undefined`.
+ * @returns `true` when both are the same reference, or both are defined with identical own keys and values.
  */
-export declare const reverseNumericEnum: (enumObject: Record<string, string | number>) => Map<number, string>;
+export declare const isShallowEqual: <T extends Record<string, unknown>>(a?: T, b?: T) => boolean;
 //# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,KAAG,CAAC,EAUjE,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,EAAE,KAAG,OAM/C,CAAC;AAIF;;;;GAIG;AACH,eAAO,MAAM,WAAW,WAAY,QAAQ,CAAC,MAAM,CAAC,KAAG,MAAM,EAAsC,CAAC;AAEpG;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,KAAG,CAAC,EACpB,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAG,OAahF,CAAC"}

package/dist/collection.js

@@ -1,98 +1,64 @@
 /**
- * Pure, runtime-agnostic collection helpers shared across GTKX packages.
- */
-/**
- * Returns a shallow copy of `record` with the given `keys` removed.
+ * Returns the items with duplicates removed, keeping the first item for each distinct key.
  *
- * 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`.
+ * @param items The items to deduplicate.
+ * @param key Computes the identity string used to detect duplicates.
  */
-export const omit = (record, keys) => {
-    const result = {};
-    for (const key of Object.keys(record)) {
-        if (!keys.includes(key)) {
-            result[key] = record[key];
-        }
+export const uniqBy = (items, key) => {
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const identity = key(item);
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        result.push(item);
     }
     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;
+export const isSameArray = (a, b) => {
     if (a.length !== b.length)
         return false;
-    for (let i = 0; i < a.length; i++) {
-        if (a[i] !== b[i])
+    for (let index = 0; index < a.length; index++) {
+        if (a[index] !== b[index])
             return false;
     }
     return true;
 };
+const compareStrings = (a, b) => a.localeCompare(b);
+/**
+ * Returns a new array of the given strings sorted with locale-aware comparison.
+ *
+ * @param values The strings to sort.
+ */
+export const sortStrings = (values) => [...values].sort(compareStrings);
 /**
- * Compares two arrays of records by shallow per-element equality.
+ * Returns a new array of the given items sorted by a locale-aware comparison of their keys.
  *
- * 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.
+ * @param items The items to sort.
+ * @param key Computes the string to sort each item by.
+ */
+export const sortStringsBy = (items, key) => [...items].sort((a, b) => compareStrings(key(a), key(b)));
+/**
+ * Determines whether two records have the same keys and strictly equal values.
  *
- * @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.
+ * @param a The first record, or `undefined`.
+ * @param b The second record, or `undefined`.
+ * @returns `true` when both are the same reference, or both are defined with identical own keys and values.
  */
-export const isShallowArrayEqual = (a, b) => {
-    if (a.length !== b.length)
+export const isShallowEqual = (a, b) => {
+    if (a === b)
+        return true;
+    if (!a || !b)
         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)
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const key of keysA) {
+        if (a[key] !== b[key])
             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 +1 @@
-{"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"}
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAI,KAAU,EAAE,GAAwB,EAAO,EAAE;IACnE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAQ,EAAE,CAAC;IACvB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,SAAS;QACjC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAI,CAAM,EAAE,CAAM,EAAW,EAAE;IACtD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAC5C,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;IAC5C,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;AAE5E;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAwB,EAAY,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAEpG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAI,KAAkB,EAAE,GAAwB,EAAO,EAAE,CAClF,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAoC,CAAK,EAAE,CAAK,EAAW,EAAE;IACvF,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAE3B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAEhD,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IACxC,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC,CAAC","sourcesContent":["/**\n * Returns the items with duplicates removed, keeping the first item for each distinct key.\n *\n * @param items The items to deduplicate.\n * @param key Computes the identity string used to detect duplicates.\n */\nexport const uniqBy = <T>(items: T[], key: (item: T) => string): T[] => {\n    const seen = new Set<string>();\n    const result: T[] = [];\n    for (const item of items) {\n        const identity = key(item);\n        if (seen.has(identity)) continue;\n        seen.add(identity);\n        result.push(item);\n    }\n    return result;\n};\n\nexport const isSameArray = <T>(a: T[], b: T[]): boolean => {\n    if (a.length !== b.length) return false;\n    for (let index = 0; index < a.length; index++) {\n        if (a[index] !== b[index]) return false;\n    }\n    return true;\n};\n\nconst compareStrings = (a: string, b: string): number => a.localeCompare(b);\n\n/**\n * Returns a new array of the given strings sorted with locale-aware comparison.\n *\n * @param values The strings to sort.\n */\nexport const sortStrings = (values: Iterable<string>): string[] => [...values].sort(compareStrings);\n\n/**\n * Returns a new array of the given items sorted by a locale-aware comparison of their keys.\n *\n * @param items The items to sort.\n * @param key Computes the string to sort each item by.\n */\nexport const sortStringsBy = <T>(items: Iterable<T>, key: (item: T) => string): T[] =>\n    [...items].sort((a, b) => compareStrings(key(a), key(b)));\n\n/**\n * Determines whether two records have the same keys and strictly equal values.\n *\n * @param a The first record, or `undefined`.\n * @param b The second record, or `undefined`.\n * @returns `true` when both are the same reference, or both are defined with identical own keys and values.\n */\nexport const isShallowEqual = <T extends Record<string, unknown>>(a?: T, b?: T): boolean => {\n    if (a === b) return true;\n    if (!a || !b) return false;\n\n    const keysA = Object.keys(a);\n    const keysB = Object.keys(b);\n    if (keysA.length !== keysB.length) return false;\n\n    for (const key of keysA) {\n        if (a[key] !== b[key]) return false;\n    }\n\n    return true;\n};\n"]}

package/dist/error.d.ts

@@ -1,13 +1,21 @@
 /**
- * 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 of unknown shape.
- * @returns A string describing the error.
+ * @param error The caught value to describe.
  */
 export declare const errorMessage: (error: unknown) => string;
+/**
+ * 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 declare const normalizeError: (error: unknown) => Error;
+/**
+ * Combines the `stderr` and `stdout` fields of a failed child-process error into a single trimmed string.
+ *
+ * @param error The child-process error to read output from.
+ * @returns The joined output, or `undefined` when neither stream carried any text.
+ */
+export declare const formatChildProcessError: (error: unknown) => string | undefined;
 //# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,eAAO,MAAM,YAAY,UAAW,OAAO,KAAG,MACgC,CAAC;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,cAAc,UAAW,OAAO,KAAG,KAG/C,CAAC;AAQF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,UAAW,OAAO,KAAG,MAAM,GAAG,SAKjE,CAAC"}

package/dist/error.js

@@ -1,13 +1,40 @@
+const isObject = (value) => typeof value === "object" && value !== null;
+const isErrorLike = (value) => 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) => 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) => {
+    if (Error.isError(error))
+        return error;
+    return Object.assign(new Error(errorMessage(error)), isErrorLike(error) ? error : {});
+};
+const readStream = (value) => {
+    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) => (error instanceof Error ? error.message : String(error));
+export const formatChildProcessError = (error) => {
+    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;
+};
 //# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AAEnH,MAAM,WAAW,GAAG,CAAC,KAAc,EAAgC,EAAE,CACjE,QAAQ,CAAC,KAAK,CAAC,IAAI,SAAS,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAc,EAAU,EAAE,CACnD,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAc,EAAS,EAAE;IACpD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC1F,CAAC,CAAC;AAEF,MAAM,UAAU,GAAG,CAAC,KAAc,EAAU,EAAE;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,YAAY,UAAU,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;IACnF,OAAO,EAAE,CAAC;AACd,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,KAAc,EAAsB,EAAE;IAC1E,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACvC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACjC,MAAM,OAAO,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3F,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC,CAAC","sourcesContent":["const isObject = (value: unknown): value is Record<string, unknown> => typeof value === \"object\" && value !== null;\n\nconst isErrorLike = (value: unknown): value is { message: string } =>\n    isObject(value) && \"message\" in value && typeof value.message === \"string\";\n\n/**\n * Extracts a human-readable message from an unknown thrown value, falling back to its string form.\n *\n * @param error The caught value to describe.\n */\nexport const errorMessage = (error: unknown): string =>\n    Error.isError(error) || isErrorLike(error) ? error.message : String(error);\n\n/**\n * Coerces an unknown thrown value into an `Error`, reusing it if it already is one and otherwise\n * wrapping its message while copying any error-like own properties.\n *\n * @param error The caught value to normalize.\n */\nexport const normalizeError = (error: unknown): Error => {\n    if (Error.isError(error)) return error;\n    return Object.assign(new Error(errorMessage(error)), isErrorLike(error) ? error : {});\n};\n\nconst readStream = (value: unknown): string => {\n    if (typeof value === \"string\") return value;\n    if (value instanceof Uint8Array || Buffer.isBuffer(value)) return value.toString();\n    return \"\";\n};\n\n/**\n * Combines the `stderr` and `stdout` fields of a failed child-process error into a single trimmed string.\n *\n * @param error The child-process error to read output from.\n * @returns The joined output, or `undefined` when neither stream carried any text.\n */\nexport const formatChildProcessError = (error: unknown): string | undefined => {\n    if (!isObject(error)) return undefined;\n    const { stderr, stdout } = error;\n    const details = [readStream(stderr), readStream(stdout)].filter(Boolean).join(\"\\n\").trim();\n    return details.length > 0 ? details : undefined;\n};\n"]}