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

package/package.json

@@ -1,36 +1,45 @@
 {
   "name": "@prisma-next/contract-authoring",
-  "version": "0.3.0-dev.4",
+  "version": "0.3.0-dev.40",
   "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.4"
+    "@prisma-next/utils": "0.3.0-dev.40",
+    "@prisma-next/contract": "0.3.0-dev.40"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.0.16",
-    "tsup": "8.5.1",
+    "tsdown": "0.18.4",
     "typescript": "5.9.3",
-    "vitest": "4.0.16"
+    "vitest": "4.0.17",
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/tsdown": "0.0.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/1-framework/2-authoring/contract"
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts",
+    "build": "tsdown",
     "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,188 @@
+import type { ColumnDefault, ExecutionMutationDefaultValue } from '@prisma-next/contract/types';
+
+/**
+ * Column type descriptor containing both codec ID and native type.
+ * Used when defining columns with descriptor objects instead of string IDs.
+ *
+ * For parameterized types (e.g., `vector(1536)`), the `typeParams` field
+ * carries codec-owned parameters that affect both TypeScript type generation
+ * and native DDL output.
+ */
+export type ColumnTypeDescriptor = {
+  readonly codecId: string;
+  readonly nativeType: string;
+  readonly typeParams?: Record<string, unknown>;
+  readonly typeRef?: string;
+};
+
+/**
+ * Base column properties shared by all column states.
+ */
+type ColumnBuilderStateBase<Name extends string, Type extends string> = {
+  readonly name: Name;
+  readonly type: Type;
+  readonly nativeType: string;
+  readonly typeParams?: Record<string, unknown>;
+  readonly typeRef?: string;
+};
+
+export type StorageTypeInstanceState = {
+  readonly codecId: string;
+  readonly nativeType: string;
+  readonly typeParams: Record<string, unknown>;
+};
+
+/**
+ * Descriptive error type shown when attempting to use both nullable and default.
+ * This string literal appears in TypeScript error messages for better DX.
+ */
+export type NullableColumnCannotHaveDefault =
+  "Error: A nullable column cannot have a default value. Remove 'nullable: true' or remove 'default'.";
+
+/**
+ * Column builder state with enforced nullable/default mutual exclusivity.
+ *
+ * Invariant: A column with a default value is always NOT NULL.
+ * This is enforced at the type level via conditional types:
+ * - Nullable columns (`nullable: true`) cannot have a `default` property
+ * - Non-nullable columns (`nullable: false`) can optionally have a `default` property
+ */
+export type ColumnBuilderState<
+  Name extends string,
+  Nullable extends boolean,
+  Type extends string,
+> = ColumnBuilderStateBase<Name, Type> &
+  (Nullable extends true
+    ? { readonly nullable: true; readonly default?: NullableColumnCannotHaveDefault }
+    : {
+        readonly nullable: false;
+        readonly default?: ColumnDefault;
+        readonly executionDefault?: ExecutionMutationDefaultValue;
+      });
+
+/**
+ * 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;
+  readonly constraint?: boolean;
+  readonly index?: boolean;
+}
+
+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 ForeignKeyDefaultsState {
+  readonly constraint: boolean;
+  readonly index: boolean;
+}
+
+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>>
+  >,
+  StorageHash 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 storageHash?: StorageHash;
+  readonly extensionPacks?: ExtensionPacks;
+  readonly capabilities?: Capabilities;
+  readonly storageTypes?: Record<string, StorageTypeInstanceState>;
+  readonly foreignKeyDefaults?: ForeignKeyDefaultsState;
+  /**
+   * 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,169 @@
+import type { TargetPackRef } from '@prisma-next/contract/framework-components';
+import type {
+  ColumnBuilderState,
+  ContractBuilderState,
+  ForeignKeyDefaultsState,
+  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>,
+  StorageHash 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,
+    StorageHash,
+    ExtensionPacks,
+    Capabilities
+  >;
+
+  constructor(
+    state?: ContractBuilderState<Target, Tables, Models, StorageHash, ExtensionPacks, Capabilities>,
+  ) {
+    this.state =
+      state ??
+      ({
+        tables: {},
+        models: {},
+      } as ContractBuilderState<Target, Tables, Models, StorageHash, ExtensionPacks, Capabilities>);
+  }
+
+  target<T extends string>(
+    packRef: TargetPackRef<string, T>,
+  ): ContractBuilder<T, Tables, Models, StorageHash, ExtensionPacks, Capabilities> {
+    return new ContractBuilder<T, Tables, Models, StorageHash, ExtensionPacks, Capabilities>({
+      ...this.state,
+      target: packRef.targetId,
+    });
+  }
+
+  capabilities<C extends Record<string, Record<string, boolean>>>(
+    capabilities: C,
+  ): ContractBuilder<Target, Tables, Models, StorageHash, ExtensionPacks, C> {
+    return new ContractBuilder<Target, Tables, Models, StorageHash, 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,
+    StorageHash,
+    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,
+      StorageHash,
+      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']>>,
+    StorageHash,
+    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']>>,
+      StorageHash,
+      ExtensionPacks,
+      Capabilities
+    >({
+      ...this.state,
+      models: { ...this.state.models, [name]: modelState } as Models &
+        Record<ModelName, ReturnType<M['build']>>,
+    });
+  }
+
+  storageHash<H extends string>(
+    hash: H,
+  ): ContractBuilder<Target, Tables, Models, H, ExtensionPacks, Capabilities> {
+    return new ContractBuilder<Target, Tables, Models, H, ExtensionPacks, Capabilities>({
+      ...this.state,
+      storageHash: hash,
+    });
+  }
+
+  foreignKeyDefaults(
+    config: ForeignKeyDefaultsState,
+  ): ContractBuilder<Target, Tables, Models, StorageHash, ExtensionPacks, Capabilities> {
+    return new ContractBuilder<Target, Tables, Models, StorageHash, ExtensionPacks, Capabilities>({
+      ...this.state,
+      foreignKeyDefaults: config,
+    });
+  }
+}
+
+export function defineContract(): ContractBuilder {
+  return new ContractBuilder();
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export type {
+  ColumnBuilder,
+  ColumnBuilderState,
+  ColumnTypeDescriptor,
+  ContractBuilderState,
+  ForeignKeyDef,
+  ForeignKeyDefaultsState,
+  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,
+    };
+  }
+}