@prisma-next/contract-authoring 0.3.0-dev.1 → 0.3.0-dev.100

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<never, never>, 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,32 @@
+export type {
+  ColumnBuilder,
+  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 { 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,
+    };
+  }
+}

package/src/table-builder.ts

@@ -0,0 +1,330 @@
+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;
+type IndexOptions = {
+  readonly name?: string;
+  readonly using?: string;
+  readonly config?: Record<string, unknown>;
+};
+
+function isIndexDef(value: readonly string[] | IndexDef): value is IndexDef {
+  return !Array.isArray(value);
+}
+
+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<
+    never,
+    ColumnBuilderState<string, boolean, string>
+  >,
+  PrimaryKey extends readonly string[] | undefined = undefined,
+> {
+  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);
+  }
+
+  private columnInternal<
+    ColName extends string,
+    Descriptor extends ColumnTypeDescriptor,
+    Options extends ColumnOptions<Descriptor>,
+  >(
+    name: ColName,
+    options: Options,
+    executionDefault?: ExecutionMutationDefaultValue,
+  ): TableBuilder<
+    Name,
+    Columns &
+      Record<
+        ColName,
+        ColumnBuilderState<ColName, NullableFromOptions<Options>, Descriptor['codecId']>
+      >,
+    PrimaryKey
+  > {
+    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,
+      ...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._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,
+  ): TableBuilder<Name, Columns, PK> {
+    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> {
+    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>;
+  index(
+    columns: readonly string[],
+    options?: IndexOptions,
+  ): TableBuilder<Name, Columns, PrimaryKey>;
+  index(indexDef: IndexDef): TableBuilder<Name, Columns, PrimaryKey>;
+  index(
+    columnsOrIndexDef: readonly string[] | IndexDef,
+    nameOrOptions?: string | IndexOptions,
+  ): TableBuilder<Name, Columns, PrimaryKey> {
+    const indexDef: IndexDef = isIndexDef(columnsOrIndexDef)
+      ? columnsOrIndexDef
+      : {
+          columns: columnsOrIndexDef,
+          ...(typeof nameOrOptions === 'string' ? { name: nameOrOptions } : {}),
+          ...(typeof nameOrOptions === 'object' && nameOrOptions !== null
+            ? {
+                ...(nameOrOptions.name !== undefined ? { name: nameOrOptions.name } : {}),
+                ...(nameOrOptions.using !== undefined ? { using: nameOrOptions.using } : {}),
+                ...(nameOrOptions.config !== undefined ? { config: nameOrOptions.config } : {}),
+              }
+            : {}),
+        };
+
+    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[] },
+    opts?: string | (ForeignKeyOptions & { constraint?: boolean; index?: boolean }),
+  ): TableBuilder<Name, Columns, PrimaryKey> {
+    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> {
+    return {
+      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>;
+  }
+}