@prisma-next/sql-contract-ts 0.3.0-dev.135 → 0.3.0-dev.146

package/src/contract.ts

@@ -1,475 +0,0 @@
-import type {
-  PrimaryKey,
-  SqlContract,
-  SqlStorage,
-  StorageTypeInstance,
-  UniqueConstraint,
-} from '@prisma-next/sql-contract/types';
-import { decodeContractDefaults } from '@prisma-next/sql-contract/validate';
-import {
-  ColumnDefaultSchema,
-  ForeignKeySchema,
-  IndexSchema,
-  validateStorageSemantics,
-} from '@prisma-next/sql-contract/validators';
-import { type } from 'arktype';
-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({
-  nativeType: 'string',
-  codecId: 'string',
-  nullable: 'boolean',
-  'typeParams?': 'Record<string, unknown>',
-  'typeRef?': 'string',
-  'default?': ColumnDefaultSchema,
-});
-
-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 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({
-  'nullable?': 'boolean',
-  'codecId?': 'string',
-});
-
-const ModelStorageFieldSchema = type({
-  column: 'string',
-});
-
-const ModelStorageSchema = type({
-  table: 'string',
-  'fields?': type({ '[string]': ModelStorageFieldSchema }),
-});
-
-const ModelSchema = type({
-  storage: ModelStorageSchema,
-  fields: type({ '[string]': ModelFieldSchema }),
-  relations: type({ '[string]': 'unknown' }),
-  'owner?': 'string',
-});
-
-const GeneratorIdSchema = type('string').narrow((value, ctx) => {
-  return /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value) ? true : ctx.mustBe('a flat generator id');
-});
-
-const ExecutionMutationDefaultValueSchema = type({
-  kind: "'generator'",
-  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(),
-  },
-});
-
-/**
- * Complete SqlContract schema for structural validation.
- * This validates the entire contract structure at once.
- */
-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>',
-  'roots?': 'Record<string, string>',
-  models: type({ '[string]': ModelSchema }),
-  storage: StorageSchema,
-  'execution?': ExecutionSchema,
-});
-
-/**
- * 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
- */
-function validateContractStructure<T extends SqlContract<SqlStorage>>(
-  value: unknown,
-): O.Overwrite<T, { targetFamily: 'sql' }> {
-  // 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') {
-    /* c8 ignore next */
-    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 O.Overwrite<T, { targetFamily: 'sql' }>;
-}
-
-/**
- * Validates logical consistency of a **structurally validated** SqlContract.
- * 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));
-
-  // Validate storage.types if present
-  if (storage.types) {
-    for (const [typeName, typeInstance] of Object.entries(storage.types)) {
-      // Validate typeParams is not an array (arrays are objects in JS but not valid here)
-      if (Array.isArray(typeInstance.typeParams)) {
-        throw new Error(
-          `Type instance "${typeName}" has invalid typeParams: must be a plain object, not an array`,
-        );
-      }
-    }
-  }
-
-  // Validate columns in all tables
-  for (const [tableName, table] of Object.entries(storage.tables)) {
-    for (const [columnName, column] of Object.entries(table.columns)) {
-      // Validate typeParams and typeRef are mutually exclusive
-      if (column.typeParams !== undefined && column.typeRef !== undefined) {
-        throw new Error(
-          `Column "${columnName}" in table "${tableName}" has both typeParams and typeRef; these are mutually exclusive`,
-        );
-      }
-
-      // Validate typeParams is not an array (arrays are objects in JS but not valid here)
-      if (column.typeParams !== undefined && Array.isArray(column.typeParams)) {
-        throw new Error(
-          `Column "${columnName}" in table "${tableName}" has invalid typeParams: must be a plain object, not an array`,
-        );
-      }
-
-      // Validate NOT NULL columns do not have literal null defaults
-      if (!column.nullable && column.default?.kind === 'literal' && column.default.value === null) {
-        throw new Error(
-          `Table "${tableName}" column "${columnName}" is NOT NULL but has a literal null default`,
-        );
-      }
-
-      // 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}"`,
-          );
-        }
-      }
-    }
-  }
-
-  for (const [modelName, modelUnknown] of Object.entries(models)) {
-    const model = modelUnknown as {
-      storage?: { table?: string; fields?: Record<string, { column?: string }> };
-      fields?: Record<string, unknown>;
-      relations?: Record<string, unknown>;
-    };
-    if (!model.storage?.table) {
-      /* c8 ignore next */
-      throw new Error(`Model "${modelName}" is missing storage.table`);
-    }
-
-    const tableName = model.storage.table;
-
-    if (!tableNames.has(tableName)) {
-      /* c8 ignore next */
-      throw new Error(`Model "${modelName}" references non-existent table "${tableName}"`);
-    }
-
-    const table = storage.tables[tableName];
-    if (!table) {
-      /* c8 ignore next */
-      throw new Error(`Model "${modelName}" references non-existent table "${tableName}"`);
-    }
-
-    if (!table.primaryKey) {
-      /* c8 ignore next */
-      throw new Error(`Model "${modelName}" table "${tableName}" is missing a primary key`);
-    }
-
-    const columnNames = new Set(Object.keys(table.columns));
-
-    const storageFields = model.storage.fields;
-    if (storageFields) {
-      for (const [fieldName, storageField] of Object.entries(storageFields)) {
-        if (!storageField.column) {
-          /* c8 ignore next */
-          throw new Error(`Model "${modelName}" field "${fieldName}" is missing column property`);
-        }
-
-        if (!columnNames.has(storageField.column)) {
-          /* c8 ignore next */
-          throw new Error(
-            `Model "${modelName}" field "${fieldName}" references non-existent column "${storageField.column}" in table "${tableName}"`,
-          );
-        }
-      }
-    }
-
-    if (model.relations) {
-      for (const [relationName, relation] of Object.entries(model.relations)) {
-        if (
-          typeof relation === 'object' &&
-          relation !== null &&
-          'on' in relation &&
-          'to' in relation
-        ) {
-          const on = relation.on as { localFields?: string[]; targetFields?: string[] };
-          const cardinality = (relation as { cardinality?: string }).cardinality;
-          const localFields = on.localFields;
-          const targetFields = on.targetFields;
-          if (!localFields || !targetFields) {
-            throw new Error(
-              `Model "${modelName}" relation "${relationName}" uses unsupported relation format (expected localFields/targetFields)`,
-            );
-          }
-          if (cardinality === '1:N') {
-            continue;
-          }
-
-          const hasMatchingFk = table.foreignKeys?.some((fk) => {
-            return (
-              fk.columns.length === localFields.length &&
-              fk.columns.every((col, i) => col === localFields[i]) &&
-              fk.references.table &&
-              fk.references.columns.length === targetFields.length &&
-              fk.references.columns.every((col, i) => col === targetFields[i])
-            );
-          });
-
-          if (!hasMatchingFk) {
-            /* c8 ignore next */
-            throw new Error(
-              `Model "${modelName}" relation "${relationName}" does not have a corresponding foreign key in table "${tableName}"`,
-            );
-          }
-        }
-      }
-    }
-  }
-
-  for (const [tableName, table] of Object.entries(storage.tables)) {
-    const columnNames = new Set(Object.keys(table.columns));
-
-    // Validate primaryKey references existing columns
-    if (table.primaryKey) {
-      for (const colName of table.primaryKey.columns) {
-        if (!columnNames.has(colName)) {
-          /* c8 ignore next */
-          throw new Error(
-            `Table "${tableName}" primaryKey references non-existent column "${colName}"`,
-          );
-        }
-      }
-    }
-
-    // Validate unique constraints reference existing columns
-    for (const unique of table.uniques) {
-      for (const colName of unique.columns) {
-        if (!columnNames.has(colName)) {
-          /* c8 ignore next */
-          throw new Error(
-            `Table "${tableName}" unique constraint references non-existent column "${colName}"`,
-          );
-        }
-      }
-    }
-
-    // Validate indexes reference existing columns
-    for (const index of table.indexes) {
-      for (const colName of index.columns) {
-        if (!columnNames.has(colName)) {
-          /* c8 ignore next */
-          throw new Error(`Table "${tableName}" index references non-existent column "${colName}"`);
-        }
-      }
-    }
-
-    // Validate foreignKeys reference existing tables and columns
-    for (const fk of table.foreignKeys) {
-      // Validate FK columns exist in the referencing table
-      for (const colName of fk.columns) {
-        if (!columnNames.has(colName)) {
-          /* c8 ignore next */
-          throw new Error(
-            `Table "${tableName}" foreignKey references non-existent column "${colName}"`,
-          );
-        }
-      }
-
-      // Validate referenced table exists
-      if (!tableNames.has(fk.references.table)) {
-        /* c8 ignore next */
-        throw new Error(
-          `Table "${tableName}" foreignKey references non-existent table "${fk.references.table}"`,
-        );
-      }
-
-      // Validate referenced columns exist in the referenced table
-      const referencedTable = storage.tables[fk.references.table];
-      if (!referencedTable) {
-        /* c8 ignore next */
-        throw new Error(
-          `Table "${tableName}" foreignKey references non-existent table "${fk.references.table}"`,
-        );
-      }
-      const referencedColumnNames = new Set(Object.keys(referencedTable.columns));
-
-      for (const colName of fk.references.columns) {
-        if (!referencedColumnNames.has(colName)) {
-          /* c8 ignore next */
-          throw new Error(
-            `Table "${tableName}" foreignKey references non-existent column "${colName}" in table "${fk.references.table}"`,
-          );
-        }
-      }
-
-      if (fk.columns.length !== fk.references.columns.length) {
-        /* c8 ignore next */
-        throw new Error(
-          `Table "${tableName}" foreignKey column count (${fk.columns.length}) does not match referenced column count (${fk.references.columns.length})`,
-        );
-      }
-    }
-  }
-}
-
-import { normalizeContract } from '@prisma-next/sql-contract/validate';
-export { normalizeContract };
-
-/**
- * Validates that a JSON import conforms to the SqlContract structure
- * and returns a fully typed SqlContract.
- *
- * This function is specifically for validating JSON imports (e.g., from contract.json).
- * Contracts created via the builder API (defineContract) are already valid and should
- * not be passed to this function - use them directly without validation.
- *
- * Performs both structural validation (using Arktype) and logical validation
- * (ensuring all references are valid).
- *
- *
- * The type parameter `TContract` must be a fully-typed contract type (e.g., from `contract.d.ts`),
- * NOT a generic `SqlContract<SqlStorage>`.
- *
- * **Correct:**
- * ```typescript
- * import type { Contract } from './contract.d';
- * const contract = validateContract<Contract>(contractJson);
- * ```
- *
- * **Incorrect:**
- * ```typescript
- * import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
- * const contract = validateContract<SqlContract<SqlStorage>>(contractJson);
- * // ❌ Types will be inferred as 'unknown' - this won't work!
- * ```
- *
- * The type parameter provides the specific table structure, column types, and model definitions.
- * This function validates the runtime structure matches the type, but does not infer types
- * from JSON (as JSON imports lose literal type information).
- *
- * @param value - The contract value to validate (must be from a JSON import, not a builder)
- * @returns A validated contract matching the TContract type
- * @throws Error if the contract structure or logic is invalid
- */
-export function validateContract<TContract extends SqlContract<SqlStorage>>(
-  value: unknown,
-): TContract {
-  // Normalize contract first (add defaults for missing fields)
-  const normalized = normalizeContract(value);
-
-  const structurallyValid = validateContractStructure<SqlContract<SqlStorage>>(normalized);
-
-  const contractForValidation = structurallyValid as SqlContract<SqlStorage>;
-
-  validateContractLogic(contractForValidation);
-
-  const semanticErrors = validateStorageSemantics(contractForValidation.storage);
-  if (semanticErrors.length > 0) {
-    throw new Error(`Contract semantic validation failed: ${semanticErrors.join('; ')}`);
-  }
-
-  return decodeContractDefaults(contractForValidation) as TContract;
-}