@prisma-next/sql-contract 0.3.0-dev.8 → 0.3.0-dev.81

package/src/factories.ts

@@ -1,5 +1,11 @@
+import type {
+  ExecutionHashBase,
+  ProfileHashBase,
+  StorageHashBase,
+} from '@prisma-next/contract/types';
 import type {
   ForeignKey,
+  ForeignKeyOptions,
   ForeignKeyReferences,
   Index,
   ModelDefinition,
@@ -13,6 +19,7 @@ import type {
   StorageTable,
   UniqueConstraint,
 } from './types';
+import { applyFkDefaults } from './types';
 
 /**
  * Creates a StorageColumn with nativeType and codecId.
@@ -52,16 +59,20 @@ export function fk(
   columns: readonly string[],
   refTable: string,
   refColumns: readonly string[],
-  name?: string,
+  opts?: ForeignKeyOptions & { constraint?: boolean; index?: boolean },
 ): ForeignKey {
   const references: ForeignKeyReferences = {
     table: refTable,
     columns: refColumns,
   };
+
   return {
     columns,
     references,
-    ...(name !== undefined && { name }),
+    ...(opts?.name !== undefined && { name: opts.name }),
+    ...(opts?.onDelete !== undefined && { onDelete: opts.onDelete }),
+    ...(opts?.onUpdate !== undefined && { onUpdate: opts.onUpdate }),
+    ...applyFkDefaults({ constraint: opts?.constraint, index: opts?.index }),
   };
 }
 
@@ -100,26 +111,40 @@ export function storage(tables: Record<string, StorageTable>): SqlStorage {
   return { tables };
 }
 
-export function contract(opts: {
+export function contract<
+  TStorageHash extends StorageHashBase<string> = StorageHashBase<string>,
+  TExecutionHash extends ExecutionHashBase<string> = ExecutionHashBase<string>,
+  TProfileHash extends ProfileHashBase<string> = ProfileHashBase<string>,
+>(opts: {
   target: string;
-  coreHash: string;
+  storageHash: TStorageHash;
+  executionHash?: TExecutionHash;
   storage: SqlStorage;
   models?: Record<string, ModelDefinition>;
   relations?: Record<string, unknown>;
   mappings?: Partial<SqlMappings>;
   schemaVersion?: '1';
   targetFamily?: 'sql';
-  profileHash?: string;
+  profileHash?: TProfileHash;
   capabilities?: Record<string, Record<string, boolean>>;
   extensionPacks?: Record<string, unknown>;
   meta?: Record<string, unknown>;
   sources?: Record<string, unknown>;
-}): SqlContract {
+}): SqlContract<
+  SqlStorage,
+  Record<string, unknown>,
+  Record<string, unknown>,
+  SqlMappings,
+  TStorageHash,
+  TExecutionHash,
+  TProfileHash
+> {
   return {
     schemaVersion: opts.schemaVersion ?? '1',
     target: opts.target,
     targetFamily: opts.targetFamily ?? 'sql',
-    coreHash: opts.coreHash,
+    storageHash: opts.storageHash,
+    ...(opts.executionHash !== undefined && { executionHash: opts.executionHash }),
     storage: opts.storage,
     models: opts.models ?? {},
     relations: opts.relations ?? {},
@@ -129,5 +154,13 @@ export function contract(opts: {
     ...(opts.extensionPacks !== undefined && { extensionPacks: opts.extensionPacks }),
     ...(opts.meta !== undefined && { meta: opts.meta }),
     ...(opts.sources !== undefined && { sources: opts.sources as Record<string, unknown> }),
-  } as SqlContract;
+  } as SqlContract<
+    SqlStorage,
+    Record<string, unknown>,
+    Record<string, unknown>,
+    SqlMappings,
+    TStorageHash,
+    TExecutionHash,
+    TProfileHash
+  >;
 }

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './exports/factories';
 export * from './exports/types';
+export * from './exports/validate';
 export * from './exports/validators';

package/src/types.ts

@@ -1,9 +1,39 @@
-import type { ContractBase } from '@prisma-next/contract/types';
+import type {
+  ColumnDefault,
+  ContractBase,
+  ExecutionHashBase,
+  ExecutionSection,
+  ProfileHashBase,
+  StorageHashBase,
+} from '@prisma-next/contract/types';
 
+/**
+ * A column definition in storage.
+ *
+ * `typeParams` is optional because most columns use non-parameterized types.
+ * Columns with parameterized types can either inline `typeParams` or reference
+ * a named {@link StorageTypeInstance} via `typeRef`.
+ */
 export type StorageColumn = {
   readonly nativeType: string;
   readonly codecId: string;
   readonly nullable: boolean;
+  /**
+   * Opaque, codec-owned JS/type parameters.
+   * The codec that owns `codecId` defines the shape and semantics.
+   * Mutually exclusive with `typeRef`.
+   */
+  readonly typeParams?: Record<string, unknown>;
+  /**
+   * Reference to a named type instance in `storage.types`.
+   * Mutually exclusive with `typeParams`.
+   */
+  readonly typeRef?: string;
+  /**
+   * Default value for the column.
+   * Can be a literal value or database function.
+   */
+  readonly default?: ColumnDefault;
 };
 
 export type PrimaryKey = {
@@ -19,6 +49,16 @@ export type UniqueConstraint = {
 export type Index = {
   readonly columns: readonly string[];
   readonly name?: string;
+  /**
+   * Optional access method identifier.
+   * Extension-specific methods are represented as strings and interpreted
+   * by the owning extension package.
+   */
+  readonly using?: string;
+  /**
+   * Optional extension-owned index configuration payload.
+   */
+  readonly config?: Record<string, unknown>;
 };
 
 export type ForeignKeyReferences = {
@@ -26,10 +66,24 @@ export type ForeignKeyReferences = {
   readonly columns: readonly string[];
 };
 
+export type ReferentialAction = 'noAction' | 'restrict' | 'cascade' | 'setNull' | 'setDefault';
+
+export type ForeignKeyOptions = {
+  readonly name?: string;
+  readonly onDelete?: ReferentialAction;
+  readonly onUpdate?: ReferentialAction;
+};
+
 export type ForeignKey = {
   readonly columns: readonly string[];
   readonly references: ForeignKeyReferences;
   readonly name?: string;
+  readonly onDelete?: ReferentialAction;
+  readonly onUpdate?: ReferentialAction;
+  /** Whether to emit FK constraint DDL (ALTER TABLE … ADD CONSTRAINT … FOREIGN KEY). */
+  readonly constraint: boolean;
+  /** Whether to emit a backing index for the FK columns. */
+  readonly index: boolean;
 };
 
 export type StorageTable = {
@@ -40,8 +94,29 @@ export type StorageTable = {
   readonly foreignKeys: ReadonlyArray<ForeignKey>;
 };
 
+/**
+ * A named, parameterized type instance.
+ * These are registered in `storage.types` for reuse across columns
+ * and to enable ergonomic schema surfaces like `schema.types.MyType`.
+ *
+ * Unlike {@link StorageColumn}, `typeParams` is required here because
+ * `StorageTypeInstance` exists specifically to define reusable parameterized types.
+ * A type instance without parameters would be redundant—columns can reference
+ * the codec directly via `codecId`.
+ */
+export type StorageTypeInstance = {
+  readonly codecId: string;
+  readonly nativeType: string;
+  readonly typeParams: Record<string, unknown>;
+};
+
 export type SqlStorage = {
   readonly tables: Record<string, StorageTable>;
+  /**
+   * Named type instances for parameterized/custom types.
+   * Columns can reference these via `typeRef`.
+   */
+  readonly types?: Record<string, StorageTypeInstance>;
 };
 
 export type ModelField = {
@@ -63,8 +138,49 @@ export type SqlMappings = {
   readonly tableToModel?: Record<string, string>;
   readonly fieldToColumn?: Record<string, Record<string, string>>;
   readonly columnToField?: Record<string, Record<string, string>>;
-  readonly codecTypes: Record<string, { readonly output: unknown }>;
-  readonly operationTypes: Record<string, Record<string, unknown>>;
+};
+
+export const DEFAULT_FK_CONSTRAINT = true;
+export const DEFAULT_FK_INDEX = true;
+
+export function applyFkDefaults(
+  fk: { constraint?: boolean | undefined; index?: boolean | undefined },
+  overrideDefaults?: { constraint?: boolean | undefined; index?: boolean | undefined },
+): { constraint: boolean; index: boolean } {
+  return {
+    constraint: fk.constraint ?? overrideDefaults?.constraint ?? DEFAULT_FK_CONSTRAINT,
+    index: fk.index ?? overrideDefaults?.index ?? DEFAULT_FK_INDEX,
+  };
+}
+
+export type TypeMaps<
+  TCodecTypes extends Record<string, { output: unknown }> = Record<string, never>,
+  TOperationTypes extends Record<string, unknown> = Record<string, never>,
+> = {
+  readonly codecTypes: TCodecTypes;
+  readonly operationTypes: TOperationTypes;
+};
+
+export type CodecTypesOf<T> = [T] extends [never]
+  ? Record<string, never>
+  : T extends { readonly codecTypes: infer C }
+    ? C extends Record<string, { output: unknown }>
+      ? C
+      : Record<string, never>
+    : Record<string, never>;
+
+export type OperationTypesOf<T> = [T] extends [never]
+  ? Record<string, never>
+  : T extends { readonly operationTypes: infer O }
+    ? O extends Record<string, unknown>
+      ? O
+      : Record<string, never>
+    : Record<string, never>;
+
+export type TypeMapsPhantomKey = '__@prisma-next/sql-contract/typeMaps@__';
+
+export type ContractWithTypeMaps<TContract, TTypeMaps> = TContract & {
+  readonly [K in TypeMapsPhantomKey]?: TTypeMaps;
 };
 
 export type SqlContract<
@@ -72,16 +188,29 @@ export type SqlContract<
   M extends Record<string, unknown> = Record<string, unknown>,
   R extends Record<string, unknown> = Record<string, unknown>,
   Map extends SqlMappings = SqlMappings,
-> = ContractBase & {
+  TStorageHash extends StorageHashBase<string> = StorageHashBase<string>,
+  TExecutionHash extends ExecutionHashBase<string> = ExecutionHashBase<string>,
+  TProfileHash extends ProfileHashBase<string> = ProfileHashBase<string>,
+> = ContractBase<TStorageHash, TExecutionHash, TProfileHash> & {
   readonly targetFamily: string;
   readonly storage: S;
   readonly models: M;
   readonly relations: R;
   readonly mappings: Map;
+  readonly execution?: ExecutionSection;
 };
 
-export type ExtractCodecTypes<TContract extends SqlContract<SqlStorage>> =
-  TContract['mappings']['codecTypes'];
+export type ExtractTypeMapsFromContract<T> = TypeMapsPhantomKey extends keyof T
+  ? NonNullable<T[TypeMapsPhantomKey & keyof T]>
+  : never;
+
+export type ExtractCodecTypes<T> = CodecTypesOf<ExtractTypeMapsFromContract<T>>;
+export type ExtractOperationTypes<T> = OperationTypesOf<ExtractTypeMapsFromContract<T>>;
+
+export type ResolveCodecTypes<TContract, TTypeMaps> = [TTypeMaps] extends [never]
+  ? ExtractCodecTypes<TContract>
+  : CodecTypesOf<TTypeMaps>;
 
-export type ExtractOperationTypes<TContract extends SqlContract<SqlStorage>> =
-  TContract['mappings']['operationTypes'];
+export type ResolveOperationTypes<TContract, TTypeMaps> = [TTypeMaps] extends [never]
+  ? ExtractOperationTypes<TContract>
+  : OperationTypesOf<TTypeMaps>;

package/src/validate.ts

@@ -0,0 +1,272 @@
+import type { ColumnDefaultLiteralInputValue } from '@prisma-next/contract/types';
+import { isTaggedBigInt, isTaggedRaw } from '@prisma-next/contract/types';
+import { constructContract } from './construct';
+import type { SqlContract, SqlStorage, StorageColumn, StorageTable } from './types';
+import { applyFkDefaults } from './types';
+import { validateSqlContract, validateStorageSemantics } from './validators';
+
+function validateContractLogic(contract: SqlContract<SqlStorage>): void {
+  const tableNames = new Set(Object.keys(contract.storage.tables));
+
+  for (const [tableName, table] of Object.entries(contract.storage.tables)) {
+    const columnNames = new Set(Object.keys(table.columns));
+
+    if (table.primaryKey) {
+      for (const colName of table.primaryKey.columns) {
+        if (!columnNames.has(colName)) {
+          throw new Error(
+            `Table "${tableName}" primaryKey references non-existent column "${colName}"`,
+          );
+        }
+      }
+    }
+
+    for (const unique of table.uniques) {
+      for (const colName of unique.columns) {
+        if (!columnNames.has(colName)) {
+          throw new Error(
+            `Table "${tableName}" unique constraint references non-existent column "${colName}"`,
+          );
+        }
+      }
+    }
+
+    for (const index of table.indexes) {
+      for (const colName of index.columns) {
+        if (!columnNames.has(colName)) {
+          throw new Error(`Table "${tableName}" index references non-existent column "${colName}"`);
+        }
+      }
+    }
+
+    for (const [colName, column] of Object.entries(table.columns)) {
+      if (!column.nullable && column.default?.kind === 'literal' && column.default.value === null) {
+        throw new Error(
+          `Table "${tableName}" column "${colName}" is NOT NULL but has a literal null default`,
+        );
+      }
+    }
+
+    for (const fk of table.foreignKeys) {
+      for (const colName of fk.columns) {
+        if (!columnNames.has(colName)) {
+          throw new Error(
+            `Table "${tableName}" foreignKey references non-existent column "${colName}"`,
+          );
+        }
+      }
+
+      if (!tableNames.has(fk.references.table)) {
+        throw new Error(
+          `Table "${tableName}" foreignKey references non-existent table "${fk.references.table}"`,
+        );
+      }
+
+      const referencedTable = contract.storage.tables[
+        fk.references.table
+      ] as (typeof contract.storage.tables)[string];
+      const referencedColumnNames = new Set(Object.keys(referencedTable.columns));
+      for (const colName of fk.references.columns) {
+        if (!referencedColumnNames.has(colName)) {
+          throw new Error(
+            `Table "${tableName}" foreignKey references non-existent column "${colName}" in table "${fk.references.table}"`,
+          );
+        }
+      }
+
+      if (fk.columns.length !== fk.references.columns.length) {
+        throw new Error(
+          `Table "${tableName}" foreignKey column count (${fk.columns.length}) does not match referenced column count (${fk.references.columns.length})`,
+        );
+      }
+    }
+  }
+}
+
+const BIGINT_NATIVE_TYPES = new Set(['bigint', 'int8']);
+
+export function isBigIntColumn(column: StorageColumn): boolean {
+  const nativeType = column.nativeType?.toLowerCase() ?? '';
+  if (BIGINT_NATIVE_TYPES.has(nativeType)) return true;
+  const codecId = column.codecId?.toLowerCase() ?? '';
+  return codecId.includes('int8') || codecId.includes('bigint');
+}
+
+export function decodeDefaultLiteralValue(
+  value: ColumnDefaultLiteralInputValue,
+  column: StorageColumn,
+  tableName: string,
+  columnName: string,
+): ColumnDefaultLiteralInputValue {
+  if (value instanceof Date) {
+    return value;
+  }
+  if (isTaggedRaw(value)) {
+    return value.value;
+  }
+  if (isTaggedBigInt(value)) {
+    if (!isBigIntColumn(column)) {
+      return value;
+    }
+    try {
+      return BigInt(value.value);
+    } catch {
+      throw new Error(
+        `Invalid tagged bigint for default value on "${tableName}.${columnName}": "${value.value}" is not a valid integer`,
+      );
+    }
+  }
+  return value;
+}
+
+export function decodeContractDefaults<T extends SqlContract<SqlStorage>>(contract: T): T {
+  const tables = contract.storage.tables;
+  let tablesChanged = false;
+  const decodedTables: Record<string, StorageTable> = {};
+
+  for (const [tableName, table] of Object.entries(tables)) {
+    let columnsChanged = false;
+    const decodedColumns: Record<string, StorageColumn> = {};
+
+    for (const [columnName, column] of Object.entries(table.columns)) {
+      if (column.default?.kind === 'literal') {
+        const decodedValue = decodeDefaultLiteralValue(
+          column.default.value,
+          column,
+          tableName,
+          columnName,
+        );
+        if (decodedValue !== column.default.value) {
+          columnsChanged = true;
+          decodedColumns[columnName] = {
+            ...column,
+            default: { kind: 'literal', value: decodedValue },
+          };
+          continue;
+        }
+      }
+      decodedColumns[columnName] = column;
+    }
+
+    if (columnsChanged) {
+      tablesChanged = true;
+      decodedTables[tableName] = { ...table, columns: decodedColumns };
+    } else {
+      decodedTables[tableName] = table;
+    }
+  }
+
+  if (!tablesChanged) {
+    return contract;
+  }
+
+  // The spread widens to SqlContract<SqlStorage>, but this transformation only
+  // decodes tagged bigint defaults for bigint-like columns and preserves all
+  // other properties of T.
+  return {
+    ...contract,
+    storage: {
+      ...contract.storage,
+      tables: decodedTables,
+    },
+  } as T;
+}
+
+export function normalizeContract(contract: unknown): SqlContract<SqlStorage> {
+  if (typeof contract !== 'object' || contract === null) {
+    return contract as SqlContract<SqlStorage>;
+  }
+
+  const contractObj = contract as Record<string, unknown>;
+
+  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) {
+      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) {
+          const normalizedColumns: Record<string, unknown> = {};
+          for (const [columnName, column] of Object.entries(columns)) {
+            const columnObj = column as Record<string, unknown>;
+            normalizedColumns[columnName] = {
+              ...columnObj,
+              nullable: columnObj['nullable'] ?? false,
+            };
+          }
+
+          // Normalize foreign keys: add constraint/index defaults if missing
+          const rawForeignKeys = (tableObj['foreignKeys'] ?? []) as Array<Record<string, unknown>>;
+          const normalizedForeignKeys = rawForeignKeys.map((fk) => ({
+            ...fk,
+            ...applyFkDefaults({
+              constraint: typeof fk['constraint'] === 'boolean' ? fk['constraint'] : undefined,
+              index: typeof fk['index'] === 'boolean' ? fk['index'] : undefined,
+            }),
+          }));
+
+          normalizedTables[tableName] = {
+            ...tableObj,
+            columns: normalizedColumns,
+            uniques: tableObj['uniques'] ?? [],
+            indexes: tableObj['indexes'] ?? [],
+            foreignKeys: normalizedForeignKeys,
+          };
+        } else {
+          normalizedTables[tableName] = tableObj;
+        }
+      }
+
+      normalizedStorage = {
+        ...storage,
+        tables: normalizedTables,
+      };
+    }
+  }
+
+  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;
+  }
+
+  return {
+    ...contractObj,
+    models: normalizedModels,
+    relations: contractObj['relations'] ?? {},
+    storage: normalizedStorage,
+    extensionPacks: contractObj['extensionPacks'] ?? {},
+    capabilities: contractObj['capabilities'] ?? {},
+    meta: contractObj['meta'] ?? {},
+    sources: contractObj['sources'] ?? {},
+  } as SqlContract<SqlStorage>;
+}
+
+export function validateContract<TContract extends SqlContract<SqlStorage>>(
+  value: unknown,
+): TContract {
+  const normalized = normalizeContract(value);
+  const structurallyValid = validateSqlContract<SqlContract<SqlStorage>>(normalized);
+  validateContractLogic(structurallyValid);
+
+  const semanticErrors = validateStorageSemantics(structurallyValid.storage);
+  if (semanticErrors.length > 0) {
+    throw new Error(`Contract semantic validation failed: ${semanticErrors.join('; ')}`);
+  }
+
+  const constructed = constructContract<TContract>(structurallyValid);
+  return decodeContractDefaults(constructed) as TContract;
+}