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

package/src/validate.ts

@@ -0,0 +1,443 @@
+import type { ColumnDefaultLiteralInputValue } from '@prisma-next/contract/types';
+import { isTaggedBigInt, isTaggedRaw } from '@prisma-next/contract/types';
+import type {
+  ModelDefinition,
+  SqlContract,
+  SqlMappings,
+  SqlStorage,
+  StorageColumn,
+  StorageTable,
+} 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 [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 existingMappings = (structurallyValid as { mappings?: Partial<SqlMappings> }).mappings;
+  const defaultMappings = computeDefaultMappings(
+    structurallyValid.models as Record<string, ModelDefinition>,
+  );
+  const mappings = mergeMappings(defaultMappings, existingMappings);
+
+  const contractWithMappings = {
+    ...structurallyValid,
+    mappings,
+  };
+
+  return decodeContractDefaults(contractWithMappings) as TContract;
+}

package/src/validators.ts

@@ -0,0 +1,227 @@
+import { type } from 'arktype';
+import type {
+  ForeignKey,
+  ForeignKeyReferences,
+  Index,
+  ModelDefinition,
+  ModelField,
+  ModelStorage,
+  PrimaryKey,
+  SqlContract,
+  SqlStorage,
+  StorageTypeInstance,
+  UniqueConstraint,
+} from './types';
+
+type ColumnDefaultLiteral = {
+  readonly kind: 'literal';
+  readonly value: string | number | boolean | Record<string, unknown> | unknown[] | null;
+};
+type ColumnDefaultFunction = { readonly kind: 'function'; readonly expression: string };
+const literalKindSchema = type("'literal'");
+const functionKindSchema = type("'function'");
+const generatorKindSchema = type("'generator'");
+const generatorIdSchema = type("'ulid' | 'nanoid' | 'uuidv7' | 'uuidv4' | 'cuid2' | 'ksuid'");
+
+export const ColumnDefaultLiteralSchema = type.declare<ColumnDefaultLiteral>().type({
+  kind: literalKindSchema,
+  value: 'string | number | boolean | null | unknown[] | Record<string, unknown>',
+});
+
+export const ColumnDefaultFunctionSchema = type.declare<ColumnDefaultFunction>().type({
+  kind: functionKindSchema,
+  expression: 'string',
+});
+
+export const ColumnDefaultSchema = ColumnDefaultLiteralSchema.or(ColumnDefaultFunctionSchema);
+
+const ExecutionMutationDefaultValueSchema = type({
+  kind: generatorKindSchema,
+  id: generatorIdSchema,
+  'params?': 'Record<string, unknown>',
+});
+
+const ExecutionMutationDefaultSchema = type({
+  ref: {
+    table: 'string',
+    column: 'string',
+  },
+  'onCreate?': ExecutionMutationDefaultValueSchema,
+  'onUpdate?': ExecutionMutationDefaultValueSchema,
+});
+
+const ExecutionSchema = type({
+  mutations: {
+    defaults: ExecutionMutationDefaultSchema.array().readonly(),
+  },
+});
+
+const StorageColumnSchema = type({
+  nativeType: 'string',
+  codecId: 'string',
+  nullable: 'boolean',
+  'typeParams?': 'Record<string, unknown>',
+  'typeRef?': 'string',
+  'default?': ColumnDefaultSchema,
+}).narrow((col, ctx) => {
+  if (col.typeParams !== undefined && col.typeRef !== undefined) {
+    return ctx.mustBe('a column with either typeParams or typeRef, not both');
+  }
+  return true;
+});
+
+const StorageTypeInstanceSchema = type.declare<StorageTypeInstance>().type({
+  codecId: 'string',
+  nativeType: 'string',
+  typeParams: 'Record<string, unknown>',
+});
+
+const PrimaryKeySchema = type.declare<PrimaryKey>().type({
+  columns: type.string.array().readonly(),
+  'name?': 'string',
+});
+
+const UniqueConstraintSchema = type.declare<UniqueConstraint>().type({
+  columns: type.string.array().readonly(),
+  'name?': 'string',
+});
+
+const IndexSchema = type.declare<Index>().type({
+  columns: type.string.array().readonly(),
+  'name?': 'string',
+});
+
+const ForeignKeyReferencesSchema = type.declare<ForeignKeyReferences>().type({
+  table: 'string',
+  columns: type.string.array().readonly(),
+});
+
+const ForeignKeySchema = type.declare<ForeignKey>().type({
+  columns: type.string.array().readonly(),
+  references: ForeignKeyReferencesSchema,
+  'name?': 'string',
+  constraint: 'boolean',
+  index: 'boolean',
+});
+
+const StorageTableSchema = type({
+  columns: type({ '[string]': StorageColumnSchema }),
+  'primaryKey?': PrimaryKeySchema,
+  uniques: UniqueConstraintSchema.array().readonly(),
+  indexes: IndexSchema.array().readonly(),
+  foreignKeys: ForeignKeySchema.array().readonly(),
+});
+
+const StorageSchema = type({
+  tables: type({ '[string]': StorageTableSchema }),
+  'types?': type({ '[string]': StorageTypeInstanceSchema }),
+});
+
+const ModelFieldSchema = type.declare<ModelField>().type({
+  column: 'string',
+});
+
+const ModelStorageSchema = type.declare<ModelStorage>().type({
+  table: 'string',
+});
+
+const ModelSchema = type.declare<ModelDefinition>().type({
+  storage: ModelStorageSchema,
+  fields: type({ '[string]': ModelFieldSchema }),
+  relations: type({ '[string]': 'unknown' }),
+});
+
+const SqlContractSchema = type({
+  'schemaVersion?': "'1'",
+  target: 'string',
+  targetFamily: "'sql'",
+  storageHash: 'string',
+  'executionHash?': 'string',
+  'profileHash?': 'string',
+  'capabilities?': 'Record<string, Record<string, boolean>>',
+  'extensionPacks?': 'Record<string, unknown>',
+  'meta?': 'Record<string, unknown>',
+  'sources?': 'Record<string, unknown>',
+  models: type({ '[string]': ModelSchema }),
+  storage: StorageSchema,
+  'execution?': ExecutionSchema,
+});
+
+// NOTE: StorageColumnSchema, StorageTableSchema, and StorageSchema use bare type()
+// instead of type.declare<T>().type() because the ColumnDefault union's value field
+// includes bigint | Date (runtime-only types after decoding) which cannot be expressed
+// in Arktype's JSON validation DSL. The `as SqlStorage` cast in validateStorage() bridges
+// the gap between the JSON-safe Arktype output and the runtime TypeScript type.
+// See decodeContractDefaults() in validate.ts for the decoding step.
+
+/**
+ * Validates the structural shape of SqlStorage using Arktype.
+ *
+ * @param value - The storage value to validate
+ * @returns The validated storage if structure is valid
+ * @throws Error if the storage structure is invalid
+ */
+export function validateStorage(value: unknown): SqlStorage {
+  const result = StorageSchema(value);
+  if (result instanceof type.errors) {
+    const messages = result.map((p: { message: string }) => p.message).join('; ');
+    throw new Error(`Storage validation failed: ${messages}`);
+  }
+  return result as SqlStorage;
+}
+
+/**
+ * Validates the structural shape of ModelDefinition using Arktype.
+ *
+ * @param value - The model value to validate
+ * @returns The validated model if structure is valid
+ * @throws Error if the model structure is invalid
+ */
+export function validateModel(value: unknown): ModelDefinition {
+  const result = ModelSchema(value);
+  if (result instanceof type.errors) {
+    const messages = result.map((p: { message: string }) => p.message).join('; ');
+    throw new Error(`Model validation failed: ${messages}`);
+  }
+  return result;
+}
+
+/**
+ * Validates the structural shape of a SqlContract using Arktype.
+ *
+ * **Responsibility: Validation Only**
+ * This function validates that the contract has the correct structure and types.
+ * It does NOT normalize the contract - normalization must happen in the contract builder.
+ *
+ * The contract passed to this function must already be normalized (all required fields present).
+ * If normalization is needed, it should be done by the contract builder before calling this function.
+ *
+ * This ensures all required fields are present and have the correct types.
+ *
+ * @param value - The contract value to validate (typically from a JSON import)
+ * @returns The validated contract if structure is valid
+ * @throws Error if the contract structure is invalid
+ */
+export function validateSqlContract<T extends SqlContract<SqlStorage>>(value: unknown): T {
+  if (typeof value !== 'object' || value === null) {
+    throw new Error('Contract structural validation failed: value must be an object');
+  }
+
+  // Check targetFamily first to provide a clear error message for unsupported target families
+  const rawValue = value as { targetFamily?: string };
+  if (rawValue.targetFamily !== undefined && rawValue.targetFamily !== 'sql') {
+    throw new Error(`Unsupported target family: ${rawValue.targetFamily}`);
+  }
+
+  const contractResult = SqlContractSchema(value);
+
+  if (contractResult instanceof type.errors) {
+    const messages = contractResult.map((p: { message: string }) => p.message).join('; ');
+    throw new Error(`Contract structural validation failed: ${messages}`);
+  }
+
+  // After validation, contractResult matches the schema and preserves the input structure
+  // TypeScript needs an assertion here due to exactOptionalPropertyTypes differences
+  // between Arktype's inferred type and the generic T, but runtime-wise they're compatible
+  return contractResult as T;
+}