@prisma-next/config 0.0.1

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@prisma-next/config",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Prisma Next config authoring types and validation",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  },
+  "dependencies": {
+    "@prisma-next/contract": "workspace:*",
+    "@prisma-next/utils": "workspace:*",
+    "arktype": "^2.1.26"
+  },
+  "devDependencies": {
+    "@prisma-next/tsconfig": "workspace:*",
+    "@prisma-next/tsdown": "workspace:*",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    "./config-types": "./dist/config-types.mjs",
+    "./config-validation": "./dist/config-validation.mjs",
+    "./types": "./dist/types.mjs",
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/1-framework/1-core/shared/config"
+  }
+}

package/src/config-types.ts

@@ -0,0 +1,164 @@
+import { type } from 'arktype';
+import type { ContractSourceProvider } from './contract-source-types';
+import type {
+  ControlAdapterDescriptor,
+  ControlDriverDescriptor,
+  ControlDriverInstance,
+  ControlExtensionDescriptor,
+  ControlFamilyDescriptor,
+  ControlTargetDescriptor,
+} from './types';
+
+/**
+ * Type alias for CLI driver instances.
+ * Uses string for both family and target IDs for maximum flexibility.
+ */
+export type CliDriver = ControlDriverInstance<string, string>;
+
+/**
+ * Contract configuration specifying source and artifact locations.
+ */
+export interface ContractConfig {
+  /**
+   * Contract source provider. The provider is always async and must return
+   * a Result containing either ContractIR or structured diagnostics.
+   */
+  readonly source: ContractSourceProvider;
+  /**
+   * Path to contract.json artifact. Defaults to 'src/prisma/contract.json'.
+   * The .d.ts types file will be colocated (e.g., contract.json -> contract.d.ts).
+   */
+  readonly output?: string;
+}
+
+/**
+ * Configuration for Prisma Next CLI.
+ * Uses Control*Descriptor types for type-safe wiring with compile-time compatibility checks.
+ *
+ * @template TFamilyId - The family ID (e.g., 'sql', 'document')
+ * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
+ * @template TConnection - The driver connection input type (defaults to `unknown` for config flexibility)
+ */
+export interface PrismaNextConfig<
+  TFamilyId extends string = string,
+  TTargetId extends string = string,
+  TConnection = unknown,
+> {
+  readonly family: ControlFamilyDescriptor<TFamilyId>;
+  readonly target: ControlTargetDescriptor<TFamilyId, TTargetId>;
+  readonly adapter: ControlAdapterDescriptor<TFamilyId, TTargetId>;
+  readonly extensionPacks?: readonly ControlExtensionDescriptor<TFamilyId, TTargetId>[];
+  /**
+   * Driver descriptor for DB-connected CLI commands.
+   * Required for DB-connected commands (e.g., db verify).
+   * Optional for commands that don't need database access (e.g., emit).
+   * The driver's connection type matches the TConnection config parameter.
+   */
+  readonly driver?: ControlDriverDescriptor<
+    TFamilyId,
+    TTargetId,
+    ControlDriverInstance<TFamilyId, TTargetId>,
+    TConnection
+  >;
+  /**
+   * Database connection configuration.
+   * The connection type is driver-specific (e.g., URL string for Postgres).
+   */
+  readonly db?: {
+    /**
+     * Driver-specific connection input.
+     * For Postgres: a connection string (URL).
+     * For other drivers: may be a structured object.
+     */
+    readonly connection?: TConnection;
+  };
+  /**
+   * Contract configuration. Specifies source and artifact locations.
+   * Required for emit command; optional for other commands that only read artifacts.
+   */
+  readonly contract?: ContractConfig;
+  /**
+   * Migration configuration. Controls where on-disk migration packages are stored.
+   */
+  readonly migrations?: {
+    /** Directory for migration packages, relative to config file. Defaults to 'migrations'. */
+    readonly dir?: string;
+  };
+}
+
+/**
+ * Arktype schema for ContractConfig validation.
+ * Validates presence/shape only.
+ * contract.source is validated as a provider function at runtime in defineConfig().
+ */
+const ContractConfigSchema = type({
+  source: 'unknown', // Runtime check enforces provider function shape
+  'output?': 'string',
+});
+
+/**
+ * Arktype schema for PrismaNextConfig validation.
+ * Note: This validates structure only. Descriptor objects (family, target, adapter) are validated separately.
+ */
+const MigrationsConfigSchema = type({
+  'dir?': 'string',
+});
+
+const PrismaNextConfigSchema = type({
+  family: 'unknown', // ControlFamilyDescriptor - validated separately
+  target: 'unknown', // ControlTargetDescriptor - validated separately
+  adapter: 'unknown', // ControlAdapterDescriptor - validated separately
+  'extensionPacks?': 'unknown[]',
+  'driver?': 'unknown', // ControlDriverDescriptor - validated separately (optional)
+  'db?': 'unknown',
+  'contract?': ContractConfigSchema,
+  'migrations?': MigrationsConfigSchema,
+});
+
+/**
+ * Helper function to define a Prisma Next config.
+ * Validates and normalizes the config using Arktype, then returns the normalized IR.
+ *
+ * Normalization:
+ * - contract.output defaults to 'src/prisma/contract.json' if missing
+ *
+ * @param config - Raw config input from user
+ * @returns Normalized config IR with defaults applied
+ * @throws Error if config structure is invalid
+ */
+export function defineConfig<TFamilyId extends string = string, TTargetId extends string = string>(
+  config: PrismaNextConfig<TFamilyId, TTargetId>,
+): PrismaNextConfig<TFamilyId, TTargetId> {
+  // Validate structure using Arktype
+  const validated = PrismaNextConfigSchema(config);
+  if (validated instanceof type.errors) {
+    const messages = validated.map((p: { message: string }) => p.message).join('; ');
+    throw new Error(`Config validation failed: ${messages}`);
+  }
+
+  // Normalize contract config if present
+  if (config.contract) {
+    // Validate contract.source provider function shape at runtime.
+    const source = config.contract.source;
+    if (typeof source !== 'function') {
+      throw new Error('Config.contract.source must be a provider function');
+    }
+
+    // Apply defaults
+    const output = config.contract.output ?? 'src/prisma/contract.json';
+
+    const normalizedContract: ContractConfig = {
+      source: config.contract.source,
+      output,
+    };
+
+    // Return normalized config
+    return {
+      ...config,
+      contract: normalizedContract,
+    };
+  }
+
+  // Return config as-is if no contract (preserve literal types)
+  return config;
+}

package/src/config-validation.ts

@@ -0,0 +1,239 @@
+import type { PrismaNextConfig } from './config-types';
+import { ConfigValidationError } from './errors';
+
+function throwValidation(field: string, why?: string): never {
+  throw new ConfigValidationError(field, why);
+}
+
+/**
+ * Validates that the config has the required structure.
+ * This is pure validation logic with no file I/O or CLI awareness.
+ *
+ * @param config - Config object to validate
+ * @throws ConfigValidationError if config structure is invalid
+ */
+export function validateConfig(config: unknown): asserts config is PrismaNextConfig {
+  if (!config || typeof config !== 'object') {
+    throwValidation('object', 'Config must be an object');
+  }
+
+  const configObj = config as Record<string, unknown>;
+
+  if (!configObj['family']) {
+    throwValidation('family');
+  }
+
+  if (!configObj['target']) {
+    throwValidation('target');
+  }
+
+  if (!configObj['adapter']) {
+    throwValidation('adapter');
+  }
+
+  // Validate family descriptor
+  const family = configObj['family'] as Record<string, unknown>;
+  if (family['kind'] !== 'family') {
+    throwValidation('family.kind', 'Config.family must have kind: "family"');
+  }
+  if (typeof family['id'] !== 'string') {
+    throwValidation('family.id', 'Config.family must have id: string');
+  }
+  if (typeof family['familyId'] !== 'string') {
+    throwValidation('family.familyId', 'Config.family must have familyId: string');
+  }
+  if (typeof family['version'] !== 'string') {
+    throwValidation('family.version', 'Config.family must have version: string');
+  }
+  if (!family['hook'] || typeof family['hook'] !== 'object') {
+    throwValidation('family.hook', 'Config.family must have hook: TargetFamilyHook');
+  }
+  if (typeof family['create'] !== 'function') {
+    throwValidation('family.create', 'Config.family must have create: function');
+  }
+
+  const familyId = family['familyId'] as string;
+
+  // Validate target descriptor
+  const target = configObj['target'] as Record<string, unknown>;
+  if (target['kind'] !== 'target') {
+    throwValidation('target.kind', 'Config.target must have kind: "target"');
+  }
+  if (typeof target['id'] !== 'string') {
+    throwValidation('target.id', 'Config.target must have id: string');
+  }
+  if (typeof target['familyId'] !== 'string') {
+    throwValidation('target.familyId', 'Config.target must have familyId: string');
+  }
+  if (typeof target['version'] !== 'string') {
+    throwValidation('target.version', 'Config.target must have version: string');
+  }
+  if (target['familyId'] !== familyId) {
+    throwValidation(
+      'target.familyId',
+      `Config.target.familyId must match Config.family.familyId (expected: ${familyId}, got: ${target['familyId']})`,
+    );
+  }
+  if (typeof target['targetId'] !== 'string') {
+    throwValidation('target.targetId', 'Config.target must have targetId: string');
+  }
+  if (typeof target['create'] !== 'function') {
+    throwValidation('target.create', 'Config.target must have create: function');
+  }
+  const expectedTargetId = target['targetId'] as string;
+
+  // Validate adapter descriptor
+  const adapter = configObj['adapter'] as Record<string, unknown>;
+  if (adapter['kind'] !== 'adapter') {
+    throwValidation('adapter.kind', 'Config.adapter must have kind: "adapter"');
+  }
+  if (typeof adapter['id'] !== 'string') {
+    throwValidation('adapter.id', 'Config.adapter must have id: string');
+  }
+  if (typeof adapter['familyId'] !== 'string') {
+    throwValidation('adapter.familyId', 'Config.adapter must have familyId: string');
+  }
+  if (typeof adapter['version'] !== 'string') {
+    throwValidation('adapter.version', 'Config.adapter must have version: string');
+  }
+  if (adapter['familyId'] !== familyId) {
+    throwValidation(
+      'adapter.familyId',
+      `Config.adapter.familyId must match Config.family.familyId (expected: ${familyId}, got: ${adapter['familyId']})`,
+    );
+  }
+  if (typeof adapter['targetId'] !== 'string') {
+    throwValidation('adapter.targetId', 'Config.adapter must have targetId: string');
+  }
+  if (adapter['targetId'] !== expectedTargetId) {
+    throwValidation(
+      'adapter.targetId',
+      `Config.adapter.targetId must match Config.target.targetId (expected: ${expectedTargetId}, got: ${adapter['targetId']})`,
+    );
+  }
+  if (typeof adapter['create'] !== 'function') {
+    throwValidation('adapter.create', 'Config.adapter must have create: function');
+  }
+
+  if (configObj['extensions'] !== undefined) {
+    throwValidation('extensions', 'Config.extensions is not supported; use Config.extensionPacks');
+  }
+
+  // Validate extensionPacks array if present
+  if (configObj['extensionPacks'] !== undefined) {
+    if (!Array.isArray(configObj['extensionPacks'])) {
+      throwValidation('extensionPacks', 'Config.extensionPacks must be an array');
+    }
+    for (const ext of configObj['extensionPacks']) {
+      if (!ext || typeof ext !== 'object') {
+        throwValidation(
+          'extensionPacks[]',
+          'Config.extensionPacks must contain ControlExtensionDescriptor objects',
+        );
+      }
+      const extObj = ext as Record<string, unknown>;
+      if (extObj['kind'] !== 'extension') {
+        throwValidation(
+          'extensionPacks[].kind',
+          'Config.extensionPacks items must have kind: "extension"',
+        );
+      }
+      if (typeof extObj['id'] !== 'string') {
+        throwValidation('extensionPacks[].id', 'Config.extensionPacks items must have id: string');
+      }
+      if (typeof extObj['familyId'] !== 'string') {
+        throwValidation(
+          'extensionPacks[].familyId',
+          'Config.extensionPacks items must have familyId: string',
+        );
+      }
+      if (typeof extObj['version'] !== 'string') {
+        throwValidation(
+          'extensionPacks[].version',
+          'Config.extensionPacks items must have version: string',
+        );
+      }
+      if (extObj['familyId'] !== familyId) {
+        throwValidation(
+          'extensionPacks[].familyId',
+          `Config.extensionPacks[].familyId must match Config.family.familyId (expected: ${familyId}, got: ${extObj['familyId']})`,
+        );
+      }
+      if (typeof extObj['targetId'] !== 'string') {
+        throwValidation(
+          'extensionPacks[].targetId',
+          'Config.extensionPacks items must have targetId: string',
+        );
+      }
+      if (extObj['targetId'] !== expectedTargetId) {
+        throwValidation(
+          'extensionPacks[].targetId',
+          `Config.extensionPacks[].targetId must match Config.target.targetId (expected: ${expectedTargetId}, got: ${extObj['targetId']})`,
+        );
+      }
+      if (typeof extObj['create'] !== 'function') {
+        throwValidation(
+          'extensionPacks[].create',
+          'Config.extensionPacks items must have create: function',
+        );
+      }
+    }
+  }
+
+  // Validate driver descriptor if present
+  if (configObj['driver'] !== undefined) {
+    const driver = configObj['driver'] as Record<string, unknown>;
+    if (driver['kind'] !== 'driver') {
+      throwValidation('driver.kind', 'Config.driver must have kind: "driver"');
+    }
+    if (typeof driver['id'] !== 'string') {
+      throwValidation('driver.id', 'Config.driver must have id: string');
+    }
+    if (typeof driver['version'] !== 'string') {
+      throwValidation('driver.version', 'Config.driver must have version: string');
+    }
+    if (typeof driver['familyId'] !== 'string') {
+      throwValidation('driver.familyId', 'Config.driver must have familyId: string');
+    }
+    if (driver['familyId'] !== familyId) {
+      throwValidation(
+        'driver.familyId',
+        `Config.driver.familyId must match Config.family.familyId (expected: ${familyId}, got: ${driver['familyId']})`,
+      );
+    }
+    if (typeof driver['targetId'] !== 'string') {
+      throwValidation('driver.targetId', 'Config.driver must have targetId: string');
+    }
+    if (driver['targetId'] !== expectedTargetId) {
+      throwValidation(
+        'driver.targetId',
+        `Config.driver.targetId must match Config.target.targetId (expected: ${expectedTargetId}, got: ${driver['targetId']})`,
+      );
+    }
+    if (typeof driver['create'] !== 'function') {
+      throwValidation('driver.create', 'Config.driver must have create: function');
+    }
+  }
+
+  // Validate contract config if present (structure validation - defineConfig() handles normalization)
+  if (configObj['contract'] !== undefined) {
+    const contract = configObj['contract'] as Record<string, unknown>;
+    if (!contract || typeof contract !== 'object') {
+      throwValidation('contract', 'Config.contract must be an object');
+    }
+    if (!Object.hasOwn(contract, 'source')) {
+      throwValidation(
+        'contract.source',
+        'Config.contract.source is required when contract is provided',
+      );
+    }
+
+    if (typeof contract['source'] !== 'function') {
+      throwValidation('contract.source', 'Config.contract.source must be a provider function');
+    }
+
+    if (contract['output'] !== undefined && typeof contract['output'] !== 'string') {
+      throwValidation('contract.output', 'Config.contract.output must be a string when provided');
+    }
+  }
+}

package/src/contract-source-types.ts

@@ -0,0 +1,28 @@
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type { Result } from '@prisma-next/utils/result';
+
+export interface ContractSourceDiagnosticPosition {
+  readonly offset: number;
+  readonly line: number;
+  readonly column: number;
+}
+
+export interface ContractSourceDiagnosticSpan {
+  readonly start: ContractSourceDiagnosticPosition;
+  readonly end: ContractSourceDiagnosticPosition;
+}
+
+export interface ContractSourceDiagnostic {
+  readonly code: string;
+  readonly message: string;
+  readonly sourceId?: string;
+  readonly span?: ContractSourceDiagnosticSpan;
+}
+
+export interface ContractSourceDiagnostics {
+  readonly summary: string;
+  readonly diagnostics: readonly ContractSourceDiagnostic[];
+  readonly meta?: Record<string, unknown>;
+}
+
+export type ContractSourceProvider = () => Promise<Result<ContractIR, ContractSourceDiagnostics>>;

package/src/errors.ts

@@ -0,0 +1,11 @@
+export class ConfigValidationError extends Error {
+  readonly field: string;
+  readonly why: string;
+
+  constructor(field: string, why?: string) {
+    super(why ?? `Config must have a "${field}" field`);
+    this.name = 'ConfigValidationError';
+    this.field = field;
+    this.why = why ?? `Config must have a "${field}" field`;
+  }
+}

package/src/exports/config-types.ts

@@ -0,0 +1,9 @@
+export type { ContractConfig, PrismaNextConfig } from '../config-types';
+export { defineConfig } from '../config-types';
+export type {
+  ContractSourceDiagnostic,
+  ContractSourceDiagnosticPosition,
+  ContractSourceDiagnosticSpan,
+  ContractSourceDiagnostics,
+  ContractSourceProvider,
+} from '../contract-source-types';

package/src/exports/config-validation.ts

@@ -0,0 +1,2 @@
+export { validateConfig } from '../config-validation';
+export { ConfigValidationError } from '../errors';

package/src/exports/types.ts

@@ -0,0 +1,13 @@
+export type {
+  ControlAdapterDescriptor,
+  ControlAdapterInstance,
+  ControlDriverDescriptor,
+  ControlDriverInstance,
+  ControlExtensionDescriptor,
+  ControlExtensionInstance,
+  ControlFamilyDescriptor,
+  ControlFamilyInstance,
+  ControlPlaneStack,
+  ControlTargetDescriptor,
+  ControlTargetInstance,
+} from '../types';