@prisma-next/family-sql 0.9.0 → 0.10.0-dev.2

package/package.json

@@ -1,34 +1,34 @@
 {
   "name": "@prisma-next/family-sql",
-  "version": "0.9.0",
+  "version": "0.10.0-dev.2",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "SQL family descriptor for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.9.0",
-    "@prisma-next/emitter": "0.9.0",
-    "@prisma-next/framework-components": "0.9.0",
-    "@prisma-next/migration-tools": "0.9.0",
-    "@prisma-next/operations": "0.9.0",
-    "@prisma-next/sql-contract": "0.9.0",
-    "@prisma-next/sql-contract-emitter": "0.9.0",
-    "@prisma-next/sql-contract-ts": "0.9.0",
-    "@prisma-next/sql-operations": "0.9.0",
-    "@prisma-next/sql-relational-core": "0.9.0",
-    "@prisma-next/sql-runtime": "0.9.0",
-    "@prisma-next/sql-schema-ir": "0.9.0",
-    "@prisma-next/utils": "0.9.0",
+    "@prisma-next/contract": "0.10.0-dev.2",
+    "@prisma-next/emitter": "0.10.0-dev.2",
+    "@prisma-next/framework-components": "0.10.0-dev.2",
+    "@prisma-next/migration-tools": "0.10.0-dev.2",
+    "@prisma-next/operations": "0.10.0-dev.2",
+    "@prisma-next/sql-contract": "0.10.0-dev.2",
+    "@prisma-next/sql-contract-emitter": "0.10.0-dev.2",
+    "@prisma-next/sql-contract-ts": "0.10.0-dev.2",
+    "@prisma-next/sql-operations": "0.10.0-dev.2",
+    "@prisma-next/sql-relational-core": "0.10.0-dev.2",
+    "@prisma-next/sql-runtime": "0.10.0-dev.2",
+    "@prisma-next/sql-schema-ir": "0.10.0-dev.2",
+    "@prisma-next/utils": "0.10.0-dev.2",
     "arktype": "^2.2.0"
   },
   "devDependencies": {
-    "@prisma-next/driver-postgres": "0.9.0",
-    "@prisma-next/psl-parser": "0.9.0",
-    "@prisma-next/psl-printer": "0.9.0",
-    "@prisma-next/sql-contract-psl": "0.9.0",
-    "@prisma-next/test-utils": "0.9.0",
-    "@prisma-next/tsconfig": "0.9.0",
-    "@prisma-next/tsdown": "0.9.0",
+    "@prisma-next/driver-postgres": "0.10.0-dev.2",
+    "@prisma-next/psl-parser": "0.10.0-dev.2",
+    "@prisma-next/psl-printer": "0.10.0-dev.2",
+    "@prisma-next/sql-contract-psl": "0.10.0-dev.2",
+    "@prisma-next/test-utils": "0.10.0-dev.2",
+    "@prisma-next/tsconfig": "0.10.0-dev.2",
+    "@prisma-next/tsdown": "0.10.0-dev.2",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",
     "vitest": "4.1.6"

package/src/core/control-instance.ts

@@ -62,11 +62,18 @@ function extractCodecTypeIdsFromContract(contract: unknown): readonly string[] {
     'storage' in contract &&
     typeof contract.storage === 'object' &&
     contract.storage !== null &&
-    'tables' in contract.storage
+    'namespaces' in contract.storage &&
+    typeof contract.storage.namespaces === 'object' &&
+    contract.storage.namespaces !== null
   ) {
-    const storage = contract.storage as { tables?: Record<string, unknown> };
-    if (storage.tables && typeof storage.tables === 'object') {
-      for (const table of Object.values(storage.tables)) {
+    const namespaces = contract.storage.namespaces as Record<
+      string,
+      { readonly tables?: Readonly<Record<string, unknown>> }
+    >;
+    for (const ns of Object.values(namespaces)) {
+      const tbls = ns.tables;
+      if (typeof tbls !== 'object' || tbls === null) continue;
+      for (const table of Object.values(tbls)) {
         if (
           typeof table === 'object' &&
           table !== null &&

package/src/core/ir/sql-contract-serializer-base.ts

@@ -1,6 +1,14 @@
+import { ContractValidationError } from '@prisma-next/contract/contract-validation-error';
 import type { Contract } from '@prisma-next/contract/types';
 import type { ContractSerializer } from '@prisma-next/framework-components/control';
-import { SqlStorage, type SqlStorageTypeEntry } from '@prisma-next/sql-contract/types';
+import { type Namespace, NamespaceBase } from '@prisma-next/framework-components/ir';
+import {
+  type SqlNamespaceTablesInput,
+  SqlStorage,
+  type SqlStorageTypeEntry,
+  StorageTable,
+  type StorageTableInput,
+} from '@prisma-next/sql-contract/types';
 import { validateSqlContractFully } from '@prisma-next/sql-contract/validators';
 import type { JsonObject } from '@prisma-next/utils/json';
 
@@ -37,51 +45,20 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
     private readonly entityTypeRegistry: ReadonlyMap<string, SqlEntityHydrationFactory>,
   ) {}
 
-  deserializeContract(json: unknown): TContract {
+  deserializeContract<T extends TContract = TContract>(json: unknown): T {
     const validated = this.parseSqlContractStructure(json);
     const hydrated = this.hydrateSqlStorage(validated);
-    return this.constructTargetContract(hydrated);
+    return this.constructTargetContract(hydrated) as T;
   }
 
   serializeContract(contract: TContract): JsonObject {
-    // Targets that ship enumerable runtime-only fields must override
-    // this method (mirroring `MongoTargetContractSerializer.serializeContract`)
-    // to construct the persisted envelope explicitly; the default identity
-    // works only when every enumerable own property belongs in the JSON.
     return contract as unknown as JsonObject;
   }
 
-  /**
-   * Family-shared validation pipeline (delegates to
-   * `validateSqlContractFully` in `@prisma-next/sql-contract/validators`):
-   * structural arktype + framework-shared domain + SQL storage
-   * logical-consistency + SQL storage semantic + model ↔ storage
-   * reference checks. Subclasses override to add target-specific
-   * structural checks before hydration; the family default suffices
-   * for targets whose contract shape is the SQL-shared shape
-   * (Postgres, SQLite today).
-   */
   protected parseSqlContractStructure(json: unknown): Contract<SqlStorage> {
     return validateSqlContractFully<Contract<SqlStorage>>(json);
   }
 
-  /**
-   * Family-shared hydration walker. Lifts the validated flat-data
-   * `storage` subtree into the SQL Contract IR class hierarchy by
-   * constructing a single `SqlStorage` instance — its constructor
-   * cascades nested instantiation of `StorageTable`, `StorageColumn`,
-   * `PrimaryKey`, `UniqueConstraint`, `Index`, `ForeignKey`,
-   * `ForeignKeyReferences`, and `StorageTypeInstance`. The rest of the
-   * contract envelope (target identity, hashes, capabilities, models,
-   * meta, …) is JSON-clean primitive data and passes through unchanged.
-   *
-   * Polymorphic `storage.types` entries are normalised before the
-   * `SqlStorage` constructor runs: when an entry carries an enumerable
-   * string `kind`, the serializer looks up a pack-registered hydration
-   * factory for that discriminator and delegates reconstruction. Entries
-   * with no registered factory pass through unchanged (codec-typed JSON
-   * stays codec-typed until `SqlStorage` normalises it).
-   */
   protected hydrateSqlStorage(validated: Contract<SqlStorage>): Contract<SqlStorage> {
     const types = validated.storage.types;
     const hydratedTypes =
@@ -94,21 +71,61 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
           )
         : undefined;
 
+    const rawNamespaces = validated.storage.namespaces;
+    const hydratedNamespaces =
+      rawNamespaces !== undefined ? this.hydrateSqlNamespaceMap(rawNamespaces) : undefined;
+
     return {
       ...validated,
       storage: new SqlStorage({
-        ...validated.storage,
+        storageHash: validated.storage.storageHash,
         ...(hydratedTypes !== undefined ? { types: hydratedTypes } : {}),
+        ...(hydratedNamespaces !== undefined ? { namespaces: hydratedNamespaces } : {}),
       }),
     };
   }
 
-  /**
-   * Per-entry hydration dispatcher for `storage.types`. When `kind` is a
-   * string and the constructor registry supplies a factory for that key,
-   * the factory returns the hydrated `SqlStorageTypeEntry`. Otherwise the
-   * entry passes through unchanged for `SqlStorage` to normalise.
-   */
+  protected hydrateSqlNamespaceMap(
+    namespaces: Readonly<Record<string, Namespace | Record<string, unknown>>>,
+  ): Readonly<Record<string, Namespace | SqlNamespaceTablesInput>> {
+    return Object.fromEntries(
+      Object.entries(namespaces).map(([nsId, raw]) => [
+        nsId,
+        this.hydrateSqlNamespaceEntry(nsId, raw),
+      ]),
+    );
+  }
+
+  protected hydrateSqlNamespaceEntry(
+    nsId: string,
+    raw: Namespace | Record<string, unknown>,
+  ): Namespace | SqlNamespaceTablesInput {
+    if (raw instanceof NamespaceBase) {
+      return raw;
+    }
+    const obj = raw as {
+      id?: string;
+      tables?: Record<string, unknown>;
+      types?: Record<string, unknown>;
+    };
+    if (obj.types !== undefined && Object.keys(obj.types).length > 0) {
+      throw new ContractValidationError(
+        'Per-schema database types (e.g. postgres-enum) under storage.namespaces[..].types require PostgresContractSerializer.',
+        'structural',
+      );
+    }
+    const tables = Object.fromEntries(
+      Object.entries(obj.tables ?? {}).map(([tableName, table]) => [
+        tableName,
+        table instanceof StorageTable ? table : new StorageTable(table as StorageTableInput),
+      ]),
+    );
+    return {
+      id: obj.id ?? nsId,
+      tables,
+    };
+  }
+
   protected hydrateStorageTypeEntry(entry: SqlStorageTypeEntry): SqlStorageTypeEntry {
     if (typeof entry !== 'object' || entry === null) {
       return entry;
@@ -124,12 +141,6 @@ export abstract class SqlContractSerializerBase<TContract extends Contract<SqlSt
     return factory(entry);
   }
 
-  /**
-   * Target-specific construction hook. Defaults to identity; targets
-   * that need to wrap the hydrated contract (e.g. attach target-only
-   * derived fields, narrow the contract type to a target-specific
-   * subtype) override.
-   */
   protected constructTargetContract(hydrated: Contract<SqlStorage>): TContract {
     return hydrated as TContract;
   }

package/src/core/migrations/contract-to-schema-ir.ts

@@ -8,7 +8,7 @@ import {
   type PostgresEnumStorageEntry,
   type SqlStorage,
   type StorageColumn,
-  type StorageTable,
+  StorageTable,
   type StorageTypeInstance,
   toStorageTypeInstance,
   type UniqueConstraint,
@@ -147,9 +147,10 @@ function convertIndex(index: Index): SqlIndexIR {
 
 function convertForeignKey(fk: ForeignKey): SqlForeignKeyIR {
   return {
-    columns: fk.columns,
-    referencedTable: fk.references.table,
-    referencedColumns: fk.references.columns,
+    columns: fk.source.columns,
+    referencedTable: fk.target.tableName,
+    referencedSchema: fk.target.namespaceId,
+    referencedColumns: fk.target.columns,
     ...ifDefined('name', fk.name),
   };
 }
@@ -180,12 +181,12 @@ function convertTable(
   const fkBackingIndexes: SqlIndexIR[] = [];
   for (const fk of table.foreignKeys) {
     if (fk.index === false) continue;
-    const key = fk.columns.join(',');
+    const key = fk.source.columns.join(',');
     if (satisfiedIndexColumns.has(key)) continue;
     fkBackingIndexes.push({
-      columns: fk.columns,
+      columns: fk.source.columns,
       unique: false,
-      name: defaultIndexName(name, fk.columns),
+      name: defaultIndexName(name, fk.source.columns),
     });
     satisfiedIndexColumns.add(key);
   }
@@ -219,25 +220,38 @@ export function detectDestructiveChanges(
 
   const conflicts: MigrationPlannerConflict[] = [];
 
-  for (const tableName of Object.keys(from.tables)) {
-    if (!hasOwn(to.tables, tableName)) {
-      conflicts.push({
-        kind: 'tableRemoved',
-        summary: `Table "${tableName}" was removed`,
-      });
-      continue;
-    }
+  const namespaceIds = [
+    ...new Set([...Object.keys(from.namespaces), ...Object.keys(to.namespaces)]),
+  ].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 
-    const toTable = to.tables[tableName] as StorageTable;
-    const fromTable = from.tables[tableName];
-    if (!fromTable) continue;
+  for (const namespaceId of namespaceIds) {
+    const fromNs = from.namespaces[namespaceId];
+    const toNs = to.namespaces[namespaceId];
+    const fromTables = fromNs?.tables;
+    if (!fromTables) continue;
 
-    for (const columnName of Object.keys(fromTable.columns)) {
-      if (!hasOwn(toTable.columns, columnName)) {
+    for (const tableName of Object.keys(fromTables)) {
+      const toTableRaw = toNs?.tables[tableName];
+      if (!(toTableRaw instanceof StorageTable)) {
         conflicts.push({
-          kind: 'columnRemoved',
-          summary: `Column "${tableName}"."${columnName}" was removed`,
+          kind: 'tableRemoved',
+          summary: `Table "${tableName}" was removed`,
         });
+        continue;
+      }
+      const toTable = toTableRaw;
+
+      const fromTableRaw = fromTables[tableName];
+      if (!(fromTableRaw instanceof StorageTable)) continue;
+      const fromTable = fromTableRaw;
+
+      for (const columnName of Object.keys(fromTable.columns)) {
+        if (!hasOwn(toTable.columns, columnName)) {
+          conflicts.push({
+            kind: 'columnRemoved',
+            summary: `Column "${tableName}"."${columnName}" was removed`,
+          });
+        }
       }
     }
   }
@@ -278,16 +292,40 @@ export function contractToSchemaIR(
   }
 
   const storage = contract.storage;
-  const storageTypes = (storage.types ?? {}) as ResolvedStorageTypes;
+  const allTypes: Record<string, StorageTypeInstance | PostgresEnumStorageEntry> = {
+    ...((storage.types ?? {}) as ResolvedStorageTypes),
+  };
+  for (const ns of Object.values(storage.namespaces)) {
+    const nsTypes = (ns as { types?: Record<string, PostgresEnumStorageEntry> }).types;
+    if (nsTypes) {
+      for (const [k, v] of Object.entries(nsTypes)) {
+        allTypes[k] = v;
+      }
+    }
+  }
+  const storageTypes = allTypes as ResolvedStorageTypes;
   const tables: Record<string, SqlTableIR> = {};
-  for (const [tableName, tableDef] of Object.entries(storage.tables)) {
-    tables[tableName] = convertTable(
-      tableName,
-      tableDef,
-      storageTypes,
-      options.expandNativeType,
-      options.renderDefault,
-    );
+  for (const ns of Object.values(storage.namespaces)) {
+    for (const [tableName, tableDefRaw] of Object.entries(ns.tables)) {
+      if (!(tableDefRaw instanceof StorageTable)) {
+        throw new Error(
+          `contractToSchemaIR: expected StorageTable at namespaces.${ns.id}.tables.${tableName}`,
+        );
+      }
+      const tableDef = tableDefRaw;
+      if (tables[tableName] !== undefined) {
+        throw new Error(
+          `contractToSchemaIR: duplicate SQL table name "${tableName}" across namespaces (ambiguous for flat SqlSchemaIR.tables).`,
+        );
+      }
+      tables[tableName] = convertTable(
+        tableName,
+        tableDef,
+        storageTypes,
+        options.expandNativeType,
+        options.renderDefault,
+      );
+    }
   }
 
   const annotations = deriveAnnotations(storage, options.annotationNamespace);
@@ -302,8 +340,19 @@ function deriveAnnotations(
   storage: SqlStorage,
   annotationNamespace: string,
 ): SqlAnnotations | undefined {
-  const types = storage.types as ResolvedStorageTypes | undefined;
-  if (!types || Object.keys(types).length === 0) return undefined;
+  const allTypes: Record<string, StorageTypeInstance | PostgresEnumStorageEntry> = {
+    ...((storage.types ?? {}) as ResolvedStorageTypes),
+  };
+  for (const ns of Object.values(storage.namespaces)) {
+    const nsTypes = (ns as { types?: Record<string, PostgresEnumStorageEntry> }).types;
+    if (nsTypes) {
+      for (const [k, v] of Object.entries(nsTypes)) {
+        allTypes[k] = v;
+      }
+    }
+  }
+  const types = allTypes as ResolvedStorageTypes;
+  if (Object.keys(types).length === 0) return undefined;
   // Re-key by nativeType, normalising every variant to the codec-typed
   // annotation shape `{codecId, nativeType, typeParams}` produced by the
   // adapter introspector (`introspectPostgresEnumTypes` writes that shape;

package/src/core/migrations/field-event-planner.ts

@@ -13,7 +13,7 @@
  *
  * - Events are grouped by phase: `'added'` → `'dropped'` → `'altered'`.
  * - Within each phase, entries are sorted alphabetically by
- *   `(tableName, fieldName)`.
+ *   `(namespaceId, tableName, fieldName)`.
  * - The hook's returned ops are appended in the order the hook returned them.
  *
  * `'altered'` is suppressed when only `codecId` differs (codec rotation is a
@@ -24,7 +24,7 @@
 
 import type { Contract } from '@prisma-next/contract/types';
 import type { OpFactoryCall } from '@prisma-next/framework-components/control';
-import type { SqlStorage, StorageColumn, StorageTable } from '@prisma-next/sql-contract/types';
+import { type SqlStorage, type StorageColumn, StorageTable } from '@prisma-next/sql-contract/types';
 import type { CodecControlHooks, FieldEvent, FieldEventContext } from './types';
 
 export interface PlanFieldEventOperationsOptions {
@@ -50,6 +50,7 @@ export interface PlanFieldEventOperationsOptions {
 }
 
 interface FieldEntry {
+  readonly namespaceId: string;
   readonly tableName: string;
   readonly fieldName: string;
   readonly priorTable: StorageTable | undefined;
@@ -61,38 +62,57 @@ interface FieldEntry {
 export function planFieldEventOperations(
   options: PlanFieldEventOperationsOptions,
 ): readonly OpFactoryCall[] {
-  const priorTables = options.priorContract?.storage.tables ?? {};
-  const newTables = options.newContract.storage.tables;
+  const priorContract = options.priorContract;
+  const newContract = options.newContract;
 
   const added: FieldEntry[] = [];
   const dropped: FieldEntry[] = [];
   const altered: FieldEntry[] = [];
 
-  const tableNames = unionSorted(Object.keys(priorTables), Object.keys(newTables));
-  for (const tableName of tableNames) {
-    const priorTable = priorTables[tableName];
-    const newTable = newTables[tableName];
-    const fieldNames = unionSorted(
-      priorTable ? Object.keys(priorTable.columns) : [],
-      newTable ? Object.keys(newTable.columns) : [],
+  const namespaceIds = unionSorted(
+    priorContract ? Object.keys(priorContract.storage.namespaces) : [],
+    Object.keys(newContract.storage.namespaces),
+  );
+
+  for (const namespaceId of namespaceIds) {
+    const priorNs = priorContract?.storage.namespaces[namespaceId];
+    const newNs = newContract.storage.namespaces[namespaceId];
+    const priorTables = priorNs?.tables;
+    const newTables = newNs?.tables;
+
+    const tableNames = unionSorted(
+      priorTables ? Object.keys(priorTables) : [],
+      newTables ? Object.keys(newTables) : [],
     );
-    for (const fieldName of fieldNames) {
-      const priorField = priorTable?.columns[fieldName];
-      const newField = newTable?.columns[fieldName];
-      const entry: FieldEntry = {
-        tableName,
-        fieldName,
-        priorTable,
-        newTable,
-        priorField,
-        newField,
-      };
-      if (priorField === undefined && newField !== undefined) {
-        added.push(entry);
-      } else if (priorField !== undefined && newField === undefined) {
-        dropped.push(entry);
-      } else if (priorField !== undefined && newField !== undefined) {
-        if (isAlteration(priorField, newField)) altered.push(entry);
+
+    for (const tableName of tableNames) {
+      const priorTableRaw = priorTables?.[tableName];
+      const newTableRaw = newTables?.[tableName];
+      const priorTable = priorTableRaw instanceof StorageTable ? priorTableRaw : undefined;
+      const newTable = newTableRaw instanceof StorageTable ? newTableRaw : undefined;
+      const fieldNames = unionSorted(
+        priorTable ? Object.keys(priorTable.columns) : [],
+        newTable ? Object.keys(newTable.columns) : [],
+      );
+      for (const fieldName of fieldNames) {
+        const priorField = priorTable?.columns[fieldName];
+        const newField = newTable?.columns[fieldName];
+        const entry: FieldEntry = {
+          namespaceId,
+          tableName,
+          fieldName,
+          priorTable,
+          newTable,
+          priorField,
+          newField,
+        };
+        if (priorField === undefined && newField !== undefined) {
+          added.push(entry);
+        } else if (priorField !== undefined && newField === undefined) {
+          dropped.push(entry);
+        } else if (priorField !== undefined && newField !== undefined) {
+          if (isAlteration(priorField, newField)) altered.push(entry);
+        }
       }
     }
   }
@@ -130,7 +150,11 @@ function appendCalls(
  * - `'altered'` — both sides populated.
  */
 function buildContext(event: FieldEvent, entry: FieldEntry): FieldEventContext {
-  const base = { tableName: entry.tableName, fieldName: entry.fieldName };
+  const base = {
+    namespaceId: entry.namespaceId,
+    tableName: entry.tableName,
+    fieldName: entry.fieldName,
+  };
   if (event === 'added') {
     return {
       ...base,

package/src/core/migrations/types.ts

@@ -79,7 +79,7 @@ export type FieldEvent = 'added' | 'dropped' | 'altered';
 /**
  * Context passed to {@link CodecControlHooks.onFieldEvent}.
  *
- * `tableName` and `fieldName` are always populated; `priorTable` /
+ * `namespaceId`, `tableName`, and `fieldName` are always populated; `priorTable` /
  * `priorField` carry the prior contract's view of the table and column
  * (present for `'dropped'` and `'altered'`); `newTable` / `newField`
  * carry the new contract's view (present for `'added'` and `'altered'`).
@@ -89,6 +89,7 @@ export type FieldEvent = 'added' | 'dropped' | 'altered';
  * application emitter only.
  */
 export interface FieldEventContext {
+  readonly namespaceId: string;
   readonly tableName: string;
   readonly fieldName: string;
   readonly priorTable?: StorageTable;

package/src/core/psl-contract-infer/sql-schema-ir-to-psl-ast.ts

@@ -12,6 +12,7 @@ import type {
   PslSpan,
   PslTypesBlock,
 } from '@prisma-next/framework-components/psl-ast';
+import { UNSPECIFIED_PSL_NAMESPACE_ID } from '@prisma-next/framework-components/psl-ast';
 import type { SqlColumnIR, SqlSchemaIR, SqlTableIR } from '@prisma-next/sql-schema-ir/types';
 import type { DefaultMappingOptions } from './default-mapping';
 import { mapDefault } from './default-mapping';
@@ -153,12 +154,25 @@ function buildPslDocumentAst(schemaIR: SqlSchemaIR, options: PslPrinterOptions):
         }
       : undefined;
 
+  // Inferred PSL nodes will eventually be routed into per-namespace buckets
+  // matching the source storage; for now we synthesise a single
+  // `__unspecified__` bucket so round-tripping the AST through the framework
+  // printer (which emits the synthesised bucket at top level with no
+  // `namespace { … }` wrapper) preserves the existing introspection output
+  // verbatim.
   const ast: PslDocumentAst = {
     kind: 'document',
     sourceId: '<sql-schema-ir>',
-    models: sortedModels,
-    enums,
-    compositeTypes: [],
+    namespaces: [
+      {
+        kind: 'namespace',
+        name: UNSPECIFIED_PSL_NAMESPACE_ID,
+        models: sortedModels,
+        enums,
+        compositeTypes: [],
+        span: SYNTHETIC_SPAN,
+      },
+    ],
     ...(types ? { types } : {}),
     span: SYNTHETIC_SPAN,
   };