@prisma-next/mongo-runtime 0.5.0-dev.4 → 0.5.0-dev.42

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@prisma-next/mongo-runtime",
-  "version": "0.5.0-dev.4",
+  "version": "0.5.0-dev.42",
   "type": "module",
   "sideEffects": false,
   "description": "MongoDB runtime implementation for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.5.0-dev.4",
-    "@prisma-next/framework-components": "0.5.0-dev.4",
-    "@prisma-next/mongo-lowering": "0.5.0-dev.4",
-    "@prisma-next/mongo-query-ast": "0.5.0-dev.4"
+    "@prisma-next/framework-components": "0.5.0-dev.42",
+    "@prisma-next/contract": "0.5.0-dev.42",
+    "@prisma-next/mongo-lowering": "0.5.0-dev.42",
+    "@prisma-next/mongo-query-ast": "0.5.0-dev.42",
+    "@prisma-next/mongo-wire": "0.5.0-dev.42",
+    "@prisma-next/mongo-codec": "0.5.0-dev.42",
+    "@prisma-next/utils": "0.5.0-dev.42"
   },
   "devDependencies": {
     "mongodb": "^6.16.0",
@@ -16,19 +19,18 @@
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
-    "@prisma-next/middleware-telemetry": "0.5.0-dev.4",
-    "@prisma-next/adapter-mongo": "0.5.0-dev.4",
-    "@prisma-next/runtime-executor": "0.5.0-dev.4",
-    "@prisma-next/mongo-contract-ts": "0.5.0-dev.4",
-    "@prisma-next/family-mongo": "0.5.0-dev.4",
-    "@prisma-next/mongo-query-builder": "0.5.0-dev.4",
-    "@prisma-next/mongo-value": "0.5.0-dev.4",
-    "@prisma-next/driver-mongo": "0.5.0-dev.4",
+    "@prisma-next/adapter-mongo": "0.5.0-dev.42",
+    "@prisma-next/middleware-telemetry": "0.5.0-dev.42",
+    "@prisma-next/mongo-contract-ts": "0.5.0-dev.42",
+    "@prisma-next/family-mongo": "0.5.0-dev.42",
+    "@prisma-next/mongo-query-builder": "0.5.0-dev.42",
+    "@prisma-next/mongo-value": "0.5.0-dev.42",
+    "@prisma-next/driver-mongo": "0.5.0-dev.42",
+    "@prisma-next/target-mongo": "0.5.0-dev.42",
+    "@prisma-next/mongo-contract": "0.5.0-dev.42",
     "@prisma-next/test-utils": "0.0.1",
-    "@prisma-next/target-mongo": "0.5.0-dev.4",
     "@prisma-next/tsconfig": "0.0.0",
-    "@prisma-next/tsdown": "0.0.0",
-    "@prisma-next/mongo-contract": "0.5.0-dev.4"
+    "@prisma-next/tsdown": "0.0.0"
   },
   "files": [
     "dist",

package/src/codecs/decoding.ts

@@ -0,0 +1,170 @@
+import type { CodecCallContext } from '@prisma-next/framework-components/codec';
+import { runtimeError } from '@prisma-next/framework-components/runtime';
+import type { MongoFieldShape, MongoResultShape } from '@prisma-next/mongo-query-ast/execution';
+import type { MongoCodecLookup } from '../mongo-execution-stack';
+
+const WIRE_PREVIEW_LIMIT = 100;
+
+function previewWireValue(wireValue: unknown): string {
+  if (typeof wireValue === 'string') {
+    return wireValue.length > WIRE_PREVIEW_LIMIT
+      ? `${wireValue.substring(0, WIRE_PREVIEW_LIMIT)}...`
+      : wireValue;
+  }
+  return String(wireValue).substring(0, WIRE_PREVIEW_LIMIT);
+}
+
+function wrapDecodeFailure(
+  error: unknown,
+  collection: string,
+  path: string,
+  codecId: string,
+  wireValue: unknown,
+): never {
+  const message = error instanceof Error ? error.message : String(error);
+  const wrapped = runtimeError(
+    'RUNTIME.DECODE_FAILED',
+    `Failed to decode field ${path} in collection '${collection}' with codec '${codecId}': ${message}`,
+    {
+      collection,
+      path,
+      codec: codecId,
+      wirePreview: previewWireValue(wireValue),
+    },
+  );
+  wrapped.cause = error;
+  throw wrapped;
+}
+
+export async function decodeMongoRow(
+  row: unknown,
+  shape: MongoResultShape,
+  registry: MongoCodecLookup,
+  collection: string,
+  ctx: CodecCallContext = {},
+): Promise<unknown> {
+  if (shape.kind === 'unknown') {
+    return row;
+  }
+  if (typeof row !== 'object' || row === null) {
+    return row;
+  }
+  const rowObj = row as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  const tasks: Array<Promise<void>> = [];
+
+  function scheduleLeaf(
+    path: string,
+    codecId: string,
+    wire: unknown,
+    assign: (v: unknown) => void,
+  ): void {
+    const codec = registry.get(codecId);
+    if (!codec) {
+      assign(wire);
+      return;
+    }
+    tasks.push(
+      (async () => {
+        try {
+          assign(await codec.decode(wire, ctx));
+        } catch (error) {
+          wrapDecodeFailure(error, collection, path, codecId, wire);
+        }
+      })(),
+    );
+  }
+
+  function walkField(
+    value: unknown,
+    fieldShape: MongoFieldShape,
+    path: string,
+    assign: (v: unknown) => void,
+  ): void {
+    // Exhaustive over `MongoFieldShape['kind']` by construction:
+    // adding a new variant must add a corresponding arm or the
+    // `satisfies never` below would error at type-check time.
+    switch (fieldShape.kind) {
+      case 'unknown':
+        assign(value);
+        return;
+      case 'leaf':
+        if (value === null || value === undefined) {
+          assign(value);
+          return;
+        }
+        scheduleLeaf(path, fieldShape.codecId, value, assign);
+        return;
+      case 'document': {
+        if (value === null || value === undefined) {
+          assign(value);
+          return;
+        }
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+          assign(value);
+          return;
+        }
+        const vObj = value as Record<string, unknown>;
+        // Pre-seed with a shallow copy so unshaped subdocument keys
+        // round-trip verbatim. Subsequent walkField assignments overwrite
+        // shaped keys with their decoded values. Mirrors the top-level
+        // pass-through invariant — the decode path is structurally
+        // additive at every nesting depth, not just the root.
+        const nested: Record<string, unknown> = { ...vObj };
+        assign(nested);
+        for (const [fk, fShape] of Object.entries(fieldShape.fields)) {
+          walkField(vObj[fk], fShape, `${path}.${fk}`, (v) => {
+            nested[fk] = v;
+          });
+        }
+        return;
+      }
+      case 'array': {
+        if (value === null || value === undefined) {
+          assign(value);
+          return;
+        }
+        if (!Array.isArray(value)) {
+          assign(value);
+          return;
+        }
+        const arr: unknown[] = [];
+        assign(arr);
+        for (let i = 0; i < value.length; i++) {
+          const el = value[i];
+          walkField(el, fieldShape.element, `${path}.${i}`, (v) => {
+            arr[i] = v;
+          });
+        }
+        return;
+      }
+    }
+    // The switch above is exhaustive over `MongoFieldShape['kind']`. The
+    // `satisfies never` below is a compile-time guard that fails if a new
+    // variant is added without a corresponding arm.
+    /* v8 ignore start */
+    fieldShape satisfies never;
+    /* v8 ignore stop */
+  }
+
+  for (const [k, fShape] of Object.entries(shape.fields)) {
+    walkField(rowObj[k], fShape, k, (v) => {
+      out[k] = v;
+    });
+  }
+
+  // Pass through any row fields the shape does not describe. The shape is a
+  // partial, lane-vouched description of what the runtime knows how to decode;
+  // fields outside that description (e.g. polymorphic variant fields the base
+  // model's shape doesn't enumerate, sidecar fields a future schema migration
+  // adds) round-trip verbatim. Drop semantics belongs to explicit projection
+  // (`select` / `$project`), not to the structural decode path.
+  for (const k of Object.keys(rowObj)) {
+    if (!Object.hasOwn(shape.fields, k)) {
+      out[k] = rowObj[k];
+    }
+  }
+
+  await Promise.all(tasks);
+  return out;
+}

package/src/exports/index.ts

@@ -1,3 +1,20 @@
+export type { RuntimeTargetInstance } from '@prisma-next/framework-components/execution';
+export type { MongoExecutionPlan } from '../mongo-execution-plan';
+export type {
+  MongoCodecLookup,
+  MongoExecutionContext,
+  MongoExecutionStack,
+  MongoRuntimeAdapterDescriptor,
+  MongoRuntimeAdapterInstance,
+  MongoRuntimeExtensionDescriptor,
+  MongoRuntimeExtensionInstance,
+  MongoRuntimeTargetDescriptor,
+  MongoStaticContributions,
+} from '../mongo-execution-stack';
+export {
+  createMongoExecutionContext,
+  createMongoExecutionStack,
+} from '../mongo-execution-stack';
 export type { MongoMiddleware, MongoMiddlewareContext } from '../mongo-middleware';
 export type { MongoRuntime, MongoRuntimeOptions } from '../mongo-runtime';
 export { createMongoRuntime } from '../mongo-runtime';

package/src/mongo-execution-plan.ts

@@ -0,0 +1,28 @@
+import type { ExecutionPlan } from '@prisma-next/framework-components/runtime';
+import type { MongoResultShape } from '@prisma-next/mongo-query-ast/execution';
+import type { AnyMongoWireCommand } from '@prisma-next/mongo-wire';
+
+/**
+ * Mongo-domain execution plan: a query lowered to the wire-command shape
+ * that a Mongo driver can run.
+ *
+ * The plan carries:
+ * - `command` — the wire command (e.g. `InsertOneWireCommand`,
+ *   `AggregateWireCommand`) produced by `MongoAdapter.lower(plan)`
+ * - `meta` — family-agnostic plan metadata (target, lane, hashes, ...)
+ * - `_row` — phantom row type, propagated from the originating
+ *   `MongoQueryPlan`
+ *
+ * Extends the framework-level `ExecutionPlan<Row>` marker so generic SPIs
+ * (`RuntimeExecutor<MongoExecutionPlan>`,
+ * `RuntimeMiddleware<MongoExecutionPlan>`) can be parameterized over it.
+ *
+ * Lives in the runtime layer (alongside `MongoRuntime`) because the wire
+ * command shape lives in the transport layer (`@prisma-next/mongo-wire`),
+ * which the lanes layer (`mongo-query-ast`, where `MongoQueryPlan` lives)
+ * cannot depend on.
+ */
+export interface MongoExecutionPlan<Row = unknown> extends ExecutionPlan<Row> {
+  readonly command: AnyMongoWireCommand;
+  readonly resultShape?: MongoResultShape;
+}

package/src/mongo-execution-stack.ts

@@ -0,0 +1,171 @@
+import {
+  createExecutionStack,
+  type ExecutionStack,
+  type RuntimeAdapterDescriptor,
+  type RuntimeAdapterInstance,
+  type RuntimeDriverDescriptor,
+  type RuntimeDriverInstance,
+  type RuntimeExtensionDescriptor,
+  type RuntimeExtensionInstance,
+  type RuntimeTargetDescriptor,
+  type RuntimeTargetInstance,
+} from '@prisma-next/framework-components/execution';
+import { runtimeError } from '@prisma-next/framework-components/runtime';
+import type { MongoCodec } from '@prisma-next/mongo-codec';
+import { createMongoCodecRegistry, type MongoCodecRegistry } from '@prisma-next/mongo-codec';
+import type { MongoAdapter } from '@prisma-next/mongo-lowering';
+
+/**
+ * Mongo-specific static contributions a runtime descriptor declares.
+ *
+ * Mirrors `SqlStaticContributions` in shape: a `codecs()` getter that yields
+ * a `MongoCodecRegistry` populated with this contributor's codecs. The
+ * registry is then walked by `createMongoExecutionContext` and folded into
+ * the single per-execution registry the runtime reads from at decode time.
+ */
+export interface MongoStaticContributions {
+  readonly codecs: () => MongoCodecRegistry;
+}
+
+export interface MongoRuntimeTargetDescriptor<
+  TTargetId extends string = 'mongo',
+  TTargetInstance extends RuntimeTargetInstance<'mongo', TTargetId> = RuntimeTargetInstance<
+    'mongo',
+    TTargetId
+  >,
+> extends RuntimeTargetDescriptor<'mongo', TTargetId, TTargetInstance>,
+    MongoStaticContributions {}
+
+export interface MongoRuntimeAdapterInstance<TTargetId extends string = 'mongo'>
+  extends RuntimeAdapterInstance<'mongo', TTargetId>,
+    MongoAdapter {}
+
+export interface MongoRuntimeAdapterDescriptor<
+  TTargetId extends string = 'mongo',
+  TAdapterInstance extends RuntimeAdapterInstance<
+    'mongo',
+    TTargetId
+  > = MongoRuntimeAdapterInstance<TTargetId>,
+> extends RuntimeAdapterDescriptor<'mongo', TTargetId, TAdapterInstance>,
+    MongoStaticContributions {}
+
+export interface MongoRuntimeExtensionInstance<TTargetId extends string = 'mongo'>
+  extends RuntimeExtensionInstance<'mongo', TTargetId> {}
+
+export interface MongoRuntimeExtensionDescriptor<TTargetId extends string = 'mongo'>
+  extends RuntimeExtensionDescriptor<'mongo', TTargetId, MongoRuntimeExtensionInstance<TTargetId>>,
+    MongoStaticContributions {
+  create(): MongoRuntimeExtensionInstance<TTargetId>;
+}
+
+/**
+ * The Mongo execution stack: target + adapter + optional driver + extension
+ * packs. Mirrors `SqlExecutionStack`. Constructed via
+ * `createMongoExecutionStack`.
+ */
+export interface MongoExecutionStack<TTargetId extends string = 'mongo'> {
+  readonly target: MongoRuntimeTargetDescriptor<TTargetId>;
+  readonly adapter: MongoRuntimeAdapterDescriptor<TTargetId>;
+  readonly driver:
+    | RuntimeDriverDescriptor<
+        'mongo',
+        TTargetId,
+        unknown,
+        RuntimeDriverInstance<'mongo', TTargetId>
+      >
+    | undefined;
+  readonly extensionPacks: readonly MongoRuntimeExtensionDescriptor<TTargetId>[];
+}
+
+export function createMongoExecutionStack<TTargetId extends string = 'mongo'>(options: {
+  readonly target: MongoRuntimeTargetDescriptor<TTargetId>;
+  readonly adapter: MongoRuntimeAdapterDescriptor<TTargetId>;
+  readonly driver?:
+    | RuntimeDriverDescriptor<
+        'mongo',
+        TTargetId,
+        unknown,
+        RuntimeDriverInstance<'mongo', TTargetId>
+      >
+    | undefined;
+  readonly extensionPacks?: readonly MongoRuntimeExtensionDescriptor<TTargetId>[] | undefined;
+}): MongoExecutionStack<TTargetId> {
+  const stack = createExecutionStack({
+    target: options.target,
+    adapter: options.adapter,
+    driver: options.driver,
+    extensionPacks: options.extensionPacks,
+  });
+  return stack as ExecutionStack<'mongo', TTargetId> as MongoExecutionStack<TTargetId>;
+}
+
+/**
+ * Read-only view of the codec registry exposed on `MongoExecutionContext`.
+ *
+ * Hides `register()` and the iterator from public surface — users do not
+ * mutate the per-execution codec registry. Internal aggregation in
+ * `createMongoExecutionContext` keeps using the full `MongoCodecRegistry`
+ * (it needs `register()`).
+ */
+export interface MongoCodecLookup {
+  get(id: string): MongoCodec<string> | undefined;
+  has(id: string): boolean;
+}
+
+/**
+ * Per-execution context aggregated from a `MongoExecutionStack`.
+ *
+ * Carries the user's contract, a read-only lookup over the codec registry
+ * composed from every stack contributor, and a back-reference to the stack
+ * itself so the runtime can reach the adapter without users threading it
+ * explicitly.
+ *
+ * Mirrors SQL's `ExecutionContext` in role; Mongo's flavour is leaner
+ * because there are no parameterised codecs, JSON-schema validators, or
+ * mutation-default generators in scope yet.
+ */
+export interface MongoExecutionContext<TTargetId extends string = 'mongo'> {
+  readonly contract: unknown;
+  readonly codecs: MongoCodecLookup;
+  readonly stack: MongoExecutionStack<TTargetId>;
+}
+
+export function createMongoExecutionContext<TTargetId extends string = 'mongo'>(options: {
+  readonly contract: unknown;
+  readonly stack: MongoExecutionStack<TTargetId>;
+}): MongoExecutionContext<TTargetId> {
+  const registry = createMongoCodecRegistry();
+  const owners = new Map<string, string>();
+
+  const contributors: ReadonlyArray<MongoStaticContributions & { readonly id: string }> = [
+    options.stack.target,
+    options.stack.adapter,
+    ...options.stack.extensionPacks,
+  ];
+
+  for (const contributor of contributors) {
+    const contributed = contributor.codecs();
+    for (const codec of iterateCodecs(contributed)) {
+      const existingOwner = owners.get(codec.id);
+      if (existingOwner !== undefined) {
+        throw runtimeError(
+          'RUNTIME.DUPLICATE_CODEC',
+          `Duplicate Mongo codec id '${codec.id}' contributed by '${contributor.id}' (already registered by '${existingOwner}').`,
+          { codecId: codec.id, existingOwner, incomingOwner: contributor.id },
+        );
+      }
+      registry.register(codec);
+      owners.set(codec.id, contributor.id);
+    }
+  }
+
+  return Object.freeze({
+    contract: options.contract,
+    codecs: registry,
+    stack: options.stack,
+  });
+}
+
+function* iterateCodecs(registry: MongoCodecRegistry): Iterable<MongoCodec<string>> {
+  yield* registry.values();
+}

package/src/mongo-middleware.ts

@@ -3,20 +3,31 @@ import type {
   RuntimeMiddleware,
   RuntimeMiddlewareContext,
 } from '@prisma-next/framework-components/runtime';
-import type { MongoQueryPlan } from '@prisma-next/mongo-query-ast/execution';
+import type { MongoExecutionPlan } from './mongo-execution-plan';
 
 export interface MongoMiddlewareContext extends RuntimeMiddlewareContext {}
 
-export interface MongoMiddleware extends RuntimeMiddleware {
-  readonly familyId: 'mongo';
-  beforeExecute?(plan: MongoQueryPlan, ctx: MongoMiddlewareContext): Promise<void>;
+/**
+ * Mongo-domain middleware. Extends the framework `RuntimeMiddleware`
+ * parameterized over `MongoExecutionPlan` because `runWithMiddleware`
+ * (driven by `RuntimeCore`) invokes the lifecycle hooks with the
+ * post-lowering plan.
+ *
+ * `familyId` is optional so generic cross-family middleware (e.g.
+ * telemetry) — which carry no `familyId` — remain assignable. When
+ * present, it must be `'mongo'`; the runtime rejects mismatches at
+ * construction time via `checkMiddlewareCompatibility`.
+ */
+export interface MongoMiddleware extends RuntimeMiddleware<MongoExecutionPlan> {
+  readonly familyId?: 'mongo';
+  beforeExecute?(plan: MongoExecutionPlan, ctx: MongoMiddlewareContext): Promise<void>;
   onRow?(
     row: Record<string, unknown>,
-    plan: MongoQueryPlan,
+    plan: MongoExecutionPlan,
     ctx: MongoMiddlewareContext,
   ): Promise<void>;
   afterExecute?(
-    plan: MongoQueryPlan,
+    plan: MongoExecutionPlan,
     result: AfterExecuteResult,
     ctx: MongoMiddlewareContext,
   ): Promise<void>;