@prisma-next/sql-contract 0.3.0-dev.4 → 0.3.0-dev.40

package/src/factories.ts

@@ -0,0 +1,162 @@
+import type {
+  ExecutionHashBase,
+  ProfileHashBase,
+  StorageHashBase,
+} from '@prisma-next/contract/types';
+import type {
+  ForeignKey,
+  ForeignKeyReferences,
+  Index,
+  ModelDefinition,
+  ModelField,
+  ModelStorage,
+  PrimaryKey,
+  SqlContract,
+  SqlMappings,
+  SqlStorage,
+  StorageColumn,
+  StorageTable,
+  UniqueConstraint,
+} from './types';
+import { applyFkDefaults } from './types';
+
+/**
+ * Creates a StorageColumn with nativeType and codecId.
+ *
+ * @param nativeType - Native database type identifier (e.g., 'int4', 'text', 'vector')
+ * @param codecId - Codec identifier (e.g., 'pg/int4@1', 'pg/text@1')
+ * @param nullable - Whether the column is nullable (default: false)
+ * @returns StorageColumn with nativeType and codecId
+ */
+export function col(nativeType: string, codecId: string, nullable = false): StorageColumn {
+  return {
+    nativeType,
+    codecId,
+    nullable,
+  };
+}
+
+export function pk(...columns: readonly string[]): PrimaryKey {
+  return {
+    columns,
+  };
+}
+
+export function unique(...columns: readonly string[]): UniqueConstraint {
+  return {
+    columns,
+  };
+}
+
+export function index(...columns: readonly string[]): Index {
+  return {
+    columns,
+  };
+}
+
+export function fk(
+  columns: readonly string[],
+  refTable: string,
+  refColumns: readonly string[],
+  opts?: { name?: string; constraint?: boolean; index?: boolean },
+): ForeignKey {
+  const references: ForeignKeyReferences = {
+    table: refTable,
+    columns: refColumns,
+  };
+  return {
+    columns,
+    references,
+    ...applyFkDefaults({ constraint: opts?.constraint, index: opts?.index }),
+    ...(opts?.name !== undefined && { name: opts.name }),
+  };
+}
+
+export function table(
+  columns: Record<string, StorageColumn>,
+  opts?: {
+    pk?: PrimaryKey;
+    uniques?: readonly UniqueConstraint[];
+    indexes?: readonly Index[];
+    fks?: readonly ForeignKey[];
+  },
+): StorageTable {
+  return {
+    columns,
+    ...(opts?.pk !== undefined && { primaryKey: opts.pk }),
+    uniques: opts?.uniques ?? [],
+    indexes: opts?.indexes ?? [],
+    foreignKeys: opts?.fks ?? [],
+  };
+}
+
+export function model(
+  table: string,
+  fields: Record<string, ModelField>,
+  relations: Record<string, unknown> = {},
+): ModelDefinition {
+  const storage: ModelStorage = { table };
+  return {
+    storage,
+    fields,
+    relations,
+  };
+}
+
+export function storage(tables: Record<string, StorageTable>): SqlStorage {
+  return { tables };
+}
+
+export function contract<
+  TStorageHash extends StorageHashBase<string> = StorageHashBase<string>,
+  TExecutionHash extends ExecutionHashBase<string> = ExecutionHashBase<string>,
+  TProfileHash extends ProfileHashBase<string> = ProfileHashBase<string>,
+>(opts: {
+  target: string;
+  storageHash: TStorageHash;
+  executionHash?: TExecutionHash;
+  storage: SqlStorage;
+  models?: Record<string, ModelDefinition>;
+  relations?: Record<string, unknown>;
+  mappings?: Partial<SqlMappings>;
+  schemaVersion?: '1';
+  targetFamily?: 'sql';
+  profileHash?: TProfileHash;
+  capabilities?: Record<string, Record<string, boolean>>;
+  extensionPacks?: Record<string, unknown>;
+  meta?: Record<string, unknown>;
+  sources?: Record<string, unknown>;
+}): SqlContract<
+  SqlStorage,
+  Record<string, unknown>,
+  Record<string, unknown>,
+  SqlMappings,
+  TStorageHash,
+  TExecutionHash,
+  TProfileHash
+> {
+  return {
+    schemaVersion: opts.schemaVersion ?? '1',
+    target: opts.target,
+    targetFamily: opts.targetFamily ?? 'sql',
+    storageHash: opts.storageHash,
+    ...(opts.executionHash !== undefined && { executionHash: opts.executionHash }),
+    storage: opts.storage,
+    models: opts.models ?? {},
+    relations: opts.relations ?? {},
+    mappings: (opts.mappings ?? {}) as SqlMappings,
+    ...(opts.profileHash !== undefined && { profileHash: opts.profileHash }),
+    ...(opts.capabilities !== undefined && { capabilities: opts.capabilities }),
+    ...(opts.extensionPacks !== undefined && { extensionPacks: opts.extensionPacks }),
+    ...(opts.meta !== undefined && { meta: opts.meta }),
+    ...(opts.sources !== undefined && { sources: opts.sources as Record<string, unknown> }),
+  } as SqlContract<
+    SqlStorage,
+    Record<string, unknown>,
+    Record<string, unknown>,
+    SqlMappings,
+    TStorageHash,
+    TExecutionHash,
+    TProfileHash
+  >;
+}

package/src/index.ts

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

package/src/pack-types.ts

@@ -0,0 +1,9 @@
+/**
+ * Storage type metadata for pack refs.
+ */
+export interface StorageTypeMetadata {
+  readonly typeId: string;
+  readonly familyId: string;
+  readonly targetId: string;
+  readonly nativeType?: string;
+}

package/src/types.ts

@@ -0,0 +1,163 @@
+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 = {
+  readonly columns: readonly string[];
+  readonly name?: string;
+};
+
+export type UniqueConstraint = {
+  readonly columns: readonly string[];
+  readonly name?: string;
+};
+
+export type Index = {
+  readonly columns: readonly string[];
+  readonly name?: string;
+};
+
+export type ForeignKeyReferences = {
+  readonly table: string;
+  readonly columns: readonly string[];
+};
+
+export type ForeignKey = {
+  readonly columns: readonly string[];
+  readonly references: ForeignKeyReferences;
+  readonly name?: string;
+  /** 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 = {
+  readonly columns: Record<string, StorageColumn>;
+  readonly primaryKey?: PrimaryKey;
+  readonly uniques: ReadonlyArray<UniqueConstraint>;
+  readonly indexes: ReadonlyArray<Index>;
+  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 = {
+  readonly column: string;
+};
+
+export type ModelStorage = {
+  readonly table: string;
+};
+
+export type ModelDefinition = {
+  readonly storage: ModelStorage;
+  readonly fields: Record<string, ModelField>;
+  readonly relations: Record<string, unknown>;
+};
+
+export type SqlMappings = {
+  readonly modelToTable?: Record<string, string>;
+  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;
+
+/**
+ * Resolves foreign key `constraint` and `index` fields to their effective boolean values,
+ * falling back through optional override defaults, then to the global defaults.
+ */
+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 SqlContract<
+  S extends SqlStorage = SqlStorage,
+  M extends Record<string, unknown> = Record<string, unknown>,
+  R extends Record<string, unknown> = Record<string, unknown>,
+  Map extends SqlMappings = SqlMappings,
+  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 ExtractOperationTypes<TContract extends SqlContract<SqlStorage>> =
+  TContract['mappings']['operationTypes'];

package/src/validate.ts

@@ -0,0 +1,335 @@
+import type { ModelDefinition, SqlContract, SqlMappings, SqlStorage } from './types';
+import { applyFkDefaults } from './types';
+import { validateSqlContract } from './validators';
+
+type ResolvedMappings = {
+  modelToTable: Record<string, string>;
+  tableToModel: Record<string, string>;
+  fieldToColumn: Record<string, Record<string, string>>;
+  columnToField: Record<string, Record<string, string>>;
+  codecTypes: Record<string, { readonly output: unknown }>;
+  operationTypes: Record<string, Record<string, unknown>>;
+};
+
+function computeDefaultMappings(models: Record<string, ModelDefinition>): ResolvedMappings {
+  const modelToTable: Record<string, string> = {};
+  const tableToModel: Record<string, string> = {};
+  const fieldToColumn: Record<string, Record<string, string>> = {};
+  const columnToField: Record<string, Record<string, string>> = {};
+
+  for (const [modelName, model] of Object.entries(models)) {
+    const tableName = model.storage.table;
+    modelToTable[modelName] = tableName;
+    tableToModel[tableName] = modelName;
+
+    const modelFieldToColumn: Record<string, string> = {};
+    for (const [fieldName, field] of Object.entries(model.fields)) {
+      const columnName = field.column;
+      modelFieldToColumn[fieldName] = columnName;
+      if (!columnToField[tableName]) {
+        columnToField[tableName] = {};
+      }
+      columnToField[tableName][columnName] = fieldName;
+    }
+
+    fieldToColumn[modelName] = modelFieldToColumn;
+  }
+
+  return {
+    modelToTable,
+    tableToModel,
+    fieldToColumn,
+    columnToField,
+    codecTypes: {},
+    operationTypes: {},
+  };
+}
+
+function assertInverseModelMappings(
+  modelToTable: Record<string, string>,
+  tableToModel: Record<string, string>,
+) {
+  for (const [model, table] of Object.entries(modelToTable)) {
+    if (tableToModel[table] !== model) {
+      throw new Error(
+        `Mappings override mismatch: modelToTable.${model}="${table}" is not mirrored in tableToModel`,
+      );
+    }
+  }
+  for (const [table, model] of Object.entries(tableToModel)) {
+    if (modelToTable[model] !== table) {
+      throw new Error(
+        `Mappings override mismatch: tableToModel.${table}="${model}" is not mirrored in modelToTable`,
+      );
+    }
+  }
+}
+
+function assertInverseFieldMappings(
+  fieldToColumn: Record<string, Record<string, string>>,
+  columnToField: Record<string, Record<string, string>>,
+  modelToTable: Record<string, string>,
+  tableToModel: Record<string, string>,
+) {
+  for (const [model, fields] of Object.entries(fieldToColumn)) {
+    const table = modelToTable[model];
+    if (!table) {
+      throw new Error(
+        `Mappings override mismatch: fieldToColumn references unknown model "${model}"`,
+      );
+    }
+    const reverseFields = columnToField[table];
+    if (!reverseFields) {
+      throw new Error(
+        `Mappings override mismatch: columnToField is missing table "${table}" for model "${model}"`,
+      );
+    }
+    for (const [field, column] of Object.entries(fields)) {
+      if (reverseFields[column] !== field) {
+        throw new Error(
+          `Mappings override mismatch: fieldToColumn.${model}.${field}="${column}" is not mirrored in columnToField.${table}`,
+        );
+      }
+    }
+  }
+
+  for (const [table, columns] of Object.entries(columnToField)) {
+    const model = tableToModel[table];
+    if (!model) {
+      throw new Error(
+        `Mappings override mismatch: columnToField references unknown table "${table}"`,
+      );
+    }
+    const forwardFields = fieldToColumn[model];
+    if (!forwardFields) {
+      throw new Error(
+        `Mappings override mismatch: fieldToColumn is missing model "${model}" for table "${table}"`,
+      );
+    }
+    for (const [column, field] of Object.entries(columns)) {
+      if (forwardFields[field] !== column) {
+        throw new Error(
+          `Mappings override mismatch: columnToField.${table}.${column}="${field}" is not mirrored in fieldToColumn.${model}`,
+        );
+      }
+    }
+  }
+}
+
+function mergeMappings(
+  defaults: ResolvedMappings,
+  existingMappings?: Partial<SqlMappings>,
+): ResolvedMappings {
+  const hasModelToTable = existingMappings?.modelToTable !== undefined;
+  const hasTableToModel = existingMappings?.tableToModel !== undefined;
+  if (hasModelToTable !== hasTableToModel) {
+    throw new Error(
+      'Mappings override mismatch: modelToTable and tableToModel must be provided together',
+    );
+  }
+
+  const hasFieldToColumn = existingMappings?.fieldToColumn !== undefined;
+  const hasColumnToField = existingMappings?.columnToField !== undefined;
+  if (hasFieldToColumn !== hasColumnToField) {
+    throw new Error(
+      'Mappings override mismatch: fieldToColumn and columnToField must be provided together',
+    );
+  }
+
+  const modelToTable: Record<string, string> = hasModelToTable
+    ? (existingMappings?.modelToTable ?? {})
+    : defaults.modelToTable;
+  const tableToModel: Record<string, string> = hasTableToModel
+    ? (existingMappings?.tableToModel ?? {})
+    : defaults.tableToModel;
+  assertInverseModelMappings(modelToTable, tableToModel);
+
+  const fieldToColumn: Record<string, Record<string, string>> = hasFieldToColumn
+    ? (existingMappings?.fieldToColumn ?? {})
+    : defaults.fieldToColumn;
+  const columnToField: Record<string, Record<string, string>> = hasColumnToField
+    ? (existingMappings?.columnToField ?? {})
+    : defaults.columnToField;
+  assertInverseFieldMappings(fieldToColumn, columnToField, modelToTable, tableToModel);
+
+  return {
+    modelToTable,
+    tableToModel,
+    fieldToColumn,
+    columnToField,
+    codecTypes: { ...defaults.codecTypes, ...(existingMappings?.codecTypes ?? {}) },
+    operationTypes: { ...defaults.operationTypes, ...(existingMappings?.operationTypes ?? {}) },
+  };
+}
+
+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 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})`,
+        );
+      }
+    }
+  }
+}
+
+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 existingMappings = (structurallyValid as { mappings?: Partial<SqlMappings> }).mappings;
+  const defaultMappings = computeDefaultMappings(
+    structurallyValid.models as Record<string, ModelDefinition>,
+  );
+  const mappings = mergeMappings(defaultMappings, existingMappings);
+
+  return {
+    ...structurallyValid,
+    mappings,
+  } as TContract;
+}