@prisma/orm-framework 8.0.0-rc.17-dev.26 → 8.0.0-rc.17-dev.27
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.
- package/dist/components.d.mts +2 -2
- package/dist/components.mjs +2 -2
- package/dist/components__runtime.d.mts +2 -2
- package/dist/components__runtime.mjs +2 -2
- package/dist/{hash-content-DwEUh-Rx.d.mts → hash-content-Bde14N2-.d.mts} +2 -2
- package/dist/{hash-content-DwEUh-Rx.d.mts.map → hash-content-Bde14N2-.d.mts.map} +1 -1
- package/dist/{hash-content-Bugg_nZn.mjs → hash-content-Bdl-HSfq.mjs} +2 -2
- package/dist/hash-content-Bdl-HSfq.mjs.map +1 -0
- package/dist/runtime-Bl61xROB.d.mts +800 -0
- package/dist/runtime-Bl61xROB.d.mts.map +1 -0
- package/dist/runtime-DoZkleC9.mjs +809 -0
- package/dist/runtime-DoZkleC9.mjs.map +1 -0
- package/dist/utils.d.mts +1 -1
- package/dist/utils.mjs +1 -1
- package/dist/utils__hash-content.d.mts +1 -1
- package/dist/utils__hash-content.mjs +1 -1
- package/package.json +15 -15
- package/dist/hash-content-Bugg_nZn.mjs.map +0 -1
- package/dist/runtime-7NCyLoeP.mjs +0 -869
- package/dist/runtime-7NCyLoeP.mjs.map +0 -1
- package/dist/runtime-CJ0h4apE.d.mts +0 -1177
- package/dist/runtime-CJ0h4apE.d.mts.map +0 -1
|
@@ -0,0 +1,800 @@
|
|
|
1
|
+
import { G as PlanMeta } from "./domain-envelope-C2vVIWGK-C5x7cBpU.mjs";
|
|
2
|
+
import { n as ContractExecutionSection } from "./contract-types-BIaUtO7Z-Bcxx2I74.mjs";
|
|
3
|
+
import { a as CodecCallContext } from "./codec-types-CQNZE70G-DZIvCZwY.mjs";
|
|
4
|
+
import { t as RuntimeErrorEnvelope } from "./runtime-error-CO4MA3Px-YW5SCUcH.mjs";
|
|
5
|
+
//#region ../../../1-framework/1-core/framework-components/dist/runtime.d.mts
|
|
6
|
+
//#region src/annotations.d.ts
|
|
7
|
+
/**
|
|
8
|
+
* The kinds of operations an annotation may apply to.
|
|
9
|
+
*
|
|
10
|
+
* - `'read'` — `SELECT` / `find` / `first` / `all` / `count` / aggregates.
|
|
11
|
+
* - `'write'` — `INSERT` / `UPDATE` / `DELETE` / `create` / `update` / `delete` / `upsert`.
|
|
12
|
+
*
|
|
13
|
+
* Annotations declare which kinds they apply to via `defineAnnotation`'s
|
|
14
|
+
* `applicableTo` option; lane terminals enforce the constraint at both the
|
|
15
|
+
* type level (via `ValidAnnotations`) and at runtime (via
|
|
16
|
+
* `assertAnnotationsApplicable`).
|
|
17
|
+
*
|
|
18
|
+
* Finer-grained kinds (`'select' | 'insert' | 'update' | 'delete' | 'upsert'`)
|
|
19
|
+
* are deliberately deferred. The binary covers the common case (the cache
|
|
20
|
+
* middleware applies to reads; an audit annotation would apply to writes;
|
|
21
|
+
* tracing/OTel applies to both). When a real annotation surfaces that needs
|
|
22
|
+
* a finer split, the union widens and existing handles remain typecheckable.
|
|
23
|
+
*/
|
|
24
|
+
type OperationKind = 'read' | 'write';
|
|
25
|
+
/**
|
|
26
|
+
* An applied annotation. Carries the namespace, the typed payload, and the
|
|
27
|
+
* `applicableTo` set the underlying handle declared. The `__annotation`
|
|
28
|
+
* brand lets `read` distinguish branded user annotations from arbitrary
|
|
29
|
+
* data that may happen to live under the same namespace key in
|
|
30
|
+
* `plan.meta.annotations` (e.g. framework-internal metadata such as
|
|
31
|
+
* `meta.annotations.codecs`).
|
|
32
|
+
*
|
|
33
|
+
* Constructed by calling an `AnnotationHandle` directly (e.g.
|
|
34
|
+
* `cacheAnnotation({ ttl: 60 })`); never instantiated by hand.
|
|
35
|
+
*/
|
|
36
|
+
interface AnnotationValue<Payload, Kinds extends OperationKind> {
|
|
37
|
+
readonly __annotation: true;
|
|
38
|
+
readonly namespace: string;
|
|
39
|
+
readonly value: Payload;
|
|
40
|
+
readonly applicableTo: ReadonlySet<Kinds>;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Handle returned by `defineAnnotation`. The handle is **callable**: the
|
|
44
|
+
* call signature wraps a `Payload` into an `AnnotationValue` ready to
|
|
45
|
+
* pass to a lane terminal's variadic `annotations` argument. The handle
|
|
46
|
+
* also carries static metadata as own properties:
|
|
47
|
+
*
|
|
48
|
+
* - `namespace` — the namespace string the handle was declared with.
|
|
49
|
+
* - `applicableTo` — the frozen `ReadonlySet<Kinds>` consumed by both
|
|
50
|
+
* the type-level `ValidAnnotations` gate and the runtime
|
|
51
|
+
* `assertAnnotationsApplicable` gate.
|
|
52
|
+
* - `read(source)` — extract the `Payload` from a plan's `meta.annotations`
|
|
53
|
+
* or an activity's `annotations` if a value was previously written under
|
|
54
|
+
* this handle's namespace. Returns `undefined` when the annotation is
|
|
55
|
+
* absent or when the stored value is not a branded `AnnotationValue`
|
|
56
|
+
* (e.g. framework-internal metadata under the same namespace key).
|
|
57
|
+
*
|
|
58
|
+
* Handles are the only supported public entry point for reading and
|
|
59
|
+
* writing annotations. Direct mutation of `plan.meta.annotations` is not
|
|
60
|
+
* part of the public API.
|
|
61
|
+
*
|
|
62
|
+
* ```typescript
|
|
63
|
+
* const cacheAnnotation = defineAnnotation<{ ttl: number }>()({
|
|
64
|
+
* namespace: 'cache',
|
|
65
|
+
* applicableTo: ['read'],
|
|
66
|
+
* });
|
|
67
|
+
*
|
|
68
|
+
* // Call the handle to construct a value:
|
|
69
|
+
* const applied = cacheAnnotation({ ttl: 60 });
|
|
70
|
+
*
|
|
71
|
+
* // Read a stored value off a plan:
|
|
72
|
+
* const payload = cacheAnnotation.read(plan);
|
|
73
|
+
* ```
|
|
74
|
+
*
|
|
75
|
+
* Note on the inherited `Function.prototype.apply`: because the handle is
|
|
76
|
+
* a function, the property name `apply` resolves to JavaScript's built-in
|
|
77
|
+
* `Function.prototype.apply` (which lets you invoke a function with an
|
|
78
|
+
* array of arguments). This is **not** the construction entry point — to
|
|
79
|
+
* build an `AnnotationValue`, call the handle directly. The
|
|
80
|
+
* `AnnotationHandle` interface deliberately does not declare an `apply`
|
|
81
|
+
* member of its own.
|
|
82
|
+
*/
|
|
83
|
+
interface AnnotationHandle<Payload, Kinds extends OperationKind> {
|
|
84
|
+
(value: Payload): AnnotationValue<Payload, Kinds>;
|
|
85
|
+
readonly namespace: string;
|
|
86
|
+
readonly applicableTo: ReadonlySet<Kinds>;
|
|
87
|
+
read(source: AnnotationSource): Payload | undefined;
|
|
88
|
+
}
|
|
89
|
+
/** A plan, or an activity, whose annotations a handle reads. */
|
|
90
|
+
type AnnotationSource = {
|
|
91
|
+
readonly meta: {
|
|
92
|
+
readonly annotations?: Record<string, unknown>;
|
|
93
|
+
};
|
|
94
|
+
} | {
|
|
95
|
+
readonly annotations: ReadonlyMap<string, unknown>;
|
|
96
|
+
};
|
|
97
|
+
/**
|
|
98
|
+
* Options accepted by `defineAnnotation`.
|
|
99
|
+
*
|
|
100
|
+
* `namespace` is the string key under which the annotation is stored in
|
|
101
|
+
* `plan.meta.annotations`. **Reserved namespaces** include framework-
|
|
102
|
+
* internal metadata keys; user handles must not use them:
|
|
103
|
+
*
|
|
104
|
+
* - `codecs` — used by the SQL emitter to record per-alias codec ids
|
|
105
|
+
* (`meta.annotations.codecs[alias] = 'pg/text@1'`); the SQL runtime's
|
|
106
|
+
* `decodeRow` reads from this key. A user `defineAnnotation('codecs')`
|
|
107
|
+
* handle is not structurally prevented, but its behavior with the
|
|
108
|
+
* emitter and the runtime is undefined and we make no compatibility
|
|
109
|
+
* guarantees about it.
|
|
110
|
+
* - Target-specific keys such as `pg` (and equivalents on other
|
|
111
|
+
* targets) are similarly reserved for adapter / target use.
|
|
112
|
+
*
|
|
113
|
+
* `applicableTo` declares which operation kinds the annotation may attach
|
|
114
|
+
* to. The lane terminals' type-level `ValidAnnotations<K, As>` gate rejects
|
|
115
|
+
* annotations whose `Kinds` does not include the terminal's `K`; the
|
|
116
|
+
* runtime helper `assertAnnotationsApplicable` does the equivalent at
|
|
117
|
+
* runtime so casts and `any` cannot bypass the gate.
|
|
118
|
+
*/
|
|
119
|
+
interface DefineAnnotationOptions<Kinds extends OperationKind> {
|
|
120
|
+
readonly namespace: string;
|
|
121
|
+
readonly applicableTo: readonly Kinds[];
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Defines a typed annotation handle.
|
|
125
|
+
*
|
|
126
|
+
* Two-step call form. The first step takes the `Payload` type argument
|
|
127
|
+
* (TypeScript cannot infer `Payload` from anything in the options, so it
|
|
128
|
+
* must be supplied explicitly); the second step takes the runtime options
|
|
129
|
+
* and infers `Kinds` from the `applicableTo` array via a `const` type
|
|
130
|
+
* parameter, so the operation kinds appear exactly once at the call site.
|
|
131
|
+
*
|
|
132
|
+
* @example
|
|
133
|
+
* ```typescript
|
|
134
|
+
* // Read-only annotation. Lane terminals like `db.User.first(...)` accept
|
|
135
|
+
* // it; `db.User.create(...)` rejects it at the type level.
|
|
136
|
+
* const cacheAnnotation = defineAnnotation<{ ttl?: number; skip?: boolean }>()({
|
|
137
|
+
* namespace: 'cache',
|
|
138
|
+
* applicableTo: ['read'],
|
|
139
|
+
* }); // Kinds inferred as 'read'
|
|
140
|
+
*
|
|
141
|
+
* // Write-only annotation. Mirror image.
|
|
142
|
+
* const auditAnnotation = defineAnnotation<{ actor: string }>()({
|
|
143
|
+
* namespace: 'audit',
|
|
144
|
+
* applicableTo: ['write'],
|
|
145
|
+
* }); // Kinds inferred as 'write'
|
|
146
|
+
*
|
|
147
|
+
* // Annotation applicable to both kinds (e.g. tracing).
|
|
148
|
+
* const otelAnnotation = defineAnnotation<{ traceId: string }>()({
|
|
149
|
+
* namespace: 'otel',
|
|
150
|
+
* applicableTo: ['read', 'write'],
|
|
151
|
+
* }); // Kinds inferred as 'read' | 'write'
|
|
152
|
+
* ```
|
|
153
|
+
*
|
|
154
|
+
* **Reserved namespaces.** See `DefineAnnotationOptions.namespace` for the
|
|
155
|
+
* list of framework-internal namespaces (`codecs`, target-specific keys).
|
|
156
|
+
* `defineAnnotation` does not structurally prevent a user from naming a
|
|
157
|
+
* reserved namespace, but the framework makes no compatibility guarantee
|
|
158
|
+
* about handles that do.
|
|
159
|
+
*/
|
|
160
|
+
declare function defineAnnotation<Payload>(): <const Kinds extends OperationKind>(options: DefineAnnotationOptions<Kinds>) => AnnotationHandle<Payload, Kinds>;
|
|
161
|
+
/**
|
|
162
|
+
* Type-level applicability gate consumed by lane terminals.
|
|
163
|
+
*
|
|
164
|
+
* Maps a tuple of `AnnotationValue`s to a tuple where each element either
|
|
165
|
+
* keeps its annotation type (when the annotation's declared `Kinds`
|
|
166
|
+
* includes the terminal's operation kind `K`) or resolves to `never`
|
|
167
|
+
* (when the kinds are incompatible). A `never` element makes the entire
|
|
168
|
+
* tuple unassignable, surfacing the mismatch as a type error at the call
|
|
169
|
+
* site of the terminal.
|
|
170
|
+
*
|
|
171
|
+
* The SQL DSL builders constrain their variadic `...annotations`
|
|
172
|
+
* parameter via `As & ValidAnnotations<K, As>`. **The intersection is
|
|
173
|
+
* load-bearing** — see the note below. The ORM terminals deliberately
|
|
174
|
+
* sidestep this trick by taking one annotation per `meta.annotate(...)`
|
|
175
|
+
* call (no variadic-tuple inference involved), so `ValidAnnotations` is
|
|
176
|
+
* consumed only by the SQL DSL today.
|
|
177
|
+
*
|
|
178
|
+
* @example
|
|
179
|
+
* ```typescript
|
|
180
|
+
* class SelectQuery<Row> {
|
|
181
|
+
* annotate<As extends readonly AnnotationValue<unknown, OperationKind>[]>(
|
|
182
|
+
* ...annotations: As & ValidAnnotations<'read', As>
|
|
183
|
+
* ): SelectQuery<Row>;
|
|
184
|
+
* }
|
|
185
|
+
*
|
|
186
|
+
* class InsertQuery<Row> {
|
|
187
|
+
* annotate<As extends readonly AnnotationValue<unknown, OperationKind>[]>(
|
|
188
|
+
* ...annotations: As & ValidAnnotations<'write', As>
|
|
189
|
+
* ): InsertQuery<Row>;
|
|
190
|
+
* }
|
|
191
|
+
*
|
|
192
|
+
* db.users.select('id').annotate(cacheAnnotation({ ttl: 60 }));
|
|
193
|
+
* // ✓ cacheAnnotation declares 'read'; SelectQuery.annotate requires 'read'.
|
|
194
|
+
*
|
|
195
|
+
* db.users.insert([{ name: 'Alice' }]).annotate(cacheAnnotation({ ttl: 60 }));
|
|
196
|
+
* // ✗ cacheAnnotation declares 'read'; InsertQuery.annotate requires 'write'.
|
|
197
|
+
* // Element resolves to `never` → tuple unassignable → type error.
|
|
198
|
+
* ```
|
|
199
|
+
*
|
|
200
|
+
* **Why `As & ValidAnnotations<K, As>` and not `ValidAnnotations<K, As>`
|
|
201
|
+
* alone.** TypeScript's variadic-tuple inference is too forgiving when
|
|
202
|
+
* the parameter type refers to `As` only through `ValidAnnotations`: it
|
|
203
|
+
* will pick an `As` that makes the call valid even when the gated tuple
|
|
204
|
+
* would contain `never` for an inapplicable element. The intersection
|
|
205
|
+
* pins `As` to the actual call-site tuple AND requires it to be
|
|
206
|
+
* assignable to the gated form. A `never` element in the gated tuple
|
|
207
|
+
* then collapses the corresponding intersection position to `never`,
|
|
208
|
+
* and the inapplicable argument fails to assign — surfacing the mismatch
|
|
209
|
+
* as a type error at the call site.
|
|
210
|
+
*
|
|
211
|
+
* The runtime helper `assertAnnotationsApplicable` covers the equivalent
|
|
212
|
+
* check at runtime so casts and `any` cannot bypass this gate.
|
|
213
|
+
*/
|
|
214
|
+
type ValidAnnotations<K extends OperationKind, As extends readonly AnnotationValue<unknown, OperationKind>[]> = { readonly [I in keyof As]: As[I] extends AnnotationValue<infer P, infer Kinds> ? K extends Kinds ? AnnotationValue<P, Kinds> : never : never; };
|
|
215
|
+
/**
|
|
216
|
+
* Runtime applicability gate. Throws `RUNTIME.ANNOTATION_INAPPLICABLE` if
|
|
217
|
+
* any annotation in `annotations` declares an `applicableTo` set that does
|
|
218
|
+
* not include `kind`. Used by lane terminals (SQL DSL builders' `.build()`,
|
|
219
|
+
* ORM `Collection` terminals) to fail closed when the type-level
|
|
220
|
+
* `ValidAnnotations` gate is bypassed via cast / `any` / dynamic
|
|
221
|
+
* invocation.
|
|
222
|
+
*
|
|
223
|
+
* Passes silently on:
|
|
224
|
+
* - empty arrays
|
|
225
|
+
* - annotations whose `applicableTo` includes `kind`
|
|
226
|
+
*
|
|
227
|
+
* Throws on:
|
|
228
|
+
* - any annotation whose `applicableTo` does not include `kind`. The
|
|
229
|
+
* error names the offending annotation's `namespace` and the
|
|
230
|
+
* `terminalName` so users can locate the misuse.
|
|
231
|
+
*
|
|
232
|
+
* @example
|
|
233
|
+
* ```typescript
|
|
234
|
+
* // Inside an ORM read terminal:
|
|
235
|
+
* assertAnnotationsApplicable(annotations, 'read', 'first');
|
|
236
|
+
* ```
|
|
237
|
+
*/
|
|
238
|
+
declare function assertAnnotationsApplicable(annotations: readonly AnnotationValue<unknown, OperationKind>[], kind: OperationKind, terminalName: string): void;
|
|
239
|
+
//#endregion
|
|
240
|
+
//#region src/execution/async-iterable-result.d.ts
|
|
241
|
+
declare class AsyncIterableResult<Row> implements AsyncIterable<Row>, PromiseLike<Row[]> {
|
|
242
|
+
private readonly generator;
|
|
243
|
+
private consumed;
|
|
244
|
+
private consumedBy;
|
|
245
|
+
private bufferedArrayPromise;
|
|
246
|
+
constructor(generator: AsyncGenerator<Row, void, unknown>);
|
|
247
|
+
[Symbol.asyncIterator](): AsyncIterator<Row>;
|
|
248
|
+
toArray(): Promise<Row[]>;
|
|
249
|
+
first(): Promise<Row | null>;
|
|
250
|
+
firstOrThrow(): Promise<Row>;
|
|
251
|
+
then<TResult1 = Row[], TResult2 = never>(onfulfilled?: ((value: Row[]) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
|
|
252
|
+
}
|
|
253
|
+
//#endregion
|
|
254
|
+
//#region src/execution/query-plan.d.ts
|
|
255
|
+
/**
|
|
256
|
+
* Family-agnostic plan marker.
|
|
257
|
+
*
|
|
258
|
+
* Carries only `meta` (the family-agnostic plan metadata) and the optional
|
|
259
|
+
* phantom `_row` parameter that lets type-level utilities recover the row
|
|
260
|
+
* type from a plan value. SQL and Mongo extend this marker with their own
|
|
261
|
+
* concrete shapes (`SqlQueryPlan`, `MongoQueryPlan`).
|
|
262
|
+
*
|
|
263
|
+
* `QueryPlan` is the *pre-lowering* marker — i.e. the surface a builder
|
|
264
|
+
* produces before family-specific lowering turns it into an executable
|
|
265
|
+
* plan (`ExecutionPlan`).
|
|
266
|
+
*/
|
|
267
|
+
interface QueryPlan<Row = unknown> {
|
|
268
|
+
readonly meta: PlanMeta;
|
|
269
|
+
/**
|
|
270
|
+
* Phantom property to carry the Row generic for type-level utilities.
|
|
271
|
+
* Not set at runtime; used only for `ResultType` extraction.
|
|
272
|
+
*/
|
|
273
|
+
readonly _row?: Row;
|
|
274
|
+
}
|
|
275
|
+
/**
|
|
276
|
+
* Family-agnostic execution-plan marker.
|
|
277
|
+
*
|
|
278
|
+
* Extends `QueryPlan` with no additional structural fields — the marker
|
|
279
|
+
* exists to nominally distinguish executable plans from pre-lowering plans
|
|
280
|
+
* in the type system. Family-specific execution plans (`SqlExecutionPlan`,
|
|
281
|
+
* `MongoExecutionPlan`) extend this marker with their concrete shapes
|
|
282
|
+
* (e.g. `sql + params` for SQL, `wireCommand` for Mongo).
|
|
283
|
+
*/
|
|
284
|
+
interface ExecutionPlan<Row = unknown> extends QueryPlan<Row> {}
|
|
285
|
+
/**
|
|
286
|
+
* Extracts the `Row` type from a plan via the phantom `_row` property.
|
|
287
|
+
*
|
|
288
|
+
* Works with any plan that extends `QueryPlan<Row>` — including
|
|
289
|
+
* `ExecutionPlan<Row>`, `SqlQueryPlan<Row>`, `SqlExecutionPlan<Row>`,
|
|
290
|
+
* `MongoQueryPlan<Row>`, and `MongoExecutionPlan<Row>`.
|
|
291
|
+
*
|
|
292
|
+
* The `_row` property must be present in the plan's static type for the
|
|
293
|
+
* conditional to bind `R`; objects whose type lacks `_row` resolve to
|
|
294
|
+
* `never`. Without the `keyof` guard, `extends { _row?: infer R }` would
|
|
295
|
+
* silently match any object and infer `unknown`.
|
|
296
|
+
*
|
|
297
|
+
* Example: `type Row = ResultType<typeof plan>`.
|
|
298
|
+
*/
|
|
299
|
+
type ResultType<P> = '_row' extends keyof P ? P extends {
|
|
300
|
+
readonly _row?: infer R;
|
|
301
|
+
} ? R : never : never;
|
|
302
|
+
//#endregion
|
|
303
|
+
//#region src/execution/runtime-middleware.d.ts
|
|
304
|
+
interface RuntimeLog {
|
|
305
|
+
info(event: unknown): void;
|
|
306
|
+
warn(event: unknown): void;
|
|
307
|
+
error(event: unknown): void;
|
|
308
|
+
debug?(event: unknown): void;
|
|
309
|
+
}
|
|
310
|
+
/** What every activity has: an identity, a kind and the annotations the user put on it. */
|
|
311
|
+
interface ActivityBase {
|
|
312
|
+
/** A fresh `crypto.randomUUID()` per activity. */
|
|
313
|
+
readonly id: string;
|
|
314
|
+
readonly kind: string;
|
|
315
|
+
/** Empty when the activity carries no annotation. */
|
|
316
|
+
readonly annotations: ReadonlyMap<string, AnnotationValue<unknown, OperationKind>>;
|
|
317
|
+
}
|
|
318
|
+
/** One statement sent to the database: `query()` sends it for its rows, `execute()` for its statistics. */
|
|
319
|
+
interface StatementActivity<TPlan extends QueryPlan = QueryPlan> extends ActivityBase {
|
|
320
|
+
readonly kind: 'statement';
|
|
321
|
+
readonly returns: 'rows' | 'stats';
|
|
322
|
+
/** The plan the caller sent. */
|
|
323
|
+
readonly plan: TPlan;
|
|
324
|
+
}
|
|
325
|
+
/** Started by `transaction()`, ended by `commit()` or `rollback()`. */
|
|
326
|
+
interface TransactionActivity extends ActivityBase {
|
|
327
|
+
readonly kind: 'transaction';
|
|
328
|
+
}
|
|
329
|
+
type RuntimeActivity = StatementActivity | TransactionActivity;
|
|
330
|
+
/**
|
|
331
|
+
* The context of one activity. Every hook of the activity receives the same object.
|
|
332
|
+
*/
|
|
333
|
+
interface ActivityContext {
|
|
334
|
+
readonly contract: unknown;
|
|
335
|
+
readonly mode: 'strict' | 'permissive';
|
|
336
|
+
readonly now: () => number;
|
|
337
|
+
readonly log: RuntimeLog;
|
|
338
|
+
/**
|
|
339
|
+
* A stable digest of an execution's storage hash, statement and parameters, usable directly as a `Map` key. Two equivalent executions return the same string.
|
|
340
|
+
*/
|
|
341
|
+
contentHash(exec: ExecutionPlan): Promise<string>;
|
|
342
|
+
/** The caller's cancellation signal, when it passed one. */
|
|
343
|
+
readonly signal?: AbortSignal;
|
|
344
|
+
/** The scope of the queryable the activity was started on. */
|
|
345
|
+
readonly scope: 'runtime' | 'connection' | 'transaction';
|
|
346
|
+
/** The parent activity's context, or `undefined` at the root. */
|
|
347
|
+
readonly parent: ActivityContext | undefined;
|
|
348
|
+
/** The state object stored under `key` for this activity, created empty on first use and dropped when the activity is finalized. Middleware that use the same key share the object. */
|
|
349
|
+
state(key: string | symbol): Record<string | symbol, unknown>;
|
|
350
|
+
/** Whether any ancestor of this activity is a transaction. */
|
|
351
|
+
inTransaction(): boolean;
|
|
352
|
+
}
|
|
353
|
+
/** The fields a runtime supplies to build an activity's context; the runtime adds `parent`, `state` and `inTransaction`. */
|
|
354
|
+
type ActivityContextFields<TContext extends ActivityContext = ActivityContext> = Omit<TContext, 'parent' | 'state' | 'inTransaction'>;
|
|
355
|
+
interface TransactionEnded {
|
|
356
|
+
readonly kind: 'transaction';
|
|
357
|
+
readonly outcome: 'succeeded' | 'failed';
|
|
358
|
+
}
|
|
359
|
+
type StatementEnded = {
|
|
360
|
+
readonly kind: 'statement';
|
|
361
|
+
/** `stopped` when the caller stopped reading the rows. */
|
|
362
|
+
readonly outcome: 'succeeded' | 'failed' | 'stopped';
|
|
363
|
+
readonly latencyMs: number;
|
|
364
|
+
/** `middleware` when an `intercept` handler supplied the result, or threw. */
|
|
365
|
+
readonly source: 'driver' | 'middleware';
|
|
366
|
+
} & ({
|
|
367
|
+
readonly returns: 'rows';
|
|
368
|
+
readonly rowCount: number;
|
|
369
|
+
} | {
|
|
370
|
+
readonly returns: 'stats';
|
|
371
|
+
readonly stats?: RuntimeStatementStats;
|
|
372
|
+
});
|
|
373
|
+
type ActivityEndedResult = TransactionEnded | StatementEnded;
|
|
374
|
+
interface ActivityFinalizedResult {
|
|
375
|
+
/** `unknown` when the runtime cannot tell whether the writes landed; treat it like `committed` when a committed write must not be missed. */
|
|
376
|
+
readonly outcome: 'committed' | 'rolled-back' | 'unknown';
|
|
377
|
+
}
|
|
378
|
+
interface QueryInterceptResult {
|
|
379
|
+
readonly rows: AsyncIterable<Record<string, unknown>> | Iterable<Record<string, unknown>>;
|
|
380
|
+
}
|
|
381
|
+
interface ExecuteInterceptResult {
|
|
382
|
+
readonly stats: RuntimeStatementStats;
|
|
383
|
+
}
|
|
384
|
+
/**
|
|
385
|
+
* Marker for the family-specific parameter mutator passed to `beforeEncode`. SQL extends it as `SqlParamRefMutator`, Mongo as `MongoParamRefMutator`.
|
|
386
|
+
*/
|
|
387
|
+
declare const PARAM_REF_MUTATOR_BRAND: unique symbol;
|
|
388
|
+
type ParamRefMutator = {
|
|
389
|
+
readonly [PARAM_REF_MUTATOR_BRAND]?: never;
|
|
390
|
+
};
|
|
391
|
+
/** The lifecycle events every activity has. They observe; they cannot change the activity. */
|
|
392
|
+
interface ActivityObserver {
|
|
393
|
+
readonly name: string;
|
|
394
|
+
/** The act begins. */
|
|
395
|
+
activityStarted?(activity: RuntimeActivity, ctx: ActivityContext): Promise<void>;
|
|
396
|
+
/** The act ends, with its outcome as the actor saw it. An error thrown when the activity succeeded fails it and reaches the caller; after a failure it is swallowed. */
|
|
397
|
+
activityEnded?(activity: RuntimeActivity, result: ActivityEndedResult, ctx: ActivityContext): Promise<void>;
|
|
398
|
+
/** The act's effects are final. A thrown error is passed to `ctx.log.error` and swallowed; later middleware still run. */
|
|
399
|
+
activityFinalized?(activity: RuntimeActivity, result: ActivityFinalizedResult, ctx: ActivityContext): Promise<void>;
|
|
400
|
+
}
|
|
401
|
+
/**
|
|
402
|
+
* Family-agnostic middleware. `TPlan` is the encoded execution plan the statement interceptors receive; `TMutator` is the family's parameter mutator.
|
|
403
|
+
*/
|
|
404
|
+
interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan, TMutator extends ParamRefMutator = ParamRefMutator> extends ActivityObserver {
|
|
405
|
+
readonly familyId?: string;
|
|
406
|
+
readonly targetId?: string;
|
|
407
|
+
/** Runs after lowering, before codecs encode the parameter values. Throw to block the statement; change values through `params`. */
|
|
408
|
+
beforeEncode?(draft: TPlan, ctx: ActivityContext, params?: TMutator): void | Promise<void>;
|
|
409
|
+
/** Supplies a statement's result instead of running it. Middleware run in registration order and the first handler that returns a result wins. */
|
|
410
|
+
intercept?: {
|
|
411
|
+
onQuery?(plan: TPlan, ctx: ActivityContext): Promise<QueryInterceptResult | undefined>;
|
|
412
|
+
onExecute?(plan: TPlan, ctx: ActivityContext): Promise<ExecuteInterceptResult | undefined>;
|
|
413
|
+
};
|
|
414
|
+
/** Runs for each row the driver returns; not for intercepted rows. Throw to stop the stream. */
|
|
415
|
+
onRow?(row: Record<string, unknown>, plan: TPlan, ctx: ActivityContext): Promise<void>;
|
|
416
|
+
}
|
|
417
|
+
/**
|
|
418
|
+
* Middleware that names no family or target, so it fits any family runtime's middleware array.
|
|
419
|
+
*/
|
|
420
|
+
type CrossFamilyMiddleware<TPlan extends QueryPlan = QueryPlan> = RuntimeMiddleware<TPlan> & {
|
|
421
|
+
readonly familyId?: undefined;
|
|
422
|
+
readonly targetId?: undefined;
|
|
423
|
+
};
|
|
424
|
+
/** Per-operation options accepted by every family runtime. */
|
|
425
|
+
interface RuntimeExecuteOptions {
|
|
426
|
+
readonly signal?: AbortSignal;
|
|
427
|
+
readonly scope?: 'runtime' | 'connection' | 'transaction';
|
|
428
|
+
}
|
|
429
|
+
interface RuntimeStatementStats {
|
|
430
|
+
readonly affectedRows: number;
|
|
431
|
+
}
|
|
432
|
+
/** Any runtime that can query or execute plans and be shut down. */
|
|
433
|
+
interface RuntimeExecutor<TPlan extends QueryPlan> {
|
|
434
|
+
query<Row>(plan: TPlan & {
|
|
435
|
+
readonly _row?: Row;
|
|
436
|
+
}, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
|
|
437
|
+
execute(plan: TPlan, options?: RuntimeExecuteOptions): Promise<RuntimeStatementStats>;
|
|
438
|
+
close(): Promise<void>;
|
|
439
|
+
}
|
|
440
|
+
declare function checkMiddlewareCompatibility(middleware: RuntimeMiddleware, runtimeFamilyId: string, runtimeTargetId: string): void;
|
|
441
|
+
//#endregion
|
|
442
|
+
//#region src/execution/activity-lifecycle.d.ts
|
|
443
|
+
/** An open activity that new activities can start beneath. */
|
|
444
|
+
interface ActivityParent {
|
|
445
|
+
readonly activity: RuntimeActivity;
|
|
446
|
+
readonly ctx: ActivityContext;
|
|
447
|
+
/** Records `child` in start order; the parent finalizes it. Returns what the child calls when it ends, which finalizes it when the parent has already ended. */
|
|
448
|
+
adopt(child: ActivityChild): (outcome: ActivityEndedResult['outcome']) => Promise<void>;
|
|
449
|
+
}
|
|
450
|
+
/** What a parent holds of a child activity until it finalizes it. */
|
|
451
|
+
interface ActivityChild {
|
|
452
|
+
/** Runs the child's `activityFinalized` hooks; a second call does nothing. */
|
|
453
|
+
finalize(result: ActivityFinalizedResult): Promise<void>;
|
|
454
|
+
}
|
|
455
|
+
/** The per-activity state behind `ctx.state(key)`: one object per key, created empty on first use. */
|
|
456
|
+
interface ActivityStateStore {
|
|
457
|
+
state(key: string | symbol): Record<string | symbol, unknown>;
|
|
458
|
+
clear(): void;
|
|
459
|
+
}
|
|
460
|
+
declare function createStateStore(): ActivityStateStore;
|
|
461
|
+
//#endregion
|
|
462
|
+
//#region src/execution/mutation-defaults.d.ts
|
|
463
|
+
/**
|
|
464
|
+
* Scope across which a generator's value is constant.
|
|
465
|
+
*
|
|
466
|
+
* - `'field'` — one value per defaulting site (one field of one record). Cache strategy: no cache; call per defaulting site. Right for per-record identifiers (UUIDs, CUIDs, ULIDs, nanoid, ksuid).
|
|
467
|
+
* - `'row'` — one value across all defaulting sites of one record of one operation. Cache strategy: per-call cache keyed by generator id. Right for correlation ids stamped into several fields of one record.
|
|
468
|
+
* - `'query'` — one value across all records and fields of one ORM operation. Cache strategy: caller-provided cache keyed by generator id. Right for `timestampNow` (a single timestamp per bulk create or update).
|
|
469
|
+
*/
|
|
470
|
+
type GeneratorStability = 'field' | 'row' | 'query';
|
|
471
|
+
interface RuntimeMutationDefaultGenerator {
|
|
472
|
+
readonly id: string;
|
|
473
|
+
readonly generate: (params?: Record<string, unknown>) => unknown;
|
|
474
|
+
/**
|
|
475
|
+
* Scope across which the generator's value is constant. The framework derives the cache strategy from this declaration; generator authors never need to know about cache keys. See `GeneratorStability` for the per-value semantics.
|
|
476
|
+
*/
|
|
477
|
+
readonly stability: GeneratorStability;
|
|
478
|
+
}
|
|
479
|
+
/** A runtime component (target, adapter, or extension) that may contribute generators. */
|
|
480
|
+
interface MutationDefaultGeneratorContributor {
|
|
481
|
+
readonly id: string;
|
|
482
|
+
readonly mutationDefaultGenerators?: () => ReadonlyArray<RuntimeMutationDefaultGenerator>;
|
|
483
|
+
}
|
|
484
|
+
type MutationDefaultsOp = 'create' | 'update';
|
|
485
|
+
interface MutationDefaultsOptions {
|
|
486
|
+
readonly op: MutationDefaultsOp;
|
|
487
|
+
/** Required: refs are namespace-scoped, so only defaults of `(namespace, entry)` apply, which tells same-named entries in different namespaces apart. */
|
|
488
|
+
readonly namespace: string;
|
|
489
|
+
readonly entry: string;
|
|
490
|
+
/** The values the caller writes. A key present here is explicit, whatever its value, and gets no default. */
|
|
491
|
+
readonly values: Readonly<Record<string, unknown>>;
|
|
492
|
+
/** Cache shared by the calls of one ORM operation, for `'query'`-stable generators. */
|
|
493
|
+
readonly defaultValueCache?: Map<string, unknown>;
|
|
494
|
+
}
|
|
495
|
+
interface AppliedMutationDefault {
|
|
496
|
+
readonly field: string;
|
|
497
|
+
readonly value: unknown;
|
|
498
|
+
}
|
|
499
|
+
interface MutationDefaults {
|
|
500
|
+
applyMutationDefaults(options: MutationDefaultsOptions): ReadonlyArray<AppliedMutationDefault>;
|
|
501
|
+
}
|
|
502
|
+
/** Registers every generator the contributors provide, by id. Two contributors providing one id is an error naming both. */
|
|
503
|
+
declare function collectMutationDefaultGenerators(contributors: ReadonlyArray<MutationDefaultGeneratorContributor>): ReadonlyMap<string, RuntimeMutationDefaultGenerator>;
|
|
504
|
+
/** Fails when the contract's mutation defaults name a generator the registry does not hold, listing every missing id and the fields that need it. */
|
|
505
|
+
declare function assertMutationDefaultGeneratorsAvailable(execution: ContractExecutionSection | undefined, generatorRegistry: ReadonlyMap<string, RuntimeMutationDefaultGenerator>): void;
|
|
506
|
+
/**
|
|
507
|
+
* The defaults to write for one record: for each mutation default of the entry and namespace whose phase matches `op`, the generated value of every field the values do not carry. An update with no keys gets none.
|
|
508
|
+
*/
|
|
509
|
+
declare function applyMutationDefaults(execution: ContractExecutionSection | undefined, generatorRegistry: ReadonlyMap<string, RuntimeMutationDefaultGenerator>, options: MutationDefaultsOptions): ReadonlyArray<AppliedMutationDefault>;
|
|
510
|
+
//#endregion
|
|
511
|
+
//#region src/execution/runtime-error.d.ts
|
|
512
|
+
/**
|
|
513
|
+
* Stable code emitted by the runtime when an in-flight `execute()`
|
|
514
|
+
* is cancelled via the per-query `AbortSignal`. The envelope's
|
|
515
|
+
* `details.phase` distinguishes where the abort was observed:
|
|
516
|
+
*
|
|
517
|
+
* - `'encode'` — abort fired during `encodeParams` (SQL) or
|
|
518
|
+
* `resolveValue` (Mongo).
|
|
519
|
+
* - `'decode'` — abort fired during `decodeRow` / `decodeField`.
|
|
520
|
+
* - `'stream'` — abort fired between rows or before any codec call
|
|
521
|
+
* (already-aborted at entry).
|
|
522
|
+
* - `'beforeEncode'` / `'onRow'` — abort fired on entry to or during
|
|
523
|
+
* the corresponding middleware phase
|
|
524
|
+
* (cooperative cancellation per the param-transform seam).
|
|
525
|
+
*/
|
|
526
|
+
declare const RUNTIME_ABORTED: "RUNTIME.ABORTED";
|
|
527
|
+
/** Discriminator placed in `details.phase` of a `RUNTIME.ABORTED` envelope. */
|
|
528
|
+
type RuntimeAbortedPhase = 'encode' | 'decode' | 'stream' | 'beforeEncode' | 'onRow';
|
|
529
|
+
/**
|
|
530
|
+
* Construct a `RUNTIME.ABORTED` envelope. Phase distinguishes where the
|
|
531
|
+
* abort was observed — codec call sites (`encode` / `decode` / `stream`)
|
|
532
|
+
* or operation-specific middleware seams, as
|
|
533
|
+
* enumerated on {@link RuntimeAbortedPhase}. Cause carries
|
|
534
|
+
* `signal.reason` verbatim from the platform — native abort produces a
|
|
535
|
+
* `DOMException`, explicit `controller.abort(reason)` produces whatever
|
|
536
|
+
* the caller passed. No synthesis happens here.
|
|
537
|
+
*/
|
|
538
|
+
declare function runtimeAborted(phase: RuntimeAbortedPhase, cause?: unknown): RuntimeErrorEnvelope;
|
|
539
|
+
//#endregion
|
|
540
|
+
//#region src/execution/race-against-abort.d.ts
|
|
541
|
+
/**
|
|
542
|
+
* Throw a phase-tagged `RUNTIME.ABORTED` envelope if the supplied
|
|
543
|
+
* context is already aborted at the precheck site. Centralises the
|
|
544
|
+
* `if (ctx.signal?.aborted) throw runtimeAborted(...)` pattern that
|
|
545
|
+
* every codec dispatch site (and the `beforeEncode` middleware phase)
|
|
546
|
+
* repeats. Accepts both the framework `CodecCallContext` and the
|
|
547
|
+
* `ActivityContext`; both expose `signal?: AbortSignal`.
|
|
548
|
+
*/
|
|
549
|
+
declare function checkAborted(ctx: {
|
|
550
|
+
readonly signal?: AbortSignal;
|
|
551
|
+
}, phase: RuntimeAbortedPhase): void;
|
|
552
|
+
/**
|
|
553
|
+
* Race a per-cell `Promise.all` (or any other in-flight work promise) against
|
|
554
|
+
* the supplied abort signal so the runtime returns `RUNTIME.ABORTED` promptly
|
|
555
|
+
* even when codec bodies ignore the signal. In-flight bodies that ignore the
|
|
556
|
+
* signal are abandoned and run to completion in the background — the
|
|
557
|
+
* cooperative-cancellation contract documented in ADR 204.
|
|
558
|
+
*
|
|
559
|
+
* Call sites still SHOULD pre-check `signal.aborted` and short-circuit with
|
|
560
|
+
* a phase-tagged `RUNTIME.ABORTED` envelope before invoking this helper —
|
|
561
|
+
* that path is the canonical "aborted at entry" surface and avoids
|
|
562
|
+
* scheduling the work promise. As a defensive belt-and-braces, this helper
|
|
563
|
+
* also handles the already-aborted case internally: `AbortSignal` does not
|
|
564
|
+
* replay past abort events to listeners registered after the abort, so we
|
|
565
|
+
* inspect `signal.aborted` synchronously and reject with the sentinel
|
|
566
|
+
* before installing the listener. The rejection is still attributed to the
|
|
567
|
+
* abort path via the sentinel-identity check.
|
|
568
|
+
*
|
|
569
|
+
* Distinguishing the rejection source is load-bearing for AC-ERR4
|
|
570
|
+
* (`RUNTIME.ENCODE_FAILED` / `RUNTIME.DECODE_FAILED` pass through unchanged).
|
|
571
|
+
* The semantically equivalent `abortable(signal)` helper in
|
|
572
|
+
* `@internal/utils` rejects with `signal.reason ?? new DOMException(...)`,
|
|
573
|
+
* which is not stably distinguishable from a codec-thrown error by identity
|
|
574
|
+
* alone (a fresh fallback DOMException is allocated per call). We instead
|
|
575
|
+
* track abort attribution with a unique sentinel: only the `onAbort` listener
|
|
576
|
+
* installed here ever rejects with the sentinel, so an `error === sentinel`
|
|
577
|
+
* identity check after the race is unambiguous.
|
|
578
|
+
*
|
|
579
|
+
* Lives in `framework-components` (rather than the SQL family, where it
|
|
580
|
+
* originated in m2) so every family runtime that needs cooperative
|
|
581
|
+
* cancellation around a codec-dispatch `Promise.all` (SQL encode + decode
|
|
582
|
+
* today, Mongo encode in m3) shares the same attribution logic.
|
|
583
|
+
*/
|
|
584
|
+
declare function raceAgainstAbort<T>(work: Promise<T>, signal: AbortSignal | undefined, phase: RuntimeAbortedPhase): Promise<T>;
|
|
585
|
+
//#endregion
|
|
586
|
+
//#region src/execution/run-with-middleware.d.ts
|
|
587
|
+
/** How a family runtime starts one statement activity. */
|
|
588
|
+
interface StatementOptions<TExec extends ExecutionPlan, TMutator extends ParamRefMutator, TContext extends ActivityContext> {
|
|
589
|
+
readonly middleware: ReadonlyArray<RuntimeMiddleware<TExec, TMutator>>;
|
|
590
|
+
/** The plan the caller sent. */
|
|
591
|
+
readonly plan: QueryPlan;
|
|
592
|
+
readonly context: ActivityContextFields<TContext>;
|
|
593
|
+
/** The open activity the statement runs beneath, such as the transaction it was sent on. */
|
|
594
|
+
readonly parent: ActivityParent | undefined;
|
|
595
|
+
}
|
|
596
|
+
/** One running statement activity, handed to the family's statement body. */
|
|
597
|
+
interface StatementActivityRun<TExec extends ExecutionPlan, TMutator extends ParamRefMutator, TContext extends ActivityContext> {
|
|
598
|
+
readonly activity: StatementActivity;
|
|
599
|
+
readonly ctx: TContext;
|
|
600
|
+
/** Runs every `beforeEncode` hook in registration order, raced against `ctx.signal`. */
|
|
601
|
+
beforeEncode(draft: TExec, params?: TMutator): Promise<void>;
|
|
602
|
+
/** Runs `intercept.onQuery`, then the intercepted rows or `runDriver()` with `onRow` for each driver row. `runDriver` is called only when no handler supplied rows. */
|
|
603
|
+
runQuery<Row>(exec: TExec, runDriver: () => AsyncIterable<Row>): AsyncIterable<Row>;
|
|
604
|
+
/** Runs `intercept.onExecute`, then `runDriver()` when no handler supplied statistics. */
|
|
605
|
+
runExecute(exec: TExec, runDriver: () => Promise<RuntimeStatementStats>): Promise<RuntimeStatementStats>;
|
|
606
|
+
}
|
|
607
|
+
/**
|
|
608
|
+
* Runs one `query()` statement as an activity. The activity starts on the first `next()`: `activityStarted`, then `body`'s rows, then `activityEnded` and, with no parent, `activityFinalized`. Each fires exactly once, whether the body succeeds, throws (`failed`) or the caller stops reading (`stopped`).
|
|
609
|
+
*/
|
|
610
|
+
declare function streamStatement<TExec extends ExecutionPlan, TMutator extends ParamRefMutator, TContext extends ActivityContext, Row>(options: StatementOptions<TExec, TMutator, TContext>, body: (statement: StatementActivityRun<TExec, TMutator, TContext>) => AsyncIterable<Row>): AsyncIterable<Row>;
|
|
611
|
+
/**
|
|
612
|
+
* Runs one `execute()` statement as an activity: `activityStarted`, then `body`, then `activityEnded` and, with no parent, `activityFinalized`, each exactly once.
|
|
613
|
+
*/
|
|
614
|
+
declare function executeStatement<TExec extends ExecutionPlan, TMutator extends ParamRefMutator, TContext extends ActivityContext>(options: StatementOptions<TExec, TMutator, TContext>, body: (statement: StatementActivityRun<TExec, TMutator, TContext>) => Promise<RuntimeStatementStats>): Promise<RuntimeStatementStats>;
|
|
615
|
+
//#endregion
|
|
616
|
+
//#region src/execution/runtime-core.d.ts
|
|
617
|
+
/**
|
|
618
|
+
* Constructor options shared by every concrete `RuntimeCore` subclass. `ctx` holds the context fields every statement's activity context starts from.
|
|
619
|
+
*/
|
|
620
|
+
interface RuntimeCoreOptions<TMiddleware extends RuntimeMiddleware<ExecutionPlan>> {
|
|
621
|
+
readonly middleware: ReadonlyArray<TMiddleware>;
|
|
622
|
+
readonly ctx: ActivityContextFields;
|
|
623
|
+
}
|
|
624
|
+
/**
|
|
625
|
+
* Family-agnostic abstract runtime base. Each `query()` and `execute()` call is one statement activity, run in this order: `activityStarted`, `runBeforeCompile`, `lower`, `beforeEncode`, `intercept`, the driver with `onRow`, `activityEnded`, then `activityFinalized`. It has no parent, so it is finalized right after it ends.
|
|
626
|
+
*
|
|
627
|
+
* Concrete subclasses implement `lower`, `runDriver`, `runExecute` and `close`.
|
|
628
|
+
*/
|
|
629
|
+
declare abstract class RuntimeCore<TPlan extends QueryPlan, TExec extends ExecutionPlan, TMiddleware extends RuntimeMiddleware<TExec>> implements RuntimeExecutor<TPlan> {
|
|
630
|
+
protected readonly middleware: ReadonlyArray<TMiddleware>;
|
|
631
|
+
protected readonly ctx: ActivityContextFields;
|
|
632
|
+
constructor(options: RuntimeCoreOptions<TMiddleware>);
|
|
633
|
+
/** Pre-lowering hook for plan rewriting. Defaults to identity. */
|
|
634
|
+
protected runBeforeCompile(plan: TPlan): TPlan | Promise<TPlan>;
|
|
635
|
+
/** Lowers a `TPlan` into the family's executable `TExec`, forwarding `ctx` to the encode-side codecs. */
|
|
636
|
+
protected abstract lower(plan: TPlan, ctx: CodecCallContext): TExec | Promise<TExec>;
|
|
637
|
+
/** Drives the transport for a lowered `TExec`, yielding raw rows. */
|
|
638
|
+
protected abstract runDriver(exec: TExec): AsyncIterable<Record<string, unknown>>;
|
|
639
|
+
protected abstract runExecute(exec: TExec): Promise<RuntimeStatementStats>;
|
|
640
|
+
abstract close(): Promise<void>;
|
|
641
|
+
query<Row>(plan: TPlan & {
|
|
642
|
+
readonly _row?: Row;
|
|
643
|
+
}, options?: RuntimeExecuteOptions): AsyncIterableResult<Row>;
|
|
644
|
+
execute(plan: TPlan, options?: RuntimeExecuteOptions): Promise<RuntimeStatementStats>;
|
|
645
|
+
private contextFieldsFor;
|
|
646
|
+
}
|
|
647
|
+
//#endregion
|
|
648
|
+
//#region src/execution/shape.d.ts
|
|
649
|
+
/**
|
|
650
|
+
* Phantom key an emitted model type carries to name its relation properties.
|
|
651
|
+
* Never present at runtime; `Scalars` and `Shape` read it to tell relations from fields.
|
|
652
|
+
*/
|
|
653
|
+
declare const RelationKeys: unique symbol;
|
|
654
|
+
/**
|
|
655
|
+
* The relation names an emitted model type declares.
|
|
656
|
+
*/
|
|
657
|
+
type RelationNamesOf<M> = Rel<M>;
|
|
658
|
+
/**
|
|
659
|
+
* Without `exactOptionalPropertyTypes` the optional phantom infers `R | undefined`, so the
|
|
660
|
+
* inferred type is filtered rather than constrained: `infer R extends string` would fall back to
|
|
661
|
+
* `string` there.
|
|
662
|
+
*/
|
|
663
|
+
type Rel<M> = M extends {
|
|
664
|
+
readonly [RelationKeys]?: infer R;
|
|
665
|
+
} ? Extract<R, string> : never;
|
|
666
|
+
/**
|
|
667
|
+
* The scalar row of a model: every field, no relations, no phantom.
|
|
668
|
+
* Distributes over a union, so the row of a polymorphic `Any<Base>` is the union of its variants' rows.
|
|
669
|
+
*/
|
|
670
|
+
type Scalars<M> = M extends {
|
|
671
|
+
readonly [RelationKeys]?: unknown;
|
|
672
|
+
} ? Omit<M, Rel<M> | typeof RelationKeys> : M;
|
|
673
|
+
/**
|
|
674
|
+
* An application data structure derived from a model.
|
|
675
|
+
*
|
|
676
|
+
* At every level of `Spec`: `'+'` names scalars and relations to keep, and narrows the scalars only
|
|
677
|
+
* when it names one; `'-'` names scalars to drop; any other key is a relation whose value is a spec
|
|
678
|
+
* that narrows the related model. A relation named in `'+'` comes with all of its scalars and none of
|
|
679
|
+
* its relations. Relations are absent unless asked for; cardinality and nullability come from the
|
|
680
|
+
* model. Distributes over a union, so each variant of `Any<Base>` keeps only its own relations.
|
|
681
|
+
*/
|
|
682
|
+
type Shape<M, Spec extends ShapeSpec<M, Spec> = Record<never, never>> = ShapeOf<M, Spec>;
|
|
683
|
+
/**
|
|
684
|
+
* The constraint a `Shape` spec satisfies. A generic that forwards a spec needs it:
|
|
685
|
+
* `type Response<S extends ShapeSpec<User, S>> = Shape<User, S>`.
|
|
686
|
+
*/
|
|
687
|
+
type ShapeSpec<M, Spec> = { readonly [K in keyof Spec]: K extends '+' ? Exclude<PlusNames<M, Spec>, keyof Spec> : K extends '-' ? ScalarNamesOf<M> : K extends RelationNamesOf<M> ? ShapeSpec<RelatedModel<M, K>, Spec[K]> : UnknownSpecKey<M, K>; };
|
|
688
|
+
type PlusNames<M, Spec> = '-' extends keyof Spec ? RelationNamesOf<M> : ScalarNamesOf<M> | RelationNamesOf<M>;
|
|
689
|
+
type UnknownSpecKey<M, K> = [RelationNamesOf<M>] extends [never] ? `'${K & string}' is not a relation of the model, which has none; try '+' or '-'` : `'${K & string}' is not a relation of the model; try '+', '-', or '${RelationNamesOf<M>}'`;
|
|
690
|
+
type ScalarNamesOf<M> = M extends unknown ? keyof Scalars<M> & string : never;
|
|
691
|
+
type RelatedModel<M, K> = M extends unknown ? K extends keyof M ? UnwrapRelation<M[K]> : never : never;
|
|
692
|
+
type UnwrapRelation<V> = V extends (infer Item)[] ? Item : NonNullable<V>;
|
|
693
|
+
type ShapeOf<M, Spec> = ShapeOfEach<M, Spec, PlusNamesAScalar<M, Spec>>;
|
|
694
|
+
type PlusNamesAScalar<M, Spec> = Spec extends {
|
|
695
|
+
readonly '+': infer Keep;
|
|
696
|
+
} ? [Extract<Keep, ScalarNamesOf<M>>] extends [never] ? false : true : false;
|
|
697
|
+
type ShapeOfEach<M, Spec, Narrow extends boolean> = M extends unknown ? Flatten<KeptScalars<M, Spec, Narrow> & { [K in IncludedRelations<M, Spec>]: WrapLike<M[K], ShapeOf<RelatedModel<M, K>, NestedSpec<Spec, K>>>; }> : never;
|
|
698
|
+
type KeptScalars<M, Spec, Narrow extends boolean> = Narrow extends true ? Spec extends {
|
|
699
|
+
readonly '+': infer Keep;
|
|
700
|
+
} ? Pick<Scalars<M>, Extract<Keep, keyof Scalars<M>>> : never : Spec extends {
|
|
701
|
+
readonly '-': infer Drop extends PropertyKey;
|
|
702
|
+
} ? Omit<Scalars<M>, Drop> : Scalars<M>;
|
|
703
|
+
type IncludedRelations<M, Spec> = Extract<keyof Spec | (Spec extends {
|
|
704
|
+
readonly '+': infer Keep;
|
|
705
|
+
} ? Keep : never), RelationNamesOf<M> & keyof M>;
|
|
706
|
+
type NestedSpec<Spec, K> = K extends keyof Spec ? Spec[K] : Record<never, never>;
|
|
707
|
+
type WrapLike<V, R> = V extends unknown[] ? R[] : null extends V ? R | null : R;
|
|
708
|
+
type Flatten<T> = { [K in keyof T]: T[K]; };
|
|
709
|
+
//#endregion
|
|
710
|
+
//#region src/execution/transaction-activity.d.ts
|
|
711
|
+
/** How a transaction's `commit()` or `rollback()` settled. */
|
|
712
|
+
type TransactionSettlement = {
|
|
713
|
+
readonly by: 'commit';
|
|
714
|
+
readonly outcome: 'succeeded' | 'failed';
|
|
715
|
+
} | {
|
|
716
|
+
readonly by: 'rollback';
|
|
717
|
+
readonly outcome: 'succeeded' | 'failed';
|
|
718
|
+
/** Whether `commit()` was called before this rollback. */
|
|
719
|
+
readonly commitAttempted: boolean;
|
|
720
|
+
};
|
|
721
|
+
/** An open transaction activity. Pass it as the `parent` of every statement sent while the transaction is open. */
|
|
722
|
+
interface TransactionActivityRun<TContext extends ActivityContext = ActivityContext> extends ActivityParent {
|
|
723
|
+
readonly activity: TransactionActivity;
|
|
724
|
+
readonly ctx: TContext;
|
|
725
|
+
/**
|
|
726
|
+
* Ends the transaction: its `activityEnded` hooks, then the `activityFinalized` hooks of its children that have ended, in the order they started, then its own. Resolves after those hooks have run. A child still open is finalized when it ends, with this transaction's outcome; `end` does not wait for it. A second call does nothing. An `activityEnded` error after a successful settlement is rethrown once finalization has run.
|
|
727
|
+
*/
|
|
728
|
+
end(settlement: TransactionSettlement): Promise<void>;
|
|
729
|
+
}
|
|
730
|
+
interface TransactionActivityOptions<TContext extends ActivityContext> {
|
|
731
|
+
readonly middleware: ReadonlyArray<ActivityObserver>;
|
|
732
|
+
readonly context: ActivityContextFields<TContext>;
|
|
733
|
+
/** Whether the transaction keeps its finished children to finalize them when it ends. A runtime decides this once, when it is created: only when a middleware implements `activityFinalized`. Without it, the transaction keeps nothing but whether a child failed. */
|
|
734
|
+
readonly holdFinishedChildren: boolean;
|
|
735
|
+
}
|
|
736
|
+
/**
|
|
737
|
+
* Starts a transaction activity and runs its `activityStarted` hooks. When one of them throws, the transaction ends `failed`, is finalized `rolled-back`, and the error is rethrown.
|
|
738
|
+
*/
|
|
739
|
+
declare function startTransactionActivity<TContext extends ActivityContext>(options: TransactionActivityOptions<TContext>): Promise<TransactionActivityRun<TContext>>;
|
|
740
|
+
//#endregion
|
|
741
|
+
//#region src/meta-builder.d.ts
|
|
742
|
+
/**
|
|
743
|
+
* Per-terminal meta configurator handed to user callbacks. The terminal's
|
|
744
|
+
* operation kind `K` is fixed by the terminal that constructed the builder;
|
|
745
|
+
* `annotate(...)` accepts only annotations whose declared `Kinds` include
|
|
746
|
+
* `K`.
|
|
747
|
+
*
|
|
748
|
+
* The conditional parameter type
|
|
749
|
+
* `K extends Kinds ? AnnotationValue<P, Kinds> : never` collapses to `never`
|
|
750
|
+
* for inapplicable annotations, surfacing the mismatch as a type error at
|
|
751
|
+
* the call site of `meta.annotate(...)`. No variadic-tuple inference is
|
|
752
|
+
* involved — TypeScript infers `Kinds` from the annotation argument and
|
|
753
|
+
* checks the conditional directly.
|
|
754
|
+
*
|
|
755
|
+
* The runtime gate inside `annotate` (via
|
|
756
|
+
* `assertAnnotationsApplicable`) catches cast / `any` / dynamic bypasses
|
|
757
|
+
* and throws `RUNTIME.ANNOTATION_INAPPLICABLE`.
|
|
758
|
+
*
|
|
759
|
+
* `annotate` returns the builder for chaining; the return value of the
|
|
760
|
+
* configurator callback is unused, so both block-body and expression-body
|
|
761
|
+
* callbacks compile.
|
|
762
|
+
*
|
|
763
|
+
* @example
|
|
764
|
+
* ```typescript
|
|
765
|
+
* await db.User.find({ id }, (meta) => meta.annotate(cacheAnnotation({ ttl: 60 })));
|
|
766
|
+
* await db.User.create(input, (meta) => {
|
|
767
|
+
* meta.annotate(auditAnnotation({ actor: 'system' }));
|
|
768
|
+
* meta.annotate(otelAnnotation({ traceId }));
|
|
769
|
+
* });
|
|
770
|
+
* ```
|
|
771
|
+
*/
|
|
772
|
+
interface MetaBuilder<K extends OperationKind> {
|
|
773
|
+
annotate<P, Kinds extends OperationKind>(annotation: K extends Kinds ? AnnotationValue<P, Kinds> : never): this;
|
|
774
|
+
}
|
|
775
|
+
/**
|
|
776
|
+
* Lane-side view of a meta builder. Extends the public `MetaBuilder<K>`
|
|
777
|
+
* surface with `annotations` so lane terminals can read the recorded map
|
|
778
|
+
* after invoking the user configurator.
|
|
779
|
+
*
|
|
780
|
+
* Lane terminals construct one of these via `createMetaBuilder(kind, terminalName)`,
|
|
781
|
+
* pass it to the user callback as `MetaBuilder<K>` (the narrower public
|
|
782
|
+
* view), then read `meta.annotations` to thread the recorded values into
|
|
783
|
+
* `plan.meta.annotations`.
|
|
784
|
+
*/
|
|
785
|
+
interface LaneMetaBuilder<K extends OperationKind> extends MetaBuilder<K> {
|
|
786
|
+
readonly annotations: ReadonlyMap<string, AnnotationValue<unknown, OperationKind>>;
|
|
787
|
+
}
|
|
788
|
+
/**
|
|
789
|
+
* Construct a lane-side meta builder for a terminal of operation kind `K`.
|
|
790
|
+
*
|
|
791
|
+
* Lane terminals call this with their `kind` (`'read'` or `'write'`) and a
|
|
792
|
+
* `terminalName` for error messages, hand the resulting builder to the
|
|
793
|
+
* user-supplied configurator callback (typed as `MetaBuilder<K>`, the
|
|
794
|
+
* narrower public view), and read `meta.annotations` afterwards to thread
|
|
795
|
+
* the recorded values into `plan.meta.annotations`.
|
|
796
|
+
*/
|
|
797
|
+
declare function createMetaBuilder<K extends OperationKind>(kind: K, terminalName: string): LaneMetaBuilder<K>;
|
|
798
|
+
//#endregion
|
|
799
|
+
export { TransactionActivityRun as $, RUNTIME_ABORTED as A, RuntimeLog as B, MutationDefaults as C, ParamRefMutator as D, OperationKind as E, RuntimeActivity as F, Shape as G, RuntimeMutationDefaultGenerator as H, RuntimeCore as I, StatementActivityRun as J, ShapeSpec as K, RuntimeCoreOptions as L, RelationNamesOf as M, ResultType as N, QueryInterceptResult as O, RuntimeAbortedPhase as P, TransactionActivityOptions as Q, RuntimeExecuteOptions as R, MutationDefaultGeneratorContributor as S, MutationDefaultsOptions as T, RuntimeStatementStats as U, RuntimeMiddleware as V, Scalars as W, StatementOptions as X, StatementEnded as Y, TransactionActivity as Z, ExecuteInterceptResult as _, ActivityEndedResult as a, assertMutationDefaultGeneratorsAvailable as at, LaneMetaBuilder as b, ActivityParent as c, collectMutationDefaultGenerators as ct, AnnotationSource as d, defineAnnotation as dt, TransactionEnded as et, AnnotationValue as f, executeStatement as ft, DefineAnnotationOptions as g, streamStatement as gt, CrossFamilyMiddleware as h, startTransactionActivity as ht, ActivityContextFields as i, assertAnnotationsApplicable as it, RelationKeys as j, QueryPlan as k, ActivityStateStore as l, createMetaBuilder as lt, AsyncIterableResult as m, runtimeAborted as mt, ActivityChild as n, ValidAnnotations as nt, ActivityFinalizedResult as o, checkAborted as ot, AppliedMutationDefault as p, raceAgainstAbort as pt, StatementActivity as q, ActivityContext as r, applyMutationDefaults as rt, ActivityObserver as s, checkMiddlewareCompatibility as st, ActivityBase as t, TransactionSettlement as tt, AnnotationHandle as u, createStateStore as ut, ExecutionPlan as v, MutationDefaultsOp as w, MetaBuilder as x, GeneratorStability as y, RuntimeExecutor as z };
|
|
800
|
+
//# sourceMappingURL=runtime-Bl61xROB.d.mts.map
|