@prisma-next/sql-runtime 0.3.0-dev.2 → 0.3.0-dev.20

package/test/sql-runtime.test.ts

@@ -0,0 +1,155 @@
+import { createOperationRegistry } from '@prisma-next/operations';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type {
+  CodecRegistry,
+  SelectAst,
+  SqlDriver,
+  SqlExecuteRequest,
+} from '@prisma-next/sql-relational-core/ast';
+import { codec, createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import { describe, expect, it, vi } from 'vitest';
+import type { RuntimeContext } from '../src/sql-context';
+import { createRuntime } from '../src/sql-runtime';
+
+// Minimal test contract
+const testContract: SqlContract<SqlStorage> = {
+  schemaVersion: '1',
+  targetFamily: 'sql',
+  target: 'postgres',
+  coreHash: 'sha256:test',
+  models: {},
+  relations: {},
+  storage: { tables: {} },
+  extensionPacks: {},
+  capabilities: {},
+  meta: {},
+  sources: {},
+  mappings: {
+    codecTypes: {},
+    operationTypes: {},
+  },
+};
+
+// Create a stub codec registry
+function createStubCodecs(): CodecRegistry {
+  const registry = createCodecRegistry();
+  registry.register(
+    codec({
+      typeId: 'pg/int4@1',
+      targetTypes: ['int4'],
+      encode: (v: number) => v,
+      decode: (w: number) => w,
+    }),
+  );
+  return registry;
+}
+
+// Create a stub adapter
+function createStubAdapter() {
+  const codecs = createStubCodecs();
+  return {
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    profile: {
+      id: 'test-profile',
+      target: 'postgres',
+      capabilities: {},
+      codecs() {
+        return codecs;
+      },
+    },
+    lower(ast: SelectAst) {
+      return {
+        profileId: 'test-profile',
+        body: Object.freeze({ sql: JSON.stringify(ast), params: [] }),
+      };
+    },
+  };
+}
+
+// Create a mock driver that implements SqlDriver interface
+function createMockDriver(): SqlDriver {
+  const execute = vi.fn().mockImplementation(async function* (_request: SqlExecuteRequest) {
+    yield { id: 1 };
+  });
+
+  return {
+    connect: vi.fn().mockResolvedValue(undefined),
+    execute,
+    query: vi.fn().mockResolvedValue({ rows: [], rowCount: 0 }),
+    close: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+// Create a test runtime context
+function createTestContext(contract: SqlContract<SqlStorage>): RuntimeContext<typeof contract> {
+  const adapter = createStubAdapter();
+  return {
+    contract,
+    adapter,
+    codecs: adapter.profile.codecs(),
+    operations: createOperationRegistry(),
+  };
+}
+
+describe('createRuntime', () => {
+  it('creates runtime with valid options', () => {
+    const context = createTestContext(testContract);
+    const driver = createMockDriver();
+
+    const runtime = createRuntime({
+      context,
+      driver,
+      verify: { mode: 'onFirstUse', requireMarker: false },
+    });
+
+    expect(runtime).toBeDefined();
+    expect(runtime.execute).toBeDefined();
+    expect(runtime.telemetry).toBeDefined();
+    expect(runtime.operations).toBeDefined();
+    expect(runtime.close).toBeDefined();
+  });
+
+  it('returns operations registry', () => {
+    const context = createTestContext(testContract);
+    const driver = createMockDriver();
+
+    const runtime = createRuntime({
+      context,
+      driver,
+      verify: { mode: 'onFirstUse', requireMarker: false },
+    });
+
+    const ops = runtime.operations();
+    expect(ops).toBeDefined();
+    expect(ops.byType).toBeDefined();
+  });
+
+  it('returns null telemetry when no events', () => {
+    const context = createTestContext(testContract);
+    const driver = createMockDriver();
+
+    const runtime = createRuntime({
+      context,
+      driver,
+      verify: { mode: 'onFirstUse', requireMarker: false },
+    });
+
+    // Before any execution, telemetry should be null
+    expect(runtime.telemetry()).toBeNull();
+  });
+
+  it('closes runtime', async () => {
+    const context = createTestContext(testContract);
+    const driver = createMockDriver();
+
+    const runtime = createRuntime({
+      context,
+      driver,
+      verify: { mode: 'onFirstUse', requireMarker: false },
+    });
+
+    await runtime.close();
+    expect(driver.close).toHaveBeenCalled();
+  });
+});

package/test/utils.ts

@@ -0,0 +1,266 @@
+import type { ExecutionPlan, ResultType } from '@prisma-next/contract/types';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { Adapter, LoweredStatement, SelectAst } from '@prisma-next/sql-relational-core/ast';
+import { codec, createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import { collectAsync, drainAsyncIterable } from '@prisma-next/test-utils';
+import type { Client } from 'pg';
+import type { SqlStatement } from '../src/exports';
+import {
+  type createRuntime,
+  createRuntimeContext,
+  ensureSchemaStatement,
+  ensureTableStatement,
+  writeContractMarker,
+} from '../src/exports';
+import type {
+  RuntimeContext,
+  SqlRuntimeAdapterInstance,
+  SqlRuntimeExtensionDescriptor,
+} from '../src/sql-context';
+
+/**
+ * Executes a plan and collects all results into an array.
+ * This helper DRYs up the common pattern of executing plans in tests.
+ * The return type is inferred from the plan's type parameter.
+ */
+export async function executePlanAndCollect<
+  P extends ExecutionPlan<ResultType<P>> | SqlQueryPlan<ResultType<P>>,
+>(runtime: ReturnType<typeof createRuntime>, plan: P): Promise<ResultType<P>[]> {
+  type Row = ResultType<P>;
+  return collectAsync<Row>(runtime.execute<Row>(plan));
+}
+
+/**
+ * Drains a plan execution, consuming all results without collecting them.
+ * Useful for testing side effects without memory overhead.
+ */
+export async function drainPlanExecution(
+  runtime: ReturnType<typeof createRuntime>,
+  plan: ExecutionPlan | SqlQueryPlan<unknown>,
+): Promise<void> {
+  return drainAsyncIterable(runtime.execute(plan));
+}
+
+/**
+ * Executes a SQL statement on a database client.
+ */
+export async function executeStatement(client: Client, statement: SqlStatement): Promise<void> {
+  if (statement.params.length > 0) {
+    await client.query(statement.sql, [...statement.params]);
+    return;
+  }
+
+  await client.query(statement.sql);
+}
+
+/**
+ * Sets up database schema and data, then writes the contract marker.
+ * This helper DRYs up the common pattern of database setup in tests.
+ */
+export async function setupTestDatabase(
+  client: Client,
+  contract: SqlContract<SqlStorage>,
+  setupFn: (client: Client) => Promise<void>,
+): Promise<void> {
+  await client.query('drop schema if exists prisma_contract cascade');
+  await client.query('create schema if not exists public');
+
+  await setupFn(client);
+
+  await executeStatement(client, ensureSchemaStatement);
+  await executeStatement(client, ensureTableStatement);
+  const write = writeContractMarker({
+    coreHash: contract.coreHash,
+    profileHash: contract.profileHash ?? contract.coreHash,
+    contractJson: contract,
+    canonicalVersion: 1,
+  });
+  await executeStatement(client, write.insert);
+}
+
+/**
+ * Writes a contract marker to the database.
+ * This helper DRYs up the common pattern of writing contract markers in tests.
+ */
+export async function writeTestContractMarker(
+  client: Client,
+  contract: SqlContract<SqlStorage>,
+): Promise<void> {
+  const write = writeContractMarker({
+    coreHash: contract.coreHash,
+    profileHash: contract.profileHash ?? contract.coreHash,
+    contractJson: contract,
+    canonicalVersion: 1,
+  });
+  await executeStatement(client, write.insert);
+}
+
+/**
+ * Creates a test adapter descriptor from a raw adapter.
+ * This wraps the adapter in a descriptor for descriptor-first context creation in tests.
+ * The adapter instance IS an Adapter (via intersection), with identity properties added.
+ */
+function createTestAdapterDescriptor(
+  adapter: Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+): {
+  readonly kind: 'adapter';
+  readonly id: string;
+  readonly version: string;
+  readonly familyId: 'sql';
+  readonly targetId: 'postgres';
+  create(): SqlRuntimeAdapterInstance<'postgres'>;
+} {
+  return {
+    kind: 'adapter' as const,
+    id: 'test-adapter',
+    version: '0.0.1',
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    create(): SqlRuntimeAdapterInstance<'postgres'> {
+      // Return an object that combines identity properties with the adapter's methods
+      return Object.assign(
+        {
+          familyId: 'sql' as const,
+          targetId: 'postgres' as const,
+        },
+        adapter,
+      );
+    },
+  };
+}
+
+/**
+ * Creates a test target descriptor.
+ * This is a minimal descriptor for descriptor-first context creation in tests.
+ */
+function createTestTargetDescriptor(): {
+  readonly kind: 'target';
+  readonly id: string;
+  readonly version: string;
+  readonly familyId: 'sql';
+  readonly targetId: 'postgres';
+  create(): { readonly familyId: 'sql'; readonly targetId: 'postgres' };
+} {
+  return {
+    kind: 'target' as const,
+    id: 'postgres',
+    version: '0.0.1',
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    create() {
+      return { familyId: 'sql' as const, targetId: 'postgres' as const };
+    },
+  };
+}
+
+/**
+ * Creates a runtime context with standard test configuration.
+ * This helper DRYs up the common pattern of context creation in tests.
+ *
+ * Accepts a raw adapter and optional extension descriptors, wrapping the
+ * adapter in a descriptor internally for descriptor-first context creation.
+ */
+export function createTestContext<TContract extends SqlContract<SqlStorage>>(
+  contract: TContract,
+  adapter: Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+  options?: {
+    extensionPacks?: ReadonlyArray<SqlRuntimeExtensionDescriptor<'postgres'>>;
+  },
+): RuntimeContext<TContract> {
+  return createRuntimeContext<TContract, 'postgres'>({
+    contract,
+    target: createTestTargetDescriptor(),
+    adapter: createTestAdapterDescriptor(adapter),
+    extensionPacks: options?.extensionPacks ?? [],
+  });
+}
+
+/**
+ * Creates a stub adapter for testing.
+ * This helper DRYs up the common pattern of adapter creation in tests.
+ *
+ * The stub adapter includes simple codecs for common test types (pg/int4@1, pg/text@1, pg/timestamptz@1)
+ * to enable type inference in tests without requiring the postgres adapter package.
+ */
+export function createStubAdapter(): Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement> {
+  const codecRegistry = createCodecRegistry();
+
+  // Register stub codecs for common test types
+  // These match the codec IDs used in test contracts (pg/int4@1, pg/text@1, pg/timestamptz@1)
+  // but don't require importing from the postgres adapter package
+  codecRegistry.register(
+    codec({
+      typeId: 'pg/int4@1',
+      targetTypes: ['int4'],
+      encode: (value: number) => value,
+      decode: (wire: number) => wire,
+    }),
+  );
+
+  codecRegistry.register(
+    codec({
+      typeId: 'pg/text@1',
+      targetTypes: ['text'],
+      encode: (value: string) => value,
+      decode: (wire: string) => wire,
+    }),
+  );
+
+  codecRegistry.register(
+    codec({
+      typeId: 'pg/timestamptz@1',
+      targetTypes: ['timestamptz'],
+      encode: (value: string | Date) => (value instanceof Date ? value.toISOString() : value),
+      decode: (wire: string | Date) =>
+        typeof wire === 'string' ? wire : wire instanceof Date ? wire.toISOString() : String(wire),
+    }),
+  );
+
+  return {
+    profile: {
+      id: 'stub-profile',
+      target: 'postgres',
+      capabilities: {},
+      codecs() {
+        return codecRegistry;
+      },
+    },
+    lower(ast: SelectAst, ctx: { contract: SqlContract<SqlStorage>; params?: readonly unknown[] }) {
+      const sqlText = JSON.stringify(ast);
+      return {
+        profileId: this.profile.id,
+        body: Object.freeze({ sql: sqlText, params: ctx.params ? [...ctx.params] : [] }),
+      };
+    },
+  };
+}
+
+/**
+ * Creates a valid test contract without using validateContract.
+ * Ensures all required fields are present (mappings, capabilities, extensionPacks, meta, sources)
+ * and returns the contract with proper typing.
+ * This helper allows tests to create contracts without depending on sql-query.
+ */
+export function createTestContract<T extends SqlContract<SqlStorage>>(
+  contract: Partial<T> &
+    Omit<T, 'mappings' | 'capabilities' | 'extensionPacks' | 'meta' | 'sources'>,
+): T {
+  return {
+    ...contract,
+    mappings: contract.mappings ?? { codecTypes: {}, operationTypes: {} },
+    capabilities: contract.capabilities ?? {},
+    extensionPacks: contract.extensionPacks ?? {},
+    meta: contract.meta ?? {},
+    sources: contract.sources ?? {},
+  } as T;
+}
+
+// Re-export generic utilities from test-utils
+export {
+  collectAsync,
+  createDevDatabase,
+  type DevDatabase,
+  teardownTestDatabase,
+  withClient,
+} from '@prisma-next/test-utils';

package/dist/index.d.ts

@@ -1,29 +0,0 @@
-export { AfterExecuteResult, BudgetsOptions, LintsOptions, Log, Plugin, PluginContext, RuntimeTelemetryEvent, RuntimeVerifyOptions, TelemetryOutcome, budgets, lints } from '@prisma-next/runtime-executor';
-import { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
-import { CodecRegistry } from '@prisma-next/sql-relational-core/ast';
-import { ExecutionPlan } from '@prisma-next/contract/types';
-import { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
-import { R as RuntimeContext } from './sql-runtime-DgEbg2OP.js';
-export { C as CreateRuntimeContextOptions, g as Runtime, h as RuntimeOptions, S as SqlRuntimeAdapterInstance, a as SqlRuntimeExtensionDescriptor, b as SqlRuntimeExtensionInstance, d as SqlStatement, i as createRuntime, c as createRuntimeContext, e as ensureSchemaStatement, f as ensureTableStatement, r as readContractMarker, w as writeContractMarker } from './sql-runtime-DgEbg2OP.js';
-import '@prisma-next/operations';
-import '@prisma-next/core-execution-plane/types';
-import '@prisma-next/sql-operations';
-import '@prisma-next/sql-relational-core/query-lane-context';
-
-declare function extractCodecIds(contract: SqlContract<SqlStorage>): Set<string>;
-declare function validateContractCodecMappings(registry: CodecRegistry, contract: SqlContract<SqlStorage>): void;
-declare function validateCodecRegistryCompleteness(registry: CodecRegistry, contract: SqlContract<SqlStorage>): void;
-
-/**
- * Lowers a SQL query plan to an executable Plan by calling the adapter's lower method.
- *
- * This function is responsible for converting a lane-produced SqlQueryPlan (which contains
- * AST and params but no SQL) into a fully executable Plan (which includes SQL string).
- *
- * @param context - Runtime context containing the adapter
- * @param queryPlan - SQL query plan from a lane (contains AST, params, meta, but no SQL)
- * @returns Fully executable Plan with SQL string
- */
-declare function lowerSqlPlan<Row>(context: RuntimeContext, queryPlan: SqlQueryPlan<Row>): ExecutionPlan<Row>;
-
-export { RuntimeContext, extractCodecIds, lowerSqlPlan, validateCodecRegistryCompleteness, validateContractCodecMappings };

package/dist/sql-runtime-DgEbg2OP.d.ts

@@ -1,109 +0,0 @@
-import { MarkerStatement, AsyncIterableResult, RuntimeTelemetryEvent, RuntimeVerifyOptions, Plugin, Log } from '@prisma-next/runtime-executor';
-import { ExecutionPlan } from '@prisma-next/contract/types';
-import { OperationRegistry } from '@prisma-next/operations';
-import { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
-import { Adapter, QueryAst, LoweredStatement, CodecRegistry, SqlDriver, SelectAst } from '@prisma-next/sql-relational-core/ast';
-import { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
-import { RuntimeTargetDescriptor, RuntimeAdapterDescriptor, RuntimeAdapterInstance, RuntimeExtensionDescriptor, RuntimeExtensionInstance } from '@prisma-next/core-execution-plane/types';
-import { SqlOperationSignature } from '@prisma-next/sql-operations';
-import { QueryLaneContext } from '@prisma-next/sql-relational-core/query-lane-context';
-
-/**
- * SQL runtime extension instance.
- * Extends the framework RuntimeExtensionInstance with SQL-specific hooks
- * for contributing codecs and operations to the runtime context.
- *
- * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
- */
-interface SqlRuntimeExtensionInstance<TTargetId extends string> extends RuntimeExtensionInstance<'sql', TTargetId> {
-    /** Returns codecs to register in the runtime context. */
-    codecs?(): CodecRegistry;
-    /** Returns operations to register in the runtime context. */
-    operations?(): ReadonlyArray<SqlOperationSignature>;
-}
-/**
- * SQL runtime extension descriptor.
- * Extends the framework RuntimeExtensionDescriptor with SQL-specific instance type.
- *
- * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
- */
-interface SqlRuntimeExtensionDescriptor<TTargetId extends string> extends RuntimeExtensionDescriptor<'sql', TTargetId, SqlRuntimeExtensionInstance<TTargetId>> {
-    create(): SqlRuntimeExtensionInstance<TTargetId>;
-}
-/**
- * SQL runtime adapter instance interface.
- * Combines RuntimeAdapterInstance identity with SQL Adapter behavior.
- * The instance IS an Adapter (via intersection), not HAS an adapter property.
- *
- * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
- */
-type SqlRuntimeAdapterInstance<TTargetId extends string = string> = RuntimeAdapterInstance<'sql', TTargetId> & Adapter<QueryAst, SqlContract<SqlStorage>, LoweredStatement>;
-interface RuntimeContext<TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>> extends QueryLaneContext<TContract> {
-    readonly adapter: Adapter<QueryAst, TContract, LoweredStatement> | Adapter<QueryAst, SqlContract<SqlStorage>, LoweredStatement>;
-}
-/**
- * Descriptor-first options for creating a SQL runtime context.
- * Takes the same framework composition as control-plane: target, adapter, extensionPacks.
- *
- * @template TContract - The SQL contract type
- * @template TTargetId - The target ID (e.g., 'postgres', 'mysql')
- */
-interface CreateRuntimeContextOptions<TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>, TTargetId extends string = string> {
-    readonly contract: TContract;
-    readonly target: RuntimeTargetDescriptor<'sql', TTargetId>;
-    readonly adapter: RuntimeAdapterDescriptor<'sql', TTargetId, SqlRuntimeAdapterInstance<TTargetId>>;
-    readonly extensionPacks?: ReadonlyArray<SqlRuntimeExtensionDescriptor<TTargetId>>;
-}
-/**
- * Creates a SQL runtime context from descriptor-first composition.
- *
- * The context includes:
- * - The validated contract
- * - The adapter instance (created from descriptor)
- * - Codec registry (populated from adapter + extension instances)
- * - Operation registry (populated from extension instances)
- *
- * @param options - Descriptor-first composition options
- * @returns RuntimeContext with registries wired from all components
- */
-declare function createRuntimeContext<TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>, TTargetId extends string = string>(options: CreateRuntimeContextOptions<TContract, TTargetId>): RuntimeContext<TContract>;
-
-interface SqlStatement {
-    readonly sql: string;
-    readonly params: readonly unknown[];
-}
-interface WriteMarkerInput {
-    readonly coreHash: string;
-    readonly profileHash: string;
-    readonly contractJson?: unknown;
-    readonly canonicalVersion?: number;
-    readonly appTag?: string;
-    readonly meta?: Record<string, unknown>;
-}
-declare const ensureSchemaStatement: SqlStatement;
-declare const ensureTableStatement: SqlStatement;
-declare function readContractMarker(): MarkerStatement;
-interface WriteContractMarkerStatements {
-    readonly insert: SqlStatement;
-    readonly update: SqlStatement;
-}
-declare function writeContractMarker(input: WriteMarkerInput): WriteContractMarkerStatements;
-
-interface RuntimeOptions<TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>> {
-    readonly driver: SqlDriver;
-    readonly verify: RuntimeVerifyOptions;
-    readonly context: RuntimeContext<TContract>;
-    readonly plugins?: readonly Plugin<TContract, Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>, SqlDriver>[];
-    readonly mode?: 'strict' | 'permissive';
-    readonly log?: Log;
-}
-interface Runtime {
-    execute<Row = Record<string, unknown>>(plan: ExecutionPlan<Row> | SqlQueryPlan<Row>): AsyncIterableResult<Row>;
-    telemetry(): RuntimeTelemetryEvent | null;
-    close(): Promise<void>;
-    operations(): OperationRegistry;
-}
-
-declare function createRuntime<TContract extends SqlContract<SqlStorage>>(options: RuntimeOptions<TContract>): Runtime;
-
-export { type CreateRuntimeContextOptions as C, type RuntimeContext as R, type SqlRuntimeAdapterInstance as S, type SqlRuntimeExtensionDescriptor as a, type SqlRuntimeExtensionInstance as b, createRuntimeContext as c, type SqlStatement as d, ensureSchemaStatement as e, ensureTableStatement as f, type Runtime as g, type RuntimeOptions as h, createRuntime as i, readContractMarker as r, writeContractMarker as w };