@prisma-next/sql-runtime 0.3.0-dev.9 → 0.3.0-pr.100.2

package/package.json

@@ -1,26 +1,27 @@
 {
   "name": "@prisma-next/sql-runtime",
-  "version": "0.3.0-dev.9",
+  "version": "0.3.0-pr.100.2",
   "type": "module",
   "sideEffects": false,
   "description": "SQL runtime implementation for Prisma Next",
   "dependencies": {
-    "@prisma-next/core-execution-plane": "0.3.0-dev.9",
-    "@prisma-next/contract": "0.3.0-dev.9",
-    "@prisma-next/operations": "0.3.0-dev.9",
-    "@prisma-next/runtime-executor": "0.3.0-dev.9",
-    "@prisma-next/sql-contract": "0.3.0-dev.9",
-    "@prisma-next/sql-operations": "0.3.0-dev.9",
-    "@prisma-next/sql-relational-core": "0.3.0-dev.9"
+    "arktype": "^2.1.26",
+    "@prisma-next/contract": "0.3.0-pr.100.2",
+    "@prisma-next/core-execution-plane": "0.3.0-pr.100.2",
+    "@prisma-next/operations": "0.3.0-pr.100.2",
+    "@prisma-next/runtime-executor": "0.3.0-pr.100.2",
+    "@prisma-next/sql-contract": "0.3.0-pr.100.2",
+    "@prisma-next/sql-operations": "0.3.0-pr.100.2",
+    "@prisma-next/sql-relational-core": "0.3.0-pr.100.2"
   },
   "devDependencies": {
     "@types/pg": "8.16.0",
-    "@vitest/coverage-v8": "4.0.16",
     "pg": "8.16.3",
     "tsup": "8.5.1",
     "typescript": "5.9.3",
     "vitest": "4.0.16",
-    "@prisma-next/test-utils": "0.0.1"
+    "@prisma-next/test-utils": "0.0.1",
+    "@prisma-next/tsconfig": "0.0.0"
   },
   "files": [
     "dist",
@@ -42,9 +43,9 @@
     "test": "vitest run --passWithNoTests",
     "test:coverage": "vitest run --coverage --passWithNoTests",
     "typecheck": "tsc --project tsconfig.json --noEmit",
-    "lint": "biome check . --config-path ../../../biome.json --error-on-warnings",
-    "lint:fix": "biome check --write . --config-path ../../../biome.json",
-    "lint:fix:unsafe": "biome check --write --unsafe . --config-path ../../../biome.json",
-    "clean": "node ../../../scripts/clean.mjs"
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
   }
 }

package/src/exports/index.ts

@@ -16,9 +16,11 @@ export { lowerSqlPlan } from '../lower-sql-plan';
 export type {
   CreateRuntimeContextOptions,
   RuntimeContext,
+  RuntimeParameterizedCodecDescriptor,
   SqlRuntimeAdapterInstance,
   SqlRuntimeExtensionDescriptor,
   SqlRuntimeExtensionInstance,
+  TypeHelperRegistry,
 } from '../sql-context';
 export { createRuntimeContext } from '../sql-context';
 export type { SqlStatement } from '../sql-marker';

package/src/sql-context.ts

@@ -6,7 +6,7 @@ import type {
   RuntimeTargetDescriptor,
 } from '@prisma-next/core-execution-plane/types';
 import { createOperationRegistry } from '@prisma-next/operations';
-import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { SqlContract, SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
 import type { SqlOperationSignature } from '@prisma-next/sql-operations';
 import type {
   Adapter,
@@ -15,7 +15,42 @@ import type {
   QueryAst,
 } from '@prisma-next/sql-relational-core/ast';
 import { createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
-import type { QueryLaneContext } from '@prisma-next/sql-relational-core/query-lane-context';
+import type {
+  QueryLaneContext,
+  TypeHelperRegistry,
+} from '@prisma-next/sql-relational-core/query-lane-context';
+import type { Type } from 'arktype';
+import { type as arktype } from 'arktype';
+
+// ============================================================================
+// Runtime Parameterized Codec Descriptor Types
+// ============================================================================
+
+/**
+ * Runtime parameterized codec descriptor.
+ * Provides validation schema and optional init hook for codecs that support type parameters.
+ * Used at runtime to validate typeParams and create type helpers.
+ */
+export interface RuntimeParameterizedCodecDescriptor<
+  TParams = Record<string, unknown>,
+  THelper = unknown,
+> {
+  /** The codec ID this descriptor applies to (e.g., 'pg/vector@1') */
+  readonly codecId: string;
+
+  /**
+   * Arktype schema for validating typeParams.
+   * The schema is used to validate both storage.types entries and inline column typeParams.
+   */
+  readonly paramsSchema: Type<TParams>;
+
+  /**
+   * Optional init hook called during runtime context creation.
+   * Receives validated params and returns a helper object to be stored in context.types.
+   * If not provided, the validated params are stored directly.
+   */
+  readonly init?: (params: TParams) => THelper;
+}
 
 // ============================================================================
 // SQL Runtime Extension Types
@@ -34,6 +69,12 @@ export interface SqlRuntimeExtensionInstance<TTargetId extends string>
   codecs?(): CodecRegistry;
   /** Returns operations to register in the runtime context. */
   operations?(): ReadonlyArray<SqlOperationSignature>;
+  /**
+   * Returns parameterized codec descriptors for type validation and helper creation.
+   * Uses unknown for type parameters to allow any concrete descriptor types.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: needed for covariance with concrete descriptor types
+  parameterizedCodecs?(): ReadonlyArray<RuntimeParameterizedCodecDescriptor<any, any>>;
 }
 
 /**
@@ -68,11 +109,21 @@ export type SqlRuntimeAdapterInstance<TTargetId extends string = string> = Runti
 // SQL Runtime Context
 // ============================================================================
 
+export type { TypeHelperRegistry };
+
 export interface RuntimeContext<TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>>
   extends QueryLaneContext<TContract> {
   readonly adapter:
     | Adapter<QueryAst, TContract, LoweredStatement>
     | Adapter<QueryAst, SqlContract<SqlStorage>, LoweredStatement>;
+
+  /**
+   * Initialized type helpers from storage.types.
+   * Each entry corresponds to a named type instance in the contract's storage.types.
+   * The value is the result of calling the codec's init hook (if provided)
+   * or the validated typeParams (if no init hook).
+   */
+  readonly types?: TypeHelperRegistry;
 }
 
 /**
@@ -96,6 +147,185 @@ export interface CreateRuntimeContextOptions<
   readonly extensionPacks?: ReadonlyArray<SqlRuntimeExtensionDescriptor<TTargetId>>;
 }
 
+// ============================================================================
+// Runtime Error Types and Helpers
+// ============================================================================
+
+/**
+ * Structured error thrown by the SQL runtime.
+ *
+ * Aligns with the repository's error envelope convention:
+ * - `code`: Stable error code for programmatic handling (e.g., `RUNTIME.TYPE_PARAMS_INVALID`)
+ * - `category`: Error source category (`RUNTIME`)
+ * - `severity`: Error severity level (`error`)
+ * - `details`: Optional structured details for debugging
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   createRuntimeContext({ ... });
+ * } catch (e) {
+ *   if ((e as RuntimeError).code === 'RUNTIME.TYPE_PARAMS_INVALID') {
+ *     console.error('Invalid type parameters:', (e as RuntimeError).details);
+ *   }
+ * }
+ * ```
+ */
+export interface RuntimeError extends Error {
+  /** Stable error code for programmatic handling (e.g., `RUNTIME.TYPE_PARAMS_INVALID`) */
+  readonly code: string;
+  /** Error source category */
+  readonly category: 'RUNTIME';
+  /** Error severity level */
+  readonly severity: 'error';
+  /** Optional structured details for debugging */
+  readonly details?: Record<string, unknown>;
+}
+
+/**
+ * Creates a RuntimeError for invalid type parameters.
+ *
+ * Error code: `RUNTIME.TYPE_PARAMS_INVALID`
+ *
+ * Thrown when:
+ * - `storage.types` entries have typeParams that fail codec schema validation
+ * - Column inline typeParams fail codec schema validation
+ *
+ * @internal
+ */
+function runtimeTypeParamsInvalid(
+  message: string,
+  details?: Record<string, unknown>,
+): RuntimeError {
+  const error = new Error(message) as RuntimeError;
+  Object.defineProperty(error, 'name', { value: 'RuntimeError', configurable: true });
+  return Object.assign(error, {
+    code: 'RUNTIME.TYPE_PARAMS_INVALID',
+    category: 'RUNTIME' as const,
+    severity: 'error' as const,
+    details,
+  });
+}
+
+// ============================================================================
+// Parameterized Type Validation
+// ============================================================================
+
+/**
+ * Validates typeParams against the codec's paramsSchema.
+ * @throws RuntimeError with code RUNTIME.TYPE_PARAMS_INVALID if validation fails
+ */
+function validateTypeParams(
+  typeParams: Record<string, unknown>,
+  codecDescriptor: RuntimeParameterizedCodecDescriptor,
+  context: { typeName?: string; tableName?: string; columnName?: string },
+): Record<string, unknown> {
+  const result = codecDescriptor.paramsSchema(typeParams);
+  if (result instanceof arktype.errors) {
+    const messages = result.map((p: { message: string }) => p.message).join('; ');
+    const locationInfo = context.typeName
+      ? `type '${context.typeName}'`
+      : `column '${context.tableName}.${context.columnName}'`;
+    throw runtimeTypeParamsInvalid(
+      `Invalid typeParams for ${locationInfo} (codecId: ${codecDescriptor.codecId}): ${messages}`,
+      { ...context, codecId: codecDescriptor.codecId, typeParams },
+    );
+  }
+  return result as Record<string, unknown>;
+}
+
+/**
+ * Collects parameterized codec descriptors from extension instances.
+ * Returns a map of codecId → descriptor for quick lookup.
+ */
+function collectParameterizedCodecDescriptors(
+  extensionInstances: ReadonlyArray<SqlRuntimeExtensionInstance<string>>,
+): Map<string, RuntimeParameterizedCodecDescriptor> {
+  const descriptors = new Map<string, RuntimeParameterizedCodecDescriptor>();
+
+  for (const extInstance of extensionInstances) {
+    const paramCodecs = extInstance.parameterizedCodecs?.();
+    if (paramCodecs) {
+      for (const descriptor of paramCodecs) {
+        if (descriptors.has(descriptor.codecId)) {
+          console.warn(
+            `Duplicate parameterized codec descriptor for codecId '${descriptor.codecId}' - using later registration`,
+          );
+        }
+        descriptors.set(descriptor.codecId, descriptor);
+      }
+    }
+  }
+
+  return descriptors;
+}
+
+/**
+ * Initializes type helpers from storage.types using codec descriptors.
+ *
+ * For each named type instance in `storage.types`:
+ * - If a codec descriptor exists with an `init` hook: calls the hook and stores the result
+ * - Otherwise: stores the full type instance metadata directly (codecId, nativeType, typeParams)
+ *
+ * This matches the typing in `ExtractSchemaTypes<Contract>` which extracts
+ * `Contract['storage']['types']` directly, ensuring runtime values match static types
+ * when no init hook transforms the value.
+ */
+function initializeTypeHelpers(
+  storageTypes: Record<string, StorageTypeInstance> | undefined,
+  codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
+): TypeHelperRegistry {
+  const helpers: TypeHelperRegistry = {};
+
+  if (!storageTypes) {
+    return helpers;
+  }
+
+  for (const [typeName, typeInstance] of Object.entries(storageTypes)) {
+    const descriptor = codecDescriptors.get(typeInstance.codecId);
+
+    if (descriptor) {
+      // Validate typeParams against the codec's schema
+      const validatedParams = validateTypeParams(typeInstance.typeParams, descriptor, {
+        typeName,
+      });
+
+      // Call init hook if provided, otherwise store full type instance
+      if (descriptor.init) {
+        helpers[typeName] = descriptor.init(validatedParams);
+      } else {
+        // No init hook: expose full type instance metadata (matches contract typing)
+        helpers[typeName] = typeInstance;
+      }
+    } else {
+      // No descriptor found: expose full type instance (no validation possible)
+      helpers[typeName] = typeInstance;
+    }
+  }
+
+  return helpers;
+}
+
+/**
+ * Validates inline column typeParams across all tables.
+ * @throws RuntimeError with code RUNTIME.TYPE_PARAMS_INVALID if validation fails
+ */
+function validateColumnTypeParams(
+  storage: SqlStorage,
+  codecDescriptors: Map<string, RuntimeParameterizedCodecDescriptor>,
+): void {
+  for (const [tableName, table] of Object.entries(storage.tables)) {
+    for (const [columnName, column] of Object.entries(table.columns)) {
+      if (column.typeParams) {
+        const descriptor = codecDescriptors.get(column.codecId);
+        if (descriptor) {
+          validateTypeParams(column.typeParams, descriptor, { tableName, columnName });
+        }
+      }
+    }
+  }
+}
+
 /**
  * Creates a SQL runtime context from descriptor-first composition.
  *
@@ -104,6 +334,7 @@ export interface CreateRuntimeContextOptions<
  * - The adapter instance (created from descriptor)
  * - Codec registry (populated from adapter + extension instances)
  * - Operation registry (populated from extension instances)
+ * - Types registry (initialized helpers from storage.types)
  *
  * @param options - Descriptor-first composition options
  * @returns RuntimeContext with registries wired from all components
@@ -128,9 +359,12 @@ export function createRuntimeContext<
     codecRegistry.register(codec);
   }
 
-  // Create extension instances and register their codecs/operations
+  // Create extension instances and collect their contributions
+  const extensionInstances: SqlRuntimeExtensionInstance<TTargetId>[] = [];
+
   for (const extDescriptor of extensionPacks ?? []) {
     const extInstance = extDescriptor.create();
+    extensionInstances.push(extInstance);
 
     const extCodecs = extInstance.codecs?.();
     if (extCodecs) {
@@ -147,10 +381,22 @@ export function createRuntimeContext<
     }
   }
 
+  // Collect parameterized codec descriptors from extensions
+  const parameterizedCodecDescriptors = collectParameterizedCodecDescriptors(extensionInstances);
+
+  // Validate column typeParams if any descriptors are registered
+  if (parameterizedCodecDescriptors.size > 0) {
+    validateColumnTypeParams(contract.storage, parameterizedCodecDescriptors);
+  }
+
+  // Initialize type helpers from storage.types
+  const types = initializeTypeHelpers(contract.storage.types, parameterizedCodecDescriptors);
+
   return {
     contract,
     adapter: adapterInstance,
     operations: operationRegistry,
     codecs: codecRegistry,
+    types,
   };
 }

package/test/context.types.test-d.ts

@@ -0,0 +1,70 @@
+import type { SqlContract, SqlMappings, SqlStorage } from '@prisma-next/sql-contract/types';
+import { expectTypeOf, test } from 'vitest';
+import type { RuntimeContext, TypeHelperRegistry } from '../src/sql-context';
+
+// Contract type with storage.types using literal types (matching emission output)
+type TestContract = SqlContract<
+  {
+    readonly tables: {
+      readonly document: {
+        readonly columns: {
+          readonly id: {
+            readonly nativeType: 'int4';
+            readonly codecId: 'pg/int4@1';
+            nullable: false;
+          };
+        };
+        readonly primaryKey: { readonly columns: readonly ['id'] };
+        readonly uniques: readonly [];
+        readonly indexes: readonly [];
+        readonly foreignKeys: readonly [];
+      };
+    };
+    readonly types: {
+      readonly Vector1536: {
+        readonly codecId: 'pg/vector@1';
+        readonly nativeType: 'vector';
+        readonly typeParams: { readonly length: 1536 };
+      };
+    };
+  },
+  Record<string, never>,
+  Record<string, never>,
+  SqlMappings
+>;
+
+test('RuntimeContext.types is TypeHelperRegistry', () => {
+  // RuntimeContext.types is intentionally loose (Record<string, unknown>)
+  // The strong typing comes from schema(context).types via ExtractSchemaTypes
+  expectTypeOf<RuntimeContext<TestContract>['types']>().toEqualTypeOf<
+    TypeHelperRegistry | undefined
+  >();
+
+  // TypeHelperRegistry allows any values - the actual type depends on init hooks
+  expectTypeOf<TypeHelperRegistry>().toEqualTypeOf<Record<string, unknown>>();
+});
+
+test('RuntimeContext preserves contract type parameter', () => {
+  // Verify the contract type is preserved in RuntimeContext
+  expectTypeOf<RuntimeContext<TestContract>['contract']>().toEqualTypeOf<TestContract>();
+
+  // Verify we can access storage.types through the context's contract
+  type ContractStorageTypes = RuntimeContext<TestContract>['contract']['storage']['types'];
+  expectTypeOf<ContractStorageTypes>().toExtend<
+    | {
+        readonly Vector1536: {
+          readonly codecId: 'pg/vector@1';
+          readonly nativeType: 'vector';
+          readonly typeParams: { readonly length: 1536 };
+        };
+      }
+    | undefined
+  >();
+});
+
+test('RuntimeContext accepts generic SqlContract', () => {
+  // Verify RuntimeContext defaults work
+  type DefaultContext = RuntimeContext;
+  expectTypeOf<DefaultContext['contract']>().toExtend<SqlContract<SqlStorage>>();
+  expectTypeOf<DefaultContext['types']>().toEqualTypeOf<TypeHelperRegistry | undefined>();
+});