@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,316 @@
+/********************************************************************************
+ * 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 Tracer, type TransferElement } from '@hydranium/protocol';
+import { type AstNode, type AstReflection } from '@hydranium/langium';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type HydraniumLanguageServices } from '../language-module.js';
+import { type Serializer } from './serializer.js';
+/**
+ * Format-agnostic options shared by all {@link AbstractSerializer} implementations.
+ *
+ * Each field captures a piece of language-specific knowledge the algorithm
+ * cannot derive from grammar reflection alone. Format-specific subclasses
+ * (YAML, JSON, …) extend this with their own style settings.
+ *
+ * `propertyOrder` is the load-bearing one: Langium's generated AST uses
+ * interface-property order which doesn't match grammar-declaration order due
+ * to inheritance, so consumers ship an explicit per-type order map.
+ *
+ * `reflection` is intentionally NOT on this options shape — the serializer
+ * reads it from `services.shared.AstReflection` so adopters bind one
+ * source of truth at the DI graph rather than passing the reflection
+ * object explicitly. Keeping it off `AbstractSerializerOptions` matches the
+ * wider `(services, options)` constructor convention.
+ */
+export interface AbstractSerializerOptions extends LogNameOptions {
+    /**
+     * Per-AST-type ordered list of property names, matching the grammar's
+     * declaration order. Optional — when no entry exists for a given type,
+     * the walker falls back to {@link Object.keys}(node), which yields the
+     * AST node's own key order (in practice Langium's parser populates
+     * properties in grammar-source order, so the fallback is usually
+     * correct). Adopters who care about deterministic per-type ordering
+     * — e.g. when augmenting the AST with extra fields the grammar didn't
+     * place — supply the map; adopters without that concern omit it.
+     */
+    readonly propertyOrder?: ReadonlyMap<string, readonly string[]>;
+    /**
+     * AST types that exist to wrap a single cross-reference. Maps the
+     * type name to the property holding the reference. The serializer emits
+     * just the reference id, dropping the wrapper noise. Defaults to an empty
+     * map — grammars without single-reference wrapper types omit this.
+     *
+     * A type may stay in this map even when it declares further optional
+     * properties: the collapse only applies while every other property is
+     * empty (see {@link AbstractSerializer.getReferenceWrapperProperty}), so
+     * a wrapper that grows an optional property keeps its collapsed form for
+     * existing documents and switches to a regular property block as soon as
+     * the extra property carries a value.
+     */
+    readonly referenceWrapperTypes?: ReadonlyMap<string, string>;
+    /**
+     * Whether {@link AbstractSerializer.serializeAst} trims trailing whitespace
+     * from the final output (leading whitespace is always trimmed). Defaults to
+     * `true` — the conventional "no trailing blank lines" document shape. Set to
+     * `false` for grammars whose values may legitimately END the document with
+     * blank lines that must survive a round-trip — e.g. a multi-line block-scalar
+     * property (see `YamlSerializerOptions.blockScalarProperties`),
+     * where a trailing-trim would silently eat user-typed blank lines.
+     */
+    readonly trimTrailingWhitespace?: boolean;
+}
+/**
+ * Abstract base for hand-written grammar-aware AST → text serializers.
+ *
+ * Langium ships no serializer ([discussion 683]; [discussion 863]) so
+ * consumers roll their own. This class is the shared algorithm — a
+ * property-by-property walk in grammar-declared order, dispatching each value
+ * through type-aware paths (references, id properties, inline types,
+ * reference-wrapper types, nested AST nodes, arrays, primitives).
+ *
+ * The same algorithm handles two value shapes uniformly:
+ * - **AST mode** — direct Langium AST nodes with `Reference` objects.
+ * - **Transfer-model mode** — structurally equivalent objects where references
+ *   are plain string ids.
+ *
+ * Both shapes round-trip through {@link serializeReferenceText}, so consumers
+ * don't need a separate serializer per mode — and that holds for a subclass
+ * that replaces the generic walk with hand-written per-`$type` emitters, not
+ * only for one that inherits it. Such an emitter calls
+ * {@link serializeReferenceText} directly, so it is the single method that has
+ * to understand both shapes; see its contract for why gating on
+ * {@link isReferenceProperty} inside {@link serializePropertyValue} is what
+ * makes that safe.
+ *
+ * Format-specific subclasses (`YamlSerializer`,
+ * `JsonSerializer`) implement the abstract
+ * methods to lay out the actual output text: how a node's properties are
+ * composed into an object representation, how arrays are bracketed, and how
+ * indentation is rendered.
+ *
+ * **Extension points** (override in a subclass):
+ * - {@link serializeReferenceText} — extract the textual form of a
+ *   cross-reference; defaults to the value's `$refText`.
+ * - {@link formatReferenceValue} — format a cross-reference value for emission;
+ *   defaults to `JSON.stringify`.
+ * - {@link serializeCustomValue} — type-specific serialization for values
+ *   that don't fit the generic paths. Runs after all reference detection, so
+ *   references never reach this hook. Returns `undefined` to fall through to
+ *   the default handling.
+ *
+ * [discussion 683]: https://github.com/langium/langium/discussions/683
+ * [discussion 863]: https://github.com/langium/langium/discussions/863
+ */
+export declare abstract class AbstractSerializer<TAst extends AstNode = AstNode, TTransfer extends TransferElement = TransferElement> implements Serializer<TAst, TTransfer> {
+    protected readonly services: HydraniumLanguageServices;
+    protected readonly options: AbstractSerializerOptions;
+    protected readonly reflection: AstReflection;
+    protected readonly tracer: Tracer;
+    constructor(services: HydraniumLanguageServices, options?: AbstractSerializerOptions);
+    /**
+     * Entry point for AST-shape inputs. Typically the grammar root, but any
+     * AST node works — the walker is recursive and shape-agnostic.
+     *
+     * Preserves the sync fast path: when every subclass override and every
+     * adopter hook is sync, the return is a bare `string` (no Promise
+     * allocation, no microtask). The async branch fires only if at least one
+     * recursive `serializeNode` call resolved to a Promise.
+     */
+    serializeAst(model: TAst): MaybePromise<string>;
+    /**
+     * Trim the final serialized output. Leading whitespace is always removed;
+     * trailing whitespace is removed unless {@link AbstractSerializerOptions.trimTrailingWhitespace}
+     * is `false` (which preserves document-ending blank lines, e.g. inside a block scalar).
+     */
+    protected trimSerialized(text: string | undefined): string;
+    /**
+     * Entry point for transfer-model-shape inputs (cross-references as plain
+     * string ids rather than `Reference` objects).
+     * Typically the transfer root, but any transfer element works.
+     *
+     * Default delegates back to {@link serializeAst} because the property
+     * walker is shape-agnostic — both shapes traverse the same
+     * {@link serializePropertyValue} dispatch and resolve references through
+     * the same {@link serializeReferenceText} read.
+     * Adopters who need shape-specific formatting override this method
+     * independently.
+     *
+     * The `as unknown as TAst` cast is honest: `TAst` and `TTransfer` are
+     * independent narrowings of two different `AstNode`-rooted hierarchies, so
+     * TS rightly refuses a direct narrowing. The walker reads only `$type` and
+     * property values, so the runtime read does not depend on the assignment
+     * being type-correct.
+     */
+    serializeTransfer(model: TTransfer): MaybePromise<string>;
+    /**
+     * Format-specific layout of an AST or transfer-model node's properties.
+     * Subclasses iterate {@link getOrderedPropertyNames}, call
+     * {@link serializePropertyValue} per property, and compose the results
+     * into the format's object representation.
+     *
+     * Returns {@link MaybePromise} so subclasses may transparently await
+     * async adopter hooks; the per-property loop in each subclass gates with
+     * {@link isPromiseLike} so sync hooks skip the microtask per
+     * iteration.
+     *
+     * @param isArrayElement when `true`, the caller is producing an array
+     *        element — formats may use this to suppress leading indentation
+     *        (YAML's `- ` prefix handles alignment).
+     */
+    protected abstract serializeNode(node: AstNode | Record<string, unknown>, indentationLevel: number, isArrayElement?: boolean): MaybePromise<string>;
+    /** Format-specific layout of an array of non-reference values. */
+    protected abstract serializeArray(items: unknown[], nodeType: string, key: string, indentationLevel: number): MaybePromise<string>;
+    /** Format-specific layout of an array of reference values (Langium References or plain strings). */
+    protected abstract serializeReferenceArray(items: unknown[], indentationLevel: number): MaybePromise<string>;
+    /**
+     * Serialize a single property value. Dispatch order (first match wins):
+     *
+     * 1. `$`-prefixed keys are skipped (Langium internals — `$type`, `$container`, …).
+     * 2. Reference-typed property (per grammar reflection): an array via
+     *    {@link serializeReferenceArray}, otherwise a single reference via
+     *    {@link serializeReferenceText} — which resolves an AST-mode Langium
+     *    `Reference` and a transfer-mode plain string id alike.
+     * 3. Reference-wrapper AST node — emitted as the wrapped reference id
+     *    (only while the node's other properties are empty, see
+     *    {@link getReferenceWrapperProperty}).
+     * 4. {@link serializeCustomValue} hook — type-specific consumer overrides.
+     * 5. Nested AST node — recurse into {@link serializeNode}.
+     * 6. Array — element-by-element via {@link serializeArray}.
+     * 7. Anything else — {@link formatPrimitive}.
+     *
+     * Reference detection (steps 2-3) runs before {@link serializeCustomValue}
+     * so that references in either shape always route through
+     * {@link formatReferenceValue}; the custom hook never has to defend against
+     * them.
+     *
+     * **Reflection is consulted before the value is inspected**, and that order
+     * is load-bearing: it is what lets {@link serializeReferenceText} accept a
+     * bare transfer-mode id without a primitive string property such as `name`
+     * being mistaken for a cross-reference. Inspecting the value first would
+     * force the two shapes down two different code paths — and a hand-written
+     * emitter, which has no `(nodeType, key)` pair to offer, could then only
+     * reach the AST-mode one.
+     *
+     * Returns {@link MaybePromise} but does not `await` internally: each
+     * dispatch branch either returns a sync value directly or returns the
+     * recursive call's result verbatim. Callers (the subclass loops) gate
+     * with {@link isPromiseLike} so sync values bypass the
+     * microtask per iteration.
+     *
+     * @param isArrayElement when `true`, nested nodes do not indent their first
+     *        property (the array element prefix handles alignment).
+     */
+    protected serializePropertyValue(nodeType: string, key: string, value: unknown, indentationLevel: number, isArrayElement?: boolean): MaybePromise<string | undefined>;
+    /**
+     * Render a cross-reference to the text the grammar accepts, in **either**
+     * serialization shape:
+     *
+     * - **AST mode** — a Langium `Reference`, or any `{ $refText }` object.
+     *   Langium's `isReference` additionally requires a resolved `ref`, but the
+     *   emitted text is the same `$refText` either way, so the single
+     *   {@link isRefTextObject} check covers both. Reading `$refText` rather
+     *   than the resolved target is deliberate: an unresolvable reference then
+     *   round-trips as the text the user typed instead of being dropped.
+     * - **Transfer mode** — a plain string id, which the framework
+     *   `TransferEncoder` emits for every cross-reference.
+     *
+     * Returns `undefined` only when the value is neither.
+     *
+     * **Call this only on values that ARE cross-references.** A bare string is
+     * indistinguishable from a primitive string value, so this method trusts
+     * its caller. The generic walker earns that trust by gating on
+     * {@link isReferenceProperty} (see {@link serializePropertyValue}); a
+     * hand-written per-`$type` emitter earns it by construction, because the
+     * author calls this on a property they know the grammar declares a
+     * reference. That is what makes ONE method correct for both the walker and
+     * a custom concrete syntax.
+     *
+     * Override to apply an adopter-specific reference-text convention — e.g.
+     * deriving text from the resolved target via the language's `NameProvider`
+     * when `$refText` is empty. The default deliberately does not reach for the
+     * `NameProvider`: a real Langium `Reference` always carries a `$refText`
+     * string, so no fallback can fire on the common path.
+     *
+     * Distinct from `ReferenceBuilder.getReferenceName`, which *mints* the name
+     * for a NEW reference from a source↔target relationship. This one *renders*
+     * a reference that already exists.
+     */
+    protected serializeReferenceText(value: unknown): string | undefined;
+    /**
+     * Whether a property should be skipped because it carries no meaningful
+     * value: `undefined`, `null`, an empty array, a default value per grammar
+     * reflection, or a blank string. Subclasses may override to widen or
+     * narrow the skip policy.
+     */
+    protected shouldSkipProperty(nodeType: string, prop: string, value: unknown): boolean;
+    /**
+     * Resolve the property that collapses a reference-wrapper node
+     * ({@link AbstractSerializerOptions.referenceWrapperTypes}) to its bare
+     * reference id, or `undefined` when the node carries additional non-empty
+     * GRAMMAR-DECLARED properties and must serialize as a regular nested node
+     * instead — an unconditional collapse would silently drop those values.
+     *
+     * The scan reads the declared property names from grammar reflection, NOT
+     * the node's own keys: transfer-model objects may carry synthesized
+     * companion fields (display labels, derived projections) that never
+     * persist, and counting those as "more" would break the collapse for
+     * every wrapper that crosses the wire in an enriched projection.
+     *
+     * Emptiness is judged by {@link shouldSkipProperty} plus one
+     * reference-specific rule: a reference object with a blank `$refText` is
+     * an unset reference and counts as empty. The rule lives here rather than
+     * in {@link shouldSkipProperty} so regular property emission is unchanged.
+     *
+     * Works on both value shapes — Langium AST nodes and transfer-model
+     * objects (plain string reference ids).
+     */
+    protected getReferenceWrapperProperty(node: AstNode): string | undefined;
+    /**
+     * Per-type ordered property names. Resolves the configured
+     * {@link AbstractSerializerOptions.propertyOrder} entry for `type`; falls back
+     * to the node's own JS-key order ({@link Object.keys}) when no entry
+     * exists. The walker filters `$`-prefixed keys downstream in
+     * {@link serializePropertyValue}, so passing every own key here is safe.
+     */
+    protected getOrderedPropertyNames(node: AstNode | Record<string, unknown>, type: string): readonly string[];
+    /**
+     * Format a cross-reference value for emission. Defaults to `JSON.stringify`.
+     * Override to apply language-specific reference quoting — e.g. an
+     * id-reference formatter that mirrors the grammar's id convention.
+     *
+     * Returns {@link MaybePromise} so adopters with async formatting needs
+     * (remote schema lookup, external canonical-id resolution) can return a
+     * `Promise<string>`. Sync overrides remain valid.
+     */
+    protected formatReferenceValue(value: string): MaybePromise<string>;
+    /**
+     * Format a primitive value (string, number, boolean) for emission. Defaults
+     * to `JSON.stringify`, which quotes strings, formats numbers/booleans, and
+     * is valid both as a YAML scalar and a JSON value.
+     *
+     * Returns {@link MaybePromise} so adopters with async formatting needs
+     * (e.g. delegating to `prettier.format` for a specific value class) can
+     * return a `Promise<string>`.
+     */
+    protected formatPrimitive(value: unknown): MaybePromise<string>;
+    /**
+     * Hook for type-specific serialization that doesn't fit the generic
+     * dispatch table. Runs after all reference detection (steps 2-4 of
+     * {@link serializePropertyValue}) and before the nested-AST-node recurse,
+     * so references never reach this hook and the override may key purely on
+     * `(nodeType, key, value)`. Return `undefined` to fall through to the
+     * default handling. Default: returns `undefined` for everything.
+     *
+     * The in-repo override is
+     * `YamlSerializer`'s, which emits
+     * grammar-declared unquoted terminals as bare strings.
+     */
+    protected serializeCustomValue(_nodeType: string, _key: string, _value: unknown, _indentationLevel: number): MaybePromise<string | undefined>;
+}
+//# sourceMappingURL=abstract-serializer.d.ts.map

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

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

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

@@ -0,0 +1,351 @@
+/********************************************************************************
+ * 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 { isDefaultValue, isReferenceProperty } from './serialization-util.js';
+function isRefTextObject(value) {
+    return typeof value === 'object' && value !== null && '$refText' in value && typeof value.$refText === 'string';
+}
+/**
+ * Abstract base for hand-written grammar-aware AST → text serializers.
+ *
+ * Langium ships no serializer ([discussion 683]; [discussion 863]) so
+ * consumers roll their own. This class is the shared algorithm — a
+ * property-by-property walk in grammar-declared order, dispatching each value
+ * through type-aware paths (references, id properties, inline types,
+ * reference-wrapper types, nested AST nodes, arrays, primitives).
+ *
+ * The same algorithm handles two value shapes uniformly:
+ * - **AST mode** — direct Langium AST nodes with `Reference` objects.
+ * - **Transfer-model mode** — structurally equivalent objects where references
+ *   are plain string ids.
+ *
+ * Both shapes round-trip through {@link serializeReferenceText}, so consumers
+ * don't need a separate serializer per mode — and that holds for a subclass
+ * that replaces the generic walk with hand-written per-`$type` emitters, not
+ * only for one that inherits it. Such an emitter calls
+ * {@link serializeReferenceText} directly, so it is the single method that has
+ * to understand both shapes; see its contract for why gating on
+ * {@link isReferenceProperty} inside {@link serializePropertyValue} is what
+ * makes that safe.
+ *
+ * Format-specific subclasses (`YamlSerializer`,
+ * `JsonSerializer`) implement the abstract
+ * methods to lay out the actual output text: how a node's properties are
+ * composed into an object representation, how arrays are bracketed, and how
+ * indentation is rendered.
+ *
+ * **Extension points** (override in a subclass):
+ * - {@link serializeReferenceText} — extract the textual form of a
+ *   cross-reference; defaults to the value's `$refText`.
+ * - {@link formatReferenceValue} — format a cross-reference value for emission;
+ *   defaults to `JSON.stringify`.
+ * - {@link serializeCustomValue} — type-specific serialization for values
+ *   that don't fit the generic paths. Runs after all reference detection, so
+ *   references never reach this hook. Returns `undefined` to fall through to
+ *   the default handling.
+ *
+ * [discussion 683]: https://github.com/langium/langium/discussions/683
+ * [discussion 863]: https://github.com/langium/langium/discussions/863
+ */
+export class AbstractSerializer {
+    services;
+    options;
+    reflection;
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.options = options;
+        this.reflection = services.shared.AstReflection;
+        this.tracer = services.shared.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+    }
+    /**
+     * Entry point for AST-shape inputs. Typically the grammar root, but any
+     * AST node works — the walker is recursive and shape-agnostic.
+     *
+     * Preserves the sync fast path: when every subclass override and every
+     * adopter hook is sync, the return is a bare `string` (no Promise
+     * allocation, no microtask). The async branch fires only if at least one
+     * recursive `serializeNode` call resolved to a Promise.
+     */
+    serializeAst(model) {
+        const result = this.serializeNode(model, 0);
+        if (isPromiseLike(result)) {
+            return result.then(text => this.trimSerialized(text));
+        }
+        return this.trimSerialized(result);
+    }
+    /**
+     * Trim the final serialized output. Leading whitespace is always removed;
+     * trailing whitespace is removed unless {@link AbstractSerializerOptions.trimTrailingWhitespace}
+     * is `false` (which preserves document-ending blank lines, e.g. inside a block scalar).
+     */
+    trimSerialized(text) {
+        if (text === undefined) {
+            return '';
+        }
+        return this.options.trimTrailingWhitespace === false ? text.trimStart() : text.trim();
+    }
+    /**
+     * Entry point for transfer-model-shape inputs (cross-references as plain
+     * string ids rather than `Reference` objects).
+     * Typically the transfer root, but any transfer element works.
+     *
+     * Default delegates back to {@link serializeAst} because the property
+     * walker is shape-agnostic — both shapes traverse the same
+     * {@link serializePropertyValue} dispatch and resolve references through
+     * the same {@link serializeReferenceText} read.
+     * Adopters who need shape-specific formatting override this method
+     * independently.
+     *
+     * The `as unknown as TAst` cast is honest: `TAst` and `TTransfer` are
+     * independent narrowings of two different `AstNode`-rooted hierarchies, so
+     * TS rightly refuses a direct narrowing. The walker reads only `$type` and
+     * property values, so the runtime read does not depend on the assignment
+     * being type-correct.
+     */
+    serializeTransfer(model) {
+        return this.serializeAst(model);
+    }
+    /**
+     * Serialize a single property value. Dispatch order (first match wins):
+     *
+     * 1. `$`-prefixed keys are skipped (Langium internals — `$type`, `$container`, …).
+     * 2. Reference-typed property (per grammar reflection): an array via
+     *    {@link serializeReferenceArray}, otherwise a single reference via
+     *    {@link serializeReferenceText} — which resolves an AST-mode Langium
+     *    `Reference` and a transfer-mode plain string id alike.
+     * 3. Reference-wrapper AST node — emitted as the wrapped reference id
+     *    (only while the node's other properties are empty, see
+     *    {@link getReferenceWrapperProperty}).
+     * 4. {@link serializeCustomValue} hook — type-specific consumer overrides.
+     * 5. Nested AST node — recurse into {@link serializeNode}.
+     * 6. Array — element-by-element via {@link serializeArray}.
+     * 7. Anything else — {@link formatPrimitive}.
+     *
+     * Reference detection (steps 2-3) runs before {@link serializeCustomValue}
+     * so that references in either shape always route through
+     * {@link formatReferenceValue}; the custom hook never has to defend against
+     * them.
+     *
+     * **Reflection is consulted before the value is inspected**, and that order
+     * is load-bearing: it is what lets {@link serializeReferenceText} accept a
+     * bare transfer-mode id without a primitive string property such as `name`
+     * being mistaken for a cross-reference. Inspecting the value first would
+     * force the two shapes down two different code paths — and a hand-written
+     * emitter, which has no `(nodeType, key)` pair to offer, could then only
+     * reach the AST-mode one.
+     *
+     * Returns {@link MaybePromise} but does not `await` internally: each
+     * dispatch branch either returns a sync value directly or returns the
+     * recursive call's result verbatim. Callers (the subclass loops) gate
+     * with {@link isPromiseLike} so sync values bypass the
+     * microtask per iteration.
+     *
+     * @param isArrayElement when `true`, nested nodes do not indent their first
+     *        property (the array element prefix handles alignment).
+     */
+    serializePropertyValue(nodeType, key, value, indentationLevel, isArrayElement = false) {
+        if (key.startsWith('$')) {
+            return undefined;
+        }
+        // Reference-typed properties (per grammar reflection), in EITHER shape: an
+        // array of references, or a single reference resolved by
+        // `serializeReferenceText`. Gating on reflection first is what lets that
+        // method accept a bare transfer-mode id — it only ever sees values the
+        // grammar declares a cross-reference, so a plain string property such as
+        // `name` can never be mistaken for one.
+        if (isReferenceProperty(this.reflection, nodeType, key)) {
+            if (Array.isArray(value)) {
+                return this.serializeReferenceArray(value, indentationLevel);
+            }
+            const reference = this.serializeReferenceText(value);
+            if (reference !== undefined) {
+                return this.formatReferenceValue(reference);
+            }
+        }
+        // Reference wrapper types: a node that exists to wrap a reference, collapsed to the
+        // bare reference id while its other properties are empty.
+        if (isAstNode(value)) {
+            const refProperty = this.getReferenceWrapperProperty(value);
+            if (refProperty) {
+                const propertyReference = this.serializeReferenceText(value[refProperty]);
+                if (propertyReference !== undefined) {
+                    return this.formatReferenceValue(propertyReference);
+                }
+            }
+        }
+        // Custom hook: type-specific consumer overrides (runs after reference detection).
+        const custom = this.serializeCustomValue(nodeType, key, value, indentationLevel);
+        if (custom !== undefined) {
+            return custom;
+        }
+        // Nested AST node: recurse.
+        if (isAstNode(value)) {
+            return this.serializeNode(value, indentationLevel, isArrayElement);
+        }
+        // Arrays of non-reference values.
+        if (Array.isArray(value)) {
+            return this.serializeArray(value, nodeType, key, indentationLevel);
+        }
+        // Primitive values.
+        return this.formatPrimitive(value);
+    }
+    /**
+     * Render a cross-reference to the text the grammar accepts, in **either**
+     * serialization shape:
+     *
+     * - **AST mode** — a Langium `Reference`, or any `{ $refText }` object.
+     *   Langium's `isReference` additionally requires a resolved `ref`, but the
+     *   emitted text is the same `$refText` either way, so the single
+     *   {@link isRefTextObject} check covers both. Reading `$refText` rather
+     *   than the resolved target is deliberate: an unresolvable reference then
+     *   round-trips as the text the user typed instead of being dropped.
+     * - **Transfer mode** — a plain string id, which the framework
+     *   `TransferEncoder` emits for every cross-reference.
+     *
+     * Returns `undefined` only when the value is neither.
+     *
+     * **Call this only on values that ARE cross-references.** A bare string is
+     * indistinguishable from a primitive string value, so this method trusts
+     * its caller. The generic walker earns that trust by gating on
+     * {@link isReferenceProperty} (see {@link serializePropertyValue}); a
+     * hand-written per-`$type` emitter earns it by construction, because the
+     * author calls this on a property they know the grammar declares a
+     * reference. That is what makes ONE method correct for both the walker and
+     * a custom concrete syntax.
+     *
+     * Override to apply an adopter-specific reference-text convention — e.g.
+     * deriving text from the resolved target via the language's `NameProvider`
+     * when `$refText` is empty. The default deliberately does not reach for the
+     * `NameProvider`: a real Langium `Reference` always carries a `$refText`
+     * string, so no fallback can fire on the common path.
+     *
+     * Distinct from `ReferenceBuilder.getReferenceName`, which *mints* the name
+     * for a NEW reference from a source↔target relationship. This one *renders*
+     * a reference that already exists.
+     */
+    serializeReferenceText(value) {
+        if (isRefTextObject(value)) {
+            return value.$refText;
+        }
+        return typeof value === 'string' ? value : undefined;
+    }
+    /**
+     * Whether a property should be skipped because it carries no meaningful
+     * value: `undefined`, `null`, an empty array, a default value per grammar
+     * reflection, or a blank string. Subclasses may override to widen or
+     * narrow the skip policy.
+     */
+    shouldSkipProperty(nodeType, prop, value) {
+        if (value === undefined || value === null) {
+            return true;
+        }
+        if (Array.isArray(value) && value.length === 0) {
+            return true;
+        }
+        if (isDefaultValue(this.reflection, nodeType, prop, value)) {
+            return true;
+        }
+        if (typeof value === 'string' && value.trim() === '') {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Resolve the property that collapses a reference-wrapper node
+     * ({@link AbstractSerializerOptions.referenceWrapperTypes}) to its bare
+     * reference id, or `undefined` when the node carries additional non-empty
+     * GRAMMAR-DECLARED properties and must serialize as a regular nested node
+     * instead — an unconditional collapse would silently drop those values.
+     *
+     * The scan reads the declared property names from grammar reflection, NOT
+     * the node's own keys: transfer-model objects may carry synthesized
+     * companion fields (display labels, derived projections) that never
+     * persist, and counting those as "more" would break the collapse for
+     * every wrapper that crosses the wire in an enriched projection.
+     *
+     * Emptiness is judged by {@link shouldSkipProperty} plus one
+     * reference-specific rule: a reference object with a blank `$refText` is
+     * an unset reference and counts as empty. The rule lives here rather than
+     * in {@link shouldSkipProperty} so regular property emission is unchanged.
+     *
+     * Works on both value shapes — Langium AST nodes and transfer-model
+     * objects (plain string reference ids).
+     */
+    getReferenceWrapperProperty(node) {
+        const referenceProperty = this.options.referenceWrapperTypes?.get(node.$type);
+        if (!referenceProperty) {
+            return undefined;
+        }
+        const generic = node;
+        const declaredProperties = Object.keys(this.reflection.getTypeMetaData(node.$type).properties);
+        const carriesMore = declaredProperties.some(property => {
+            if (property === referenceProperty) {
+                return false;
+            }
+            const propertyValue = generic[property];
+            if (isRefTextObject(propertyValue) && propertyValue.$refText.trim() === '') {
+                return false;
+            }
+            return !this.shouldSkipProperty(node.$type, property, propertyValue);
+        });
+        return carriesMore ? undefined : referenceProperty;
+    }
+    /**
+     * Per-type ordered property names. Resolves the configured
+     * {@link AbstractSerializerOptions.propertyOrder} entry for `type`; falls back
+     * to the node's own JS-key order ({@link Object.keys}) when no entry
+     * exists. The walker filters `$`-prefixed keys downstream in
+     * {@link serializePropertyValue}, so passing every own key here is safe.
+     */
+    getOrderedPropertyNames(node, type) {
+        return this.options.propertyOrder?.get(type) ?? Object.keys(node);
+    }
+    /**
+     * Format a cross-reference value for emission. Defaults to `JSON.stringify`.
+     * Override to apply language-specific reference quoting — e.g. an
+     * id-reference formatter that mirrors the grammar's id convention.
+     *
+     * Returns {@link MaybePromise} so adopters with async formatting needs
+     * (remote schema lookup, external canonical-id resolution) can return a
+     * `Promise<string>`. Sync overrides remain valid.
+     */
+    formatReferenceValue(value) {
+        return JSON.stringify(value);
+    }
+    /**
+     * Format a primitive value (string, number, boolean) for emission. Defaults
+     * to `JSON.stringify`, which quotes strings, formats numbers/booleans, and
+     * is valid both as a YAML scalar and a JSON value.
+     *
+     * Returns {@link MaybePromise} so adopters with async formatting needs
+     * (e.g. delegating to `prettier.format` for a specific value class) can
+     * return a `Promise<string>`.
+     */
+    formatPrimitive(value) {
+        return JSON.stringify(value);
+    }
+    /**
+     * Hook for type-specific serialization that doesn't fit the generic
+     * dispatch table. Runs after all reference detection (steps 2-4 of
+     * {@link serializePropertyValue}) and before the nested-AST-node recurse,
+     * so references never reach this hook and the override may key purely on
+     * `(nodeType, key, value)`. Return `undefined` to fall through to the
+     * default handling. Default: returns `undefined` for everything.
+     *
+     * The in-repo override is
+     * `YamlSerializer`'s, which emits
+     * grammar-declared unquoted terminals as bare strings.
+     */
+    serializeCustomValue(_nodeType, _key, _value, _indentationLevel) {
+        return undefined;
+    }
+}
+//# sourceMappingURL=abstract-serializer.js.map