@prisma/orm-family-mongo 8.0.0-rc.24-dev.12 → 8.0.0-rc.24-dev.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/dist/{control-BNH5e5av.d.mts → control-C60vKgXR.d.mts} +2 -2
  2. package/dist/{control-BNH5e5av.d.mts.map → control-C60vKgXR.d.mts.map} +1 -1
  3. package/dist/{control-Cxe4huYd.d.mts → control-CwUH60Zs.d.mts} +4 -4
  4. package/dist/{control-Cxe4huYd.d.mts.map → control-CwUH60Zs.d.mts.map} +1 -1
  5. package/dist/{control-adapter-BheElqfe-Z1rEl51r.d.mts → control-adapter-BheElqfe-DvKx2xNu.d.mts} +3 -3
  6. package/dist/{control-adapter-BheElqfe-Z1rEl51r.d.mts.map → control-adapter-BheElqfe-DvKx2xNu.d.mts.map} +1 -1
  7. package/dist/control-adapter-CsdEt84L.d.mts +1 -0
  8. package/dist/{execution-CD6EeX3b.d.mts → execution-BaB-jj-9.d.mts} +2 -2
  9. package/dist/{execution-CD6EeX3b.d.mts.map → execution-BaB-jj-9.d.mts.map} +1 -1
  10. package/dist/family.d.mts +4 -4
  11. package/dist/family__control-adapter.d.mts +2 -2
  12. package/dist/family__control.d.mts +1 -1
  13. package/dist/family__migration.d.mts +1 -1
  14. package/dist/{field-accessor-DJzCZm0f-ZGjGQy0_.d.mts → field-accessor-DJzCZm0f-BErO0512.d.mts} +3 -3
  15. package/dist/{field-accessor-DJzCZm0f-ZGjGQy0_.d.mts.map → field-accessor-DJzCZm0f-BErO0512.d.mts.map} +1 -1
  16. package/dist/index-Bzkio7As.d.mts +849 -0
  17. package/dist/index-Bzkio7As.d.mts.map +1 -0
  18. package/dist/{index-B2yjvk4C.d.mts → index-C4SE1De2.d.mts} +3 -3
  19. package/dist/{index-B2yjvk4C.d.mts.map → index-C4SE1De2.d.mts.map} +1 -1
  20. package/dist/{index-By9G6gWh.d.mts → index-DoC4WknJ.d.mts} +5 -5
  21. package/dist/{index-By9G6gWh.d.mts.map → index-DoC4WknJ.d.mts.map} +1 -1
  22. package/dist/lowering.d.mts +1 -1
  23. package/dist/{migration-B7PcbeNg.d.mts → migration-C6-3qUP0.d.mts} +2 -2
  24. package/dist/{migration-B7PcbeNg.d.mts.map → migration-C6-3qUP0.d.mts.map} +1 -1
  25. package/dist/orm.d.mts +36 -12
  26. package/dist/orm.d.mts.map +1 -1
  27. package/dist/orm.mjs +201 -23
  28. package/dist/orm.mjs.map +1 -1
  29. package/dist/query-ast.d.mts +4 -4
  30. package/dist/query-ast__control.d.mts +2 -2
  31. package/dist/query-ast__execution.d.mts +3 -3
  32. package/dist/query-builder.d.mts +4 -849
  33. package/dist/query-builder__contract-free.d.mts +4 -4
  34. package/dist/{query-plan-Dtyaa2z2-BD60dwyV.d.mts → query-plan-k7nXo4F_-C07yAGNa.d.mts} +9 -4
  35. package/dist/{query-plan-Dtyaa2z2-BD60dwyV.d.mts.map → query-plan-k7nXo4F_-C07yAGNa.d.mts.map} +1 -1
  36. package/dist/runtime.d.mts +12 -15
  37. package/dist/runtime.d.mts.map +1 -1
  38. package/dist/wire.d.mts +2 -2
  39. package/package.json +20 -20
  40. package/dist/control-adapter-Cj8JmiQV.d.mts +0 -1
  41. package/dist/query-builder.d.mts.map +0 -1
@@ -0,0 +1,849 @@
1
+ import { E as MongoContractWithTypeMaps, H as MongoModelStorage, T as MongoContract, U as MongoModelsMap, dt as RootModelName, n as ExtractMongoCodecTypes, t as AnyMongoTypeMaps } from "./mongo-value-set-ChzpEiPK-BVtp7f-a.mjs";
2
+ import "./index-BHEoA-q8.mjs";
3
+ import { d as MongoPreparedParamRef, p as MongoValue } from "./index-Cvd8czxA.mjs";
4
+ import { B as MongoFilterExpr, L as MongoFieldShape, Nt as UpdateManyCommand, Pt as UpdateOneCommand, R as MongoFillOutput, St as MongoWindowField, a as DeleteOneCommand, c as InsertManyCommand, d as MongoAggAccumulator, et as MongoPipelineStage, i as DeleteManyCommand, it as MongoQueryPlan, j as MongoDensifyRange, l as InsertOneCommand, m as MongoAggExpr, n as AggregateCommand, o as FindOneAndDeleteCommand, r as AnyMongoCommand, s as FindOneAndUpdateCommand, st as MongoResultShape, yt as MongoUpdatePipelineStage } from "./query-plan-k7nXo4F_-C07yAGNa.mjs";
5
+ import { a as InsertOneResult, d as UpdateResult, i as InsertManyResult, r as DeleteResult, s as MongoExecutionContext } from "./execution-BaB-jj-9.mjs";
6
+ import { A as TypedAccumulatorExpr, C as PagingCount, D as ResolveRow, N as UnwoundShape, O as SortSpec, P as UpdaterResult, T as ProjectedShape, _ as NestedDocShape, a as DocField, b as NumericField, c as ExtractDocShape, d as GroupedDocShape, f as LeafExpression, g as ModelToDocShape, h as ModelNestedShape, i as DateField, j as TypedAggExpr, k as StringField, l as FieldAccessor, m as ModelArrayField, n as BooleanField, o as DocShape, p as LiteralValue, r as BsonDateField, s as Expression, t as ArrayField, u as GroupSpec, v as NullableDocField, y as NullableNumericField } from "./field-accessor-DJzCZm0f-BErO0512.mjs";
7
+ import { ContractField, ContractModel, StorageBase } from "@prisma/orm-framework/contract/types";
8
+ //#region ../../../2-mongo-family/5-query-builders/query-builder/dist/index.d.mts
9
+ //#region src/accumulator-helpers.d.ts
10
+ declare const acc: {
11
+ sum<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<F>;
12
+ avg(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
13
+ min<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
14
+ readonly codecId: F["codecId"];
15
+ readonly nullable: true;
16
+ }>;
17
+ max<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
18
+ readonly codecId: F["codecId"];
19
+ readonly nullable: true;
20
+ }>;
21
+ first<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
22
+ readonly codecId: F["codecId"];
23
+ readonly nullable: true;
24
+ }>;
25
+ last<F extends DocField>(expr: TypedAggExpr<F>): TypedAccumulatorExpr<{
26
+ readonly codecId: F["codecId"];
27
+ readonly nullable: true;
28
+ }>;
29
+ push(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<ArrayField>;
30
+ addToSet(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<ArrayField>;
31
+ count(): TypedAccumulatorExpr<NumericField>;
32
+ stdDevPop(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
33
+ stdDevSamp(expr: TypedAggExpr<DocField>): TypedAccumulatorExpr<NullableNumericField>;
34
+ firstN(args: {
35
+ input: TypedAggExpr<DocField>;
36
+ n: TypedAggExpr<NumericField>;
37
+ }): TypedAccumulatorExpr<ArrayField>;
38
+ lastN(args: {
39
+ input: TypedAggExpr<DocField>;
40
+ n: TypedAggExpr<NumericField>;
41
+ }): TypedAccumulatorExpr<ArrayField>;
42
+ maxN(args: {
43
+ input: TypedAggExpr<DocField>;
44
+ n: TypedAggExpr<NumericField>;
45
+ }): TypedAccumulatorExpr<ArrayField>;
46
+ minN(args: {
47
+ input: TypedAggExpr<DocField>;
48
+ n: TypedAggExpr<NumericField>;
49
+ }): TypedAccumulatorExpr<ArrayField>;
50
+ top(args: {
51
+ output: TypedAggExpr<DocField>;
52
+ sortBy: Readonly<Record<string, 1 | -1>>;
53
+ }): TypedAccumulatorExpr<DocField>;
54
+ bottom(args: {
55
+ output: TypedAggExpr<DocField>;
56
+ sortBy: Readonly<Record<string, 1 | -1>>;
57
+ }): TypedAccumulatorExpr<DocField>;
58
+ topN(args: {
59
+ output: TypedAggExpr<DocField>;
60
+ sortBy: Readonly<Record<string, 1 | -1>>;
61
+ n: TypedAggExpr<NumericField>;
62
+ }): TypedAccumulatorExpr<ArrayField>;
63
+ bottomN(args: {
64
+ output: TypedAggExpr<DocField>;
65
+ sortBy: Readonly<Record<string, 1 | -1>>;
66
+ n: TypedAggExpr<NumericField>;
67
+ }): TypedAccumulatorExpr<ArrayField>;
68
+ };
69
+ //#endregion
70
+ //#region src/lookup-builder.d.ts
71
+ /**
72
+ * Resolved foreign-model name for a contract root. Looks `RootName` up
73
+ * through `TContract['roots']` and extracts the referenced model name
74
+ * so it can be used as a `ModelName` index into `models`. Resolves to
75
+ * `never` when the root is not present (this surface should never be
76
+ * reachable through normal use because `from()` constrains its `R`
77
+ * parameter to `keyof TContract['roots']`).
78
+ */
79
+ type ModelOf<TContract extends MongoContract, RootName extends keyof TContract['roots'] & string> = RootModelName<TContract, RootName>;
80
+ /**
81
+ * Object returned by the user from the `on(...)` callback. Each side is
82
+ * a `LeafExpression` produced by property access on the corresponding
83
+ * `FieldAccessor` (`local._id`, `foreign.customerId`, etc.). Carrying
84
+ * `LeafExpression` rather than the broader `TypedAggExpr` is what makes
85
+ * non-leaf returns (e.g. `fn.toUpper(local._id)`) a compile-time error
86
+ * without per-field operator gating — `LeafExpression` carries `_path`,
87
+ * `TypedAggExpr` does not (see field-accessor.ts L47–L82).
88
+ */
89
+ interface LookupOnResult {
90
+ readonly local: LeafExpression<DocField>;
91
+ readonly foreign: LeafExpression<DocField>;
92
+ }
93
+ /**
94
+ * Marker brand on the captured spec returned by the `lookup(...)`
95
+ * callback. The phantom `_brand` literal lets `PipelineChain.lookup`
96
+ * accept the result of `from(...).on(...).as(...)` without exposing the
97
+ * internal field shape to user code, and prevents accidental
98
+ * construction of a malformed spec by hand.
99
+ */
100
+ type LookupResultBrand = 'mongo-query-builder/lookup-result@1';
101
+ /**
102
+ * Captured output of the inner `from(name).on(cb).as(name)` chain. The
103
+ * contract is consumed by `PipelineChain.lookup` to construct the
104
+ * `MongoLookupStage` (collection name comes from `models[ModelName]
105
+ * .storage.collection`) and to thread `ModelArrayField<ModelName>` into
106
+ * the resulting `Shape` so the resolver yields `Array<ForeignRow>`.
107
+ *
108
+ * Type parameters carry the foreign-root literal `RootName`, the
109
+ * resolved foreign model name `ModelName`, and the `As` literal so
110
+ * `PipelineChain.lookup`'s return type can encode the result-row
111
+ * promotion precisely.
112
+ */
113
+ interface LookupResult<RootName extends string, ModelName extends string, As extends string> {
114
+ readonly _brand: LookupResultBrand;
115
+ readonly _root: RootName;
116
+ readonly _model: ModelName;
117
+ readonly _localField: string;
118
+ readonly _foreignField: string;
119
+ readonly _as: As;
120
+ }
121
+ /**
122
+ * Builder returned by `from(name).on(cb)`. Carries the foreign root /
123
+ * model literals plus the captured local / foreign paths, and exposes
124
+ * `.as(name)` to finalise the spec with the user-chosen field name.
125
+ */
126
+ interface LookupBuilderWithKey<RootName extends string, ModelName extends string> {
127
+ as<As extends string>(name: As): LookupResult<RootName, ModelName, As>;
128
+ }
129
+ /**
130
+ * Builder returned by `from(name)`. Carries the foreign root / model
131
+ * literals and the local pipeline's `Shape` / nested shape so the
132
+ * `on(...)` callback's `local` and `foreign` accessors are typed
133
+ * narrowly.
134
+ *
135
+ * `on(cb)` runs the user's callback to capture the leaf paths and
136
+ * returns a `LookupBuilderWithKey` that exposes `.as(name)`.
137
+ */
138
+ interface LookupBuilder<TContract extends MongoContract, Shape extends DocShape, Nested extends Record<string, DocField>, RootName extends string, ModelName extends string> {
139
+ on(cb: (local: FieldAccessor<Shape, Nested>, foreign: ModelName extends keyof MongoModelsMap<TContract> & string ? FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>> : never) => LookupOnResult): LookupBuilderWithKey<RootName, ModelName>;
140
+ }
141
+ /**
142
+ * Type of the `from` callable passed to `PipelineChain.lookup`'s outer
143
+ * callback. The generic argument is inferred from a string-literal
144
+ * argument (the same pattern as `mongoQuery({ context }).from('orders')`),
145
+ * which grounds `RootName` into the returned `LookupBuilder` *before*
146
+ * the inner `on(...)` callback is type-checked. This sequential
147
+ * inference is what makes `foreign` resolve narrowly to the foreign
148
+ * model's `FieldAccessor` (verified in the R1.5 spike — see spec § Open
149
+ * Questions / Resolved decisions).
150
+ */
151
+ type LookupFrom<TContract extends MongoContract, Shape extends DocShape, Nested extends Record<string, DocField>> = <RootName extends keyof TContract['roots'] & string>(name: RootName) => LookupBuilder<TContract, Shape, Nested, RootName, ModelOf<TContract, RootName>>;
152
+ //#endregion
153
+ //#region src/markers.d.ts
154
+ /**
155
+ * Phantom capability markers for `PipelineChain`.
156
+ *
157
+ * `UpdateEnabled` — gates `.updateMany()` / `.updateOne()` no-arg form
158
+ * (consume accumulated pipeline as an update-with-pipeline spec).
159
+ * `FindAndModifyEnabled` — gates `.findOneAndUpdate(...)` / `.findOneAndDelete(...)`
160
+ * (deconstruct pipeline into the wire command's filter/sort/skip slots).
161
+ * `LeadingMatch` — internal marker tracking whether the chain is still
162
+ * in its leading-`$match` prefix. Flips to `'past-leading'`
163
+ * after the first non-`$match` stage, which lets
164
+ * `match()` clear `UpdateEnabled` on second `$match`
165
+ * stages that sit past the prefix (and would otherwise
166
+ * fail at runtime inside `deconstructUpdateChain`).
167
+ *
168
+ * Each pipeline-stage method either preserves or clears these markers per
169
+ * the marker table (and rationale per row) in
170
+ * `docs/architecture docs/adrs/ADR 201 - State-machine pattern for typed DSL builders.md`.
171
+ *
172
+ * The markers exist only at the type level; nothing reads them at runtime.
173
+ * Value literals are self-identifying so the slots are distinguishable in
174
+ * hover tooltips and error messages (e.g. `'update-ok'` vs `'fam-ok'`).
175
+ */
176
+ type UpdateEnabled = 'update-ok' | 'update-cleared';
177
+ type FindAndModifyEnabled = 'fam-ok' | 'fam-cleared';
178
+ type LeadingMatch = 'leading' | 'past-leading';
179
+ //#endregion
180
+ //#region src/builder.d.ts
181
+ interface PipelineChainState {
182
+ readonly collection: string;
183
+ readonly stages: ReadonlyArray<MongoPipelineStage>;
184
+ readonly storageHash: string;
185
+ readonly modelName?: string;
186
+ }
187
+ /**
188
+ * The pipeline state in the query-builder state machine.
189
+ *
190
+ * Reached from `CollectionHandle` or `FilteredCollection` after the first
191
+ * pipeline-stage method call (or directly via `aggregate()` shortcuts). Holds
192
+ * the accumulated `MongoPipelineStage[]` and exposes pipeline-stage methods,
193
+ * the `merge`/`out` write terminals, and the `build`/`aggregate` read
194
+ * terminals.
195
+ *
196
+ * Two phantom type parameters gate the conditional terminals:
197
+ *
198
+ * - `U extends UpdateEnabled` — when `'update-ok'`, the no-arg `updateMany()` /
199
+ * `updateOne()` form is available (consume the chain as an
200
+ * update-with-pipeline spec). Cleared by stages that produce content the
201
+ * `update` AST cannot represent (e.g. `$group`, `$lookup`, `$limit`).
202
+ * - `F extends FindAndModifyEnabled` — when `'fam-ok'`, the
203
+ * `findOneAndUpdate(...)` / `findOneAndDelete(...)` terminals are
204
+ * available. Cleared by stages incompatible with their wire-command slots
205
+ * (`$limit`, `$group`, mutating stages, …).
206
+ *
207
+ * The marker semantics are encoded in the per-method return types — see the
208
+ * marker table (and rationale per row) in
209
+ * `docs/architecture docs/adrs/ADR 201 - State-machine pattern for typed DSL builders.md`.
210
+ */
211
+ declare class PipelineChain<TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>, Shape extends DocShape, U extends UpdateEnabled = 'update-ok', F extends FindAndModifyEnabled = 'fam-ok', L extends LeadingMatch = 'leading', N extends NestedDocShape = Record<string, never>> {
212
+ #private;
213
+ readonly __updateCompat: U;
214
+ readonly __findAndModifyCompat: F;
215
+ readonly __leadingMatch: L;
216
+ constructor(contract: TContract, state: PipelineChainState);
217
+ /**
218
+ * `$match`. `FindAndModifyEnabled` is always preserved. `UpdateEnabled` is
219
+ * preserved only while the chain is still in the leading-`$match` prefix
220
+ * (`L = 'leading'`); a `$match` that follows any non-`$match` stage
221
+ * transitions to `L = 'past-leading'` and clears `UpdateEnabled`, since
222
+ * `deconstructUpdateChain` can only peel leading `$match` stages into the
223
+ * wire-command filter.
224
+ */
225
+ match(filter: MongoFilterExpr): PipelineChain<TContract, Shape, L extends 'leading' ? U : 'update-cleared', F, L, N>;
226
+ match(fn: (fields: FieldAccessor<Shape, N>) => MongoFilterExpr): PipelineChain<TContract, Shape, L extends 'leading' ? U : 'update-cleared', F, L, N>;
227
+ /**
228
+ * `$sort`. Clears `UpdateEnabled` (`update` has no per-document sort) but
229
+ * preserves `FindAndModifyEnabled` (`findAndModify` has a `sort` slot).
230
+ */
231
+ sort(spec: SortSpec<Shape>): PipelineChain<TContract, Shape, 'update-cleared', F, 'past-leading', N>;
232
+ /**
233
+ * `$limit`. Clears both markers — `limit` is incompatible with the `update`
234
+ * wire command, and `findAndModify` already implies single-document
235
+ * semantics (so `.limit(...)` adds no meaning, only ambiguity).
236
+ */
237
+ limit(n: PagingCount<TContract>): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
238
+ /**
239
+ * `$skip`. Clears both markers — MongoDB's `findAndModify` wire command
240
+ * has no `skip` slot, so `deconstructFindAndModifyChain` rejects any
241
+ * `$skip` at runtime; keeping the marker `fam-cleared` makes the type
242
+ * system reflect the same constraint (see ADR 201 marker table).
243
+ */
244
+ skip(n: PagingCount<TContract>): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
245
+ sample(n: number): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
246
+ /**
247
+ * `$addFields`. Preserves `UpdateEnabled` (representable as
248
+ * update-with-pipeline `$set`); clears `FindAndModifyEnabled` (no analogue
249
+ * in the find-and-modify wire commands). The nested-path shape `N` is
250
+ * preserved — newly added flat fields are reachable via property access
251
+ * (`f.newField`) but do not themselves carry nested structure.
252
+ */
253
+ addFields<NewFields extends Record<string, TypedAggExpr<DocField>>>(fn: (fields: FieldAccessor<Shape, N>) => NewFields): PipelineChain<TContract, Shape & ExtractDocShape<NewFields>, U, 'fam-cleared', 'past-leading', N>;
254
+ /**
255
+ * `$lookup`. Clears both markers — joins are not representable in either
256
+ * the `update` or `findAndModify` wire commands. The original document's
257
+ * nested-path shape `N` is preserved (the lookup adds a sidecar array
258
+ * field; existing keys are untouched).
259
+ *
260
+ * The single callback receives a `from` callable that grounds the
261
+ * foreign-root literal sequentially before the inner `on(...)`
262
+ * callback is type-checked — see `lookup-builder.ts`. The resulting
263
+ * `Shape` gains the `As` key as a `ModelArrayField<ModelName>` so
264
+ * `ResolveRow` produces `Array<ForeignRow>` (with concrete leaf
265
+ * types) instead of the legacy `unknown[]`.
266
+ */
267
+ lookup<RootName extends string, ModelName extends string, As extends string>(fn: (from: LookupFrom<TContract, Shape, N>) => LookupResult<RootName, ModelName, As>): PipelineChain<TContract, Shape & Record<As, ModelArrayField<ModelName>>, 'update-cleared', 'fam-cleared', 'past-leading', N>;
268
+ /**
269
+ * `$project`. Preserves `UpdateEnabled` (representable as update-with-pipeline
270
+ * `$project` / `$unset`); clears `FindAndModifyEnabled` (use `.project()` on
271
+ * the result of `.build()` if both projection and find-and-modify are
272
+ * needed — see spec).
273
+ *
274
+ * Resets the nested-path shape to `Record<string, never>` — projection
275
+ * fundamentally rewrites the document, so dot-paths into the *source*
276
+ * document are no longer meaningful downstream.
277
+ */
278
+ project<K extends keyof Shape & string>(...keys: K[]): PipelineChain<TContract, Pick<Shape, K | ('_id' extends keyof Shape ? '_id' : never)>, U, 'fam-cleared', 'past-leading'>;
279
+ project<Spec extends Record<string, 1 | TypedAggExpr<DocField>>>(fn: (fields: FieldAccessor<Shape, N>) => Spec): PipelineChain<TContract, ProjectedShape<Shape, Spec>, U, 'fam-cleared', 'past-leading'>;
280
+ /**
281
+ * `$unwind`. Clears both markers — array unrolling produces multiple output
282
+ * documents per input, incompatible with both single-document update and
283
+ * find-and-modify wire commands. The original `N` is preserved: unwind
284
+ * replaces the unwound array slot with its element but leaves the rest
285
+ * of the document structurally intact.
286
+ */
287
+ unwind<K extends keyof Shape & string>(field: K, options?: {
288
+ preserveNullAndEmptyArrays?: boolean;
289
+ }): PipelineChain<TContract, UnwoundShape<Shape, K>, 'update-cleared', 'fam-cleared', 'past-leading', N>;
290
+ /**
291
+ * `$group`. Clears both markers — group output bears no relation to source
292
+ * documents; neither `update` nor `findAndModify` can consume it. Nested
293
+ * path shape is reset (the source document's path tree is gone).
294
+ */
295
+ group<Spec extends GroupSpec>(fn: (fields: FieldAccessor<Shape, N>) => Spec): PipelineChain<TContract, GroupedDocShape<Spec>, 'update-cleared', 'fam-cleared', 'past-leading'>;
296
+ /**
297
+ * `$replaceRoot`. Preserves `UpdateEnabled` (representable as
298
+ * update-with-pipeline `$replaceRoot`); clears `FindAndModifyEnabled`.
299
+ * Nested path shape is reset — the replaced root has no relation to
300
+ * the original document structure.
301
+ */
302
+ replaceRoot<NewShape extends DocShape>(fn: (fields: FieldAccessor<Shape, N>) => Expression<DocField> | TypedAggExpr<DocField>): PipelineChain<TContract, NewShape, U, 'fam-cleared', 'past-leading'>;
303
+ count<Field extends string>(field: Field): PipelineChain<TContract, Record<Field, {
304
+ readonly codecId: 'mongo/double@1';
305
+ readonly nullable: false;
306
+ }>, 'update-cleared', 'fam-cleared', 'past-leading'>;
307
+ sortByCount<F2 extends DocField>(fn: (fields: FieldAccessor<Shape, N>) => Expression<F2> | TypedAggExpr<F2>): PipelineChain<TContract, {
308
+ _id: F2;
309
+ count: {
310
+ readonly codecId: 'mongo/double@1';
311
+ readonly nullable: false;
312
+ };
313
+ }, 'update-cleared', 'fam-cleared', 'past-leading'>;
314
+ /**
315
+ * `$redact`. Preserves `UpdateEnabled`; clears `FindAndModifyEnabled`.
316
+ * Shape- and nested-path-preserving (the document tree is unchanged).
317
+ */
318
+ redact(fn: (fields: FieldAccessor<Shape, N>) => Expression<DocField> | TypedAggExpr<DocField>): PipelineChain<TContract, Shape, U, 'fam-cleared', 'past-leading', N>;
319
+ /**
320
+ * `$out` write terminal. Materialises the pipeline output into
321
+ * `collection` (optionally in `db`), replacing any prior contents. Unlike
322
+ * the other pipeline-stage methods, this **terminates** the chain — it
323
+ * returns a `MongoQueryPlan` rather than another `PipelineChain`, since
324
+ * `$out` must be the final stage and there is nothing further to chain.
325
+ *
326
+ * Lane is `mongo-query` (matching all other terminals in this package) so
327
+ * middleware can dispatch on intent without inspecting the command.
328
+ *
329
+ * The result row stream is empty (`unknown` row type) — the data lives
330
+ * in the destination collection, not the response.
331
+ */
332
+ out(collection: string, db?: string): MongoQueryPlan<unknown, AggregateCommand>;
333
+ /**
334
+ * `$merge` write terminal. Streams the pipeline output into the target
335
+ * collection per the supplied merge semantics (`whenMatched` /
336
+ * `whenNotMatched`). Like `out()`, terminates the chain — `$merge` must
337
+ * be the final stage.
338
+ */
339
+ merge(options: {
340
+ into: string | {
341
+ db: string;
342
+ coll: string;
343
+ };
344
+ on?: string | ReadonlyArray<string>;
345
+ whenMatched?: string | ReadonlyArray<MongoUpdatePipelineStage>;
346
+ whenNotMatched?: string;
347
+ }): MongoQueryPlan<unknown, AggregateCommand>;
348
+ unionWith(collection: string, pipeline?: ReadonlyArray<MongoPipelineStage>): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
349
+ bucket(options: {
350
+ groupBy: MongoAggExpr;
351
+ boundaries: ReadonlyArray<unknown>;
352
+ default_?: unknown;
353
+ output?: Record<string, MongoAggAccumulator>;
354
+ }): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
355
+ bucketAuto(options: {
356
+ groupBy: MongoAggExpr;
357
+ buckets: number;
358
+ output?: Record<string, MongoAggAccumulator>;
359
+ granularity?: string;
360
+ }): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
361
+ geoNear(options: {
362
+ near: unknown;
363
+ distanceField: string;
364
+ spherical?: boolean;
365
+ maxDistance?: number;
366
+ minDistance?: number;
367
+ query?: MongoFilterExpr;
368
+ key?: string;
369
+ distanceMultiplier?: number;
370
+ includeLocs?: string;
371
+ }): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
372
+ facet(facets: Record<string, ReadonlyArray<MongoPipelineStage>>): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
373
+ graphLookup(options: {
374
+ from: string;
375
+ startWith: MongoAggExpr;
376
+ connectFromField: string;
377
+ connectToField: string;
378
+ as: string;
379
+ maxDepth?: number;
380
+ depthField?: string;
381
+ restrictSearchWithMatch?: MongoFilterExpr;
382
+ }): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
383
+ setWindowFields(options: {
384
+ partitionBy?: MongoAggExpr;
385
+ sortBy?: Record<string, 1 | -1>;
386
+ output: Record<string, MongoWindowField>;
387
+ }): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
388
+ densify(options: {
389
+ field: string;
390
+ partitionByFields?: ReadonlyArray<string>;
391
+ range: MongoDensifyRange;
392
+ }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
393
+ fill(options: {
394
+ partitionBy?: MongoAggExpr;
395
+ partitionByFields?: ReadonlyArray<string>;
396
+ sortBy?: Record<string, 1 | -1>;
397
+ output: Record<string, MongoFillOutput>;
398
+ }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
399
+ search(config: Record<string, unknown>, index?: string): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
400
+ searchMeta(config: Record<string, unknown>, index?: string): PipelineChain<TContract, DocShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
401
+ vectorSearch(options: {
402
+ index: string;
403
+ path: string;
404
+ queryVector: ReadonlyArray<number>;
405
+ numCandidates: number;
406
+ limit: number;
407
+ filter?: Record<string, unknown>;
408
+ }): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading', N>;
409
+ pipe(stage: MongoPipelineStage): PipelineChain<TContract, Shape, 'update-cleared', 'fam-cleared', 'past-leading'>;
410
+ pipe<NewShape extends DocShape>(stage: MongoPipelineStage): PipelineChain<TContract, NewShape, 'update-cleared', 'fam-cleared', 'past-leading'>;
411
+ /**
412
+ * No-arg `updateMany()`: deconstruct the chain into leading `$match`
413
+ * stages (folded into the filter) and remaining stages (which must all
414
+ * be valid pipeline-update stages). Available only when `U = 'update-ok'`.
415
+ *
416
+ * The optional callback parameter exists for subclass-override
417
+ * compatibility with `FilteredCollection.updateMany(updaterFn)` — TS's
418
+ * strict override check requires the parent's parameter to accept at
419
+ * least what the child's signature does. A runtime guard throws if a
420
+ * callback is actually passed on a bare `PipelineChain`. Note that
421
+ * because nothing in the public surface transitions `U` from
422
+ * `'update-cleared'` (the initial state on `CollectionHandle` /
423
+ * `FilteredCollection`) back to `'update-ok'`, the no-arg form is
424
+ * reachable only via explicit type casts in internal tests — the
425
+ * callback-form "type hole" is therefore not reachable from user
426
+ * code. See `docs/architecture docs/adrs/ADR 201 - State-machine
427
+ * pattern for typed DSL builders.md` for the marker-transition table.
428
+ */
429
+ updateMany(this: PipelineChain<TContract, Shape, 'update-ok', F, L, N>, updaterFn?: (fields: FieldAccessor<Shape, N>) => UpdaterResult): MongoQueryPlan<UpdateResult, UpdateManyCommand>;
430
+ /**
431
+ * No-arg `updateOne()`: same as `updateMany()` but maps to a single-doc
432
+ * update. Carries the same optional-callback/subclass-compat caveat
433
+ * documented above — the callback form is reachable only via forced
434
+ * casts in internal tests.
435
+ */
436
+ updateOne(this: PipelineChain<TContract, Shape, 'update-ok', F, L, N>, updaterFn?: (fields: FieldAccessor<Shape, N>) => UpdaterResult): MongoQueryPlan<UpdateResult, UpdateOneCommand>;
437
+ /**
438
+ * Find a single document matching the accumulated pipeline (which must
439
+ * consist solely of leading `$match` stages followed by at most one
440
+ * `$sort`) and apply `updaterFn`. Available only when
441
+ * `FindAndModifyEnabled` is `'fam-ok'` — stages that clear the marker
442
+ * (including `$skip`, which MongoDB's `findAndModify` has no slot for)
443
+ * make this method invisible at the type level.
444
+ *
445
+ * The pipeline stages are deconstructed into the wire command's `filter`
446
+ * and `sort` slots. If any non-deconstructable stage is present, a
447
+ * runtime error is thrown as a defensive check (the type system should
448
+ * prevent this).
449
+ */
450
+ findOneAndUpdate(this: PipelineChain<TContract, Shape, U, 'fam-ok', L, N>, updaterFn: (fields: FieldAccessor<Shape, N>) => UpdaterResult, opts?: {
451
+ readonly upsert?: boolean;
452
+ readonly returnDocument?: 'before' | 'after';
453
+ }): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract> | null, FindOneAndUpdateCommand>;
454
+ /**
455
+ * Find a single document matching the accumulated pipeline and delete it.
456
+ * Same marker gating and deconstruction as `findOneAndUpdate`.
457
+ */
458
+ findOneAndDelete(this: PipelineChain<TContract, Shape, U, 'fam-ok', L, N>): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract> | null, FindOneAndDeleteCommand>;
459
+ /**
460
+ * Materialise the chain as a `MongoQueryPlan` wrapping an `AggregateCommand`.
461
+ */
462
+ build(): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract>, AggregateCommand>;
463
+ /**
464
+ * Alias for `build()` — surfaces the read intent at the call site.
465
+ */
466
+ aggregate(): MongoQueryPlan<ResolveRow<Shape, ExtractMongoCodecTypes<TContract>, TContract>, AggregateCommand>;
467
+ }
468
+ //#endregion
469
+ //#region src/expression-helpers.d.ts
470
+ declare function literal(value: string): TypedAggExpr<StringField>;
471
+ declare function literal(value: number): TypedAggExpr<NumericField>;
472
+ declare function literal(value: boolean): TypedAggExpr<BooleanField>;
473
+ declare function literal(value: Date): TypedAggExpr<DateField>;
474
+ declare function literal<C extends string, N extends boolean>(value: MongoPreparedParamRef<C, N>): TypedAggExpr<{
475
+ readonly codecId: C;
476
+ readonly nullable: N;
477
+ }>;
478
+ declare function literal<F extends DocField>(value: LiteralValue<F>): TypedAggExpr<F>;
479
+ declare const fn: {
480
+ add(...args: TypedAggExpr<DocField>[]): TypedAggExpr<NumericField>;
481
+ subtract(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
482
+ multiply(...args: TypedAggExpr<DocField>[]): TypedAggExpr<NumericField>;
483
+ divide(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
484
+ concat(...args: TypedAggExpr<DocField>[]): TypedAggExpr<StringField>;
485
+ toLower(a: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
486
+ toUpper(a: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
487
+ size(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
488
+ cond<F extends DocField>(condition: MongoAggExpr, thenExpr: TypedAggExpr<F>, elseExpr: TypedAggExpr<DocField>): TypedAggExpr<F>;
489
+ literal: typeof literal;
490
+ year(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
491
+ month(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
492
+ dayOfMonth(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
493
+ hour(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
494
+ minute(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
495
+ second(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
496
+ millisecond(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
497
+ dateToString(args: {
498
+ date: TypedAggExpr<BsonDateField>;
499
+ format?: TypedAggExpr<StringField>;
500
+ timezone?: TypedAggExpr<StringField>;
501
+ onNull?: TypedAggExpr<DocField>;
502
+ }): TypedAggExpr<StringField>;
503
+ dateFromString(args: {
504
+ dateString: TypedAggExpr<StringField>;
505
+ format?: TypedAggExpr<StringField>;
506
+ timezone?: TypedAggExpr<StringField>;
507
+ onError?: TypedAggExpr<DocField>;
508
+ onNull?: TypedAggExpr<DocField>;
509
+ }): TypedAggExpr<DateField>;
510
+ dateDiff(args: {
511
+ startDate: TypedAggExpr<BsonDateField>;
512
+ endDate: TypedAggExpr<BsonDateField>;
513
+ unit: TypedAggExpr<StringField>;
514
+ timezone?: TypedAggExpr<StringField>;
515
+ startOfWeek?: TypedAggExpr<StringField>;
516
+ }): TypedAggExpr<NumericField>;
517
+ dateAdd(args: {
518
+ startDate: TypedAggExpr<BsonDateField>;
519
+ unit: TypedAggExpr<StringField>;
520
+ amount: TypedAggExpr<NumericField>;
521
+ timezone?: TypedAggExpr<StringField>;
522
+ }): TypedAggExpr<DateField>;
523
+ dateSubtract(args: {
524
+ startDate: TypedAggExpr<BsonDateField>;
525
+ unit: TypedAggExpr<StringField>;
526
+ amount: TypedAggExpr<NumericField>;
527
+ timezone?: TypedAggExpr<StringField>;
528
+ }): TypedAggExpr<DateField>;
529
+ dateTrunc(args: {
530
+ date: TypedAggExpr<BsonDateField>;
531
+ unit: TypedAggExpr<StringField>;
532
+ binSize?: TypedAggExpr<NumericField>;
533
+ timezone?: TypedAggExpr<StringField>;
534
+ startOfWeek?: TypedAggExpr<StringField>;
535
+ }): TypedAggExpr<DateField>;
536
+ substr(str: TypedAggExpr<DocField>, start: TypedAggExpr<DocField>, length: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
537
+ substrBytes(str: TypedAggExpr<DocField>, start: TypedAggExpr<DocField>, count: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
538
+ trim(args: {
539
+ input: TypedAggExpr<StringField>;
540
+ chars?: TypedAggExpr<StringField>;
541
+ }): TypedAggExpr<StringField>;
542
+ ltrim(args: {
543
+ input: TypedAggExpr<StringField>;
544
+ chars?: TypedAggExpr<StringField>;
545
+ }): TypedAggExpr<StringField>;
546
+ rtrim(args: {
547
+ input: TypedAggExpr<StringField>;
548
+ chars?: TypedAggExpr<StringField>;
549
+ }): TypedAggExpr<StringField>;
550
+ split(str: TypedAggExpr<DocField>, delimiter: TypedAggExpr<DocField>): TypedAggExpr<ArrayField>;
551
+ strLenCP(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
552
+ strLenBytes(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
553
+ regexMatch(args: {
554
+ input: TypedAggExpr<StringField>;
555
+ regex: TypedAggExpr<StringField>;
556
+ options?: TypedAggExpr<StringField>;
557
+ }): TypedAggExpr<BooleanField>;
558
+ regexFind(args: {
559
+ input: TypedAggExpr<StringField>;
560
+ regex: TypedAggExpr<StringField>;
561
+ options?: TypedAggExpr<StringField>;
562
+ }): TypedAggExpr<DocField>;
563
+ regexFindAll(args: {
564
+ input: TypedAggExpr<StringField>;
565
+ regex: TypedAggExpr<StringField>;
566
+ options?: TypedAggExpr<StringField>;
567
+ }): TypedAggExpr<ArrayField>;
568
+ replaceOne(args: {
569
+ input: TypedAggExpr<StringField>;
570
+ find: TypedAggExpr<StringField>;
571
+ replacement: TypedAggExpr<StringField>;
572
+ }): TypedAggExpr<StringField>;
573
+ replaceAll(args: {
574
+ input: TypedAggExpr<StringField>;
575
+ find: TypedAggExpr<StringField>;
576
+ replacement: TypedAggExpr<StringField>;
577
+ }): TypedAggExpr<StringField>;
578
+ cmp(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
579
+ eq(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
580
+ ne(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
581
+ gt(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
582
+ gte(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
583
+ lt(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
584
+ lte(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
585
+ arrayElemAt(arr: TypedAggExpr<DocField>, idx: TypedAggExpr<DocField>): TypedAggExpr<NullableDocField>;
586
+ concatArrays(...args: TypedAggExpr<DocField>[]): TypedAggExpr<ArrayField>;
587
+ firstElem(a: TypedAggExpr<DocField>): TypedAggExpr<NullableDocField>;
588
+ lastElem(a: TypedAggExpr<DocField>): TypedAggExpr<NullableDocField>;
589
+ isIn(elem: TypedAggExpr<DocField>, arr: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
590
+ indexOfArray(arr: TypedAggExpr<DocField>, value: TypedAggExpr<DocField>, ...rest: TypedAggExpr<DocField>[]): TypedAggExpr<NumericField>;
591
+ isArray(a: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
592
+ reverseArray(a: TypedAggExpr<DocField>): TypedAggExpr<ArrayField>;
593
+ slice(arr: TypedAggExpr<DocField>, ...rest: TypedAggExpr<DocField>[]): TypedAggExpr<ArrayField>;
594
+ zip(args: {
595
+ inputs: TypedAggExpr<ArrayField>[];
596
+ useLongestLength?: TypedAggExpr<BooleanField>;
597
+ defaults?: TypedAggExpr<ArrayField>;
598
+ }): TypedAggExpr<ArrayField>;
599
+ range(start: TypedAggExpr<DocField>, end: TypedAggExpr<DocField>, step: TypedAggExpr<DocField>): TypedAggExpr<ArrayField>;
600
+ setUnion(...args: TypedAggExpr<DocField>[]): TypedAggExpr<ArrayField>;
601
+ setIntersection(...args: TypedAggExpr<DocField>[]): TypedAggExpr<ArrayField>;
602
+ setDifference(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<ArrayField>;
603
+ setEquals(...args: TypedAggExpr<DocField>[]): TypedAggExpr<BooleanField>;
604
+ setIsSubset(a: TypedAggExpr<DocField>, b: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
605
+ anyElementTrue(a: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
606
+ allElementsTrue(a: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
607
+ typeOf(a: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
608
+ convert(args: {
609
+ input: TypedAggExpr<DocField>;
610
+ to: TypedAggExpr<StringField | NumericField>;
611
+ onError?: TypedAggExpr<DocField>;
612
+ onNull?: TypedAggExpr<DocField>;
613
+ }): TypedAggExpr<DocField>;
614
+ toInt(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
615
+ toLong(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
616
+ toDouble(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
617
+ toDecimal(a: TypedAggExpr<DocField>): TypedAggExpr<NumericField>;
618
+ toString_(a: TypedAggExpr<DocField>): TypedAggExpr<StringField>;
619
+ toObjectId(a: TypedAggExpr<DocField>): TypedAggExpr<DocField>;
620
+ toBool(a: TypedAggExpr<DocField>): TypedAggExpr<BooleanField>;
621
+ toDate(a: TypedAggExpr<DocField>): TypedAggExpr<DateField>;
622
+ objectToArray(a: TypedAggExpr<DocField>): TypedAggExpr<ArrayField>;
623
+ arrayToObject(a: TypedAggExpr<DocField>): TypedAggExpr<DocField>;
624
+ getField(args: {
625
+ field: TypedAggExpr<StringField>;
626
+ input?: TypedAggExpr<DocField>;
627
+ }): TypedAggExpr<DocField>;
628
+ setField(args: {
629
+ field: TypedAggExpr<StringField>;
630
+ input: TypedAggExpr<DocField>;
631
+ value: TypedAggExpr<DocField>;
632
+ }): TypedAggExpr<DocField>;
633
+ };
634
+ //#endregion
635
+ //#region src/state-classes.d.ts
636
+ /**
637
+ * Root state of the query-builder state machine. Returned from
638
+ * `mongoQuery(...).from(name)` and bound to a single collection.
639
+ *
640
+ * Inherits the entire pipeline-stage surface from `PipelineChain` (since an
641
+ * empty `CollectionHandle` is observably an empty pipeline). Adds:
642
+ *
643
+ * - `match(...)` — overridden to transition to `FilteredCollection`, which
644
+ * accumulates filters for eventual splatting into write/find-and-modify
645
+ * wire commands.
646
+ * - **Insert / unqualified-write methods** (M2): `insertOne`, `insertMany`,
647
+ * `updateAll`, `deleteAll`. These live *only* here — the corresponding
648
+ * methods are absent from `FilteredCollection`, so a caller cannot
649
+ * accidentally produce an unqualified write by forgetting to `.match(...)`
650
+ * later in the chain. Bodies land in M2.
651
+ */
652
+ declare class CollectionHandle<TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>, ModelName extends keyof MongoModelsMap<TContract> & string> extends PipelineChain<TContract, ModelToDocShape<TContract, ModelName>, 'update-cleared', 'fam-cleared', 'leading', ModelNestedShape<TContract, ModelName>> {
653
+ #private;
654
+ constructor(ctx: BindingContext<TContract>, modelName: ModelName);
655
+ /**
656
+ * Bound model name. Exposed so type tests can assert the binding without
657
+ * flipping into a pipeline. Not part of the public-API contract.
658
+ */
659
+ get _modelName(): ModelName;
660
+ /**
661
+ * Begin accumulating a filter. Transitions to `FilteredCollection`.
662
+ *
663
+ * Overrides `PipelineChain.match` (which appends another `$match` stage
664
+ * and stays in the chain). The two implementations are semantically
665
+ * equivalent for the read terminal — multiple `$match` stages AND-fold in
666
+ * Mongo — but `FilteredCollection` makes the accumulated filter
667
+ * addressable for the write/find-and-modify terminals landing in M2/M3.
668
+ */
669
+ match(filter: MongoFilterExpr): FilteredCollection<TContract, ModelName>;
670
+ match(fn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => MongoFilterExpr): FilteredCollection<TContract, ModelName>;
671
+ /**
672
+ * Insert a single document. Document fields are passed straight through to
673
+ * the wire `InsertOneCommand` — codec normalisation happens at the
674
+ * adapter/driver boundary, identically to the SQL builder (see Open Item
675
+ * #14 confirmation in the design conversation).
676
+ *
677
+ * Returns a `MongoQueryPlan<InsertOneResult>` whose row stream yields a
678
+ * single result document with the server-assigned `insertedId`.
679
+ */
680
+ insertOne(document: Record<string, MongoValue>): MongoQueryPlan<InsertOneResult, InsertOneCommand>;
681
+ /**
682
+ * Insert a batch of documents. Order is preserved in the returned
683
+ * `insertedIds` array.
684
+ */
685
+ insertMany(documents: ReadonlyArray<Record<string, MongoValue>>): MongoQueryPlan<InsertManyResult, InsertManyCommand>;
686
+ /**
687
+ * Update *every* document in the collection. Lives only on
688
+ * `CollectionHandle` — the corresponding method is intentionally absent
689
+ * from `FilteredCollection` so a caller cannot accidentally produce an
690
+ * unqualified write by forgetting to `.match(...)` first. Pair with
691
+ * `.match(...).updateMany(...)` for the filtered case.
692
+ */
693
+ updateAll(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult, UpdateManyCommand>;
694
+ /**
695
+ * Delete *every* document in the collection. See `updateAll` for the
696
+ * rationale around the unqualified-write surface being limited to this
697
+ * state class.
698
+ */
699
+ deleteAll(): MongoQueryPlan<DeleteResult, DeleteManyCommand>;
700
+ /**
701
+ * Insert-or-update the document matching `filterFn`. The filter is
702
+ * mandatory (vs. `updateAll`'s tautological match) because an upsert
703
+ * without a discriminating predicate would either match every existing
704
+ * document or insert an indistinguishable new one.
705
+ *
706
+ * Maps to `UpdateOneCommand` with `upsert: true`. The driver inserts a
707
+ * new document derived from the filter equality fields plus the update
708
+ * spec when no match is found; otherwise updates the matched document.
709
+ */
710
+ upsertOne(filterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => MongoFilterExpr, updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult, UpdateOneCommand>;
711
+ }
712
+ /**
713
+ * State reached after one or more `.match(...)` calls on `CollectionHandle`.
714
+ *
715
+ * Inherits the pipeline-stage surface from `PipelineChain`, with the
716
+ * accumulated filters baked in as a leading `$match` stage on the underlying
717
+ * pipeline state. This means read-terminal output (`.aggregate()` /
718
+ * `.build()`) and any subsequent pipeline-stage chain see the filtered
719
+ * collection as input — the read story works through pure inheritance.
720
+ *
721
+ * Adds:
722
+ *
723
+ * - `match(...)` — pushes another `$match` stage *and* records the filter in
724
+ * the accumulator, so the eventual write/find-and-modify terminal can
725
+ * splat the AND-folded filter into the wire command's `filter` slot.
726
+ * - **Filtered writes** (M2): `updateMany`, `updateOne`, `deleteMany`,
727
+ * `deleteOne`, `upsertOne`. Stubbed in M1. (Upsert-many is an open
728
+ * question in the spec — see TML-2267 — and is intentionally absent.)
729
+ * - **Find-and-modify** (M3): `findOneAndUpdate`, `findOneAndDelete`.
730
+ * Stubbed in M1.
731
+ *
732
+ * Notably *does not* expose `insertOne`/`insertMany`/`updateAll`/`deleteAll`
733
+ * — those are insert or unqualified-write operations that are nonsense
734
+ * after a filter has been applied.
735
+ */
736
+ declare class FilteredCollection<TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>, ModelName extends keyof MongoModelsMap<TContract> & string> extends PipelineChain<TContract, ModelToDocShape<TContract, ModelName>, 'update-cleared', 'fam-cleared', 'leading', ModelNestedShape<TContract, ModelName>> {
737
+ #private;
738
+ constructor(ctx: BindingContext<TContract>, modelName: ModelName, filters: ReadonlyArray<MongoFilterExpr>);
739
+ get _modelName(): ModelName;
740
+ /**
741
+ * Accumulated filter list. Exposed for the M2/M3 write/find-and-modify
742
+ * terminals to splat into wire-command `filter` slots; not part of the
743
+ * public-API contract.
744
+ */
745
+ get _filters(): ReadonlyArray<MongoFilterExpr>;
746
+ /**
747
+ * Append another filter to the accumulator. Returns a new
748
+ * `FilteredCollection` whose underlying pipeline rebuilds the leading
749
+ * `$match` from the AND-folded accumulator (rather than appending a
750
+ * second `$match` stage), so the write/find-and-modify terminals see a
751
+ * single authoritative filter expression.
752
+ */
753
+ match(filter: MongoFilterExpr): FilteredCollection<TContract, ModelName>;
754
+ match(fn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => MongoFilterExpr): FilteredCollection<TContract, ModelName>;
755
+ /**
756
+ * Update every matching document. `updaterFn` receives a `FieldAccessor`
757
+ * and returns an array of `TypedUpdateOp` (e.g. `[f.amount.inc(1),
758
+ * f.status.set('done')]`). Operators are folded into the wire-format
759
+ * update spec by `foldUpdateOps`, which throws on operator+path
760
+ * collisions.
761
+ */
762
+ updateMany(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult, UpdateManyCommand>;
763
+ /**
764
+ * Update at most one matching document. The driver picks the document
765
+ * (typically the first one matched by the underlying scan); no ordering
766
+ * guarantee is implied — chain `.sort(...)` and use the M3
767
+ * `.findOneAndUpdate(...)` terminal when ordering matters.
768
+ */
769
+ updateOne(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult, UpdateOneCommand>;
770
+ /**
771
+ * Delete every matching document.
772
+ */
773
+ deleteMany(): MongoQueryPlan<DeleteResult, DeleteManyCommand>;
774
+ /**
775
+ * Delete at most one matching document. See the `updateOne` note about
776
+ * driver-chosen victim selection.
777
+ */
778
+ deleteOne(): MongoQueryPlan<DeleteResult, DeleteOneCommand>;
779
+ /**
780
+ * Insert-or-update against the accumulated filter. Maps to
781
+ * `UpdateOneCommand` with `upsert: true`. Equivalent to
782
+ * `CollectionHandle.upsertOne(f => filter, updaterFn)` but reuses the
783
+ * already-accumulated `.match(...)` filter chain.
784
+ */
785
+ upsertOne(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult): MongoQueryPlan<UpdateResult, UpdateOneCommand>;
786
+ /**
787
+ * Find a single matching document and apply `updaterFn` to it.
788
+ *
789
+ * `opts.upsert` (default `false`) toggles insert-on-miss behaviour.
790
+ * `opts.returnDocument` (default `'after'`) controls whether the row
791
+ * stream yields the document as it was before or after the update.
792
+ */
793
+ findOneAndUpdate(updaterFn: (fields: FieldAccessor<ModelToDocShape<TContract, ModelName>, ModelNestedShape<TContract, ModelName>>) => UpdaterResult, opts?: {
794
+ readonly upsert?: boolean;
795
+ readonly returnDocument?: 'before' | 'after';
796
+ }): MongoQueryPlan<ResolveRow<ModelToDocShape<TContract, ModelName>, ExtractMongoCodecTypes<TContract>, TContract> | null, FindOneAndUpdateCommand>;
797
+ /**
798
+ * Find a single matching document and delete it. Returns the deleted
799
+ * document via the row stream.
800
+ */
801
+ findOneAndDelete(): MongoQueryPlan<ResolveRow<ModelToDocShape<TContract, ModelName>, ExtractMongoCodecTypes<TContract>, TContract> | null, FindOneAndDeleteCommand>;
802
+ }
803
+ /**
804
+ * Bound execution context shared across the three state classes.
805
+ */
806
+ interface BindingContext<TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>> {
807
+ readonly contract: TContract;
808
+ readonly collection: string;
809
+ readonly storageHash: string;
810
+ }
811
+ //#endregion
812
+ //#region src/query.d.ts
813
+ /**
814
+ * Public entry point of the query builder. `mongoQuery(...).from(rootName)`
815
+ * yields the root state of the three-state machine
816
+ * (`CollectionHandle` → `FilteredCollection` → `PipelineChain`).
817
+ *
818
+ * `rawCommand(cmd)` is the escape hatch for cases the typed surface does
819
+ * not cover (yet) — it accepts any `AnyMongoCommand` (typed CRUD or a
820
+ * `RawMongoCommand` of `Document`s) and packages it into a `MongoQueryPlan`
821
+ * with `lane: 'mongo-query'`. Row type is `unknown` because the runtime
822
+ * cannot know what the caller's command yields.
823
+ */
824
+ interface QueryRoot<TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>> {
825
+ from<K extends keyof TContract['roots'] & string>(rootName: K): CollectionHandle<TContract, RootModelName<TContract, K>>;
826
+ rawCommand<C extends AnyMongoCommand>(command: C): MongoQueryPlan<unknown, C>;
827
+ }
828
+ /** Builds queries for the contract of `context`, which `mongoStatic({ contract })` and `mongo({ contract })` create after validating the contract. */
829
+ declare function mongoQuery<TContract extends MongoContractWithTypeMaps<MongoContract, AnyMongoTypeMaps>>(options: {
830
+ readonly context: MongoExecutionContext<TContract>;
831
+ }): QueryRoot<TContract>;
832
+ //#endregion
833
+ //#region src/result-shape.d.ts
834
+ /**
835
+ * The shape the runtime decodes one field against. A value-object field becomes a document of its own fields when `storage` holds the value object its reference names; a value object nested inside itself is left undecoded.
836
+ */
837
+ declare function contractFieldToMongoFieldShape(field: ContractField, storage?: Pick<StorageBase, 'namespaces'>): MongoFieldShape;
838
+ /**
839
+ * The shape the runtime decodes a model's documents against, keyed by stored name. `selection` names stored names; `includes` is keyed by relation name.
840
+ */
841
+ declare function contractModelToMongoResultShape(model: ContractModel<MongoModelStorage>, options?: {
842
+ readonly selection?: readonly string[];
843
+ /** The shape of each included relation, keyed by relation name. */
844
+ readonly includes?: Readonly<Record<string, MongoFieldShape>>;
845
+ readonly storage?: Pick<StorageBase, 'namespaces'>;
846
+ }): MongoResultShape;
847
+ //#endregion
848
+ export { mongoQuery as _, LookupBuilderWithKey as a, LookupResult as c, QueryRoot as d, UpdateEnabled as f, fn as g, contractModelToMongoResultShape as h, LookupBuilder as i, ModelOf as l, contractFieldToMongoFieldShape as m, FilteredCollection as n, LookupFrom as o, acc as p, FindAndModifyEnabled as r, LookupOnResult as s, CollectionHandle as t, PipelineChain as u };
849
+ //# sourceMappingURL=index-Bzkio7As.d.mts.map