@prisma-next/sql-contract 0.14.0-dev.4 → 0.14.0-dev.41

package/src/exports/contract-view.ts

@@ -0,0 +1,11 @@
+export type {
+  SqlBuiltinKind,
+  SqlSchemaQualifiedView,
+  SqlSingleNamespaceAccessors,
+  SqlSingleNamespaceView,
+} from '../contract-view';
+export {
+  buildSqlSchemaQualifiedView,
+  buildSqlSingleNamespaceView,
+  SQL_BUILTIN_KINDS,
+} from '../contract-view';

package/src/exports/types.ts

@@ -1,3 +1,7 @@
+export type {
+  StorageColumnMapAt,
+  StorageColumnTypeAcrossNamespaces,
+} from '../column-type-resolution';
 export type {
   CheckConstraintInput,
   CodecTypesOf,
@@ -6,6 +10,8 @@ export type {
   ExtractFieldInputTypes,
   ExtractFieldOutputTypes,
   ExtractQueryOperationTypes,
+  ExtractStorageColumnInputTypes,
+  ExtractStorageColumnTypes,
   ExtractTypeMapsFromContract,
   FieldInputTypesOf,
   FieldOutputTypesOf,
@@ -13,6 +19,8 @@ export type {
   ForeignKeyOptions,
   ForeignKeyReferenceInput,
   IndexInput,
+  NamespacedFieldTypeMap,
+  NamespacedStorageColumnTypeMap,
   PrimaryKeyInput,
   QueryOperationReturn,
   QueryOperationSelfSpec,
@@ -21,16 +29,20 @@ export type {
   QueryOperationTypesOf,
   ReferentialAction,
   ResolveCodecTypes,
+  SqlAuthoringContributions,
   SqlControlDriverInstance,
   SqlModelFieldStorage,
   SqlModelStorage,
   SqlNamespace,
   SqlNamespaceEntries,
-  SqlNamespaceTablesInput,
+  SqlNamespaceFactory,
+  SqlNamespaceInput,
   SqlQueryOperationTypes,
   SqlStorageInput,
   SqlStorageTypeEntry,
   StorageColumnInput,
+  StorageColumnInputTypesOf,
+  StorageColumnTypesOf,
   StorageTableInput,
   StorageTypeInstance,
   StorageTypeInstanceInput,
@@ -41,8 +53,6 @@ export type {
 } from '../types';
 export {
   applyFkDefaults,
-  buildSqlNamespace,
-  buildSqlNamespaceMap,
   CheckConstraint,
   CODEC_INSTANCE_KIND,
   DEFAULT_FK_CONSTRAINT,
@@ -50,11 +60,14 @@ export {
   ForeignKey,
   ForeignKeyReference,
   Index,
+  isMaterializedSqlNamespace,
+  isSqlAuthoringContributions,
   isStorageTypeInstance,
+  isStorageValueSet,
   PrimaryKey,
+  SqlNamespaceBase,
   SqlNode,
   SqlStorage,
-  SqlUnboundNamespace,
   StorageColumn,
   StorageTable,
   StorageValueSet,

package/src/factories.ts

@@ -14,8 +14,18 @@ import {
   UniqueConstraint,
 } from './types';
 
-export function col(nativeType: string, codecId: string, nullable = false): StorageColumn {
-  return new StorageColumn({ nativeType, codecId, nullable });
+export function col(
+  nativeType: string,
+  codecId: string,
+  nullable = false,
+  opts?: { readonly many?: boolean },
+): StorageColumn {
+  return new StorageColumn({
+    nativeType,
+    codecId,
+    nullable,
+    ...(opts?.many !== undefined && { many: opts.many }),
+  });
 }
 
 export function pk(...columns: readonly string[]): PrimaryKey {

package/src/ir/sql-storage.ts

@@ -1,5 +1,12 @@
 import type { StorageHashBase } from '@prisma-next/contract/types';
-import { freezeNode, type Namespace, type Storage } from '@prisma-next/framework-components/ir';
+import type { AuthoringContributions } from '@prisma-next/framework-components/authoring';
+import {
+  freezeNode,
+  isPlainRecord,
+  type Namespace,
+  NamespaceBase,
+  type Storage,
+} from '@prisma-next/framework-components/ir';
 import { SqlNode } from './sql-node';
 import type { StorageTable } from './storage-table';
 import {
@@ -19,15 +26,45 @@ import type { StorageValueSet } from './storage-value-set';
  */
 export type SqlStorageTypeEntry = StorageTypeInstance | StorageTypeInstanceInput;
 
-export interface SqlNamespaceTablesInput {
+export interface SqlNamespaceInput {
   readonly id: string;
   readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
 }
 
+/**
+ * Target-supplied factory that materializes a `Namespace` from a SQL
+ * `SqlNamespaceInput` (used to populate `SqlStorage.namespaces`).
+ */
+export type SqlNamespaceFactory = (input: SqlNamespaceInput) => Namespace;
+
+/**
+ * SQL-family extension of the framework `AuthoringContributions`. SQL target
+ * packs add a `createNamespace` factory so the PSL/TS authoring paths can
+ * materialize namespaces (and merge lowered extension-block entities) without
+ * each consumer re-specifying it. The factory is SQL-specific, so it lives here
+ * rather than on the framework `AuthoringContributions` base.
+ */
+export interface SqlAuthoringContributions extends AuthoringContributions {
+  readonly createNamespace?: SqlNamespaceFactory;
+}
+
+/**
+ * Narrows framework `AuthoringContributions` to the SQL-family shape by testing
+ * for the SQL-specific `createNamespace` capability.
+ */
+export function isSqlAuthoringContributions(
+  authoring: AuthoringContributions | undefined,
+): authoring is SqlAuthoringContributions {
+  if (authoring === undefined || !Object.hasOwn(authoring, 'createNamespace')) {
+    return false;
+  }
+  return typeof Reflect.get(authoring, 'createNamespace') === 'function';
+}
+
 export interface SqlStorageInput<THash extends string = string> {
   readonly storageHash: StorageHashBase<THash>;
   readonly types?: Record<string, SqlStorageTypeEntry>;
-  readonly namespaces: Readonly<Record<string, SqlNamespace>>;
+  readonly namespaces: Readonly<Record<string, SqlNamespaceBase>>;
 }
 
 /**
@@ -63,22 +100,48 @@ export type SqlNamespaceEntries = Readonly<Record<string, Readonly<Record<string
 };
 
 /**
- * SQL family namespace. `entries` is the open ADR 224 dictionary —
- * `entries[entityKind][entityName]` addresses any entity. Emitted
- * contract literals satisfy this structurally (no prototype getters
- * needed). For typed access to specific kinds, use the class getters
- * on the concretion or `ns.entries.table` / `ns.entries.valueSet` directly.
+ * Structural interface for SQL family namespaces. Generated `.d.ts` contract
+ * types satisfy this structurally (no prototype methods). The runtime
+ * abstract class `SqlNamespaceBase` extends this.
+ *
+ * `qualifyTable` is optional so JSON-shaped contract types (which carry no
+ * methods) are accepted where `SqlNamespace` is required. Hydrated
+ * `SqlNamespaceBase` instances always have it.
  */
-export type SqlNamespace = Namespace & {
+export interface SqlNamespace {
+  readonly kind: string;
+  readonly id: string;
   readonly entries: SqlNamespaceEntries;
-  /**
-   * Render a dialect-qualified table reference for runtime SQL emission.
-   * Present on materialised target concretions (`PostgresSchema`,
-   * `SqliteDatabase`, …) and family placeholders; omitted on emitted
-   * contract structural namespace literals (methods are not serialised).
-   */
   qualifyTable?(tableName: string): string;
-};
+}
+
+/**
+ * Abstract SQL family namespace base class. Target concretions (`PostgresSchema`,
+ * `SqliteDatabase`, …) extend this — it is never instantiated directly.
+ * `entries` is the open ADR 224 dictionary: `entries[entityKind][entityName]`
+ * addresses any entity.
+ */
+export abstract class SqlNamespaceBase extends NamespaceBase implements SqlNamespace {
+  abstract override readonly id: string;
+  abstract override readonly entries: SqlNamespaceEntries;
+
+  abstract qualifyTable(tableName: string): string;
+}
+
+/**
+ * Realm-safe guard for hydrated `SqlNamespaceBase` concretions. Checks
+ * `qualifyTable` structurally instead of `instanceof NamespaceBase`, so it
+ * survives duplicate-module boundaries (e.g. dist e2e where the target and
+ * the family carry separate copies of `@prisma-next/framework-components`).
+ *
+ * Every concrete `SqlNamespaceBase` subclass (`PostgresSchema`, `SqliteDatabase`,
+ * `TestSqlNamespace`, …) implements `qualifyTable`. Raw `SqlNamespaceInput`
+ * objects (`{ id, entries }`) do not.
+ */
+export function isMaterializedSqlNamespace(x: unknown): x is SqlNamespaceBase {
+  if (typeof x !== 'object' || x === null || !('qualifyTable' in x)) return false;
+  return typeof x.qualifyTable === 'function';
+}
 
 export class SqlStorage<THash extends string = string> extends SqlNode implements Storage {
   readonly storageHash: StorageHashBase<THash>;
@@ -128,7 +191,7 @@ function normaliseTypeEntry(name: string, entry: SqlStorageTypeEntry): StorageTy
     }
     return toStorageTypeInstance(entry);
   }
-  const rawKind = (entry as { kind?: unknown }).kind;
+  const rawKind = isPlainRecord(entry) ? entry['kind'] : undefined;
   const kindDescription =
     rawKind === undefined
       ? 'missing `kind` discriminator'

package/src/ir/storage-column.ts

@@ -16,6 +16,7 @@ export interface StorageColumnInput {
   readonly nativeType: string;
   readonly codecId: string;
   readonly nullable: boolean;
+  readonly many?: boolean;
   readonly typeParams?: Record<string, unknown>;
   readonly typeRef?: string;
   readonly default?: ColumnDefault;
@@ -40,6 +41,7 @@ export class StorageColumn extends SqlNode {
   readonly nativeType: string;
   readonly codecId: string;
   readonly nullable: boolean;
+  declare readonly many?: boolean;
   declare readonly typeParams?: Record<string, unknown>;
   declare readonly typeRef?: string;
   declare readonly default?: ColumnDefault;
@@ -51,6 +53,7 @@ export class StorageColumn extends SqlNode {
     this.nativeType = input.nativeType;
     this.codecId = input.codecId;
     this.nullable = input.nullable;
+    if (input.many !== undefined) this.many = input.many;
     if (input.typeParams !== undefined) this.typeParams = input.typeParams;
     if (input.typeRef !== undefined) this.typeRef = input.typeRef;
     if (input.default !== undefined) this.default = input.default;

package/src/ir/storage-entry-schemas.ts

@@ -39,6 +39,7 @@ const StorageColumnSchema = type({
   nativeType: 'string',
   codecId: 'string',
   nullable: 'boolean',
+  'many?': 'boolean',
   'typeParams?': 'Record<string, unknown>',
   'typeRef?': 'string',
   'default?': ColumnDefaultSchema,

package/src/ir/storage-table.ts

@@ -68,4 +68,25 @@ export class StorageTable extends SqlNode {
     }
     freezeNode(this);
   }
+
+  /**
+   * Runtime guard that a namespace `table` entry is really a `StorageTable`.
+   * The compiler already types the entry as `StorageTable`, but a
+   * freshly-deserialized contract may carry plain JSON at that slot until
+   * hydration; this duck-types the structural shape. Accepts `undefined` so
+   * optional-chained entry lookups pass straight through.
+   */
+  static is(value: StorageTable | undefined): value is StorageTable {
+    if (typeof value !== 'object' || value === null) return false;
+    return 'columns' in value && 'uniques' in value && 'indexes' in value && 'foreignKeys' in value;
+  }
+
+  static assert(
+    value: StorageTable | undefined,
+    coordinate: string,
+  ): asserts value is StorageTable {
+    if (!StorageTable.is(value)) {
+      throw new Error(`Expected a StorageTable at ${coordinate}`);
+    }
+  }
 }

package/src/ir/storage-value-set.ts

@@ -41,3 +41,8 @@ export class StorageValueSet extends SqlNode {
     freezeNode(this);
   }
 }
+
+export function isStorageValueSet(value: unknown): value is StorageValueSet {
+  if (typeof value !== 'object' || value === null) return false;
+  return 'kind' in value && value.kind === 'valueSet' && 'values' in value;
+}

package/src/types.ts

@@ -10,7 +10,6 @@ export interface SqlControlDriverInstance<T extends string = string>
   ): Promise<{ readonly rows: Row[] }>;
 }
 
-export { buildSqlNamespace, buildSqlNamespaceMap } from './ir/build-sql-namespace';
 export { CheckConstraint, type CheckConstraintInput } from './ir/check-constraint';
 export {
   ForeignKey,
@@ -25,14 +24,18 @@ export { PrimaryKey, type PrimaryKeyInput } from './ir/primary-key';
 export { Index, type IndexInput } from './ir/sql-index';
 export { SqlNode } from './ir/sql-node';
 export {
+  isMaterializedSqlNamespace,
+  isSqlAuthoringContributions,
+  type SqlAuthoringContributions,
   type SqlNamespace,
+  SqlNamespaceBase,
   type SqlNamespaceEntries,
-  type SqlNamespaceTablesInput,
+  type SqlNamespaceFactory,
+  type SqlNamespaceInput,
   SqlStorage,
   type SqlStorageInput,
   type SqlStorageTypeEntry,
 } from './ir/sql-storage';
-export { SqlUnboundNamespace } from './ir/sql-unbound-namespace';
 export { StorageColumn, type StorageColumnInput } from './ir/storage-column';
 export { StorageTable, type StorageTableInput } from './ir/storage-table';
 export {
@@ -42,7 +45,11 @@ export {
   type StorageTypeInstanceInput,
   toStorageTypeInstance,
 } from './ir/storage-type-instance';
-export { StorageValueSet, type StorageValueSetInput } from './ir/storage-value-set';
+export {
+  isStorageValueSet,
+  StorageValueSet,
+  type StorageValueSetInput,
+} from './ir/storage-value-set';
 export {
   UniqueConstraint,
   type UniqueConstraintInput,
@@ -83,16 +90,25 @@ export function applyFkDefaults(
 // Shared by the output and input field-type maps and their extractors.
 export type NamespacedFieldTypeMap = Record<string, Record<string, Record<string, unknown>>>;
 
+export type NamespacedStorageColumnTypeMap = Record<
+  string,
+  Record<string, Record<string, unknown>>
+>;
+
 export type TypeMaps<
   TCodecTypes extends Record<string, { output: unknown }> = Record<string, never>,
   TQueryOperationTypes extends Record<string, unknown> = Record<string, never>,
   TFieldOutputTypes extends NamespacedFieldTypeMap = Record<string, never>,
   TFieldInputTypes extends NamespacedFieldTypeMap = Record<string, never>,
+  TStorageColumnTypes extends NamespacedStorageColumnTypeMap = Record<string, never>,
+  TStorageColumnInputTypes extends NamespacedStorageColumnTypeMap = Record<string, never>,
 > = {
   readonly codecTypes: TCodecTypes;
   readonly queryOperationTypes: TQueryOperationTypes;
   readonly fieldOutputTypes: TFieldOutputTypes;
   readonly fieldInputTypes: TFieldInputTypes;
+  readonly storageColumnTypes: TStorageColumnTypes;
+  readonly storageColumnInputTypes: TStorageColumnInputTypes;
 };
 
 export type CodecTypesOf<T> = [T] extends [never]
@@ -107,12 +123,19 @@ export type CodecTypesOf<T> = [T] extends [never]
  * Dispatch hint identifying the first-argument target of an operation.
  *
  * Used by ORM column helpers to decide whether an operation is reachable on a
- * field. Either names a concrete codec identity or a set of capability traits
- * that the field's codec must carry.
+ * field. Names a concrete codec identity, a set of capability traits the
+ * field's codec must carry, or targets list-typed (`many`) fields. Element
+ * capability gating for list ops travels in `elementTraits`.
  */
 export type QueryOperationSelfSpec =
-  | { readonly codecId: string; readonly traits?: never }
-  | { readonly traits: readonly CodecTrait[]; readonly codecId?: never };
+  | { readonly codecId: string; readonly traits?: never; readonly many?: never }
+  | { readonly traits: readonly CodecTrait[]; readonly codecId?: never; readonly many?: never }
+  | {
+      readonly many: true;
+      readonly elementTraits?: readonly CodecTrait[];
+      readonly codecId?: never;
+      readonly traits?: never;
+    };
 
 /**
  * Structural shape an operation's impl must return: any value carrying a
@@ -172,10 +195,30 @@ export type FieldInputTypesOf<T> = [T] extends [never]
       : Record<string, never>
     : Record<string, never>;
 
+export type StorageColumnTypesOf<T> = [T] extends [never]
+  ? Record<string, never>
+  : T extends { readonly storageColumnTypes: infer F }
+    ? F extends NamespacedStorageColumnTypeMap
+      ? F
+      : Record<string, never>
+    : Record<string, never>;
+
+export type StorageColumnInputTypesOf<T> = [T] extends [never]
+  ? Record<string, never>
+  : T extends { readonly storageColumnInputTypes: infer F }
+    ? F extends NamespacedStorageColumnTypeMap
+      ? F
+      : Record<string, never>
+    : Record<string, never>;
+
 export type ExtractCodecTypes<T> = CodecTypesOf<ExtractTypeMapsFromContract<T>>;
 export type ExtractQueryOperationTypes<T> = QueryOperationTypesOf<ExtractTypeMapsFromContract<T>>;
 export type ExtractFieldOutputTypes<T> = FieldOutputTypesOf<ExtractTypeMapsFromContract<T>>;
 export type ExtractFieldInputTypes<T> = FieldInputTypesOf<ExtractTypeMapsFromContract<T>>;
+export type ExtractStorageColumnTypes<T> = StorageColumnTypesOf<ExtractTypeMapsFromContract<T>>;
+export type ExtractStorageColumnInputTypes<T> = StorageColumnInputTypesOf<
+  ExtractTypeMapsFromContract<T>
+>;
 
 export type ResolveCodecTypes<TContract, TTypeMaps> = [TTypeMaps] extends [never]
   ? ExtractCodecTypes<TContract>