@prisma-next/contract 0.1.0-pr.56.1 → 0.1.0-pr.56.3

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 CHANGED
@@ -12,7 +12,7 @@ This package provides the foundational type definitions for Prisma Next, includi
12
12
  ## Responsibilities
13
13
 
14
14
  - **Core Contract Types**: Defines framework-level contract types (`ContractBase`, `Source`, `FamilyInstance`) that are shared across all target families
15
- - **Framework Component Descriptors**: Provides base descriptor interfaces (`FamilyDescriptor`, `TargetDescriptor`, `AdapterDescriptor`, `DriverDescriptor`, `ExtensionDescriptor`) that plane-specific descriptors extend
15
+ - **Framework Component Model**: Provides base descriptor interfaces (`FamilyDescriptor`, `TargetDescriptor`, `AdapterDescriptor`, `DriverDescriptor`, `ExtensionDescriptor`) and identity instance bases (`FamilyInstance`, `TargetInstance`, `AdapterInstance`, `DriverInstance`, `ExtensionInstance`) that plane-specific types extend
16
16
  - **Document Family Types**: Provides TypeScript types for document target family contracts (`DocumentContract`)
17
17
  - **JSON Schema Validation**: Provides JSON Schemas for validating contract structure in IDEs and tooling
18
18
  - **Type Guards**: Provides runtime type guards for narrowing contract types (`isDocumentContract`)
@@ -73,18 +73,25 @@ const myFamilyHook: TargetFamilyHook = {
73
73
  };
74
74
  ```
75
75
 
76
- ### Framework Component Descriptors
76
+ ### Framework Component Model
77
77
 
78
- Import base descriptor interfaces to define or type-check framework components:
78
+ Import base descriptor and instance interfaces to define or type-check framework components:
79
79
 
80
80
  ```typescript
81
81
  import type {
82
+ // Descriptors
82
83
  ComponentDescriptor,
83
84
  FamilyDescriptor,
84
85
  TargetDescriptor,
85
86
  AdapterDescriptor,
86
87
  DriverDescriptor,
87
88
  ExtensionDescriptor,
89
+ // Instances
90
+ FamilyInstance,
91
+ TargetInstance,
92
+ AdapterInstance,
93
+ DriverInstance,
94
+ ExtensionInstance,
88
95
  } from '@prisma-next/contract/framework-components';
89
96
 
90
97
  // Component descriptors share common properties
@@ -108,6 +115,11 @@ const postgresTarget: TargetDescriptor<'sql', 'postgres'> = {
108
115
  targetId: 'postgres',
109
116
  manifest: { /* ... */ },
110
117
  };
118
+
119
+ // Identity instance bases are extended by plane-specific instances
120
+ interface MySqlInstance extends FamilyInstance<'sql'> {
121
+ // Plane-specific methods...
122
+ }
111
123
  ```
112
124
 
113
125
  The component hierarchy is:
@@ -229,7 +241,7 @@ if (isDocumentContract(contract)) {
229
241
  ## Exports
230
242
 
231
243
  - `./types`: Core contract type definitions, type guards, and emitter SPI types
232
- - `./framework-components`: Framework component descriptor base interfaces
244
+ - `./framework-components`: Framework component model (descriptors + identity instance bases)
233
245
  - `./pack-manifest-types`: Extension pack manifest types
234
246
  - `./ir`: Contract IR types
235
247
  - `./schema-document`: Document family JSON Schema (`schemas/data-contract-document-v1.json`)
@@ -1,4 +1,4 @@
1
- import { E as ExtensionPackManifest } from './pack-manifest-types-BS9Z7pMY.js';
1
+ import { E as ExtensionPackManifest } from './pack-manifest-types-BYh8H2fb.js';
2
2
  import '@prisma-next/operations';
3
3
  import './ir.js';
4
4
 
@@ -197,5 +197,116 @@ interface ExtensionDescriptor<TFamilyId extends string, TTargetId extends string
197
197
  /** The target this extension is designed for */
198
198
  readonly targetId: TTargetId;
199
199
  }
200
+ /**
201
+ * Base interface for family instances.
202
+ *
203
+ * A family instance is created by a family descriptor's `create()` method.
204
+ * This base interface carries only the identity; plane-specific interfaces
205
+ * add domain actions (e.g., `emitContract`, `verify` on ControlFamilyInstance).
206
+ *
207
+ * @template TFamilyId - Literal type for the family identifier (e.g., 'sql', 'document')
208
+ *
209
+ * @example
210
+ * ```ts
211
+ * const instance = sql.create({ target, adapter, driver, extensions });
212
+ * instance.familyId // 'sql'
213
+ * ```
214
+ */
215
+ interface FamilyInstance<TFamilyId extends string> {
216
+ /** The family identifier (e.g., 'sql', 'document') */
217
+ readonly familyId: TFamilyId;
218
+ }
219
+ /**
220
+ * Base interface for target instances.
221
+ *
222
+ * A target instance is created by a target descriptor's `create()` method.
223
+ * This base interface carries only the identity; plane-specific interfaces
224
+ * add target-specific behavior.
225
+ *
226
+ * @template TFamilyId - Literal type for the family identifier
227
+ * @template TTargetId - Literal type for the target identifier (e.g., 'postgres', 'mysql')
228
+ *
229
+ * @example
230
+ * ```ts
231
+ * const instance = postgres.create();
232
+ * instance.familyId // 'sql'
233
+ * instance.targetId // 'postgres'
234
+ * ```
235
+ */
236
+ interface TargetInstance<TFamilyId extends string, TTargetId extends string> {
237
+ /** The family this target belongs to */
238
+ readonly familyId: TFamilyId;
239
+ /** The target identifier (e.g., 'postgres', 'mysql', 'mongodb') */
240
+ readonly targetId: TTargetId;
241
+ }
242
+ /**
243
+ * Base interface for adapter instances.
244
+ *
245
+ * An adapter instance is created by an adapter descriptor's `create()` method.
246
+ * This base interface carries only the identity; plane-specific interfaces
247
+ * add adapter-specific behavior (e.g., codec registration, query lowering).
248
+ *
249
+ * @template TFamilyId - Literal type for the family identifier
250
+ * @template TTargetId - Literal type for the target identifier
251
+ *
252
+ * @example
253
+ * ```ts
254
+ * const instance = postgresAdapter.create();
255
+ * instance.familyId // 'sql'
256
+ * instance.targetId // 'postgres'
257
+ * ```
258
+ */
259
+ interface AdapterInstance<TFamilyId extends string, TTargetId extends string> {
260
+ /** The family this adapter belongs to */
261
+ readonly familyId: TFamilyId;
262
+ /** The target this adapter is designed for */
263
+ readonly targetId: TTargetId;
264
+ }
265
+ /**
266
+ * Base interface for driver instances.
267
+ *
268
+ * A driver instance is created by a driver descriptor's `create()` method.
269
+ * This base interface carries only the identity; plane-specific interfaces
270
+ * add driver-specific behavior (e.g., `query`, `close` on ControlDriverInstance).
271
+ *
272
+ * @template TFamilyId - Literal type for the family identifier
273
+ * @template TTargetId - Literal type for the target identifier
274
+ *
275
+ * @example
276
+ * ```ts
277
+ * const instance = postgresDriver.create({ databaseUrl });
278
+ * instance.familyId // 'sql'
279
+ * instance.targetId // 'postgres'
280
+ * ```
281
+ */
282
+ interface DriverInstance<TFamilyId extends string, TTargetId extends string> {
283
+ /** The family this driver belongs to */
284
+ readonly familyId: TFamilyId;
285
+ /** The target this driver connects to */
286
+ readonly targetId: TTargetId;
287
+ }
288
+ /**
289
+ * Base interface for extension instances.
290
+ *
291
+ * An extension instance is created by an extension descriptor's `create()` method.
292
+ * This base interface carries only the identity; plane-specific interfaces
293
+ * add extension-specific behavior.
294
+ *
295
+ * @template TFamilyId - Literal type for the family identifier
296
+ * @template TTargetId - Literal type for the target identifier
297
+ *
298
+ * @example
299
+ * ```ts
300
+ * const instance = pgvector.create();
301
+ * instance.familyId // 'sql'
302
+ * instance.targetId // 'postgres'
303
+ * ```
304
+ */
305
+ interface ExtensionInstance<TFamilyId extends string, TTargetId extends string> {
306
+ /** The family this extension belongs to */
307
+ readonly familyId: TFamilyId;
308
+ /** The target this extension is designed for */
309
+ readonly targetId: TTargetId;
310
+ }
200
311
 
201
- export type { AdapterDescriptor, ComponentDescriptor, DriverDescriptor, ExtensionDescriptor, FamilyDescriptor, TargetDescriptor };
312
+ export type { AdapterDescriptor, AdapterInstance, ComponentDescriptor, DriverDescriptor, DriverInstance, ExtensionDescriptor, ExtensionInstance, FamilyDescriptor, FamilyInstance, TargetDescriptor, TargetInstance };
@@ -1,15 +1,6 @@
1
1
  import { OperationRegistry } from '@prisma-next/operations';
2
2
  import { ContractIR } from './ir.js';
3
3
 
4
- /**
5
- * Base interface for family instances.
6
- * Extended by plane-specific interfaces (ControlFamilyInstance, RuntimeFamilyInstance).
7
- *
8
- * @template TFamilyId - The family ID (e.g., 'sql', 'document')
9
- */
10
- interface FamilyInstance<TFamilyId extends string = string> {
11
- readonly familyId: TFamilyId;
12
- }
13
4
  interface ContractBase {
14
5
  readonly schemaVersion: string;
15
6
  readonly target: string;
@@ -257,4 +248,4 @@ interface ExtensionPack {
257
248
  readonly path: string;
258
249
  }
259
250
 
260
- export { type ArgSpecManifest as A, type ContractBase as C, type DocCollection as D, type ExtensionPackManifest as E, type FamilyInstance as F, type LoweringSpecManifest as L, type OperationManifest as O, type ParamDescriptor as P, type ResultType as R, type Source as S, type TargetFamilyHook as T, type ValidationContext as V, type ContractMarkerRecord as a, type DocIndex as b, type DocumentContract as c, type DocumentStorage as d, type ExecutionPlan as e, type Expr as f, type FieldType as g, type PlanMeta as h, type PlanRefs as i, type TypesImportSpec as j, isDocumentContract as k, type ExtensionPack as l, type ReturnSpecManifest as m };
251
+ export { type ArgSpecManifest as A, type ContractBase as C, type DocCollection as D, type ExtensionPackManifest as E, type FieldType as F, type LoweringSpecManifest as L, type OperationManifest as O, type ParamDescriptor as P, type ResultType as R, type Source as S, type TargetFamilyHook as T, type ValidationContext as V, type ContractMarkerRecord as a, type DocIndex as b, type DocumentContract as c, type DocumentStorage as d, type ExecutionPlan as e, type Expr as f, type PlanMeta as g, type PlanRefs as h, type TypesImportSpec as i, isDocumentContract as j, type ExtensionPack as k, type ReturnSpecManifest as l };
@@ -1,3 +1,3 @@
1
- export { A as ArgSpecManifest, l as ExtensionPack, E as ExtensionPackManifest, L as LoweringSpecManifest, O as OperationManifest, m as ReturnSpecManifest } from './pack-manifest-types-BS9Z7pMY.js';
1
+ export { A as ArgSpecManifest, k as ExtensionPack, E as ExtensionPackManifest, L as LoweringSpecManifest, O as OperationManifest, l as ReturnSpecManifest } from './pack-manifest-types-BYh8H2fb.js';
2
2
  import '@prisma-next/operations';
3
3
  import './ir.js';
@@ -1,3 +1,3 @@
1
- export { C as ContractBase, a as ContractMarkerRecord, D as DocCollection, b as DocIndex, c as DocumentContract, d as DocumentStorage, e as ExecutionPlan, f as Expr, F as FamilyInstance, g as FieldType, P as ParamDescriptor, h as PlanMeta, i as PlanRefs, R as ResultType, S as Source, T as TargetFamilyHook, j as TypesImportSpec, V as ValidationContext, k as isDocumentContract } from './pack-manifest-types-BS9Z7pMY.js';
1
+ export { C as ContractBase, a as ContractMarkerRecord, D as DocCollection, b as DocIndex, c as DocumentContract, d as DocumentStorage, e as ExecutionPlan, f as Expr, F as FieldType, P as ParamDescriptor, g as PlanMeta, h as PlanRefs, R as ResultType, S as Source, T as TargetFamilyHook, i as TypesImportSpec, V as ValidationContext, j as isDocumentContract } from './pack-manifest-types-BYh8H2fb.js';
2
2
  import '@prisma-next/operations';
3
3
  import './ir.js';
@@ -1 +1 @@
1
- {"version":3,"sources":["../../src/types.ts"],"sourcesContent":["import type { OperationRegistry } from '@prisma-next/operations';\nimport type { ContractIR } from './ir';\n\n// ============================================================================\n// Family Instance Base Interface\n// ============================================================================\n\n/**\n * Base interface for family instances.\n * Extended by plane-specific interfaces (ControlFamilyInstance, RuntimeFamilyInstance).\n *\n * @template TFamilyId - The family ID (e.g., 'sql', 'document')\n */\nexport interface FamilyInstance<TFamilyId extends string = string> {\n readonly familyId: TFamilyId;\n}\n\n// ============================================================================\n// Shared header and neutral types\n// ============================================================================\n// Note: Fields like targetFamily accept string to work with JSON imports,\n// which don't preserve literal types. Runtime validation ensures correct values\nexport interface ContractBase {\n readonly schemaVersion: string;\n readonly target: string;\n readonly targetFamily: string;\n readonly coreHash: string;\n readonly profileHash?: string;\n readonly capabilities?: Record<string, Record<string, boolean>>;\n readonly extensions?: Record<string, unknown>;\n readonly meta?: Record<string, unknown>;\n readonly sources?: Record<string, Source>;\n}\n\nexport interface FieldType {\n readonly type: string;\n readonly nullable: boolean;\n readonly items?: FieldType;\n readonly properties?: Record<string, FieldType>;\n}\n\nexport interface Source {\n readonly readOnly: boolean;\n readonly projection: Record<string, FieldType>;\n readonly origin?: Record<string, unknown>;\n readonly capabilities?: Record<string, boolean>;\n}\n\n// Document family types\nexport interface DocIndex {\n readonly name: string;\n readonly keys: Record<string, 'asc' | 'desc'>;\n readonly unique?: boolean;\n readonly where?: Expr;\n}\n\nexport type Expr =\n | { readonly kind: 'eq'; readonly path: ReadonlyArray<string>; readonly value: unknown }\n | { readonly kind: 'exists'; readonly path: ReadonlyArray<string> };\n\nexport interface DocCollection {\n readonly name: string;\n readonly id?: {\n readonly strategy: 'auto' | 'client' | 'uuid' | 'cuid' | 'objectId';\n };\n readonly fields: Record<string, FieldType>;\n readonly indexes?: ReadonlyArray<DocIndex>;\n readonly readOnly?: boolean;\n}\n\nexport interface DocumentStorage {\n readonly document: {\n readonly collections: Record<string, DocCollection>;\n };\n}\n\nexport interface DocumentContract extends ContractBase {\n // Accept string to work with JSON imports; runtime validation ensures 'document'\n readonly targetFamily: string;\n readonly storage: DocumentStorage;\n}\n\n// Plan types - target-family agnostic execution types\nexport interface ParamDescriptor {\n readonly index?: number;\n readonly name?: string;\n readonly codecId?: string;\n readonly nativeType?: string;\n readonly nullable?: boolean;\n readonly source: 'dsl' | 'raw';\n readonly refs?: { table: string; column: string };\n}\n\nexport interface PlanRefs {\n readonly tables?: readonly string[];\n readonly columns?: ReadonlyArray<{ table: string; column: string }>;\n readonly indexes?: ReadonlyArray<{\n readonly table: string;\n readonly columns: ReadonlyArray<string>;\n readonly name?: string;\n }>;\n}\n\nexport interface PlanMeta {\n readonly target: string;\n readonly targetFamily?: string;\n readonly coreHash: string;\n readonly profileHash?: string;\n readonly lane: string;\n readonly annotations?: {\n codecs?: Record<string, string>; // alias/param → codec id ('ns/name@v')\n [key: string]: unknown;\n };\n readonly paramDescriptors: ReadonlyArray<ParamDescriptor>;\n readonly refs?: PlanRefs;\n readonly projection?: Record<string, string> | ReadonlyArray<string>;\n /**\n * Optional mapping of projection alias → column type ID (fully qualified ns/name@version).\n * Used for codec resolution when AST+refs don't provide enough type info.\n */\n readonly projectionTypes?: Record<string, string>;\n}\n\n/**\n * Canonical execution plan shape used by runtimes.\n *\n * - Row is the inferred result row type (TypeScript-only).\n * - Ast is the optional, family-specific AST type (e.g. SQL QueryAst).\n *\n * The payload executed by the runtime is represented by the sql + params pair\n * for now; future families can specialize this via Ast or additional metadata.\n */\nexport interface ExecutionPlan<Row = unknown, Ast = unknown> {\n readonly sql: string;\n readonly params: readonly unknown[];\n readonly ast?: Ast;\n readonly meta: PlanMeta;\n /**\n * Phantom property to carry the Row generic for type-level utilities.\n * Not set at runtime; used only for ResultType extraction.\n */\n readonly _row?: Row;\n}\n\n/**\n * Utility type to extract the Row type from an ExecutionPlan.\n * Example: `type Row = ResultType<typeof plan>`\n *\n * Works with both ExecutionPlan and SqlQueryPlan (SQL query plans before lowering).\n * SqlQueryPlan includes a phantom `_Row` property to preserve the generic parameter\n * for type extraction.\n */\nexport type ResultType<P> = P extends ExecutionPlan<infer R, unknown>\n ? R\n : P extends { readonly _Row?: infer R }\n ? R\n : never;\n\n/**\n * Type guard to check if a contract is a Document contract\n */\nexport function isDocumentContract(contract: unknown): contract is DocumentContract {\n return (\n typeof contract === 'object' &&\n contract !== null &&\n 'targetFamily' in contract &&\n contract.targetFamily === 'document'\n );\n}\n\n/**\n * Contract marker record stored in the database.\n * Represents the current contract identity for a database.\n */\nexport interface ContractMarkerRecord {\n readonly coreHash: string;\n readonly profileHash: string;\n readonly contractJson: unknown | null;\n readonly canonicalVersion: number | null;\n readonly updatedAt: Date;\n readonly appTag: string | null;\n readonly meta: Record<string, unknown>;\n}\n\n// Emitter types - moved from @prisma-next/emitter to shared location\n/**\n * Specifies how to import TypeScript types from a package.\n * Used in extension pack manifests to declare codec and operation type imports.\n */\nexport interface TypesImportSpec {\n readonly package: string;\n readonly named: string;\n readonly alias: string;\n}\n\n/**\n * Validation context passed to TargetFamilyHook.validateTypes().\n * Contains pre-assembled operation registry, type imports, and extension IDs.\n */\nexport interface ValidationContext {\n readonly operationRegistry?: OperationRegistry;\n readonly codecTypeImports?: ReadonlyArray<TypesImportSpec>;\n readonly operationTypeImports?: ReadonlyArray<TypesImportSpec>;\n readonly extensionIds?: ReadonlyArray<string>;\n}\n\n/**\n * SPI interface for target family hooks that extend emission behavior.\n * Implemented by family-specific emitter hooks (e.g., SQL family).\n */\nexport interface TargetFamilyHook {\n readonly id: string;\n\n /**\n * Validates that all type IDs in the contract come from referenced extensions.\n * @param ir - Contract IR to validate\n * @param ctx - Validation context with operation registry and extension IDs\n */\n validateTypes(ir: ContractIR, ctx: ValidationContext): void;\n\n /**\n * Validates family-specific contract structure.\n * @param ir - Contract IR to validate\n */\n validateStructure(ir: ContractIR): void;\n\n /**\n * Generates contract.d.ts file content.\n * @param ir - Contract IR\n * @param codecTypeImports - Array of codec type import specs\n * @param operationTypeImports - Array of operation type import specs\n * @returns Generated TypeScript type definitions as string\n */\n generateContractTypes(\n ir: ContractIR,\n codecTypeImports: ReadonlyArray<TypesImportSpec>,\n operationTypeImports: ReadonlyArray<TypesImportSpec>,\n ): string;\n}\n\n// Extension pack manifest types - moved from @prisma-next/core-control-plane to shared location\nexport type ArgSpecManifest =\n | { readonly kind: 'typeId'; readonly type: string }\n | { readonly kind: 'param' }\n | { readonly kind: 'literal' };\n\nexport type ReturnSpecManifest =\n | { readonly kind: 'typeId'; readonly type: string }\n | { readonly kind: 'builtin'; readonly type: 'number' | 'boolean' | 'string' };\n\nexport interface LoweringSpecManifest {\n readonly targetFamily: 'sql';\n readonly strategy: 'infix' | 'function';\n readonly template: string;\n}\n\nexport interface OperationManifest {\n readonly for: string;\n readonly method: string;\n readonly args: ReadonlyArray<ArgSpecManifest>;\n readonly returns: ReturnSpecManifest;\n readonly lowering: LoweringSpecManifest;\n readonly capabilities?: ReadonlyArray<string>;\n}\n\nexport interface ExtensionPackManifest {\n readonly id: string;\n readonly version: string;\n readonly targets?: Record<string, { readonly minVersion?: string }>;\n readonly capabilities?: Record<string, unknown>;\n readonly types?: {\n readonly codecTypes?: {\n readonly import: TypesImportSpec;\n };\n readonly operationTypes?: {\n readonly import: TypesImportSpec;\n };\n readonly storage?: readonly {\n readonly typeId: string;\n readonly familyId: string;\n readonly targetId: string;\n readonly nativeType?: string;\n }[];\n };\n readonly operations?: ReadonlyArray<OperationManifest>;\n}\n\nexport interface ExtensionPack {\n readonly manifest: ExtensionPackManifest;\n readonly path: string;\n}\n"],"mappings":";AAiKO,SAAS,mBAAmB,UAAiD;AAClF,SACE,OAAO,aAAa,YACpB,aAAa,QACb,kBAAkB,YAClB,SAAS,iBAAiB;AAE9B;","names":[]}
1
+ {"version":3,"sources":["../../src/types.ts"],"sourcesContent":["import type { OperationRegistry } from '@prisma-next/operations';\nimport type { ContractIR } from './ir';\n\n// ============================================================================\n// Shared header and neutral types\n// ============================================================================\n// Note: Fields like targetFamily accept string to work with JSON imports,\n// which don't preserve literal types. Runtime validation ensures correct values\nexport interface ContractBase {\n readonly schemaVersion: string;\n readonly target: string;\n readonly targetFamily: string;\n readonly coreHash: string;\n readonly profileHash?: string;\n readonly capabilities?: Record<string, Record<string, boolean>>;\n readonly extensions?: Record<string, unknown>;\n readonly meta?: Record<string, unknown>;\n readonly sources?: Record<string, Source>;\n}\n\nexport interface FieldType {\n readonly type: string;\n readonly nullable: boolean;\n readonly items?: FieldType;\n readonly properties?: Record<string, FieldType>;\n}\n\nexport interface Source {\n readonly readOnly: boolean;\n readonly projection: Record<string, FieldType>;\n readonly origin?: Record<string, unknown>;\n readonly capabilities?: Record<string, boolean>;\n}\n\n// Document family types\nexport interface DocIndex {\n readonly name: string;\n readonly keys: Record<string, 'asc' | 'desc'>;\n readonly unique?: boolean;\n readonly where?: Expr;\n}\n\nexport type Expr =\n | { readonly kind: 'eq'; readonly path: ReadonlyArray<string>; readonly value: unknown }\n | { readonly kind: 'exists'; readonly path: ReadonlyArray<string> };\n\nexport interface DocCollection {\n readonly name: string;\n readonly id?: {\n readonly strategy: 'auto' | 'client' | 'uuid' | 'cuid' | 'objectId';\n };\n readonly fields: Record<string, FieldType>;\n readonly indexes?: ReadonlyArray<DocIndex>;\n readonly readOnly?: boolean;\n}\n\nexport interface DocumentStorage {\n readonly document: {\n readonly collections: Record<string, DocCollection>;\n };\n}\n\nexport interface DocumentContract extends ContractBase {\n // Accept string to work with JSON imports; runtime validation ensures 'document'\n readonly targetFamily: string;\n readonly storage: DocumentStorage;\n}\n\n// Plan types - target-family agnostic execution types\nexport interface ParamDescriptor {\n readonly index?: number;\n readonly name?: string;\n readonly codecId?: string;\n readonly nativeType?: string;\n readonly nullable?: boolean;\n readonly source: 'dsl' | 'raw';\n readonly refs?: { table: string; column: string };\n}\n\nexport interface PlanRefs {\n readonly tables?: readonly string[];\n readonly columns?: ReadonlyArray<{ table: string; column: string }>;\n readonly indexes?: ReadonlyArray<{\n readonly table: string;\n readonly columns: ReadonlyArray<string>;\n readonly name?: string;\n }>;\n}\n\nexport interface PlanMeta {\n readonly target: string;\n readonly targetFamily?: string;\n readonly coreHash: string;\n readonly profileHash?: string;\n readonly lane: string;\n readonly annotations?: {\n codecs?: Record<string, string>; // alias/param → codec id ('ns/name@v')\n [key: string]: unknown;\n };\n readonly paramDescriptors: ReadonlyArray<ParamDescriptor>;\n readonly refs?: PlanRefs;\n readonly projection?: Record<string, string> | ReadonlyArray<string>;\n /**\n * Optional mapping of projection alias → column type ID (fully qualified ns/name@version).\n * Used for codec resolution when AST+refs don't provide enough type info.\n */\n readonly projectionTypes?: Record<string, string>;\n}\n\n/**\n * Canonical execution plan shape used by runtimes.\n *\n * - Row is the inferred result row type (TypeScript-only).\n * - Ast is the optional, family-specific AST type (e.g. SQL QueryAst).\n *\n * The payload executed by the runtime is represented by the sql + params pair\n * for now; future families can specialize this via Ast or additional metadata.\n */\nexport interface ExecutionPlan<Row = unknown, Ast = unknown> {\n readonly sql: string;\n readonly params: readonly unknown[];\n readonly ast?: Ast;\n readonly meta: PlanMeta;\n /**\n * Phantom property to carry the Row generic for type-level utilities.\n * Not set at runtime; used only for ResultType extraction.\n */\n readonly _row?: Row;\n}\n\n/**\n * Utility type to extract the Row type from an ExecutionPlan.\n * Example: `type Row = ResultType<typeof plan>`\n *\n * Works with both ExecutionPlan and SqlQueryPlan (SQL query plans before lowering).\n * SqlQueryPlan includes a phantom `_Row` property to preserve the generic parameter\n * for type extraction.\n */\nexport type ResultType<P> = P extends ExecutionPlan<infer R, unknown>\n ? R\n : P extends { readonly _Row?: infer R }\n ? R\n : never;\n\n/**\n * Type guard to check if a contract is a Document contract\n */\nexport function isDocumentContract(contract: unknown): contract is DocumentContract {\n return (\n typeof contract === 'object' &&\n contract !== null &&\n 'targetFamily' in contract &&\n contract.targetFamily === 'document'\n );\n}\n\n/**\n * Contract marker record stored in the database.\n * Represents the current contract identity for a database.\n */\nexport interface ContractMarkerRecord {\n readonly coreHash: string;\n readonly profileHash: string;\n readonly contractJson: unknown | null;\n readonly canonicalVersion: number | null;\n readonly updatedAt: Date;\n readonly appTag: string | null;\n readonly meta: Record<string, unknown>;\n}\n\n// Emitter types - moved from @prisma-next/emitter to shared location\n/**\n * Specifies how to import TypeScript types from a package.\n * Used in extension pack manifests to declare codec and operation type imports.\n */\nexport interface TypesImportSpec {\n readonly package: string;\n readonly named: string;\n readonly alias: string;\n}\n\n/**\n * Validation context passed to TargetFamilyHook.validateTypes().\n * Contains pre-assembled operation registry, type imports, and extension IDs.\n */\nexport interface ValidationContext {\n readonly operationRegistry?: OperationRegistry;\n readonly codecTypeImports?: ReadonlyArray<TypesImportSpec>;\n readonly operationTypeImports?: ReadonlyArray<TypesImportSpec>;\n readonly extensionIds?: ReadonlyArray<string>;\n}\n\n/**\n * SPI interface for target family hooks that extend emission behavior.\n * Implemented by family-specific emitter hooks (e.g., SQL family).\n */\nexport interface TargetFamilyHook {\n readonly id: string;\n\n /**\n * Validates that all type IDs in the contract come from referenced extensions.\n * @param ir - Contract IR to validate\n * @param ctx - Validation context with operation registry and extension IDs\n */\n validateTypes(ir: ContractIR, ctx: ValidationContext): void;\n\n /**\n * Validates family-specific contract structure.\n * @param ir - Contract IR to validate\n */\n validateStructure(ir: ContractIR): void;\n\n /**\n * Generates contract.d.ts file content.\n * @param ir - Contract IR\n * @param codecTypeImports - Array of codec type import specs\n * @param operationTypeImports - Array of operation type import specs\n * @returns Generated TypeScript type definitions as string\n */\n generateContractTypes(\n ir: ContractIR,\n codecTypeImports: ReadonlyArray<TypesImportSpec>,\n operationTypeImports: ReadonlyArray<TypesImportSpec>,\n ): string;\n}\n\n// Extension pack manifest types - moved from @prisma-next/core-control-plane to shared location\nexport type ArgSpecManifest =\n | { readonly kind: 'typeId'; readonly type: string }\n | { readonly kind: 'param' }\n | { readonly kind: 'literal' };\n\nexport type ReturnSpecManifest =\n | { readonly kind: 'typeId'; readonly type: string }\n | { readonly kind: 'builtin'; readonly type: 'number' | 'boolean' | 'string' };\n\nexport interface LoweringSpecManifest {\n readonly targetFamily: 'sql';\n readonly strategy: 'infix' | 'function';\n readonly template: string;\n}\n\nexport interface OperationManifest {\n readonly for: string;\n readonly method: string;\n readonly args: ReadonlyArray<ArgSpecManifest>;\n readonly returns: ReturnSpecManifest;\n readonly lowering: LoweringSpecManifest;\n readonly capabilities?: ReadonlyArray<string>;\n}\n\nexport interface ExtensionPackManifest {\n readonly id: string;\n readonly version: string;\n readonly targets?: Record<string, { readonly minVersion?: string }>;\n readonly capabilities?: Record<string, unknown>;\n readonly types?: {\n readonly codecTypes?: {\n readonly import: TypesImportSpec;\n };\n readonly operationTypes?: {\n readonly import: TypesImportSpec;\n };\n readonly storage?: readonly {\n readonly typeId: string;\n readonly familyId: string;\n readonly targetId: string;\n readonly nativeType?: string;\n }[];\n };\n readonly operations?: ReadonlyArray<OperationManifest>;\n}\n\nexport interface ExtensionPack {\n readonly manifest: ExtensionPackManifest;\n readonly path: string;\n}\n"],"mappings":";AAmJO,SAAS,mBAAmB,UAAiD;AAClF,SACE,OAAO,aAAa,YACpB,aAAa,QACb,kBAAkB,YAClB,SAAS,iBAAiB;AAE9B;","names":[]}
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@prisma-next/contract",
3
- "version": "0.1.0-pr.56.1",
3
+ "version": "0.1.0-pr.56.3",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "description": "Data contract type definitions and JSON schema for Prisma Next",
7
7
  "dependencies": {
8
- "@prisma-next/operations": "0.1.0-pr.56.1"
8
+ "@prisma-next/operations": "0.1.0-pr.56.3"
9
9
  },
10
10
  "devDependencies": {
11
11
  "@vitest/coverage-v8": "^2.1.1",