@_linked/core 2.12.0 → 2.13.0

package/lib/cjs/queries/FieldSet.js

@@ -1,802 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FieldSet = void 0;
-const PropertyPath_js_1 = require("./PropertyPath.js");
-const ShapeClass_js_1 = require("../utils/ShapeClass.js");
-const ProxiedPathBuilder_js_1 = require("./ProxiedPathBuilder.js");
-const ExpressionNode_js_1 = require("../expressions/ExpressionNode.js");
-const DslJsonExpression_js_1 = require("./DslJsonExpression.js");
-const QueryBuilderSerialization_js_1 = require("./QueryBuilderSerialization.js");
-const isQueryBuilderObject = (obj) => obj !== null &&
-    typeof obj === 'object' &&
-    'property' in obj &&
-    'subject' in obj &&
-    typeof obj.getPropertyPath === 'function';
-const isSetSize = (obj) => obj !== null &&
-    typeof obj === 'object' &&
-    'subject' in obj &&
-    typeof obj.as === 'function' &&
-    typeof obj.getPropertyPath === 'function' &&
-    // SetSize has a 'countable' field (may be undefined) and 'label' field
-    'label' in obj;
-// BoundComponent: has .source (QueryBuilderObject) and .originalValue (component-like)
-const isBoundComponent = (obj) => obj !== null &&
-    typeof obj === 'object' &&
-    'source' in obj &&
-    'originalValue' in obj;
-/** Option keys reserved inside a relation options object (never a relation path). */
-const RELATION_OPTION_KEYS = new Set([
-    'as',
-    'where',
-    'whereIndex',
-    'aggregation',
-    'customKey',
-    'limit',
-    'offset',
-    'orderBy',
-    'fields',
-]);
-/**
- * An immutable, composable collection of property paths for a shape.
- *
- * FieldSet describes which properties to select, independent of
- * how the query is built. It integrates with QueryBuilder via
- * `.select(fieldSet)`.
- *
- * Every mutation method returns a new FieldSet — the original is never modified.
- */
-class FieldSet {
-    constructor(shape, entries) {
-        this.shape = shape;
-        this.entries = entries;
-    }
-    static for(shape, fieldsOrFn) {
-        const resolved = FieldSet.resolveShapeInput(shape);
-        const resolvedShape = resolved.nodeShape;
-        if (typeof fieldsOrFn === 'function') {
-            if (!resolved.shapeClass) {
-                throw new Error(`Cannot use callback form for shape '${resolved.nodeShape.id}': no ShapeConstructor registered. ` +
-                    `Use string field names instead, or pass the Shape class directly.`);
-            }
-            const fields = FieldSet.traceFieldsWithProxy(resolved.nodeShape, resolved.shapeClass, fieldsOrFn);
-            return new FieldSet(resolved.nodeShape, fields);
-        }
-        const entries = FieldSet.resolveInputs(resolvedShape, fieldsOrFn);
-        return new FieldSet(resolvedShape, entries);
-    }
-    /**
-     * Create a typed FieldSet for a sub-select. Traces the callback through the proxy,
-     * stores parentSegments and traceResponse for runtime compatibility, and preserves
-     * R and Source generics for conditional type inference.
-     */
-    static forSubSelect(shapeClass, fn, parentSegments, source) {
-        const nodeShape = shapeClass.shape || shapeClass;
-        // Trace once: get both the raw response (for type carriers) and the entries
-        const proxy = (0, ProxiedPathBuilder_js_1.createProxiedPathBuilder)(shapeClass);
-        const traceResponse = fn(proxy);
-        const entries = FieldSet.extractSubSelectEntries(nodeShape, traceResponse);
-        const fs = new FieldSet(nodeShape, entries);
-        // Writable cast — these readonly fields are initialised once here at construction time
-        const w = fs;
-        w.traceResponse = traceResponse;
-        w.parentSegments = parentSegments;
-        w.shapeType = shapeClass;
-        // Carry an inline `.where()` from the parent traversal chain (walked
-        // leaf→root, same convention as convertTraceResult for plain paths).
-        let current = source;
-        let leafDistance = 0;
-        while (current) {
-            if (current.wherePath) {
-                w.parentWherePath = current.wherePath;
-                w.parentWherePathIndex = parentSegments.length - 1 - leafDistance;
-                break;
-            }
-            current = current.subject;
-            leafDistance++;
-        }
-        return fs;
-    }
-    static all(shape, opts) {
-        var _a;
-        const depth = (_a = opts === null || opts === void 0 ? void 0 : opts.depth) !== null && _a !== void 0 ? _a : 1;
-        if (depth < 1) {
-            throw new Error('FieldSet.all() requires depth >= 1. Use a node reference ({id}) for depth 0.');
-        }
-        const resolved = FieldSet.resolveShapeInput(shape);
-        // Seed visited with the root shape to prevent self-referencing cycles
-        const visited = new Set([resolved.nodeShape.id]);
-        return FieldSet.allForShape(resolved.nodeShape, depth, visited);
-    }
-    /**
-     * Recursive helper for all(). Tracks visited shape IDs to prevent infinite loops
-     * from circular shape references.
-     */
-    static allForShape(nodeShape, depth, visited) {
-        const propertyShapes = nodeShape.getUniquePropertyShapes();
-        const entries = [];
-        for (const ps of propertyShapes) {
-            const entry = { path: new PropertyPath_js_1.PropertyPath(nodeShape, [ps]) };
-            // If depth > 1, recurse into nested shapes
-            if (depth > 1 && ps.valueShape) {
-                const nestedShapeClass = (0, ShapeClass_js_1.getShapeClass)(ps.valueShape);
-                if ((nestedShapeClass === null || nestedShapeClass === void 0 ? void 0 : nestedShapeClass.shape) && !visited.has(nestedShapeClass.shape.id)) {
-                    visited.add(nestedShapeClass.shape.id);
-                    const nestedFs = FieldSet.allForShape(nestedShapeClass.shape, depth - 1, visited);
-                    if (nestedFs.entries.length > 0) {
-                        entry.subSelect = nestedFs;
-                    }
-                }
-            }
-            entries.push(entry);
-        }
-        return new FieldSet(nodeShape, entries);
-    }
-    /**
-     * Merge multiple FieldSets into one, deduplicating by path equality.
-     * All FieldSets must share the same root shape.
-     */
-    static merge(sets) {
-        if (sets.length === 0) {
-            throw new Error('Cannot merge empty array of FieldSets');
-        }
-        const shape = sets[0].shape;
-        for (const set of sets) {
-            if (set.shape.id !== shape.id) {
-                throw new Error(`Cannot merge FieldSets with different shapes: '${shape.label || shape.id}' and '${set.shape.label || set.shape.id}'`);
-            }
-        }
-        const merged = [];
-        const seen = new Set();
-        for (const set of sets) {
-            for (const entry of set.entries) {
-                // Include aggregation in the dedup key so that 'friends' and 'friends(count)' are distinct
-                const key = entry.aggregation
-                    ? `${entry.path.toString()}:${entry.aggregation}`
-                    : entry.path.toString();
-                if (!seen.has(key)) {
-                    seen.add(key);
-                    merged.push(entry);
-                }
-            }
-        }
-        return new FieldSet(shape, merged);
-    }
-    // ---------------------------------------------------------------------------
-    // Composition methods — each returns a new FieldSet
-    // ---------------------------------------------------------------------------
-    /** Returns a new FieldSet with only the given fields. */
-    select(fields) {
-        const entries = FieldSet.resolveInputs(this.shape, fields);
-        return new FieldSet(this.shape, entries);
-    }
-    /**
-     * Clone this FieldSet, preserving the sub-select carrier fields
-     * (traceResponse / parentSegments / shapeType / inner pagination) and
-     * applying the supplied overrides. Used by `.limit()`/`.offset()`/`.orderBy()`.
-     */
-    cloneWith(overrides) {
-        const clone = new FieldSet(this.shape, this.entries);
-        // The sub-select carrier fields are declared `readonly` (normally set once at
-        // construction via `forSubSelect`). Copy this FieldSet's identity onto the
-        // clone through a mutable view, then layer the pagination overrides on top.
-        Object.assign(clone, Object.assign({ traceResponse: this.traceResponse, parentSegments: this.parentSegments, shapeType: this.shapeType, parentWherePath: this.parentWherePath, parentWherePathIndex: this.parentWherePathIndex, innerLimit: this.innerLimit, innerOffset: this.innerOffset, innerOrderBy: this.innerOrderBy }, overrides));
-        return clone;
-    }
-    /**
-     * Bound a nested select's related collection to at most `lim` items per parent.
-     * Only honoured when the outer query targets a single subject; otherwise the
-     * pipeline throws (per-group pagination across multiple parents is unsupported).
-     */
-    limit(lim) {
-        return this.cloneWith({ innerLimit: lim });
-    }
-    /** Skip the first `off` items of a nested select's related collection (single-subject only). */
-    offset(off) {
-        return this.cloneWith({ innerOffset: off });
-    }
-    /**
-     * Order a nested select's related collection, producing a deterministic window
-     * for inner LIMIT/OFFSET. Defaults to ascending.
-     *
-     * Accepts either a proxy callback — `.orderBy(f => f.name)` — consistent with
-     * the rest of the DSL, or a property-name string (`.orderBy('name')`).
-     */
-    orderBy(paths, direction = 'ASC') {
-        const orderBy = typeof paths === 'function'
-            ? this.orderByFromProxy(paths, direction)
-            : (Array.isArray(paths) ? paths : [paths]).map((label) => {
-                const ps = (0, PropertyPath_js_1.walkPropertyPath)(this.shape, label).terminal;
-                if (!ps) {
-                    throw new Error(`orderBy: cannot resolve property '${label}' on shape '${this.shape.id}'`);
-                }
-                return { propertyShapeId: ps.id, direction };
-            });
-        return this.cloneWith({ innerOrderBy: orderBy });
-    }
-    /** Resolve a proxy `orderBy` callback (e.g. `f => f.name` or `f => [f.a, f.b]`)
-     *  to inner order-by clauses by tracing the sub-select shape's property proxy. */
-    orderByFromProxy(fn, direction) {
-        if (!this.shapeType) {
-            throw new Error('orderBy(callback) is only available on a nested select(); pass a property-name string otherwise');
-        }
-        const response = fn((0, ProxiedPathBuilder_js_1.createProxiedPathBuilder)(this.shapeType));
-        const results = Array.isArray(response) ? response : [response];
-        return results.map((result) => {
-            const segments = FieldSet.collectPropertySegments(result);
-            const terminal = segments[segments.length - 1];
-            if (!terminal) {
-                throw new Error('orderBy: callback did not resolve to a property of the sub-select shape');
-            }
-            return { propertyShapeId: terminal.id, direction };
-        });
-    }
-    /** Returns a new FieldSet with additional entries. */
-    add(fields) {
-        const newEntries = FieldSet.resolveInputs(this.shape, fields);
-        // Deduplicate
-        const existing = new Set(this.entries.map((e) => e.path.toString()));
-        const combined = [...this.entries];
-        for (const entry of newEntries) {
-            if (!existing.has(entry.path.toString())) {
-                combined.push(entry);
-            }
-        }
-        return new FieldSet(this.shape, combined);
-    }
-    /** Returns a new FieldSet without entries matching the given labels. */
-    remove(labels) {
-        const labelSet = new Set(labels);
-        const filtered = this.entries.filter((e) => { var _a; return !labelSet.has((_a = e.path.terminal) === null || _a === void 0 ? void 0 : _a.label); });
-        return new FieldSet(this.shape, filtered);
-    }
-    /** Synonym for replacing all entries — returns a new FieldSet with only the given fields. */
-    set(fields) {
-        const entries = FieldSet.resolveInputs(this.shape, fields);
-        return new FieldSet(this.shape, entries);
-    }
-    /** Returns a new FieldSet keeping only entries matching the given labels. */
-    pick(labels) {
-        const labelSet = new Set(labels);
-        const filtered = this.entries.filter((e) => { var _a; return labelSet.has((_a = e.path.terminal) === null || _a === void 0 ? void 0 : _a.label); });
-        return new FieldSet(this.shape, filtered);
-    }
-    /** Returns all PropertyPaths in this FieldSet. */
-    paths() {
-        return this.entries.map((e) => e.path);
-    }
-    /** Returns terminal property labels of all entries. */
-    labels() {
-        return this.entries.map((e) => { var _a; return (_a = e.path.terminal) === null || _a === void 0 ? void 0 : _a.label; }).filter(Boolean);
-    }
-    // ---------------------------------------------------------------------------
-    // Serialization
-    // ---------------------------------------------------------------------------
-    /**
-     * Serialize this FieldSet to a plain JSON object.
-     * Shape is identified by its IRI, paths by dot-separated labels.
-     */
-    toJSON() {
-        return { shape: this.shape.id, fields: this.toFieldsJSON() };
-    }
-    /** Serialize just the field entries (used for nested relation sub-fields). */
-    toFieldsJSON() {
-        return this.entries.map((entry) => this.serializeEntry(entry));
-    }
-    serializeEntry(entry) {
-        var _a, _b;
-        // Computed projection — no path; carry the DSL-JSON value.
-        if (entry.expressionNode) {
-            const out = {
-                value: (0, DslJsonExpression_js_1.encodeValueExpr)(entry.expressionNode.ir, entry.expressionNode._refs),
-            };
-            if (entry.alias)
-                out.as = entry.alias;
-            if (entry.customKey)
-                out.customKey = entry.customKey;
-            return out;
-        }
-        const pathStr = FieldSet.pathToStringWithCasts(this.shape, entry.path.segments);
-        const sub = (_a = entry.subSelect) !== null && _a !== void 0 ? _a : entry.preloadSubSelect;
-        const subFields = sub ? sub.toFieldsJSON() : undefined;
-        const opts = {};
-        if (entry.alias)
-            opts.as = entry.alias;
-        if (entry.aggregation)
-            opts.aggregation = entry.aggregation;
-        if (entry.customKey)
-            opts.customKey = entry.customKey;
-        if (entry.scopedFilter) {
-            const idx = (_b = entry.scopedFilterIndex) !== null && _b !== void 0 ? _b : entry.path.segments.length - 1;
-            opts.where = (0, QueryBuilderSerialization_js_1.serializeWherePath)(entry.scopedFilter, this.scopedShapeAt(entry, idx));
-            opts.whereIndex = idx;
-        }
-        // Nested-select pagination (G10) — was previously dropped on the wire.
-        if (typeof entry.innerLimit === 'number')
-            opts.limit = entry.innerLimit;
-        if (typeof entry.innerOffset === 'number')
-            opts.offset = entry.innerOffset;
-        if (entry.innerOrderBy && entry.innerOrderBy.length > 0) {
-            opts.orderBy = entry.innerOrderBy.map((o) => ({
-                [FieldSet.labelOfId(o.propertyShapeId)]: o.direction,
-            }));
-        }
-        const hasOpts = Object.keys(opts).length > 0;
-        // Bare-string shorthand: a plain leaf/relation with no options or sub-fields.
-        if (!subFields && !hasOpts)
-            return pathStr;
-        // Array shorthand: sub-fields only, no other options.
-        if (subFields && !hasOpts)
-            return { [pathStr]: subFields };
-        // Full options object (optionally carrying `fields`).
-        return { [pathStr]: Object.assign(Object.assign({}, opts), (subFields ? { fields: subFields } : {})) };
-    }
-    /** The shape a scoped filter at segment `idx` is evaluated against (the segment's value shape). */
-    scopedShapeAt(entry, idx) {
-        var _a, _b;
-        const seg = entry.path.segments[idx];
-        const valueShapeId = (_a = seg === null || seg === void 0 ? void 0 : seg.valueShape) === null || _a === void 0 ? void 0 : _a.id;
-        return (valueShapeId && ((_b = (0, ShapeClass_js_1.getShapeClass)(valueShapeId)) === null || _b === void 0 ? void 0 : _b.shape)) || this.shape;
-    }
-    /**
-     * Reconstruct a FieldSet from a JSON object.
-     * Resolves shape IRI via getShapeClass() and paths via walkPropertyPath().
-     */
-    static fromJSON(json) {
-        return FieldSet.fromFields(FieldSet.resolveShape(json.shape), json.fields);
-    }
-    /** Build a FieldSet from a shape + relation-keyed field list (recursion entry). */
-    static fromFields(shape, fields) {
-        return new FieldSet(shape, fields.map((raw) => FieldSet.parseField(shape, raw)));
-    }
-    /** Parse one field entry (string leaf / computed / relation-keyed) against `shape`. */
-    static parseField(shape, raw) {
-        var _a, _b, _c, _d, _e;
-        // Leaf path (may carry inline `as(Shape)` casts).
-        if (typeof raw === 'string') {
-            return { path: FieldSet.walkPathWithCasts(shape, raw) };
-        }
-        // Computed projection — carries `value`.
-        if ('value' in raw && raw.value !== undefined) {
-            const computed = raw;
-            const { ir, refs } = (0, DslJsonExpression_js_1.decodeValueExpr)(computed.value, shape);
-            const entry = {
-                path: new PropertyPath_js_1.PropertyPath(shape, []),
-                expressionNode: new ExpressionNode_js_1.ExpressionNode(ir, refs),
-            };
-            if (computed.as)
-                entry.alias = computed.as;
-            if (computed.customKey)
-                entry.customKey = computed.customKey;
-            return entry;
-        }
-        // Relation-keyed: the single non-option key is the relation path.
-        const rel = raw;
-        const pathKey = Object.keys(rel).find((k) => !RELATION_OPTION_KEYS.has(k));
-        if (!pathKey) {
-            throw new Error(`FieldSet field has no relation path: ${JSON.stringify(raw)}`);
-        }
-        const spec = rel[pathKey];
-        const path = FieldSet.walkPathWithCasts(shape, pathKey);
-        const entry = { path };
-        const subFields = Array.isArray(spec) ? spec : spec.fields;
-        const opts = Array.isArray(spec) ? {} : spec;
-        if (opts.as)
-            entry.alias = opts.as;
-        if (opts.customKey)
-            entry.customKey = opts.customKey;
-        if (opts.aggregation)
-            entry.aggregation = opts.aggregation;
-        if (opts.where) {
-            const idx = (_a = opts.whereIndex) !== null && _a !== void 0 ? _a : path.segments.length - 1;
-            const seg = path.segments[idx];
-            const valueShapeId = (_b = seg === null || seg === void 0 ? void 0 : seg.valueShape) === null || _b === void 0 ? void 0 : _b.id;
-            const scopedShape = (valueShapeId && ((_c = (0, ShapeClass_js_1.getShapeClass)(valueShapeId)) === null || _c === void 0 ? void 0 : _c.shape)) || shape;
-            entry.scopedFilter = (0, QueryBuilderSerialization_js_1.deserializeWherePath)(scopedShape, opts.where);
-            entry.scopedFilterIndex = idx;
-        }
-        // Nested-select pagination (G10).
-        if (typeof opts.limit === 'number')
-            entry.innerLimit = opts.limit;
-        if (typeof opts.offset === 'number')
-            entry.innerOffset = opts.offset;
-        if (opts.orderBy && opts.orderBy.length > 0) {
-            const nested = (_d = FieldSet.nestedShapeOf(path)) !== null && _d !== void 0 ? _d : shape;
-            entry.innerOrderBy = opts.orderBy.map((e) => {
-                var _a;
-                const label = Object.keys(e)[0];
-                const ps = nested.getPropertyShape(label);
-                return { propertyShapeId: (_a = ps === null || ps === void 0 ? void 0 : ps.id) !== null && _a !== void 0 ? _a : label, direction: Object.values(e)[0] };
-            });
-        }
-        if (subFields) {
-            const nested = (_e = FieldSet.nestedShapeOf(path)) !== null && _e !== void 0 ? _e : shape;
-            entry.subSelect = FieldSet.fromFields(nested, subFields);
-        }
-        return entry;
-    }
-    /** The shape reached at the end of a relation path (its terminal segment's value shape). */
-    static nestedShapeOf(path) {
-        var _a, _b;
-        const seg = path.segments[path.segments.length - 1];
-        const valueShapeId = (_a = seg === null || seg === void 0 ? void 0 : seg.valueShape) === null || _a === void 0 ? void 0 : _a.id;
-        return (valueShapeId && ((_b = (0, ShapeClass_js_1.getShapeClass)(valueShapeId)) === null || _b === void 0 ? void 0 : _b.shape)) || undefined;
-    }
-    // ---------------------------------------------------------------------------
-    // Private helpers
-    // ---------------------------------------------------------------------------
-    /**
-     * Resolves any of the accepted shape input types to a NodeShape and optional ShapeClass.
-     * Accepts: ShapeConstructor (class with .shape), NodeShape, or IRI string.
-     */
-    static resolveShapeInput(shape) {
-        if (typeof shape === 'string') {
-            const shapeClass = (0, ShapeClass_js_1.getShapeClass)(shape);
-            if (!shapeClass || !shapeClass.shape) {
-                throw new Error(`Cannot resolve shape for '${shape}'`);
-            }
-            return { nodeShape: shapeClass.shape, shapeClass };
-        }
-        // ShapeConstructor: has a static .shape property that is a NodeShape
-        if ('shape' in shape && typeof shape.shape === 'object' && shape.shape !== null && 'id' in shape.shape) {
-            return { nodeShape: shape.shape, shapeClass: shape };
-        }
-        // NodeShape: has .id directly — try to look up its ShapeConstructor for full proxy support
-        const nodeShape = shape;
-        const shapeClass = nodeShape.id ? (0, ShapeClass_js_1.getShapeClass)(nodeShape.id) : undefined;
-        return shapeClass
-            ? { nodeShape, shapeClass }
-            : { nodeShape };
-    }
-    /** @deprecated Use resolveShapeInput instead. Kept for fromJSON which only passes NodeShape|string. */
-    static resolveShape(shape) {
-        return FieldSet.resolveShapeInput(shape).nodeShape;
-    }
-    static resolveInputs(shape, inputs) {
-        const entries = [];
-        for (const input of inputs) {
-            if (typeof input === 'string') {
-                entries.push({ path: (0, PropertyPath_js_1.walkPropertyPath)(shape, input) });
-            }
-            else if (input instanceof PropertyPath_js_1.PropertyPath) {
-                entries.push({ path: input });
-            }
-            else if (input instanceof FieldSet) {
-                entries.push(...input.entries);
-            }
-            else if (typeof input === 'object') {
-                // Nested object form: { friends: ['name', 'hobby'] }
-                for (const [key, value] of Object.entries(input)) {
-                    const basePath = (0, PropertyPath_js_1.walkPropertyPath)(shape, key);
-                    if (value instanceof FieldSet) {
-                        // Merge nested FieldSet entries under this path
-                        for (const entry of value.entries) {
-                            const combined = new PropertyPath_js_1.PropertyPath(shape, [
-                                ...basePath.segments,
-                                ...entry.path.segments,
-                            ]);
-                            entries.push({ path: combined, alias: entry.alias, scopedFilter: entry.scopedFilter });
-                        }
-                    }
-                    else if (Array.isArray(value)) {
-                        // Resolve nested string fields
-                        const basePropertyShape = basePath.terminal;
-                        if (!(basePropertyShape === null || basePropertyShape === void 0 ? void 0 : basePropertyShape.valueShape)) {
-                            throw new Error(`Property '${key}' has no valueShape; cannot resolve nested fields`);
-                        }
-                        const nestedShapeClass = (0, ShapeClass_js_1.getShapeClass)(basePropertyShape.valueShape);
-                        if (!nestedShapeClass || !nestedShapeClass.shape) {
-                            throw new Error(`Cannot resolve valueShape for property '${key}'`);
-                        }
-                        for (const nestedField of value) {
-                            const nestedPath = (0, PropertyPath_js_1.walkPropertyPath)(nestedShapeClass.shape, nestedField);
-                            const combined = new PropertyPath_js_1.PropertyPath(shape, [
-                                ...basePath.segments,
-                                ...nestedPath.segments,
-                            ]);
-                            entries.push({ path: combined });
-                        }
-                    }
-                }
-            }
-        }
-        return entries;
-    }
-    /**
-     * Trace fields using the full ProxiedPathBuilder proxy (createProxiedPathBuilder).
-     * Handles nested paths, where conditions, aggregations, and sub-selects.
-     */
-    static traceFieldsWithProxy(nodeShape, shapeClass, fn) {
-        const proxy = (0, ProxiedPathBuilder_js_1.createProxiedPathBuilder)(shapeClass);
-        const result = fn(proxy);
-        // Normalize result: could be a single value, array, or custom object
-        if (Array.isArray(result)) {
-            return result.map((item) => FieldSet.convertTraceResult(nodeShape, item));
-        }
-        if (isQueryBuilderObject(result)) {
-            return [FieldSet.convertTraceResult(nodeShape, result)];
-        }
-        // Single FieldSet sub-select (e.g. p.friends.select(f => [f.name]))
-        if (result instanceof FieldSet && result.parentSegments !== undefined) {
-            return [FieldSet.convertTraceResult(nodeShape, result)];
-        }
-        // Single SetSize (e.g. p.friends.size())
-        if (isSetSize(result)) {
-            return [FieldSet.convertTraceResult(nodeShape, result)];
-        }
-        // Single BoundComponent (e.g. p.bestFriend.preloadFor(comp))
-        if (isBoundComponent(result)) {
-            return [FieldSet.convertTraceResult(nodeShape, result)];
-        }
-        // Single ExpressionNode (e.g. p.age.times(12))
-        if ((0, ExpressionNode_js_1.isExpressionNode)(result)) {
-            return [FieldSet.convertTraceResult(nodeShape, result)];
-        }
-        if (typeof result === 'object' && result !== null) {
-            // Custom object form: {name: p.name, hobby: p.hobby}
-            const entries = [];
-            for (const [key, value] of Object.entries(result)) {
-                const entry = FieldSet.convertTraceResult(nodeShape, value);
-                entry.customKey = key;
-                entries.push(entry);
-            }
-            return entries;
-        }
-        return [];
-    }
-    /**
-     * Convert a single proxy trace result (QueryBuilderObject, SetSize, or FieldSet sub-select)
-     * into a FieldSetEntry.
-     */
-    static convertTraceResult(rootShape, obj) {
-        // SetSize → aggregation: 'count'
-        if (isSetSize(obj)) {
-            const segments = FieldSet.collectPropertySegments(obj.subject);
-            return {
-                path: new PropertyPath_js_1.PropertyPath(rootShape, segments),
-                aggregation: 'count',
-            };
-        }
-        // FieldSet sub-select — use its entries directly (created by forSubSelect)
-        if (obj instanceof FieldSet && obj.parentSegments !== undefined) {
-            const subSelect = obj.entries.length > 0 ? obj : undefined;
-            const entry = {
-                path: new PropertyPath_js_1.PropertyPath(rootShape, obj.parentSegments),
-                subSelect: subSelect,
-            };
-            // Carry an inline `.where()` from the parent traversal chain
-            // (e.g. `p.friends.where(...).select(...)`).
-            if (obj.parentWherePath) {
-                entry.scopedFilter = obj.parentWherePath;
-                entry.scopedFilterIndex = obj.parentWherePathIndex;
-            }
-            // Carry inner LIMIT/OFFSET/ORDER BY from `.limit()`/`.offset()`/`.orderBy()`.
-            if (typeof obj.innerLimit === 'number')
-                entry.innerLimit = obj.innerLimit;
-            if (typeof obj.innerOffset === 'number')
-                entry.innerOffset = obj.innerOffset;
-            if (obj.innerOrderBy)
-                entry.innerOrderBy = obj.innerOrderBy;
-            return entry;
-        }
-        // BoundComponent → preload composition (e.g. p.bestFriend.preloadFor(component))
-        // Extract the component's FieldSet and store it as preloadSubSelect.
-        if (isBoundComponent(obj)) {
-            const segments = FieldSet.collectPropertySegments(obj.source);
-            const componentFieldSet = FieldSet.extractComponentFieldSet(obj.originalValue);
-            return {
-                path: new PropertyPath_js_1.PropertyPath(rootShape, segments),
-                preloadSubSelect: componentFieldSet,
-            };
-        }
-        // ExpressionNode → computed expression (e.g. p.age.times(12))
-        if ((0, ExpressionNode_js_1.isExpressionNode)(obj)) {
-            return {
-                path: new PropertyPath_js_1.PropertyPath(rootShape, []),
-                expressionNode: obj,
-            };
-        }
-        // QueryBuilderObject → walk the chain to collect PropertyPath segments
-        if (isQueryBuilderObject(obj)) {
-            const segments = FieldSet.collectPropertySegments(obj);
-            const entry = {
-                path: new PropertyPath_js_1.PropertyPath(rootShape, segments),
-            };
-            // Walk from leaf to root to find wherePath on any object in the chain.
-            // Track which segment it belongs to so desugarEntry attaches the filter correctly.
-            let current = obj;
-            let leafDistance = 0;
-            while (current) {
-                if (current.wherePath) {
-                    entry.scopedFilter = current.wherePath;
-                    entry.scopedFilterIndex = segments.length - 1 - leafDistance;
-                    break;
-                }
-                current = current.subject;
-                leafDistance++;
-            }
-            return entry;
-        }
-        // Fallback: string label
-        if (typeof obj === 'string') {
-            return { path: (0, PropertyPath_js_1.walkPropertyPath)(rootShape, obj) };
-        }
-        throw new Error(`Unknown trace result type: ${obj}`);
-    }
-    /**
-     * Walk a QueryBuilderObject-like chain (via .subject) collecting PropertyShape segments
-     * from leaf to root, then reverse to get root-to-leaf order.
-     */
-    static collectPropertySegments(obj) {
-        const segments = [];
-        let current = obj;
-        while (current) {
-            if (current.property) {
-                segments.unshift(current.property);
-            }
-            current = current.subject;
-        }
-        return segments;
-    }
-    // ---------------------------------------------------------------------------
-    // Cast-aware path (de)serialization — carries `.as(Shape)` narrowing inline as
-    // an `as(<ShapeLabel>)` path segment (documentation/dsl-json.md, backlog 002 G5).
-    // ---------------------------------------------------------------------------
-    static shapeById(id) {
-        var _a;
-        return (_a = (0, ShapeClass_js_1.getShapeClass)(id)) === null || _a === void 0 ? void 0 : _a.shape;
-    }
-    static shapeByLabel(label) {
-        for (const cls of (0, ShapeClass_js_1.getAllShapeClasses)().values()) {
-            const shape = cls.shape;
-            if (shape && (shape.label === label || FieldSet.labelOfId(shape.id) === label)) {
-                return shape;
-            }
-        }
-        return undefined;
-    }
-    static labelOfId(id) {
-        const i = id.lastIndexOf('/');
-        return i >= 0 ? id.slice(i + 1) : id;
-    }
-    /**
-     * Render a segment chain as a dotted label path, inserting `as(<ShapeLabel>)`
-     * wherever a segment is not resolvable by label from the natural (walked) shape
-     * — i.e. a `.as(Shape)` narrowing happened before it.
-     */
-    static pathToStringWithCasts(rootShape, segments) {
-        var _a, _b;
-        const parts = [];
-        let current = rootShape;
-        for (const seg of segments) {
-            const label = FieldSet.labelOfId(seg.id);
-            const natural = current === null || current === void 0 ? void 0 : current.getPropertyShape(label);
-            if (!natural || natural.id !== seg.id) {
-                // A cast narrowed the context to the segment's owner shape.
-                const ownerId = seg.id.slice(0, seg.id.lastIndexOf('/'));
-                const owner = FieldSet.shapeById(ownerId);
-                parts.push(`as(${(_a = owner === null || owner === void 0 ? void 0 : owner.label) !== null && _a !== void 0 ? _a : FieldSet.labelOfId(ownerId)})`);
-                current = owner !== null && owner !== void 0 ? owner : current;
-            }
-            parts.push(label);
-            const vs = seg.valueShape;
-            current = vs ? (_b = FieldSet.shapeById(vs.id)) !== null && _b !== void 0 ? _b : current : current;
-        }
-        return parts.join('.');
-    }
-    /** Inverse of {@link pathToStringWithCasts}: resolve a dotted path with `as(X)` casts. */
-    static walkPathWithCasts(rootShape, path) {
-        var _a, _b;
-        if (!path.includes('as('))
-            return (0, PropertyPath_js_1.walkPropertyPath)(rootShape, path);
-        const segments = [];
-        let current = rootShape;
-        for (const token of path.split('.')) {
-            const cast = /^as\((.+)\)$/.exec(token);
-            if (cast) {
-                current = (_a = FieldSet.shapeByLabel(cast[1])) !== null && _a !== void 0 ? _a : current;
-                continue;
-            }
-            const ps = current === null || current === void 0 ? void 0 : current.getPropertyShape(token);
-            if (!ps) {
-                throw new Error(`Property '${token}' not found on shape '${(current === null || current === void 0 ? void 0 : current.label) || (current === null || current === void 0 ? void 0 : current.id)}' while resolving path '${path}'`);
-            }
-            segments.push(ps);
-            const vs = ps.valueShape;
-            current = vs ? (_b = FieldSet.shapeById(vs.id)) !== null && _b !== void 0 ? _b : current : current;
-        }
-        return new PropertyPath_js_1.PropertyPath(rootShape, segments);
-    }
-    /**
-     * Extract a FieldSet from a component-like object for preload composition.
-     *
-     * Supports multiple component interfaces:
-     * - `.fields` as a FieldSet directly
-     * - `.query` as a FieldSet, QueryBuilder (duck-typed via .fields()), or
-     *   Record<string, QueryBuilder> (e.g. `{person: PersonQuery}`)
-     */
-    static extractComponentFieldSet(component) {
-        // Prefer .fields if it's a FieldSet
-        if (component.fields instanceof FieldSet) {
-            return component.fields;
-        }
-        const query = component.query;
-        if (query instanceof FieldSet) {
-            return query;
-        }
-        // QueryBuilder duck-type — has .fields() method
-        if (query && typeof query.fields === 'function') {
-            return query.fields();
-        }
-        // Record form: { propName: QueryBuilder }
-        if (typeof query === 'object') {
-            for (const key in query) {
-                const value = query[key];
-                if (value && typeof value.fields === 'function') {
-                    return value.fields();
-                }
-            }
-        }
-        return undefined;
-    }
-    /**
-     * Internal factory that bypasses the private constructor for use by static methods.
-     */
-    static createInternal(shape, entries) {
-        return new FieldSet(shape, entries);
-    }
-    /**
-     * Create a FieldSet from raw entries. Used by QueryBuilder to merge preload entries.
-     */
-    static createFromEntries(shape, entries) {
-        return new FieldSet(shape, entries);
-    }
-    /**
-     * Extract FieldSetEntry[] from a sub-query's traceResponse.
-     * Public alias for use by lightweight sub-select wrappers.
-     */
-    static extractSubSelectEntriesPublic(rootShape, traceResponse) {
-        return FieldSet.extractSubSelectEntries(rootShape, traceResponse);
-    }
-    /**
-     * Extract FieldSetEntry[] from a sub-select's traceResponse.
-     * The traceResponse is the result of calling the sub-query callback with a proxy,
-     * containing QueryBuilderObjects, arrays, custom objects, etc.
-     */
-    static extractSubSelectEntries(rootShape, traceResponse) {
-        if (Array.isArray(traceResponse)) {
-            return traceResponse
-                .filter((item) => item !== null && item !== undefined)
-                .map((item) => FieldSet.convertTraceResult(rootShape, item));
-        }
-        if (isQueryBuilderObject(traceResponse)) {
-            return [FieldSet.convertTraceResult(rootShape, traceResponse)];
-        }
-        // Single FieldSet sub-select — convert directly
-        if (traceResponse instanceof FieldSet && traceResponse.parentSegments !== undefined) {
-            return [FieldSet.convertTraceResult(rootShape, traceResponse)];
-        }
-        // Single SetSize
-        if (isSetSize(traceResponse)) {
-            return [FieldSet.convertTraceResult(rootShape, traceResponse)];
-        }
-        // Single ExpressionNode
-        if ((0, ExpressionNode_js_1.isExpressionNode)(traceResponse)) {
-            return [FieldSet.convertTraceResult(rootShape, traceResponse)];
-        }
-        if (typeof traceResponse === 'object' && traceResponse !== null) {
-            // Custom object form: {name: p.name, hobby: p.hobby}
-            const entries = [];
-            for (const [key, value] of Object.entries(traceResponse)) {
-                if (value !== null && value !== undefined) {
-                    const entry = FieldSet.convertTraceResult(rootShape, value);
-                    entry.customKey = key;
-                    entries.push(entry);
-                }
-            }
-            return entries;
-        }
-        return [];
-    }
-}
-exports.FieldSet = FieldSet;
-//# sourceMappingURL=FieldSet.js.map