@hydranium/core 1.0.0-next.10

package/lib/langium/serialization/yaml-serializer.d.ts

@@ -0,0 +1,166 @@
+/********************************************************************************
+ * 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 { type MaybePromise, type TransferElement } from '@hydranium/protocol';
+import { type AstNode } from '@hydranium/langium';
+import { type HydraniumLanguageServices } from '../language-module.js';
+import { AbstractSerializer, type AbstractSerializerOptions } from './abstract-serializer.js';
+/**
+ * Options for {@link YamlSerializer}. Extends the format-agnostic
+ * {@link AbstractSerializerOptions} with YAML-specific style settings.
+ */
+export interface YamlSerializerOptions extends AbstractSerializerOptions {
+    /**
+     * Property paths (`"<TypeName>.<propertyName>"`) whose values should be
+     * serialized without quotes. Required for grammar terminals that accept
+     * unquoted enum-like values (e.g. cardinality keywords, type literals).
+     * Defaults to an empty set — grammars without unquoted terminals omit this.
+     */
+    readonly unquotedProperties?: ReadonlySet<string>;
+    /**
+     * Properties whose **multi-line** string values serialize as a YAML literal
+     * block scalar (`key: |` followed by the indented lines) instead of a single
+     * quoted scalar. An entry is matched either as a qualified path
+     * (`"<TypeName>.<propertyName>"`, for a property on one specific type) or as
+     * a bare property name (`"<propertyName>"`, matching that property on any
+     * node — use for a property declared on a shared interface, e.g. a
+     * `description` carried by every named element). Single-line values for the
+     * same properties serialize normally (quoted). Required for free-text
+     * properties that legitimately span multiple lines (e.g. multi-line
+     * expressions) and must round-trip through a block-scalar terminal.
+     * Defaults to an empty set — grammars without such properties omit this.
+     */
+    readonly blockScalarProperties?: ReadonlySet<string>;
+    /**
+     * AST type names that should serialize on the same line as their parent
+     * key (rather than as an indented YAML block). Use for thin wrapper types
+     * whose own block structure adds noise. Defaults to an empty set —
+     * grammars without inline-block types omit this.
+     */
+    readonly inlineSerializedTypes?: ReadonlySet<string>;
+    /**
+     * Newline character used between serialized lines. Defaults to `'\n'`.
+     * Adopters emitting Windows line endings pass `'\r\n'`.
+     */
+    readonly newlineChar?: string;
+    /**
+     * Indentation character. Defaults to `' '` (space). Adopters with a
+     * tab-indent house style pass `'\t'`.
+     */
+    readonly indentationChar?: string;
+    /**
+     * Number of {@link indentationChar} characters per indentation level.
+     * Defaults to `2` (YAML community convention). Set to `4` for 4-space
+     * indent.
+     */
+    readonly indentationAmount?: number;
+    /**
+     * Lookup table mapping `"<propertyName>.<valueType>"` → substitute YAML
+     * keyword. Used when a grammar declares multiple keyword alternatives
+     * for the same property (e.g. `element=FooElement |
+     * element=BarElement`) and the emitted keyword needs
+     * to switch based on the actual `$type` of the value. Defaults to an
+     * empty map — grammars without alternative-keyword properties omit
+     * this.
+     */
+    readonly typeSpecificKeywords?: ReadonlyMap<string, string>;
+}
+/**
+ * Hand-written grammar-aware AST → YAML serializer.
+ *
+ * Implements the YAML-specific layout on top of {@link AbstractSerializer}: nodes
+ * become `key: value` lines (2-space block indentation by default), nested
+ * nodes go on a new line unless declared in `inlineSerializedTypes`, and
+ * arrays render as `- item` block-style lists.
+ *
+ * The shared dispatch algorithm (reference detection, default-value skipping,
+ * reference-wrapper collapsing, custom-value hook) lives in
+ * {@link AbstractSerializer}. Consult that class for the format-agnostic extension
+ * points. YAML's one addition is unquoted-terminal emission, handled by its
+ * {@link serializeCustomValue} override driven by
+ * {@link YamlSerializerOptions.unquotedProperties}.
+ */
+export declare class YamlSerializer<TAst extends AstNode = AstNode, TTransfer extends TransferElement = TransferElement> extends AbstractSerializer<TAst, TTransfer> {
+    /** Default {@link YamlSerializerOptions.newlineChar}. */
+    static readonly DEFAULT_NEWLINE_CHAR = "\n";
+    /** Default {@link YamlSerializerOptions.indentationChar}. */
+    static readonly DEFAULT_INDENTATION_CHAR = " ";
+    /** Default {@link YamlSerializerOptions.indentationAmount}. */
+    static readonly DEFAULT_INDENTATION_AMOUNT = 2;
+    /** Default {@link YamlSerializerOptions.typeSpecificKeywords}: empty map (no dispatch). */
+    static readonly DEFAULT_TYPE_SPECIFIC_KEYWORDS: ReadonlyMap<string, string>;
+    /** Narrows the inherited {@link AbstractSerializer.options} field to the YAML-specific shape. */
+    protected readonly options: YamlSerializerOptions;
+    protected readonly newlineChar: string;
+    protected readonly indentationChar: string;
+    protected readonly indentationAmount: number;
+    protected readonly typeSpecificKeywords: ReadonlyMap<string, string>;
+    constructor(services: HydraniumLanguageServices, options?: YamlSerializerOptions);
+    /**
+     * Serialize an AST or transfer-model node as a YAML block. Properties are
+     * emitted in grammar-declared order ({@link getOrderedPropertyNames}); each
+     * property is rendered as `key: value` either inline (scalars / inline
+     * types) or with the value on the next line (nested blocks, arrays).
+     *
+     * @param isArrayElement when `true`, the first property is not indented
+     *        (the array `- ` prefix handles alignment).
+     */
+    protected serializeNode(node: AstNode | Record<string, unknown>, indentationLevel: number, isArrayElement?: boolean): MaybePromise<string>;
+    /**
+     * Iterate `propNames` from `startIndex`, serialise each property, and
+     * accumulate the resulting YAML lines. Stays on the sync fast path while
+     * every {@link serializePropertyValue} returns a string; the moment one
+     * returns a Promise, switches to a `.then`-chained tail that resumes
+     * iteration after the async value resolves. Keeps the all-sync case
+     * Promise-free even though the method's declared return type is the union.
+     */
+    protected collectNodeLines(node: AstNode | Record<string, unknown>, nodeType: string, propNames: readonly string[], indentationLevel: number, state: {
+        isFirst: boolean;
+    }, lines: string[], startIndex: number): MaybePromise<string>;
+    /**
+     * Returns the YAML keyword for a property. Default reads from
+     * {@link typeSpecificKeywords} (initialised from
+     * {@link YamlSerializerOptions.typeSpecificKeywords} in the constructor):
+     * looks up `${prop}.${valueType}` and falls back to the raw property name
+     * for non-AST values and unmapped types. Adopters whose keyword follows a
+     * rule rather than a fixed table override this method instead of
+     * providing the data map.
+     */
+    protected getPropertyKeyword(prop: string, valueType?: string): string;
+    protected pushNodeLine(serialized: string | undefined, keyword: string, onNewLine: boolean, indentationLevel: number, state: {
+        isFirst: boolean;
+    }, lines: string[]): void;
+    /** Serialize an array of reference values (Langium References or plain strings). */
+    protected serializeReferenceArray(items: unknown[], indentationLevel: number): MaybePromise<string>;
+    /** Same sync-or-async tail pattern as {@link collectArrayLines}, for reference-array elements. */
+    protected collectReferenceArrayLines(items: unknown[], indentationLevel: number, lines: string[], startIndex: number): MaybePromise<string>;
+    /** Serialize an array of non-reference values. */
+    protected serializeArray(items: unknown[], nodeType: string, key: string, indentationLevel: number): MaybePromise<string>;
+    /** Same sync-or-async tail pattern as {@link collectNodeLines}, for array elements. */
+    protected collectArrayLines(items: unknown[], nodeType: string, key: string, indentationLevel: number, lines: string[], startIndex: number): MaybePromise<string>;
+    protected pushArrayLine(serialized: string | undefined, indentationLevel: number, lines: string[]): void;
+    /**
+     * YAML emits grammar-declared unquoted terminals (cardinality keywords,
+     * type literals) as bare strings rather than quoting them. The decision is
+     * `(type, key)`-based, so it rides the {@link AbstractSerializer.serializeCustomValue}
+     * hook; non-matching properties delegate up the chain via `super`.
+     */
+    protected serializeCustomValue(nodeType: string, key: string, value: unknown, indentationLevel: number): MaybePromise<string | undefined>;
+    /** Indent a line at the given level. */
+    protected indent(text: string, level: number): string;
+    /**
+     * Serialize a multi-line string as a YAML literal block scalar. Returns
+     * `|` followed by every line indented one level deeper than `indentationLevel`
+     * (the node level at which the owning `key:` is emitted), so the block content
+     * sits below — and is reparsed relative to — its key. Every line (including
+     * blank ones) is indented so a block-string value converter that strips the
+     * common indentation round-trips interior and trailing blank lines.
+     */
+    protected serializeBlockScalar(value: string, indentationLevel: number): string;
+}
+//# sourceMappingURL=yaml-serializer.d.ts.map

package/lib/langium/serialization/yaml-serializer.d.ts.map

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

package/lib/langium/serialization/yaml-serializer.js

@@ -0,0 +1,228 @@
+/********************************************************************************
+ * 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 { isPromiseLike } from '@hydranium/protocol';
+import { isAstNode } from '@hydranium/langium';
+import { AbstractSerializer } from './abstract-serializer.js';
+/**
+ * Hand-written grammar-aware AST → YAML serializer.
+ *
+ * Implements the YAML-specific layout on top of {@link AbstractSerializer}: nodes
+ * become `key: value` lines (2-space block indentation by default), nested
+ * nodes go on a new line unless declared in `inlineSerializedTypes`, and
+ * arrays render as `- item` block-style lists.
+ *
+ * The shared dispatch algorithm (reference detection, default-value skipping,
+ * reference-wrapper collapsing, custom-value hook) lives in
+ * {@link AbstractSerializer}. Consult that class for the format-agnostic extension
+ * points. YAML's one addition is unquoted-terminal emission, handled by its
+ * {@link serializeCustomValue} override driven by
+ * {@link YamlSerializerOptions.unquotedProperties}.
+ */
+export class YamlSerializer extends AbstractSerializer {
+    /** Default {@link YamlSerializerOptions.newlineChar}. */
+    static DEFAULT_NEWLINE_CHAR = '\n';
+    /** Default {@link YamlSerializerOptions.indentationChar}. */
+    static DEFAULT_INDENTATION_CHAR = ' ';
+    /** Default {@link YamlSerializerOptions.indentationAmount}. */
+    static DEFAULT_INDENTATION_AMOUNT = 2;
+    /** Default {@link YamlSerializerOptions.typeSpecificKeywords}: empty map (no dispatch). */
+    static DEFAULT_TYPE_SPECIFIC_KEYWORDS = new Map();
+    newlineChar;
+    indentationChar;
+    indentationAmount;
+    typeSpecificKeywords;
+    constructor(services, options = {}) {
+        super(services, options);
+        this.newlineChar = options.newlineChar ?? YamlSerializer.DEFAULT_NEWLINE_CHAR;
+        this.indentationChar = options.indentationChar ?? YamlSerializer.DEFAULT_INDENTATION_CHAR;
+        this.indentationAmount = options.indentationAmount ?? YamlSerializer.DEFAULT_INDENTATION_AMOUNT;
+        this.typeSpecificKeywords = options.typeSpecificKeywords ?? YamlSerializer.DEFAULT_TYPE_SPECIFIC_KEYWORDS;
+    }
+    /**
+     * Serialize an AST or transfer-model node as a YAML block. Properties are
+     * emitted in grammar-declared order ({@link getOrderedPropertyNames}); each
+     * property is rendered as `key: value` either inline (scalars / inline
+     * types) or with the value on the next line (nested blocks, arrays).
+     *
+     * @param isArrayElement when `true`, the first property is not indented
+     *        (the array `- ` prefix handles alignment).
+     */
+    serializeNode(node, indentationLevel, isArrayElement = false) {
+        const nodeType = node.$type;
+        const propNames = this.getOrderedPropertyNames(node, nodeType);
+        const state = { isFirst: !isArrayElement };
+        return this.collectNodeLines(node, nodeType, propNames, indentationLevel, state, [], 0);
+    }
+    /**
+     * Iterate `propNames` from `startIndex`, serialise each property, and
+     * accumulate the resulting YAML lines. Stays on the sync fast path while
+     * every {@link serializePropertyValue} returns a string; the moment one
+     * returns a Promise, switches to a `.then`-chained tail that resumes
+     * iteration after the async value resolves. Keeps the all-sync case
+     * Promise-free even though the method's declared return type is the union.
+     */
+    collectNodeLines(node, nodeType, propNames, indentationLevel, state, lines, startIndex) {
+        for (let i = startIndex; i < propNames.length; i++) {
+            const prop = propNames[i];
+            const propValue = node[prop];
+            if (this.shouldSkipProperty(nodeType, prop, propValue)) {
+                continue;
+            }
+            // Arrays and non-inline objects start on a new line after the keyword.
+            const onNewLine = Array.isArray(propValue) || (isAstNode(propValue) && !this.options.inlineSerializedTypes?.has(propValue.$type));
+            // Pick the grammar keyword: when the value is an AST node and the property has
+            // type-specific keyword alternatives (e.g. `element` → `fooElement`),
+            // `getPropertyKeyword` consults the `YamlSerializerOptions.typeSpecificKeywords`
+            // map. Adopters that need procedural logic instead of (or in addition to) the map
+            // override the method.
+            const valueType = isAstNode(propValue) ? propValue.$type : undefined;
+            const keyword = this.getPropertyKeyword(prop, valueType);
+            // Multi-line string for a declared block-scalar property: emit `key: |` plus the
+            // indented content. The block content carries its own absolute indentation (one level
+            // deeper than the key), computed here from the real node level — `serializeCustomValue`
+            // cannot do this because inline values are dispatched at level 0.
+            if (typeof propValue === 'string' &&
+                propValue.includes(this.newlineChar) &&
+                (this.options.blockScalarProperties?.has(`${nodeType}.${prop}`) || this.options.blockScalarProperties?.has(prop))) {
+                const blockScalar = this.serializeBlockScalar(propValue, indentationLevel);
+                this.pushNodeLine(blockScalar, keyword, /* onNewLine */ false, indentationLevel, state, lines);
+                continue;
+            }
+            const maybe = this.serializePropertyValue(nodeType, prop, propValue, onNewLine ? indentationLevel + 1 : 0);
+            if (isPromiseLike(maybe)) {
+                const resumeAt = i + 1;
+                return maybe.then(serialized => {
+                    this.pushNodeLine(serialized, keyword, onNewLine, indentationLevel, state, lines);
+                    return this.collectNodeLines(node, nodeType, propNames, indentationLevel, state, lines, resumeAt);
+                });
+            }
+            this.pushNodeLine(maybe, keyword, onNewLine, indentationLevel, state, lines);
+        }
+        return lines.join(this.newlineChar + this.indent('', indentationLevel));
+    }
+    /**
+     * Returns the YAML keyword for a property. Default reads from
+     * {@link typeSpecificKeywords} (initialised from
+     * {@link YamlSerializerOptions.typeSpecificKeywords} in the constructor):
+     * looks up `${prop}.${valueType}` and falls back to the raw property name
+     * for non-AST values and unmapped types. Adopters whose keyword follows a
+     * rule rather than a fixed table override this method instead of
+     * providing the data map.
+     */
+    getPropertyKeyword(prop, valueType) {
+        if (valueType === undefined) {
+            return prop;
+        }
+        return this.typeSpecificKeywords.get(`${prop}.${valueType}`) ?? prop;
+    }
+    pushNodeLine(serialized, keyword, onNewLine, indentationLevel, state, lines) {
+        if (!serialized) {
+            return;
+        }
+        const separator = onNewLine ? this.newlineChar : ' ';
+        const line = `${keyword}:${separator}${serialized}`;
+        lines.push(state.isFirst ? this.indent(line, indentationLevel) : line);
+        state.isFirst = false;
+    }
+    /** Serialize an array of reference values (Langium References or plain strings). */
+    serializeReferenceArray(items, indentationLevel) {
+        return this.collectReferenceArrayLines(items, indentationLevel, [], 0);
+    }
+    /** Same sync-or-async tail pattern as {@link collectArrayLines}, for reference-array elements. */
+    collectReferenceArrayLines(items, indentationLevel, lines, startIndex) {
+        for (let i = startIndex; i < items.length; i++) {
+            const item = items[i];
+            if (item === undefined) {
+                continue;
+            }
+            const refText = this.serializeReferenceText(item);
+            let maybe;
+            if (refText !== undefined) {
+                maybe = this.formatReferenceValue(refText);
+            }
+            else if (typeof item === 'string') {
+                maybe = this.formatReferenceValue(item);
+            }
+            if (maybe === undefined) {
+                continue;
+            }
+            if (isPromiseLike(maybe)) {
+                const resumeAt = i + 1;
+                return maybe.then(formatted => {
+                    lines.push(this.indent(`  - ${formatted}`, indentationLevel - 1));
+                    return this.collectReferenceArrayLines(items, indentationLevel, lines, resumeAt);
+                });
+            }
+            lines.push(this.indent(`  - ${maybe}`, indentationLevel - 1));
+        }
+        return lines.join(this.newlineChar);
+    }
+    /** Serialize an array of non-reference values. */
+    serializeArray(items, nodeType, key, indentationLevel) {
+        return this.collectArrayLines(items, nodeType, key, indentationLevel, [], 0);
+    }
+    /** Same sync-or-async tail pattern as {@link collectNodeLines}, for array elements. */
+    collectArrayLines(items, nodeType, key, indentationLevel, lines, startIndex) {
+        for (let i = startIndex; i < items.length; i++) {
+            const item = items[i];
+            if (item === undefined) {
+                continue;
+            }
+            const maybe = this.serializePropertyValue(nodeType, key, item, indentationLevel, /* isArrayElement */ true);
+            if (isPromiseLike(maybe)) {
+                const resumeAt = i + 1;
+                return maybe.then(serialized => {
+                    this.pushArrayLine(serialized, indentationLevel, lines);
+                    return this.collectArrayLines(items, nodeType, key, indentationLevel, lines, resumeAt);
+                });
+            }
+            this.pushArrayLine(maybe, indentationLevel, lines);
+        }
+        return lines.join(this.newlineChar);
+    }
+    pushArrayLine(serialized, indentationLevel, lines) {
+        if (serialized === undefined) {
+            return;
+        }
+        lines.push(this.indent(`  - ${serialized}`, indentationLevel - 1));
+    }
+    /**
+     * YAML emits grammar-declared unquoted terminals (cardinality keywords,
+     * type literals) as bare strings rather than quoting them. The decision is
+     * `(type, key)`-based, so it rides the {@link AbstractSerializer.serializeCustomValue}
+     * hook; non-matching properties delegate up the chain via `super`.
+     */
+    serializeCustomValue(nodeType, key, value, indentationLevel) {
+        if (typeof value === 'string' && this.options.unquotedProperties?.has(`${nodeType}.${key}`)) {
+            return String(value);
+        }
+        return super.serializeCustomValue(nodeType, key, value, indentationLevel);
+    }
+    /** Indent a line at the given level. */
+    indent(text, level) {
+        return `${this.indentationChar.repeat(level * this.indentationAmount)}${text}`;
+    }
+    /**
+     * Serialize a multi-line string as a YAML literal block scalar. Returns
+     * `|` followed by every line indented one level deeper than `indentationLevel`
+     * (the node level at which the owning `key:` is emitted), so the block content
+     * sits below — and is reparsed relative to — its key. Every line (including
+     * blank ones) is indented so a block-string value converter that strips the
+     * common indentation round-trips interior and trailing blank lines.
+     */
+    serializeBlockScalar(value, indentationLevel) {
+        const indent = this.indentationChar.repeat((indentationLevel + 1) * this.indentationAmount);
+        const lines = value
+            .split(this.newlineChar)
+            .map(line => indent + line)
+            .join(this.newlineChar);
+        return `|${this.newlineChar}${lines}`;
+    }
+}
+//# sourceMappingURL=yaml-serializer.js.map

package/lib/langium/serialization/yaml-serializer.js.map

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

package/lib/langium/service-registry.d.ts

@@ -0,0 +1,220 @@
+/********************************************************************************
+ * 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 { type AstNode, DefaultServiceRegistry, type LangiumCoreServices, type LangiumSharedCoreServices, type LanguageMetaData, URI } from '@hydranium/langium';
+import { type LanguageTypeIndex } from './language-types.js';
+/**
+ * Anything that identifies the document whose language is wanted: an AST node
+ * (routed by the document it lives in), a `URI`, or a URI string.
+ *
+ * Named because it is a concept rather than an incidental union — "the thing
+ * whose own language decides this". `undefined` is deliberately NOT a member:
+ * whether a given parameter is optional is a fact about that signature, not
+ * about what can identify a document.
+ */
+export type LanguageTarget = AstNode | URI | string;
+/**
+ * `DefaultServiceRegistry` whose `register` / `getServices` methods are typed
+ * with a consumer-specific extended-services type.
+ *
+ * Langium's stock `ServiceRegistry` returns the base `LangiumCoreServices`,
+ * which forces consumers to cast every time they reach for an extended
+ * service. By parameterising the registry with the consumer's full service
+ * type, the type narrowing happens at the registry boundary instead of every
+ * call site.
+ */
+export declare class HydraniumServiceRegistry<TServices extends LangiumCoreServices = LangiumCoreServices> extends DefaultServiceRegistry {
+    /**
+     * Shared services, held only so `workspace.TextDocuments` can be resolved
+     * per lookup instead of at construction.
+     */
+    protected sharedServices?: LangiumSharedCoreServices;
+    /** Backing field for {@link registrations}. */
+    protected _registrations: number;
+    /**
+     * How many times {@link register} has been called — monotonic, and the
+     * cache key a consumer memoising over the registered set should use.
+     *
+     * `all.length` does not work for that: `register` writes into
+     * `languageIdMap` keyed by language id, so RE-registering an id replaces
+     * the entry and leaves the length unchanged. A consumer keyed on the count
+     * would then keep a cache built from the replaced language's metadata.
+     */
+    get registrations(): number;
+    constructor(services?: LangiumSharedCoreServices);
+    /**
+     * Supply the shared services after construction, for a registry built
+     * without them. Only fills an empty reference — an explicitly constructed
+     * one is never replaced. Called by `bootstrapLangiumLanguages` so the
+     * languageId rung works regardless of how the adopter's `ServiceRegistry`
+     * binding constructed the registry; without it, an adopter rebinding the
+     * slot with a zero-argument `new MyRegistry()` would silently lose that
+     * rung with nothing to indicate it.
+     */
+    acceptSharedServices(services: LangiumSharedCoreServices): void;
+    register(language: TServices): void;
+    /**
+     * Langium's lookup ladder: an open document's declared `languageId`, then
+     * its file name, then its extension, then a throw. Because `super` was
+     * never given the services it reads `textDocuments` from, its own
+     * languageId rung is inert — so this supplies that rung and delegates
+     * every rung below it (and the throw) to `super`, rather than restating
+     * the ladder.
+     *
+     * The declared-id rung is what lets an `untitled:` or extensionless
+     * document route at all, and what gives an OPEN buffer's declared id
+     * precedence over its file extension.
+     *
+     * It does NOT make two languages that share a file extension workable, and
+     * `assertDistinctFileRouting` fails the boot on that configuration: only an
+     * open buffer has a declared id, while indexing, scope computation and
+     * validation route every CLOSED file in the workspace by extension, where
+     * Langium's last-registered-wins would silently hand half the workspace to
+     * the wrong grammar.
+     */
+    getServices(uri: URI): TServices;
+}
+declare const ServicesTypeBrand: unique symbol;
+/**
+ * Phantom-branded subtype of {@link LanguageMetaData} that carries the
+ * extended-services type as a compile-time tag. Construct via
+ * {@link typedMetadata} from a generated `<Grammar>LanguageMetaData` constant,
+ * and pass instances to {@link ExtendedServiceRegistry.getServices} for a
+ * fully-inferred return type (no caller-side cast).
+ *
+ * The brand uses a `unique symbol` member so the type is invariant in
+ * `TServices` — `TypedLanguageMetaData<A>` is NOT assignable to
+ * `TypedLanguageMetaData<B>` even when `A` and `B` are structurally
+ * identical. The brand is optional (`?`) so a bare `LanguageMetaData`
+ * literal stays structurally assignable to the underlying interface; only
+ * the `TypedLanguageMetaData` view of it has phantom-type teeth.
+ */
+export interface TypedLanguageMetaData<TServices extends LangiumCoreServices = LangiumCoreServices> extends LanguageMetaData {
+    readonly [ServicesTypeBrand]?: TServices;
+}
+/**
+ * Annotate a generated {@link LanguageMetaData} constant with the
+ * extended-services type it indexes. Use once per grammar at module
+ * scope; the resulting handle is a stable identity for typed
+ * `getServices(metadata)` lookups.
+ */
+export declare function typedMetadata<TServices extends LangiumCoreServices>(metadata: LanguageMetaData): TypedLanguageMetaData<TServices>;
+/**
+ * Extended {@link HydraniumServiceRegistry}, adding the lookups the inherited
+ * URI-keyed `getServices(uri)` cannot answer:
+ *
+ * - **Typed metadata handle** — `getServices(metadata: TypedLanguageMetaData<T>)`
+ *   returns the registered services typed as `T | undefined`. The primary
+ *   path: callers hold a typed handle per grammar (constructed once via
+ *   {@link typedMetadata}) and resolve services without any caller-side cast.
+ * - **Anything that identifies a document** — {@link getServicesFor} takes an
+ *   AST node, a `URI` or a URI string, and abstains instead of throwing.
+ * - **String id escape hatch** — {@link getServicesById}, for a language id
+ *   derived dynamically (from a wire envelope) where the typed handle isn't
+ *   reachable at the call site.
+ * - **File extension escape hatch** — {@link getServicesByExtension}, for
+ *   file-routing logic that has no URI yet.
+ * - **Producible AST type** — {@link getServicesByType} returns every language
+ *   whose grammar can produce a `$type`, and {@link soleServicesByType}
+ *   narrows that to the unambiguous case. It is the only routing signal a
+ *   request that names no document carries at all.
+ *
+ * Two overload signatures on `getServices` discriminate at compile time
+ * — passing a `URI` keeps the inherited `TServices` return shape; passing a
+ * `TypedLanguageMetaData<T>` returns `T | undefined`.
+ *
+ * Langium's base `ServiceRegistry` type stays unchanged. The framework narrows
+ * its own `ServiceRegistry` slot to this class instead, so the extended lookups
+ * are reachable from the shared-services shapes without a cast.
+ */
+export declare class ExtendedServiceRegistry<TServices extends LangiumCoreServices = LangiumCoreServices> extends HydraniumServiceRegistry<TServices> {
+    getServices<TMetaServices extends LangiumCoreServices>(metadata: TypedLanguageMetaData<TMetaServices>): TMetaServices | undefined;
+    getServices(uri: URI): TServices;
+    /**
+     * Lookup by anything that identifies a document — an AST node (routed by
+     * the document it lives in), a `URI`, or a URI string. `undefined` when the
+     * node has no document, or nothing routes the URI.
+     *
+     * **Abstains rather than throws**, unlike the inherited `getServices(uri)`.
+     * Throwing is right for a build pipeline, which must have a language for
+     * every document it builds, and wrong for a caller asking an optional
+     * question about an arbitrary target: a foreign reference target, a
+     * synthetic node, a directory URI. Same contract as
+     * {@link getServicesById}.
+     *
+     * **The per-target lookup belongs here, not at the call sites.** The thing
+     * to apply to a node is decided by the node's OWN document, and a caller
+     * that captures one provider and reuses it across nodes derives names and
+     * keys under the wrong grammar's `nameProperties` / `nameSeparator` the
+     * moment two languages differ — silently, since the result is a
+     * plausible-looking string. Hand-rolling the three steps (node to root
+     * document, abstain on miss, one ladder walk not two) is what let that
+     * defect recur; being a registry method makes the correct call the
+     * discoverable one, and the generic `TServices` return means no call site
+     * needs a cast.
+     *
+     * One walk of the lookup ladder: Langium implements `hasServices` as a
+     * try/catch around `getServices`, so the obvious `hasServices(uri) &&
+     * getServices(uri)` pair costs two walks on the happy path — and these are
+     * bulk paths, once per indexed node or serialised reference.
+     */
+    getServicesFor(target: LanguageTarget | undefined): TServices | undefined;
+    /**
+     * Lookup by raw `languageId` string. Returns `undefined` when no
+     * services have been registered for the id (vs. the URI overload's
+     * inherited Langium semantics, which throws on miss). Used for
+     * dynamically-routed lookups where the language id comes from
+     * external input.
+     */
+    getServicesById(languageId: string): LangiumCoreServices | undefined;
+    /**
+     * Lookup by file extension. Returns `undefined` when no services match.
+     * Useful for routing decisions that need to dispatch on file extension
+     * before a URI is available.
+     */
+    getServicesByExtension(extension: string): LangiumCoreServices | undefined;
+    /**
+     * Every registered language whose grammar can PRODUCE `type`, in
+     * registration order. Empty when none can; more than one when several do
+     * (types reached through a grammar they both import).
+     *
+     * Returns the list rather than a single answer on purpose: "no language
+     * produces this" and "four do" are different facts, and a caller needs to
+     * tell them apart both to explain itself and to decide whether to fall
+     * through to another signal. The registry answers the fact; the head owns
+     * the policy. {@link soleServicesByType} is the shorthand for the common
+     * policy.
+     *
+     * Attribution is *produced, not mentioned* and *reachable from the entry
+     * rule, not merely present* — see `collectProducibleTypes`.
+     */
+    getServicesByType(type: string): readonly TServices[];
+    /**
+     * The single language that can produce `type`, or `undefined` when none
+     * can or several can. The common policy over {@link getServicesByType}:
+     * an ambiguous type does not identify a language, so abstaining is the
+     * honest answer rather than taking the first.
+     */
+    soleServicesByType(type: string): TServices | undefined;
+    /**
+     * Drop the memoised type index, so a language registered after the first
+     * type lookup is accounted for. The reason this index belongs on the
+     * registry rather than in a consumer's private memo: the registry is the
+     * one place that knows when the registered set changed.
+     */
+    register(language: TServices): void;
+    protected _typeIndex?: LanguageTypeIndex<TServices>;
+    /**
+     * Type → language index over the registered grammars, built on first use.
+     * Lazy because a grammar walk per language is not free and most lookups
+     * never need it; invalidated by {@link register}.
+     */
+    protected get typeIndex(): LanguageTypeIndex<TServices>;
+}
+export {};
+//# sourceMappingURL=service-registry.d.ts.map

package/lib/langium/service-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-registry.d.ts","sourceRoot":"","sources":["../../src/langium/service-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,KAAK,OAAO,EAEZ,sBAAsB,EAEtB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EACrB,GAAG,EACL,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAA0B,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,GAAG,GAAG,MAAM,CAAC;AAEpD;;;;;;;;;GASG;AACH,qBAAa,wBAAwB,CAAC,SAAS,SAAS,mBAAmB,GAAG,mBAAmB,CAAE,SAAQ,sBAAsB;IAC9H;;;OAGG;IACH,SAAS,CAAC,cAAc,CAAC,EAAE,yBAAyB,CAAC;IAErD,+CAA+C;IAC/C,SAAS,CAAC,cAAc,SAAK;IAE7B;;;;;;;;OAQG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;gBAEW,QAAQ,CAAC,EAAE,yBAAyB;IAgBhD;;;;;;;;OAQG;IACH,oBAAoB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI;IAItD,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI;IAK5C;;;;;;;;;;;;;;;;;;OAkBG;IACM,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,SAAS;CAa3C;AAED,OAAO,CAAC,MAAM,iBAAiB,EAAE,OAAO,MAAM,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,qBAAqB,CAAC,SAAS,SAAS,mBAAmB,GAAG,mBAAmB,CAAE,SAAQ,gBAAgB;IACzH,QAAQ,CAAC,CAAC,iBAAiB,CAAC,CAAC,EAAE,SAAS,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,SAAS,mBAAmB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAEjI;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,uBAAuB,CACjC,SAAS,SAAS,mBAAmB,GAAG,mBAAmB,CAC5D,SAAQ,wBAAwB,CAAC,SAAS,CAAC;IAEjC,WAAW,CAAC,aAAa,SAAS,mBAAmB,EAC3D,QAAQ,EAAE,qBAAqB,CAAC,aAAa,CAAC,GAC9C,aAAa,GAAG,SAAS;IAEnB,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,SAAS;IAQzC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS;IAYzE;;;;;;OAMG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAIpE;;;;OAIG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAI1E;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,SAAS,EAAE;IAIrD;;;;;OAKG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAKvD;;;;;OAKG;IACM,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI;IAK5C,SAAS,CAAC,UAAU,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAEpD;;;;OAIG;IACH,SAAS,KAAK,SAAS,IAAI,iBAAiB,CAAC,SAAS,CAAC,CAEtD;CACH"}