@prisma-next/target-postgres 0.16.0-dev.22 → 0.16.0-dev.23

package/src/core/authoring.ts

@@ -26,6 +26,7 @@ import { assertDefined } from '@prisma-next/utils/assertions';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { PG_ENUM_CODEC_ID } from './codec-ids';
+import { postgresError } from './errors';
 import { PostgresNativeEnum } from './postgres-native-enum';
 import { PostgresRlsEnablement, type PostgresRlsEnablementInput } from './postgres-rls-enablement';
 import { PostgresRlsPolicy, type RlsPolicyOperation } from './postgres-rls-policy';
@@ -723,12 +724,16 @@ function requireLocalTarget(
     return { namespaceId: target.namespaceId, tableName: target.tableName };
   }
   if (target !== undefined && target.kind === 'cross-space') {
-    throw new Error(
+    throw postgresError(
+      'CONTRACT.POLICY_INVALID',
       `defineContract: ${subject} targets model "${target.modelName ?? target.tableName}", which lives in another contract space. Policies and rlsEnabled entries must target a model declared in this contract.`,
+      { meta: { model: target.modelName ?? target.tableName, reason: 'cross-space-target' } },
     );
   }
-  throw new Error(
+  throw postgresError(
+    'CONTRACT.MODEL_UNKNOWN',
     `defineContract: ${subject} targets model "${target?.modelName ?? '<anonymous>'}", which is not in the contract's models. Add the model to \`models\`.`,
+    { meta: { model: target?.modelName ?? '<anonymous>' } },
   );
 }
 
@@ -780,8 +785,10 @@ export function postgresLowerEntityHandles(
           'role handles are constructed only by the postgres contract-builder role() constructor, which enforces this shape'
         >(handle);
         if (roles.has(roleHandle.name)) {
-          throw new Error(
+          throw postgresError(
+            'CONTRACT.ROLE_INVALID',
             `defineContract: role "${roleHandle.name}" is declared more than once in the entities list.`,
+            { meta: { role: roleHandle.name, reason: 'duplicate' } },
           );
         }
         // Roles are cluster-scoped in Postgres, so they always land in the
@@ -804,8 +811,10 @@ export function postgresLowerEntityHandles(
         break;
       }
       default:
-        throw new Error(
+        throw postgresError(
+          'CONTRACT.ENTITY_KIND_INVALID',
           `defineContract: the postgres pack does not lower "${handle.entityKind}" handles from the entities list.`,
+          { meta: { entityKind: handle.entityKind } },
         );
     }
   }
@@ -816,21 +825,33 @@ export function postgresLowerEntityHandles(
   for (const { handle: policy, refs } of policies) {
     const prefix = policy.name;
     if (prefix.length > RLS_POLICY_PREFIX_MAX_LENGTH) {
-      throw new Error(
+      throw postgresError(
+        'CONTRACT.POLICY_INVALID',
         `defineContract: policy prefix "${prefix}" exceeds the ${RLS_POLICY_PREFIX_MAX_LENGTH}-character maximum (Postgres identifiers cap at 63 characters and the wire name appends a 9-character hash suffix).`,
+        { meta: { prefix, reason: 'prefix-too-long' } },
       );
     }
     const coordinate = requireLocalTarget(refs, `policy "${prefix}"`);
     if (!enablements.has(coordinateKey(coordinate))) {
       const target = refs['target'];
-      throw new Error(
+      throw postgresError(
+        'CONTRACT.POLICY_INVALID',
         `defineContract: policy "${prefix}" targets model "${target?.modelName ?? coordinate.tableName}", whose table is not RLS-enabled. Add rlsEnabled(<model>) to the entities list.`,
+        {
+          meta: {
+            prefix,
+            model: target?.modelName ?? coordinate.tableName,
+            reason: 'target-not-rls-enabled',
+          },
+        },
       );
     }
     const prefixKey = `${coordinate.namespaceId} ${prefix}`;
     if (seenPrefixes.has(prefixKey)) {
-      throw new Error(
+      throw postgresError(
+        'CONTRACT.POLICY_INVALID',
         `defineContract: policy prefix "${prefix}" is declared more than once in namespace "${coordinate.namespaceId}". Policy prefixes must be unique per namespace.`,
+        { meta: { prefix, namespaceId: coordinate.namespaceId, reason: 'duplicate-prefix' } },
       );
     }
     seenPrefixes.add(prefixKey);

package/src/core/codec-helpers.ts

@@ -7,6 +7,7 @@
  */
 
 import type { JsonValue } from '@prisma-next/contract/types';
+import { postgresError } from './errors';
 
 export function renderLength(
   typeName: string,
@@ -17,8 +18,10 @@ export function renderLength(
     return undefined;
   }
   if (typeof length !== 'number' || !Number.isFinite(length) || !Number.isInteger(length)) {
-    throw new Error(
+    throw postgresError(
+      'RUNTIME.TYPE_PARAMS_INVALID',
       `renderOutputType: expected integer "length" in typeParams for ${typeName}, got ${String(length)}`,
+      { meta: { nativeType: typeName, param: 'length', received: String(length) } },
     );
   }
   return `${typeName}<${length}>`;
@@ -34,8 +37,10 @@ export function renderPrecision(typeName: string, typeParams: Record<string, unk
     !Number.isFinite(precision) ||
     !Number.isInteger(precision)
   ) {
-    throw new Error(
+    throw postgresError(
+      'RUNTIME.TYPE_PARAMS_INVALID',
       `renderOutputType: expected integer "precision" in typeParams for ${typeName}, got ${String(precision)}`,
+      { meta: { nativeType: typeName, param: 'precision', received: String(precision) } },
     );
   }
   return `${typeName}<${precision}>`;
@@ -57,15 +62,19 @@ export const pgNumericRenderOutputType = (typeParams: {
     !Number.isFinite(precision) ||
     !Number.isInteger(precision)
   ) {
-    throw new Error(
+    throw postgresError(
+      'RUNTIME.TYPE_PARAMS_INVALID',
       `renderOutputType: expected integer "precision" in typeParams for Numeric, got ${String(precision)}`,
+      { meta: { nativeType: 'Numeric', param: 'precision', received: String(precision) } },
     );
   }
   const scale = typeParams.scale;
   if (scale === undefined) return `Numeric<${precision}>`;
   if (typeof scale !== 'number' || !Number.isFinite(scale) || !Number.isInteger(scale)) {
-    throw new Error(
+    throw postgresError(
+      'RUNTIME.TYPE_PARAMS_INVALID',
       `renderOutputType: expected integer "scale" in typeParams for Numeric, got ${String(scale)}`,
+      { meta: { nativeType: 'Numeric', param: 'scale', received: String(scale) } },
     );
   }
   return `Numeric<${precision}, ${scale}>`;
@@ -78,14 +87,26 @@ const ISO_8601_TIMESTAMPTZ =
 export const pgTimestampEncodeJson = (value: Date): JsonValue => value.toISOString().slice(0, -1);
 export const pgTimestampDecodeJson = (json: JsonValue): Date => {
   if (typeof json !== 'string') {
-    throw new Error(`Expected ISO date string for pg/timestamp@1, got ${typeof json}`);
+    throw postgresError(
+      'RUNTIME.DECODE_FAILED',
+      `Expected ISO date string for pg/timestamp@1, got ${typeof json}`,
+      { meta: { codecId: 'pg/timestamp@1', received: typeof json } },
+    );
   }
   if (!ISO_8601_TIMESTAMP.test(json)) {
-    throw new Error(`Invalid ISO date string for pg/timestamp@1: ${json}`);
+    throw postgresError(
+      'RUNTIME.DECODE_FAILED',
+      `Invalid ISO date string for pg/timestamp@1: ${json}`,
+      { meta: { codecId: 'pg/timestamp@1', received: json } },
+    );
   }
   const date = new Date(`${json}Z`);
   if (Number.isNaN(date.getTime())) {
-    throw new Error(`Invalid ISO date string for pg/timestamp@1: ${json}`);
+    throw postgresError(
+      'RUNTIME.DECODE_FAILED',
+      `Invalid ISO date string for pg/timestamp@1: ${json}`,
+      { meta: { codecId: 'pg/timestamp@1', received: json } },
+    );
   }
   return date;
 };
@@ -94,14 +115,26 @@ export const pgTimestamptzEncodeJson = (value: Date): JsonValue =>
   value.toISOString().replace(/Z$/, '+00:00');
 export const pgTimestamptzDecodeJson = (json: JsonValue): Date => {
   if (typeof json !== 'string') {
-    throw new Error(`Expected ISO date string for pg/timestamptz@1, got ${typeof json}`);
+    throw postgresError(
+      'RUNTIME.DECODE_FAILED',
+      `Expected ISO date string for pg/timestamptz@1, got ${typeof json}`,
+      { meta: { codecId: 'pg/timestamptz@1', received: typeof json } },
+    );
   }
   if (!ISO_8601_TIMESTAMPTZ.test(json)) {
-    throw new Error(`Invalid ISO date string for pg/timestamptz@1: ${json}`);
+    throw postgresError(
+      'RUNTIME.DECODE_FAILED',
+      `Invalid ISO date string for pg/timestamptz@1: ${json}`,
+      { meta: { codecId: 'pg/timestamptz@1', received: json } },
+    );
   }
   const date = new Date(json);
   if (Number.isNaN(date.getTime())) {
-    throw new Error(`Invalid ISO date string for pg/timestamptz@1: ${json}`);
+    throw postgresError(
+      'RUNTIME.DECODE_FAILED',
+      `Invalid ISO date string for pg/timestamptz@1: ${json}`,
+      { meta: { codecId: 'pg/timestamptz@1', received: json } },
+    );
   }
   return date;
 };
@@ -141,11 +174,17 @@ export const pgDateEncodeJson = (value: Date): JsonValue => pgDateEncode(value);
 
 export const pgDateDecodeJson = (json: JsonValue): Date => {
   if (typeof json !== 'string') {
-    throw new Error(`Expected date string for pg/date@1, got ${typeof json}`);
+    throw postgresError(
+      'RUNTIME.DECODE_FAILED',
+      `Expected date string for pg/date@1, got ${typeof json}`,
+      { meta: { codecId: 'pg/date@1', received: typeof json } },
+    );
   }
   const match = ISO_8601_DATE.exec(json);
   if (!match) {
-    throw new Error(`Invalid date string for pg/date@1: ${json}`);
+    throw postgresError('RUNTIME.DECODE_FAILED', `Invalid date string for pg/date@1: ${json}`, {
+      meta: { codecId: 'pg/date@1', received: json },
+    });
   }
   const [, yearText, monthText, dayText] = match;
   const year = Number(yearText);
@@ -153,7 +192,9 @@ export const pgDateDecodeJson = (json: JsonValue): Date => {
   const day = Number(dayText);
   const date = new Date(Date.UTC(year, month, day));
   if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month || date.getUTCDate() !== day) {
-    throw new Error(`Invalid date string for pg/date@1: ${json}`);
+    throw postgresError('RUNTIME.DECODE_FAILED', `Invalid date string for pg/date@1: ${json}`, {
+      meta: { codecId: 'pg/date@1', received: json },
+    });
   }
   return date;
 };
@@ -168,19 +209,31 @@ export const pgByteaEncodeJson = (value: Uint8Array): JsonValue =>
 
 export const pgByteaDecodeJson = (value: JsonValue): Uint8Array => {
   if (typeof value !== 'string' || !value.startsWith('\\x')) {
-    throw new Error(`Expected Postgres bytea hex text to start with "\\x"`);
+    throw postgresError(
+      'RUNTIME.DECODE_FAILED',
+      `Expected Postgres bytea hex text to start with "\\x"`,
+      { meta: { codecId: 'pg/bytea@1' } },
+    );
   }
 
   const hex = value.slice(2);
   if (hex.length % 2 !== 0) {
-    throw new Error(`Invalid Postgres bytea hex text length: ${hex.length}`);
+    throw postgresError(
+      'RUNTIME.DECODE_FAILED',
+      `Invalid Postgres bytea hex text length: ${hex.length}`,
+      { meta: { codecId: 'pg/bytea@1', received: hex.length } },
+    );
   }
 
   const bytes = new Uint8Array(hex.length / 2);
   for (let offset = 0; offset < hex.length; offset += 2) {
     const pair = hex.slice(offset, offset + 2);
     if (!/^[0-9a-fA-F]{2}$/.test(pair)) {
-      throw new Error(`Invalid Postgres bytea hex pair "${pair}" at offset ${offset}`);
+      throw postgresError(
+        'RUNTIME.DECODE_FAILED',
+        `Invalid Postgres bytea hex pair "${pair}" at offset ${offset}`,
+        { meta: { codecId: 'pg/bytea@1', received: pair } },
+      );
     }
     bytes[offset / 2] = Number.parseInt(pair, 16);
   }

package/src/core/codecs.ts

@@ -92,6 +92,7 @@ import {
   PG_VARBIT_CODEC_ID,
   PG_VARCHAR_CODEC_ID,
 } from './codec-ids';
+import { postgresError } from './errors';
 import { DEFAULT_NAMESPACE_ID } from './namespace-ids';
 import { PostgresNativeEnum } from './postgres-native-enum';
 
@@ -632,13 +633,21 @@ export class PgNumericCodec extends CodecImpl<
   encodeJson(value: string): JsonValue {
     const number = Number(value);
     if (!Number.isFinite(number)) {
-      throw new TypeError('pg/numeric@1 database JSON value must be a finite number');
+      throw postgresError(
+        'RUNTIME.ENCODE_FAILED',
+        'pg/numeric@1 database JSON value must be a finite number',
+        { meta: { codecId: 'pg/numeric@1', received: value } },
+      );
     }
     return number;
   }
   decodeJson(json: JsonValue): string {
     if (typeof json !== 'number') {
-      throw new TypeError('pg/numeric@1 database JSON value must be a number');
+      throw postgresError(
+        'RUNTIME.DECODE_FAILED',
+        'pg/numeric@1 database JSON value must be a number',
+        { meta: { codecId: 'pg/numeric@1', received: typeof json } },
+      );
     }
     return pgNumericDecode(json);
   }

package/src/core/errors.ts

@@ -1,4 +1,34 @@
 import { CliStructuredError } from '@prisma-next/errors/control';
+import type { StructuredError, StructuredErrorOptions } from '@prisma-next/utils/structured-error';
+import { structuredError } from '@prisma-next/utils/structured-error';
+
+export type PostgresTargetErrorCode =
+  | 'CONTRACT.CODEC_DESCRIPTOR_MISSING'
+  | 'CONTRACT.DEFAULT_INVALID'
+  | 'CONTRACT.ENTITY_KIND_INVALID'
+  | 'CONTRACT.IDENTIFIER_INVALID'
+  | 'CONTRACT.INDEX_INVALID'
+  | 'CONTRACT.INFER_UNSUPPORTED'
+  | 'CONTRACT.MODEL_UNKNOWN'
+  | 'CONTRACT.NAME_DUPLICATE'
+  | 'CONTRACT.NATIVE_TYPE_INVALID'
+  | 'CONTRACT.PACK_CONTRIBUTION_INVALID'
+  | 'CONTRACT.POLICY_INVALID'
+  | 'CONTRACT.ROLE_INVALID'
+  | 'MIGRATION.CONTRACT_SPACE_VIOLATION'
+  | 'MIGRATION.POSTGRES_CONTROL_STACK_MISSING'
+  | 'MIGRATION.TARGET_MISMATCH'
+  | 'RUNTIME.DECODE_FAILED'
+  | 'RUNTIME.ENCODE_FAILED'
+  | 'RUNTIME.TYPE_PARAMS_INVALID';
+
+export function postgresError(
+  code: PostgresTargetErrorCode,
+  message: string,
+  options?: StructuredErrorOptions,
+): StructuredError {
+  return structuredError(code, message, options);
+}
 
 /**
  * A `PostgresMigration` operation that needs the materialized control adapter

package/src/core/migrations/column-ddl-rendering.ts

@@ -5,6 +5,7 @@ import * as contractFree from '@prisma-next/sql-relational-core/contract-free';
 import type { SqlColumnDefaultIR, SqlColumnIR } from '@prisma-next/sql-schema-ir/types';
 import { blindCast } from '@prisma-next/utils/casts';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { InternalError } from '@prisma-next/utils/internal-error';
 import { postgresDefaultToDdlColumnDefault } from './op-factory-call';
 import { buildColumnDefaultSql, buildColumnTypeSql } from './planner-ddl-builders';
 import { resolveIdentityValue } from './planner-identity-values';
@@ -29,7 +30,7 @@ function columnLike(
   'nativeType' | 'codecId' | 'nullable' | 'many' | 'typeParams' | 'typeRef' | 'default'
 > {
   if (column.codecRef === undefined || column.codecBaseNativeType === undefined) {
-    throw new Error(
+    throw new InternalError(
       `columnLike: expected column "${column.name}" carries no codec identity — the expected tree must be derived via contractToSchemaIR for planning`,
     );
   }

package/src/core/migrations/contract-to-postgres-database-schema-node.ts

@@ -10,6 +10,7 @@ import {
   SqlUniqueIR,
 } from '@prisma-next/sql-schema-ir/types';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { postgresError } from '../errors';
 import type { PostgresRlsPolicy } from '../postgres-rls-policy';
 import type { PostgresContract } from '../postgres-schema';
 import { isPostgresSchema } from '../postgres-schema';
@@ -232,14 +233,25 @@ export function contractToPostgresDatabaseSchemaNode(
     for (const [tableName, tablePolicies] of policiesByTable) {
       if (!(tableName in tables)) {
         const policyName = tablePolicies[0]?.name ?? '(unknown)';
-        throw new Error(
+        throw postgresError(
+          'CONTRACT.POLICY_INVALID',
           `contract-to-postgres-database-schema-node: policy "${policyName}" references table "${tableName}" not present in namespace "${ddlSchema}"`,
+          { meta: { policyName, tableName, namespaceId: ddlSchema, reason: 'table-missing' } },
         );
       }
       if (!Object.hasOwn(ns.rls, tableName)) {
         const policyPrefix = tablePolicies[0]?.prefix ?? '(unknown)';
-        throw new Error(
+        throw postgresError(
+          'CONTRACT.POLICY_INVALID',
           `contract-to-postgres-database-schema-node: policy "${policyPrefix}" targets table "${tableName}" in namespace "${ddlSchema}", which is not RLS-controlled. Mark the model with @@rls (entries.rls["${tableName}"]) or remove the policy.`,
+          {
+            meta: {
+              policyName: policyPrefix,
+              tableName,
+              namespaceId: ddlSchema,
+              reason: 'table-not-rls-controlled',
+            },
+          },
         );
       }
     }