@prisma-next/contract-authoring 0.3.0-dev.5 → 0.3.0-dev.50

package/package.json

@@ -1,37 +1,45 @@
 {
   "name": "@prisma-next/contract-authoring",
-  "version": "0.3.0-dev.5",
+  "version": "0.3.0-dev.50",
   "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.5"
+    "@prisma-next/contract": "0.3.0-dev.50",
+    "@prisma-next/utils": "0.3.0-dev.50"
   },
   "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",
     "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 && tsc --project tsconfig.build.json",
+    "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

@@ -1,21 +1,97 @@
+import type { ColumnDefault, ExecutionMutationDefaultValue } from '@prisma-next/contract/types';
+
+/**
+ * Duplicated from sql-contract to avoid cross-layer dependency
+ * (framework authoring cannot depend on the SQL domain's contract package).
+ */
+export type ReferentialAction = 'noAction' | 'restrict' | 'cascade' | 'setNull' | 'setDefault';
+
 /**
  * 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;
 };
 
-export interface ColumnBuilderState<
-  Name extends string,
-  Nullable extends boolean,
-  Type extends string,
-> {
+/**
+ * Base column properties shared by all column states.
+ */
+type ColumnBuilderStateBase<Name extends string, Type extends string> = {
   readonly name: Name;
-  readonly nullable: Nullable;
   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>;
+};
+
+/**
+ * Column builder state.
+ *
+ * Both nullable and non-nullable columns can define defaults to match database behavior.
+ */
+export type ColumnBuilderState<
+  Name extends string,
+  Nullable extends boolean,
+  Type extends string,
+> = ColumnBuilderStateBase<Name, Type> &
+  (Nullable extends true
+    ? { readonly nullable: true; readonly default?: ColumnDefault }
+    : {
+        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;
+}
+
+/**
+ * Options for configuring a foreign key's name and referential actions.
+ */
+export type ForeignKeyOptions = {
+  readonly name?: string;
+  readonly onDelete?: ReferentialAction;
+  readonly onUpdate?: ReferentialAction;
+};
+
+/**
+ * Foreign key definition for table builder.
+ */
+export interface ForeignKeyDef extends ForeignKeyOptions {
+  readonly columns: readonly string[];
+  readonly references: {
+    readonly table: string;
+    readonly columns: readonly string[];
+  };
+  readonly constraint?: boolean;
+  readonly index?: boolean;
 }
 
 export interface TableBuilderState<
@@ -26,6 +102,10 @@ export interface TableBuilderState<
   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 = {
@@ -54,6 +134,11 @@ export interface ModelBuilderState<
   readonly relations: Relations;
 }
 
+export interface ForeignKeyDefaultsState {
+  readonly constraint: boolean;
+  readonly index: boolean;
+}
+
 export interface ContractBuilderState<
   Target extends string | undefined = string | undefined,
   Tables extends Record<
@@ -78,16 +163,18 @@ export interface ContractBuilderState<
     never,
     ModelBuilderState<string, string, Record<string, string>, Record<string, RelationDefinition>>
   >,
-  CoreHash extends string | undefined = string | undefined,
+  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 coreHash?: CoreHash;
+  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.

package/src/contract-builder.ts

@@ -2,12 +2,13 @@ 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 { TableBuilder } from './table-builder';
+import { createTable, TableBuilder } from './table-builder';
 
 export class ContractBuilder<
   Target extends string | undefined = undefined,
@@ -23,7 +24,7 @@ export class ContractBuilder<
     string,
     ModelBuilderState<string, string, Record<string, string>, Record<string, RelationDefinition>>
   > = Record<never, never>,
-  CoreHash extends string | undefined = undefined,
+  StorageHash extends string | undefined = undefined,
   ExtensionPacks extends Record<string, unknown> | undefined = undefined,
   Capabilities extends Record<string, Record<string, boolean>> | undefined = undefined,
 > {
@@ -31,26 +32,26 @@ export class ContractBuilder<
     Target,
     Tables,
     Models,
-    CoreHash,
+    StorageHash,
     ExtensionPacks,
     Capabilities
   >;
 
   constructor(
-    state?: ContractBuilderState<Target, Tables, Models, CoreHash, ExtensionPacks, Capabilities>,
+    state?: ContractBuilderState<Target, Tables, Models, StorageHash, ExtensionPacks, Capabilities>,
   ) {
     this.state =
       state ??
       ({
         tables: {},
         models: {},
-      } as ContractBuilderState<Target, Tables, Models, CoreHash, ExtensionPacks, Capabilities>);
+      } as ContractBuilderState<Target, Tables, Models, StorageHash, 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>({
+  ): ContractBuilder<T, Tables, Models, StorageHash, ExtensionPacks, Capabilities> {
+    return new ContractBuilder<T, Tables, Models, StorageHash, ExtensionPacks, Capabilities>({
       ...this.state,
       target: packRef.targetId,
     });
@@ -58,8 +59,8 @@ export class ContractBuilder<
 
   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>({
+  ): ContractBuilder<Target, Tables, Models, StorageHash, ExtensionPacks, C> {
+    return new ContractBuilder<Target, Tables, Models, StorageHash, ExtensionPacks, C>({
       ...this.state,
       capabilities,
     });
@@ -79,11 +80,11 @@ export class ContractBuilder<
     Target,
     Tables & Record<TableName, ReturnType<T['build']>>,
     Models,
-    CoreHash,
+    StorageHash,
     ExtensionPacks,
     Capabilities
   > {
-    const tableBuilder = new TableBuilder<TableName>(name);
+    const tableBuilder = createTable(name);
     const result = callback(tableBuilder);
     const finalBuilder = result instanceof TableBuilder ? result : tableBuilder;
     const tableState = finalBuilder.build();
@@ -92,7 +93,7 @@ export class ContractBuilder<
       Target,
       Tables & Record<TableName, ReturnType<T['build']>>,
       Models,
-      CoreHash,
+      StorageHash,
       ExtensionPacks,
       Capabilities
     >({
@@ -121,7 +122,7 @@ export class ContractBuilder<
     Target,
     Tables,
     Models & Record<ModelName, ReturnType<M['build']>>,
-    CoreHash,
+    StorageHash,
     ExtensionPacks,
     Capabilities
   > {
@@ -134,7 +135,7 @@ export class ContractBuilder<
       Target,
       Tables,
       Models & Record<ModelName, ReturnType<M['build']>>,
-      CoreHash,
+      StorageHash,
       ExtensionPacks,
       Capabilities
     >({
@@ -144,12 +145,21 @@ export class ContractBuilder<
     });
   }
 
-  coreHash<H extends string>(
+  storageHash<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,
+      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,
     });
   }
 }

package/src/index.ts

@@ -3,14 +3,19 @@ export type {
   ColumnBuilderState,
   ColumnTypeDescriptor,
   ContractBuilderState,
+  ForeignKeyDef,
+  ForeignKeyDefaultsState,
+  ForeignKeyOptions,
+  IndexDef,
   ModelBuilderState,
   RelationDefinition,
   TableBuilderState,
+  UniqueConstraintDef,
 } from './builder-state';
 
 export { ContractBuilder, defineContract } from './contract-builder';
 export { ModelBuilder } from './model-builder';
-export { TableBuilder } from './table-builder';
+export { createTable, TableBuilder } from './table-builder';
 
 export type {
   BuildModelFields,

package/src/table-builder.ts

@@ -1,5 +1,82 @@
-import type { ColumnBuilderState, ColumnTypeDescriptor, TableBuilderState } from './builder-state';
+import type { ColumnDefault, ExecutionMutationDefaultValue } from '@prisma-next/contract/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type {
+  ColumnBuilderState,
+  ColumnTypeDescriptor,
+  ForeignKeyDef,
+  ForeignKeyOptions,
+  IndexDef,
+  TableBuilderState,
+  UniqueConstraintDef,
+} from './builder-state';
 
+/**
+ * Column options for nullable columns.
+ */
+interface NullableColumnOptions<Descriptor extends ColumnTypeDescriptor> {
+  type: Descriptor;
+  nullable: true;
+  typeParams?: Record<string, unknown>;
+  default?: ColumnDefault;
+}
+
+/**
+ * Column options for non-nullable columns.
+ * Non-nullable columns can optionally have a default value.
+ */
+interface NonNullableColumnOptions<Descriptor extends ColumnTypeDescriptor> {
+  type: Descriptor;
+  nullable?: false;
+  typeParams?: Record<string, unknown>;
+  default?: ColumnDefault;
+}
+
+type GeneratedColumnOptions<Descriptor extends ColumnTypeDescriptor> = Omit<
+  NonNullableColumnOptions<Descriptor>,
+  'default' | 'nullable'
+> & {
+  /**
+   * Generated columns are always non-nullable and use mutation-time defaults
+   * that the runtime injects when the column is omitted from insert input.
+   */
+  nullable?: false;
+  generated: ExecutionMutationDefaultValue;
+};
+
+/** Column options for any column nullability. */
+type ColumnOptions<Descriptor extends ColumnTypeDescriptor> =
+  | NullableColumnOptions<Descriptor>
+  | NonNullableColumnOptions<Descriptor>;
+
+type NullableFromOptions<TOptions> = TOptions extends { nullable: true } ? true : false;
+
+interface TableBuilderInternalState<
+  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 | undefined;
+  readonly uniques: readonly UniqueConstraintDef[];
+  readonly indexes: readonly IndexDef[];
+  readonly foreignKeys: readonly ForeignKeyDef[];
+}
+
+/**
+ * Creates a new table builder with the given name.
+ * This is the preferred way to create a TableBuilder - it ensures
+ * type parameters are inferred correctly without unsafe casts.
+ */
+export function createTable<Name extends string>(name: Name): TableBuilder<Name> {
+  return new TableBuilder(name, {}, undefined, undefined, [], [], []);
+}
+
+/**
+ * Builder for defining table structure with type-safe chaining.
+ * Use `createTable(name)` to create instances.
+ */
 export class TableBuilder<
   Name extends string,
   Columns extends Record<string, ColumnBuilderState<string, boolean, string>> = Record<
@@ -8,76 +85,202 @@ export class TableBuilder<
   >,
   PrimaryKey extends readonly string[] | undefined = undefined,
 > {
-  private readonly _name: Name;
-  private readonly _columns: Columns;
-  private readonly _primaryKey: PrimaryKey;
-
-  constructor(name: Name, columns: Columns = {} as Columns, primaryKey?: PrimaryKey) {
-    this._name = name;
-    this._columns = columns;
-    this._primaryKey = primaryKey as PrimaryKey;
+  private readonly _state: TableBuilderInternalState<Name, Columns, PrimaryKey>;
+
+  /** @internal Use createTable() instead */
+  constructor(
+    name: Name,
+    columns: Columns,
+    primaryKey: PrimaryKey,
+    primaryKeyName: string | undefined,
+    uniques: readonly UniqueConstraintDef[],
+    indexes: readonly IndexDef[],
+    foreignKeys: readonly ForeignKeyDef[],
+  ) {
+    this._state = {
+      name,
+      columns,
+      primaryKey,
+      primaryKeyName,
+      uniques,
+      indexes,
+      foreignKeys,
+    };
+  }
+
+  private get _name(): Name {
+    return this._state.name;
+  }
+
+  private get _columns(): Columns {
+    return this._state.columns;
+  }
+
+  private get _primaryKey(): PrimaryKey {
+    return this._state.primaryKey;
+  }
+
+  /** Add a nullable column to the table. */
+  column<ColName extends string, Descriptor extends ColumnTypeDescriptor>(
+    name: ColName,
+    options: NullableColumnOptions<Descriptor>,
+  ): TableBuilder<
+    Name,
+    Columns & Record<ColName, ColumnBuilderState<ColName, true, Descriptor['codecId']>>,
+    PrimaryKey
+  >;
+
+  /**
+   * Add a non-nullable column to the table.
+   * Non-nullable columns can optionally have a default value.
+   */
+  column<ColName extends string, Descriptor extends ColumnTypeDescriptor>(
+    name: ColName,
+    options: NonNullableColumnOptions<Descriptor>,
+  ): TableBuilder<
+    Name,
+    Columns & Record<ColName, ColumnBuilderState<ColName, false, Descriptor['codecId']>>,
+    PrimaryKey
+  >;
+
+  /**
+   * Implementation of the column method.
+   */
+  column<ColName extends string, Descriptor extends ColumnTypeDescriptor>(
+    name: ColName,
+    options: ColumnOptions<Descriptor>,
+  ): TableBuilder<
+    Name,
+    Columns & Record<ColName, ColumnBuilderState<ColName, boolean, Descriptor['codecId']>>,
+    PrimaryKey
+  > {
+    return this.columnInternal(name, options);
+  }
+
+  generated<ColName extends string, Descriptor extends ColumnTypeDescriptor>(
+    name: ColName,
+    options: GeneratedColumnOptions<Descriptor>,
+  ): TableBuilder<
+    Name,
+    Columns & Record<ColName, ColumnBuilderState<ColName, false, Descriptor['codecId']>>,
+    PrimaryKey
+  > {
+    const { generated, ...columnOptions } = options;
+    return this.columnInternal(name, columnOptions, generated);
   }
 
-  column<
+  private columnInternal<
     ColName extends string,
     Descriptor extends ColumnTypeDescriptor,
-    Nullable extends boolean | undefined = undefined,
+    Options extends ColumnOptions<Descriptor>,
   >(
     name: ColName,
-    options: {
-      type: Descriptor;
-      nullable?: Nullable;
-    },
+    options: Options,
+    executionDefault?: ExecutionMutationDefaultValue,
   ): TableBuilder<
     Name,
     Columns &
       Record<
         ColName,
-        ColumnBuilderState<ColName, Nullable extends true ? true : false, Descriptor['codecId']>
+        ColumnBuilderState<ColName, NullableFromOptions<Options>, Descriptor['codecId']>
       >,
     PrimaryKey
   > {
-    const nullable = (options.nullable ?? false) as Nullable extends true ? true : false;
-    const { codecId, nativeType } = options.type;
+    const nullable = options.nullable ?? false;
+    const { codecId, nativeType, typeParams: descriptorTypeParams, typeRef } = options.type;
+    const typeParams = options.typeParams ?? descriptorTypeParams;
 
     const columnState = {
       name,
       nullable,
       type: codecId,
       nativeType,
-    } as ColumnBuilderState<ColName, Nullable extends true ? true : false, Descriptor['codecId']>;
+      ...ifDefined('typeParams', typeParams),
+      ...ifDefined('typeRef', typeRef),
+      ...ifDefined('default', 'default' in options ? options.default : undefined),
+      ...ifDefined('executionDefault', executionDefault),
+    } as ColumnBuilderState<ColName, NullableFromOptions<Options>, Descriptor['codecId']>;
+    const newColumns = { ...this._columns, [name]: columnState } as Columns &
+      Record<
+        ColName,
+        ColumnBuilderState<ColName, NullableFromOptions<Options>, Descriptor['codecId']>
+      >;
     return new TableBuilder(
-      this._name,
-      { ...this._columns, [name]: columnState } as Columns &
-        Record<
-          ColName,
-          ColumnBuilderState<ColName, Nullable extends true ? true : false, Descriptor['codecId']>
-        >,
-      this._primaryKey,
+      this._state.name,
+      newColumns,
+      this._state.primaryKey,
+      this._state.primaryKeyName,
+      this._state.uniques,
+      this._state.indexes,
+      this._state.foreignKeys,
     );
   }
 
   primaryKey<PK extends readonly string[]>(
     columns: PK,
-    _name?: string,
+    name?: string,
   ): TableBuilder<Name, Columns, PK> {
-    return new TableBuilder(this._name, this._columns, columns);
+    return new TableBuilder(
+      this._state.name,
+      this._state.columns,
+      columns,
+      name,
+      this._state.uniques,
+      this._state.indexes,
+      this._state.foreignKeys,
+    );
   }
 
-  unique(_columns: readonly string[], _name?: string): TableBuilder<Name, Columns, PrimaryKey> {
-    return this;
+  unique(columns: readonly string[], name?: string): TableBuilder<Name, Columns, PrimaryKey> {
+    const constraint: UniqueConstraintDef = name ? { columns, name } : { columns };
+    return new TableBuilder(
+      this._state.name,
+      this._state.columns,
+      this._state.primaryKey,
+      this._state.primaryKeyName,
+      [...this._state.uniques, constraint],
+      this._state.indexes,
+      this._state.foreignKeys,
+    );
   }
 
-  index(_columns: readonly string[], _name?: string): TableBuilder<Name, Columns, PrimaryKey> {
-    return this;
+  index(columns: readonly string[], name?: string): TableBuilder<Name, Columns, PrimaryKey> {
+    const indexDef: IndexDef = name ? { columns, name } : { columns };
+    return new TableBuilder(
+      this._state.name,
+      this._state.columns,
+      this._state.primaryKey,
+      this._state.primaryKeyName,
+      this._state.uniques,
+      [...this._state.indexes, indexDef],
+      this._state.foreignKeys,
+    );
   }
 
   foreignKey(
-    _columns: readonly string[],
-    _references: { table: string; columns: readonly string[] },
-    _name?: string,
+    columns: readonly string[],
+    references: { table: string; columns: readonly string[] },
+    opts?: string | (ForeignKeyOptions & { constraint?: boolean; index?: boolean }),
   ): TableBuilder<Name, Columns, PrimaryKey> {
-    return this;
+    const resolved = typeof opts === 'string' ? { name: opts } : opts;
+    const fkDef: ForeignKeyDef = {
+      columns,
+      references,
+      ...ifDefined('name', resolved?.name),
+      ...ifDefined('onDelete', resolved?.onDelete),
+      ...ifDefined('onUpdate', resolved?.onUpdate),
+      ...ifDefined('constraint', resolved?.constraint),
+      ...ifDefined('index', resolved?.index),
+    };
+    return new TableBuilder(
+      this._state.name,
+      this._state.columns,
+      this._state.primaryKey,
+      this._state.primaryKeyName,
+      this._state.uniques,
+      this._state.indexes,
+      [...this._state.foreignKeys, fkDef],
+    );
   }
 
   build(): TableBuilderState<Name, Columns, PrimaryKey> {
@@ -85,6 +288,12 @@ export class TableBuilder<
       name: this._name,
       columns: this._columns,
       ...(this._primaryKey !== undefined ? { primaryKey: this._primaryKey } : {}),
+      ...(this._state.primaryKeyName !== undefined
+        ? { primaryKeyName: this._state.primaryKeyName }
+        : {}),
+      uniques: this._state.uniques,
+      indexes: this._state.indexes,
+      foreignKeys: this._state.foreignKeys,
     } as TableBuilderState<Name, Columns, PrimaryKey>;
   }
 }