TML-2837: eliminate the defineContract cast pattern in SQL extension wrappers via a shared bound builder (#731)

wmadden-electric · web-flow · commit fa181e307307 · 2026-06-05T08:23:36.000Z
Introduces a shared family/target-bound `buildBoundContract` in the SQL contract-builder; the sqlite and postgres extension `defineContract` wrappers delegate to it cast-free (4→0 casts each). The one residual helpers-composition cast stays in its single existing home.

Also includes the factory-clobber hardening (TML-2839): `buildBoundContract` spreads only the factory's declared outputs (`types`/`models`) via `ifDefined`, so factory output cannot override the pre-bound `family`/`target`/`extensionPacks`.

Refs: TML-2837, TML-2839

Signed-off-by: Will Madden &lt;madden@prisma.io&gt;
diff --git a/packages/2-sql/2-authoring/contract-ts/src/contract-builder.ts b/packages/2-sql/2-authoring/contract-ts/src/contract-builder.ts
@@ -13,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,
@@ -292,6 +293,130 @@ 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;
+};
+
+// 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>;
+  },
+>(
+  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>;
+      })
+    | undefined,
+) {
+  const full = { ...definition, family, target };
+
+  if (factory !== undefined) {
+    const built = factory(
+      createComposedAuthoringHelpers({
+        family,
+        target,
+        extensionPacks: definition.extensionPacks,
+      }),
+    );
+    return buildContractFromDsl({
+      ...full,
+      ...ifDefined('types', built.types),
+      ...ifDefined('models', built.models),
+    });
+  }
+
+  return buildContractFromDsl(full);
+}
+
 export function defineContract<
   const Family extends FamilyPackRef<string>,
   const Target extends TargetPackRef<'sql', string>,
@@ -387,22 +512,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 {
diff --git a/packages/2-sql/2-authoring/contract-ts/src/exports/contract-builder.ts b/packages/2-sql/2-authoring/contract-ts/src/exports/contract-builder.ts
@@ -6,6 +6,7 @@ export type {
   ScalarFieldBuilder,
 } from '../contract-builder';
 export {
+  buildBoundContract,
   buildSqlContractFromDefinition,
   defineContract,
   field,
diff --git a/packages/3-extensions/postgres/src/contract/define-contract.ts b/packages/3-extensions/postgres/src/contract/define-contract.ts
@@ -9,7 +9,7 @@ import type {
   ContractInput,
   ModelLike,
 } from '@prisma-next/sql-contract-ts/contract-builder';
-import { defineContract as baseDefineContract } from '@prisma-next/sql-contract-ts/contract-builder';
+import { buildBoundContract } from '@prisma-next/sql-contract-ts/contract-builder';
 import postgresPack from '@prisma-next/target-postgres/pack';
 import { postgresCreateNamespace } from '@prisma-next/target-postgres/types';
 
@@ -23,13 +23,13 @@ type PostgresResult<
   Types extends TypesConstraint,
   Models extends ModelsConstraint,
   ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
-> = Omit<
-  ReturnType<typeof baseDefineContract<SqlFamily, PostgresPack, Types, Models, ExtensionPacks>>,
-  'target' | 'targetFamily'
-> & {
-  readonly target: PostgresPack['targetId'];
-  readonly targetFamily: SqlFamily['familyId'];
-};
+> = ReturnType<
+  typeof buildBoundContract<
+    SqlFamily,
+    PostgresPack,
+    { readonly types?: Types; readonly models?: Models; readonly extensionPacks?: ExtensionPacks }
+  >
+>;
 
 type PostgresBaseScaffold<
   ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
@@ -81,29 +81,18 @@ export function defineContract<
   },
 ): PostgresResult<Types, Models, ExtensionPacks>;
 
+// Implementation — delegates to buildBoundContract which pre-binds family/target,
+// carrying zero casts at this layer.
 export function defineContract(
-  scaffold: Omit<ContractInput, 'family' | 'target'>,
+  definition: PostgresDefinition<TypesConstraint, ModelsConstraint, undefined>,
   factory?: (helpers: ComposedAuthoringHelpers<SqlFamily, PostgresPack, undefined>) => {
     readonly types?: TypesConstraint;
     readonly models?: ModelsConstraint;
   },
 ): PostgresResult<TypesConstraint, ModelsConstraint, undefined> {
-  const full = {
-    ...scaffold,
-    family: sqlFamilyPack,
-    target: postgresPack,
-    createNamespace: postgresCreateNamespace,
-  } as ContractInput;
+  const bound = { ...definition, createNamespace: postgresCreateNamespace };
   if (factory !== undefined) {
-    const { types: _t, models: _m, ...scaffoldOnly } = full;
-    return baseDefineContract(
-      scaffoldOnly,
-      factory as Parameters<typeof baseDefineContract>[1],
-    ) as unknown as PostgresResult<TypesConstraint, ModelsConstraint, undefined>;
+    return buildBoundContract(sqlFamilyPack, postgresPack, bound, factory);
   }
-  return baseDefineContract(full) as unknown as PostgresResult<
-    TypesConstraint,
-    ModelsConstraint,
-    undefined
-  >;
+  return buildBoundContract(sqlFamilyPack, postgresPack, bound);
 }
diff --git a/packages/3-extensions/sqlite/src/contract/define-contract.ts b/packages/3-extensions/sqlite/src/contract/define-contract.ts
@@ -6,7 +6,7 @@ import type {
   ContractInput,
   ModelLike,
 } from '@prisma-next/sql-contract-ts/contract-builder';
-import { defineContract as baseDefineContract } from '@prisma-next/sql-contract-ts/contract-builder';
+import { buildBoundContract } from '@prisma-next/sql-contract-ts/contract-builder';
 import { sqliteCreateNamespace } from '@prisma-next/target-sqlite/control';
 import sqlitePack from '@prisma-next/target-sqlite/pack';
 
@@ -20,13 +20,13 @@ type SqliteResult<
   Types extends TypesConstraint,
   Models extends ModelsConstraint,
   ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
-> = Omit<
-  ReturnType<typeof baseDefineContract<SqlFamily, SqlitePack, Types, Models, ExtensionPacks>>,
-  'target' | 'targetFamily'
-> & {
-  readonly target: SqlitePack['targetId'];
-  readonly targetFamily: SqlFamily['familyId'];
-};
+> = ReturnType<
+  typeof buildBoundContract<
+    SqlFamily,
+    SqlitePack,
+    { readonly types?: Types; readonly models?: Models; readonly extensionPacks?: ExtensionPacks }
+  >
+>;
 
 type SqliteBaseScaffold<
   ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
@@ -48,10 +48,6 @@ type SqliteScaffold<
   ExtensionPacks extends Record<string, ExtensionPackRef<'sql', string>> | undefined,
 > = SqliteBaseScaffold<ExtensionPacks>;
 
-const sqliteAuthoringDefaults = {
-  createNamespace: sqliteCreateNamespace,
-} as const;
-
 export function defineContract<
   const Types extends TypesConstraint = Record<never, never>,
   const Models extends ModelsConstraint = Record<never, never>,
@@ -76,29 +72,18 @@ export function defineContract<
   },
 ): SqliteResult<Types, Models, ExtensionPacks>;
 
+// Implementation — delegates to buildBoundContract which pre-binds family/target,
+// carrying zero casts at this layer.
 export function defineContract(
-  scaffold: Omit<ContractInput, 'family' | 'target'>,
+  definition: SqliteDefinition<TypesConstraint, ModelsConstraint, undefined>,
   factory?: (helpers: ComposedAuthoringHelpers<SqlFamily, SqlitePack, undefined>) => {
     readonly types?: TypesConstraint;
     readonly models?: ModelsConstraint;
   },
 ): SqliteResult<TypesConstraint, ModelsConstraint, undefined> {
-  const full = {
-    ...scaffold,
-    ...sqliteAuthoringDefaults,
-    family: sqlFamilyPack,
-    target: sqlitePack,
-  } as ContractInput;
+  const bound = { ...definition, createNamespace: sqliteCreateNamespace };
   if (factory !== undefined) {
-    const { types: _t, models: _m, ...scaffoldOnly } = full;
-    return baseDefineContract(
-      { ...scaffoldOnly, ...sqliteAuthoringDefaults },
-      factory as Parameters<typeof baseDefineContract>[1],
-    ) as unknown as SqliteResult<TypesConstraint, ModelsConstraint, undefined>;
+    return buildBoundContract(sqlFamilyPack, sqlitePack, bound, factory);
   }
-  return baseDefineContract(full) as unknown as SqliteResult<
-    TypesConstraint,
-    ModelsConstraint,
-    undefined
-  >;
+  return buildBoundContract(sqlFamilyPack, sqlitePack, bound);
 }
diff --git a/skills/extension-author/prisma-next-extension-upgrade/upgrades/0.12-to-0.13/instructions.md b/skills/extension-author/prisma-next-extension-upgrade/upgrades/0.12-to-0.13/instructions.md
@@ -18,3 +18,7 @@ defineContract wrapper to eliminate bare casts via a shared bound
 contract builder. No extension API or behaviour change; incidental
 substrate diff only.
 -->
+
+# 0.12 → 0.13 — Extension-author upgrade instructions
+
+No extension-author action required for this transition. The `defineContract` wrappers in the `@prisma-next/postgres` and `@prisma-next/sqlite` packages were refactored to be cast-free via a shared `buildBoundContract` helper in `@prisma-next/sql-contract-ts`; the consumer-facing API and emitted contract shapes are unchanged.
