@prisma-next/sql-contract-ts 0.9.0 → 0.10.0

package/src/contract-dsl.ts

@@ -14,8 +14,10 @@ import type {
   FamilyPackRef,
   TargetPackRef,
 } from '@prisma-next/framework-components/components';
+import type { Namespace } from '@prisma-next/framework-components/ir';
 import type {
   PostgresEnumStorageEntry,
+  SqlNamespaceTablesInput,
   StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
 import { ifDefined } from '@prisma-next/utils/defined';
@@ -998,6 +1000,7 @@ export class ContractModelBuilder<
   constructor(
     readonly stageOne: {
       readonly modelName?: ModelName;
+      readonly namespace?: string;
       readonly fields: Fields;
       readonly relations: Relations;
     },
@@ -1215,6 +1218,51 @@ export type ContractInput<
   readonly storageHash?: string;
   readonly foreignKeyDefaults?: ForeignKeyDefaultsState;
   readonly capabilities?: Capabilities;
+  /**
+   * Declared namespace coordinates the contract recognises. Per-model
+   * `namespace` references must reference an entry in this list (or the
+   * Postgres-specific late-binding keyword `unbound`). Reserved values:
+   *
+   * - `__unbound__` — IR sentinel for the late-binding slot.
+   * - `__unspecified__` — parser-synthesised AST bucket for top-level
+   *   declarations (not a real namespace).
+   * - `unbound` — Postgres-specific reserved keyword (the PSL surface
+   *   uses `namespace unbound { … }` to opt into late binding).
+   *
+   * SQLite contracts must declare an empty list (or omit the field) —
+   * SQLite has no schema concept and emits unqualified DDL.
+   *
+   * Populates `SqlStorage.namespaces` together with the
+   * {@link ContractInput.createNamespace} factory: each declared name
+   * (plus the framework-reserved `UNBOUND_NAMESPACE_ID` sentinel) is
+   * resolved through `createNamespace` and stored as the matching slot
+   * value. Models reference declared namespaces via their per-model
+   * `namespace` coordinate; entries that go unreferenced still occupy a
+   * slot so contracts that pre-declare schemas surface them on the live
+   * storage walk.
+   */
+  readonly namespaces?: readonly string[];
+  /**
+   * Target-supplied factory that materialises a `Namespace` concretion
+   * for a declared namespace coordinate. The SQL family layer is
+   * target-agnostic and cannot import concretions like
+   * `PostgresSchema` or `SqliteUnboundDatabase`; the factory is the
+   * seam by which target packs hand the family the right runtime
+   * representation.
+   *
+   * Called once per distinct namespace id discovered in the contract:
+   * each entry of {@link ContractInput.namespaces}, every
+   * `StorageTable.namespaceId` referenced by a model, and the
+   * framework `UNBOUND_NAMESPACE_ID` sentinel (always present so the
+   * late-bound slot stays available regardless of authoring choices).
+   *
+   * When omitted, the family layer falls back to its placeholder
+   * `SqlUnboundNamespace` singleton for the unbound slot and rejects
+   * any non-unbound coordinate — single-namespace contracts authored
+   * before targets ship their factory stay byte-stable; multi-namespace
+   * contracts must pass the factory through.
+   */
+  readonly createNamespace?: (input: SqlNamespaceTablesInput) => Namespace;
   readonly types?: Types;
   readonly models?: Models;
   readonly codecLookup?: CodecLookup;
@@ -1229,6 +1277,7 @@ export function model<
   input: {
     readonly fields: Fields;
     readonly relations?: Relations;
+    readonly namespace?: string;
   },
 ): ContractModelBuilder<ModelName, Fields, Relations>;
 
@@ -1238,6 +1287,7 @@ export function model<
 >(input: {
   readonly fields: Fields;
   readonly relations?: Relations;
+  readonly namespace?: string;
 }): ContractModelBuilder<undefined, Fields, Relations>;
 
 export function model<
@@ -1250,10 +1300,12 @@ export function model<
     | {
         readonly fields: Fields;
         readonly relations?: Relations;
+        readonly namespace?: string;
       },
   maybeInput?: {
     readonly fields: Fields;
     readonly relations?: Relations;
+    readonly namespace?: string;
   },
 ): ContractModelBuilder<ModelName | undefined, Fields, Relations> {
   const input = typeof modelNameOrInput === 'string' ? maybeInput : modelNameOrInput;
@@ -1264,6 +1316,7 @@ export function model<
 
   return new ContractModelBuilder({
     ...(typeof modelNameOrInput === 'string' ? { modelName: modelNameOrInput } : {}),
+    ...(input.namespace !== undefined ? { namespace: input.namespace } : {}),
     fields: input.fields,
     relations: (input.relations ?? {}) as Relations,
   });

package/src/contract-lowering.ts

@@ -47,6 +47,7 @@ type RuntimeModel = ContractModelBuilder<
 type RuntimeModelSpec = {
   readonly modelName: string;
   readonly tableName: string;
+  readonly namespace: string | undefined;
   readonly fieldBuilders: Record<string, ScalarFieldBuilder>;
   readonly fieldToColumn: Record<string, string>;
   readonly relations: Record<string, RelationBuilder<RelationState>>;
@@ -595,6 +596,7 @@ function resolveModelNode(
   return {
     modelName: spec.modelName,
     tableName: spec.tableName,
+    ...(spec.namespace !== undefined ? { namespaceId: spec.namespace } : {}),
     fields,
     ...(idConstraint
       ? {
@@ -668,6 +670,7 @@ function collectRuntimeModelSpecs(definition: ContractInput): RuntimeCollection
     modelSpecs.set(modelName, {
       modelName,
       tableName,
+      namespace: modelDefinition.stageOne.namespace,
       fieldBuilders,
       fieldToColumn,
       relations: modelDefinition.stageOne.relations,
@@ -711,6 +714,8 @@ export function buildContractDefinition(definition: ContractInput): ContractDefi
     ...(Object.keys(collection.storageTypes).length > 0
       ? { storageTypes: collection.storageTypes }
       : {}),
+    ...(definition.namespaces ? { namespaces: definition.namespaces } : {}),
+    ...(definition.createNamespace ? { createNamespace: definition.createNamespace } : {}),
     models,
   };
 }

package/src/contract-types.ts

@@ -5,7 +5,6 @@ import type {
   StorageHashBase,
 } from '@prisma-next/contract/types';
 import type { ExtensionPackRef, TargetPackRef } from '@prisma-next/framework-components/components';
-import type { Namespace } from '@prisma-next/framework-components/ir';
 import type { IndexTypeRegistration } from '@prisma-next/sql-contract/index-types';
 import type {
   ContractWithTypeMaps,
@@ -107,6 +106,16 @@ type DefinitionModels<Definition> = Definition extends {
     : Record<never, never>
   : Record<never, never>;
 
+type DefinitionNamespaces<Definition> = Definition extends {
+  readonly namespaces?: infer Names extends readonly string[];
+}
+  ? string[] extends Names
+    ? never
+    : readonly string[] extends Names
+      ? never
+      : Names[number]
+  : never;
+
 type DefinitionTypes<Definition> = Definition extends {
   readonly types?: unknown;
 }
@@ -499,8 +508,16 @@ type BuiltStorageTables<Definition> = {
     }>;
     readonly indexes: ReadonlyArray<Index>;
     readonly foreignKeys: ReadonlyArray<{
-      readonly columns: readonly string[];
-      readonly references: { readonly table: string; readonly columns: readonly string[] };
+      readonly source: {
+        readonly namespaceId: string;
+        readonly tableName: string;
+        readonly columns: readonly string[];
+      };
+      readonly target: {
+        readonly namespaceId: string;
+        readonly tableName: string;
+        readonly columns: readonly string[];
+      };
       readonly name?: string;
       readonly onDelete?: ReferentialAction;
       readonly onUpdate?: ReferentialAction;
@@ -521,11 +538,39 @@ type BuiltStorageTables<Definition> = {
     : Record<string, never>);
 };
 
+type BuiltStorageTypes<Definition> = {
+  readonly [K in keyof DefinitionTypes<Definition> as DefinitionTypes<Definition>[K] extends PostgresEnumStorageEntry
+    ? never
+    : K]: DefinitionTypes<Definition>[K];
+};
+
 type BuiltStorage<Definition> = {
   readonly storageHash: StorageHashBase<string>;
-  readonly tables: BuiltStorageTables<Definition>;
-  readonly types: DefinitionTypes<Definition>;
-  readonly namespaces: Readonly<Record<string, Namespace>>;
+  readonly types: BuiltStorageTypes<Definition>;
+  // SQL contracts always carry a literal `__unbound__` namespace whose tables
+  // slot is narrowed to the actual built table shape so downstream DSL
+  // surfaces (TableProxyContract, Ref, SelectBuilder) keep literal-keyed
+  // access without an optional-narrowing dance. The shape is described
+  // inline (rather than intersecting with `SqlStorage['namespaces']`) so
+  // its `Readonly<Record<string, Namespace>>` index signature doesn't
+  // collapse `keyof tables` to `string`. The literal object is still
+  // structurally assignable to `SqlStorage['namespaces']` because every
+  // value satisfies the framework `Namespace` interface.
+  readonly namespaces: {
+    readonly __unbound__: {
+      readonly id: '__unbound__';
+      readonly kind?: string;
+      readonly tables: BuiltStorageTables<Definition>;
+      readonly types?: Readonly<Record<string, PostgresEnumStorageEntry>>;
+    };
+  } & {
+    readonly [Ns in Exclude<DefinitionNamespaces<Definition>, '__unbound__'>]: {
+      readonly id: Ns;
+      readonly kind?: string;
+      readonly tables: Record<never, never>;
+      readonly types?: Readonly<Record<string, PostgresEnumStorageEntry>>;
+    };
+  };
 };
 
 type FieldOutputType<