@hydranium/core 1.0.0-next.10

package/lib/util/registry.d.ts

@@ -0,0 +1,88 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { Disposable } from 'vscode-languageserver';
+/**
+ * Common shape for items stored in a {@link Registry}: a stable identity, an
+ * optional label for log lines, and an optional sort key.
+ */
+export interface RegistryItem {
+    /** Stable machine identifier; required, and must be unique within the registry. */
+    readonly id: string;
+    /** Human-readable name for logs; consumers fall back to {@link RegistryItem.id} when it is absent. */
+    readonly label?: string;
+    /**
+     * Sort key for {@link Registry.all}: lower runs first, ties break by
+     * registration order. Defaults to `0`, so items that set no priority keep
+     * their registration order among themselves.
+     */
+    readonly priority?: number;
+}
+/**
+ * A small, generic, id-keyed registry with priority-ordered iteration, used
+ * wherever a framework service needs multi-binding-style registration.
+ *
+ * Identity lives on the item itself ({@link RegistryItem.id}) rather than on a
+ * registration handle, so an adopter can remove a built-in registration by id
+ * without holding the {@link Disposable} the framework's own `register` call
+ * returned.
+ */
+export declare class Registry<T extends RegistryItem> {
+    protected readonly items: T[];
+    /** Sorted snapshot backing {@link all}; discarded on every mutation. */
+    protected cachedSorted: readonly T[] | undefined;
+    /**
+     * Add an item. Throws if an item with the same {@link RegistryItem.id} is
+     * already registered — duplicate ids are a programming error, not a
+     * silent overwrite.
+     *
+     * @returns a {@link Disposable} that removes THIS item when disposed, and
+     * nothing else. Keyed by identity rather than by {@link RegistryItem.id}:
+     * an id-keyed handle removes whatever item holds that id at the moment it
+     * is disposed, so a stale handle disposed after the id was unregistered and
+     * re-registered silently unregisters a DIFFERENT item it never owned.
+     * Identity also makes a repeat dispose inert without a separate flag.
+     */
+    register(item: T): Disposable;
+    /** Remove an item by id. Returns `true` if an item was removed, `false` otherwise. */
+    unregister(id: string): boolean;
+    /** Whether an item with the given id is registered. */
+    has(id: string): boolean;
+    /** Get an item by id, or `undefined` if not registered. */
+    get(id: string): T | undefined;
+    /** Number of registered items. */
+    get size(): number;
+    /**
+     * All registered items in iteration order: {@link RegistryItem.priority}
+     * ascending, ties broken by registration order. Priority orders the whole
+     * registry; a consumer that partitions the result further owns whatever
+     * ordering holds across its own partitions.
+     *
+     * **The identity of the returned array is part of the contract.** This is
+     * the hot read path while registration is rare, so the sorted list is built
+     * once and discarded only by a register / unregister: repeated calls with no
+     * intervening mutation return the *same* array reference and allocate
+     * nothing. Consumers rely on that reference as a cache key — deriving a
+     * secondary index from `all()` and rebuilding it only when the reference
+     * changes is the intended pattern, so returning a freshly built array per
+     * call would leave every such index rebuilding on every read. The guarantee
+     * is pinned by a test of its own.
+     *
+     * Treat the result as read-only: mutating it corrupts the cache for every
+     * other caller, which the `readonly` element type exists to prevent.
+     *
+     * Registration order for ties comes from the SORT's stability, required of
+     * `Array.prototype.sort` since ES2019, not from a secondary comparator key.
+     * A key would have to carry the index alongside each item, costing a wrapper
+     * object per item per rebuild, and could not change the result for any input
+     * — a comparator result of `NaN` or `-0` is normatively coerced to `+0`, so
+     * the primary comparison never leaves a tie for it to break differently.
+     */
+    all(): readonly T[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/lib/util/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/util/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sGAAsG;IACtG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,qBAAa,QAAQ,CAAC,CAAC,SAAS,YAAY;IACzC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,CAAM;IACnC,wEAAwE;IACxE,SAAS,CAAC,YAAY,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,CAAC;IAEjD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,UAAU;IAgB7B,sFAAsF;IACtF,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAU/B,uDAAuD;IACvD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAI9B,kCAAkC;IAClC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,GAAG,IAAI,SAAS,CAAC,EAAE;CAMrB"}

package/lib/util/registry.js

@@ -0,0 +1,105 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { Disposable } from 'vscode-languageserver';
+/**
+ * A small, generic, id-keyed registry with priority-ordered iteration, used
+ * wherever a framework service needs multi-binding-style registration.
+ *
+ * Identity lives on the item itself ({@link RegistryItem.id}) rather than on a
+ * registration handle, so an adopter can remove a built-in registration by id
+ * without holding the {@link Disposable} the framework's own `register` call
+ * returned.
+ */
+export class Registry {
+    items = [];
+    /** Sorted snapshot backing {@link all}; discarded on every mutation. */
+    cachedSorted;
+    /**
+     * Add an item. Throws if an item with the same {@link RegistryItem.id} is
+     * already registered — duplicate ids are a programming error, not a
+     * silent overwrite.
+     *
+     * @returns a {@link Disposable} that removes THIS item when disposed, and
+     * nothing else. Keyed by identity rather than by {@link RegistryItem.id}:
+     * an id-keyed handle removes whatever item holds that id at the moment it
+     * is disposed, so a stale handle disposed after the id was unregistered and
+     * re-registered silently unregisters a DIFFERENT item it never owned.
+     * Identity also makes a repeat dispose inert without a separate flag.
+     */
+    register(item) {
+        if (this.items.some(existing => existing.id === item.id)) {
+            throw new Error(`Duplicate registry id: '${item.id}'`);
+        }
+        this.items.push(item);
+        this.cachedSorted = undefined;
+        return Disposable.create(() => {
+            const index = this.items.indexOf(item);
+            if (index < 0) {
+                return;
+            }
+            this.items.splice(index, 1);
+            this.cachedSorted = undefined;
+        });
+    }
+    /** Remove an item by id. Returns `true` if an item was removed, `false` otherwise. */
+    unregister(id) {
+        const index = this.items.findIndex(item => item.id === id);
+        if (index < 0) {
+            return false;
+        }
+        this.items.splice(index, 1);
+        this.cachedSorted = undefined;
+        return true;
+    }
+    /** Whether an item with the given id is registered. */
+    has(id) {
+        return this.items.some(item => item.id === id);
+    }
+    /** Get an item by id, or `undefined` if not registered. */
+    get(id) {
+        return this.items.find(item => item.id === id);
+    }
+    /** Number of registered items. */
+    get size() {
+        return this.items.length;
+    }
+    /**
+     * All registered items in iteration order: {@link RegistryItem.priority}
+     * ascending, ties broken by registration order. Priority orders the whole
+     * registry; a consumer that partitions the result further owns whatever
+     * ordering holds across its own partitions.
+     *
+     * **The identity of the returned array is part of the contract.** This is
+     * the hot read path while registration is rare, so the sorted list is built
+     * once and discarded only by a register / unregister: repeated calls with no
+     * intervening mutation return the *same* array reference and allocate
+     * nothing. Consumers rely on that reference as a cache key — deriving a
+     * secondary index from `all()` and rebuilding it only when the reference
+     * changes is the intended pattern, so returning a freshly built array per
+     * call would leave every such index rebuilding on every read. The guarantee
+     * is pinned by a test of its own.
+     *
+     * Treat the result as read-only: mutating it corrupts the cache for every
+     * other caller, which the `readonly` element type exists to prevent.
+     *
+     * Registration order for ties comes from the SORT's stability, required of
+     * `Array.prototype.sort` since ES2019, not from a secondary comparator key.
+     * A key would have to carry the index alongside each item, costing a wrapper
+     * object per item per rebuild, and could not change the result for any input
+     * — a comparator result of `NaN` or `-0` is normatively coerced to `+0`, so
+     * the primary comparison never leaves a tie for it to break differently.
+     */
+    all() {
+        if (this.cachedSorted === undefined) {
+            this.cachedSorted = [...this.items].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+        }
+        return this.cachedSorted;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/lib/util/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/util/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAmBnD;;;;;;;;GAQG;AACH,MAAM,OAAO,QAAQ;IACC,KAAK,GAAQ,EAAE,CAAC;IACnC,wEAAwE;IAC9D,YAAY,CAA2B;IAEjD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAO;QACb,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAC9B,OAAO,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE;YAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACb,OAAO;YACV,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAC5B,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QACjC,CAAC,CAAC,CAAC;IACN,CAAC;IAED,sFAAsF;IACtF,UAAU,CAAC,EAAU;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC3D,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACb,OAAO,KAAK,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAC9B,OAAO,IAAI,CAAC;IACf,CAAC;IAED,uDAAuD;IACvD,GAAG,CAAC,EAAU;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,2DAA2D;IAC3D,GAAG,CAAC,EAAU;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,kCAAkC;IAClC,IAAI,IAAI;QACL,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,GAAG;QACA,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,YAAY,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7F,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC;IAC5B,CAAC;CACH"}

package/package.json

@@ -0,0 +1,134 @@
+{
+  "name": "@hydranium/core",
+  "version": "1.0.0-next.10",
+  "description": "Foundational runtime of the hydranium framework: AST coordination layer (services, integrity, AST extension, serialization, multi-client documents) plus the LSP textual head at the /lsp subpath. Consumed by protocol-head packages (@hydranium/data-server, @hydranium/glsp-server).",
+  "keywords": [
+    "hydranium",
+    "langium",
+    "language-server",
+    "lsp",
+    "ast",
+    "serialization"
+  ],
+  "homepage": "https://github.com/eclipse-emfcloud/hydranium/tree/main/packages/core",
+  "bugs": {
+    "url": "https://github.com/eclipse-emfcloud/hydranium/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-emfcloud/hydranium.git",
+    "directory": "packages/core"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Hydranium Team"
+  },
+  "sideEffects": [
+    "./lib/node/index.js",
+    "./lib/util/index.js"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./lsp": {
+      "types": "./lib/lsp/index.d.ts",
+      "default": "./lib/lsp/index.js"
+    },
+    "./lib/lsp": {
+      "types": "./lib/lsp/index.d.ts",
+      "default": "./lib/lsp/index.js"
+    },
+    "./node": {
+      "types": "./lib/node/index.d.ts",
+      "default": "./lib/node/index.js"
+    },
+    "./lib/node": {
+      "types": "./lib/node/index.d.ts",
+      "default": "./lib/node/index.js"
+    },
+    "./testing": {
+      "types": "./lib/testing/index.d.ts",
+      "default": "./lib/testing/index.js"
+    },
+    "./testing/node": {
+      "types": "./lib/testing/node/index.d.ts",
+      "default": "./lib/testing/node/index.js"
+    },
+    "./lib/testing/node": {
+      "types": "./lib/testing/node/index.d.ts",
+      "default": "./lib/testing/node/index.js"
+    },
+    "./lib/testing": {
+      "types": "./lib/testing/index.d.ts",
+      "default": "./lib/testing/index.js"
+    },
+    "./testing/playwright": {
+      "types": "./lib/testing/playwright/index.d.ts",
+      "default": "./lib/testing/playwright/index.js"
+    },
+    "./lib/testing/playwright": {
+      "types": "./lib/testing/playwright/index.d.ts",
+      "default": "./lib/testing/playwright/index.js"
+    }
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "src",
+    "!lib/**/*.tsbuildinfo"
+  ],
+  "scripts": {
+    "audit:mutation": "stryker run",
+    "audit:mutation:quick": "stryker run --mutate src/langium/model-service/model-service.ts",
+    "build": "tsc -b",
+    "clean": "rimraf lib tsconfig.tsbuildinfo",
+    "lint": "eslint src test --max-warnings 0",
+    "prepack": "node -e \"const m=require('./package.json'),fs=require('node:fs');const missing=[m.main,...Object.values(m.bin||{})].filter(entry=>entry&&!fs.existsSync(entry));if(missing.length){console.error('prepack '+m.name+': not built ('+missing.join(', ')+' missing). Run the build before packing: a files entry that matches nothing is skipped silently, so the tarball would ship src only.');process.exit(1);}\"",
+    "test": "npm run typecheck:test && vitest run",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "watch": "tsc -b -w --preserveWatchOutput"
+  },
+  "dependencies": {
+    "diff": "^5.2.0"
+  },
+  "devDependencies": {
+    "@hydranium/langium": "1.0.0-next.10",
+    "@hydranium/protocol": "1.0.0-next.10",
+    "@playwright/test": "^1.40.0",
+    "@types/diff": "^5.2.0",
+    "rimraf": "^5.0.0",
+    "typescript": "^5.8.0",
+    "vscode-jsonrpc": "9.0.1",
+    "vscode-languageserver": "~10.0.1",
+    "vscode-languageserver-protocol": "~3.18.2",
+    "vscode-languageserver-textdocument": "^1.0.12",
+    "vscode-languageserver-types": "^3.17.5"
+  },
+  "peerDependencies": {
+    "@hydranium/langium": "1.0.0-next.10",
+    "@hydranium/protocol": "1.0.0-next.10",
+    "@playwright/test": "^1.40.0",
+    "vscode-jsonrpc": "^8.0.0 || ^9.0.0",
+    "vscode-languageserver": "^9.0.0 || ^10.0.0",
+    "vscode-languageserver-protocol": "^3.17.5",
+    "vscode-languageserver-textdocument": "^1.0.12",
+    "vscode-languageserver-types": "^3.17.5"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
+  "//sideEffects": "NOT `false`: two barrels do work at module load that their re-exports do not account for, and a bundler skips an unflagged re-export barrel outright. `node/index.js` calls `installNodeLogFileSink()` and `installNodeWriteLockScope()`, which is how a Node host gets the log file-tee and write-lock reentrancy detection merely by importing `@hydranium/core/node`. `util/index.js` carries a bare `import '@hydranium/langium'` so the `UriUtils` namespace augmentation stays loaded for anything importing from here. Both failures are runtime-only and silent — a missing log file, a `UriUtils.toUri` that is `undefined`."
+}