@prisma-next/sql-contract-ts 0.3.0-dev.34 → 0.3.0-dev.37

package/src/contract-builder.ts

@@ -1,6 +1,9 @@
 import type { ExtensionPackRef, TargetPackRef } from '@prisma-next/contract/framework-components';
+import type { ExecutionMutationDefault } from '@prisma-next/contract/types';
 import type {
   ColumnBuilderState,
+  ContractBuilderState,
+  ForeignKeyDefaultsState,
   ModelBuilderState,
   RelationDefinition,
   TableBuilderState,
@@ -17,13 +20,16 @@ import {
   type Mutable,
   TableBuilder,
 } from '@prisma-next/contract-authoring';
-import type {
-  ModelDefinition,
-  ModelField,
-  SqlContract,
-  SqlMappings,
-  SqlStorage,
+import {
+  applyFkDefaults,
+  type ModelDefinition,
+  type ModelField,
+  type SqlContract,
+  type SqlMappings,
+  type SqlStorage,
+  type StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { computeMappings } from './contract';
 
 /**
@@ -33,8 +39,8 @@ import { computeMappings } from './contract';
  * produces. `codecTypes` uses the generic `CodecTypes` parameter; `operationTypes` is always
  * empty since operations are added via extensions at runtime.
  *
- * **Difference from RuntimeContext**: This is a compile-time type for contract construction.
- * `RuntimeContext` is a runtime object with populated registries for query execution.
+ * **Difference from ExecutionContext**: This is a compile-time type for contract construction.
+ * `ExecutionContext` is a runtime object with populated registries for query execution.
  *
  * @template C - The `CodecTypes` generic parameter passed to `defineContract<CodecTypes>()`
  */
@@ -66,6 +72,8 @@ type BuildStorageTable<
     readonly columns: readonly string[];
     readonly references: { readonly table: string; readonly columns: readonly string[] };
     readonly name?: string;
+    readonly constraint: boolean;
+    readonly index: boolean;
   }>;
 } & (PK extends readonly string[]
   ? { readonly primaryKey: { readonly columns: PK; readonly name?: string } }
@@ -80,6 +88,7 @@ type BuildStorage<
       readonly string[] | undefined
     >
   >,
+  Types extends Record<string, StorageTypeInstance>,
 > = {
   readonly tables: {
     readonly [K in keyof Tables]: BuildStorageTable<
@@ -88,6 +97,7 @@ type BuildStorage<
       ExtractPrimaryKey<Tables[K]>
     >;
   };
+  readonly types: Types;
 };
 
 type BuildStorageTables<
@@ -128,10 +138,21 @@ class SqlContractBuilder<
     string,
     ModelBuilderState<string, string, Record<string, string>, Record<string, RelationDefinition>>
   > = Record<never, never>,
-  CoreHash extends string | undefined = undefined,
+  Types extends Record<string, StorageTypeInstance> = Record<never, never>,
+  StorageHash extends string | undefined = undefined,
   ExtensionPacks extends Record<string, unknown> | undefined = undefined,
   Capabilities extends Record<string, Record<string, boolean>> | undefined = undefined,
-> extends ContractBuilder<Target, Tables, Models, CoreHash, ExtensionPacks, Capabilities> {
+> extends ContractBuilder<Target, Tables, Models, StorageHash, ExtensionPacks, Capabilities> {
+  protected declare readonly state: ContractBuilderState<
+    Target,
+    Tables,
+    Models,
+    StorageHash,
+    ExtensionPacks,
+    Capabilities
+  > & {
+    readonly storageTypes?: Types;
+  };
   /**
    * This method is responsible for normalizing the contract IR by setting default values
    * for all required fields:
@@ -152,7 +173,7 @@ class SqlContractBuilder<
    */
   build(): Target extends string
     ? SqlContract<
-        BuildStorage<Tables>,
+        BuildStorage<Tables, Types>,
         BuildModels<Models>,
         BuildRelations<Models>,
         ContractBuilderMappings<CodecTypes>
@@ -160,7 +181,7 @@ class SqlContractBuilder<
         readonly schemaVersion: '1';
         readonly target: Target;
         readonly targetFamily: 'sql';
-        readonly coreHash: CoreHash extends string ? CoreHash : string;
+        readonly storageHash: StorageHash extends string ? StorageHash : string;
       } & (ExtensionPacks extends Record<string, unknown>
           ? { readonly extensionPacks: ExtensionPacks }
           : Record<string, never>) &
@@ -171,7 +192,7 @@ class SqlContractBuilder<
     // Type helper to ensure literal types are preserved in return type
     type BuiltContract = Target extends string
       ? SqlContract<
-          BuildStorage<Tables>,
+          BuildStorage<Tables, Types>,
           BuildModels<Models>,
           BuildRelations<Models>,
           ContractBuilderMappings<CodecTypes>
@@ -179,7 +200,7 @@ class SqlContractBuilder<
           readonly schemaVersion: '1';
           readonly target: Target;
           readonly targetFamily: 'sql';
-          readonly coreHash: CoreHash extends string ? CoreHash : string;
+          readonly storageHash: StorageHash extends string ? StorageHash : string;
         } & (ExtensionPacks extends Record<string, unknown>
             ? { readonly extensionPacks: ExtensionPacks }
             : Record<string, never>) &
@@ -194,6 +215,7 @@ class SqlContractBuilder<
     const target = this.state.target as Target & string;
 
     const storageTables = {} as Partial<Mutable<BuildStorageTables<Tables>>>;
+    const executionDefaults: ExecutionMutationDefault[] = [];
 
     for (const tableName of Object.keys(this.state.tables) as Array<keyof Tables & string>) {
       const tableState = this.state.tables[tableName];
@@ -215,17 +237,27 @@ class SqlContractBuilder<
         if (!columnState) continue;
         const codecId = columnState.type;
         const nativeType = columnState.nativeType;
+        const typeRef = columnState.typeRef;
 
         columns[columnName as keyof ColumnDefs] = {
           nativeType,
           codecId,
           nullable: (columnState.nullable ?? false) as ColumnDefs[keyof ColumnDefs]['nullable'] &
             boolean,
-          ...(columnState.typeParams ? { typeParams: columnState.typeParams } : {}),
+          ...ifDefined('typeParams', columnState.typeParams),
+          ...ifDefined('default', columnState.default),
+          ...ifDefined('typeRef', typeRef),
         } as BuildStorageColumn<
           ColumnDefs[keyof ColumnDefs]['nullable'] & boolean,
           ColumnDefs[keyof ColumnDefs]['type']
         >;
+
+        if ('executionDefault' in columnState && columnState.executionDefault) {
+          executionDefaults.push({
+            ref: { table: tableName, column: columnName },
+            onCreate: columnState.executionDefault,
+          });
+        }
       }
 
       // Build uniques from table state
@@ -240,10 +272,11 @@ class SqlContractBuilder<
         ...(i.name ? { name: i.name } : {}),
       }));
 
-      // Build foreign keys from table state
+      // Build foreign keys from table state, materializing defaults
       const foreignKeys = (tableState.foreignKeys ?? []).map((fk) => ({
         columns: fk.columns,
         references: fk.references,
+        ...applyFkDefaults(fk, this.state.foreignKeyDefaults),
         ...(fk.name ? { name: fk.name } : {}),
       }));
 
@@ -270,7 +303,26 @@ class SqlContractBuilder<
       (storageTables as Mutable<BuildStorageTables<Tables>>)[tableName] = table;
     }
 
-    const storage = { tables: storageTables as BuildStorageTables<Tables> } as BuildStorage<Tables>;
+    const storageTypes = (this.state.storageTypes ?? {}) as Types;
+    const storage: BuildStorage<Tables, Types> = {
+      tables: storageTables as BuildStorageTables<Tables>,
+      types: storageTypes,
+    };
+
+    const execution =
+      executionDefaults.length > 0
+        ? {
+            mutations: {
+              defaults: executionDefaults.sort((a, b) => {
+                const tableCompare = a.ref.table.localeCompare(b.ref.table);
+                if (tableCompare !== 0) {
+                  return tableCompare;
+                }
+                return a.ref.column.localeCompare(b.ref.column);
+              }),
+            },
+          }
+        : undefined;
 
     // Build models - construct as partial first, then assert full type
     const modelsPartial: Partial<BuildModels<Models>> = {};
@@ -374,11 +426,12 @@ class SqlContractBuilder<
       schemaVersion: '1' as const,
       target,
       targetFamily: 'sql' as const,
-      coreHash: this.state.coreHash || 'sha256:ts-builder-placeholder',
+      storageHash: this.state.storageHash || 'sha256:ts-builder-placeholder',
       models,
       relations: relationsPartial,
       storage,
       mappings,
+      ...(execution ? { execution } : {}),
       extensionPacks,
       capabilities: this.state.capabilities || {},
       meta: {},
@@ -391,7 +444,8 @@ class SqlContractBuilder<
         Target,
         Tables,
         Models,
-        CoreHash,
+        Types,
+        StorageHash,
         ExtensionPacks,
         Capabilities
       >['build']
@@ -400,13 +454,23 @@ class SqlContractBuilder<
 
   override target<T extends string>(
     packRef: TargetPackRef<'sql', T>,
-  ): SqlContractBuilder<CodecTypes, T, Tables, Models, CoreHash, ExtensionPacks, Capabilities> {
+  ): SqlContractBuilder<
+    CodecTypes,
+    T,
+    Tables,
+    Models,
+    Types,
+    StorageHash,
+    ExtensionPacks,
+    Capabilities
+  > {
     return new SqlContractBuilder<
       CodecTypes,
       T,
       Tables,
       Models,
-      CoreHash,
+      Types,
+      StorageHash,
       ExtensionPacks,
       Capabilities
     >({
@@ -422,7 +486,8 @@ class SqlContractBuilder<
     Target,
     Tables,
     Models,
-    CoreHash,
+    Types,
+    StorageHash,
     ExtensionPacks,
     Capabilities
   > {
@@ -461,7 +526,8 @@ class SqlContractBuilder<
       Target,
       Tables,
       Models,
-      CoreHash,
+      Types,
+      StorageHash,
       ExtensionPacks,
       Capabilities
     >({
@@ -472,27 +538,46 @@ class SqlContractBuilder<
 
   override capabilities<C extends Record<string, Record<string, boolean>>>(
     capabilities: C,
-  ): SqlContractBuilder<CodecTypes, Target, Tables, Models, CoreHash, ExtensionPacks, C> {
-    return new SqlContractBuilder<CodecTypes, Target, Tables, Models, CoreHash, ExtensionPacks, C>({
+  ): SqlContractBuilder<CodecTypes, Target, Tables, Models, Types, StorageHash, ExtensionPacks, C> {
+    return new SqlContractBuilder<
+      CodecTypes,
+      Target,
+      Tables,
+      Models,
+      Types,
+      StorageHash,
+      ExtensionPacks,
+      C
+    >({
       ...this.state,
       capabilities,
     });
   }
 
-  override coreHash<H extends string>(
+  override storageHash<H extends string>(
     hash: H,
-  ): SqlContractBuilder<CodecTypes, Target, Tables, Models, H, ExtensionPacks, Capabilities> {
+  ): SqlContractBuilder<
+    CodecTypes,
+    Target,
+    Tables,
+    Models,
+    Types,
+    H,
+    ExtensionPacks,
+    Capabilities
+  > {
     return new SqlContractBuilder<
       CodecTypes,
       Target,
       Tables,
       Models,
+      Types,
       H,
       ExtensionPacks,
       Capabilities
     >({
       ...this.state,
-      coreHash: hash,
+      storageHash: hash,
     });
   }
 
@@ -511,7 +596,8 @@ class SqlContractBuilder<
     Target,
     Tables & Record<TableName, ReturnType<T['build']>>,
     Models,
-    CoreHash,
+    Types,
+    StorageHash,
     ExtensionPacks,
     Capabilities
   > {
@@ -525,7 +611,8 @@ class SqlContractBuilder<
       Target,
       Tables & Record<TableName, ReturnType<T['build']>>,
       Models,
-      CoreHash,
+      Types,
+      StorageHash,
       ExtensionPacks,
       Capabilities
     >({
@@ -555,7 +642,8 @@ class SqlContractBuilder<
     Target,
     Tables,
     Models & Record<ModelName, ReturnType<M['build']>>,
-    CoreHash,
+    Types,
+    StorageHash,
     ExtensionPacks,
     Capabilities
   > {
@@ -569,7 +657,8 @@ class SqlContractBuilder<
       Target,
       Tables,
       Models & Record<ModelName, ReturnType<M['build']>>,
-      CoreHash,
+      Types,
+      StorageHash,
       ExtensionPacks,
       Capabilities
     >({
@@ -578,6 +667,64 @@ class SqlContractBuilder<
         Record<ModelName, ReturnType<M['build']>>,
     });
   }
+
+  override foreignKeyDefaults(
+    config: ForeignKeyDefaultsState,
+  ): SqlContractBuilder<
+    CodecTypes,
+    Target,
+    Tables,
+    Models,
+    Types,
+    StorageHash,
+    ExtensionPacks,
+    Capabilities
+  > {
+    return new SqlContractBuilder<
+      CodecTypes,
+      Target,
+      Tables,
+      Models,
+      Types,
+      StorageHash,
+      ExtensionPacks,
+      Capabilities
+    >({
+      ...this.state,
+      foreignKeyDefaults: config,
+    });
+  }
+
+  storageType<Name extends string, Type extends StorageTypeInstance>(
+    name: Name,
+    typeInstance: Type,
+  ): SqlContractBuilder<
+    CodecTypes,
+    Target,
+    Tables,
+    Models,
+    Types & Record<Name, Type>,
+    StorageHash,
+    ExtensionPacks,
+    Capabilities
+  > {
+    return new SqlContractBuilder<
+      CodecTypes,
+      Target,
+      Tables,
+      Models,
+      Types & Record<Name, Type>,
+      StorageHash,
+      ExtensionPacks,
+      Capabilities
+    >({
+      ...this.state,
+      storageTypes: {
+        ...(this.state.storageTypes ?? {}),
+        [name]: typeInstance,
+      },
+    });
+  }
 }
 
 export function defineContract<

package/src/contract.ts

@@ -14,6 +14,7 @@ import type {
   StorageTypeInstance,
   UniqueConstraint,
 } from '@prisma-next/sql-contract/types';
+import { ColumnDefaultSchema } from '@prisma-next/sql-contract/validators';
 import { type } from 'arktype';
 import type { O } from 'ts-toolbelt';
 
@@ -21,12 +22,14 @@ import type { O } from 'ts-toolbelt';
  * Structural validation schema for SqlContract using Arktype.
  * This validates the shape and types of the contract structure.
  */
+
 const StorageColumnSchema = type.declare<StorageColumn>().type({
   nativeType: 'string',
   codecId: 'string',
   nullable: 'boolean',
   'typeParams?': 'Record<string, unknown>',
   'typeRef?': 'string',
+  'default?': ColumnDefaultSchema,
 });
 
 const StorageTypeInstanceSchema = type.declare<StorageTypeInstance>().type({
@@ -59,6 +62,8 @@ const ForeignKeySchema = type.declare<ForeignKey>().type({
   columns: type.string.array().readonly(),
   references: ForeignKeyReferencesSchema,
   'name?': 'string',
+  constraint: 'boolean',
+  index: 'boolean',
 });
 
 const StorageTableSchema = type.declare<StorageTable>().type({
@@ -88,6 +93,27 @@ const ModelSchema = type.declare<ModelDefinition>().type({
   relations: type({ '[string]': 'unknown' }),
 });
 
+const ExecutionMutationDefaultValueSchema = type({
+  kind: "'generator'",
+  id: "'ulid' | 'nanoid' | 'uuidv7' | 'uuidv4' | 'cuid2' | 'ksuid'",
+  'params?': 'Record<string, unknown>',
+});
+
+const ExecutionMutationDefaultSchema = type({
+  ref: {
+    table: 'string',
+    column: 'string',
+  },
+  'onCreate?': ExecutionMutationDefaultValueSchema,
+  'onUpdate?': ExecutionMutationDefaultValueSchema,
+});
+
+const ExecutionSchema = type({
+  mutations: {
+    defaults: ExecutionMutationDefaultSchema.array().readonly(),
+  },
+});
+
 /**
  * Complete SqlContract schema for structural validation.
  * This validates the entire contract structure at once.
@@ -96,7 +122,8 @@ const SqlContractSchema = type({
   'schemaVersion?': "'1'",
   target: 'string',
   targetFamily: "'sql'",
-  coreHash: 'string',
+  storageHash: 'string',
+  'executionHash?': 'string',
   'profileHash?': 'string',
   'capabilities?': 'Record<string, Record<string, boolean>>',
   'extensionPacks?': 'Record<string, unknown>',
@@ -104,6 +131,7 @@ const SqlContractSchema = type({
   'sources?': 'Record<string, unknown>',
   models: type({ '[string]': ModelSchema }),
   storage: StorageSchema,
+  'execution?': ExecutionSchema,
 });
 
 /**
@@ -198,13 +226,15 @@ export function computeMappings(
  * This checks that references (e.g., foreign keys, primary keys, uniques) point to storage objects that already exist.
  * Structural validation is expected to have already completed before this helper runs.
  *
+ * Rule: keep this focused on structural consistency only; capability/feature
+ * gating (e.g., defaults.*) belongs in migration/runtime verification, not here.
+ *
  * @param structurallyValidatedContract - The contract whose structure has already been validated
  * @throws Error if logical validation fails
  */
 function validateContractLogic(structurallyValidatedContract: SqlContract<SqlStorage>): void {
   const { storage, models } = structurallyValidatedContract;
   const tableNames = new Set(Object.keys(storage.tables));
-  const typeInstanceNames = new Set(Object.keys(storage.types ?? {}));
 
   // Validate storage.types if present
   if (storage.types) {
@@ -235,11 +265,26 @@ function validateContractLogic(structurallyValidatedContract: SqlContract<SqlSto
         );
       }
 
-      // Validate typeRef points to an existing storage.types key
-      if (column.typeRef !== undefined && !typeInstanceNames.has(column.typeRef)) {
-        throw new Error(
-          `Column "${columnName}" in table "${tableName}" references non-existent type instance "${column.typeRef}" (not found in storage.types)`,
-        );
+      // Validate typeRef points to an existing storage.types key and matches codecId/nativeType
+      if (column.typeRef !== undefined) {
+        const referencedType = storage.types?.[column.typeRef];
+        if (!referencedType) {
+          throw new Error(
+            `Column "${columnName}" in table "${tableName}" references non-existent type instance "${column.typeRef}" (not found in storage.types)`,
+          );
+        }
+
+        if (column.codecId !== referencedType.codecId) {
+          throw new Error(
+            `Column "${columnName}" in table "${tableName}" has codecId "${column.codecId}" but references type instance "${column.typeRef}" with codecId "${referencedType.codecId}"`,
+          );
+        }
+
+        if (column.nativeType !== referencedType.nativeType) {
+          throw new Error(
+            `Column "${columnName}" in table "${tableName}" has nativeType "${column.nativeType}" but references type instance "${column.typeRef}" with nativeType "${referencedType.nativeType}"`,
+          );
+        }
       }
     }
   }
@@ -431,82 +476,8 @@ function validateContractLogic(structurallyValidatedContract: SqlContract<SqlSto
   }
 }
 
-export function normalizeContract(contract: unknown): SqlContract<SqlStorage> {
-  const contractObj = contract as Record<string, unknown>;
-
-  // Only normalize if storage exists (validation will catch if it's missing)
-  let normalizedStorage = contractObj['storage'];
-  if (normalizedStorage && typeof normalizedStorage === 'object' && normalizedStorage !== null) {
-    const storage = normalizedStorage as Record<string, unknown>;
-    const tables = storage['tables'] as Record<string, unknown> | undefined;
-
-    if (tables) {
-      // Normalize storage tables
-      const normalizedTables: Record<string, unknown> = {};
-      for (const [tableName, table] of Object.entries(tables)) {
-        const tableObj = table as Record<string, unknown>;
-        const columns = tableObj['columns'] as Record<string, unknown> | undefined;
-
-        if (columns) {
-          // Normalize columns: add nullable: false if missing
-          const normalizedColumns: Record<string, unknown> = {};
-          for (const [columnName, column] of Object.entries(columns)) {
-            const columnObj = column as Record<string, unknown>;
-            const normalizedColumn: Record<string, unknown> = {
-              ...columnObj,
-              nullable: columnObj['nullable'] ?? false,
-            };
-
-            normalizedColumns[columnName] = normalizedColumn;
-          }
-
-          // Normalize table arrays: add empty arrays if missing
-          normalizedTables[tableName] = {
-            ...tableObj,
-            columns: normalizedColumns,
-            uniques: tableObj['uniques'] ?? [],
-            indexes: tableObj['indexes'] ?? [],
-            foreignKeys: tableObj['foreignKeys'] ?? [],
-          };
-        } else {
-          normalizedTables[tableName] = tableObj;
-        }
-      }
-
-      normalizedStorage = {
-        ...storage,
-        tables: normalizedTables,
-      };
-    }
-  }
-
-  // Only normalize if models exists (validation will catch if it's missing)
-  let normalizedModels = contractObj['models'];
-  if (normalizedModels && typeof normalizedModels === 'object' && normalizedModels !== null) {
-    const models = normalizedModels as Record<string, unknown>;
-    const normalizedModelsObj: Record<string, unknown> = {};
-    for (const [modelName, model] of Object.entries(models)) {
-      const modelObj = model as Record<string, unknown>;
-      normalizedModelsObj[modelName] = {
-        ...modelObj,
-        relations: modelObj['relations'] ?? {},
-      };
-    }
-    normalizedModels = normalizedModelsObj;
-  }
-
-  // Normalize top-level fields: add empty objects if missing
-  return {
-    ...contractObj,
-    models: normalizedModels,
-    relations: contractObj['relations'] ?? {},
-    storage: normalizedStorage,
-    extensionPacks: contractObj['extensionPacks'] ?? {},
-    capabilities: contractObj['capabilities'] ?? {},
-    meta: contractObj['meta'] ?? {},
-    sources: contractObj['sources'] ?? {},
-  } as SqlContract<SqlStorage>;
-}
+import { normalizeContract } from '@prisma-next/sql-contract/validate';
+export { normalizeContract };
 
 /**
  * Validates that a JSON import conforms to the SqlContract structure