@prisma-next/sql-contract-ts 0.12.0 → 0.13.0-dev.10

package/src/config-types.ts

@@ -1,6 +1,7 @@
 import { pathToFileURL } from 'node:url';
 import type { ContractConfig } from '@prisma-next/config/config-types';
-import type { Contract } from '@prisma-next/contract/types';
+import { applySpecifierDefaultControlPolicy } from '@prisma-next/contract/apply-specifier-default-control-policy';
+import type { Contract, ControlPolicy } from '@prisma-next/contract/types';
 import type { TargetPackRef } from '@prisma-next/framework-components/components';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { ok } from '@prisma-next/utils/result';
@@ -19,22 +20,35 @@ function defaultOutputFromContractPath(contractPath: string): string {
   return `${contractPath.slice(0, -ext.length)}.json`;
 }
 
+export interface TypeScriptContractSpecifierOptions {
+  readonly defaultControlPolicy?: ControlPolicy;
+}
+
 export function emptyContract(options: {
   readonly output?: string;
   readonly target: TargetPackRef<'sql', string>;
+  readonly defaultControlPolicy?: ControlPolicy;
 }): ContractConfig {
   return {
     source: {
-      load: async () => ok(buildSqlContractFromDefinition({ target: options.target, models: [] })),
+      load: async () => {
+        const built = buildSqlContractFromDefinition({ target: options.target, models: [] });
+        return ok(applySpecifierDefaultControlPolicy(built, options.defaultControlPolicy));
+      },
     },
     ...ifDefined('output', options.output),
   };
 }
 
-export function typescriptContract(contract: Contract, output?: string): ContractConfig {
+export function typescriptContract(
+  contract: Contract,
+  output?: string,
+  options?: TypeScriptContractSpecifierOptions,
+): ContractConfig {
   return {
     source: {
-      load: async () => ok(contract),
+      load: async () =>
+        ok(applySpecifierDefaultControlPolicy(contract, options?.defaultControlPolicy)),
     },
     // The in-memory variant has no input path to anchor on; fall through to
     // the global default in `normalizeContractConfig` when caller doesn't pin it.
@@ -42,7 +56,11 @@ export function typescriptContract(contract: Contract, output?: string): Contrac
   };
 }
 
-export function typescriptContractFromPath(contractPath: string, output?: string): ContractConfig {
+export function typescriptContractFromPath(
+  contractPath: string,
+  output?: string,
+  options?: TypeScriptContractSpecifierOptions,
+): ContractConfig {
   return {
     source: {
       inputs: [contractPath],
@@ -60,7 +78,7 @@ export function typescriptContractFromPath(contractPath: string, output?: string
             `typescriptContractFromPath: module at "${absolutePath}" has no "default" or "contract" export.`,
           );
         }
-        return ok(contract);
+        return ok(applySpecifierDefaultControlPolicy(contract, options?.defaultControlPolicy));
       },
     },
     output: output ?? defaultOutputFromContractPath(contractPath),

package/src/contract-builder.ts

@@ -1,3 +1,4 @@
+import type { ControlPolicy } from '@prisma-next/contract/types';
 import type { ForeignKeyDefaultsState } from '@prisma-next/contract-authoring';
 import type { CodecLookup } from '@prisma-next/framework-components/codec';
 import type {
@@ -12,6 +13,7 @@ import type {
   StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
 import { blindCast } from '@prisma-next/utils/casts';
+import { ifDefined } from '@prisma-next/utils/defined';
 import { buildSqlContractFromDefinition } from './build-contract';
 import {
   type ComposedAuthoringHelpers,
@@ -20,6 +22,7 @@ import {
 import {
   type ContractInput,
   type ContractModelBuilder,
+  extensionModel,
   field,
   isContractInput,
   type ModelAttributesSpec,
@@ -32,6 +35,7 @@ import {
 } from './contract-dsl';
 import { buildContractDefinition } from './contract-lowering';
 import type { SqlContractResult } from './contract-types';
+import type { EnumTypeHandle } from './enum-type';
 
 export { buildSqlContractFromDefinition } from './build-contract';
 
@@ -58,6 +62,7 @@ type ContractDefinition<
   StorageHash extends string | undefined,
   ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined,
   Namespaces extends readonly string[] | undefined = undefined,
+  Enums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>,
 > = {
   readonly family: Family;
   readonly target: Target;
@@ -65,11 +70,13 @@ type ContractDefinition<
   readonly naming?: Naming;
   readonly storageHash?: StorageHash;
   readonly foreignKeyDefaults?: ForeignKeyDefaults;
+  readonly defaultControlPolicy?: ControlPolicy;
   readonly namespaces?: Namespaces;
   readonly createNamespace?: (input: SqlNamespaceTablesInput) => Namespace;
   readonly types?: Types;
   readonly models?: Models;
   readonly codecLookup?: CodecLookup;
+  readonly enums?: Enums;
 };
 
 type ContractScaffold<
@@ -80,6 +87,7 @@ type ContractScaffold<
   StorageHash extends string | undefined,
   ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined,
   Namespaces extends readonly string[] | undefined = undefined,
+  Enums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>,
 > = {
   readonly family: Family;
   readonly target: Target;
@@ -87,11 +95,13 @@ type ContractScaffold<
   readonly naming?: Naming;
   readonly storageHash?: StorageHash;
   readonly foreignKeyDefaults?: ForeignKeyDefaults;
+  readonly defaultControlPolicy?: ControlPolicy;
   readonly namespaces?: Namespaces;
   readonly createNamespace?: (input: SqlNamespaceTablesInput) => Namespace;
   readonly types?: never;
   readonly models?: never;
   readonly codecLookup?: CodecLookup;
+  readonly enums?: Enums;
 };
 
 type ContractFactory<
@@ -100,9 +110,11 @@ type ContractFactory<
   Types extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry>,
   Models extends Record<string, ModelLike>,
   ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
+  Enums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>,
 > = (helpers: ComposedAuthoringHelpers<Family, Target, ExtensionPacks>) => {
   readonly types?: Types;
   readonly models?: Models;
+  readonly enums?: Enums;
 };
 
 function validateTargetPackRef(
@@ -289,6 +301,149 @@ function buildContractFromDsl<Definition extends ContractInput>(
   >(buildSqlContractFromDefinition(buildContractDefinition(definition), definition.codecLookup));
 }
 
+// Input for buildBoundContract — all fields from ContractInput except family/target
+// (those are injected by the builder, pre-bound at the call site).
+type BoundDefinitionInput<
+  Types extends Record<string, StorageTypeInstance | PostgresEnumStorageEntry> = Record<
+    never,
+    never
+  >,
+  Models extends Record<string, ModelLike> = Record<never, never>,
+  ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined = undefined,
+  Naming extends ContractInput['naming'] | undefined = undefined,
+  StorageHash extends string | undefined = undefined,
+  ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined = undefined,
+  Namespaces extends readonly string[] | undefined = undefined,
+> = {
+  readonly extensionPacks?: ExtensionPacks;
+  readonly naming?: Naming;
+  readonly storageHash?: StorageHash;
+  readonly foreignKeyDefaults?: ForeignKeyDefaults;
+  readonly defaultControlPolicy?: ControlPolicy;
+  readonly namespaces?: Namespaces;
+  readonly createNamespace?: (input: SqlNamespaceTablesInput) => Namespace;
+  readonly types?: Types;
+  readonly models?: Models;
+  readonly codecLookup?: CodecLookup;
+  readonly enums?: Record<string, EnumTypeHandle>;
+};
+
+// A bare `Record<string, EnumTypeHandle>` (no literal keys) is the widened
+// default for a side that declared no enums; drop it so the merge keeps only
+// literally-authored enum handles.
+type LiteralEnums<E extends Record<string, EnumTypeHandle>> = string extends keyof E
+  ? Record<never, never>
+  : E;
+
+// Merges enum handles authored on the scaffold definition with those returned
+// from the factory callback. Either side may be the widened default (empty).
+export type MergeEnums<
+  ScaffoldEnums extends Record<string, EnumTypeHandle>,
+  FactoryEnums extends Record<string, EnumTypeHandle>,
+> = LiteralEnums<ScaffoldEnums> & LiteralEnums<FactoryEnums>;
+
+// Merges a bound input with the pre-bound family/target to produce a full ContractDefinition.
+type WithFamilyTarget<
+  Input,
+  F extends FamilyPackRef<string>,
+  T extends TargetPackRef<'sql', string>,
+> = Input & { readonly family: F; readonly target: T };
+
+/**
+ * Shared builder that assembles a SqlContract with pre-bound family and target.
+ * Extension wrappers keep their own public overloads and delegate their impl body here;
+ * this is a plain overloaded function (not a factory returning an overloaded function)
+ * so no overloaded-function-return cast is needed.
+ *
+ * Overload 1: definition form (no factory).
+ */
+export function buildBoundContract<
+  const F extends FamilyPackRef<string>,
+  const T extends TargetPackRef<'sql', string>,
+  const Definition extends BoundDefinitionInput<
+    Record<string, StorageTypeInstance | PostgresEnumStorageEntry>,
+    Record<string, ModelLike>,
+    Record<string, ExtensionPackRef<'sql', string>> | undefined,
+    ContractInput['naming'] | undefined,
+    string | undefined,
+    ForeignKeyDefaultsState | undefined,
+    readonly string[] | undefined
+  >,
+>(
+  family: F,
+  target: T,
+  definition: Definition,
+  factory?: undefined,
+): SqlContractResult<WithFamilyTarget<Definition, F, T>>;
+/**
+ * Overload 2: factory form.
+ */
+export function buildBoundContract<
+  const F extends FamilyPackRef<string>,
+  const T extends TargetPackRef<'sql', string>,
+  const Definition extends BoundDefinitionInput<
+    Record<string, StorageTypeInstance | PostgresEnumStorageEntry>,
+    Record<string, ModelLike>,
+    Record<string, ExtensionPackRef<'sql', string>> | undefined,
+    ContractInput['naming'] | undefined,
+    string | undefined,
+    ForeignKeyDefaultsState | undefined,
+    readonly string[] | undefined
+  >,
+  const Built extends {
+    readonly types?: Record<string, StorageTypeInstance | PostgresEnumStorageEntry>;
+    readonly models?: Record<string, ModelLike>;
+    readonly enums?: Record<string, EnumTypeHandle>;
+  },
+>(
+  family: F,
+  target: T,
+  definition: Definition,
+  factory: (
+    helpers: ComposedAuthoringHelpers<F, T, NonNullable<Definition['extensionPacks']>>,
+  ) => Built,
+): SqlContractResult<WithFamilyTarget<Definition & Built, F, T>>;
+/** Implementation. */
+export function buildBoundContract(
+  family: FamilyPackRef<string>,
+  target: TargetPackRef<'sql', string>,
+  definition: Omit<ContractInput, 'family' | 'target'>,
+  factory?:
+    | ((
+        helpers: ComposedAuthoringHelpers<
+          FamilyPackRef<string>,
+          TargetPackRef<'sql', string>,
+          Record<string, ExtensionPackRef<'sql', string>> | undefined
+        >,
+      ) => {
+        readonly types?: Record<string, StorageTypeInstance | PostgresEnumStorageEntry>;
+        readonly models?: Record<string, ModelLike>;
+        readonly enums?: Record<string, EnumTypeHandle>;
+      })
+    | undefined,
+) {
+  const full = { ...definition, family, target };
+
+  if (factory !== undefined) {
+    const built = factory(
+      createComposedAuthoringHelpers({
+        family,
+        target,
+        extensionPacks: definition.extensionPacks,
+      }),
+    );
+    const mergedEnums = { ...(definition.enums ?? {}), ...built.enums };
+    return buildContractFromDsl({
+      ...full,
+      ...ifDefined('types', built.types),
+      ...ifDefined('models', built.models),
+      ...ifDefined('enums', Object.keys(mergedEnums).length > 0 ? mergedEnums : undefined),
+    });
+  }
+
+  return buildContractFromDsl(full);
+}
+
 export function defineContract<
   const Family extends FamilyPackRef<string>,
   const Target extends TargetPackRef<'sql', string>,
@@ -304,6 +459,7 @@ export function defineContract<
   const StorageHash extends string | undefined = undefined,
   const ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined = undefined,
   const Namespaces extends readonly string[] | undefined = undefined,
+  const Enums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>,
 >(
   definition: ContractDefinition<
     Family,
@@ -314,7 +470,8 @@ export function defineContract<
     Naming,
     StorageHash,
     ForeignKeyDefaults,
-    Namespaces
+    Namespaces,
+    Enums
   >,
 ): SqlContractResult<
   ContractDefinition<
@@ -326,7 +483,8 @@ export function defineContract<
     Naming,
     StorageHash,
     ForeignKeyDefaults,
-    Namespaces
+    Namespaces,
+    Enums
   >
 >;
 export function defineContract<
@@ -344,6 +502,8 @@ export function defineContract<
   const StorageHash extends string | undefined = undefined,
   const ForeignKeyDefaults extends ForeignKeyDefaultsState | undefined = undefined,
   const Namespaces extends readonly string[] | undefined = undefined,
+  const ScaffoldEnums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>,
+  const FactoryEnums extends Record<string, EnumTypeHandle> = Record<string, EnumTypeHandle>,
 >(
   definition: ContractScaffold<
     Family,
@@ -352,9 +512,10 @@ export function defineContract<
     Naming,
     StorageHash,
     ForeignKeyDefaults,
-    Namespaces
+    Namespaces,
+    ScaffoldEnums
   >,
-  factory: ContractFactory<Family, Target, Types, Models, ExtensionPacks>,
+  factory: ContractFactory<Family, Target, Types, Models, ExtensionPacks, FactoryEnums>,
 ): SqlContractResult<
   ContractDefinition<
     Family,
@@ -365,7 +526,8 @@ export function defineContract<
     Naming,
     StorageHash,
     ForeignKeyDefaults,
-    Namespaces
+    Namespaces,
+    MergeEnums<ScaffoldEnums, FactoryEnums>
   >
 >;
 export function defineContract(
@@ -384,22 +546,10 @@ export function defineContract(
     );
   }
 
-  if (!factory) {
-    return buildContractFromDsl(definition);
+  if (factory !== undefined) {
+    return buildBoundContract(definition.family, definition.target, definition, factory);
   }
-
-  const builtDefinition = {
-    ...definition,
-    ...factory(
-      createComposedAuthoringHelpers({
-        family: definition.family,
-        target: definition.target,
-        extensionPacks: definition.extensionPacks,
-      }),
-    ),
-  };
-
-  return buildContractFromDsl(builtDefinition);
+  return buildBoundContract(definition.family, definition.target, definition);
 }
 
 export type {
@@ -409,4 +559,4 @@ export type {
   ModelLike,
   ScalarFieldBuilder,
 };
-export { field, model, rel };
+export { extensionModel, field, model, rel };

package/src/contract-definition.ts

@@ -1,4 +1,8 @@
-import type { ColumnDefault, ExecutionMutationDefaultPhases } from '@prisma-next/contract/types';
+import type {
+  ColumnDefault,
+  ControlPolicy,
+  ExecutionMutationDefaultPhases,
+} from '@prisma-next/contract/types';
 import type { ForeignKeyDefaultsState } from '@prisma-next/contract-authoring';
 import type { ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';
 import type { ExtensionPackRef, TargetPackRef } from '@prisma-next/framework-components/components';
@@ -9,6 +13,7 @@ import type {
   SqlNamespaceTablesInput,
   StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
+import type { EnumTypeHandle } from './enum-type';
 
 export type { ExecutionMutationDefaultPhases };
 
@@ -20,6 +25,8 @@ export interface FieldNode {
   readonly default?: ColumnDefault;
   readonly executionDefaults?: ExecutionMutationDefaultPhases;
   readonly many?: boolean;
+  /** Present when the field was authored with `field.namedType(enumHandle)`. */
+  readonly enumTypeHandle?: EnumTypeHandle;
 }
 
 export interface PrimaryKeyNode {
@@ -52,6 +59,12 @@ export interface ForeignKeyNode {
      * know the target namespace can stamp it explicitly.
      */
     readonly namespaceId?: string;
+    /**
+     * Contract-space identity of the referenced table. When present, the
+     * table lives in a different contract space (identified by this value)
+     * rather than the current contract. Absent for local FKs.
+     */
+    readonly spaceId?: string;
   };
   readonly name?: string;
   readonly onDelete?: ReferentialAction;
@@ -64,7 +77,26 @@ export interface RelationNode {
   readonly fieldName: string;
   readonly toModel: string;
   readonly toTable: string;
+  /**
+   * Namespace coordinate of the related model. When omitted the assembler
+   * resolves the coordinate from the referenced model node's own
+   * `namespaceId`; the field exists so authoring paths that already know the
+   * target namespace can stamp it explicitly — required to disambiguate a
+   * relation to a model whose bare name also exists in another namespace.
+   */
+  readonly toNamespaceId?: string;
   readonly cardinality: '1:1' | '1:N' | 'N:1' | 'N:M';
+  /**
+   * Contract-space identity of the related model. When present, the
+   * related model lives in a different contract space. Absent for local
+   * (same-space) relations.
+   */
+  readonly spaceId?: string;
+  /**
+   * Namespace coordinate of the related model in the foreign space.
+   * Only set when `spaceId` is present.
+   */
+  readonly namespaceId?: string;
   readonly on: {
     readonly parentTable: string;
     readonly parentColumns: readonly string[];
@@ -113,10 +145,20 @@ export interface ModelNode {
   readonly indexes?: readonly IndexNode[];
   readonly foreignKeys?: readonly ForeignKeyNode[];
   readonly relations?: readonly RelationNode[];
+  readonly control?: ControlPolicy;
+  /**
+   * Single-table-inheritance variants share their base model's storage table:
+   * the variant's columns are materialised onto the base `ModelNode`, and this
+   * model contributes a domain model but no storage table of its own. When set,
+   * the assembler builds the domain model but skips creating a (shadow) storage
+   * table and a root for this model — the base owns both.
+   */
+  readonly sharesBaseTable?: boolean;
 }
 
 export interface ContractDefinition {
   readonly target: TargetPackRef<'sql', string>;
+  readonly defaultControlPolicy?: ControlPolicy;
   readonly extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>;
   readonly storageHash?: string;
   readonly foreignKeyDefaults?: ForeignKeyDefaultsState;
@@ -124,7 +166,7 @@ export interface ContractDefinition {
   /**
    * Enum types declared inside a named `namespace { enum … }` block,
    * keyed first by namespace id then by type name. These are routed to
-   * `storage.namespaces[nsId].enum` rather than the implicit fallback
+   * `storage.namespaces[nsId].entries.type` rather than the implicit fallback
    * namespace used for top-level `storageTypes` enums.
    */
   readonly namespaceTypes?: Readonly<
@@ -139,8 +181,20 @@ export interface ContractDefinition {
    * Target-supplied factory that materialises a `Namespace` concretion
    * for a declared namespace coordinate. Mirrors
    * `ContractInput.createNamespace`.
+   *
+   * The optional second argument carries target-specific enum types for the
+   * namespace (e.g. postgres enum registrations keyed by type name).
    */
-  readonly createNamespace?: (input: SqlNamespaceTablesInput) => Namespace;
+  readonly createNamespace?: (
+    input: SqlNamespaceTablesInput,
+    enumTypes?: Readonly<Record<string, PostgresEnumStorageEntry>>,
+  ) => Namespace;
   readonly models: readonly ModelNode[];
   readonly valueObjects?: readonly ValueObjectNode[];
+  /**
+   * Domain enum handles authored via `enumType()`. Each entry lowers to a
+   * domain `enum` entry and a storage `valueSet` entry in the contract's
+   * default namespace.
+   */
+  readonly enums?: Record<string, EnumTypeHandle>;
 }