@prisma-next/contract-authoring 0.3.0-dev.3 → 0.3.0-dev.30

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+import type { ColumnBuilderState, ModelBuilderState, RelationDefinition, TableBuilderState } from './builder-state';
+export type BuildStorageColumn<Nullable extends boolean, Type extends string> = {
+    readonly nativeType: string;
+    readonly codecId: Type;
+    readonly nullable: Nullable;
+};
+export type ExtractColumns<T extends TableBuilderState<string, Record<string, ColumnBuilderState<string, boolean, string>>, readonly string[] | undefined>> = T extends TableBuilderState<string, infer C, readonly string[] | undefined> ? C : never;
+export type ExtractPrimaryKey<T extends TableBuilderState<string, Record<string, ColumnBuilderState<string, boolean, string>>, readonly string[] | undefined>> = T extends TableBuilderState<string, Record<string, ColumnBuilderState<string, boolean, string>>, infer PK> ? PK : never;
+export type BuildStorage<Tables extends Record<string, TableBuilderState<string, Record<string, ColumnBuilderState<string, boolean, string>>, readonly string[] | undefined>>> = {
+    readonly tables: {
+        readonly [K in keyof Tables]: {
+            readonly columns: {
+                readonly [ColK in keyof ExtractColumns<Tables[K]>]: ExtractColumns<Tables[K]>[ColK] extends ColumnBuilderState<string, infer Null, infer TType> ? BuildStorageColumn<Null & boolean, TType> : never;
+            };
+        };
+    };
+};
+export type BuildStorageTables<Tables extends Record<string, TableBuilderState<string, Record<string, ColumnBuilderState<string, boolean, string>>, readonly string[] | undefined>>> = {
+    readonly [K in keyof Tables]: {
+        readonly columns: {
+            readonly [ColK in keyof ExtractColumns<Tables[K]>]: ExtractColumns<Tables[K]>[ColK] extends ColumnBuilderState<string, infer Null, infer TType> ? BuildStorageColumn<Null & boolean, TType> : never;
+        };
+    };
+};
+export type Mutable<T> = {
+    -readonly [K in keyof T]-?: T[K];
+};
+export type BuildModelFields<Fields extends Record<string, string>> = {
+    readonly [K in keyof Fields]: {
+        readonly column: Fields[K];
+    };
+};
+export type ExtractModelFields<T extends ModelBuilderState<string, string, Record<string, string>, Record<string, RelationDefinition>>> = T extends ModelBuilderState<string, string, infer F, Record<string, RelationDefinition>> ? F : never;
+export type ExtractModelRelations<T extends ModelBuilderState<string, string, Record<string, string>, Record<string, RelationDefinition>>> = T extends ModelBuilderState<string, string, Record<string, string>, infer R> ? R : never;
+export type BuildModels<Models extends Record<string, ModelBuilderState<string, string, Record<string, string>, Record<string, RelationDefinition>>>> = {
+    readonly [K in keyof Models]: {
+        readonly storage: {
+            readonly table: Models[K]['table'];
+        };
+        readonly fields: BuildModelFields<ExtractModelFields<Models[K]>>;
+    };
+};
+export type BuildRelations<Models extends Record<string, ModelBuilderState<string, string, Record<string, string>, Record<string, RelationDefinition>>>> = {
+    readonly [K in keyof Models as Models[K]['table']]: ExtractModelRelations<Models[K]>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,kBAAkB,CAAC,QAAQ,SAAS,OAAO,EAAE,IAAI,SAAS,MAAM,IAAI;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,cAAc,CACxB,CAAC,SAAS,iBAAiB,CACzB,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,EAC3D,SAAS,MAAM,EAAE,GAAG,SAAS,CAC9B,IACC,CAAC,SAAS,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5F,MAAM,MAAM,iBAAiB,CAC3B,CAAC,SAAS,iBAAiB,CACzB,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,EAC3D,SAAS,MAAM,EAAE,GAAG,SAAS,CAC9B,IAED,CAAC,SAAS,iBAAiB,CACzB,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,EAC3D,MAAM,EAAE,CACT,GACG,EAAE,GACF,KAAK,CAAC;AAEZ,MAAM,MAAM,YAAY,CACtB,MAAM,SAAS,MAAM,CACnB,MAAM,EACN,iBAAiB,CACf,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,EAC3D,SAAS,MAAM,EAAE,GAAG,SAAS,CAC9B,CACF,IACC;IACF,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,EAAE,CAAC,IAAI,MAAM,MAAM,GAAG;YAC5B,QAAQ,CAAC,OAAO,EAAE;gBAChB,QAAQ,EAAE,IAAI,IAAI,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAChE,MAAM,CAAC,CAAC,CAAC,CACV,CAAC,IAAI,CAAC,SAAS,kBAAkB,CAAC,MAAM,EAAE,MAAM,IAAI,EAAE,MAAM,KAAK,CAAC,GAC/D,kBAAkB,CAAC,IAAI,GAAG,OAAO,EAAE,KAAK,CAAC,GACzC,KAAK;aACV,CAAC;SACH;KACF,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAC5B,MAAM,SAAS,MAAM,CACnB,MAAM,EACN,iBAAiB,CACf,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,EAC3D,SAAS,MAAM,EAAE,GAAG,SAAS,CAC9B,CACF,IACC;IACF,QAAQ,EAAE,CAAC,IAAI,MAAM,MAAM,GAAG;QAC5B,QAAQ,CAAC,OAAO,EAAE;YAChB,QAAQ,EAAE,IAAI,IAAI,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAChE,MAAM,CAAC,CAAC,CAAC,CACV,CAAC,IAAI,CAAC,SAAS,kBAAkB,CAAC,MAAM,EAAE,MAAM,IAAI,EAAE,MAAM,KAAK,CAAC,GAC/D,kBAAkB,CAAC,IAAI,GAAG,OAAO,EAAE,KAAK,CAAC,GACzC,KAAK;SACV,CAAC;KACH;CACF,CAAC;AAEF,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI;IACvB,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI;IACpE,QAAQ,EAAE,CAAC,IAAI,MAAM,MAAM,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;KAAE;CAC7D,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAC5B,CAAC,SAAS,iBAAiB,CACzB,MAAM,EACN,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtB,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CACnC,IAED,CAAC,SAAS,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,GACpF,CAAC,GACD,KAAK,CAAC;AAEZ,MAAM,MAAM,qBAAqB,CAC/B,CAAC,SAAS,iBAAiB,CACzB,MAAM,EACN,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtB,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CACnC,IACC,CAAC,SAAS,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE7F,MAAM,MAAM,WAAW,CACrB,MAAM,SAAS,MAAM,CACnB,MAAM,EACN,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAC9F,IACC;IACF,QAAQ,EAAE,CAAC,IAAI,MAAM,MAAM,GAAG;QAC5B,QAAQ,CAAC,OAAO,EAAE;YAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;SAAE,CAAC;QACzD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAClE;CACF,CAAC;AAEF,MAAM,MAAM,cAAc,CACxB,MAAM,SAAS,MAAM,CACnB,MAAM,EACN,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAC9F,IACC;IACF,QAAQ,EAAE,CAAC,IAAI,MAAM,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;CACrF,CAAC"}

package/package.json

@@ -1,21 +1,22 @@
 {
   "name": "@prisma-next/contract-authoring",
-  "version": "0.3.0-dev.3",
+  "version": "0.3.0-dev.30",
   "type": "module",
   "sideEffects": false,
   "description": "Target-agnostic contract authoring builder core for Prisma Next",
   "dependencies": {
     "ts-toolbelt": "^9.6.0",
-    "@prisma-next/contract": "0.3.0-dev.3"
+    "@prisma-next/contract": "0.3.0-dev.30"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.0.0",
-    "tsup": "^8.3.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.0.16",
+    "@prisma-next/tsconfig": "0.0.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "exports": {
     ".": {
@@ -24,13 +25,13 @@
     }
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts",
+    "build": "tsup --config tsup.config.ts && tsc --project tsconfig.build.json",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --project tsconfig.json --noEmit",
-    "lint": "biome check . --config-path ../../../../biome.json --error-on-warnings",
-    "lint:fix": "biome check --write . --config-path ../../../../biome.json",
-    "lint:fix:unsafe": "biome check --write --unsafe . --config-path ../../../../biome.json",
-    "clean": "node ../../../../scripts/clean.mjs"
+    "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"
   }
 }

package/src/builder-state.ts

@@ -0,0 +1,137 @@
+/**
+ * Column type descriptor containing both codec ID and native type.
+ * Used when defining columns with descriptor objects instead of string IDs.
+ */
+export type ColumnTypeDescriptor = {
+  readonly codecId: string;
+  readonly nativeType: string;
+};
+
+export interface ColumnBuilderState<
+  Name extends string,
+  Nullable extends boolean,
+  Type extends string,
+> {
+  readonly name: Name;
+  readonly nullable: Nullable;
+  readonly type: Type;
+  readonly nativeType: string;
+}
+
+/**
+ * Unique constraint definition for table builder.
+ */
+export interface UniqueConstraintDef {
+  readonly columns: readonly string[];
+  readonly name?: string;
+}
+
+/**
+ * Index definition for table builder.
+ */
+export interface IndexDef {
+  readonly columns: readonly string[];
+  readonly name?: string;
+}
+
+/**
+ * Foreign key definition for table builder.
+ */
+export interface ForeignKeyDef {
+  readonly columns: readonly string[];
+  readonly references: {
+    readonly table: string;
+    readonly columns: readonly string[];
+  };
+  readonly name?: string;
+}
+
+export interface TableBuilderState<
+  Name extends string,
+  Columns extends Record<string, ColumnBuilderState<string, boolean, string>>,
+  PrimaryKey extends readonly string[] | undefined,
+> {
+  readonly name: Name;
+  readonly columns: Columns;
+  readonly primaryKey?: PrimaryKey;
+  readonly primaryKeyName?: string;
+  readonly uniques: readonly UniqueConstraintDef[];
+  readonly indexes: readonly IndexDef[];
+  readonly foreignKeys: readonly ForeignKeyDef[];
+}
+
+export type RelationDefinition = {
+  readonly to: string;
+  readonly cardinality: '1:1' | '1:N' | 'N:1' | 'N:M';
+  readonly on: {
+    readonly parentCols: readonly string[];
+    readonly childCols: readonly string[];
+  };
+  readonly through?: {
+    readonly table: string;
+    readonly parentCols: readonly string[];
+    readonly childCols: readonly string[];
+  };
+};
+
+export interface ModelBuilderState<
+  Name extends string,
+  Table extends string,
+  Fields extends Record<string, string>,
+  Relations extends Record<string, RelationDefinition>,
+> {
+  readonly name: Name;
+  readonly table: Table;
+  readonly fields: Fields;
+  readonly relations: Relations;
+}
+
+export interface ContractBuilderState<
+  Target extends string | undefined = string | undefined,
+  Tables extends Record<
+    string,
+    TableBuilderState<
+      string,
+      Record<string, ColumnBuilderState<string, boolean, string>>,
+      readonly string[] | undefined
+    >
+  > = Record<
+    never,
+    TableBuilderState<
+      string,
+      Record<string, ColumnBuilderState<string, boolean, string>>,
+      readonly string[] | undefined
+    >
+  >,
+  Models extends Record<
+    string,
+    ModelBuilderState<string, string, Record<string, string>, Record<string, RelationDefinition>>
+  > = Record<
+    never,
+    ModelBuilderState<string, string, Record<string, string>, Record<string, RelationDefinition>>
+  >,
+  CoreHash extends string | undefined = string | undefined,
+  ExtensionPacks extends Record<string, unknown> | undefined = undefined,
+  Capabilities extends Record<string, Record<string, boolean>> | undefined = undefined,
+> {
+  readonly target?: Target;
+  readonly tables: Tables;
+  readonly models: Models;
+  readonly coreHash?: CoreHash;
+  readonly extensionPacks?: ExtensionPacks;
+  readonly capabilities?: Capabilities;
+  /**
+   * Array of extension pack namespace identifiers (e.g., ['pgvector', 'postgis']).
+   * Populated when extension packs are registered during contract building.
+   * Used to track which extension packs are included in the contract.
+   * Can be undefined or empty if no extension packs are registered.
+   * Namespace format matches the extension pack ID (e.g., 'pgvector', not 'pgvector@1.0.0').
+   */
+  readonly extensionNamespaces?: readonly string[];
+}
+
+export interface ColumnBuilder<Name extends string, Nullable extends boolean, Type extends string> {
+  nullable<Value extends boolean>(value?: Value): ColumnBuilder<Name, Value, Type>;
+  type<Id extends string>(id: Id): ColumnBuilder<Name, Nullable, Id>;
+  build(): ColumnBuilderState<Name, Nullable, Type>;
+}

package/src/contract-builder.ts

@@ -0,0 +1,159 @@
+import type { TargetPackRef } from '@prisma-next/contract/framework-components';
+import type {
+  ColumnBuilderState,
+  ContractBuilderState,
+  ModelBuilderState,
+  RelationDefinition,
+  TableBuilderState,
+} from './builder-state';
+import { ModelBuilder } from './model-builder';
+import { createTable, TableBuilder } from './table-builder';
+
+export class ContractBuilder<
+  Target extends string | undefined = undefined,
+  Tables extends Record<
+    string,
+    TableBuilderState<
+      string,
+      Record<string, ColumnBuilderState<string, boolean, string>>,
+      readonly string[] | undefined
+    >
+  > = Record<never, never>,
+  Models extends Record<
+    string,
+    ModelBuilderState<string, string, Record<string, string>, Record<string, RelationDefinition>>
+  > = Record<never, never>,
+  CoreHash extends string | undefined = undefined,
+  ExtensionPacks extends Record<string, unknown> | undefined = undefined,
+  Capabilities extends Record<string, Record<string, boolean>> | undefined = undefined,
+> {
+  protected readonly state: ContractBuilderState<
+    Target,
+    Tables,
+    Models,
+    CoreHash,
+    ExtensionPacks,
+    Capabilities
+  >;
+
+  constructor(
+    state?: ContractBuilderState<Target, Tables, Models, CoreHash, ExtensionPacks, Capabilities>,
+  ) {
+    this.state =
+      state ??
+      ({
+        tables: {},
+        models: {},
+      } as ContractBuilderState<Target, Tables, Models, CoreHash, ExtensionPacks, Capabilities>);
+  }
+
+  target<T extends string>(
+    packRef: TargetPackRef<string, T>,
+  ): ContractBuilder<T, Tables, Models, CoreHash, ExtensionPacks, Capabilities> {
+    return new ContractBuilder<T, Tables, Models, CoreHash, ExtensionPacks, Capabilities>({
+      ...this.state,
+      target: packRef.targetId,
+    });
+  }
+
+  capabilities<C extends Record<string, Record<string, boolean>>>(
+    capabilities: C,
+  ): ContractBuilder<Target, Tables, Models, CoreHash, ExtensionPacks, C> {
+    return new ContractBuilder<Target, Tables, Models, CoreHash, ExtensionPacks, C>({
+      ...this.state,
+      capabilities,
+    });
+  }
+
+  table<
+    TableName extends string,
+    T extends TableBuilder<
+      TableName,
+      Record<string, ColumnBuilderState<string, boolean, string>>,
+      readonly string[] | undefined
+    >,
+  >(
+    name: TableName,
+    callback: (t: TableBuilder<TableName>) => T | undefined,
+  ): ContractBuilder<
+    Target,
+    Tables & Record<TableName, ReturnType<T['build']>>,
+    Models,
+    CoreHash,
+    ExtensionPacks,
+    Capabilities
+  > {
+    const tableBuilder = createTable(name);
+    const result = callback(tableBuilder);
+    const finalBuilder = result instanceof TableBuilder ? result : tableBuilder;
+    const tableState = finalBuilder.build();
+
+    return new ContractBuilder<
+      Target,
+      Tables & Record<TableName, ReturnType<T['build']>>,
+      Models,
+      CoreHash,
+      ExtensionPacks,
+      Capabilities
+    >({
+      ...this.state,
+      tables: { ...this.state.tables, [name]: tableState } as Tables &
+        Record<TableName, ReturnType<T['build']>>,
+    });
+  }
+
+  model<
+    ModelName extends string,
+    TableName extends string,
+    M extends ModelBuilder<
+      ModelName,
+      TableName,
+      Record<string, string>,
+      Record<string, RelationDefinition>
+    >,
+  >(
+    name: ModelName,
+    table: TableName,
+    callback: (
+      m: ModelBuilder<ModelName, TableName, Record<string, string>, Record<never, never>>,
+    ) => M | undefined,
+  ): ContractBuilder<
+    Target,
+    Tables,
+    Models & Record<ModelName, ReturnType<M['build']>>,
+    CoreHash,
+    ExtensionPacks,
+    Capabilities
+  > {
+    const modelBuilder = new ModelBuilder<ModelName, TableName>(name, table);
+    const result = callback(modelBuilder);
+    const finalBuilder = result instanceof ModelBuilder ? result : modelBuilder;
+    const modelState = finalBuilder.build();
+
+    return new ContractBuilder<
+      Target,
+      Tables,
+      Models & Record<ModelName, ReturnType<M['build']>>,
+      CoreHash,
+      ExtensionPacks,
+      Capabilities
+    >({
+      ...this.state,
+      models: { ...this.state.models, [name]: modelState } as Models &
+        Record<ModelName, ReturnType<M['build']>>,
+    });
+  }
+
+  coreHash<H extends string>(
+    hash: H,
+  ): ContractBuilder<Target, Tables, Models, H, ExtensionPacks, Capabilities> {
+    return new ContractBuilder<Target, Tables, Models, H, ExtensionPacks, Capabilities>({
+      ...this.state,
+      coreHash: hash,
+    });
+  }
+}
+
+export function defineContract(): ContractBuilder {
+  return new ContractBuilder();
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+export type {
+  ColumnBuilder,
+  ColumnBuilderState,
+  ColumnTypeDescriptor,
+  ContractBuilderState,
+  ForeignKeyDef,
+  IndexDef,
+  ModelBuilderState,
+  RelationDefinition,
+  TableBuilderState,
+  UniqueConstraintDef,
+} from './builder-state';
+
+export { ContractBuilder, defineContract } from './contract-builder';
+export { ModelBuilder } from './model-builder';
+export { createTable, TableBuilder } from './table-builder';
+
+export type {
+  BuildModelFields,
+  BuildModels,
+  BuildRelations,
+  BuildStorage,
+  BuildStorageColumn,
+  BuildStorageTables,
+  ExtractColumns,
+  ExtractModelFields,
+  ExtractModelRelations,
+  ExtractPrimaryKey,
+  Mutable,
+} from './types';

package/src/model-builder.ts

@@ -0,0 +1,160 @@
+import type { ModelBuilderState, RelationDefinition } from './builder-state';
+
+export class ModelBuilder<
+  Name extends string,
+  Table extends string,
+  Fields extends Record<string, string> = Record<never, never>,
+  Relations extends Record<string, RelationDefinition> = Record<never, never>,
+> {
+  private readonly _name: Name;
+  private readonly _table: Table;
+  private readonly _fields: Fields;
+  private readonly _relations: Relations;
+
+  constructor(
+    name: Name,
+    table: Table,
+    fields: Fields = {} as Fields,
+    relations: Relations = {} as Relations,
+  ) {
+    this._name = name;
+    this._table = table;
+    this._fields = fields;
+    this._relations = relations;
+  }
+
+  field<FieldName extends string, ColumnName extends string>(
+    fieldName: FieldName,
+    columnName: ColumnName,
+  ): ModelBuilder<Name, Table, Fields & Record<FieldName, ColumnName>, Relations> {
+    return new ModelBuilder(
+      this._name,
+      this._table,
+      {
+        ...this._fields,
+        [fieldName]: columnName,
+      } as Fields & Record<FieldName, ColumnName>,
+      this._relations,
+    );
+  }
+
+  relation<RelationName extends string, ToModel extends string, ToTable extends string>(
+    name: RelationName,
+    options: {
+      toModel: ToModel;
+      toTable: ToTable;
+      cardinality: '1:1' | '1:N' | 'N:1';
+      on: {
+        parentTable: Table;
+        parentColumns: readonly string[];
+        childTable: ToTable;
+        childColumns: readonly string[];
+      };
+    },
+  ): ModelBuilder<Name, Table, Fields, Relations & Record<RelationName, RelationDefinition>>;
+  relation<
+    RelationName extends string,
+    ToModel extends string,
+    ToTable extends string,
+    JunctionTable extends string,
+  >(
+    name: RelationName,
+    options: {
+      toModel: ToModel;
+      toTable: ToTable;
+      cardinality: 'N:M';
+      through: {
+        table: JunctionTable;
+        parentColumns: readonly string[];
+        childColumns: readonly string[];
+      };
+      on: {
+        parentTable: Table;
+        parentColumns: readonly string[];
+        childTable: JunctionTable;
+        childColumns: readonly string[];
+      };
+    },
+  ): ModelBuilder<Name, Table, Fields, Relations & Record<RelationName, RelationDefinition>>;
+  relation<
+    RelationName extends string,
+    ToModel extends string,
+    ToTable extends string,
+    JunctionTable extends string = never,
+  >(
+    name: RelationName,
+    options: {
+      toModel: ToModel;
+      toTable: ToTable;
+      cardinality: '1:1' | '1:N' | 'N:1' | 'N:M';
+      through?: {
+        table: JunctionTable;
+        parentColumns: readonly string[];
+        childColumns: readonly string[];
+      };
+      on: {
+        parentTable: Table;
+        parentColumns: readonly string[];
+        childTable: ToTable | JunctionTable;
+        childColumns: readonly string[];
+      };
+    },
+  ): ModelBuilder<Name, Table, Fields, Relations & Record<RelationName, RelationDefinition>> {
+    // Validate parentTable matches model's table
+    if (options.on.parentTable !== this._table) {
+      throw new Error(
+        `Relation "${name}" parentTable "${options.on.parentTable}" does not match model table "${this._table}"`,
+      );
+    }
+
+    // Validate childTable matches toTable (for non-N:M) or through.table (for N:M)
+    if (options.cardinality === 'N:M') {
+      if (!options.through) {
+        throw new Error(`Relation "${name}" with cardinality "N:M" requires through field`);
+      }
+      if (options.on.childTable !== options.through.table) {
+        throw new Error(
+          `Relation "${name}" childTable "${options.on.childTable}" does not match through.table "${options.through.table}"`,
+        );
+      }
+    } else {
+      if (options.on.childTable !== options.toTable) {
+        throw new Error(
+          `Relation "${name}" childTable "${options.on.childTable}" does not match toTable "${options.toTable}"`,
+        );
+      }
+    }
+
+    const relationDef: RelationDefinition = {
+      to: options.toModel,
+      cardinality: options.cardinality,
+      on: {
+        parentCols: options.on.parentColumns,
+        childCols: options.on.childColumns,
+      },
+      ...(options.through
+        ? {
+            through: {
+              table: options.through.table,
+              parentCols: options.through.parentColumns,
+              childCols: options.through.childColumns,
+            },
+          }
+        : undefined),
+    };
+
+    return new ModelBuilder(this._name, this._table, this._fields, {
+      ...this._relations,
+      [name]: relationDef,
+    } as Relations & Record<RelationName, RelationDefinition>);
+  }
+
+  build(): ModelBuilderState<Name, Table, Fields, Relations> {
+    return {
+      name: this._name,
+      table: this._table,
+      fields: this._fields,
+      relations: this._relations,
+    };
+  }
+}