@hydranium/protocol 1.0.0-next.10

package/lib/transfer-document.js

@@ -0,0 +1,46 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2023-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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransferDocument = void 0;
+var TransferDocument;
+(function (TransferDocument) {
+    /**
+     * Whether the server had this document. Branch on it where absence is an
+     * ordinary state — a view bound to a file that may not exist yet.
+     */
+    function isLoaded(document) {
+        return document.root !== undefined;
+    }
+    TransferDocument.isLoaded = isLoaded;
+    /**
+     * The same document with `root` no longer optional, or a throw. For call
+     * sites where absence is a bug rather than a branch; the whole envelope is
+     * returned because a caller needing `root` usually needs `uri` or `version`
+     * with it.
+     */
+    function assertLoaded(document) {
+        if (!isLoaded(document)) {
+            throw new Error(`No document at ${document.uri}`);
+        }
+        return document;
+    }
+    TransferDocument.assertLoaded = assertLoaded;
+    /**
+     * Construct a {@link TransferDocument} envelope. `diagnostics` defaults
+     * to `[]` so test fixtures, fake protocol implementations, and the
+     * "no diagnostics yet" code paths don't need to repeat the empty array
+     * at every call site.
+     */
+    function create(uri, version, root, diagnostics = []) {
+        return { uri, version, root, diagnostics };
+    }
+    TransferDocument.create = create;
+})(TransferDocument || (exports.TransferDocument = TransferDocument = {}));
+//# sourceMappingURL=transfer-document.js.map

package/lib/transfer-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-document.js","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAmDlF,IAAiB,gBAAgB,CAwChC;AAxCD,WAAiB,gBAAgB;IAC9B;;;OAGG;IACH,SAAgB,QAAQ,CACrB,QAAkD;QAElD,OAAO,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC;IACtC,CAAC;IAJe,yBAAQ,WAIvB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CACzB,QAAkD;QAElD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,kBAAkB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,QAAQ,CAAC;IACnB,CAAC;IAPe,6BAAY,eAO3B,CAAA;IAED;;;;;OAKG;IACH,SAAgB,MAAM,CACnB,GAAW,EACX,OAAe,EACf,IAAe,EACf,cAA6B,EAAE;QAE/B,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAC9C,CAAC;IAPe,uBAAM,SAOrB,CAAA;AACJ,CAAC,EAxCgB,gBAAgB,gCAAhB,gBAAgB,QAwChC"}

package/lib/transfer-element.d.ts

@@ -0,0 +1,39 @@
+/********************************************************************************
+ * Copyright (c) 2023-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
+ ********************************************************************************/
+/**
+ * Base shapes for the transfer-model overlay generated per consumer language.
+ *
+ * Every node in a generated transfer model extends {@link TransferElement} and
+ * cross-references between nodes serialise as plain strings. These types carry no
+ * language-specific knowledge — language-specific types live in the consumer's
+ * generated `transfer-model.ts` overlay, emitted by the code generator from
+ * the consumer's grammar.
+ */
+/** Base type of every transfer-model node — carries the AST type discriminator. */
+export interface TransferElement {
+    readonly $type: string;
+}
+/**
+ * Type-level lookup: given an AST node type `T` (with a string-literal
+ * `$type` discriminator from Langium's generated AST) and a per-grammar
+ * `TTransferMap` overlay keyed by those `$type` strings, resolve to the
+ * declared wire shape — or fall back to the structural base
+ * {@link TransferElement} when no entry is declared.
+ *
+ * Adopters declare the overlay by interface merging or by generating an
+ * interface keyed on those `$type` strings. Types not in the overlay resolve to
+ * `TransferElement` — the framework default behaves correctly without an
+ * overlay (no autocomplete, but no compile error either).
+ *
+ * The lookup is compile-time only; no runtime cost.
+ */
+export type TransferTypeFor<TAst extends {
+    readonly $type: string;
+}, TTransferMap> = TAst['$type'] extends keyof TTransferMap ? TTransferMap[TAst['$type']] extends TransferElement ? TTransferMap[TAst['$type']] : TransferElement : TransferElement;
+//# sourceMappingURL=transfer-element.d.ts.map

package/lib/transfer-element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-element.d.ts","sourceRoot":"","sources":["../src/transfer-element.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;GAQG;AAEH,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,YAAY,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,MAAM,YAAY,GACxH,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,SAAS,eAAe,GAChD,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,GAC3B,eAAe,GAClB,eAAe,CAAC"}

package/lib/transfer-element.js

@@ -0,0 +1,11 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2023-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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=transfer-element.js.map

package/lib/transfer-element.js.map

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

package/lib/uri.d.ts

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Branded URI-string types distinguishing the framework's two document-identity
+ * spaces. Both are `string` at runtime — the brand is a phantom field, erased by
+ * the compiler, so there is zero runtime cost and the values pass freely to any
+ * `string` sink (`UriUtils`, RPC payloads, logs). At compile time they are
+ * **nominally distinct and mutually non-assignable**, so one cannot be used
+ * where the other is expected.
+ *
+ * - {@link CanonicalUri} — *server-identity* space: the single canonical key a
+ *   document is stored under (`LangiumDocuments` keying, AST-document event
+ *   filters, request-path lookups). Minted ONLY by
+ *   `DocumentUriPolicy.canonicalUri` — the single point that defines what
+ *   "canonical" means, so every `CanonicalUri` has provable provenance.
+ * - {@link LanguageClientUri} — the URI the LSP *textual* language client
+ *   (Monaco / VS Code) actually opened a document under, which may differ from
+ *   its canonical identity (e.g. a symlinked path while the document is keyed by
+ *   its real path). This is the URI `applyEditToLanguageClient` and diagnostics must
+ *   address. Named for the *language client* specifically — the GLSP and
+ *   data-server heads are also clients, but they are addressed canonically.
+ *
+ * Why both are real brands rather than aliases: a plain `type X = string` is
+ * assignable to and from any `string` (and a `CanonicalUri` *is* a `string`), so
+ * an alias would let a canonical URI flow into a language-client sink unchecked —
+ * exactly the class of bug where an outbound sync addressed the client by the
+ * canonical URI it never opened. The distinct `__uriSpace` discriminants make
+ * that a compile error, and make plain `string` assignable to neither — forcing
+ * values through a mint point.
+ *
+ * Scope: these are an **internal** server-identity discipline. RPC/wire fields
+ * and public service parameters stay plain `string` so the brands never leak to
+ * adopters or across the wire; conversion happens at the framework boundary.
+ */
+export type CanonicalUri = string & {
+    readonly __uriSpace: 'canonical';
+};
+/** The LSP textual language client's document URI. See {@link CanonicalUri} for the full rationale. */
+export type LanguageClientUri = string & {
+    readonly __uriSpace: 'languageClient';
+};
+/**
+ * Mint a {@link CanonicalUri}. The single sanctioned place the brand assertion
+ * lives — call this from the one component that defines canonicalisation
+ * (`DocumentUriPolicy.canonicalUri`) instead of scattering `as CanonicalUri`
+ * casts, so a call site reads as a deliberate identity mint rather than an
+ * escape hatch.
+ */
+export declare const asCanonicalUri: (value: string) => CanonicalUri;
+/**
+ * Mint a {@link LanguageClientUri}. The single sanctioned place the brand
+ * assertion lives — call this from the component that owns the language-client
+ * URI space (the text store's `toLanguageClientUri`). See {@link asCanonicalUri}.
+ */
+export declare const asLanguageClientUri: (value: string) => LanguageClientUri;
+//# sourceMappingURL=uri.d.ts.map

package/lib/uri.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri.d.ts","sourceRoot":"","sources":["../src/uri.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAA;CAAE,CAAC;AAEzE,uGAAuG;AACvG,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAEnF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,YAAqC,CAAC;AAErF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,KAAG,iBAA+C,CAAC"}

package/lib/uri.js

@@ -0,0 +1,28 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asLanguageClientUri = exports.asCanonicalUri = void 0;
+/**
+ * Mint a {@link CanonicalUri}. The single sanctioned place the brand assertion
+ * lives — call this from the one component that defines canonicalisation
+ * (`DocumentUriPolicy.canonicalUri`) instead of scattering `as CanonicalUri`
+ * casts, so a call site reads as a deliberate identity mint rather than an
+ * escape hatch.
+ */
+const asCanonicalUri = (value) => value;
+exports.asCanonicalUri = asCanonicalUri;
+/**
+ * Mint a {@link LanguageClientUri}. The single sanctioned place the brand
+ * assertion lives — call this from the component that owns the language-client
+ * URI space (the text store's `toLanguageClientUri`). See {@link asCanonicalUri}.
+ */
+const asLanguageClientUri = (value) => value;
+exports.asLanguageClientUri = asLanguageClientUri;
+//# sourceMappingURL=uri.js.map

package/lib/uri.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri.js","sourceRoot":"","sources":["../src/uri.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAuClF;;;;;;GAMG;AACI,MAAM,cAAc,GAAG,CAAC,KAAa,EAAgB,EAAE,CAAC,KAAqB,CAAC;AAAxE,QAAA,cAAc,kBAA0D;AAErF;;;;GAIG;AACI,MAAM,mBAAmB,GAAG,CAAC,KAAa,EAAqB,EAAE,CAAC,KAA0B,CAAC;AAAvF,QAAA,mBAAmB,uBAAoE"}

package/lib/util.d.ts

@@ -0,0 +1,147 @@
+/********************************************************************************
+ * Copyright (c) 2023 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
+ ********************************************************************************/
+/** A user-defined type predicate. */
+export type TypeGuard<T> = (item: unknown) => item is T;
+/**
+ * Minimal disposable shape, intentionally identical to `vscode-jsonrpc.Disposable`
+ * by structural typing so it interoperates without an actual dependency on that
+ * library. Consumers may pass instances of this type wherever a `Disposable`
+ * is expected, and vice versa.
+ *
+ * Re-defined locally rather than re-exported from `vscode-jsonrpc` so adopters
+ * pulling this interface in do not transitively see `vscode-jsonrpc` types as
+ * part of the framework's public surface.
+ */
+export interface Disposable {
+    dispose(): void;
+}
+export declare namespace Disposable {
+    function create(dispose: () => void): Disposable;
+    /**
+     * Shared no-op {@link Disposable} — `dispose()` does nothing. Use wherever a
+     * disposable is required but there is nothing to release (a subscription with
+     * no teardown, a listener registration in a test double) instead of a fresh
+     * `{ dispose: () => undefined }` literal. Frozen so the shared instance can't
+     * be mutated.
+     */
+    const EMPTY: Disposable;
+}
+/**
+ * A collection of disposables that itself implements {@link Disposable}.
+ *
+ * - {@link dispose} is idempotent: repeat calls are safe.
+ * - {@link push} returns the added disposable for chaining.
+ * - Push-after-disposal disposes the added item immediately (prevents leaks
+ *   from late arrivals on a collection that has already been torn down).
+ * - LIFO drain order: last-pushed disposes first. Matches the convention that
+ *   later disposables typically depend on earlier ones (e.g., a subscription
+ *   depends on a connection, so the subscription must dispose first before
+ *   the connection tears down its transport).
+ * - A throwing dispose does not strand subsequent disposables in the drain.
+ *
+ * Fills the gap left by vscode-jsonrpc and Langium, which provide only the
+ * `Disposable` interface and a `Disposable.create()` factory.
+ */
+export declare class DisposableCollection implements Disposable {
+    protected readonly disposables: Disposable[];
+    protected _disposed: boolean;
+    get disposed(): boolean;
+    push(disposable: Disposable): Disposable;
+    dispose(): void;
+}
+/**
+ * A `Promise` paired with its `resolve` / `reject` callbacks, so producer
+ * and consumer code can be in different scopes. Use when a constructor
+ * needs to expose a `ready` promise that a later method resolves.
+ *
+ * Equivalent to Theia / GLSP / Langium's `Deferred` utility — re-implemented
+ * here so `@hydranium/protocol` stays runtime-dependency-free.
+ */
+export declare class Deferred<T = void> {
+    readonly promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+    constructor();
+}
+/**
+ * A value that is either `T` directly (sync) or a thenable that resolves to `T`
+ * (async). Used in framework hook signatures where adopter overrides may be
+ * either sync or async without forcing the synchronous fast path to pay an
+ * unconditional microtask tick.
+ *
+ * Uses the permissive `PromiseLike<T>` form so externally-produced thenables
+ * (non-native Promise implementations) also flow through.
+ *
+ * Pair with {@link isPromiseLike} at hot-loop call sites to preserve
+ * the sync fast path (an `await` on a non-promise still schedules a microtask).
+ */
+export type MaybePromise<T> = T | PromiseLike<T>;
+/**
+ * Type guard distinguishing the async branch of {@link MaybePromise}.
+ *
+ * At framework call sites in tight loops, guarding before the `await` keeps
+ * sync implementations on the synchronous fast path — `await` on
+ * a non-promise still schedules a microtask, which for per-node loops adds
+ * up. Outside of tight loops a naive `await maybe` is equivalent and
+ * shorter; reach for the guard only when the call sits on the build's
+ * critical path.
+ *
+ * Thenable check (`'then' in value`) rather than `instanceof Promise` so
+ * non-native Promise implementations also classify as async.
+ */
+export declare function isPromiseLike<T = unknown>(value: MaybePromise<T>): value is PromiseLike<T>;
+/** Removes `readonly` from all properties of `T`. */
+export type Mutable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+/** Returns the same value typed as a {@link Mutable}. Compile-time only. */
+export declare function asMutable<T>(item: T): Mutable<T>;
+/** Type-guard variant: narrows `item` to `Mutable<T> | undefined` if `guard` accepts it. */
+export declare function toMutable<T>(item: unknown, guard: TypeGuard<T>): item is Mutable<T> | undefined;
+/**
+ * Wrap `text` in `quoteChar`, escaping interior occurrences with `replaceChar`.
+ *
+ * - Empty input becomes a pair of quote characters.
+ * - Pre-existing surrounding quotes are not double-wrapped.
+ * - Interior `quoteChar` runs are mapped to `replaceChar`.
+ */
+export declare function quote(text: string, quoteChar?: string, replaceChar?: string): string;
+/** Strip a single layer of `quoteChar` from the start and end of `text` if present. */
+export declare function unquote(text: string, quoteChar?: string): string;
+/** Capitalise the first character of `input`. */
+export declare function toPascal(input: string): string;
+/**
+ * Format a [codicon](https://github.com/microsoft/vscode-codicons) name as the
+ * CSS class string consumed by VS Code- and Theia-style icon hosts.
+ *
+ * Presentation, not wire contract, and a duplicate of `@eclipse-glsp/client`'s
+ * export of the same name — a file importing both barrels gets an ambiguity, so
+ * client code that already depends on GLSP takes the upstream one. It stays on
+ * this barrel because adopter protocol packages re-export these helpers
+ * wholesale, which makes relocating it a breaking change rather than a move.
+ */
+export declare function codiconCSSString(icon: string): string;
+/** The identity function. Useful as a default mapping callback. */
+export declare function identity<T>(value: T): T;
+/** Find a name based on `suggestion` that is not already in `existing`, appending an
+ *  incrementing numeric suffix until a free slot is found. */
+export declare function findNextUnique(suggestion: string, existing: string[]): string;
+export declare function findNextUnique<T>(suggestion: string, existing: T[], nameGetter: (element: T) => string): string;
+/** Throw if reached. Helper for exhaustiveness checks at the end of a discriminated-union switch. */
+export declare function unreachable(input: never): never;
+/**
+ * Resolve a nested value from a plain object using a path of property names.
+ * Returns `undefined` for any segment that is not an object or is null.
+ *
+ * The generic `T` is a caller-provided assertion about the value's type — it
+ * is not validated at runtime. Use `unknown` (the default) if the type is
+ * uncertain, then narrow with a type-guard.
+ */
+export declare function getAt<T = unknown>(obj: unknown, path: string[]): T | undefined;
+//# sourceMappingURL=util.d.ts.map

package/lib/util.d.ts.map

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

package/lib/util.js

@@ -0,0 +1,211 @@
+"use strict";
+/********************************************************************************
+ * Copyright (c) 2023 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Deferred = exports.DisposableCollection = exports.Disposable = void 0;
+exports.isPromiseLike = isPromiseLike;
+exports.asMutable = asMutable;
+exports.toMutable = toMutable;
+exports.quote = quote;
+exports.unquote = unquote;
+exports.toPascal = toPascal;
+exports.codiconCSSString = codiconCSSString;
+exports.identity = identity;
+exports.findNextUnique = findNextUnique;
+exports.unreachable = unreachable;
+exports.getAt = getAt;
+var Disposable;
+(function (Disposable) {
+    function create(dispose) {
+        return { dispose };
+    }
+    Disposable.create = create;
+    /**
+     * Shared no-op {@link Disposable} — `dispose()` does nothing. Use wherever a
+     * disposable is required but there is nothing to release (a subscription with
+     * no teardown, a listener registration in a test double) instead of a fresh
+     * `{ dispose: () => undefined }` literal. Frozen so the shared instance can't
+     * be mutated.
+     */
+    Disposable.EMPTY = Object.freeze({ dispose: () => undefined });
+})(Disposable || (exports.Disposable = Disposable = {}));
+/**
+ * A collection of disposables that itself implements {@link Disposable}.
+ *
+ * - {@link dispose} is idempotent: repeat calls are safe.
+ * - {@link push} returns the added disposable for chaining.
+ * - Push-after-disposal disposes the added item immediately (prevents leaks
+ *   from late arrivals on a collection that has already been torn down).
+ * - LIFO drain order: last-pushed disposes first. Matches the convention that
+ *   later disposables typically depend on earlier ones (e.g., a subscription
+ *   depends on a connection, so the subscription must dispose first before
+ *   the connection tears down its transport).
+ * - A throwing dispose does not strand subsequent disposables in the drain.
+ *
+ * Fills the gap left by vscode-jsonrpc and Langium, which provide only the
+ * `Disposable` interface and a `Disposable.create()` factory.
+ */
+class DisposableCollection {
+    disposables = [];
+    _disposed = false;
+    get disposed() {
+        return this._disposed;
+    }
+    push(disposable) {
+        if (this._disposed) {
+            disposable.dispose();
+        }
+        else {
+            this.disposables.push(disposable);
+        }
+        return disposable;
+    }
+    dispose() {
+        if (this._disposed) {
+            return;
+        }
+        this._disposed = true;
+        while (this.disposables.length > 0) {
+            try {
+                this.disposables.pop().dispose();
+            }
+            catch (_err) {
+                // Continue draining — one failed dispose shouldn't strand the rest.
+            }
+        }
+    }
+}
+exports.DisposableCollection = DisposableCollection;
+/**
+ * A `Promise` paired with its `resolve` / `reject` callbacks, so producer
+ * and consumer code can be in different scopes. Use when a constructor
+ * needs to expose a `ready` promise that a later method resolves.
+ *
+ * Equivalent to Theia / GLSP / Langium's `Deferred` utility — re-implemented
+ * here so `@hydranium/protocol` stays runtime-dependency-free.
+ */
+class Deferred {
+    promise;
+    resolve;
+    reject;
+    constructor() {
+        this.promise = new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+    }
+}
+exports.Deferred = Deferred;
+/**
+ * Type guard distinguishing the async branch of {@link MaybePromise}.
+ *
+ * At framework call sites in tight loops, guarding before the `await` keeps
+ * sync implementations on the synchronous fast path — `await` on
+ * a non-promise still schedules a microtask, which for per-node loops adds
+ * up. Outside of tight loops a naive `await maybe` is equivalent and
+ * shorter; reach for the guard only when the call sits on the build's
+ * critical path.
+ *
+ * Thenable check (`'then' in value`) rather than `instanceof Promise` so
+ * non-native Promise implementations also classify as async.
+ */
+function isPromiseLike(value) {
+    return !!value && typeof value.then === 'function';
+}
+/** Returns the same value typed as a {@link Mutable}. Compile-time only. */
+function asMutable(item) {
+    return item;
+}
+function toMutable(item, guard) {
+    return guard ? guard(item) : true;
+}
+/**
+ * Wrap `text` in `quoteChar`, escaping interior occurrences with `replaceChar`.
+ *
+ * - Empty input becomes a pair of quote characters.
+ * - Pre-existing surrounding quotes are not double-wrapped.
+ * - Interior `quoteChar` runs are mapped to `replaceChar`.
+ */
+function quote(text, quoteChar = '"', replaceChar = "'") {
+    if (text.length === 0) {
+        return quoteChar + quoteChar;
+    }
+    let quoted = text;
+    if (!quoted.startsWith(quoteChar)) {
+        quoted = quoteChar + quoted;
+    }
+    if (!quoted.endsWith(quoteChar)) {
+        quoted += quoteChar;
+    }
+    return (quoteChar +
+        quoted
+            .substring(1, quoted.length - 1)
+            .split(quoteChar)
+            .join(replaceChar) +
+        quoteChar);
+}
+/** Strip a single layer of `quoteChar` from the start and end of `text` if present. */
+function unquote(text, quoteChar = '"') {
+    const start = text.startsWith(quoteChar) ? 1 : undefined;
+    const end = text.endsWith(quoteChar) ? -1 : undefined;
+    return text.slice(start, end);
+}
+/** Capitalise the first character of `input`. */
+function toPascal(input) {
+    return input.charAt(0).toLocaleUpperCase() + input.slice(1);
+}
+/**
+ * Format a [codicon](https://github.com/microsoft/vscode-codicons) name as the
+ * CSS class string consumed by VS Code- and Theia-style icon hosts.
+ *
+ * Presentation, not wire contract, and a duplicate of `@eclipse-glsp/client`'s
+ * export of the same name — a file importing both barrels gets an ambiguity, so
+ * client code that already depends on GLSP takes the upstream one. It stays on
+ * this barrel because adopter protocol packages re-export these helpers
+ * wholesale, which makes relocating it a breaking change rather than a move.
+ */
+function codiconCSSString(icon) {
+    return `codicon codicon-${icon}`;
+}
+/** The identity function. Useful as a default mapping callback. */
+function identity(value) {
+    return value;
+}
+function findNextUnique(suggestion, existing, nameGetter) {
+    const names = nameGetter ? existing.map(nameGetter) : existing;
+    let name = suggestion;
+    let index = 1;
+    while (names.includes(name)) {
+        name = suggestion + index++;
+    }
+    return name;
+}
+/** Throw if reached. Helper for exhaustiveness checks at the end of a discriminated-union switch. */
+function unreachable(input) {
+    throw new Error('Value detected in unreachable assertion: ' + `${input}`);
+}
+/**
+ * Resolve a nested value from a plain object using a path of property names.
+ * Returns `undefined` for any segment that is not an object or is null.
+ *
+ * The generic `T` is a caller-provided assertion about the value's type — it
+ * is not validated at runtime. Use `unknown` (the default) if the type is
+ * uncertain, then narrow with a type-guard.
+ */
+function getAt(obj, path) {
+    let cur = obj;
+    for (const seg of path) {
+        if (cur == null || typeof cur !== 'object') {
+            return undefined;
+        }
+        cur = cur[seg];
+    }
+    return cur;
+}
+//# sourceMappingURL=util.js.map

package/lib/util.js.map

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