@prisma-next/sql-contract-ts 0.12.0-dev.57 → 0.12.0-dev.59

package/package.json

@@ -1,30 +1,30 @@
 {
   "name": "@prisma-next/sql-contract-ts",
-  "version": "0.12.0-dev.57",
+  "version": "0.12.0-dev.59",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "SQL-specific TypeScript contract authoring surface for Prisma Next",
   "dependencies": {
-    "@prisma-next/config": "0.12.0-dev.57",
-    "@prisma-next/contract": "0.12.0-dev.57",
-    "@prisma-next/contract-authoring": "0.12.0-dev.57",
-    "@prisma-next/framework-components": "0.12.0-dev.57",
-    "@prisma-next/sql-contract": "0.12.0-dev.57",
-    "@prisma-next/utils": "0.12.0-dev.57",
+    "@prisma-next/config": "0.12.0-dev.59",
+    "@prisma-next/contract": "0.12.0-dev.59",
+    "@prisma-next/contract-authoring": "0.12.0-dev.59",
+    "@prisma-next/framework-components": "0.12.0-dev.59",
+    "@prisma-next/sql-contract": "0.12.0-dev.59",
+    "@prisma-next/utils": "0.12.0-dev.59",
     "arktype": "^2.2.0",
     "pathe": "^2.0.3",
     "ts-toolbelt": "^9.6.0"
   },
   "devDependencies": {
-    "@prisma-next/test-utils": "0.12.0-dev.57",
-    "@prisma-next/tsconfig": "0.12.0-dev.57",
+    "@prisma-next/test-utils": "0.12.0-dev.59",
+    "@prisma-next/tsconfig": "0.12.0-dev.59",
     "@types/pg": "8.20.0",
-    "pg": "8.20.0",
-    "@prisma-next/tsdown": "0.12.0-dev.57",
-    "tsdown": "0.22.0",
+    "pg": "8.21.0",
+    "@prisma-next/tsdown": "0.12.0-dev.59",
+    "tsdown": "0.22.1",
     "typescript": "5.9.3",
-    "vitest": "4.1.6"
+    "vitest": "4.1.7"
   },
   "peerDependencies": {
     "typescript": ">=5.9"

package/src/build-contract.ts

@@ -8,6 +8,7 @@ import {
   type ColumnDefault,
   type ColumnDefaultLiteralInputValue,
   type Contract,
+  type ContractEnum,
   type ContractField,
   type ContractModel,
   type ContractRelation,
@@ -18,6 +19,7 @@ import {
   type ExecutionMutationDefault,
   type JsonValue,
   type StorageHashBase,
+  type ValueSetRef,
 } from '@prisma-next/contract/types';
 import { type CapabilityMatrix, mergeCapabilityMatrices } from '@prisma-next/contract-authoring';
 import type { CodecLookup } from '@prisma-next/framework-components/codec';
@@ -41,6 +43,7 @@ import {
   StorageTable,
   type StorageTableInput,
   type StorageTypeInstance,
+  type StorageValueSetInput,
   toStorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
 import { validateStorageSemantics } from '@prisma-next/sql-contract/validators';
@@ -166,6 +169,7 @@ function resolveModelNamespaceId(
 
 function buildStorageColumn(
   field: FieldNode | ValueObjectFieldNode,
+  storageValueSetRef: ValueSetRef | undefined,
   codecLookup?: CodecLookup,
 ): StorageColumn {
   if (isValueObjectField(field)) {
@@ -203,12 +207,14 @@ function buildStorageColumn(
     ...ifDefined('typeParams', field.descriptor.typeParams),
     ...ifDefined('default', encodedDefault),
     ...ifDefined('typeRef', field.descriptor.typeRef),
+    ...ifDefined('valueSet', storageValueSetRef),
   };
 }
 
 function buildDomainField(
   field: FieldNode | ValueObjectFieldNode,
   column: StorageColumn,
+  domainValueSetRef: ValueSetRef | undefined,
 ): ContractField {
   if (isValueObjectField(field)) {
     return {
@@ -226,6 +232,7 @@ function buildDomainField(
     },
     nullable: column.nullable,
     ...(field.many ? { many: true } : {}),
+    ...ifDefined('valueSet', domainValueSetRef),
   };
 }
 
@@ -369,11 +376,34 @@ export function buildSqlContractFromDefinition(
         }
       }
 
-      const column = buildStorageColumn(field, codecLookup);
+      const enumHandle = !isValueObjectField(field) ? field.enumTypeHandle : undefined;
+      // Authored enums are always registered under the contract's defaultNamespaceId
+      // (see the enum registration loop below), so refs must point there regardless
+      // of which namespace the consuming model lives in.
+      const storageValueSetRef: ValueSetRef | undefined =
+        enumHandle !== undefined
+          ? {
+              plane: 'storage',
+              entityKind: 'value-set',
+              namespaceId: defaultNamespaceId,
+              name: enumHandle.enumName,
+            }
+          : undefined;
+      const domainValueSetRef: ValueSetRef | undefined =
+        enumHandle !== undefined
+          ? {
+              plane: 'domain',
+              entityKind: 'enum',
+              namespaceId: defaultNamespaceId,
+              name: enumHandle.enumName,
+            }
+          : undefined;
+
+      const column = buildStorageColumn(field, storageValueSetRef, codecLookup);
       columns[field.columnName] = column;
       fieldToColumn[field.fieldName] = field.columnName;
 
-      domainFields[field.fieldName] = buildDomainField(field, column);
+      domainFields[field.fieldName] = buildDomainField(field, column, domainValueSetRef);
 
       if (isValueObjectField(field)) {
         domainFieldRefs[field.fieldName] = {
@@ -585,6 +615,39 @@ export function buildSqlContractFromDefinition(
   for (const id of Object.keys(namespaceEnumTypesById)) {
     namespaceCoordinateIds.add(id);
   }
+
+  // Build per-namespace registries for `enumType()` handles.
+  // All authored enums target the contract's default namespace.
+  const domainEnumsByNs: Record<string, Record<string, ContractEnum>> = {};
+  const storageValueSetsByNs: Record<string, Record<string, StorageValueSetInput>> = {};
+  for (const [enumName, handle] of Object.entries(definition.enums ?? {})) {
+    if (enumName !== handle.enumName) {
+      throw new Error(
+        `enum declaration key "${enumName}" must match enumType name "${handle.enumName}". Aliases are not supported.`,
+      );
+    }
+    const nsId = defaultNamespaceId;
+    let domainSlot = domainEnumsByNs[nsId];
+    if (domainSlot === undefined) {
+      domainSlot = {};
+      domainEnumsByNs[nsId] = domainSlot;
+    }
+    domainSlot[enumName] = {
+      codecId: handle.codecId,
+      members: handle.enumMembers,
+    };
+
+    let storageSlot = storageValueSetsByNs[nsId];
+    if (storageSlot === undefined) {
+      storageSlot = {};
+      storageValueSetsByNs[nsId] = storageSlot;
+    }
+    storageSlot[enumName] = {
+      kind: 'value-set',
+      values: handle.values,
+    };
+  }
+
   const { createNamespace } = definition;
   const namespaces = blindCast<
     SqlStorageInput['namespaces'],
@@ -593,10 +656,14 @@ export function buildSqlContractFromDefinition(
     Object.fromEntries(
       [...namespaceCoordinateIds].sort().map((id) => {
         const enumTypes = namespaceEnumTypesById[id];
+        const valueSetEntries = storageValueSetsByNs[id];
         const nsInput: SqlNamespaceTablesInput = {
           id,
           entries: {
             table: tablesByNamespace[id] ?? {},
+            ...(valueSetEntries !== undefined && Object.keys(valueSetEntries).length > 0
+              ? { valueSet: valueSetEntries }
+              : {}),
           },
         };
         return [
@@ -711,13 +778,22 @@ export function buildSqlContractFromDefinition(
   if (valueObjects !== undefined) {
     domainNamespaceIds.add(defaultNamespaceId);
   }
+  for (const nsId of Object.keys(domainEnumsByNs)) {
+    domainNamespaceIds.add(nsId);
+  }
   const domainNamespaces = Object.fromEntries(
     [...domainNamespaceIds].sort().map((namespaceId) => {
       const modelsInNs = modelsByNamespace[namespaceId] ?? {};
-      const namespaceSlice =
-        namespaceId === defaultNamespaceId && valueObjects !== undefined
-          ? { models: modelsInNs, valueObjects }
-          : { models: modelsInNs };
+      const enumsInNs = domainEnumsByNs[namespaceId];
+      const namespaceSlice = {
+        models: modelsInNs,
+        ...(namespaceId === defaultNamespaceId && valueObjects !== undefined
+          ? { valueObjects }
+          : {}),
+        ...(enumsInNs !== undefined && Object.keys(enumsInNs).length > 0
+          ? { enum: enumsInNs }
+          : {}),
+      };
       return [namespaceId, namespaceSlice];
     }),
   );

package/src/contract-builder.ts

@@ -34,6 +34,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';
 
@@ -73,6 +74,7 @@ type ContractDefinition<
   readonly types?: Types;
   readonly models?: Models;
   readonly codecLookup?: CodecLookup;
+  readonly enums?: Record<string, EnumTypeHandle>;
 };
 
 type ContractScaffold<
@@ -96,6 +98,7 @@ type ContractScaffold<
   readonly types?: never;
   readonly models?: never;
   readonly codecLookup?: CodecLookup;
+  readonly enums?: Record<string, EnumTypeHandle>;
 };
 
 type ContractFactory<
@@ -317,6 +320,7 @@ type BoundDefinitionInput<
   readonly types?: Types;
   readonly models?: Models;
   readonly codecLookup?: CodecLookup;
+  readonly enums?: Record<string, EnumTypeHandle>;
 };
 
 // Merges a bound input with the pre-bound family/target to produce a full ContractDefinition.

package/src/contract-definition.ts

@@ -13,6 +13,7 @@ import type {
   SqlNamespaceTablesInput,
   StorageTypeInstance,
 } from '@prisma-next/sql-contract/types';
+import type { EnumTypeHandle } from './enum-type';
 
 export type { ExecutionMutationDefaultPhases };
 
@@ -24,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 {
@@ -163,4 +166,10 @@ export interface ContractDefinition {
   ) => 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>;
 }

package/src/contract-dsl.ts

@@ -23,6 +23,8 @@ import type {
 } from '@prisma-next/sql-contract/types';
 import { ifDefined } from '@prisma-next/utils/defined';
 import type { NamedConstraintSpec } from './authoring-type-utils';
+import type { EnumTypeHandle } from './enum-type';
+import { isEnumTypeHandle } from './enum-type';
 
 export type NamingStrategy = 'identity' | 'snake_case';
 
@@ -31,7 +33,7 @@ export type NamingConfig = {
   readonly columns?: NamingStrategy;
 };
 
-type NamedStorageTypeRef = string | StorageTypeInstance | PostgresEnumStorageEntry;
+type NamedStorageTypeRef = string | StorageTypeInstance | PostgresEnumStorageEntry | EnumTypeHandle;
 
 type NamedConstraintNameSpec<Name extends string = string> = {
   readonly name: Name;
@@ -358,9 +360,19 @@ function namedTypeField<TypeRef extends StorageTypeInstance>(
 function namedTypeField<TypeRef extends PostgresEnumStorageEntry>(
   typeRef: TypeRef,
 ): ScalarFieldBuilder<ScalarFieldState<string, TypeRef, false, undefined>>;
+function namedTypeField<Handle extends EnumTypeHandle>(
+  typeRef: Handle,
+): ScalarFieldBuilder<ScalarFieldState<Handle['codecId'], Handle, false, undefined>>;
 function namedTypeField(
   typeRef: NamedStorageTypeRef,
 ): ScalarFieldBuilder<ScalarFieldState<string, NamedStorageTypeRef, false, undefined>> {
+  if (isEnumTypeHandle(typeRef)) {
+    return new ScalarFieldBuilder({
+      kind: 'scalar',
+      typeRef,
+      nullable: false,
+    });
+  }
   return new ScalarFieldBuilder({
     kind: 'scalar',
     typeRef,
@@ -1267,6 +1279,12 @@ export type ContractInput<
   readonly types?: Types;
   readonly models?: Models;
   readonly codecLookup?: CodecLookup;
+  /**
+   * Domain enum handles authored via `enumType()`. Each handle lowers to a
+   * domain `enum` entry and a storage `valueSet` entry in the target's
+   * default namespace. Fields reference the enum via `field.namedType(handle)`.
+   */
+  readonly enums?: Record<string, import('./enum-type').EnumTypeHandle>;
 };
 
 export function model<

package/src/contract-lowering.ts

@@ -35,6 +35,7 @@ import {
   emitTypedCrossModelFallbackWarnings,
   emitTypedNamedTypeFallbackWarnings,
 } from './contract-warnings';
+import { isEnumTypeHandle } from './enum-type';
 
 type RuntimeModel = ContractModelBuilder<
   string | undefined,
@@ -84,6 +85,13 @@ function resolveFieldDescriptor(
   }
 
   if ('typeRef' in fieldState && fieldState.typeRef) {
+    if (isEnumTypeHandle(fieldState.typeRef)) {
+      return {
+        codecId: fieldState.typeRef.codecId,
+        nativeType: fieldState.typeRef.nativeType,
+      };
+    }
+
     const typeRef =
       typeof fieldState.typeRef === 'string'
         ? fieldState.typeRef
@@ -567,6 +575,11 @@ function resolveModelNode(
       throw new Error(`Column name resolution failed for "${spec.modelName}.${fieldName}"`);
     }
 
+    const enumHandle =
+      'typeRef' in fieldState && isEnumTypeHandle(fieldState.typeRef)
+        ? fieldState.typeRef
+        : undefined;
+
     fields.push({
       fieldName,
       columnName,
@@ -574,6 +587,7 @@ function resolveModelNode(
       nullable: fieldState.nullable,
       ...(fieldState.default ? { default: fieldState.default } : {}),
       ...(fieldState.executionDefaults ? { executionDefaults: fieldState.executionDefaults } : {}),
+      ...(enumHandle !== undefined ? { enumTypeHandle: enumHandle } : {}),
     });
   }
 
@@ -717,6 +731,9 @@ export function buildContractDefinition(definition: ContractInput): ContractDefi
       : {}),
     ...(definition.namespaces ? { namespaces: definition.namespaces } : {}),
     ...(definition.createNamespace ? { createNamespace: definition.createNamespace } : {}),
+    ...(definition.enums && Object.keys(definition.enums).length > 0
+      ? { enums: definition.enums }
+      : {}),
     models,
   };
 }

package/src/enum-type.ts

@@ -0,0 +1,236 @@
+import type { ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';
+import { blindCast } from '@prisma-next/utils/casts';
+
+// ---------------------------------------------------------------------------
+// EnumMember — a single member declaration with literal type preservation
+// ---------------------------------------------------------------------------
+
+/**
+ * A single enum member produced by `member()`. The `Name` and `Value` generics
+ * are preserved as literal types so `enumType()` can carry the ordered value
+ * tuple in its return type.
+ */
+export interface EnumMember<Name extends string, Value extends string> {
+  readonly name: Name;
+  readonly value: Value;
+}
+
+/**
+ * Declare an enum member. The `value` defaults to `name` when omitted.
+ * Both generics are preserved as literals so downstream `enumType` can
+ * carry the ordered value tuple in its type.
+ */
+export function member<const Name extends string>(name: Name): EnumMember<Name, Name>;
+export function member<const Name extends string, const Value extends string>(
+  name: Name,
+  value: Value,
+): EnumMember<Name, Value>;
+export function member<const Name extends string, const Value extends string = Name>(
+  name: Name,
+  value?: Value,
+): EnumMember<Name, Value> {
+  return {
+    name,
+    value: blindCast<
+      Value,
+      'overload signatures enforce Value=Name when value is omitted; default generic Value=Name makes this safe'
+    >(value ?? name),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal types for inferring the literal tuple from the members spread
+// ---------------------------------------------------------------------------
+
+type MembersToValues<Members extends readonly EnumMember<string, string>[]> = {
+  readonly [K in keyof Members]: Members[K] extends EnumMember<string, infer V> ? V : never;
+};
+
+type MembersToNames<Members extends readonly EnumMember<string, string>[]> = {
+  readonly [K in keyof Members]: Members[K] extends EnumMember<infer N, string> ? N : never;
+};
+
+type MembersAccessorMap<Members extends readonly EnumMember<string, string>[]> = {
+  readonly [M in Members[number] as M['name']]: M['value'];
+};
+
+// ---------------------------------------------------------------------------
+// EnumTypeHandle — the authoring handle returned by enumType()
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal brand that identifies an EnumTypeHandle in the lowering pipeline.
+ * Not exported — callers only interact with `EnumTypeHandle`.
+ */
+export const ENUM_TYPE_HANDLE_BRAND = Symbol('EnumTypeHandle');
+
+/**
+ * Authoring handle returned by `enumType()`. Carries:
+ *
+ * - The ordered literal value tuple (`.values`) and name tuple (`.names`)
+ *   so downstream type-tests can assert literal preservation.
+ * - A namespaced member accessor map (`.members`) to avoid collisions with
+ *   `.values` / `.has` / `.nameOf` / `.ordinalOf`.
+ * - Runtime helpers `.has()`, `.nameOf()`, `.ordinalOf()`.
+ * - Internal metadata (`enumName`, `codecId`, `nativeType`,
+ *   `enumMembers`) for the lowering pipeline.
+ *
+ * The type is generic over the ordered value tuple so callers that assign
+ * `const Role = enumType(...)` retain the literal tuple on `.values`.
+ */
+export interface EnumTypeHandle<
+  Name extends string = string,
+  Values extends readonly string[] = readonly string[],
+  Names extends readonly string[] = readonly string[],
+  MembersMap extends Record<string, string> = Record<string, string>,
+> {
+  /** Internal brand for lowering-pipeline detection. */
+  readonly [ENUM_TYPE_HANDLE_BRAND]: true;
+
+  /** The enum's declared name (used as the key in domain `enum` / storage `valueSet`). */
+  readonly enumName: Name;
+
+  /** codecId from the codec passed to `enumType`. */
+  readonly codecId: string;
+
+  /** nativeType from the codec passed to `enumType`. */
+  readonly nativeType: string;
+
+  /** Ordered member list for lowering (name + value pairs). */
+  readonly enumMembers: readonly { readonly name: string; readonly value: string }[];
+
+  /** Ordered literal value tuple. Declaration order is preserved. */
+  readonly values: Values;
+
+  /** Ordered literal name tuple. Declaration order is preserved. */
+  readonly names: Names;
+
+  /**
+   * Namespaced accessor map: `Role.members.User === 'user'`.
+   * Namespaced under `.members` to avoid collisions with `.values` / `.has`.
+   */
+  readonly members: MembersMap;
+
+  /** Returns `true` if `v` is a declared member value. */
+  has(v: string): boolean;
+
+  /** Returns the member name for a value, or `undefined` if not found. */
+  nameOf(v: string): string | undefined;
+
+  /** Returns the zero-based declaration index of a value, or `-1` if not found. */
+  ordinalOf(v: string): number;
+}
+
+// ---------------------------------------------------------------------------
+// enumType()
+// ---------------------------------------------------------------------------
+
+/**
+ * Declare a domain enum for use in TS-authoring contracts.
+ *
+ * - The codec is an explicit required argument — the `codecId` and
+ *   `nativeType` are taken from the passed `ColumnTypeDescriptor` (e.g.
+ *   `{ codecId: 'pg/text@1', nativeType: 'text' }` from a field preset
+ *   output or a direct inline object).
+ * - `const` generics on the members spread preserve the ordered literal
+ *   value tuple so `Role.values` is `readonly ['user','admin']`, not
+ *   `string[]`.
+ * - Well-formedness assertions at construction: non-empty member list;
+ *   unique names; unique values.
+ *
+ * The returned handle wires into `field.namedType(handle)` to set
+ * `valueSet` refs on both the domain field and the storage column.
+ *
+ * @example
+ * ```ts
+ * const Role = enumType('Role', { codecId: 'pg/text@1', nativeType: 'text' },
+ *   member('User', 'user'),
+ *   member('Admin', 'admin'),
+ * );
+ * // Role.values → readonly ['user', 'admin']
+ * // Role.members.User → 'user'
+ * ```
+ */
+export function enumType<
+  const Name extends string,
+  const Codec extends Pick<ColumnTypeDescriptor, 'codecId' | 'nativeType'>,
+  const Members extends readonly [EnumMember<string, string>, ...EnumMember<string, string>[]],
+>(
+  name: Name,
+  codec: Codec,
+  ...members: Members
+): EnumTypeHandle<
+  Name,
+  MembersToValues<[...Members]>,
+  MembersToNames<[...Members]>,
+  MembersAccessorMap<[...Members]>
+>;
+export function enumType(
+  name: string,
+  codec: Pick<ColumnTypeDescriptor, 'codecId' | 'nativeType'>,
+  ...members: EnumMember<string, string>[]
+): EnumTypeHandle;
+export function enumType(
+  name: string,
+  codec: Pick<ColumnTypeDescriptor, 'codecId' | 'nativeType'>,
+  ...members: EnumMember<string, string>[]
+): EnumTypeHandle {
+  if (members.length === 0) {
+    throw new Error(`enumType("${name}"): must have at least one member.`);
+  }
+
+  const seenNames = new Set<string>();
+  const seenValues = new Set<string>();
+  for (const m of members) {
+    if (seenNames.has(m.name)) {
+      throw new Error(
+        `enumType("${name}"): duplicate member name "${m.name}". Member names must be unique.`,
+      );
+    }
+    seenNames.add(m.name);
+
+    if (seenValues.has(m.value)) {
+      throw new Error(
+        `enumType("${name}"): duplicate member value "${m.value}". Member values must be unique.`,
+      );
+    }
+    seenValues.add(m.value);
+  }
+
+  const values = Object.freeze(members.map((m) => m.value));
+  const names = Object.freeze(members.map((m) => m.name));
+  const enumMembers = Object.freeze(members.map((m) => ({ name: m.name, value: m.value })));
+
+  const membersAccessor = Object.freeze(Object.fromEntries(members.map((m) => [m.name, m.value])));
+
+  const valueSet = new Set(values);
+  const valueToName = new Map(members.map((m) => [m.value, m.name]));
+  const valueToOrdinal = new Map(values.map((v, i) => [v, i]));
+
+  return {
+    [ENUM_TYPE_HANDLE_BRAND]: true,
+    enumName: name,
+    codecId: codec.codecId,
+    nativeType: codec.nativeType,
+    enumMembers,
+    values,
+    names,
+    members: membersAccessor,
+    has: (v: string) => valueSet.has(v),
+    nameOf: (v: string) => valueToName.get(v),
+    ordinalOf: (v: string) => valueToOrdinal.get(v) ?? -1,
+  };
+}
+
+/**
+ * Returns true when the value is an `EnumTypeHandle` produced by
+ * `enumType()`. Used in the lowering pipeline to detect enum handles
+ * in field state without importing the BRAND symbol at every call site.
+ */
+export function isEnumTypeHandle(value: unknown): value is EnumTypeHandle {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Reflect.get(value, ENUM_TYPE_HANDLE_BRAND) === true
+  );
+}

package/src/exports/contract-builder.ts

@@ -23,3 +23,5 @@ export type {
   RelationNode,
   UniqueConstraintNode,
 } from '../contract-definition';
+export type { EnumMember, EnumTypeHandle } from '../enum-type';
+export { enumType, member } from '../enum-type';