@prisma-next/framework-components 0.5.0-dev.5 → 0.5.0-dev.51

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 (86) hide show
  1. package/README.md +61 -0
  2. package/dist/authoring.d.mts +1 -1
  3. package/dist/authoring.mjs +1 -1
  4. package/dist/authoring.mjs.map +1 -1
  5. package/dist/codec-types-CB0jWeHU.d.mts +207 -0
  6. package/dist/codec-types-CB0jWeHU.d.mts.map +1 -0
  7. package/dist/codec.d.mts +2 -2
  8. package/dist/codec.mjs +38 -2
  9. package/dist/codec.mjs.map +1 -1
  10. package/dist/components.d.mts +1 -1
  11. package/dist/components.mjs +1 -1
  12. package/dist/control.d.mts +109 -70
  13. package/dist/control.d.mts.map +1 -1
  14. package/dist/control.mjs +11 -5
  15. package/dist/control.mjs.map +1 -1
  16. package/dist/emission-types-D6t3_a0x.d.mts +39 -0
  17. package/dist/emission-types-D6t3_a0x.d.mts.map +1 -0
  18. package/dist/emission.d.mts +2 -2
  19. package/dist/execution.d.mts +5 -5
  20. package/dist/execution.d.mts.map +1 -1
  21. package/dist/execution.mjs +3 -3
  22. package/dist/execution.mjs.map +1 -1
  23. package/dist/{framework-authoring-D1-JZ37B.d.mts → framework-authoring-BdrFDx4x.d.mts} +2 -2
  24. package/dist/framework-authoring-BdrFDx4x.d.mts.map +1 -0
  25. package/dist/{framework-components-EJXe-pum.d.mts → framework-components-AHI6V96G.d.mts} +6 -6
  26. package/dist/framework-components-AHI6V96G.d.mts.map +1 -0
  27. package/dist/{framework-components-C8ZhSwXe.mjs → framework-components-BsWST1Rn.mjs} +2 -2
  28. package/dist/framework-components-BsWST1Rn.mjs.map +1 -0
  29. package/dist/psl-ast-9X5rwo98.d.mts +159 -0
  30. package/dist/psl-ast-9X5rwo98.d.mts.map +1 -0
  31. package/dist/psl-ast.d.mts +2 -0
  32. package/dist/psl-ast.mjs +1 -0
  33. package/dist/runtime.d.mts +346 -19
  34. package/dist/runtime.d.mts.map +1 -1
  35. package/dist/runtime.mjs +256 -4
  36. package/dist/runtime.mjs.map +1 -1
  37. package/dist/{types-import-spec-C4sc7wbb.d.mts → types-import-spec-D-O6GotH.d.mts} +2 -2
  38. package/dist/types-import-spec-D-O6GotH.d.mts.map +1 -0
  39. package/package.json +6 -4
  40. package/src/control/control-capabilities.ts +71 -0
  41. package/src/{control-descriptors.ts → control/control-descriptors.ts} +7 -7
  42. package/src/{control-instances.ts → control/control-instances.ts} +6 -6
  43. package/src/{control-migration-types.ts → control/control-migration-types.ts} +57 -60
  44. package/src/control/control-operation-preview.ts +23 -0
  45. package/src/{control-stack.ts → control/control-stack.ts} +13 -13
  46. package/src/control/emission-types.ts +49 -0
  47. package/src/control/psl-ast.ts +193 -0
  48. package/src/{execution-descriptors.ts → execution/execution-descriptors.ts} +7 -7
  49. package/src/{execution-instances.ts → execution/execution-instances.ts} +1 -1
  50. package/src/{execution-requirements.ts → execution/execution-requirements.ts} +1 -1
  51. package/src/execution/query-plan.ts +53 -0
  52. package/src/execution/race-against-abort.ts +85 -0
  53. package/src/execution/run-with-middleware.ts +132 -0
  54. package/src/execution/runtime-core.ts +133 -0
  55. package/src/execution/runtime-error.ts +83 -0
  56. package/src/execution/runtime-middleware.ts +182 -0
  57. package/src/exports/authoring.ts +2 -2
  58. package/src/exports/codec.ts +14 -2
  59. package/src/exports/components.ts +2 -2
  60. package/src/exports/control.ts +26 -13
  61. package/src/exports/emission.ts +2 -2
  62. package/src/exports/execution.ts +5 -5
  63. package/src/exports/psl-ast.ts +1 -0
  64. package/src/exports/runtime.ts +17 -5
  65. package/src/shared/codec-types.ts +261 -0
  66. package/dist/codec-types-B58nCJiu.d.mts +0 -40
  67. package/dist/codec-types-B58nCJiu.d.mts.map +0 -1
  68. package/dist/emission-types-BPAALJbF.d.mts +0 -24
  69. package/dist/emission-types-BPAALJbF.d.mts.map +0 -1
  70. package/dist/framework-authoring-D1-JZ37B.d.mts.map +0 -1
  71. package/dist/framework-components-C8ZhSwXe.mjs.map +0 -1
  72. package/dist/framework-components-EJXe-pum.d.mts.map +0 -1
  73. package/dist/types-import-spec-C4sc7wbb.d.mts.map +0 -1
  74. package/src/codec-types.ts +0 -46
  75. package/src/control-capabilities.ts +0 -34
  76. package/src/emission-types.ts +0 -28
  77. package/src/runtime-error.ts +0 -39
  78. package/src/runtime-middleware.ts +0 -83
  79. /package/src/{control-result-types.ts → control/control-result-types.ts} +0 -0
  80. /package/src/{control-schema-view.ts → control/control-schema-view.ts} +0 -0
  81. /package/src/{async-iterable-result.ts → execution/async-iterable-result.ts} +0 -0
  82. /package/src/{execution-stack.ts → execution/execution-stack.ts} +0 -0
  83. /package/src/{framework-authoring.ts → shared/framework-authoring.ts} +0 -0
  84. /package/src/{framework-components.ts → shared/framework-components.ts} +0 -0
  85. /package/src/{mutation-default-types.ts → shared/mutation-default-types.ts} +0 -0
  86. /package/src/{types-import-spec.ts → shared/types-import-spec.ts} +0 -0
@@ -1,6 +1,7 @@
1
+ import { n as CodecCallContext } from "./codec-types-CB0jWeHU.mjs";
1
2
  import { PlanMeta } from "@prisma-next/contract/types";
2
3
 
3
- //#region src/async-iterable-result.d.ts
4
+ //#region src/execution/async-iterable-result.d.ts
4
5
  declare class AsyncIterableResult<Row> implements AsyncIterable<Row>, PromiseLike<Row[]> {
5
6
  private readonly generator;
6
7
  private consumed;
@@ -14,16 +15,136 @@ declare class AsyncIterableResult<Row> implements AsyncIterable<Row>, PromiseLik
14
15
  then<TResult1 = Row[], TResult2 = never>(onfulfilled?: ((value: Row[]) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
15
16
  }
16
17
  //#endregion
17
- //#region src/runtime-error.d.ts
18
+ //#region src/execution/query-plan.d.ts
19
+ /**
20
+ * Family-agnostic plan marker.
21
+ *
22
+ * Carries only `meta` (the family-agnostic plan metadata) and the optional
23
+ * phantom `_row` parameter that lets type-level utilities recover the row
24
+ * type from a plan value. SQL and Mongo extend this marker with their own
25
+ * concrete shapes (`SqlQueryPlan`, `MongoQueryPlan`).
26
+ *
27
+ * `QueryPlan` is the *pre-lowering* marker — i.e. the surface a builder
28
+ * produces before family-specific lowering turns it into an executable
29
+ * plan (`ExecutionPlan`).
30
+ */
31
+ interface QueryPlan<Row = unknown> {
32
+ readonly meta: PlanMeta;
33
+ /**
34
+ * Phantom property to carry the Row generic for type-level utilities.
35
+ * Not set at runtime; used only for `ResultType` extraction.
36
+ */
37
+ readonly _row?: Row;
38
+ }
39
+ /**
40
+ * Family-agnostic execution-plan marker.
41
+ *
42
+ * Extends `QueryPlan` with no additional structural fields — the marker
43
+ * exists to nominally distinguish executable plans from pre-lowering plans
44
+ * in the type system. Family-specific execution plans (`SqlExecutionPlan`,
45
+ * `MongoExecutionPlan`) extend this marker with their concrete shapes
46
+ * (e.g. `sql + params` for SQL, `wireCommand` for Mongo).
47
+ */
48
+ interface ExecutionPlan<Row = unknown> extends QueryPlan<Row> {}
49
+ /**
50
+ * Extracts the `Row` type from a plan via the phantom `_row` property.
51
+ *
52
+ * Works with any plan that extends `QueryPlan<Row>` — including
53
+ * `ExecutionPlan<Row>`, `SqlQueryPlan<Row>`, `SqlExecutionPlan<Row>`,
54
+ * `MongoQueryPlan<Row>`, and `MongoExecutionPlan<Row>`.
55
+ *
56
+ * The `_row` property must be present in the plan's static type for the
57
+ * conditional to bind `R`; objects whose type lacks `_row` resolve to
58
+ * `never`. Without the `keyof` guard, `extends { _row?: infer R }` would
59
+ * silently match any object and infer `unknown`.
60
+ *
61
+ * Example: `type Row = ResultType<typeof plan>`.
62
+ */
63
+ type ResultType<P> = '_row' extends keyof P ? P extends {
64
+ readonly _row?: infer R;
65
+ } ? R : never : never;
66
+ //#endregion
67
+ //#region src/execution/runtime-error.d.ts
18
68
  interface RuntimeErrorEnvelope extends Error {
19
69
  readonly code: string;
20
70
  readonly category: 'PLAN' | 'CONTRACT' | 'LINT' | 'BUDGET' | 'RUNTIME';
21
71
  readonly severity: 'error';
22
72
  readonly details?: Record<string, unknown>;
23
73
  }
74
+ /**
75
+ * Stable code emitted by the runtime when an in-flight `execute()`
76
+ * is cancelled via the per-query `AbortSignal`. The envelope's
77
+ * `details.phase` distinguishes where the abort was observed:
78
+ *
79
+ * - `'encode'` — abort fired during `encodeParams` (SQL) or
80
+ * `resolveValue` (Mongo).
81
+ * - `'decode'` — abort fired during `decodeRow` / `decodeField`.
82
+ * - `'stream'` — abort fired between rows or before any codec call
83
+ * (already-aborted at entry).
84
+ */
85
+ declare const RUNTIME_ABORTED: "RUNTIME.ABORTED";
86
+ /** Discriminator placed in `details.phase` of a `RUNTIME.ABORTED` envelope. */
87
+ type RuntimeAbortedPhase = 'encode' | 'decode' | 'stream';
88
+ /**
89
+ * Type guard for the runtime-error envelope produced by `runtimeError`.
90
+ *
91
+ * Prefer this over duck-typing on `error.code` directly so consumers stay
92
+ * insulated from the envelope's internal shape.
93
+ */
94
+ declare function isRuntimeError(error: unknown): error is RuntimeErrorEnvelope;
24
95
  declare function runtimeError(code: string, message: string, details?: Record<string, unknown>): RuntimeErrorEnvelope;
96
+ /**
97
+ * Construct a `RUNTIME.ABORTED` envelope. Phase distinguishes where the
98
+ * abort was observed (encode / decode / stream); cause carries `signal.reason`
99
+ * verbatim from the platform — native abort produces a `DOMException`,
100
+ * explicit `controller.abort(reason)` produces whatever the caller passed.
101
+ * No synthesis happens here.
102
+ */
103
+ declare function runtimeAborted(phase: RuntimeAbortedPhase, cause?: unknown): RuntimeErrorEnvelope;
104
+ //#endregion
105
+ //#region src/execution/race-against-abort.d.ts
106
+ /**
107
+ * Throw a phase-tagged `RUNTIME.ABORTED` envelope if the supplied
108
+ * codec-call context is already aborted at the precheck site. Centralises
109
+ * the `if (ctx.signal?.aborted) throw runtimeAborted(...)` pattern that
110
+ * every codec dispatch site repeats.
111
+ */
112
+ declare function checkAborted(ctx: CodecCallContext, phase: RuntimeAbortedPhase): void;
113
+ /**
114
+ * Race a per-cell `Promise.all` (or any other in-flight work promise) against
115
+ * the supplied abort signal so the runtime returns `RUNTIME.ABORTED` promptly
116
+ * even when codec bodies ignore the signal. In-flight bodies that ignore the
117
+ * signal are abandoned and run to completion in the background — the
118
+ * cooperative-cancellation contract documented in ADR 204.
119
+ *
120
+ * Call sites still SHOULD pre-check `signal.aborted` and short-circuit with
121
+ * a phase-tagged `RUNTIME.ABORTED` envelope before invoking this helper —
122
+ * that path is the canonical "aborted at entry" surface and avoids
123
+ * scheduling the work promise. As a defensive belt-and-braces, this helper
124
+ * also handles the already-aborted case internally: `AbortSignal` does not
125
+ * replay past abort events to listeners registered after the abort, so we
126
+ * inspect `signal.aborted` synchronously and reject with the sentinel
127
+ * before installing the listener. The rejection is still attributed to the
128
+ * abort path via the sentinel-identity check.
129
+ *
130
+ * Distinguishing the rejection source is load-bearing for AC-ERR4
131
+ * (`RUNTIME.ENCODE_FAILED` / `RUNTIME.DECODE_FAILED` pass through unchanged).
132
+ * The semantically equivalent `abortable(signal)` helper in
133
+ * `@prisma-next/utils` rejects with `signal.reason ?? new DOMException(...)`,
134
+ * which is not stably distinguishable from a codec-thrown error by identity
135
+ * alone (a fresh fallback DOMException is allocated per call). We instead
136
+ * track abort attribution with a unique sentinel: only the `onAbort` listener
137
+ * installed here ever rejects with the sentinel, so an `error === sentinel`
138
+ * identity check after the race is unambiguous.
139
+ *
140
+ * Lives in `framework-components` (rather than the SQL family, where it
141
+ * originated in m2) so every family runtime that needs cooperative
142
+ * cancellation around a codec-dispatch `Promise.all` (SQL encode + decode
143
+ * today, Mongo encode in m3) shares the same attribution logic.
144
+ */
145
+ declare function raceAgainstAbort<T>(work: Promise<T>, signal: AbortSignal | undefined, phase: RuntimeAbortedPhase): Promise<T>;
25
146
  //#endregion
26
- //#region src/runtime-middleware.d.ts
147
+ //#region src/execution/runtime-middleware.d.ts
27
148
  interface RuntimeLog {
28
149
  info(event: unknown): void;
29
150
  warn(event: unknown): void;
@@ -35,25 +156,117 @@ interface RuntimeMiddlewareContext {
35
156
  readonly mode: 'strict' | 'permissive';
36
157
  readonly now: () => number;
37
158
  readonly log: RuntimeLog;
159
+ /**
160
+ * Returns a stable string identifying the (storage, statement, params)
161
+ * tuple of an execution. Two semantically equivalent executions return
162
+ * the same string. Used by middleware that need per-execution identity
163
+ * (caching, request coalescing).
164
+ *
165
+ * The family runtime owns the implementation:
166
+ * - SQL: `meta.storageHash` + `exec.sql` + `canonicalStringify(exec.params)`
167
+ * - Mongo: `meta.storageHash` + `canonicalStringify({ ...exec.command })`
168
+ *
169
+ * The method is `async` because the underlying digest helper
170
+ * (`hashContent`) uses the WebCrypto API, whose `crypto.subtle.digest`
171
+ * primitive is asynchronous by design.
172
+ *
173
+ * The returned string is intended to be consumed directly as a `Map` key
174
+ * — it is not (and should not be) further hashed by callers.
175
+ */
176
+ contentHash(exec: ExecutionPlan): Promise<string>;
38
177
  }
39
178
  interface AfterExecuteResult {
40
179
  readonly rowCount: number;
41
180
  readonly latencyMs: number;
42
181
  readonly completed: boolean;
182
+ /**
183
+ * Indicates where the rows observed during this execution came from.
184
+ *
185
+ * - `'driver'` — the default. Rows came from the underlying driver via
186
+ * `runDriver` / `runWithMiddleware`'s normal path.
187
+ * - `'middleware'` — a `RuntimeMiddleware.intercept` hook short-circuited
188
+ * execution and supplied the rows directly. The driver was not invoked.
189
+ *
190
+ * Observers (telemetry, lints, budgets) that need to distinguish between
191
+ * driver-served and middleware-served executions read this field.
192
+ * Observers that don't care can ignore it.
193
+ */
194
+ readonly source: 'driver' | 'middleware';
43
195
  }
44
- interface RuntimeMiddleware {
196
+ /**
197
+ * Result of a successful `RuntimeMiddleware.intercept` hook.
198
+ *
199
+ * Carries the rows that the middleware wishes to return in place of
200
+ * invoking the driver. The runtime iterates `rows` in order and yields
201
+ * each row to the consumer; `beforeExecute`, `runDriver`, and `onRow` are
202
+ * all skipped on the hit path. `afterExecute` still fires with
203
+ * `source: 'middleware'`.
204
+ *
205
+ * `rows` accepts both `Iterable` (arrays, sync generators) and
206
+ * `AsyncIterable` (async generators). `for await` natively handles both
207
+ * via `Symbol.asyncIterator` / `Symbol.iterator` fallback, so the
208
+ * orchestrator does not need to branch on the variant. Cached arrays in
209
+ * the cache middleware are the common case; streaming variants support
210
+ * future use cases like mock layers replaying recordings.
211
+ *
212
+ * Row shape is `Record<string, unknown>` — the same untyped shape
213
+ * `onRow` receives. The SQL runtime decodes intercepted rows through its
214
+ * normal codec pass, so interceptors cache and return raw (undecoded)
215
+ * rows.
216
+ */
217
+ interface InterceptResult {
218
+ readonly rows: AsyncIterable<Record<string, unknown>> | Iterable<Record<string, unknown>>;
219
+ }
220
+ /**
221
+ * Family-agnostic middleware SPI parameterized over the plan marker.
222
+ *
223
+ * `TPlan` defaults to the framework `QueryPlan` marker so a generic
224
+ * middleware (e.g. cross-family telemetry) can be authored without
225
+ * naming a family. Family-specific middleware (`SqlMiddleware`,
226
+ * `MongoMiddleware`) narrow `TPlan` to their concrete plan type.
227
+ */
228
+ interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan> {
45
229
  readonly name: string;
46
230
  readonly familyId?: string;
47
231
  readonly targetId?: string;
48
- beforeExecute?(plan: {
49
- readonly meta: PlanMeta;
50
- }, ctx: RuntimeMiddlewareContext): Promise<void>;
51
- onRow?(row: Record<string, unknown>, plan: {
52
- readonly meta: PlanMeta;
53
- }, ctx: RuntimeMiddlewareContext): Promise<void>;
54
- afterExecute?(plan: {
55
- readonly meta: PlanMeta;
56
- }, result: AfterExecuteResult, ctx: RuntimeMiddlewareContext): Promise<void>;
232
+ /**
233
+ * Optional short-circuit hook. Runs inside `runWithMiddleware`, after
234
+ * the orchestrator receives the lowered plan and before any
235
+ * `beforeExecute` hook fires. Middleware run in registration order; the
236
+ * first to return a non-`undefined` `InterceptResult` wins, and
237
+ * subsequent middleware's `intercept` does not fire.
238
+ *
239
+ * On a hit, `beforeExecute`, `runDriver`, and `onRow` are all skipped.
240
+ * `afterExecute` still fires with `source: 'middleware'`.
241
+ *
242
+ * Returning `undefined` (or omitting the hook entirely) signals
243
+ * passthrough — execution proceeds through the normal driver path.
244
+ *
245
+ * Errors thrown inside `intercept` are rethrown by `runWithMiddleware`
246
+ * as the original `Error` — no envelope is guaranteed at this layer.
247
+ * Before rethrowing, `afterExecute` fires with `completed: false` and
248
+ * `source: 'middleware'`. Errors thrown by `afterExecute` during the
249
+ * error path remain swallowed (existing semantics, unchanged).
250
+ *
251
+ * Used by middleware that need to short-circuit execution and supply
252
+ * rows directly: caching, mocks, rate limiting, circuit breaking.
253
+ */
254
+ intercept?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<InterceptResult | undefined>;
255
+ beforeExecute?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
256
+ onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
257
+ afterExecute?(plan: TPlan, result: AfterExecuteResult, ctx: RuntimeMiddlewareContext): Promise<void>;
258
+ }
259
+ /**
260
+ * Optional per-`execute` options accepted by every family runtime.
261
+ *
262
+ * `signal` is the per-query cancellation signal. The runtime threads the
263
+ * signal through to every codec call for the query and uses it to short-
264
+ * circuit the row stream with `RUNTIME.ABORTED` when the caller aborts.
265
+ * Omitting the option (or passing `undefined`) preserves today's behavior
266
+ * bit-for-bit.
267
+ */
268
+ interface RuntimeExecuteOptions {
269
+ readonly signal?: AbortSignal;
57
270
  }
58
271
  /**
59
272
  * Cross-family SPI for any runtime that can execute plans and be shut down.
@@ -61,17 +274,131 @@ interface RuntimeMiddleware {
61
274
  * Mongo structurally (due to its phantom Row parameter using a unique symbol).
62
275
  *
63
276
  * The `_row` intersection on `execute` connects the `Row` type parameter to the
64
- * plan, mirroring how `ExecutionPlan<Row>` carries a phantom `_row?: Row`.
277
+ * plan, mirroring how `QueryPlan<Row>` carries a phantom `_row?: Row`.
65
278
  */
66
- interface RuntimeExecutor<TPlan extends {
67
- readonly meta: PlanMeta;
68
- }> {
279
+ interface RuntimeExecutor<TPlan extends QueryPlan> {
69
280
  execute<Row>(plan: TPlan & {
70
281
  readonly _row?: Row;
71
- }): AsyncIterableResult<Row>;
282
+ }, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
72
283
  close(): Promise<void>;
73
284
  }
74
285
  declare function checkMiddlewareCompatibility(middleware: RuntimeMiddleware, runtimeFamilyId: string, runtimeTargetId: string): void;
75
286
  //#endregion
76
- export { type AfterExecuteResult, AsyncIterableResult, type RuntimeErrorEnvelope, type RuntimeExecutor, type RuntimeLog, type RuntimeMiddleware, type RuntimeMiddlewareContext, checkMiddlewareCompatibility, runtimeError };
287
+ //#region src/execution/run-with-middleware.d.ts
288
+ /**
289
+ * Drives a single execution of `runDriver()` through the middleware lifecycle.
290
+ *
291
+ * Lifecycle, in order:
292
+ * 1. For each middleware in registration order: `intercept(exec, ctx)`. The
293
+ * first non-`undefined` result wins; subsequent middleware's `intercept`
294
+ * does not fire. On a hit, the runtime emits a `middleware.intercept`
295
+ * debug event naming the winning middleware, switches the row source to
296
+ * the intercepted rows, and proceeds with `source: 'middleware'`. On
297
+ * all-passthrough (every `intercept` returns `undefined` or is omitted),
298
+ * `source: 'driver'` is used and the row source is `runDriver()`.
299
+ * 2. If `source === 'driver'`: for each middleware in registration order,
300
+ * `beforeExecute(exec, ctx)`. Skipped on the intercepted hit path —
301
+ * `beforeExecute` semantically means "about to hit the driver".
302
+ * 3. Iterate the row source. On the driver path, for each row, for each
303
+ * middleware in registration order: `onRow(row, exec, ctx)`; then yield
304
+ * the row. On the intercepted hit path, `onRow` is skipped — intercepted
305
+ * rows did not originate from a driver row stream — but rows are still
306
+ * yielded to the consumer in order.
307
+ * 4. On successful completion: for each middleware in registration order:
308
+ * `afterExecute(exec, { rowCount, latencyMs, completed: true, source },
309
+ * ctx)`.
310
+ * 5. On any error thrown during steps 1–3: for each middleware in
311
+ * registration order: `afterExecute(exec, { rowCount, latencyMs,
312
+ * completed: false, source }, ctx)`. Errors thrown by `afterExecute`
313
+ * during the error path are swallowed so they do not mask the original
314
+ * error. The original error is then rethrown.
315
+ *
316
+ * The `source` field on `AfterExecuteResult` lets observers (telemetry,
317
+ * lints, budgets) distinguish driver-served from middleware-served
318
+ * executions without needing their own out-of-band signal.
319
+ *
320
+ * This helper is the single canonical implementation of the middleware
321
+ * orchestration loop; family runtimes should not reimplement it.
322
+ */
323
+ declare function runWithMiddleware<TExec extends ExecutionPlan, Row>(exec: TExec, middleware: ReadonlyArray<RuntimeMiddleware<TExec>>, ctx: RuntimeMiddlewareContext, runDriver: () => AsyncIterable<Row>): AsyncIterableResult<Row>;
324
+ //#endregion
325
+ //#region src/execution/runtime-core.d.ts
326
+ /**
327
+ * Constructor options shared by every concrete `RuntimeCore` subclass.
328
+ *
329
+ * Family runtimes typically build the middleware list and the
330
+ * `RuntimeMiddlewareContext` themselves (running compatibility checks,
331
+ * narrowing the context's `contract` field, etc.) before calling `super`.
332
+ */
333
+ interface RuntimeCoreOptions<TMiddleware extends RuntimeMiddleware<ExecutionPlan>> {
334
+ readonly middleware: ReadonlyArray<TMiddleware>;
335
+ readonly ctx: RuntimeMiddlewareContext;
336
+ }
337
+ /**
338
+ * Family-agnostic abstract runtime base.
339
+ *
340
+ * Defines the entire `execute(plan)` template in one place:
341
+ *
342
+ * 1. `runBeforeCompile(plan)` — concrete; defaults to identity. SQL overrides
343
+ * this to run its `beforeCompile` middleware-hook chain.
344
+ * 2. `lower(plan)` — abstract. Each family produces its `*ExecutionPlan`
345
+ * (SQL via `lowerSqlPlan`, Mongo via `adapter.lower`).
346
+ * 3. `runWithMiddleware(exec, this.middleware, this.ctx,
347
+ * () => runDriver(exec))` — concrete; lifts the middleware lifecycle
348
+ * out of the family runtimes into the canonical helper.
349
+ *
350
+ * Concrete subclasses must implement `lower`, `runDriver`, and `close`.
351
+ *
352
+ * The class is generic over:
353
+ * - `TPlan` — the family's pre-lowering plan type.
354
+ * - `TExec` — the family's post-lowering (executable) plan type.
355
+ * - `TMiddleware` — the family's middleware type. Constrained to
356
+ * `RuntimeMiddleware<TExec>` because `runWithMiddleware` invokes the
357
+ * `beforeExecute` / `onRow` / `afterExecute` hooks with the lowered
358
+ * `TExec`. (The spec/plan wording "RuntimeMiddleware<TPlan>" is
359
+ * tightened to `<TExec>` here so the helper call typechecks; the
360
+ * intent is unchanged — middleware sees the post-lowering plan.)
361
+ */
362
+ declare abstract class RuntimeCore<TPlan extends QueryPlan, TExec extends ExecutionPlan, TMiddleware extends RuntimeMiddleware<TExec>> implements RuntimeExecutor<TPlan> {
363
+ protected readonly middleware: ReadonlyArray<TMiddleware>;
364
+ protected readonly ctx: RuntimeMiddlewareContext;
365
+ constructor(options: RuntimeCoreOptions<TMiddleware>);
366
+ /**
367
+ * Pre-lowering hook for plan rewriting. Defaults to identity. Subclasses
368
+ * may override to run a `beforeCompile` middleware chain (SQL does this
369
+ * to support typed AST rewrites — see `before-compile-chain.ts`).
370
+ */
371
+ protected runBeforeCompile(plan: TPlan): TPlan | Promise<TPlan>;
372
+ /**
373
+ * Lower a pre-lowering `TPlan` into the family's executable `TExec`.
374
+ * Family-specific: SQL produces `{ sql, params, ast?, ... }`; Mongo
375
+ * produces `{ command, ... }`.
376
+ *
377
+ * `ctx` carries per-query cancellation (and any future fields on
378
+ * `CodecCallContext`); concrete subclasses forward it to the
379
+ * encode-side codec dispatch site (e.g. SQL's `encodeParams` in m2,
380
+ * Mongo's `resolveValue` in m3). The runtime allocates one ctx per
381
+ * `execute()` call and threads the same reference everywhere; the
382
+ * `signal` field inside may be `undefined`, but the ctx object itself
383
+ * is always present.
384
+ */
385
+ protected abstract lower(plan: TPlan, ctx: CodecCallContext): TExec | Promise<TExec>;
386
+ /**
387
+ * Drive the underlying transport for a lowered `TExec`. Yields raw rows
388
+ * directly from the driver as `Record<string, unknown>`; codec decoding
389
+ * (if any) is the subclass's responsibility, applied by wrapping
390
+ * `execute()` rather than living inside this hook.
391
+ *
392
+ * The `Row` type parameter on `execute()` is satisfied by the caller via
393
+ * the plan's phantom `_row`; the runtime treats rows as opaque records
394
+ * here and trusts the caller's row typing.
395
+ */
396
+ protected abstract runDriver(exec: TExec): AsyncIterable<Record<string, unknown>>;
397
+ abstract close(): Promise<void>;
398
+ execute<Row>(plan: TPlan & {
399
+ readonly _row?: Row;
400
+ }, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
401
+ }
402
+ //#endregion
403
+ export { type AfterExecuteResult, AsyncIterableResult, type ExecutionPlan, type InterceptResult, type QueryPlan, RUNTIME_ABORTED, type ResultType, type RuntimeAbortedPhase, RuntimeCore, type RuntimeCoreOptions, type RuntimeErrorEnvelope, type RuntimeExecuteOptions, type RuntimeExecutor, type RuntimeLog, type RuntimeMiddleware, type RuntimeMiddlewareContext, checkAborted, checkMiddlewareCompatibility, isRuntimeError, raceAgainstAbort, runWithMiddleware, runtimeAborted, runtimeError };
77
404
  //# sourceMappingURL=runtime.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/async-iterable-result.ts","../src/runtime-error.ts","../src/runtime-middleware.ts"],"sourcesContent":[],"mappings":"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"}
1
+ {"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/execution/async-iterable-result.ts","../src/execution/query-plan.ts","../src/execution/runtime-error.ts","../src/execution/race-against-abort.ts","../src/execution/runtime-middleware.ts","../src/execution/run-with-middleware.ts","../src/execution/runtime-core.ts"],"sourcesContent":[],"mappings":";;;;cAEa,oCAAoC,cAAc,MAAM,YAAY;;;;EAApE,QAAA,oBAAmB;EAA+B,WAAA,CAAA,SAAA,EAMtC,cANsC,CAMvB,GANuB,EAAA,IAAA,EAAA,OAAA,CAAA;EAAkB,CAU9E,MAAA,CAAO,aAAA,GAVuE,EAUrD,aAVqD,CAUvC,GAVuC,CAAA;EAMzC,OAAA,CAAA,CAAA,EAuB3B,OAvB2B,CAuBnB,GAvBmB,EAAA,CAAA;EAAf,KAAA,CAAA,CAAA,EAsDR,OAtDQ,CAsDA,GAtDA,GAAA,IAAA,CAAA;EAIiB,YAAA,CAAA,CAAA,EAuDlB,OAvDkB,CAuDV,GAvDU,CAAA;EAAd,IAAA,CAAA,WAmEV,GAnEU,EAAA,EAAA,WAAA,KAAA,CAAA,CAAA,WAAA,CAAA,EAAA,CAAA,CAAA,KAAA,EAoED,GApEC,EAAA,EAAA,GAoES,QApET,GAoEoB,WApEpB,CAoEgC,QApEhC,CAAA,CAAA,GAAA,SAAA,GAAA,IAAA,EAAA,UAAA,CAAA,EAAA,CAAA,CAAA,MAAA,EAAA,OAAA,EAAA,GAqEW,QArEX,GAqEsB,WArEtB,CAqEkC,QArElC,CAAA,CAAA,GAAA,SAAA,GAAA,IAAA,CAAA,EAsEvB,WAtEuB,CAsEX,QAtEW,GAsEA,QAtEA,CAAA;;;;;;;AAV5B;;;;;;;;;AA6Ba,UCjBI,SDiBJ,CAAA,MAAA,OAAA,CAAA,CAAA;EA+BY,SAAA,IAAA,EC/CR,QD+CQ;EAAR;;;;EAkBU,SAAA,IAAA,CAAA,EC5DT,GD4DS;;;;;;;;;;;AA9E0C,UC8BpD,aD9BoD,CAAA,MAAA,OAAA,CAAA,SC8Bf,SD9Be,CC8BL,GD9BK,CAAA,CAAA;;;;ACYrE;AAkBA;AAgBA;;;;AChDA;AAkBA;AAGA;AAQA;AAUA;AAwCgB,KD/BJ,UC+BkB,CAAA,CAAA,CAAA,GAAA,MAAQ,SAAA,MD/BW,CC+BX,GD9BlC,CC8BkC,SAAuC;;;;;UA/E5D,oBAAA,SAA6B;;;;EFEjC,SAAA,OAAA,CAAA,EEEQ,MFFW,CAAA,MAAA,EAAA,OAAA,CAAA;;;;;;;;;;;;;AAiER,cEjDX,eFiDW,EAAA,iBAAA;;AAaG,KE3Df,mBAAA,GF2De,QAAA,GAAA,QAAA,GAAA,QAAA;;;;;;;AAEV,iBErDD,cAAA,CFqDC,KAAA,EAAA,OAAA,CAAA,EAAA,KAAA,IErDwC,oBFqDxC;AAAW,iBE3CZ,YAAA,CF2CY,IAAA,EAAA,MAAA,EAAA,OAAA,EAAA,MAAA,EAAA,OAAA,CAAA,EExChB,MFwCgB,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,EEvCzB,oBFuCyB;;;;;;;;ACpEX,iBCiED,cAAA,CDhEC,KAKC,EC2DoB,mBD3DjB,EAAA,KAAA,CAAA,EAAA,OAAA,CAAA,EC2DwD,oBD3DxD;;;;;ADlBrB;;;;AAMyB,iBGET,YAAA,CHFS,GAAA,EGES,gBHFT,EAAA,KAAA,EGEkC,mBHFlC,CAAA,EAAA,IAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;ACMzB;AAkBA;AAgBA;;;;AChDiB,iBCgDK,gBD5CD,CAAA,CAAA,CAAA,CAAA,IAJyB,ECiDtC,ODjD2C,CCiDnC,CDjDmC,CAAA,EAAA,MAAA,ECkDzC,WDlDyC,GAAA,SAAA,EAAA,KAAA,ECmD1C,mBDnD0C,CAAA,ECoDhD,ODpDgD,CCoDxC,CDpDwC,CAAA;;;UEIlC,UAAA;;EJFJ,IAAA,CAAA,KAAA,EAAA,OAAA,CAAA,EAAmB,IAAA;EAA+B,KAAA,CAAA,KAAA,EAAA,OAAA,CAAA,EAAA,IAAA;EAAkB,KAAA,EAAA,KAAA,EAAA,OAAA,CAAA,EAAA,IAAA;;AAMxD,UIGR,wBAAA,CJHQ;EAIiB,SAAA,QAAA,EAAA,OAAA;EAAd,SAAA,IAAA,EAAA,QAAA,GAAA,YAAA;EAAzB,SAAO,GAAA,EAAA,GAAA,GAAA,MAAA;EAmBW,SAAA,GAAA,EIhBL,UJgBK;EAAR;;;;;;;;;;;;;;;;;EA7BwD,WAAA,CAAA,IAAA,EI+BjD,aJ/BiD,CAAA,EI+BjC,OJ/BiC,CAAA,MAAA,CAAA;;UIkCpD,kBAAA;;;EHtBA,SAAA,SAAS,EAAA,OAAA;EAkBT;AAgBjB;;;;AChDA;AAkBA;AAGA;AAQA;AAUA;AAwCA;;;;ACrEA;AAsCA;;;;;;;;;;;AC5CA;AAOA;;;;;AAyBA;AAwCA;;AACiB,UADA,eAAA,CACA;EAAkD,SAAA,IAAA,EAAlD,aAAkD,CAApC,MAAoC,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,GAAT,QAAS,CAAA,MAAA,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA;;;AAWnE;;;;;;;AA2BuB,UA3BN,iBA2BM,CAAA,cA3B0B,SA2B1B,GA3BsC,SA2BtC,CAAA,CAAA;EAAY,SAAA,IAAA,EAAA,MAAA;EAA2B,SAAA,QAAA,CAAA,EAAA,MAAA;EAChD,SAAA,QAAA,CAAA,EAAA,MAAA;EAA+B;;;;;;;;AAiB7C;AAYA;;;;;;;;;AAQA;;;;EClHgB,SAAA,EAAA,IAAA,ED2EG,KC3Ec,EAAA,GAAA,ED2EF,wBC3EE,CAAA,ED2EyB,OC3EzB,CD2EiC,eC3EjC,GAAA,SAAA,CAAA;EAAe,aAAA,EAAA,IAAA,ED4EzB,KC5EyB,EAAA,GAAA,ED4Eb,wBC5Ea,CAAA,ED4Ec,OC5Ed,CAAA,IAAA,CAAA;EACxC,KAAA,EAAA,GAAA,ED4EM,MC5EN,CAAA,MAAA,EAAA,OAAA,CAAA,EAAA,IAAA,ED4EqC,KC5ErC,EAAA,GAAA,ED4EiD,wBC5EjD,CAAA,ED4E4E,OC5E5E,CAAA,IAAA,CAAA;EACsC,YAAA,EAAA,IAAA,ED6EpC,KC7EoC,EAAA,MAAA,ED8ElC,kBC9EkC,EAAA,GAAA,ED+ErC,wBC/EqC,CAAA,EDgFzC,OChFyC,CAAA,IAAA,CAAA;;;;;;;;;;;UD4F7B,qBAAA;EElHA,SAAA,MAAA,CAAA,EFmHG,WEnHe;;;;;;;AA8BnC;;;AAGwC,UF6FvB,eE7FuB,CAAA,cF6FO,SE7FP,CAAA,CAAA;EAAlB,OAAA,CAAA,GAAA,CAAA,CAAA,IAAA,EF+FZ,KE/FY,GAAA;IACO,SAAA,IAAA,CAAA,EF8FO,GE9FP;EAEkB,CAAA,EAAA,OAAA,CAAA,EF6FjC,qBE7FiC,CAAA,EF8F1C,mBE9F0C,CF8FtB,GE9FsB,CAAA;EAAd,KAAA,EAAA,EF+FtB,OE/FsB,CAAA,IAAA,CAAA;;AAGS,iBF+F1B,4BAAA,CE/F0B,UAAA,EFgG5B,iBEhG4B,EAAA,eAAA,EAAA,MAAA,EAAA,eAAA,EAAA,MAAA,CAAA,EAAA,IAAA;;;;ANxD1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACYA;AAkBA;AAgBA;iBITgB,gCAAgC,0BACxC,mBACM,cAAc,kBAAkB,cACvC,2CACY,cAAc,OAC9B,oBAAoB;;;AL1CvB;;;;;;;AAUG,UMOc,kBNPP,CAAA,oBMO8C,iBNP9C,CMOgE,aNPhE,CAAA,CAAA,CAAA;EAmBW,SAAA,UAAA,EMXE,aNWF,CMXgB,WNWhB,CAAA;EAAR,SAAA,GAAA,EMVG,wBNUH;;;;;;;;;;;;;;;;;;;;;;ACjBb;AAkBA;AAgBA;;;uBKCsB,0BACN,yBACA,mCACM,kBAAkB,mBAC3B,gBAAgB;EJrDZ,mBAAA,UAAqB,EIuDL,aJvDa,CIuDC,WJvDI,CAAA;EAkBtC,mBAA4C,GAAA,EIsC/B,wBJtC+B;EAG7C,WAAA,CAAA,OAAA,EIqCW,kBJrCQ,CIqCW,WJrCX,CAAA;EAQf;AAUhB;AAwCA;;;mCIXmC,QAAQ,QAAQ,QAAQ;EH1D3C;AAsChB;;;;;;;;;;;AC5CA;EAOiB,mBAAA,KAAA,CAAA,IAAwB,EE0ER,KF1EQ,EAAA,GAAA,EE0EI,gBF1EJ,CAAA,EE0EuB,KF1EvB,GE0E+B,OF1E/B,CE0EuC,KF1EvC,CAAA;EAIzB;;;;AAqBhB;AAwCA;;;;;EACkE,mBAAA,SAAA,CAAA,IAAA,EEoB7B,KFpB6B,CAAA,EEoBrB,aFpBqB,CEoBP,MFpBO,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA;EAWjD,SAAA,KAAA,CAAA,CAAA,EEWG,OFXc,CAAA,IAAA,CAAA;EAAe,OAAA,CAAA,GAAA,CAAA,CAAA,IAAA,EEcvC,KFduC,GAAA;IAAY,SAAA,IAAA,CAAA,EEczB,GFdyB;EA0B1C,CAAA,EAAA,OAAA,CAAA,EEXL,qBFWK,CAAA,EEVd,mBFUc,CEVM,GFUN,CAAA"}