@prisma-next/sql-contract-ts 0.16.0-dev.3 → 0.16.0-dev.30

package/src/contract-lowering.ts

@@ -11,6 +11,7 @@ import {
 } from '@prisma-next/sql-contract/entity-handle-lowering-hook';
 import type { StorageTypeInstance } from '@prisma-next/sql-contract/types';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import type {
   AttachedEntities,
   ContractDefinition,
@@ -39,6 +40,7 @@ import {
   type SqlStageSpec,
   type UniqueConstraint,
 } from './contract-dsl';
+import { contractError } from './contract-errors';
 import {
   emitTypedCrossModelFallbackWarnings,
   emitTypedNamedTypeFallbackWarnings,
@@ -106,15 +108,19 @@ function resolveFieldDescriptor(
         : storageTypeReverseLookup.get(fieldState.typeRef as StorageTypeInstance);
 
     if (!typeRef) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.TYPE_UNKNOWN',
         `Field "${modelName}.${fieldName}" references a storage type instance that is not present in definition.types`,
+        { meta: { modelName, fieldName, reason: 'instance-not-in-definition-types' } },
       );
     }
 
     const referencedType = storageTypes[typeRef];
     if (!referencedType) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.TYPE_UNKNOWN',
         `Field "${modelName}.${fieldName}" references unknown storage type "${typeRef}"`,
+        { meta: { modelName, fieldName, typeRef } },
       );
     }
 
@@ -125,7 +131,11 @@ function resolveFieldDescriptor(
     };
   }
 
-  throw new Error(`Field "${modelName}.${fieldName}" does not resolve to a storage descriptor`);
+  throw contractError(
+    'CONTRACT.TYPE_UNKNOWN',
+    `Field "${modelName}.${fieldName}" does not resolve to a storage descriptor`,
+    { meta: { modelName, fieldName, reason: 'unresolved-storage-descriptor' } },
+  );
 }
 
 function mapFieldNamesToColumnNames(
@@ -136,7 +146,11 @@ function mapFieldNamesToColumnNames(
   return fieldNames.map((fieldName) => {
     const columnName = fieldToColumn[fieldName];
     if (!columnName) {
-      throw new Error(`Unknown field "${modelName}.${fieldName}" in contract definition`);
+      throw contractError(
+        'CONTRACT.FIELD_UNKNOWN',
+        `Unknown field "${modelName}.${fieldName}" in contract definition`,
+        { meta: { modelName, fieldName } },
+      );
     }
     return columnName;
   });
@@ -154,8 +168,16 @@ function assertRelationFieldArity(params: {
     return;
   }
 
-  throw new Error(
+  throw contractError(
+    'CONTRACT.RELATION_INVALID',
     `Relation "${params.modelName}.${params.relationName}" maps ${params.leftFields.length} ${params.leftLabel} field(s) to ${params.rightFields.length} ${params.rightLabel} field(s).`,
+    {
+      meta: {
+        modelName: params.modelName,
+        relationName: params.relationName,
+        reason: 'field-count-mismatch',
+      },
+    },
   );
 }
 
@@ -182,8 +204,12 @@ function resolveInlineIdConstraint(
   }
 
   if (inlineIdFields.length > 1) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.IDENTITY_INVALID',
       `Model "${spec.modelName}" marks multiple fields with .id(). Use .attributes(...) for compound identities.`,
+      {
+        meta: { modelName: spec.modelName, reason: 'multiple-inline-ids', fields: inlineIdFields },
+      },
     );
   }
 
@@ -225,14 +251,20 @@ function resolveModelIdConstraint(
   const attributeId = spec.attributesSpec?.id;
 
   if (inlineId && attributeId) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.IDENTITY_INVALID',
       `Model "${spec.modelName}" defines identity both inline and in .attributes(...). Pick one identity style.`,
+      { meta: { modelName: spec.modelName, reason: 'inline-and-attributes' } },
     );
   }
 
   const resolvedId = attributeId ?? inlineId;
   if (resolvedId && resolvedId.fields.length === 0) {
-    throw new Error(`Model "${spec.modelName}" defines an empty identity. Add at least one field.`);
+    throw contractError(
+      'CONTRACT.IDENTITY_INVALID',
+      `Model "${spec.modelName}" defines an empty identity. Add at least one field.`,
+      { meta: { modelName: spec.modelName, reason: 'empty-identity' } },
+    );
   }
 
   return resolvedId;
@@ -242,8 +274,10 @@ function resolveModelUniqueConstraints(spec: RuntimeModelSpec): readonly UniqueC
   const attributeUniques = spec.attributesSpec?.uniques ?? [];
   for (const unique of attributeUniques) {
     if (unique.fields.length === 0) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.CONSTRAINT_INVALID',
         `Model "${spec.modelName}" defines an empty unique constraint. Add at least one field.`,
+        { meta: { modelName: spec.modelName } },
       );
     }
   }
@@ -300,8 +334,10 @@ function resolveRelationForeignKeys(
     }
 
     if (!allSpecs.has(targetModelName)) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.MODEL_UNKNOWN',
         `Relation "${spec.modelName}.${relationName}" references unknown model "${targetModelName}"`,
+        { meta: { sourceModel: spec.modelName, relationName, targetModel: targetModelName } },
       );
     }
 
@@ -344,8 +380,10 @@ function resolveRelationAnchorFields(spec: RuntimeModelSpec): readonly string[]
     return ['id'];
   }
 
-  throw new Error(
+  throw contractError(
+    'CONTRACT.IDENTITY_INVALID',
     `Model "${spec.modelName}" needs an explicit id or an "id" field to anchor non-owning relations`,
+    { meta: { modelName: spec.modelName, reason: 'missing-anchor-id' } },
   );
 }
 
@@ -354,7 +392,7 @@ function lowerBelongsToRelation(
   relation: Extract<RelationState, { kind: 'belongsTo' }>,
   currentSpec: RuntimeModelSpec,
   allSpecs: ReadonlyMap<string, RuntimeModelSpec>,
-  extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>,
+  extensions?: Record<string, ExtensionPackRef<'sql', string>>,
 ): RelationNode {
   const targetModelName = resolveRelationModelName(relation.toModel);
   const fromFields = normalizeRelationFieldNames(relation.from);
@@ -374,7 +412,7 @@ function lowerBelongsToRelation(
   // requiring a local model spec — matching how the FK lowering works.
   if (relation.spaceId !== undefined) {
     assertKnownExtensionPack(
-      extensionPacks,
+      extensions,
       relation.spaceId,
       `Relation "${currentSpec.modelName}.${relationName}"`,
     );
@@ -406,8 +444,10 @@ function lowerBelongsToRelation(
 
   const targetSpec = allSpecs.get(targetModelName);
   if (!targetSpec) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.MODEL_UNKNOWN',
       `Relation "${currentSpec.modelName}.${relationName}" references unknown model "${targetModelName}"`,
+      { meta: { sourceModel: currentSpec.modelName, relationName, targetModel: targetModelName } },
     );
   }
 
@@ -442,8 +482,10 @@ function lowerHasOwnershipRelation(
   const targetModelName = resolveRelationModelName(relation.toModel);
   const targetSpec = allSpecs.get(targetModelName);
   if (!targetSpec) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.MODEL_UNKNOWN',
       `Relation "${currentSpec.modelName}.${relationName}" references unknown model "${targetModelName}"`,
+      { meta: { sourceModel: currentSpec.modelName, relationName, targetModel: targetModelName } },
     );
   }
 
@@ -489,16 +531,20 @@ function lowerManyToManyRelation(
   const targetModelName = resolveRelationModelName(relation.toModel);
   const targetSpec = allSpecs.get(targetModelName);
   if (!targetSpec) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.MODEL_UNKNOWN',
       `Relation "${currentSpec.modelName}.${relationName}" references unknown model "${targetModelName}"`,
+      { meta: { sourceModel: currentSpec.modelName, relationName, targetModel: targetModelName } },
     );
   }
 
   const throughModelName = resolveRelationModelName(relation.through);
   const throughSpec = allSpecs.get(throughModelName);
   if (!throughSpec) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.MODEL_UNKNOWN',
       `Relation "${currentSpec.modelName}.${relationName}" references unknown through model "${throughModelName}"`,
+      { meta: { sourceModel: currentSpec.modelName, relationName, targetModel: throughModelName } },
     );
   }
 
@@ -510,8 +556,16 @@ function lowerManyToManyRelation(
     currentAnchorFields.length !== throughFromFields.length ||
     targetAnchorFields.length !== throughToFields.length
   ) {
-    throw new Error(
+    throw contractError(
+      'CONTRACT.RELATION_INVALID',
       `Relation "${currentSpec.modelName}.${relationName}" has mismatched many-to-many field counts.`,
+      {
+        meta: {
+          modelName: currentSpec.modelName,
+          relationName,
+          reason: 'many-to-many-field-count-mismatch',
+        },
+      },
     );
   }
 
@@ -556,10 +610,10 @@ function resolveRelationNode(
   relation: RelationState,
   currentSpec: RuntimeModelSpec,
   allSpecs: ReadonlyMap<string, RuntimeModelSpec>,
-  extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>,
+  extensions?: Record<string, ExtensionPackRef<'sql', string>>,
 ): RelationNode {
   if (relation.kind === 'belongsTo') {
-    return lowerBelongsToRelation(relationName, relation, currentSpec, allSpecs, extensionPacks);
+    return lowerBelongsToRelation(relationName, relation, currentSpec, allSpecs, extensions);
   }
 
   if (relation.kind === 'hasMany' || relation.kind === 'hasOne') {
@@ -637,29 +691,31 @@ function lowerCrossSpaceForeignKeyNode(
 }
 
 function assertKnownExtensionPack(
-  extensionPacks: Record<string, ExtensionPackRef<'sql', string>> | undefined,
+  extensions: Record<string, ExtensionPackRef<'sql', string>> | undefined,
   spaceId: string,
   context: string,
 ): void {
-  if (extensionPacks !== undefined && Object.hasOwn(extensionPacks, spaceId)) {
+  if (extensions !== undefined && Object.hasOwn(extensions, spaceId)) {
     return;
   }
-  throw new Error(
-    `${context} references contract space "${spaceId}" but "${spaceId}" is not declared in extensionPacks. Add the pack to extensionPacks.`,
+  throw contractError(
+    'CONTRACT.PACK_MISSING',
+    `${context} references contract space "${spaceId}" but "${spaceId}" is not declared in extensions. Add the pack to extensions.`,
+    { meta: { spaceId, context } },
   );
 }
 
 function resolveForeignKeyNodes(
   spec: RuntimeModelSpec,
   allSpecs: ReadonlyMap<string, RuntimeModelSpec>,
-  extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>,
+  extensions?: Record<string, ExtensionPackRef<'sql', string>>,
 ): readonly ForeignKeyNode[] {
   const relationForeignKeys = resolveRelationForeignKeys(spec, allSpecs).map((foreignKey) => {
     // F-relfk: relation-derived FKs for cross-space targets carry targetSpaceId;
     // route them through the cross-space path, just like explicit sql() FKs.
     if (foreignKey.targetSpaceId !== undefined) {
       assertKnownExtensionPack(
-        extensionPacks,
+        extensions,
         foreignKey.targetSpaceId,
         `Relation-derived foreign key on "${spec.modelName}"`,
       );
@@ -671,8 +727,10 @@ function resolveForeignKeyNodes(
 
     const targetSpec = allSpecs.get(foreignKey.targetModel);
     if (!targetSpec) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.MODEL_UNKNOWN',
         `Foreign key on "${spec.modelName}" references unknown model "${foreignKey.targetModel}"`,
+        { meta: { sourceModel: spec.modelName, targetModel: foreignKey.targetModel } },
       );
     }
 
@@ -682,7 +740,7 @@ function resolveForeignKeyNodes(
   const sqlForeignKeys = (spec.sqlSpec?.foreignKeys ?? []).map((foreignKey) => {
     if (foreignKey.targetSpaceId !== undefined) {
       assertKnownExtensionPack(
-        extensionPacks,
+        extensions,
         foreignKey.targetSpaceId,
         `Foreign key on "${spec.modelName}"`,
       );
@@ -694,8 +752,10 @@ function resolveForeignKeyNodes(
 
     const targetSpec = allSpecs.get(foreignKey.targetModel);
     if (!targetSpec) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.MODEL_UNKNOWN',
         `Foreign key on "${spec.modelName}" references unknown model "${foreignKey.targetModel}"`,
+        { meta: { sourceModel: spec.modelName, targetModel: foreignKey.targetModel } },
       );
     }
 
@@ -710,7 +770,7 @@ function resolveModelNode(
   allSpecs: ReadonlyMap<string, RuntimeModelSpec>,
   storageTypes: Record<string, StorageTypeInstance>,
   storageTypeReverseLookup: ReadonlyMap<StorageTypeInstance, string>,
-  extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>,
+  extensions?: Record<string, ExtensionPackRef<'sql', string>>,
 ): ModelNode {
   const fields: FieldNode[] = [];
 
@@ -725,7 +785,7 @@ function resolveModelNode(
     );
     const columnName = spec.fieldToColumn[fieldName];
     if (!columnName) {
-      throw new Error(`Column name resolution failed for "${spec.modelName}.${fieldName}"`);
+      throw new InternalError(`Column name resolution failed for "${spec.modelName}.${fieldName}"`);
     }
 
     const enumHandle =
@@ -756,9 +816,9 @@ function resolveModelNode(
     ...ifDefined('type', index.type),
     ...ifDefined('options', index.options),
   })) satisfies readonly IndexNode[];
-  const foreignKeys = resolveForeignKeyNodes(spec, allSpecs, extensionPacks);
+  const foreignKeys = resolveForeignKeyNodes(spec, allSpecs, extensions);
   const relations = Object.entries(spec.relations).map(([relationName, relationBuilder]) =>
-    resolveRelationNode(relationName, relationBuilder.build(), spec, allSpecs, extensionPacks),
+    resolveRelationNode(relationName, relationBuilder.build(), spec, allSpecs, extensions),
   );
 
   return {
@@ -798,8 +858,10 @@ function collectRuntimeModelSpecs(definition: ContractInput): RuntimeCollection
   for (const [modelName, modelDefinition] of Object.entries(models)) {
     const tokenModelName = modelDefinition.stageOne.modelName;
     if (tokenModelName && tokenModelName !== modelName) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.MODEL_TOKEN_INVALID',
         `Model token "${tokenModelName}" must be assigned to models.${tokenModelName}. Received models.${modelName}.`,
+        { meta: { tokenModelName, assignedKey: modelName } },
       );
     }
 
@@ -812,8 +874,10 @@ function collectRuntimeModelSpecs(definition: ContractInput): RuntimeCollection
     const tableKey = JSON.stringify([namespaceId, tableName]);
     const existingModel = tableOwners.get(tableKey);
     if (existingModel) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.NAME_DUPLICATE',
         `Models "${existingModel}" and "${modelName}" both map to table "${tableName}".`,
+        { meta: { kind: 'table', name: tableName, first: existingModel, second: modelName } },
       );
     }
     tableOwners.set(tableKey, modelName);
@@ -827,8 +891,10 @@ function collectRuntimeModelSpecs(definition: ContractInput): RuntimeCollection
         fieldState.columnName ?? applyNaming(fieldName, definition.naming?.columns);
       const existingField = columnOwners.get(columnName);
       if (existingField) {
-        throw new Error(
+        throw contractError(
+          'CONTRACT.NAME_DUPLICATE',
           `Model "${modelName}" maps both "${existingField}" and "${fieldName}" to column "${columnName}".`,
+          { meta: { kind: 'column', name: columnName, first: existingField, second: fieldName } },
         );
       }
       columnOwners.set(columnName, fieldName);
@@ -859,7 +925,7 @@ function collectRuntimeModelSpecs(definition: ContractInput): RuntimeCollection
 
 function lowerModels(
   collection: RuntimeCollection,
-  extensionPacks?: Record<string, ExtensionPackRef<'sql', string>>,
+  extensions?: Record<string, ExtensionPackRef<'sql', string>>,
 ): readonly ModelNode[] {
   emitTypedCrossModelFallbackWarnings(collection);
 
@@ -870,7 +936,7 @@ function lowerModels(
       collection.modelSpecs,
       collection.storageTypes,
       storageTypeReverseLookup,
-      extensionPacks,
+      extensions,
     ),
   );
 }
@@ -906,7 +972,7 @@ function lowerPackEntityHandles(
     readonly authoring?: import('@prisma-next/framework-components/authoring').AuthoringContributions;
   }[] = [
     definition.target,
-    ...Object.values<ExtensionPackRef<'sql', string>>(definition.extensionPacks ?? {}),
+    ...Object.values<ExtensionPackRef<'sql', string>>(definition.extensions ?? {}),
   ];
   const owningComponent = new Map<string, (typeof components)[number]>();
   const walkEntityTypes = (
@@ -976,8 +1042,10 @@ function lowerPackEntityHandles(
   for (const handle of entities) {
     const component = owningComponent.get(handle.entityKind);
     if (component === undefined) {
-      throw new Error(
+      throw contractError(
+        'CONTRACT.ENTITY_KIND_UNKNOWN',
         `defineContract: entities contains a handle with entityKind "${handle.entityKind}", which no composed pack registers. Compose a pack whose entityTypes contribution claims "${handle.entityKind}", or remove the handle.`,
+        { meta: { entityKind: handle.entityKind } },
       );
     }
     const refs: Record<string, ResolvedEntityHandleRef> = {};
@@ -994,8 +1062,10 @@ function lowerPackEntityHandles(
     const authoring = component.authoring;
     if (!providesEntityHandleLowering(authoring)) {
       const kinds = [...new Set(handles.map((entry) => entry.handle.entityKind))].sort();
-      throw new Error(
+      throw contractError(
+        'CONTRACT.PACK_CONTRIBUTION_INVALID',
         `defineContract: entityKind(s) ${kinds.map((kind) => `"${kind}"`).join(', ')} are registered by a pack that does not implement entity-handle lowering (no lowerEntityHandles on its authoring contributions).`,
+        { meta: { entityKinds: kinds, reason: 'missing-lowerEntityHandles' } },
       );
     }
     for (const row of authoring.lowerEntityHandles({ handles, defaultNamespaceId })) {
@@ -1005,8 +1075,10 @@ function lowerPackEntityHandles(
       forNamespace[row.entityKind] = forKind;
       const existing = forKind[row.key];
       if (existing !== undefined && existing !== row.entity) {
-        throw new Error(
+        throw contractError(
+          'CONTRACT.NAME_DUPLICATE',
           `defineContract: two different "${row.entityKind}" entities named "${row.key}" in namespace "${row.namespaceId}" — pack-entity names must be unique per namespace.`,
+          { meta: { kind: row.entityKind, name: row.key, namespaceId: row.namespaceId } },
         );
       }
       forKind[row.key] = row.entity;
@@ -1017,13 +1089,13 @@ function lowerPackEntityHandles(
 
 export function buildContractDefinition(definition: ContractInput): ContractDefinition {
   const collection = collectRuntimeModelSpecs(definition);
-  const models = lowerModels(collection, definition.extensionPacks);
+  const models = lowerModels(collection, definition.extensions);
   const attachedEntities = lowerPackEntityHandles(definition, collection.modelSpecs);
 
   return {
     target: definition.target,
     ...ifDefined('defaultControlPolicy', definition.defaultControlPolicy),
-    ...(definition.extensionPacks ? { extensionPacks: definition.extensionPacks } : {}),
+    ...(definition.extensions ? { extensions: definition.extensions } : {}),
     ...(definition.storageHash ? { storageHash: definition.storageHash } : {}),
     ...(definition.foreignKeyDefaults ? { foreignKeyDefaults: definition.foreignKeyDefaults } : {}),
     ...(Object.keys(collection.storageTypes).length > 0

package/src/contract-types.ts

@@ -67,8 +67,8 @@ export type MergeExtensionPackRefs<
   Added extends Record<string, ExtensionPackRef<'sql', string>>,
 > = Existing extends Record<string, unknown> ? Existing & Added : Added;
 
-type DefinitionExtensionPacks<Definition> = Definition extends {
-  readonly extensionPacks?: infer Packs extends Record<string, ExtensionPackRef<'sql', string>>;
+type DefinitionExtensions<Definition> = Definition extends {
+  readonly extensions?: infer Packs extends Record<string, ExtensionPackRef<'sql', string>>;
 }
   ? Packs
   : Record<never, never>;
@@ -101,7 +101,7 @@ type DerivedCapabilities<Definition> = Defaulted<
   ExtractPackCapabilities<DefinitionTarget<Definition>>,
   Record<string, never>
 > &
-  MergeExtensionPackCapabilities<DefinitionExtensionPacks<Definition>>;
+  MergeExtensionPackCapabilities<DefinitionExtensions<Definition>>;
 
 type DefinitionTargetId<Definition> = Definition extends {
   readonly target: TargetPackRef<'sql', infer Target>;
@@ -114,13 +114,13 @@ type Present<T> = Exclude<T, undefined>;
 type CodecTypesFromDefinition<Definition> = ExtractCodecTypesFromPack<
   Definition extends { readonly target: infer Target } ? Target : never
 > &
-  MergeExtensionCodecTypesSafe<DefinitionExtensionPacks<Definition>>;
+  MergeExtensionCodecTypesSafe<DefinitionExtensions<Definition>>;
 
 type DefinitionTarget<Definition> = Definition extends { readonly target: infer Target }
   ? Target
   : never;
 
-type AllPacks<Definition> = DefinitionExtensionPacks<Definition> & {
+type AllPacks<Definition> = DefinitionExtensions<Definition> & {
   readonly __target: DefinitionTarget<Definition>;
 };
 
@@ -799,9 +799,9 @@ export type SqlContractResult<Definition> = ContractWithTypeMaps<
       readonly namespaces: Readonly<Record<string, BuiltDomainNamespace<Definition>>>;
     } & BuiltDomain<Definition>;
   } & {
-    readonly extensionPacks: keyof DefinitionExtensionPacks<Definition> extends never
+    readonly extensions: keyof DefinitionExtensions<Definition> extends never
       ? Record<string, never>
-      : DefinitionExtensionPacks<Definition>;
+      : DefinitionExtensions<Definition>;
     readonly capabilities: DerivedCapabilities<Definition>;
     readonly enumAccessors: BuiltEnumAccessors<Definition>;
   },