@prisma-next/framework-components 0.5.0-dev.4 → 0.5.0-dev.41
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/README.md +61 -0
- package/dist/authoring.d.mts +1 -1
- package/dist/authoring.mjs +1 -1
- package/dist/authoring.mjs.map +1 -1
- package/dist/codec-types-CB0jWeHU.d.mts +207 -0
- package/dist/codec-types-CB0jWeHU.d.mts.map +1 -0
- package/dist/codec.d.mts +2 -2
- package/dist/codec.mjs +38 -2
- package/dist/codec.mjs.map +1 -1
- package/dist/components.d.mts +1 -1
- package/dist/components.mjs +1 -1
- package/dist/control.d.mts +101 -35
- package/dist/control.d.mts.map +1 -1
- package/dist/control.mjs +11 -5
- package/dist/control.mjs.map +1 -1
- package/dist/emission-types-D6t3_a0x.d.mts +39 -0
- package/dist/emission-types-D6t3_a0x.d.mts.map +1 -0
- package/dist/emission.d.mts +2 -2
- package/dist/execution.d.mts +5 -5
- package/dist/execution.d.mts.map +1 -1
- package/dist/execution.mjs +3 -3
- package/dist/execution.mjs.map +1 -1
- package/dist/{framework-authoring-D1-JZ37B.d.mts → framework-authoring-BdrFDx4x.d.mts} +2 -2
- package/dist/framework-authoring-BdrFDx4x.d.mts.map +1 -0
- package/dist/{framework-components-EJXe-pum.d.mts → framework-components-AHI6V96G.d.mts} +6 -6
- package/dist/framework-components-AHI6V96G.d.mts.map +1 -0
- package/dist/{framework-components-C8ZhSwXe.mjs → framework-components-BsWST1Rn.mjs} +2 -2
- package/dist/framework-components-BsWST1Rn.mjs.map +1 -0
- package/dist/psl-ast-9X5rwo98.d.mts +159 -0
- package/dist/psl-ast-9X5rwo98.d.mts.map +1 -0
- package/dist/psl-ast.d.mts +2 -0
- package/dist/psl-ast.mjs +1 -0
- package/dist/runtime.d.mts +251 -19
- package/dist/runtime.d.mts.map +1 -1
- package/dist/runtime.mjs +215 -4
- package/dist/runtime.mjs.map +1 -1
- package/dist/{types-import-spec-C4sc7wbb.d.mts → types-import-spec-D-O6GotH.d.mts} +2 -2
- package/dist/types-import-spec-D-O6GotH.d.mts.map +1 -0
- package/package.json +8 -6
- package/src/control/control-capabilities.ts +71 -0
- package/src/{control-descriptors.ts → control/control-descriptors.ts} +7 -7
- package/src/{control-instances.ts → control/control-instances.ts} +6 -6
- package/src/{control-migration-types.ts → control/control-migration-types.ts} +48 -23
- package/src/control/control-operation-preview.ts +23 -0
- package/src/{control-stack.ts → control/control-stack.ts} +13 -13
- package/src/control/emission-types.ts +49 -0
- package/src/control/psl-ast.ts +193 -0
- package/src/{execution-descriptors.ts → execution/execution-descriptors.ts} +7 -7
- package/src/{execution-instances.ts → execution/execution-instances.ts} +1 -1
- package/src/{execution-requirements.ts → execution/execution-requirements.ts} +1 -1
- package/src/execution/query-plan.ts +53 -0
- package/src/execution/race-against-abort.ts +85 -0
- package/src/execution/run-with-middleware.ts +77 -0
- package/src/execution/runtime-core.ts +133 -0
- package/src/execution/runtime-error.ts +83 -0
- package/src/{runtime-middleware.ts → execution/runtime-middleware.ts} +32 -12
- package/src/exports/authoring.ts +2 -2
- package/src/exports/codec.ts +14 -2
- package/src/exports/components.ts +2 -2
- package/src/exports/control.ts +26 -12
- package/src/exports/emission.ts +2 -2
- package/src/exports/execution.ts +5 -5
- package/src/exports/psl-ast.ts +1 -0
- package/src/exports/runtime.ts +16 -5
- package/src/shared/codec-types.ts +261 -0
- package/dist/codec-types-B58nCJiu.d.mts +0 -40
- package/dist/codec-types-B58nCJiu.d.mts.map +0 -1
- package/dist/emission-types-BPAALJbF.d.mts +0 -24
- package/dist/emission-types-BPAALJbF.d.mts.map +0 -1
- package/dist/framework-authoring-D1-JZ37B.d.mts.map +0 -1
- package/dist/framework-components-C8ZhSwXe.mjs.map +0 -1
- package/dist/framework-components-EJXe-pum.d.mts.map +0 -1
- package/dist/types-import-spec-C4sc7wbb.d.mts.map +0 -1
- package/src/codec-types.ts +0 -46
- package/src/control-capabilities.ts +0 -34
- package/src/emission-types.ts +0 -28
- package/src/runtime-error.ts +0 -39
- /package/src/{control-result-types.ts → control/control-result-types.ts} +0 -0
- /package/src/{control-schema-view.ts → control/control-schema-view.ts} +0 -0
- /package/src/{async-iterable-result.ts → execution/async-iterable-result.ts} +0 -0
- /package/src/{execution-stack.ts → execution/execution-stack.ts} +0 -0
- /package/src/{framework-authoring.ts → shared/framework-authoring.ts} +0 -0
- /package/src/{framework-components.ts → shared/framework-components.ts} +0 -0
- /package/src/{mutation-default-types.ts → shared/mutation-default-types.ts} +0 -0
- /package/src/{types-import-spec.ts → shared/types-import-spec.ts} +0 -0
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import type { PlanMeta } from '@prisma-next/contract/types';
|
|
2
1
|
import type { AsyncIterableResult } from './async-iterable-result';
|
|
2
|
+
import type { QueryPlan } from './query-plan';
|
|
3
3
|
import { runtimeError } from './runtime-error';
|
|
4
4
|
|
|
5
5
|
export interface RuntimeLog {
|
|
@@ -22,33 +22,53 @@ export interface AfterExecuteResult {
|
|
|
22
22
|
readonly completed: boolean;
|
|
23
23
|
}
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
/**
|
|
26
|
+
* Family-agnostic middleware SPI parameterized over the plan marker.
|
|
27
|
+
*
|
|
28
|
+
* `TPlan` defaults to the framework `QueryPlan` marker so a generic
|
|
29
|
+
* middleware (e.g. cross-family telemetry) can be authored without
|
|
30
|
+
* naming a family. Family-specific middleware (`SqlMiddleware`,
|
|
31
|
+
* `MongoMiddleware`) narrow `TPlan` to their concrete plan type.
|
|
32
|
+
*/
|
|
33
|
+
export interface RuntimeMiddleware<TPlan extends QueryPlan = QueryPlan> {
|
|
26
34
|
readonly name: string;
|
|
27
35
|
readonly familyId?: string;
|
|
28
36
|
readonly targetId?: string;
|
|
29
|
-
beforeExecute?(plan:
|
|
30
|
-
onRow?(
|
|
31
|
-
row: Record<string, unknown>,
|
|
32
|
-
plan: { readonly meta: PlanMeta },
|
|
33
|
-
ctx: RuntimeMiddlewareContext,
|
|
34
|
-
): Promise<void>;
|
|
37
|
+
beforeExecute?(plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
|
|
38
|
+
onRow?(row: Record<string, unknown>, plan: TPlan, ctx: RuntimeMiddlewareContext): Promise<void>;
|
|
35
39
|
afterExecute?(
|
|
36
|
-
plan:
|
|
40
|
+
plan: TPlan,
|
|
37
41
|
result: AfterExecuteResult,
|
|
38
42
|
ctx: RuntimeMiddlewareContext,
|
|
39
43
|
): Promise<void>;
|
|
40
44
|
}
|
|
41
45
|
|
|
46
|
+
/**
|
|
47
|
+
* Optional per-`execute` options accepted by every family runtime.
|
|
48
|
+
*
|
|
49
|
+
* `signal` is the per-query cancellation signal. The runtime threads the
|
|
50
|
+
* signal through to every codec call for the query and uses it to short-
|
|
51
|
+
* circuit the row stream with `RUNTIME.ABORTED` when the caller aborts.
|
|
52
|
+
* Omitting the option (or passing `undefined`) preserves today's behavior
|
|
53
|
+
* bit-for-bit.
|
|
54
|
+
*/
|
|
55
|
+
export interface RuntimeExecuteOptions {
|
|
56
|
+
readonly signal?: AbortSignal;
|
|
57
|
+
}
|
|
58
|
+
|
|
42
59
|
/**
|
|
43
60
|
* Cross-family SPI for any runtime that can execute plans and be shut down.
|
|
44
61
|
* Each family runtime (SQL, Mongo) satisfies this interface — SQL nominally,
|
|
45
62
|
* Mongo structurally (due to its phantom Row parameter using a unique symbol).
|
|
46
63
|
*
|
|
47
64
|
* The `_row` intersection on `execute` connects the `Row` type parameter to the
|
|
48
|
-
* plan, mirroring how `
|
|
65
|
+
* plan, mirroring how `QueryPlan<Row>` carries a phantom `_row?: Row`.
|
|
49
66
|
*/
|
|
50
|
-
export interface RuntimeExecutor<TPlan extends
|
|
51
|
-
execute<Row>(
|
|
67
|
+
export interface RuntimeExecutor<TPlan extends QueryPlan> {
|
|
68
|
+
execute<Row>(
|
|
69
|
+
plan: TPlan & { readonly _row?: Row },
|
|
70
|
+
options?: RuntimeExecuteOptions,
|
|
71
|
+
): AsyncIterableResult<Row>;
|
|
52
72
|
close(): Promise<void>;
|
|
53
73
|
}
|
|
54
74
|
|
package/src/exports/authoring.ts
CHANGED
|
@@ -10,7 +10,7 @@ export type {
|
|
|
10
10
|
AuthoringTemplateValue,
|
|
11
11
|
AuthoringTypeConstructorDescriptor,
|
|
12
12
|
AuthoringTypeNamespace,
|
|
13
|
-
} from '../framework-authoring';
|
|
13
|
+
} from '../shared/framework-authoring';
|
|
14
14
|
export {
|
|
15
15
|
instantiateAuthoringFieldPreset,
|
|
16
16
|
instantiateAuthoringTypeConstructor,
|
|
@@ -19,4 +19,4 @@ export {
|
|
|
19
19
|
isAuthoringTypeConstructorDescriptor,
|
|
20
20
|
resolveAuthoringTemplateValue,
|
|
21
21
|
validateAuthoringHelperArguments,
|
|
22
|
-
} from '../framework-authoring';
|
|
22
|
+
} from '../shared/framework-authoring';
|
package/src/exports/codec.ts
CHANGED
|
@@ -1,2 +1,14 @@
|
|
|
1
|
-
export type {
|
|
2
|
-
|
|
1
|
+
export type {
|
|
2
|
+
Codec,
|
|
3
|
+
CodecCallContext,
|
|
4
|
+
CodecDescriptor,
|
|
5
|
+
CodecInstanceContext,
|
|
6
|
+
CodecLookup,
|
|
7
|
+
CodecMeta,
|
|
8
|
+
CodecTrait,
|
|
9
|
+
} from '../shared/codec-types';
|
|
10
|
+
export {
|
|
11
|
+
emptyCodecLookup,
|
|
12
|
+
synthesizeNonParameterizedDescriptor,
|
|
13
|
+
voidParamsSchema,
|
|
14
|
+
} from '../shared/codec-types';
|
|
@@ -20,5 +20,5 @@ export type {
|
|
|
20
20
|
TargetDescriptor,
|
|
21
21
|
TargetInstance,
|
|
22
22
|
TargetPackRef,
|
|
23
|
-
} from '../framework-components';
|
|
24
|
-
export { checkContractComponentRequirements } from '../framework-components';
|
|
23
|
+
} from '../shared/framework-components';
|
|
24
|
+
export { checkContractComponentRequirements } from '../shared/framework-components';
|
package/src/exports/control.ts
CHANGED
|
@@ -1,19 +1,29 @@
|
|
|
1
|
-
export type {
|
|
2
|
-
|
|
1
|
+
export type {
|
|
2
|
+
MigratableTargetDescriptor,
|
|
3
|
+
OperationPreviewCapable,
|
|
4
|
+
PslContractInferCapable,
|
|
5
|
+
SchemaViewCapable,
|
|
6
|
+
} from '../control/control-capabilities';
|
|
7
|
+
export {
|
|
8
|
+
hasMigrations,
|
|
9
|
+
hasOperationPreview,
|
|
10
|
+
hasPslContractInfer,
|
|
11
|
+
hasSchemaView,
|
|
12
|
+
} from '../control/control-capabilities';
|
|
3
13
|
export type {
|
|
4
14
|
ControlAdapterDescriptor,
|
|
5
15
|
ControlDriverDescriptor,
|
|
6
16
|
ControlExtensionDescriptor,
|
|
7
17
|
ControlFamilyDescriptor,
|
|
8
18
|
ControlTargetDescriptor,
|
|
9
|
-
} from '../control-descriptors';
|
|
19
|
+
} from '../control/control-descriptors';
|
|
10
20
|
export type {
|
|
11
21
|
ControlAdapterInstance,
|
|
12
22
|
ControlDriverInstance,
|
|
13
23
|
ControlExtensionInstance,
|
|
14
24
|
ControlFamilyInstance,
|
|
15
25
|
ControlTargetInstance,
|
|
16
|
-
} from '../control-instances';
|
|
26
|
+
} from '../control/control-instances';
|
|
17
27
|
export type {
|
|
18
28
|
DataTransformOperation,
|
|
19
29
|
MigrationOperationClass,
|
|
@@ -35,7 +45,11 @@ export type {
|
|
|
35
45
|
OpFactoryCall,
|
|
36
46
|
SerializedQueryPlan,
|
|
37
47
|
TargetMigrationsCapability,
|
|
38
|
-
} from '../control-migration-types';
|
|
48
|
+
} from '../control/control-migration-types';
|
|
49
|
+
export type {
|
|
50
|
+
OperationPreview,
|
|
51
|
+
OperationPreviewStatement,
|
|
52
|
+
} from '../control/control-operation-preview';
|
|
39
53
|
export type {
|
|
40
54
|
BaseSchemaIssue,
|
|
41
55
|
EmitContractResult,
|
|
@@ -47,25 +61,25 @@ export type {
|
|
|
47
61
|
SignDatabaseResult,
|
|
48
62
|
VerifyDatabaseResult,
|
|
49
63
|
VerifyDatabaseSchemaResult,
|
|
50
|
-
} from '../control-result-types';
|
|
64
|
+
} from '../control/control-result-types';
|
|
51
65
|
export {
|
|
52
66
|
VERIFY_CODE_HASH_MISMATCH,
|
|
53
67
|
VERIFY_CODE_MARKER_MISSING,
|
|
54
68
|
VERIFY_CODE_SCHEMA_FAILURE,
|
|
55
69
|
VERIFY_CODE_TARGET_MISMATCH,
|
|
56
|
-
} from '../control-result-types';
|
|
70
|
+
} from '../control/control-result-types';
|
|
57
71
|
export type {
|
|
58
72
|
CoreSchemaView,
|
|
59
73
|
SchemaNodeKind,
|
|
60
74
|
SchemaTreeNodeOptions,
|
|
61
75
|
SchemaTreeVisitor,
|
|
62
|
-
} from '../control-schema-view';
|
|
63
|
-
export { SchemaTreeNode } from '../control-schema-view';
|
|
76
|
+
} from '../control/control-schema-view';
|
|
77
|
+
export { SchemaTreeNode } from '../control/control-schema-view';
|
|
64
78
|
export type {
|
|
65
79
|
AssembledAuthoringContributions,
|
|
66
80
|
ControlStack,
|
|
67
81
|
CreateControlStackInput,
|
|
68
|
-
} from '../control-stack';
|
|
82
|
+
} from '../control/control-stack';
|
|
69
83
|
export {
|
|
70
84
|
assembleAuthoringContributions,
|
|
71
85
|
assembleControlMutationDefaults,
|
|
@@ -77,7 +91,7 @@ export {
|
|
|
77
91
|
extractComponentIds,
|
|
78
92
|
extractOperationTypeImports,
|
|
79
93
|
extractQueryOperationTypeImports,
|
|
80
|
-
} from '../control-stack';
|
|
94
|
+
} from '../control/control-stack';
|
|
81
95
|
export type {
|
|
82
96
|
ControlMutationDefaultEntry,
|
|
83
97
|
ControlMutationDefaultRegistry,
|
|
@@ -92,4 +106,4 @@ export type {
|
|
|
92
106
|
ParsedDefaultFunctionCall,
|
|
93
107
|
SourceDiagnostic,
|
|
94
108
|
SourceSpan,
|
|
95
|
-
} from '../mutation-default-types';
|
|
109
|
+
} from '../shared/mutation-default-types';
|
package/src/exports/emission.ts
CHANGED
|
@@ -2,5 +2,5 @@ export type {
|
|
|
2
2
|
EmissionSpi,
|
|
3
3
|
GenerateContractTypesOptions,
|
|
4
4
|
ValidationContext,
|
|
5
|
-
} from '../emission-types';
|
|
6
|
-
export type { TypesImportSpec } from '../types-import-spec';
|
|
5
|
+
} from '../control/emission-types';
|
|
6
|
+
export type { TypesImportSpec } from '../shared/types-import-spec';
|
package/src/exports/execution.ts
CHANGED
|
@@ -4,14 +4,14 @@ export type {
|
|
|
4
4
|
RuntimeExtensionDescriptor,
|
|
5
5
|
RuntimeFamilyDescriptor,
|
|
6
6
|
RuntimeTargetDescriptor,
|
|
7
|
-
} from '../execution-descriptors';
|
|
7
|
+
} from '../execution/execution-descriptors';
|
|
8
8
|
export type {
|
|
9
9
|
RuntimeAdapterInstance,
|
|
10
10
|
RuntimeDriverInstance,
|
|
11
11
|
RuntimeExtensionInstance,
|
|
12
12
|
RuntimeFamilyInstance,
|
|
13
13
|
RuntimeTargetInstance,
|
|
14
|
-
} from '../execution-instances';
|
|
15
|
-
export { assertRuntimeContractRequirementsSatisfied } from '../execution-requirements';
|
|
16
|
-
export type { ExecutionStack, ExecutionStackInstance } from '../execution-stack';
|
|
17
|
-
export { createExecutionStack, instantiateExecutionStack } from '../execution-stack';
|
|
14
|
+
} from '../execution/execution-instances';
|
|
15
|
+
export { assertRuntimeContractRequirementsSatisfied } from '../execution/execution-requirements';
|
|
16
|
+
export type { ExecutionStack, ExecutionStackInstance } from '../execution/execution-stack';
|
|
17
|
+
export { createExecutionStack, instantiateExecutionStack } from '../execution/execution-stack';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from '../control/psl-ast';
|
package/src/exports/runtime.ts
CHANGED
|
@@ -1,11 +1,22 @@
|
|
|
1
|
-
export { AsyncIterableResult } from '../async-iterable-result';
|
|
2
|
-
export type {
|
|
3
|
-
export {
|
|
1
|
+
export { AsyncIterableResult } from '../execution/async-iterable-result';
|
|
2
|
+
export type { ExecutionPlan, QueryPlan, ResultType } from '../execution/query-plan';
|
|
3
|
+
export { checkAborted, raceAgainstAbort } from '../execution/race-against-abort';
|
|
4
|
+
export { runWithMiddleware } from '../execution/run-with-middleware';
|
|
5
|
+
export type { RuntimeCoreOptions } from '../execution/runtime-core';
|
|
6
|
+
export { RuntimeCore } from '../execution/runtime-core';
|
|
7
|
+
export type { RuntimeAbortedPhase, RuntimeErrorEnvelope } from '../execution/runtime-error';
|
|
8
|
+
export {
|
|
9
|
+
isRuntimeError,
|
|
10
|
+
RUNTIME_ABORTED,
|
|
11
|
+
runtimeAborted,
|
|
12
|
+
runtimeError,
|
|
13
|
+
} from '../execution/runtime-error';
|
|
4
14
|
export type {
|
|
5
15
|
AfterExecuteResult,
|
|
16
|
+
RuntimeExecuteOptions,
|
|
6
17
|
RuntimeExecutor,
|
|
7
18
|
RuntimeLog,
|
|
8
19
|
RuntimeMiddleware,
|
|
9
20
|
RuntimeMiddlewareContext,
|
|
10
|
-
} from '../runtime-middleware';
|
|
11
|
-
export { checkMiddlewareCompatibility } from '../runtime-middleware';
|
|
21
|
+
} from '../execution/runtime-middleware';
|
|
22
|
+
export { checkMiddlewareCompatibility } from '../execution/runtime-middleware';
|
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
import type { JsonValue } from '@prisma-next/contract/types';
|
|
2
|
+
import type { StandardSchemaV1 } from '@standard-schema/spec';
|
|
3
|
+
|
|
4
|
+
export type CodecTrait =
|
|
5
|
+
| 'equality'
|
|
6
|
+
| 'order'
|
|
7
|
+
| 'boolean'
|
|
8
|
+
| 'numeric'
|
|
9
|
+
| 'textual'
|
|
10
|
+
/**
|
|
11
|
+
* The codec carries a per-instance `validate(value: unknown) =>
|
|
12
|
+
* JsonSchemaValidationResult` function on the resolved codec object that
|
|
13
|
+
* the framework's `JsonSchemaValidatorRegistry` consults at runtime. The
|
|
14
|
+
* trait gates the `extractValidator` cast from structurally-typed
|
|
15
|
+
* `unknown` to a typed validator view.
|
|
16
|
+
*
|
|
17
|
+
* Retirement target. The unified `CodecDescriptor` model moves
|
|
18
|
+
* validation into the resolved codec's `decode` body; the parallel
|
|
19
|
+
* `JsonSchemaValidatorRegistry` (and this trait alongside it) retires
|
|
20
|
+
* under TML-2357 (T3.5.12). Per-library JSON extensions like
|
|
21
|
+
* `@prisma-next/extension-arktype-json` already follow the new pattern.
|
|
22
|
+
*/
|
|
23
|
+
| 'json-validator';
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Per-call context the runtime threads to every `codec.encode` /
|
|
27
|
+
* `codec.decode` invocation for a single `runtime.execute()` call.
|
|
28
|
+
*
|
|
29
|
+
* The framework-level shape is family-agnostic and carries one field:
|
|
30
|
+
*
|
|
31
|
+
* - `signal?: AbortSignal` — per-query cancellation. The runtime returns
|
|
32
|
+
* a `RUNTIME.ABORTED` envelope when the signal aborts; codec authors
|
|
33
|
+
* who forward `signal` to their underlying SDK get true cancellation
|
|
34
|
+
* of in-flight network calls.
|
|
35
|
+
*
|
|
36
|
+
* Family layers extend this base with their own shape-of-call metadata:
|
|
37
|
+
* the SQL family adds `column?: SqlColumnRef` via `SqlCodecCallContext`
|
|
38
|
+
* (see `@prisma-next/sql-relational-core`). Mongo currently uses this
|
|
39
|
+
* framework type unchanged. Column metadata is intentionally **not** on
|
|
40
|
+
* the framework type — it is a SQL-family concept rooted in SQL's
|
|
41
|
+
* `(table, column)` addressing model and would not generalise to other
|
|
42
|
+
* families.
|
|
43
|
+
*
|
|
44
|
+
* The interface is named explicitly (not inlined) so future framework
|
|
45
|
+
* fields and family extensions can land additively without breaking
|
|
46
|
+
* codec author signatures.
|
|
47
|
+
*/
|
|
48
|
+
export interface CodecCallContext {
|
|
49
|
+
readonly signal?: AbortSignal;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* A codec is the contract between an application value and its on-wire and
|
|
54
|
+
* on-contract-disk representations.
|
|
55
|
+
*
|
|
56
|
+
* The author's mental model is two JS-side types — `TInput` (the
|
|
57
|
+
* application JS type) and `TWire` (the database driver wire format) —
|
|
58
|
+
* plus `JsonValue` for build-time contract artifacts. The codec translates
|
|
59
|
+
* `TInput` to `TWire` on writes and back on reads, and to/from `JsonValue`
|
|
60
|
+
* during contract emission and loading.
|
|
61
|
+
*
|
|
62
|
+
* Three representations participate:
|
|
63
|
+
* - **Input** (`TInput`): the JS type at the application boundary.
|
|
64
|
+
* - **Wire** (`TWire`): the format exchanged with the database driver.
|
|
65
|
+
* - **JSON** (`JsonValue`): a JSON-safe form used in contract artifacts.
|
|
66
|
+
*
|
|
67
|
+
* Codec methods split into two groups:
|
|
68
|
+
*
|
|
69
|
+
* - **Query-time** methods (`encode`, `decode`) run per row/parameter at the
|
|
70
|
+
* IO boundary; they are required and Promise-returning. The per-family
|
|
71
|
+
* codec factory accepts sync or async author functions and lifts sync
|
|
72
|
+
* ones to Promise-shaped methods automatically.
|
|
73
|
+
* - **Build-time** methods (`encodeJson`, `decodeJson`, `renderOutputType`)
|
|
74
|
+
* run when the contract is serialized, loaded, or when client types are
|
|
75
|
+
* emitted. They stay synchronous so contract validation and client
|
|
76
|
+
* construction are synchronous.
|
|
77
|
+
*
|
|
78
|
+
* Target-family codec interfaces extend this base with target-shaped
|
|
79
|
+
* metadata.
|
|
80
|
+
*/
|
|
81
|
+
export interface Codec<
|
|
82
|
+
Id extends string = string,
|
|
83
|
+
TTraits extends readonly CodecTrait[] = readonly CodecTrait[],
|
|
84
|
+
TWire = unknown,
|
|
85
|
+
TInput = unknown,
|
|
86
|
+
> {
|
|
87
|
+
/** Unique codec identifier in `namespace/name@version` format (e.g. `pg/timestamptz@1`). */
|
|
88
|
+
readonly id: Id;
|
|
89
|
+
/** Database-native type names this codec handles (e.g. `['timestamptz']`). */
|
|
90
|
+
readonly targetTypes: readonly string[];
|
|
91
|
+
/** Semantic traits for operator gating (e.g. equality, order, numeric). */
|
|
92
|
+
readonly traits?: TTraits;
|
|
93
|
+
/** Converts a JS value to the wire format expected by the database driver. Always Promise-returning at the boundary. The {@link CodecCallContext} is supplied by the runtime on every call (allocated once per `runtime.execute()`); family layers may narrow the ctx to extend it (e.g. SQL adds `column`). Author-side single-arg `(value) => …` functions remain legal via TypeScript's bivariance for trailing parameters. */
|
|
94
|
+
encode(value: TInput, ctx: CodecCallContext): Promise<TWire>;
|
|
95
|
+
/** Converts a wire value from the database driver into the JS application type. Always Promise-returning at the boundary. The {@link CodecCallContext} is supplied by the runtime on every call (allocated once per `runtime.execute()`); family layers may narrow the ctx to extend it (e.g. SQL adds `column`). Author-side single-arg `(wire) => …` functions remain legal via TypeScript's bivariance for trailing parameters. */
|
|
96
|
+
decode(wire: TWire, ctx: CodecCallContext): Promise<TInput>;
|
|
97
|
+
/** Converts a JS value to a JSON-safe representation for contract serialization. Synchronous; called during contract emission. */
|
|
98
|
+
encodeJson(value: TInput): JsonValue;
|
|
99
|
+
/** Converts a JSON representation back to the JS input type. Synchronous; called during contract loading via `validateContract`. */
|
|
100
|
+
decodeJson(json: JsonValue): TInput;
|
|
101
|
+
/** Produces the TypeScript output type expression for a field given its `typeParams`. Synchronous; used during contract.d.ts emission. */
|
|
102
|
+
renderOutputType?(typeParams: Record<string, unknown>): string | undefined;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
export interface CodecLookup {
|
|
106
|
+
get(id: string): Codec | undefined;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
export const emptyCodecLookup: CodecLookup = {
|
|
110
|
+
get: () => undefined,
|
|
111
|
+
};
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Family-agnostic per-instance context supplied by the framework when
|
|
115
|
+
* applying a higher-order codec factory. Allows stateful codecs (e.g.
|
|
116
|
+
* column-scoped encryption) to derive per-instance state from the
|
|
117
|
+
* materialization site.
|
|
118
|
+
*
|
|
119
|
+
* - `name` — the family-agnostic instance identity. For SQL, the runtime
|
|
120
|
+
* populates this as the `storage.types` instance name (e.g.
|
|
121
|
+
* `Embedding1536`) for typeRef-shaped columns, the synthesized
|
|
122
|
+
* anonymous instance name (`<anon:Document.embedding>`) for inline-
|
|
123
|
+
* `typeParams` columns, or a shared sentinel (`<shared:pg/text@1>`)
|
|
124
|
+
* for non-parameterized codec ids. Other families pick the analogous
|
|
125
|
+
* identity for their materialization sites.
|
|
126
|
+
*
|
|
127
|
+
* Family-specific extensions (e.g. {@link import('@prisma-next/sql-relational-core/ast').SqlCodecInstanceContext}
|
|
128
|
+
* in the SQL layer) augment this base with domain-shaped column-set
|
|
129
|
+
* metadata. Codec authors target the base when they don't read family-
|
|
130
|
+
* specific metadata; they target the family extension when they do.
|
|
131
|
+
*/
|
|
132
|
+
export interface CodecInstanceContext {
|
|
133
|
+
readonly name: string;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* Family-agnostic codec metadata. Family-specific extensions augment the
|
|
138
|
+
* base `db.<family>.<target>` block with native-type information; the base
|
|
139
|
+
* shape is an empty object so non-relational codecs can carry no metadata.
|
|
140
|
+
*/
|
|
141
|
+
export interface CodecMeta {
|
|
142
|
+
readonly db?: Record<string, unknown>;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* Unified codec descriptor. Every codec in the framework registers through
|
|
147
|
+
* this shape — non-parameterized codecs use `P = void` and a constant
|
|
148
|
+
* factory that returns the same shared codec instance for every column;
|
|
149
|
+
* parameterized codecs use a non-empty `P` and a curried higher-order
|
|
150
|
+
* factory that returns a per-instance codec.
|
|
151
|
+
*
|
|
152
|
+
* The descriptor is the codec-id-keyed source of truth for static metadata
|
|
153
|
+
* (`traits`, `targetTypes`, `meta`) and registration concerns
|
|
154
|
+
* (`paramsSchema` for JSON-boundary validation; optional `renderOutputType`
|
|
155
|
+
* for the `contract.d.ts` emit path). The runtime `Codec` instance returned
|
|
156
|
+
* by `factory(params)(ctx)` carries only the conversion behavior.
|
|
157
|
+
*
|
|
158
|
+
* Whether a codec id "is parameterized" stops being a registration-time
|
|
159
|
+
* distinction — it's a property of `P` on the descriptor. The descriptor
|
|
160
|
+
* map indexes every descriptor by `codecId`; both `descriptorFor(codecId)`
|
|
161
|
+
* and `forColumn(table, column)` resolve through the same map without
|
|
162
|
+
* branching on parameterization.
|
|
163
|
+
*
|
|
164
|
+
* @template P - The shape of the params accepted by the factory (`void` for
|
|
165
|
+
* non-parameterized codecs; a record like `{ length: number }` for
|
|
166
|
+
* parameterized codecs).
|
|
167
|
+
*
|
|
168
|
+
* Codec-registry-unification project § Decision.
|
|
169
|
+
*/
|
|
170
|
+
export interface CodecDescriptor<P = void> {
|
|
171
|
+
/** The codec ID this descriptor applies to (e.g. `pg/vector@1`, `pg/text@1`). */
|
|
172
|
+
readonly codecId: string;
|
|
173
|
+
/** Semantic traits for operator gating (e.g. equality, order, numeric). */
|
|
174
|
+
readonly traits: readonly CodecTrait[];
|
|
175
|
+
/** Database-native type names this codec handles (e.g. `['timestamptz']`). */
|
|
176
|
+
readonly targetTypes: readonly string[];
|
|
177
|
+
/** Optional family-specific metadata (e.g. SQL-side `db.sql.postgres.nativeType`). */
|
|
178
|
+
readonly meta?: CodecMeta;
|
|
179
|
+
/**
|
|
180
|
+
* Standard Schema validator for the factory's params. Validates JSON-
|
|
181
|
+
* sourced params at the contract boundary (PSL → IR; `contract.json` →
|
|
182
|
+
* runtime). For non-parameterized codecs (`P = void`), the schema
|
|
183
|
+
* validates `void`/`undefined` — the framework supplies no params at the
|
|
184
|
+
* call boundary.
|
|
185
|
+
*/
|
|
186
|
+
readonly paramsSchema: StandardSchemaV1<P>;
|
|
187
|
+
/**
|
|
188
|
+
* Emit-path string renderer for `contract.d.ts`. Returns the TypeScript
|
|
189
|
+
* output type expression for given params (e.g. `Vector<1536>`).
|
|
190
|
+
* Optional; absent renderers cause the emitter to fall back to the
|
|
191
|
+
* codec's base output type. Non-parameterized codecs typically omit it.
|
|
192
|
+
*/
|
|
193
|
+
readonly renderOutputType?: (params: P) => string | undefined;
|
|
194
|
+
/**
|
|
195
|
+
* The curried higher-order codec. For non-parameterized codecs, the
|
|
196
|
+
* factory is constant — every call returns the same shared codec
|
|
197
|
+
* instance. For parameterized codecs, the factory is called once per
|
|
198
|
+
* `storage.types` instance (or once per inline-`typeParams` column),
|
|
199
|
+
* with `ctx` carrying the column set the resulting codec serves.
|
|
200
|
+
*/
|
|
201
|
+
readonly factory: (params: P) => (ctx: CodecInstanceContext) => Codec;
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* Standard Schema validator for `void` params. Accepts only `undefined`
|
|
206
|
+
* (or absent input); rejects any other value so a contract that tries to
|
|
207
|
+
* thread `typeParams` through a non-parameterized codec id fails fast at
|
|
208
|
+
* the JSON boundary instead of silently coercing the value away. Used by
|
|
209
|
+
* the framework-supplied non-parameterized descriptor synthesizer.
|
|
210
|
+
*/
|
|
211
|
+
export const voidParamsSchema: StandardSchemaV1<void> = {
|
|
212
|
+
'~standard': {
|
|
213
|
+
version: 1,
|
|
214
|
+
vendor: 'prisma-next',
|
|
215
|
+
validate: (input) =>
|
|
216
|
+
input === undefined
|
|
217
|
+
? { value: undefined }
|
|
218
|
+
: {
|
|
219
|
+
issues: [
|
|
220
|
+
{
|
|
221
|
+
message: 'unexpected typeParams for non-parameterized codec (void params expected)',
|
|
222
|
+
},
|
|
223
|
+
],
|
|
224
|
+
},
|
|
225
|
+
},
|
|
226
|
+
};
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* Synthesize a `CodecDescriptor<void>` for a non-parameterized codec
|
|
230
|
+
* runtime instance. The factory is constant — every call returns the same
|
|
231
|
+
* shared codec instance — so columns sharing this codec id share one
|
|
232
|
+
* resolved codec.
|
|
233
|
+
*
|
|
234
|
+
* Codec-registry-unification spec § Decision (Case T — non-parameterized
|
|
235
|
+
* text codec). This is the bridge while non-parameterized codec
|
|
236
|
+
* contributors still register through the legacy `codecs:` slot; once they
|
|
237
|
+
* migrate to ship descriptors directly (TML-2357 T3.5.3), this synthesis
|
|
238
|
+
* steps aside.
|
|
239
|
+
*/
|
|
240
|
+
export function synthesizeNonParameterizedDescriptor(codec: Codec): CodecDescriptor<void> {
|
|
241
|
+
// The descriptor's `factory: (params: void) => (ctx: CodecInstanceContext)
|
|
242
|
+
// => Codec` is a constant for non-parameterized codecs — `params` is
|
|
243
|
+
// never read and the returned ctx-applier always yields the same shared
|
|
244
|
+
// codec. We rely on the descriptor's typed `factory` slot to infer the
|
|
245
|
+
// signatures rather than naming `void` locally (biome's
|
|
246
|
+
// `noConfusingVoidType` flags `void` outside return positions).
|
|
247
|
+
const sharedFactory = () => () => codec;
|
|
248
|
+
// Family-extended codecs (SQL `Codec`) carry an optional `meta` field
|
|
249
|
+
// that the base interface doesn't declare. Read it through a structural
|
|
250
|
+
// narrow so the synthesizer forwards it to the descriptor without losing
|
|
251
|
+
// type safety on the base shape.
|
|
252
|
+
const codecMeta = (codec as { readonly meta?: CodecMeta }).meta;
|
|
253
|
+
return {
|
|
254
|
+
codecId: codec.id,
|
|
255
|
+
traits: codec.traits ?? [],
|
|
256
|
+
targetTypes: codec.targetTypes,
|
|
257
|
+
paramsSchema: voidParamsSchema,
|
|
258
|
+
factory: sharedFactory,
|
|
259
|
+
...(codecMeta !== undefined ? { meta: codecMeta } : {}),
|
|
260
|
+
};
|
|
261
|
+
}
|
|
@@ -1,40 +0,0 @@
|
|
|
1
|
-
import { JsonValue } from "@prisma-next/contract/types";
|
|
2
|
-
|
|
3
|
-
//#region src/codec-types.d.ts
|
|
4
|
-
type CodecTrait = 'equality' | 'order' | 'boolean' | 'numeric' | 'textual';
|
|
5
|
-
/**
|
|
6
|
-
* Base codec interface for all target families.
|
|
7
|
-
*
|
|
8
|
-
* A codec maps between three representations of a value:
|
|
9
|
-
* - **JS** (`TJs`): the JavaScript type used in application code
|
|
10
|
-
* - **Wire** (`TWire`): the format sent to/from the database driver
|
|
11
|
-
* - **JSON** (`JsonValue`): the JSON-safe form stored in contract artifacts
|
|
12
|
-
*
|
|
13
|
-
* Family-specific codec interfaces (SQL `Codec`, Mongo `MongoCodec`) extend
|
|
14
|
-
* this base to add family-specific metadata.
|
|
15
|
-
*/
|
|
16
|
-
interface Codec<Id extends string = string, TTraits extends readonly CodecTrait[] = readonly CodecTrait[], TWire = unknown, TJs = unknown> {
|
|
17
|
-
/** Unique codec identifier in `namespace/name@version` format (e.g. `pg/timestamptz@1`). */
|
|
18
|
-
readonly id: Id;
|
|
19
|
-
/** Database-native type names this codec handles (e.g. `['timestamptz']`). */
|
|
20
|
-
readonly targetTypes: readonly string[];
|
|
21
|
-
/** Semantic traits for operator gating (e.g. equality, order, numeric). */
|
|
22
|
-
readonly traits?: TTraits;
|
|
23
|
-
/** Converts a JS value to the wire format expected by the database driver. Optional when the driver accepts the JS type directly. */
|
|
24
|
-
encode?(value: TJs): TWire;
|
|
25
|
-
/** Converts a wire value from the database driver into the JS type. */
|
|
26
|
-
decode(wire: TWire): TJs;
|
|
27
|
-
/** Converts a JS value to a JSON-safe representation for contract serialization. Called during contract emission. */
|
|
28
|
-
encodeJson(value: TJs): JsonValue;
|
|
29
|
-
/** Converts a JSON representation back to the JS type. Called during contract loading via `validateContract`. */
|
|
30
|
-
decodeJson(json: JsonValue): TJs;
|
|
31
|
-
/** Produces the TypeScript output type expression for a field given its `typeParams`. Used during contract.d.ts emission. */
|
|
32
|
-
renderOutputType?(typeParams: Record<string, unknown>): string | undefined;
|
|
33
|
-
}
|
|
34
|
-
interface CodecLookup {
|
|
35
|
-
get(id: string): Codec | undefined;
|
|
36
|
-
}
|
|
37
|
-
declare const emptyCodecLookup: CodecLookup;
|
|
38
|
-
//#endregion
|
|
39
|
-
export { emptyCodecLookup as i, CodecLookup as n, CodecTrait as r, Codec as t };
|
|
40
|
-
//# sourceMappingURL=codec-types-B58nCJiu.d.mts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"codec-types-B58nCJiu.d.mts","names":[],"sources":["../src/codec-types.ts"],"sourcesContent":[],"mappings":";;;KAEY,UAAA;;AAAZ;AAaA;;;;;;;;;AAiBoB,UAjBH,KAiBG,CAAA,WAAA,MAAA,GAAA,MAAA,EAAA,gBAAA,SAfO,UAeP,EAAA,GAAA,SAf+B,UAe/B,EAAA,EAAA,QAAA,OAAA,EAAA,MAAA,OAAA,CAAA,CAAA;EAAM;EAEP,SAAA,EAAA,EAZJ,EAYI;EAAY;EAEC,SAAA,WAAA,EAAA,SAAA,MAAA,EAAA;EAAM;EAGrB,SAAA,MAAW,CAAA,EAbR,OAaQ;EAIf;iBAfI,MAAM;;eAER,QAAQ;;oBAEH,MAAM;;mBAEP,YAAY;;gCAEC;;UAGf,WAAA;mBACE;;cAGN,kBAAkB"}
|
|
@@ -1,24 +0,0 @@
|
|
|
1
|
-
import { t as TypesImportSpec } from "./types-import-spec-C4sc7wbb.mjs";
|
|
2
|
-
import { Contract, ContractModel } from "@prisma-next/contract/types";
|
|
3
|
-
|
|
4
|
-
//#region src/emission-types.d.ts
|
|
5
|
-
interface GenerateContractTypesOptions {
|
|
6
|
-
readonly queryOperationTypeImports?: ReadonlyArray<TypesImportSpec>;
|
|
7
|
-
}
|
|
8
|
-
interface ValidationContext {
|
|
9
|
-
readonly codecTypeImports?: ReadonlyArray<TypesImportSpec>;
|
|
10
|
-
readonly operationTypeImports?: ReadonlyArray<TypesImportSpec>;
|
|
11
|
-
readonly extensionIds?: ReadonlyArray<string>;
|
|
12
|
-
}
|
|
13
|
-
interface EmissionSpi {
|
|
14
|
-
readonly id: string;
|
|
15
|
-
generateStorageType(contract: Contract, storageHashTypeName: string): string;
|
|
16
|
-
generateModelStorageType(modelName: string, model: ContractModel): string;
|
|
17
|
-
getFamilyImports(): string[];
|
|
18
|
-
getFamilyTypeAliases(options?: GenerateContractTypesOptions): string;
|
|
19
|
-
getTypeMapsExpression(): string;
|
|
20
|
-
getContractWrapper(contractBaseName: string, typeMapsName: string): string;
|
|
21
|
-
}
|
|
22
|
-
//#endregion
|
|
23
|
-
export { GenerateContractTypesOptions as n, ValidationContext as r, EmissionSpi as t };
|
|
24
|
-
//# sourceMappingURL=emission-types-BPAALJbF.d.mts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"emission-types-BPAALJbF.d.mts","names":[],"sources":["../src/emission-types.ts"],"sourcesContent":[],"mappings":";;;;UAGiB,4BAAA;uCACsB,cAAc;AADrD;AAIiB,UAAA,iBAAA,CAAiB;EACU,SAAA,gBAAA,CAAA,EAAd,aAAc,CAAA,eAAA,CAAA;EAAd,SAAA,oBAAA,CAAA,EACI,aADJ,CACkB,eADlB,CAAA;EACkB,SAAA,YAAA,CAAA,EACtB,aADsB,CAAA,MAAA,CAAA;;AACtB,UAGT,WAAA,CAHS;EAAa,SAAA,EAAA,EAAA,MAAA;EAGtB,mBAAW,CAAA,QAAA,EAGI,QAHJ,EAAA,mBAAA,EAAA,MAAA,CAAA,EAAA,MAAA;EAGI,wBAAA,CAAA,SAAA,EAAA,MAAA,EAAA,KAAA,EAEqB,aAFrB,CAAA,EAAA,MAAA;EAEqB,gBAAA,EAAA,EAAA,MAAA,EAAA;EAIpB,oBAAA,CAAA,OAAA,CAAA,EAAA,4BAAA,CAAA,EAAA,MAAA;EAA4B,qBAAA,EAAA,EAAA,MAAA"}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"framework-authoring-D1-JZ37B.d.mts","names":[],"sources":["../src/framework-authoring.ts"],"sourcesContent":[],"mappings":";KAEY,eAAA;EAAA,SAAA,IAAA,EAAA,KAAe;EAOf,SAAA,KAAA,EAAA,MAAA;EAKR,SAAA,IAAA,CAAA,EAAA,SAAA,MAAA,EAAA;EACS,SAAA,OAAA,CAAA,EATQ,sBASR;CACiB;AAAsB,KAPxC,sBAAA,GAOwC,MAAA,GAAA,MAAA,GAAA,OAAA,GAAA,IAAA,GAFhD,eAEgD,GAAA,SADvC,sBACuC,EAAA,GAAA;EAE1C,UAAA,GAAA,EAAA,MAAA,CAAA,EAFoB,sBAEa;AAK3C,CAAA;UALU,iCAAA,CAKgC;EAYE,SAAA,IAAA,CAAA,EAAA,MAAA;EAAf,SAAA,QAAA,CAAA,EAAA,OAAA;;AAIZ,KAhBL,2BAAA,GAA8B,iCAgBG,GAAA,CAAA;EAEtB,SAAA,IAAA,EAAA,QAAA;CACgB,GAAA;EAAf,SAAA,IAAA,EAAA,QAAA;EAAM,SAAA,OAAA,CAAA,EAAA,OAAA;EAGb,SAAA,OAAA,CAAA,EAAA,MAAA;EAMA,SAAA,OAAA,CAAA,EAAA,MAAA;AAKjB,CAAA,GAAiB;EAKL,SAAA,IAAA,EAAA,aAAA;AAIZ,CAAA,GAAiB;EAEI,SAAA,IAAA,EAAA,QAAA;EACS,SAAA,UAAA,EAjCD,MAiCC,CAAA,MAAA,EAjCc,2BAiCd,CAAA;CAHsB,CAAA;AAA4B,UA1B/D,4BAAA,CA0B+D;EAQ/D,SAAA,OAAA,EAAA,MAAA;EAML,SAAA,UAAA,EAtCW,sBAuCI;EAGf,SAAA,UAAA,CAAA,EAzCY,MAyCW,CAAA,MAAA,EAzCI,sBA0CZ,CAAA;AAG3B;AAKgB,UA/CC,kCAAA,CA+C2C;EAkB5C,SAAA,IAAA,EAAA,iBAAA;EAYA,SAAA,IAAA,CAAA,EAAA,SA3EW,2BA6Ef,EAAA;EAUI,SAAA,MAAA,EAtFG,4BAuFP;AA2GZ;AAuFgB,UAtRC,qCAAA,CAuRH;EAUE,SAAA,IAAA,EAAA,SAAA;kBA/RE;;UAGD,sCAAA;;uBAEM;;KAGX,8BAAA,GACR,wCACA;UAEa,0BAAA,SAAmC;;qBAE/B;8BACS;;;;UAKb,8BAAA;;2BAEU;mBACR;;KAGP,sBAAA;2BACe,qCAAqC;;KAGpD,uBAAA;2BACe,iCAAiC;;UAG3C,sBAAA;kBACC;mBACC;;iBAGH,iBAAA,2BAA4C;iBAkB5C,oCAAA,2BAEJ;iBAUI,gCAAA,2BAEJ;iBAUI,6BAAA,WACJ;iBA2GI,gCAAA,2CAEQ;iBAqFR,mCAAA,aACF;;;wBAKU;;iBAKR,+BAAA,aACF;;;;0BAMY"}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"framework-components-C8ZhSwXe.mjs","names":[],"sources":["../src/framework-components.ts"],"sourcesContent":["import type { Codec } from './codec-types';\nimport type { AuthoringContributions } from './framework-authoring';\nimport type { ControlMutationDefaults } from './mutation-default-types';\nimport type { TypesImportSpec } from './types-import-spec';\n\n/**\n * Declarative fields that describe component metadata.\n */\nexport interface ComponentMetadata {\n /** Component version (semver) */\n readonly version: string;\n\n /**\n * Capabilities this component provides.\n *\n * For adapters, capabilities must be declared on the adapter descriptor (so they are emitted into\n * the contract) and also exposed in runtime adapter code (e.g. `adapter.profile.capabilities`);\n * keep these declarations in sync. Targets are identifiers/descriptors and typically do not\n * declare capabilities.\n */\n readonly capabilities?: Record<string, unknown>;\n\n /** Type imports for contract.d.ts generation */\n readonly types?: {\n readonly codecTypes?: {\n /**\n * Base codec types import spec.\n * Optional: adapters typically provide this, extensions usually don't.\n */\n readonly import?: TypesImportSpec;\n /**\n * Additional type-only imports for parameterized codec branded types.\n *\n * These imports are included in generated `contract.d.ts` but are NOT treated as\n * codec type maps (i.e., they should not be intersected into `export type CodecTypes = ...`).\n *\n * Example: `Vector<N>` for pgvector codecs that emit `Vector<1536>`\n */\n readonly typeImports?: ReadonlyArray<TypesImportSpec>;\n /**\n * Optional control-plane hooks keyed by codecId.\n * Used by family-specific planners/verifiers to handle storage types.\n */\n readonly controlPlaneHooks?: Record<string, unknown>;\n /**\n * Codec instances contributed by this component.\n * Used to build a CodecLookup for codec-dispatched type rendering during emission.\n */\n readonly codecInstances?: ReadonlyArray<Codec>;\n };\n readonly operationTypes?: { readonly import: TypesImportSpec };\n readonly queryOperationTypes?: { readonly import: TypesImportSpec };\n readonly storage?: ReadonlyArray<{\n readonly typeId: string;\n readonly familyId: string;\n readonly targetId: string;\n readonly nativeType?: string;\n }>;\n };\n\n /**\n * Optional pure-data authoring contributions exposed by this component.\n *\n * These contributions are safe to include on pack refs and descriptors because\n * they contain only declarative metadata. Higher-level authoring packages may\n * project them into concrete helper functions for TS-first workflows.\n */\n readonly authoring?: AuthoringContributions;\n\n /**\n * Scalar type name to codec ID mapping contributed by this component.\n * Assembled by `createControlStack` with duplicate detection.\n */\n readonly scalarTypeDescriptors?: ReadonlyMap<string, string>;\n\n /**\n * Mutation default function handlers and generator descriptors contributed\n * by this component. Assembled by `createControlStack` with duplicate detection.\n */\n readonly controlMutationDefaults?: ControlMutationDefaults;\n}\n\n/**\n * Base descriptor for any framework component.\n *\n * All component descriptors share these fundamental properties that identify\n * the component and provide its metadata. This interface is extended by\n * specific descriptor types (FamilyDescriptor, TargetDescriptor, etc.).\n *\n * @template Kind - Discriminator literal identifying the component type.\n * Built-in kinds are 'family', 'target', 'adapter', 'driver', 'extension',\n * but the type accepts any string to allow ecosystem extensions.\n *\n * @example\n * ```ts\n * // All descriptors have these properties\n * descriptor.kind // The Kind type parameter (e.g., 'family', 'target', or custom kinds)\n * descriptor.id // Unique string identifier (e.g., 'sql', 'postgres')\n * descriptor.version // Component version (semver)\n * ```\n */\nexport interface ComponentDescriptor<Kind extends string> extends ComponentMetadata {\n /** Discriminator identifying the component type */\n readonly kind: Kind;\n\n /** Unique identifier for this component (e.g., 'sql', 'postgres', 'pgvector') */\n readonly id: string;\n}\n\nexport interface ContractComponentRequirementsCheckInput {\n readonly contract: {\n readonly target: string;\n readonly targetFamily?: string | undefined;\n readonly extensionPacks?: Record<string, unknown> | undefined;\n };\n readonly expectedTargetFamily?: string | undefined;\n readonly expectedTargetId?: string | undefined;\n readonly providedComponentIds: Iterable<string>;\n}\n\nexport interface ContractComponentRequirementsCheckResult {\n readonly familyMismatch?: { readonly expected: string; readonly actual: string } | undefined;\n readonly targetMismatch?: { readonly expected: string; readonly actual: string } | undefined;\n readonly missingExtensionPackIds: readonly string[];\n}\n\nexport function checkContractComponentRequirements(\n input: ContractComponentRequirementsCheckInput,\n): ContractComponentRequirementsCheckResult {\n const providedIds = new Set<string>();\n for (const id of input.providedComponentIds) {\n providedIds.add(id);\n }\n\n const requiredExtensionPackIds = input.contract.extensionPacks\n ? Object.keys(input.contract.extensionPacks)\n : [];\n const missingExtensionPackIds = requiredExtensionPackIds.filter((id) => !providedIds.has(id));\n\n const expectedTargetFamily = input.expectedTargetFamily;\n const contractTargetFamily = input.contract.targetFamily;\n const familyMismatch =\n expectedTargetFamily !== undefined &&\n contractTargetFamily !== undefined &&\n contractTargetFamily !== expectedTargetFamily\n ? { expected: expectedTargetFamily, actual: contractTargetFamily }\n : undefined;\n\n const expectedTargetId = input.expectedTargetId;\n const contractTargetId = input.contract.target;\n const targetMismatch =\n expectedTargetId !== undefined && contractTargetId !== expectedTargetId\n ? { expected: expectedTargetId, actual: contractTargetId }\n : undefined;\n\n return {\n ...(familyMismatch ? { familyMismatch } : {}),\n ...(targetMismatch ? { targetMismatch } : {}),\n missingExtensionPackIds,\n };\n}\n\n/**\n * Descriptor for a family component.\n *\n * A \"family\" represents a category of data sources with shared semantics\n * (e.g., SQL databases, document stores). Families define:\n * - Query semantics and operations (SELECT, INSERT, find, aggregate, etc.)\n * - Contract structure (tables vs collections, columns vs fields)\n * - Type system and codecs\n *\n * Families are the top-level grouping. Each family contains multiple targets\n * (e.g., SQL family contains Postgres, MySQL, SQLite targets).\n *\n * Extended by plane-specific descriptors:\n * - `ControlFamilyDescriptor` - adds `emission` for CLI/tooling operations\n * - `RuntimeFamilyDescriptor` - adds runtime-specific factory methods\n *\n * @template TFamilyId - Literal type for the family identifier (e.g., 'sql', 'document')\n *\n * @example\n * ```ts\n * import sql from '@prisma-next/family-sql/control';\n *\n * sql.kind // 'family'\n * sql.familyId // 'sql'\n * sql.id // 'sql'\n * ```\n */\nexport interface FamilyDescriptor<TFamilyId extends string> extends ComponentDescriptor<'family'> {\n /** The family identifier (e.g., 'sql', 'document') */\n readonly familyId: TFamilyId;\n}\n\n/**\n * Descriptor for a target component.\n *\n * A \"target\" represents a specific database or data store within a family\n * (e.g., Postgres, MySQL, MongoDB). Targets define:\n * - Native type mappings (e.g., Postgres int4 → TypeScript number)\n * - Target-specific capabilities (e.g., RETURNING, LATERAL joins)\n *\n * Targets are bound to a family and provide the target-specific implementation\n * details that adapters and drivers use.\n *\n * Extended by plane-specific descriptors:\n * - `ControlTargetDescriptor` - adds optional `migrations` capability\n * - `RuntimeTargetDescriptor` - adds runtime factory method\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier (e.g., 'postgres', 'mysql')\n *\n * @example\n * ```ts\n * import postgres from '@prisma-next/target-postgres/control';\n *\n * postgres.kind // 'target'\n * postgres.familyId // 'sql'\n * postgres.targetId // 'postgres'\n * ```\n */\nexport interface TargetDescriptor<TFamilyId extends string, TTargetId extends string>\n extends ComponentDescriptor<'target'> {\n /** The family this target belongs to */\n readonly familyId: TFamilyId;\n\n /** The target identifier (e.g., 'postgres', 'mysql', 'mongodb') */\n readonly targetId: TTargetId;\n}\n\n/**\n * Base shape for any pack reference.\n * Pack refs are pure JSON-friendly objects safe to import in authoring flows.\n */\nexport interface PackRefBase<Kind extends string, TFamilyId extends string>\n extends ComponentMetadata {\n readonly kind: Kind;\n readonly id: string;\n readonly familyId: TFamilyId;\n readonly targetId?: string;\n readonly authoring?: AuthoringContributions;\n}\n\nexport type FamilyPackRef<TFamilyId extends string = string> = PackRefBase<'family', TFamilyId>;\n\nexport type TargetPackRef<\n TFamilyId extends string = string,\n TTargetId extends string = string,\n> = PackRefBase<'target', TFamilyId> & {\n readonly targetId: TTargetId;\n};\n\nexport type AdapterPackRef<\n TFamilyId extends string = string,\n TTargetId extends string = string,\n> = PackRefBase<'adapter', TFamilyId> & {\n readonly targetId: TTargetId;\n};\n\nexport type ExtensionPackRef<\n TFamilyId extends string = string,\n TTargetId extends string = string,\n> = PackRefBase<'extension', TFamilyId> & {\n readonly targetId: TTargetId;\n};\n\nexport type DriverPackRef<\n TFamilyId extends string = string,\n TTargetId extends string = string,\n> = PackRefBase<'driver', TFamilyId> & {\n readonly targetId: TTargetId;\n};\n\n/**\n * Descriptor for an adapter component.\n *\n * An \"adapter\" provides the protocol and dialect implementation for a target.\n * Adapters handle:\n * - SQL/query generation (lowering AST to target-specific syntax)\n * - Codec registration (encoding/decoding between JS and wire types)\n * - Type mappings and coercions\n *\n * Adapters are bound to a specific family+target combination and work with\n * any compatible driver for that target.\n *\n * Extended by plane-specific descriptors:\n * - `ControlAdapterDescriptor` - control-plane factory\n * - `RuntimeAdapterDescriptor` - runtime factory\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier\n *\n * @example\n * ```ts\n * import postgresAdapter from '@prisma-next/adapter-postgres/control';\n *\n * postgresAdapter.kind // 'adapter'\n * postgresAdapter.familyId // 'sql'\n * postgresAdapter.targetId // 'postgres'\n * ```\n */\nexport interface AdapterDescriptor<TFamilyId extends string, TTargetId extends string>\n extends ComponentDescriptor<'adapter'> {\n /** The family this adapter belongs to */\n readonly familyId: TFamilyId;\n\n /** The target this adapter is designed for */\n readonly targetId: TTargetId;\n}\n\n/**\n * Descriptor for a driver component.\n *\n * A \"driver\" provides the connection and execution layer for a target.\n * Drivers handle:\n * - Connection management (pooling, timeouts, retries)\n * - Query execution (sending SQL/commands, receiving results)\n * - Transaction management\n * - Wire protocol communication\n *\n * Drivers are bound to a specific family+target and work with any compatible\n * adapter. Multiple drivers can exist for the same target (e.g., node-postgres\n * vs postgres.js for Postgres).\n *\n * Extended by plane-specific descriptors:\n * - `ControlDriverDescriptor` - creates driver from connection URL\n * - `RuntimeDriverDescriptor` - creates driver with runtime options\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier\n *\n * @example\n * ```ts\n * import postgresDriver from '@prisma-next/driver-postgres/control';\n *\n * postgresDriver.kind // 'driver'\n * postgresDriver.familyId // 'sql'\n * postgresDriver.targetId // 'postgres'\n * ```\n */\nexport interface DriverDescriptor<TFamilyId extends string, TTargetId extends string>\n extends ComponentDescriptor<'driver'> {\n /** The family this driver belongs to */\n readonly familyId: TFamilyId;\n\n /** The target this driver connects to */\n readonly targetId: TTargetId;\n}\n\n/**\n * Descriptor for an extension component.\n *\n * An \"extension\" adds optional capabilities to a target. Extensions can provide:\n * - Additional operations (e.g., vector similarity search with pgvector)\n * - Custom types and codecs (e.g., vector type)\n * - Extended query capabilities\n *\n * Extensions are bound to a specific family+target and are registered in the\n * config alongside the core components. Multiple extensions can be used together.\n *\n * Extended by plane-specific descriptors:\n * - `ControlExtensionDescriptor` - control-plane extension factory\n * - `RuntimeExtensionDescriptor` - runtime extension factory\n *\n * @template TFamilyId - Literal type for the family identifier\n * @template TTargetId - Literal type for the target identifier\n *\n * @example\n * ```ts\n * import pgvector from '@prisma-next/extension-pgvector/control';\n *\n * pgvector.kind // 'extension'\n * pgvector.familyId // 'sql'\n * pgvector.targetId // 'postgres'\n * ```\n */\nexport interface ExtensionDescriptor<TFamilyId extends string, TTargetId extends string>\n extends ComponentDescriptor<'extension'> {\n /** The family this extension belongs to */\n readonly familyId: TFamilyId;\n\n /** The target this extension is designed for */\n readonly targetId: TTargetId;\n}\n\n/** Components bound to a specific family+target combination. */\nexport type TargetBoundComponentDescriptor<TFamilyId extends string, TTargetId extends string> =\n | TargetDescriptor<TFamilyId, TTargetId>\n | AdapterDescriptor<TFamilyId, TTargetId>\n | DriverDescriptor<TFamilyId, TTargetId>\n | ExtensionDescriptor<TFamilyId, TTargetId>;\n\nexport interface FamilyInstance<TFamilyId extends string> {\n readonly familyId: TFamilyId;\n}\n\nexport interface TargetInstance<TFamilyId extends string, TTargetId extends string> {\n readonly familyId: TFamilyId;\n readonly targetId: TTargetId;\n}\n\nexport interface AdapterInstance<TFamilyId extends string, TTargetId extends string> {\n readonly familyId: TFamilyId;\n readonly targetId: TTargetId;\n}\n\nexport interface DriverInstance<TFamilyId extends string, TTargetId extends string> {\n readonly familyId: TFamilyId;\n readonly targetId: TTargetId;\n}\n\nexport interface ExtensionInstance<TFamilyId extends string, TTargetId extends string> {\n readonly familyId: TFamilyId;\n readonly targetId: TTargetId;\n}\n"],"mappings":";AA8HA,SAAgB,mCACd,OAC0C;CAC1C,MAAM,8BAAc,IAAI,KAAa;AACrC,MAAK,MAAM,MAAM,MAAM,qBACrB,aAAY,IAAI,GAAG;CAMrB,MAAM,2BAH2B,MAAM,SAAS,iBAC5C,OAAO,KAAK,MAAM,SAAS,eAAe,GAC1C,EAAE,EACmD,QAAQ,OAAO,CAAC,YAAY,IAAI,GAAG,CAAC;CAE7F,MAAM,uBAAuB,MAAM;CACnC,MAAM,uBAAuB,MAAM,SAAS;CAC5C,MAAM,iBACJ,yBAAyB,UACzB,yBAAyB,UACzB,yBAAyB,uBACrB;EAAE,UAAU;EAAsB,QAAQ;EAAsB,GAChE;CAEN,MAAM,mBAAmB,MAAM;CAC/B,MAAM,mBAAmB,MAAM,SAAS;CACxC,MAAM,iBACJ,qBAAqB,UAAa,qBAAqB,mBACnD;EAAE,UAAU;EAAkB,QAAQ;EAAkB,GACxD;AAEN,QAAO;EACL,GAAI,iBAAiB,EAAE,gBAAgB,GAAG,EAAE;EAC5C,GAAI,iBAAiB,EAAE,gBAAgB,GAAG,EAAE;EAC5C;EACD"}
|