@_linked/core 2.12.0 → 2.13.0

package/lib/cjs/queries/FieldSet.d.ts

@@ -1,310 +0,0 @@
-import type { NodeShape, PropertyShape } from '../shapes/SHACL.js';
-import type { Shape, ShapeConstructor } from '../shapes/Shape.js';
-import { PropertyPath } from './PropertyPath.js';
-import type { WherePath } from './SelectQuery.js';
-import { ExpressionNode } from '../expressions/ExpressionNode.js';
-import { type DslJsonValue } from './DslJsonExpression.js';
-import { type WherePathJSON } from './QueryBuilderSerialization.js';
-type QueryBuilderObjectLike = {
-    property?: PropertyShape;
-    subject?: QueryBuilderObjectLike;
-    wherePath?: unknown;
-};
-/**
- * A single entry in a FieldSet: a property path with optional alias, scoped filter,
- * sub-selection, aggregation, and custom key.
- */
-export type FieldSetEntry = {
-    path: PropertyPath;
-    alias?: string;
-    scopedFilter?: WherePath;
-    /** Index into path.segments indicating which segment the scopedFilter applies to.
-     *  Defaults to the last segment if not specified. */
-    scopedFilterIndex?: number;
-    /** Nested object selection — the user explicitly selected sub-fields (e.g. `p.friends.select(...)`) */
-    subSelect?: FieldSet;
-    aggregation?: 'count';
-    customKey?: string;
-    /** Component preload composition — the FieldSet comes from a linked component's own query,
-     *  merged in via `preloadFor()`. Distinct from subSelect which is a user-authored nested query. */
-    preloadSubSelect?: FieldSet;
-    /** Computed expression from proxy tracing (e.g. `p.age.times(12)`) */
-    expressionNode?: ExpressionNode;
-    /** Inner LIMIT for a nested select (e.g. `p.friends.select(...).limit(2)`).
-     *  Only supported when the outer query targets a single subject. */
-    innerLimit?: number;
-    /** Inner OFFSET for a nested select. */
-    innerOffset?: number;
-    /** Inner ORDER BY for a nested select — paths relative to the sub-select shape. */
-    innerOrderBy?: FieldSetInnerOrderBy[];
-};
-/** A single inner ORDER BY clause for a nested select. */
-export type FieldSetInnerOrderBy = {
-    propertyShapeId: string;
-    direction: 'ASC' | 'DESC';
-};
-/**
- * Input types accepted by FieldSet construction methods.
- *
- * - `string` — resolved via walkPropertyPath (dot-separated)
- * - `PropertyPath` — used directly
- * - `FieldSet` — merged in
- * - `Record<string, string[] | FieldSet>` — nested fields
- */
-export type FieldSetInput = string | PropertyPath | FieldSet | Record<string, string[] | FieldSet>;
-/** A computed projection field: `{ as?, value }` — a DSL-JSON expression, no path. */
-export type FieldSetComputedJSON = {
-    as?: string;
-    value: DslJsonValue;
-    customKey?: string;
-};
-/** Options for a relation projection (the object value under a relation key). */
-export type FieldSetRelationOptionsJSON = {
-    as?: string;
-    /** A scoped filter on the relation (`p.friends.where(...)`). */
-    where?: WherePathJSON;
-    /** Which path segment the scoped `where` applies to (defaults to the last). */
-    whereIndex?: number;
-    aggregation?: string;
-    customKey?: string;
-    /** Nested-select pagination (`p.friends.select(...).limit(5).offset(2).orderBy(...)`). */
-    limit?: number;
-    offset?: number;
-    orderBy?: Array<{
-        [path: string]: 'ASC' | 'DESC';
-    }>;
-    /** Sub-projection of the related shape. */
-    fields?: FieldSetFieldJSON[];
-};
-/**
- * A relation-keyed field: a single-key object whose key is the relation path
- * (labels dotted, with inline `as(Shape)` casts) and whose value is either the
- * sub-fields array (`{ "friends": ["name"] }`) or an options object
- * (`{ "friends": { as, where, fields } }`). Also covers a leaf with options
- * (`{ "name": { "as": "personName" } }`). The related shape is inferred.
- */
-export type FieldSetRelationJSON = {
-    [path: string]: FieldSetFieldJSON[] | FieldSetRelationOptionsJSON;
-};
-/**
- * JSON representation of a FieldSet field entry — exactly three shapes:
- *   - a **string** leaf path (`"name"`, `"friends.friends.name"`, `"pets.as(Dog).level"`)
- *   - a **relation-keyed** object (`{ "friends": [...] | {options} }`)
- *   - a **computed** object (`{ as?, value }`)
- */
-export type FieldSetFieldJSON = string | FieldSetComputedJSON | FieldSetRelationJSON;
-/** JSON representation of a FieldSet (a shape + its top-level fields). */
-export type FieldSetJSON = {
-    shape: string;
-    fields: FieldSetFieldJSON[];
-};
-/**
- * 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.
- */
-export declare class FieldSet<R = any, Source = any> {
-    readonly shape: NodeShape;
-    readonly entries: readonly FieldSetEntry[];
-    /** Phantom field — carries the callback response type for conditional type inference. */
-    readonly __response: R;
-    /** Phantom field — carries the source context (QueryShapeSet/QueryShape) for conditional type inference. */
-    readonly __source: Source;
-    /**
-     * For sub-select FieldSets: the raw callback return value (proxy trace objects).
-     * Stored so conditional types can extract the response type.
-     */
-    readonly traceResponse?: R;
-    /**
-     * For sub-select FieldSets: the parent property segments leading to this sub-select.
-     */
-    readonly parentSegments?: PropertyShape[];
-    /**
-     * For sub-select FieldSets: the shape class (ShapeType) of the sub-select's target.
-     */
-    readonly shapeType?: any;
-    /**
-     * For sub-select FieldSets: inline `.where()` filter found on the parent
-     * traversal chain (e.g. `p.friends.where(...).select(...)`), plus the index
-     * into `parentSegments` of the segment it scopes.
-     */
-    readonly parentWherePath?: WherePath;
-    readonly parentWherePathIndex?: number;
-    /**
-     * For sub-select FieldSets: inner LIMIT/OFFSET/ORDER BY carried from
-     * `.limit()`/`.offset()`/`.orderBy()` chained on the nested select.
-     * These bound the related collection per parent (single-subject only).
-     */
-    readonly innerLimit?: number;
-    readonly innerOffset?: number;
-    readonly innerOrderBy?: FieldSetInnerOrderBy[];
-    private constructor();
-    /**
-     * Create a FieldSet for the given shape with the specified fields.
-     *
-     * Accepts a ShapeClass (e.g. Person), NodeShape, or shape IRI string.
-     * Fields can be string paths, PropertyPath instances, nested objects,
-     * or a callback receiving a proxy for dot-access.
-     */
-    static for<S extends Shape>(shape: ShapeConstructor<S>, fields: FieldSetInput[]): FieldSet<any>;
-    static for<S extends Shape, R>(shape: ShapeConstructor<S>, fn: (p: any) => R): FieldSet<R>;
-    static for(shape: NodeShape | string, fields: FieldSetInput[]): FieldSet<any>;
-    static for(shape: NodeShape | string, fn: (p: any) => any): FieldSet<any>;
-    /**
-     * 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<R, Source>(shapeClass: any, fn: (p: any) => R, parentSegments: PropertyShape[], source?: QueryBuilderObjectLike): FieldSet<R, Source>;
-    /**
-     * Create a FieldSet containing all decorated properties of the shape.
-     *
-     * @param opts.depth Controls how deep to include nested shape properties:
-     *   - `depth=1` (default): this level only — properties of the root shape.
-     *   - `depth=0`: throws — use a node reference instead.
-     *   - `depth>1`: recursively includes nested shape properties up to the given depth.
-     */
-    static all<S extends Shape>(shape: ShapeConstructor<S>, opts?: {
-        depth?: number;
-    }): FieldSet;
-    static all(shape: NodeShape | string, opts?: {
-        depth?: number;
-    }): FieldSet;
-    /**
-     * Recursive helper for all(). Tracks visited shape IDs to prevent infinite loops
-     * from circular shape references.
-     */
-    private static allForShape;
-    /**
-     * Merge multiple FieldSets into one, deduplicating by path equality.
-     * All FieldSets must share the same root shape.
-     */
-    static merge(sets: FieldSet[]): FieldSet;
-    /** Returns a new FieldSet with only the given fields. */
-    select(fields: FieldSetInput[]): FieldSet;
-    /**
-     * Clone this FieldSet, preserving the sub-select carrier fields
-     * (traceResponse / parentSegments / shapeType / inner pagination) and
-     * applying the supplied overrides. Used by `.limit()`/`.offset()`/`.orderBy()`.
-     */
-    private cloneWith;
-    /**
-     * 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: number): this;
-    /** Skip the first `off` items of a nested select's related collection (single-subject only). */
-    offset(off: number): this;
-    /**
-     * 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: string | string[] | ((p: any) => unknown), direction?: 'ASC' | 'DESC'): this;
-    /** 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. */
-    private orderByFromProxy;
-    /** Returns a new FieldSet with additional entries. */
-    add(fields: FieldSetInput[]): FieldSet;
-    /** Returns a new FieldSet without entries matching the given labels. */
-    remove(labels: string[]): FieldSet;
-    /** Synonym for replacing all entries — returns a new FieldSet with only the given fields. */
-    set(fields: FieldSetInput[]): FieldSet;
-    /** Returns a new FieldSet keeping only entries matching the given labels. */
-    pick(labels: string[]): FieldSet;
-    /** Returns all PropertyPaths in this FieldSet. */
-    paths(): PropertyPath[];
-    /** Returns terminal property labels of all entries. */
-    labels(): string[];
-    /**
-     * Serialize this FieldSet to a plain JSON object.
-     * Shape is identified by its IRI, paths by dot-separated labels.
-     */
-    toJSON(): FieldSetJSON;
-    /** Serialize just the field entries (used for nested relation sub-fields). */
-    private toFieldsJSON;
-    private serializeEntry;
-    /** The shape a scoped filter at segment `idx` is evaluated against (the segment's value shape). */
-    private scopedShapeAt;
-    /**
-     * Reconstruct a FieldSet from a JSON object.
-     * Resolves shape IRI via getShapeClass() and paths via walkPropertyPath().
-     */
-    static fromJSON(json: FieldSetJSON): FieldSet;
-    /** Build a FieldSet from a shape + relation-keyed field list (recursion entry). */
-    private static fromFields;
-    /** Parse one field entry (string leaf / computed / relation-keyed) against `shape`. */
-    private static parseField;
-    /** The shape reached at the end of a relation path (its terminal segment's value shape). */
-    private static nestedShapeOf;
-    /**
-     * Resolves any of the accepted shape input types to a NodeShape and optional ShapeClass.
-     * Accepts: ShapeConstructor (class with .shape), NodeShape, or IRI string.
-     */
-    private static resolveShapeInput;
-    /** @deprecated Use resolveShapeInput instead. Kept for fromJSON which only passes NodeShape|string. */
-    private static resolveShape;
-    private static resolveInputs;
-    /**
-     * Trace fields using the full ProxiedPathBuilder proxy (createProxiedPathBuilder).
-     * Handles nested paths, where conditions, aggregations, and sub-selects.
-     */
-    private static traceFieldsWithProxy;
-    /**
-     * Convert a single proxy trace result (QueryBuilderObject, SetSize, or FieldSet sub-select)
-     * into a FieldSetEntry.
-     */
-    private static convertTraceResult;
-    /**
-     * 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: QueryBuilderObjectLike): PropertyShape[];
-    private static shapeById;
-    private static shapeByLabel;
-    private static labelOfId;
-    /**
-     * 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: NodeShape, segments: readonly PropertyShape[]): string;
-    /** Inverse of {@link pathToStringWithCasts}: resolve a dotted path with `as(X)` casts. */
-    static walkPathWithCasts(rootShape: NodeShape, path: string): PropertyPath;
-    /**
-     * 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: any): FieldSet | undefined;
-    /**
-     * Internal factory that bypasses the private constructor for use by static methods.
-     */
-    private static createInternal;
-    /**
-     * Create a FieldSet from raw entries. Used by QueryBuilder to merge preload entries.
-     */
-    static createFromEntries(shape: NodeShape, entries: FieldSetEntry[]): FieldSet;
-    /**
-     * Extract FieldSetEntry[] from a sub-query's traceResponse.
-     * Public alias for use by lightweight sub-select wrappers.
-     */
-    static extractSubSelectEntriesPublic(rootShape: NodeShape, traceResponse: any): FieldSetEntry[];
-    /**
-     * 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.
-     */
-    private static extractSubSelectEntries;
-}
-export {};