@prisma/orm-family-mongo 0.16.0-dev.36

package/dist/field-accessor-DHsAPiW3-BdYCspQC.d.mts

@@ -0,0 +1,588 @@
+import { C as MongoContract, V as MongoModelsMap, a as ExtractMongoTypeMaps, o as InferModelRow, t as AnyMongoTypeMaps, w as MongoContractWithTypeMaps } from "./mongo-value-set-tNn9-pun-dJYx_rVD.mjs";
+import "./index-Cd2zLiU6.mjs";
+import { c as MongoValue } from "./index-wKMm41HC.mjs";
+import { B as MongoFilterExpr, d as MongoAggAccumulator, m as MongoAggExpr, vt as MongoUpdatePipelineStage } from "./query-plan-C0-Yu8hf-DdilEdW6.mjs";
+import "./execution-CKnUiOfm.mjs";
+import { ContractValueObjectDefinitions } from "@prisma/orm-framework/contract/types";
+//#region ../../../2-mongo-family/5-query-builders/query-builder/dist/field-accessor-DHsAPiW3.d.mts
+//#region src/types.d.ts
+interface DocField {
+  readonly codecId: string;
+  readonly nullable: boolean;
+}
+type NumericField = {
+  readonly codecId: 'mongo/double@1';
+  readonly nullable: false;
+};
+type NullableNumericField = {
+  readonly codecId: 'mongo/double@1';
+  readonly nullable: true;
+};
+type StringField = {
+  readonly codecId: 'mongo/string@1';
+  readonly nullable: false;
+};
+type ArrayField = {
+  readonly codecId: 'mongo/array@1';
+  readonly nullable: false;
+};
+type BooleanField = {
+  readonly codecId: 'mongo/bool@1';
+  readonly nullable: false;
+};
+type DateField = {
+  readonly codecId: 'mongo/date@1';
+  readonly nullable: false;
+};
+type NullableDocField = {
+  readonly codecId: string;
+  readonly nullable: true;
+};
+type LiteralValue<F extends DocField> = F extends StringField ? string : F extends NumericField ? number : F extends BooleanField ? boolean : F extends DateField ? Date : unknown;
+type DocShape = Record<string, DocField>;
+type ExtractCodecId<F> = F extends {
+  type: {
+    kind: 'scalar';
+    codecId: infer C;
+  };
+} ? C : F extends {
+  codecId: infer C extends string;
+} ? C : string;
+type ModelToDocShape<TContract extends MongoContract, ModelName extends string & keyof MongoModelsMap<TContract>> = { [K in keyof MongoModelsMap<TContract>[ModelName]['fields'] & string]: {
+  readonly codecId: ExtractCodecId<MongoModelsMap<TContract>[ModelName]['fields'][K]>;
+  readonly nullable: MongoModelsMap<TContract>[ModelName]['fields'][K]['nullable'];
+}; } & ModelOriginBranded<ModelName>;
+/**
+ * Per-field resolver. Walks `Shape`'s string keys, routing
+ * `ModelArrayField` (the lookup marker) through `InferModelRow` and
+ * everything else through the codec-lookup branch.
+ *
+ * Internal helper — public callers should use `ResolveRow`, which adds
+ * the model-origin brand detection on top.
+ */
+type ResolveFields<Shape extends DocShape, CodecTypes extends Record<string, {
+  readonly output: unknown;
+}>, TContract extends MongoContract> = { -readonly [K in keyof Shape & string]: Shape[K] extends ModelArrayField<infer ModelName> ? IsConcreteContract<TContract> extends true ? TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps> ? ModelName extends string & keyof MongoModelsMap<TContract> ? Array<InferModelRow<TContract, ModelName>> : unknown[] : unknown[] : unknown[] : Shape[K]['codecId'] extends keyof CodecTypes ? Shape[K]['nullable'] extends true ? CodecTypes[Shape[K]['codecId']]['output'] | null : CodecTypes[Shape[K]['codecId']]['output'] : unknown; };
+/**
+ * Resolve a `DocShape` to a concrete row object type.
+ *
+ * The optional `TContract` parameter exists so the resolver can:
+ *
+ *  1. Detect the `ModelOriginBrand` on `Shape` — the phantom symbol
+ *     placed by `ModelToDocShape`. When present (and the contract has
+ *     type maps), the row is resolved via `InferModelRow<TC, M>` from
+ *     `@internal/mongo-contract`, which walks scalar / valueObject /
+ *     union field kinds (handling nested value-objects and `many: true`).
+ *     This makes entry-point reads (`q.from('users').build()`) and
+ *     shape-extending stages (`match`, `addFields`) resolve value-object
+ *     fields to their concrete nested types instead of `unknown`.
+ *
+ *  2. Detect the per-field `ModelArrayField<ModelName>` marker produced
+ *     by `lookup()` and resolve it to `Array<InferModelRow<TC, M>>` so
+ *     lookup rows carry the same fully-typed foreign rows.
+ *
+ * When the contract is not threaded through (or lacks the type-map
+ * phantom), both branches fall back to `unknown` / `unknown[]` —
+ * preserving the legacy resolver shape for call sites that do not need
+ * model-row resolution.
+ */
+/**
+ * Flatten an intersection `A & B` into a single object literal so callers
+ * (and `expectTypeOf().toEqualTypeOf<…>()`) see one homogeneous record
+ * rather than the intersection form. Vitest's strict equality check
+ * treats `A & B` as distinct from the structurally-equivalent flat
+ * record, even when assignability is bidirectional, so the
+ * `ResolveRow` brand-positive branch normalises its result through this.
+ */
+type Flatten<T> = T extends (infer U) ? { [K in keyof U]: U[K]; } : never;
+/**
+ * Decide whether to route a brand-positive `ResolveRow` through
+ * `InferModelRow`. The default `MongoContract` (no concrete models)
+ * still satisfies `MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>`
+ * because the phantom key is optional, but `InferModelRow<MongoContract, …>`
+ * collapses to an empty/unknown row. Gate on the presence of the
+ * type-maps phantom: a concrete contract attaches concrete `TestTypeMaps`-
+ * shaped maps, while the default `MongoContract` has no phantom and
+ * `ExtractMongoTypeMaps` resolves to `never`.
+ */
+type IsConcreteContract<TContract> = [ExtractMongoTypeMaps<TContract>] extends [never] ? false : true;
+type ResolveRow<Shape extends DocShape, CodecTypes extends Record<string, {
+  readonly output: unknown;
+}>, TContract extends MongoContract = MongoContract> = Shape extends {
+  readonly [ModelOriginBrand]?: infer ModelName extends string;
+} ? IsConcreteContract<TContract> extends true ? TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps> ? ModelName extends string & keyof MongoModelsMap<TContract> ? Flatten<InferModelRow<TContract, ModelName> & Omit<ResolveFields<Shape, CodecTypes, TContract>, keyof InferModelRow<TContract, ModelName>>> : ResolveFields<Shape, CodecTypes, TContract> : ResolveFields<Shape, CodecTypes, TContract> : ResolveFields<Shape, CodecTypes, TContract> : ResolveFields<Shape, CodecTypes, TContract>;
+interface TypedAggExpr<F extends DocField> {
+  readonly _field: F;
+  readonly node: MongoAggExpr;
+}
+interface TypedAccumulatorExpr<F extends DocField> {
+  readonly _field: F;
+  readonly node: MongoAggAccumulator;
+}
+type ExtractDocShape<T extends Record<string, TypedAggExpr<DocField>>> = { [K in keyof T & string]: T[K]['_field']; };
+type SortSpec<S extends DocShape> = Partial<Record<keyof S & string, 1 | -1>>;
+type ProjectedShape<Shape extends DocShape, Spec extends Record<string, 1 | TypedAggExpr<DocField>>> = { [K in keyof Spec & string]: Spec[K] extends 1 ? K extends keyof Shape ? Shape[K] : DocField : Spec[K] extends TypedAggExpr<infer F> ? F : DocField; } & ('_id' extends keyof Shape ? '_id' extends keyof Spec ? Record<keyof never, never> : Pick<Shape, '_id'> : Record<keyof never, never>);
+type GroupSpec = {
+  _id: TypedAggExpr<DocField> | null;
+  [key: string]: TypedAggExpr<DocField> | TypedAccumulatorExpr<DocField> | null;
+};
+type GroupedDocShape<Spec extends GroupSpec> = { [K in keyof Spec & string]: Spec[K] extends TypedAggExpr<infer F> ? F : Spec[K] extends TypedAccumulatorExpr<infer F> ? F : Spec[K] extends null ? {
+  readonly codecId: 'mongo/null@1';
+  readonly nullable: true;
+} : DocField; };
+/**
+ * Intentionally identity — full array element type extraction is deferred.
+ * Used by `UnwoundShape` so the unwind result shape can be refined later
+ * without changing the public API.
+ */
+type UnwrapArrayDocField<F extends DocField> = F;
+/**
+ * `$unwind` reshapes the array slot but leaves the rest of the document
+ * structurally intact. The mapped iteration is keyed on `keyof S & string`,
+ * which discards the symbol-keyed `ModelOriginBrand` carried by
+ * model-rooted shapes. Preserve the brand explicitly so post-unwind
+ * `ResolveRow` still routes through `InferModelRow` and value-object
+ * fields keep their concrete nested types.
+ */
+type UnwoundShape<S extends DocShape, K extends keyof S & string> = { [P in keyof S & string]: P extends K ? UnwrapArrayDocField<S[P]> : S[P]; } & (S extends ModelOriginBranded<infer ModelName extends string> ? ModelOriginBranded<ModelName> : unknown);
+//#endregion
+//#region src/resolve-path.d.ts
+/**
+ * Marker `DocField` variant representing a non-leaf (value-object) path in
+ * a [NestedDocShape]. Extends `DocField` with a `fields` property carrying
+ * the sub-shape so the pipeline builder can recurse into it.
+ *
+ * `codecId` is the reserved literal `'prisma/object@1'`; the accessor's
+ * runtime implementation does not serialize it — the codec id is a purely
+ * type-level sentinel used by `Expression<F>` to select the reduced
+ * operator surface for non-leaf paths.
+ *
+ * `nullable` tracks whether the value object itself may be absent/null on
+ * the parent document. The callable form currently does not propagate the
+ * parent's `nullable` flag onto leaves beneath it (path traversal under a
+ * nullable parent resolves to the leaf's own `nullable` — matching how
+ * MongoDB treats missing intermediate documents).
+ */
+interface ObjectField<N extends NestedDocShape> extends DocField {
+  readonly codecId: 'prisma/object@1';
+  readonly nullable: boolean;
+  readonly fields: N;
+}
+/**
+ * Marker `DocField` variant representing "an array of foreign-model rows"
+ * — the result of a `$lookup` whose foreign side was selected via the
+ * typed `col` accessor. `ModelName` is the literal foreign model name
+ * (e.g. `'User'`), preserved in the type so `ResolveRow` can resolve the
+ * field to `ResolveRow<ModelToDocShape<TC, ModelName>, …>[]` rather than
+ * the opaque `unknown[]` produced by the legacy `mongo/array@1` sentinel.
+ *
+ * Like `ObjectField`, the codec id is a purely type-level sentinel —
+ * there is no runtime codec entry for `'prisma/modelArray@1'`. The
+ * surrounding pipeline emits the standard `MongoLookupStage` whose
+ * runtime shape is unchanged; the marker exists solely to thread the
+ * foreign element type through the result-row resolver.
+ */
+interface ModelArrayField<ModelName extends string> extends DocField {
+  readonly codecId: 'prisma/modelArray@1';
+  readonly nullable: false;
+  readonly model: ModelName;
+}
+/**
+ * Phantom-symbol brand placed on `ModelToDocShape`'s output (and inherited
+ * through shape-extending stages like `addFields`, `match`, `lookup`) so
+ * `ResolveRow` can route value-object resolution through `InferModelRow`
+ * — which walks the contract's `valueObjects` registry and resolves
+ * nested types — instead of falling through the codec-lookup branch to
+ * `unknown`.
+ *
+ * The brand is keyed on a `unique symbol` rather than a string so it is
+ * invisible to every `keyof Shape & string` walk in the package
+ * (`SortSpec`, `ProjectedShape`, `GroupedDocShape`, the field accessor's
+ * `Object.keys` iteration, etc.). Field accessors do not surface a
+ * `__modelOrigin` autocomplete entry; sorts cannot key on it; projections
+ * cannot reference it.
+ *
+ * Shape-extending stages preserve the brand because intersection types
+ * (`Shape & NewFields`) carry through symbol-keyed properties. Shape-
+ * replacing stages (`replaceRoot`, `group`, `project`) construct fresh
+ * `DocShape`s from scratch, naturally dropping the brand — which is the
+ * intended behaviour, since those stages legitimately leave model
+ * territory.
+ */
+declare const ModelOriginBrand: unique symbol;
+type ModelOriginBrand = typeof ModelOriginBrand;
+/**
+ * Brand carrier — a Shape whose row type should be resolved via
+ * `InferModelRow<TContract, ModelName>` rather than the per-field codec
+ * walk. Use as `ModelToDocShape<TC, ModelName> & ModelOriginBranded<ModelName>`.
+ */
+type ModelOriginBranded<ModelName extends string> = {
+  readonly [ModelOriginBrand]?: ModelName;
+};
+/**
+ * Document shape that carries nested value-object sub-shapes.
+ *
+ * Structurally identical to a flat `DocShape` (`Record<string, DocField>`),
+ * but individual values may be `ObjectField<SubShape>` carrying a nested
+ * `NestedDocShape` sub-tree. The pipeline builder threads a
+ * `NestedDocShape` alongside the flat `DocShape` so the callable
+ * `f('a.b.c')` form can validate dot-paths at the type level.
+ *
+ * When a stage transforms the root shape in a way that invalidates nested
+ * paths (e.g. `$group`, `$project`, `$replaceRoot`), the thread is reset
+ * to the empty shape `Record<string, never>` — which makes `ValidPaths`
+ * resolve to `never` and so disables the callable form downstream.
+ */
+type NestedDocShape = Record<string, DocField>;
+type FieldToLeaf<F> = F extends {
+  readonly type: {
+    readonly kind: 'scalar';
+    readonly codecId: infer C extends string;
+  };
+  readonly nullable: infer N extends boolean;
+} ? {
+  readonly codecId: C;
+  readonly nullable: N;
+} : F extends {
+  readonly many: true;
+  readonly nullable: infer N extends boolean;
+} ? {
+  readonly codecId: 'mongo/array@1';
+  readonly nullable: N;
+} : DocField;
+/**
+ * Translate a single contract field to its nested-shape form. Scalars
+ * become `DocField` leaves; value-object fields become
+ * `ObjectField<Sub>`; `many: true` stops at a leaf; anything else falls
+ * through to the opaque `DocField` base.
+ *
+ * Kept as a per-field helper (rather than a `Fields → NestedShape` helper
+ * that maps over keys internally) so the parent mapped type stays
+ * homomorphic over the model/value-object `fields` record. Homomorphic
+ * mapped types preserve the literal keys of their source object through
+ * TypeScript's intersection-collapsing machinery, which keeps
+ * `ModelNestedShape` hover output and `keyof`/indexed-access resolution
+ * concrete instead of collapsing to `{ [x: string]: … }`.
+ */
+type TranslateField<TContract extends MongoContract, F> = F extends {
+  readonly many: true;
+} ? FieldToLeaf<F> : F extends {
+  readonly type: {
+    readonly kind: 'valueObject';
+    readonly name: infer VOName extends string;
+  };
+  readonly nullable: infer Null extends boolean;
+} ? ObjectField<VONestedShape<TContract, VOName>> & {
+  readonly nullable: Null;
+} : F extends {
+  readonly type: {
+    readonly kind: 'scalar';
+    readonly codecId: string;
+  };
+} ? FieldToLeaf<F> : DocField;
+/**
+ * Resolve a named value object from the contract into its own
+ * `NestedDocShape`. The mapped iteration is inlined here (not delegated
+ * to a generic helper) so that the homomorphism over
+ * `VOs[VOName]['fields']` is preserved and the hover / indexed-access
+ * surface stays concrete at instantiation time.
+ */
+type VONestedShape<TContract extends MongoContract, VOName extends string> = [ContractValueObjectDefinitions<TContract>] extends [infer VOs extends Record<string, {
+  readonly fields: Record<string, unknown>;
+}>] ? VOName extends keyof VOs & string ? { readonly [K in keyof VOs[VOName]['fields'] & string]: TranslateField<TContract, VOs[VOName]['fields'][K]>; } : never : never;
+/**
+ * Build the `NestedDocShape` for a model. Scalar leaves resolve to their
+ * concrete codec id; value-object fields recurse into the referenced
+ * `valueObjects[VOName].fields` table, producing a tree that
+ * `ResolvePath` / `ValidPaths` can walk.
+ *
+ * The mapped iteration is inlined (not hidden behind a helper type that
+ * takes `Fields` as a generic) so TypeScript recognises the mapped type
+ * as homomorphic over `MongoModelsMap<TContract>[ModelName]['fields']`. That
+ * preserves the literal field-name keys at instantiation — without this,
+ * the intersection of `Record<string, ContractField>` and the specific
+ * literal field record collapses `keyof` to `string` and the result hover
+ * degrades to `{ readonly [x: string]: any }`.
+ */
+type ModelNestedShape<TContract extends MongoContract, ModelName extends string & keyof MongoModelsMap<TContract>> = { readonly [K in keyof MongoModelsMap<TContract>[ModelName]['fields'] & string]: TranslateField<TContract, MongoModelsMap<TContract>[ModelName]['fields'][K]>; };
+/**
+ * Resolve a dot-path against a `NestedDocShape`. Returns:
+ *  - the leaf `DocField` when `Path` terminates on a scalar/array leaf,
+ *  - the `ObjectField<Sub>` when `Path` terminates on a value object (so
+ *    the caller can operate on the whole sub-document),
+ *  - `never` when the path is invalid (unknown segment, or a scalar
+ *    segment followed by further traversal).
+ *
+ * Paired with the constrained callable `<P extends ValidPaths<N>>(path: P)
+ * => Expression<ResolvePath<N, P>>` so the IDE offers completions and
+ * rejects bad paths with a clear error instead of silently resolving to
+ * `never`.
+ */
+type ResolvePath<N extends NestedDocShape, Path extends string> = Path extends `${infer Head}.${infer Rest}` ? Head extends keyof N & string ? N[Head] extends ObjectField<infer Sub> ? ResolvePath<Sub, Rest> : never : never : Path extends keyof N & string ? N[Path] : never;
+/**
+ * Union of every valid dot-path within a `NestedDocShape`. Includes
+ * top-level keys (scalar leaves *and* value-object roots) and every
+ * recursive descent through `ObjectField` sub-shapes.
+ *
+ * Non-leaf paths are intentionally included — `f('address')` yields an
+ * `Expression<ObjectField<…>>` whose reduced operator surface (`set`,
+ * `unset`, `exists`, `eq(null)`, `ne(null)`) lets callers operate on the
+ * whole value object. Leaf paths like `f('address.city')` get the full
+ * leaf operator surface.
+ *
+ * The `string extends keyof N` guard short-circuits to `never` for
+ * open-ended index-signature shapes (e.g. the default
+ * `Record<string, never>` used to represent "no nested information" —
+ * notably downstream of replacement stages in the pipeline builder). An
+ * open-ended `keyof` cannot resolve a specific literal path, so the
+ * callable form must be disabled at the type level.
+ */
+type ValidPaths<N extends NestedDocShape> = string extends keyof N ? never : { [K in keyof N & string]: N[K] extends ObjectField<infer Sub> ? K | `${K}.${ValidPaths<Sub>}` : K; }[keyof N & string];
+/**
+ * IDE-oriented alias for `ValidPaths`. Kept as a separate export so future
+ * refinements (e.g. ArkType-style lazy expansion for very deep shapes) can
+ * diverge from the strict `ValidPaths` constraint without breaking
+ * downstream consumers. For now the two are intentionally equivalent.
+ */
+type PathCompletions<N extends NestedDocShape> = ValidPaths<N>;
+//#endregion
+//#region src/update-ops.d.ts
+/**
+ * Per-field update operations produced by `Expression`'s update methods
+ * (`set`, `inc`, `push`, …). A write terminal folds an array of these into a
+ * `MongoUpdateSpec` record (`{ $set: { … }, $inc: { … }, … }`) before
+ * constructing the underlying `UpdateManyCommand` / `UpdateOneCommand` AST node.
+ *
+ * One `TypedUpdateOp` value corresponds to one Mongo update operator applied
+ * to one field path. The `op` string is the wire-level operator name (`$set`,
+ * `$inc`, …); the `path` is the dot-path to the field (or its top-level name).
+ */
+type TypedUpdateOp = {
+  readonly op: '$set';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$unset';
+  readonly path: string;
+} | {
+  readonly op: '$rename';
+  readonly path: string;
+  readonly newName: string;
+} | {
+  readonly op: '$inc';
+  readonly path: string;
+  readonly amount: number;
+} | {
+  readonly op: '$mul';
+  readonly path: string;
+  readonly factor: number;
+} | {
+  readonly op: '$min';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$max';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$push';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$addToSet';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$pop';
+  readonly path: string;
+  readonly direction: 1 | -1;
+} | {
+  readonly op: '$pull';
+  readonly path: string;
+  readonly value: MongoValue;
+} | {
+  readonly op: '$pullAll';
+  readonly path: string;
+  readonly values: ReadonlyArray<MongoValue>;
+} | {
+  readonly op: '$currentDate';
+  readonly path: string;
+} | {
+  readonly op: '$setOnInsert';
+  readonly path: string;
+  readonly value: MongoValue;
+};
+/**
+ * The return type for updater callbacks. Typed as a union of homogeneous
+ * arrays so mixed-shape updaters (operator + pipeline stage in the same
+ * array) are a compile error. The runtime guard in `resolveUpdaterResult`
+ * remains as defence-in-depth.
+ */
+type UpdaterResult = ReadonlyArray<TypedUpdateOp> | ReadonlyArray<MongoUpdatePipelineStage>;
+//#endregion
+//#region src/field-accessor.d.ts
+/**
+ * Operator surface for leaf (scalar) paths — today's full set: filter,
+ * update, and aggregation operators. Returned by `Expression<F>` for any
+ * `F extends DocField` that is not an `ObjectField<…>` sub-tree.
+ *
+ * Operator surfaces are intentionally not trait-gated by codec in this
+ * revision — tracked on Linear as TML-2259 (scope extended to cover the
+ * query-builder's `Expression<F>`). Calling, e.g. `.inc(1)` on a
+ * string-typed expression compiles; the runtime relies on Mongo to
+ * surface the error. Trait-gating can be tightened in a follow-up
+ * without changing the accessor's public shape.
+ */
+interface LeafExpression<F extends DocField> extends TypedAggExpr<F> {
+  readonly _path: string;
+  eq(value: MongoValue): MongoFilterExpr;
+  ne(value: MongoValue): MongoFilterExpr;
+  gt(value: MongoValue): MongoFilterExpr;
+  gte(value: MongoValue): MongoFilterExpr;
+  lt(value: MongoValue): MongoFilterExpr;
+  lte(value: MongoValue): MongoFilterExpr;
+  in(values: ReadonlyArray<MongoValue>): MongoFilterExpr;
+  nin(values: ReadonlyArray<MongoValue>): MongoFilterExpr;
+  exists(flag?: boolean): MongoFilterExpr;
+  /**
+   * `$type` filter: `{ field: { $type: bsonType } }`. Rides
+   * `MongoFieldFilter`'s generic `op` string — no dedicated AST node. The
+   * BSON type is expressed as Mongo's alias string (e.g. `'string'`) or
+   * numeric type code; an array selects any of several types.
+   */
+  type(bsonType: MongoValue): MongoFilterExpr;
+  set(value: MongoValue): TypedUpdateOp;
+  unset(): TypedUpdateOp;
+  rename(newName: string): TypedUpdateOp;
+  inc(amount: number): TypedUpdateOp;
+  mul(factor: number): TypedUpdateOp;
+  min(value: MongoValue): TypedUpdateOp;
+  max(value: MongoValue): TypedUpdateOp;
+  push(value: MongoValue): TypedUpdateOp;
+  addToSet(value: MongoValue): TypedUpdateOp;
+  pop(direction?: 1 | -1): TypedUpdateOp;
+  pull(value: MongoValue): TypedUpdateOp;
+  pullAll(values: ReadonlyArray<MongoValue>): TypedUpdateOp;
+  currentDate(): TypedUpdateOp;
+  setOnInsert(value: MongoValue): TypedUpdateOp;
+}
+/**
+ * Operator surface for non-leaf (value-object) paths — `f('address')`
+ * when `address` is a `ContractValueObject`. Intentionally minimal: the
+ * whole-value ops that make sense on a structured sub-document
+ * (`set`/`unset`/`exists`, null presence via `eq(null)`/`ne(null)`). Field-
+ * level ops belong on the constituent leaves (`f('address.city')`).
+ *
+ * The aggregation `node` is still present (`TypedAggExpr<ObjectField<N>>`)
+ * so the value object can be piped through `$addFields` /
+ * `$replaceRoot` / etc. as-is.
+ */
+interface ObjectExpression<N extends NestedDocShape> extends TypedAggExpr<ObjectField<N>> {
+  readonly _path: string;
+  exists(flag?: boolean): MongoFilterExpr;
+  eq(value: null): MongoFilterExpr;
+  ne(value: null): MongoFilterExpr;
+  set(value: MongoValue): TypedUpdateOp;
+  unset(): TypedUpdateOp;
+}
+/**
+ * The unified field accessor expression returned by `FieldAccessor` (per
+ * [ADR 180](../../../../docs/architecture%20docs/adrs/ADR%20180%20-%20Dot-path%20field%20accessor.md)).
+ *
+ * Resolves to `ObjectExpression<Sub>` when `F` is an `ObjectField<Sub>`
+ * (non-leaf path), otherwise to `LeafExpression<F>` (the full operator
+ * surface). The conditional is driven off the `fields` marker that
+ * `ObjectField` adds to `DocField`, so existing code that uses plain
+ * `DocField` shapes continues to resolve to `LeafExpression`.
+ */
+type Expression<F extends DocField> = F extends ObjectField<infer N> ? ObjectExpression<N> : LeafExpression<F>;
+/**
+ * Emitters for MongoDB update-pipeline stages (`$addFields`/`$set`,
+ * `$project`/`$unset`, `$replaceRoot`/`$replaceWith`). These return
+ * `MongoUpdatePipelineStage` nodes and let an updater callback express
+ * the pipeline-form update as an alternative to the typed-operator form.
+ *
+ * The two forms are mutually exclusive per updater call: `resolveUpdaterResult`
+ * rejects arrays that mix `TypedUpdateOp` and `MongoUpdatePipelineStage`
+ * entries with a clear error — an updater callback must return either all
+ * typed ops or all pipeline stages. Pick the form that matches the update
+ * you want and commit to it for that call site.
+ *
+ * Accessible via `f.stage` on the `FieldAccessor`.
+ */
+interface StageEmitters {
+  set(fields: Record<string, MongoAggExpr>): MongoUpdatePipelineStage;
+  unset(...paths: ReadonlyArray<string>): MongoUpdatePipelineStage;
+  replaceRoot(newRoot: MongoAggExpr): MongoUpdatePipelineStage;
+  replaceWith(newRoot: MongoAggExpr): MongoUpdatePipelineStage;
+}
+/**
+ * The unified `FieldAccessor` per ADR 180.
+ *
+ * - Property access (`f.status`) returns an `Expression<F>` whose codec
+ *   comes from the current pipeline shape `S`.
+ * - Callable form (`f('address.city')`) returns an `Expression<ResolvePath<N, P>>`
+ *   where `N` is the nested shape carrying value-object sub-shapes.
+ *   Paths that don't exist in `N` are rejected with a compile-time error
+ *   (via `P extends ValidPaths<N>`). Non-leaf paths like `f('address')`
+ *   resolve to an `ObjectExpression` whose reduced surface covers the
+ *   whole-value operations (`set`, `unset`, `exists`, `eq(null)`,
+ *   `ne(null)`).
+ * - `f.rawPath('path')` is a deliberate escape hatch that skips path
+ *   validation and returns a `LeafExpression<F>` for the given string.
+ *   Intended for migration authoring where the target field is not yet
+ *   part of the typed contract (e.g. a backfill writing a newly-added
+ *   column before the contract hash rolls forward). The method name is
+ *   deliberately `rawPath` rather than `raw` so it does not shadow a
+ *   legitimate top-level `raw` field on a user model.
+ * - `f.stage` exposes pipeline-style update emitters (`$set`, `$unset`,
+ *   `$replaceRoot`, `$replaceWith`).
+ *
+ * When `N` is `Record<string, never>` (the default — e.g. after a
+ * replacement stage like `$group` / `$project` / `$replaceRoot`),
+ * `ValidPaths<N>` is `never` and the callable form is effectively
+ * disabled at the type level. This keeps the builder sound downstream of
+ * stages that invalidate the original document's nested-path tree.
+ * `f.rawPath(...)` remains available in that state for callers that need
+ * an explicit unvalidated path.
+ */
+type FieldAccessor<S extends DocShape, N extends NestedDocShape = Record<string, never>> = { readonly [K in keyof S & string]: Expression<S[K]>; } & (<P extends ValidPaths<N>>(path: P) => Expression<ResolvePath<N, P>>) & {
+  readonly stage: StageEmitters;
+  /**
+   * Escape hatch: build a `LeafExpression<F>` for an unvalidated string
+   * path. Use only when the path is intentionally outside the typed
+   * model surface — data-migration authoring is the canonical case
+   * (e.g. backfilling a field that is not yet in the contract). Default
+   * `F` is the opaque `DocField`; callers can narrow via the explicit
+   * generic: `f.rawPath<StringField>("status").set("active")`.
+   *
+   * The method is named `rawPath` (not `raw`) so a user model with a
+   * top-level `raw` field still resolves `f.raw` to the field-expression
+   * property, not to this escape hatch. Does not participate in
+   * `ValidPaths<N>` / `ResolvePath<N, P>` — the path is passed through
+   * verbatim and no IDE autocomplete is offered.
+   */
+  rawPath<F extends DocField = DocField>(path: string): LeafExpression<F>;
+};
+/**
+ * Wrap a boolean aggregation expression as an `$expr` filter
+ * (`MongoExprFilter`). Lets a `$match` express an aggregation-expression
+ * predicate — e.g. comparing two field references via `fn.eq(a, b)` — in
+ * the typed AST rather than via a raw escape hatch. Pairs with `.type()`
+ * to express filters like `{ _id: { $type: 'string' }, $expr: { $eq: ['$_id', '$space'] } }`.
+ */
+declare function expr(predicate: TypedAggExpr<DocField>): MongoFilterExpr;
+/**
+ * Construct a unified `FieldAccessor<S, N>` proxy. Property access creates
+ * an `Expression` using the property name as the field path; callable
+ * form accepts a dot-path string validated against `N` at compile time.
+ *
+ * The proxy target is a function so the resulting object is both callable
+ * and indexable. Symbol-keyed accesses (e.g. `Symbol.toPrimitive`) return
+ * `undefined` to keep accidental coercion behaviour unsurprising —
+ * matching the previous `FieldProxy` / `FilterProxy` semantics.
+ */
+declare function createFieldAccessor<S extends DocShape, N extends NestedDocShape = Record<string, never>>(): FieldAccessor<S, N>;
+//#endregion
+export { TypedUpdateOp as A, ProjectedShape as C, StringField as D, SortSpec as E, expr as F, UpdaterResult as M, ValidPaths as N, TypedAccumulatorExpr as O, createFieldAccessor as P, PathCompletions as S, ResolveRow as T, NullableDocField as _, DocShape as a, ObjectExpression as b, FieldAccessor as c, LeafExpression as d, LiteralValue as f, NestedDocShape as g, ModelToDocShape as h, DocField as i, UnwoundShape as j, TypedAggExpr as k, GroupSpec as l, ModelNestedShape as m, BooleanField as n, Expression as o, ModelArrayField as p, DateField as r, ExtractDocShape as s, ArrayField as t, GroupedDocShape as u, NullableNumericField as v, ResolvePath as w, ObjectField as x, NumericField as y };
+//# sourceMappingURL=field-accessor-DHsAPiW3-BdYCspQC.d.mts.map

package/dist/field-accessor-DHsAPiW3-BdYCspQC.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-accessor-DHsAPiW3-BdYCspQC.d.mts","names":[],"sources":["../../../../2-mongo-family/5-query-builders/query-builder/dist/field-accessor-DHsAPiW3.d.mts"],"mappings":";;;;;;;;UAKU;WACC;WACA;;KAEN;WACM;WACA;;KAEN;WACM;WACA;;KAEN;WACM;WACA;;KAEN;WACM;WACA;;KAEN;WACM;WACA;;KAEN;WACM;WACA;;KAEN;WACM;WACA;;KAEN,aAAa,UAAU,YAAY,UAAU,uBAAuB,UAAU,wBAAwB,UAAU,yBAAyB,UAAU,YAAY;KAC/J,WAAW,eAAe;KAC1B,eAAe,KAAK;EACvB;IACE;IACA,eAAe;;IAEf,IAAI;EACN,eAAe;IACb;KACC,gBAAgB,kBAAkB,eAAe,iCAAiC,eAAe,iBAAiB,WAAW,eAAe,WAAW;WACjJ,SAAS,eAAe,eAAe,WAAW,qBAAqB;WACvE,UAAU,eAAe,WAAW,qBAAqB;OAC7D,mBAAmB;;;;;;;;;KASrB,cAAc,cAAc,UAAU,mBAAmB;WACnD;IACP,kBAAkB,8BAA8B,WAAW,iBAAiB,MAAM,WAAW,sBAAsB,aAAa,mBAAmB,0BAA0B,kBAAkB,0BAA0B,eAAe,oBAAoB,iCAAiC,eAAe,aAAa,MAAM,cAAc,WAAW,kDAAkD,MAAM,4BAA4B,aAAa,MAAM,8BAA8B,WAAW,MAAM,kCAAkC,WAAW,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgChiB,QAAQ,KAAK,iBAAiB,QAAQ,WAAW,IAAI,EAAE;;;;;;;;;;;KAWvD,mBAAmB,cAAc,qBAAqB;KACtD,WAAW,cAAc,UAAU,mBAAmB;WAChD;IACP,kBAAkB,gBAAgB,iBAAiB;YAC3C,0BAA0B;IAClC,mBAAmB,0BAA0B,kBAAkB,0BAA0B,eAAe,oBAAoB,iCAAiC,eAAe,aAAa,QAAQ,cAAc,WAAW,aAAa,KAAK,cAAc,OAAO,YAAY,kBAAkB,cAAc,WAAW,eAAe,cAAc,OAAO,YAAY,aAAa,cAAc,OAAO,YAAY,aAAa,cAAc,OAAO,YAAY,aAAa,cAAc,OAAO,YAAY;UAC5e,aAAa,UAAU;WACtB,QAAQ;WACR,MAAM;;UAEP,qBAAqB,UAAU;WAC9B,QAAQ;WACR,MAAM;;KAEZ,gBAAgB,UAAU,eAAe,aAAa,iBAAiB,WAAW,aAAa,EAAE;KACjG,SAAS,UAAU,YAAY,QAAQ,aAAa;KACpD,eAAe,cAAc,UAAU,aAAa,mBAAmB,aAAa,iBAAiB,WAAW,gBAAgB,KAAK,eAAe,gBAAgB,QAAQ,MAAM,KAAK,WAAW,KAAK,WAAW,mBAAmB,KAAK,IAAI,mCAAmC,4BAA4B,OAAO,6BAA6B,KAAK,gBAAgB;KACtW;EACH,KAAK,aAAa;GACjB,cAAc,aAAa,YAAY,qBAAqB;;KAE1D,gBAAgB,aAAa,gBAAgB,WAAW,gBAAgB,KAAK,WAAW,mBAAmB,KAAK,IAAI,KAAK,WAAW,2BAA2B,KAAK,IAAI,KAAK;WACvK;WACA;IACP;;;;;;KAMC,oBAAoB,UAAU,YAAY;;;;;;;;;KAS1C,aAAa,UAAU,UAAU,gBAAgB,iBAAiB,WAAW,aAAa,UAAU,IAAI,oBAAoB,EAAE,MAAM,EAAE,SAAS,UAAU,yBAAyB,4BAA4B,mBAAmB;;;;;;;;;;;;;;;;;;;UAmB5N,YAAY,UAAU,wBAAwB;WAC7C;WACA;WACA,QAAQ;;;;;;;;;;;;;;;;UAgBT,gBAAgB,kCAAkC;WACjD;WACA;WACA,OAAO;;;;;;;;;;;;;;;;;;;;;;;;cAwBJ;KACT,0BAA0B;;;;;;KAM1B,mBAAmB;YACZ,oBAAoB;;;;;;;;;;;;;;;;KAgB3B,iBAAiB,eAAe;KAChC,YAAY,KAAK;WACX;aACE;aACA,eAAe;;WAEjB,gBAAgB;;WAEhB,SAAS;WACT,UAAU;IACjB;WACO;WACA,gBAAgB;;WAEhB;WACA,UAAU;IACjB;;;;;;;;;;;;;;;KAeC,eAAe,kBAAkB,eAAe,KAAK;WAC/C;IACP,YAAY,KAAK;WACV;aACE;aACA,YAAY;;WAEd,gBAAgB;IACvB,YAAY,cAAc,WAAW;WAC9B,UAAU;IACjB;WACO;aACE;aACA;;IAET,YAAY,KAAK;;;;;;;;KAQhB,cAAc,kBAAkB,eAAe,0BAA0B,+BAA+B,2BAA2B,YAAY;WACzI,QAAQ;MACb,qBAAqB,2BAA2B,WAAW,IAAI,6BAA6B,eAAe,WAAW,IAAI,kBAAkB;;;;;;;;;;;;;;;KAe7I,iBAAiB,kBAAkB,eAAe,iCAAiC,eAAe,0BAA0B,WAAW,eAAe,WAAW,gCAAgC,eAAe,WAAW,eAAe,WAAW,qBAAqB;;;;;;;;;;;;;;KAc1Q,YAAY,UAAU,gBAAgB,uBAAuB,sBAAsB,cAAc,SAAS,mBAAmB,aAAa,EAAE,cAAc,kBAAkB,OAAO,YAAY,KAAK,wBAAwB,mBAAmB,aAAa,EAAE;;;;;;;;;;;;;;;;;;;KAmB9P,WAAW,UAAU,uCAAuC,eAAe,WAAW,aAAa,EAAE,WAAW,kBAAkB,OAAO,OAAO,KAAK,WAAW,SAAS,WAAW;;;;;;;KAOpL,gBAAgB,UAAU,kBAAkB,WAAW;;;;;;;;;;;;;KAavD;WACM;WACA;WACA,OAAO;;WAEP;WACA;;WAEA;WACA;WACA;;WAEA;WACA;WACA;;WAEA;WACA;WACA;;WAEA;WACA;WACA,OAAO;;WAEP;WACA;WACA,OAAO;;WAEP;WACA;WACA,OAAO;;WAEP;WACA;WACA,OAAO;;WAEP;WACA;WACA;;WAEA;WACA;WACA,OAAO;;WAEP;WACA;WACA,QAAQ,cAAc;;WAEtB;WACA;;WAEA;WACA;WACA,OAAO;;;;;;;;KAQb,gBAAgB,cAAc,iBAAiB,cAAc;;;;;;;;;;;;;;;UAexD,eAAe,UAAU,kBAAkB,aAAa;WACvD;EACT,GAAG,OAAO,aAAa;EACvB,GAAG,OAAO,aAAa;EACvB,GAAG,OAAO,aAAa;EACvB,IAAI,OAAO,aAAa;EACxB,GAAG,OAAO,aAAa;EACvB,IAAI,OAAO,aAAa;EACxB,GAAG,QAAQ,cAAc,cAAc;EACvC,IAAI,QAAQ,cAAc,cAAc;EACxC,OAAO,iBAAiB;;;;;;;EAOxB,KAAK,UAAU,aAAa;EAC5B,IAAI,OAAO,aAAa;EACxB,SAAS;EACT,OAAO,kBAAkB;EACzB,IAAI,iBAAiB;EACrB,IAAI,iBAAiB;EACrB,IAAI,OAAO,aAAa;EACxB,IAAI,OAAO,aAAa;EACxB,KAAK,OAAO,aAAa;EACzB,SAAS,OAAO,aAAa;EAC7B,IAAI,qBAAqB;EACzB,KAAK,OAAO,aAAa;EACzB,QAAQ,QAAQ,cAAc,cAAc;EAC5C,eAAe;EACf,YAAY,OAAO,aAAa;;;;;;;;;;;;;UAaxB,iBAAiB,UAAU,wBAAwB,aAAa,YAAY;WAC3E;EACT,OAAO,iBAAiB;EACxB,GAAG,cAAc;EACjB,GAAG,cAAc;EACjB,IAAI,OAAO,aAAa;EACxB,SAAS;;;;;;;;;;;;KAYN,WAAW,UAAU,YAAY,UAAU,kBAAkB,KAAK,iBAAiB,KAAK,eAAe;;;;;;;;;;;;;;;UAelG;EACR,IAAI,QAAQ,eAAe,gBAAgB;EAC3C,SAAS,OAAO,wBAAwB;EACxC,YAAY,SAAS,eAAe;EACpC,YAAY,SAAS,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgCjC,cAAc,UAAU,UAAU,UAAU,iBAAiB,qCAAqC,WAAW,aAAa,WAAW,EAAE,WAAW,UAAU,WAAW,IAAI,MAAM,MAAM,WAAW,YAAY,GAAG;WAC3M,OAAO;;;;;;;;;;;;;;;EAehB,QAAQ,UAAU,WAAW,UAAU,eAAe,eAAe;;;;;;;;;iBAStD,KAAK,WAAW,aAAa,YAAY;;;;;;;;;;;iBAWzC,oBAAoB,UAAU,UAAU,UAAU,iBAAiB,0BAA0B,cAAc,GAAG"}