@prisma-next/mongo-lowering 0.11.0 → 0.12.0

package/README.md

@@ -4,7 +4,7 @@ Adapter and driver interface contracts for the MongoDB transport layer.
 
 ## Responsibilities
 
-- **Adapter interface**: `MongoAdapter` — defines `lower(plan: MongoQueryPlan): Promise<AnyMongoWireCommand>`, the contract for converting a typed query plan into a wire command. Async at the boundary: callers must `await lower(...)` so adapters may run async codec encodes (e.g. `resolveValue`) before producing the wire shape.
+- **Adapter interface**: `MongoAdapter` — defines `lower(plan: MongoQueryPlan): Promise<AnyMongoWireCommand>` (one-shot `resolveParams(structuralLower(plan))`), plus the two-phase split `structuralLower` / `resolveParams` used by `@prisma-next/mongo-runtime` so `beforeExecute` middleware can mutate `MongoParamRef` leaves before codec resolution. Those phase methods are public on this SPI (unlike SQL's private `lowerToDraft` / `encodeDraftParams` on the SQL runtime) because lowering is target-owned through the adapter on the execution stack. Rationale and SQL contrast: [ADR 215 — Mongo family: lifecycle parity and intentional placement asymmetries](../../../../docs/architecture%20docs/adrs/ADR%20215%20-%20Runtime%20middleware%20lifecycle%20beforeExecute%20before%20encodeParams.md#mongo-family-lifecycle-parity-and-intentional-placement-asymmetries).
 - **Driver interface**: `MongoDriver` — defines `execute<Row>(wireCommand): AsyncIterable<Row>` and `close()`, the contract for sending wire commands to a MongoDB instance
 
 ## Dependencies

package/dist/index.d.mts

@@ -3,26 +3,134 @@ import { MongoQueryPlan } from "@prisma-next/mongo-query-ast/execution";
 import { AnyMongoWireCommand } from "@prisma-next/mongo-wire";
 
 //#region src/adapter-types.d.ts
+/**
+ * Intermediate state produced by structural lowering. `MongoParamRef` leaves
+ * remain in place — they have not yet been resolved through codecs. The
+ * runtime defers value resolution past the `beforeExecute` middleware chain
+ * so middleware can walk and rewrite `MongoParamRef` nodes before encoding.
+ *
+ * All document/filter/update slots that may carry `MongoParamRef` nodes are
+ * typed as `Record<string, unknown>` to allow heterogeneous values. Raw
+ * command variants carry already-resolved `Record<string, unknown>` values
+ * and pass through unchanged.
+ */
+type MongoLoweredDraft = {
+  readonly kind: 'insertOne';
+  readonly collection: string;
+  readonly document: Record<string, unknown>;
+} | {
+  readonly kind: 'insertMany';
+  readonly collection: string;
+  readonly documents: ReadonlyArray<Record<string, unknown>>;
+} | {
+  readonly kind: 'updateOne';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+  readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+  readonly upsert: boolean | undefined;
+} | {
+  readonly kind: 'updateMany';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+  readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+  readonly upsert: boolean | undefined;
+} | {
+  readonly kind: 'deleteOne';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+} | {
+  readonly kind: 'deleteMany';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+} | {
+  readonly kind: 'findOneAndUpdate';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+  readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+  readonly upsert: boolean | undefined;
+  readonly sort: Record<string, 1 | -1> | undefined;
+  readonly returnDocument: 'before' | 'after' | undefined;
+} | {
+  readonly kind: 'findOneAndDelete';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+  readonly sort: Record<string, 1 | -1> | undefined;
+} | {
+  readonly kind: 'aggregate';
+  readonly collection: string;
+  readonly pipeline: ReadonlyArray<Record<string, unknown>>;
+} | {
+  readonly kind: 'rawInsertOne';
+  readonly collection: string;
+  readonly document: Record<string, unknown>;
+} | {
+  readonly kind: 'rawInsertMany';
+  readonly collection: string;
+  readonly documents: ReadonlyArray<Record<string, unknown>>;
+} | {
+  readonly kind: 'rawUpdateOne';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+  readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+} | {
+  readonly kind: 'rawUpdateMany';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+  readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+} | {
+  readonly kind: 'rawDeleteOne';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+} | {
+  readonly kind: 'rawDeleteMany';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+} | {
+  readonly kind: 'rawFindOneAndUpdate';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+  readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+  readonly upsert: boolean;
+  readonly sort: Record<string, 1 | -1> | undefined;
+  readonly returnDocument: 'before' | 'after' | undefined;
+} | {
+  readonly kind: 'rawFindOneAndDelete';
+  readonly collection: string;
+  readonly filter: Record<string, unknown>;
+  readonly sort: Record<string, 1 | -1> | undefined;
+} | {
+  readonly kind: 'rawAggregate';
+  readonly collection: string;
+  readonly pipeline: ReadonlyArray<Record<string, unknown>>;
+};
 interface MongoAdapter {
   /**
    * Lower a `MongoQueryPlan` to a driver-ready wire command.
    *
-   * `ctx` carries the per-`runtime.execute()` context — today just an
-   * `AbortSignal` for cooperative cancellation. The runtime allocates one
-   * ctx per execute and threads the same reference through
-   * `lower → resolveValue → codec.encode`, so codec authors observe
-   * **signal identity** across the whole encode dispatch. The `signal`
-   * field inside the ctx may be `undefined`, but the ctx object itself
-   * is always present.
-   *
-   * Implementations are expected to:
-   * - Pass `ctx` through to every `resolveValue` call so the per-level
-   *   `Promise.all` race can observe the signal.
-   * - Surface `RUNTIME.ABORTED { phase: 'encode' }` (via `runtimeAborted`)
-   *   from inside `resolveValue` when the signal aborts mid-flight; no
-   *   adapter-level abort handling is required beyond ctx forwarding.
+   * Equivalent to `resolveParams(structuralLower(plan), ctx)`. Preserved for
+   * callers that do not need the two-phase split.
    */
   lower(plan: MongoQueryPlan, ctx: CodecCallContext): Promise<AnyMongoWireCommand>;
+  /**
+   * Phase 1 of the two-phase lowering pipeline.
+   *
+   * Transforms the plan's command AST into the lowered wire shape **without**
+   * calling `resolveValue` on any `MongoParamRef` leaf. All filter predicates,
+   * document fields, and pipeline stage values that carry `MongoParamRef`
+   * nodes are preserved in the returned `MongoLoweredDraft` so that the
+   * `beforeExecute` middleware chain can inspect and rewrite them before
+   * encoding runs. Synchronous — no I/O or codec calls.
+   */
+  structuralLower(plan: MongoQueryPlan): MongoLoweredDraft;
+  /**
+   * Phase 2 of the two-phase lowering pipeline.
+   *
+   * Walks the `MongoLoweredDraft` produced by `structuralLower`, resolves
+   * every `MongoParamRef` leaf through the codec registry, and constructs the
+   * frozen `AnyMongoWireCommand` ready for the driver. The same abort-signal
+   * forwarding and `RUNTIME.ABORTED` surface contract as `lower` applies.
+   */
+  resolveParams(draft: MongoLoweredDraft, ctx: CodecCallContext): Promise<AnyMongoWireCommand>;
 }
 //#endregion
 //#region src/driver-types.d.ts
@@ -31,5 +139,5 @@ interface MongoDriver {
   close(): Promise<void>;
 }
 //#endregion
-export { type MongoAdapter, type MongoDriver };
+export { type MongoAdapter, type MongoDriver, type MongoLoweredDraft };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/adapter-types.ts","../src/driver-types.ts"],"mappings":";;;;;UAIiB,YAAA;;AAAjB;;;;;;;;;;;;;;;;;EAmBE,KAAA,CAAM,IAAA,EAAM,cAAA,EAAgB,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,mBAAA;AAAA;;;UCrB7C,WAAA;EACf,OAAA,MAAa,WAAA,EAAa,mBAAA,GAAsB,aAAA,CAAc,GAAA;EAC9D,KAAA,IAAS,OAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/adapter-types.ts","../src/driver-types.ts"],"mappings":";;;;;;;AAeA;;;;;;;;;KAAY,iBAAA;EAAA,SAEG,IAAA;EAAA,SACA,UAAA;EAAA,SACA,QAAA,EAAU,MAAA;AAAA;EAAA,SAGV,IAAA;EAAA,SACA,UAAA;EAAA,SACA,SAAA,EAAW,aAAA,CAAc,MAAA;AAAA;EAAA,SAGzB,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;EAAA,SACR,MAAA,EAAQ,MAAA,oBAA0B,aAAA,CAAc,MAAA;EAAA,SAChD,MAAA;AAAA;EAAA,SAGA,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;EAAA,SACR,MAAA,EAAQ,MAAA,oBAA0B,aAAA,CAAc,MAAA;EAAA,SAChD,MAAA;AAAA;EAAA,SAGA,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;AAAA;EAAA,SAGR,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;AAAA;EAAA,SAGR,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;EAAA,SACR,MAAA,EAAQ,MAAA,oBAA0B,aAAA,CAAc,MAAA;EAAA,SAChD,MAAA;EAAA,SACA,IAAA,EAAM,MAAA;EAAA,SACN,cAAA;AAAA;EAAA,SAGA,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;EAAA,SACR,IAAA,EAAM,MAAA;AAAA;EAAA,SAGN,IAAA;EAAA,SACA,UAAA;EAAA,SACA,QAAA,EAAU,aAAA,CAAc,MAAA;AAAA;EAAA,SAGxB,IAAA;EAAA,SACA,UAAA;EAAA,SACA,QAAA,EAAU,MAAA;AAAA;EAAA,SAGV,IAAA;EAAA,SACA,UAAA;EAAA,SACA,SAAA,EAAW,aAAA,CAAc,MAAA;AAAA;EAAA,SAGzB,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;EAAA,SACR,MAAA,EAAQ,MAAA,oBAA0B,aAAA,CAAc,MAAA;AAAA;EAAA,SAGhD,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;EAAA,SACR,MAAA,EAAQ,MAAA,oBAA0B,aAAA,CAAc,MAAA;AAAA;EAAA,SAGhD,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;AAAA;EAAA,SAGR,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;AAAA;EAAA,SAGR,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;EAAA,SACR,MAAA,EAAQ,MAAA,oBAA0B,aAAA,CAAc,MAAA;EAAA,SAChD,MAAA;EAAA,SACA,IAAA,EAAM,MAAA;EAAA,SACN,cAAA;AAAA;EAAA,SAGA,IAAA;EAAA,SACA,UAAA;EAAA,SACA,MAAA,EAAQ,MAAA;EAAA,SACR,IAAA,EAAM,MAAA;AAAA;EAAA,SAGN,IAAA;EAAA,SACA,UAAA;EAAA,SACA,QAAA,EAAU,aAAA,CAAc,MAAA;AAAA;AAAA,UAGtB,YAAA;EA7DM;;;;;;EAoErB,KAAA,CAAM,IAAA,EAAM,cAAA,EAAgB,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,mBAAA;EA9DvB;;;;;;;;;;EA0ErC,eAAA,CAAgB,IAAA,EAAM,cAAA,GAAiB,iBAAA;EA5D1B;;;;;;;;EAsEb,aAAA,CAAc,KAAA,EAAO,iBAAA,EAAmB,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,mBAAA;AAAA;;;UCtJzD,WAAA;EACf,OAAA,MAAa,WAAA,EAAa,mBAAA,GAAsB,aAAA,CAAc,GAAA;EAC9D,KAAA,IAAS,OAAA;AAAA"}

package/package.json

@@ -1,31 +1,42 @@
 {
   "name": "@prisma-next/mongo-lowering",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "Adapter and driver interfaces for Prisma Next MongoDB lowering",
   "dependencies": {
-    "@prisma-next/framework-components": "0.11.0",
-    "@prisma-next/mongo-query-ast": "0.11.0",
-    "@prisma-next/mongo-wire": "0.11.0"
+    "@prisma-next/framework-components": "0.12.0",
+    "@prisma-next/mongo-query-ast": "0.12.0",
+    "@prisma-next/mongo-wire": "0.12.0"
   },
   "devDependencies": {
-    "@prisma-next/tsconfig": "0.11.0",
-    "@prisma-next/tsdown": "0.11.0",
+    "@prisma-next/tsconfig": "0.12.0",
+    "@prisma-next/tsdown": "0.12.0",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",
     "vitest": "4.1.6"
   },
+  "peerDependencies": {
+    "typescript": ">=5.9"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
   "files": [
     "dist",
     "src"
   ],
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": "./dist/index.mjs",
     "./package.json": "./package.json"
   },
-  "types": "./dist/index.d.mts",
+  "engines": {
+    "node": ">=24"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/prisma/prisma-next.git",

package/src/adapter-types.ts

@@ -2,24 +2,153 @@ import type { CodecCallContext } from '@prisma-next/framework-components/codec';
 import type { MongoQueryPlan } from '@prisma-next/mongo-query-ast/execution';
 import type { AnyMongoWireCommand } from '@prisma-next/mongo-wire';
 
+/**
+ * Intermediate state produced by structural lowering. `MongoParamRef` leaves
+ * remain in place — they have not yet been resolved through codecs. The
+ * runtime defers value resolution past the `beforeExecute` middleware chain
+ * so middleware can walk and rewrite `MongoParamRef` nodes before encoding.
+ *
+ * All document/filter/update slots that may carry `MongoParamRef` nodes are
+ * typed as `Record<string, unknown>` to allow heterogeneous values. Raw
+ * command variants carry already-resolved `Record<string, unknown>` values
+ * and pass through unchanged.
+ */
+export type MongoLoweredDraft =
+  | {
+      readonly kind: 'insertOne';
+      readonly collection: string;
+      readonly document: Record<string, unknown>;
+    }
+  | {
+      readonly kind: 'insertMany';
+      readonly collection: string;
+      readonly documents: ReadonlyArray<Record<string, unknown>>;
+    }
+  | {
+      readonly kind: 'updateOne';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+      readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+      readonly upsert: boolean | undefined;
+    }
+  | {
+      readonly kind: 'updateMany';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+      readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+      readonly upsert: boolean | undefined;
+    }
+  | {
+      readonly kind: 'deleteOne';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+    }
+  | {
+      readonly kind: 'deleteMany';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+    }
+  | {
+      readonly kind: 'findOneAndUpdate';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+      readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+      readonly upsert: boolean | undefined;
+      readonly sort: Record<string, 1 | -1> | undefined;
+      readonly returnDocument: 'before' | 'after' | undefined;
+    }
+  | {
+      readonly kind: 'findOneAndDelete';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+      readonly sort: Record<string, 1 | -1> | undefined;
+    }
+  | {
+      readonly kind: 'aggregate';
+      readonly collection: string;
+      readonly pipeline: ReadonlyArray<Record<string, unknown>>;
+    }
+  | {
+      readonly kind: 'rawInsertOne';
+      readonly collection: string;
+      readonly document: Record<string, unknown>;
+    }
+  | {
+      readonly kind: 'rawInsertMany';
+      readonly collection: string;
+      readonly documents: ReadonlyArray<Record<string, unknown>>;
+    }
+  | {
+      readonly kind: 'rawUpdateOne';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+      readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+    }
+  | {
+      readonly kind: 'rawUpdateMany';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+      readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+    }
+  | {
+      readonly kind: 'rawDeleteOne';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+    }
+  | {
+      readonly kind: 'rawDeleteMany';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+    }
+  | {
+      readonly kind: 'rawFindOneAndUpdate';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+      readonly update: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
+      readonly upsert: boolean;
+      readonly sort: Record<string, 1 | -1> | undefined;
+      readonly returnDocument: 'before' | 'after' | undefined;
+    }
+  | {
+      readonly kind: 'rawFindOneAndDelete';
+      readonly collection: string;
+      readonly filter: Record<string, unknown>;
+      readonly sort: Record<string, 1 | -1> | undefined;
+    }
+  | {
+      readonly kind: 'rawAggregate';
+      readonly collection: string;
+      readonly pipeline: ReadonlyArray<Record<string, unknown>>;
+    };
+
 export interface MongoAdapter {
   /**
    * Lower a `MongoQueryPlan` to a driver-ready wire command.
    *
-   * `ctx` carries the per-`runtime.execute()` context — today just an
-   * `AbortSignal` for cooperative cancellation. The runtime allocates one
-   * ctx per execute and threads the same reference through
-   * `lower → resolveValue → codec.encode`, so codec authors observe
-   * **signal identity** across the whole encode dispatch. The `signal`
-   * field inside the ctx may be `undefined`, but the ctx object itself
-   * is always present.
-   *
-   * Implementations are expected to:
-   * - Pass `ctx` through to every `resolveValue` call so the per-level
-   *   `Promise.all` race can observe the signal.
-   * - Surface `RUNTIME.ABORTED { phase: 'encode' }` (via `runtimeAborted`)
-   *   from inside `resolveValue` when the signal aborts mid-flight; no
-   *   adapter-level abort handling is required beyond ctx forwarding.
+   * Equivalent to `resolveParams(structuralLower(plan), ctx)`. Preserved for
+   * callers that do not need the two-phase split.
    */
   lower(plan: MongoQueryPlan, ctx: CodecCallContext): Promise<AnyMongoWireCommand>;
+
+  /**
+   * Phase 1 of the two-phase lowering pipeline.
+   *
+   * Transforms the plan's command AST into the lowered wire shape **without**
+   * calling `resolveValue` on any `MongoParamRef` leaf. All filter predicates,
+   * document fields, and pipeline stage values that carry `MongoParamRef`
+   * nodes are preserved in the returned `MongoLoweredDraft` so that the
+   * `beforeExecute` middleware chain can inspect and rewrite them before
+   * encoding runs. Synchronous — no I/O or codec calls.
+   */
+  structuralLower(plan: MongoQueryPlan): MongoLoweredDraft;
+
+  /**
+   * Phase 2 of the two-phase lowering pipeline.
+   *
+   * Walks the `MongoLoweredDraft` produced by `structuralLower`, resolves
+   * every `MongoParamRef` leaf through the codec registry, and constructs the
+   * frozen `AnyMongoWireCommand` ready for the driver. The same abort-signal
+   * forwarding and `RUNTIME.ABORTED` surface contract as `lower` applies.
+   */
+  resolveParams(draft: MongoLoweredDraft, ctx: CodecCallContext): Promise<AnyMongoWireCommand>;
 }

package/src/exports/index.ts

@@ -1,2 +1,2 @@
-export type { MongoAdapter } from '../adapter-types';
+export type { MongoAdapter, MongoLoweredDraft } from '../adapter-types';
 export type { MongoDriver } from '../driver-types';