@prisma-next/sql-runtime 0.3.0-dev.4 → 0.3.0-dev.40

package/src/sql-runtime.ts

@@ -0,0 +1,232 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import type { ExecutionStackInstance } from '@prisma-next/core-execution-plane/stack';
+import type { RuntimeDriverInstance } from '@prisma-next/core-execution-plane/types';
+import type { OperationRegistry } from '@prisma-next/operations';
+import type {
+  Log,
+  Plugin,
+  RuntimeCore,
+  RuntimeCoreOptions,
+  RuntimeTelemetryEvent,
+  RuntimeVerifyOptions,
+  TelemetryOutcome,
+} from '@prisma-next/runtime-executor';
+import { AsyncIterableResult, createRuntimeCore } from '@prisma-next/runtime-executor';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type {
+  Adapter,
+  CodecRegistry,
+  LoweredStatement,
+  QueryAst,
+  SelectAst,
+  SqlDriver,
+} from '@prisma-next/sql-relational-core/ast';
+import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import type { JsonSchemaValidatorRegistry } from '@prisma-next/sql-relational-core/query-lane-context';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { decodeRow } from './codecs/decoding';
+import { encodeParams } from './codecs/encoding';
+import { validateCodecRegistryCompleteness } from './codecs/validation';
+import { lowerSqlPlan } from './lower-sql-plan';
+import type {
+  ExecutionContext,
+  SqlRuntimeAdapterInstance,
+  SqlRuntimeExtensionInstance,
+} from './sql-context';
+import { SqlFamilyAdapter } from './sql-family-adapter';
+
+export interface RuntimeOptions<
+  TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
+> {
+  readonly context: ExecutionContext<TContract>;
+  readonly adapter: Adapter<QueryAst, SqlContract<SqlStorage>, LoweredStatement>;
+  readonly driver: SqlDriver<unknown>;
+  readonly verify: RuntimeVerifyOptions;
+  readonly plugins?: readonly Plugin<
+    TContract,
+    Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+    SqlDriver<unknown>
+  >[];
+  readonly mode?: 'strict' | 'permissive';
+  readonly log?: Log;
+}
+
+export interface CreateRuntimeOptions<
+  TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
+  TTargetId extends string = string,
+> {
+  readonly stackInstance: ExecutionStackInstance<
+    'sql',
+    TTargetId,
+    SqlRuntimeAdapterInstance<TTargetId>,
+    RuntimeDriverInstance<'sql', TTargetId>,
+    SqlRuntimeExtensionInstance<TTargetId>
+  >;
+  readonly context: ExecutionContext<TContract>;
+  readonly driver: SqlDriver<unknown>;
+  readonly verify: RuntimeVerifyOptions;
+  readonly plugins?: readonly Plugin<
+    TContract,
+    Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+    SqlDriver<unknown>
+  >[];
+  readonly mode?: 'strict' | 'permissive';
+  readonly log?: Log;
+}
+
+export interface Runtime extends RuntimeQueryable {
+  connection(): Promise<RuntimeConnection>;
+  telemetry(): RuntimeTelemetryEvent | null;
+  close(): Promise<void>;
+  operations(): OperationRegistry;
+}
+
+export interface RuntimeConnection extends RuntimeQueryable {
+  transaction(): Promise<RuntimeTransaction>;
+  release(): Promise<void>;
+}
+
+export interface RuntimeTransaction extends RuntimeQueryable {
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+
+export interface RuntimeQueryable {
+  execute<Row = Record<string, unknown>>(
+    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+  ): AsyncIterableResult<Row>;
+}
+
+export type { RuntimeTelemetryEvent, RuntimeVerifyOptions, TelemetryOutcome };
+
+class SqlRuntimeImpl<TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>>
+  implements Runtime
+{
+  private readonly core: RuntimeCore<
+    TContract,
+    Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+    SqlDriver<unknown>
+  >;
+  private readonly contract: TContract;
+  private readonly adapter: Adapter<QueryAst, SqlContract<SqlStorage>, LoweredStatement>;
+  private readonly codecRegistry: CodecRegistry;
+  private readonly jsonSchemaValidators: JsonSchemaValidatorRegistry | undefined;
+  private codecRegistryValidated: boolean;
+
+  constructor(options: RuntimeOptions<TContract>) {
+    const { context, adapter, driver, verify, plugins, mode, log } = options;
+    this.contract = context.contract;
+    this.adapter = adapter;
+    this.codecRegistry = context.codecs;
+    this.jsonSchemaValidators = context.jsonSchemaValidators;
+    this.codecRegistryValidated = false;
+
+    const familyAdapter = new SqlFamilyAdapter(context.contract);
+
+    const coreOptions: RuntimeCoreOptions<
+      TContract,
+      Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+      SqlDriver<unknown>
+    > = {
+      familyAdapter,
+      driver,
+      verify,
+      plugins: plugins as readonly Plugin<
+        TContract,
+        Adapter<SelectAst, SqlContract<SqlStorage>, LoweredStatement>,
+        SqlDriver<unknown>
+      >[],
+      ...ifDefined('mode', mode),
+      ...ifDefined('log', log),
+      operationRegistry: context.operations,
+    };
+
+    this.core = createRuntimeCore(coreOptions);
+
+    if (verify.mode === 'startup') {
+      validateCodecRegistryCompleteness(this.codecRegistry, context.contract);
+      this.codecRegistryValidated = true;
+    }
+  }
+
+  private ensureCodecRegistryValidated(contract: SqlContract<SqlStorage>): void {
+    if (!this.codecRegistryValidated) {
+      validateCodecRegistryCompleteness(this.codecRegistry, contract);
+      this.codecRegistryValidated = true;
+    }
+  }
+
+  execute<Row = Record<string, unknown>>(
+    plan: ExecutionPlan<Row> | SqlQueryPlan<Row>,
+  ): AsyncIterableResult<Row> {
+    this.ensureCodecRegistryValidated(this.contract);
+
+    const isSqlQueryPlan = (p: ExecutionPlan<Row> | SqlQueryPlan<Row>): p is SqlQueryPlan<Row> => {
+      return 'ast' in p && !('sql' in p);
+    };
+
+    const executablePlan: ExecutionPlan<Row> = isSqlQueryPlan(plan)
+      ? lowerSqlPlan(this.adapter, this.contract, plan)
+      : plan;
+
+    const iterator = async function* (
+      self: SqlRuntimeImpl<TContract>,
+    ): AsyncGenerator<Row, void, unknown> {
+      const encodedParams = encodeParams(
+        executablePlan,
+        self.codecRegistry,
+        self.jsonSchemaValidators,
+      );
+      const planWithEncodedParams: ExecutionPlan<Row> = {
+        ...executablePlan,
+        params: encodedParams,
+      };
+
+      const coreIterator = self.core.execute(planWithEncodedParams);
+
+      for await (const rawRow of coreIterator) {
+        const decodedRow = decodeRow(
+          rawRow as Record<string, unknown>,
+          executablePlan,
+          self.codecRegistry,
+          self.jsonSchemaValidators,
+        );
+        yield decodedRow as Row;
+      }
+    };
+
+    return new AsyncIterableResult(iterator(this));
+  }
+
+  connection(): Promise<RuntimeConnection> {
+    return this.core.connection();
+  }
+
+  telemetry(): RuntimeTelemetryEvent | null {
+    return this.core.telemetry();
+  }
+
+  operations(): OperationRegistry {
+    return this.core.operations();
+  }
+
+  close(): Promise<void> {
+    return this.core.close();
+  }
+}
+
+export function createRuntime<TContract extends SqlContract<SqlStorage>, TTargetId extends string>(
+  options: CreateRuntimeOptions<TContract, TTargetId>,
+): Runtime {
+  const { stackInstance, context, driver, verify, plugins, mode, log } = options;
+
+  return new SqlRuntimeImpl({
+    context,
+    adapter: stackInstance.adapter,
+    driver,
+    verify,
+    ...ifDefined('plugins', plugins),
+    ...ifDefined('mode', mode),
+    ...ifDefined('log', log),
+  });
+}

package/test/async-iterable-result.test.ts

@@ -0,0 +1,144 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import { instantiateExecutionStack } from '@prisma-next/core-execution-plane/stack';
+import type { AsyncIterableResult } from '@prisma-next/runtime-executor';
+import { describe, expect, it } from 'vitest';
+import type { Runtime } from '../src/exports';
+import { createRuntime, createSqlExecutionStack } from '../src/exports';
+import {
+  createStubAdapter,
+  createTestAdapterDescriptor,
+  createTestContext,
+  createTestContract,
+  createTestTargetDescriptor,
+} from './utils';
+
+class MockDriver {
+  private rows: ReadonlyArray<Record<string, unknown>> = [];
+
+  setRows(rows: ReadonlyArray<Record<string, unknown>>): void {
+    this.rows = rows;
+  }
+
+  async query<Row = Record<string, unknown>>(
+    _sql: string,
+    _params?: readonly unknown[],
+  ): Promise<{ rows: ReadonlyArray<Row> }> {
+    return { rows: [] };
+  }
+
+  async *execute<Row = Record<string, unknown>>(_options: {
+    sql: string;
+    params: readonly unknown[];
+  }): AsyncIterable<Row> {
+    for (const row of this.rows) {
+      yield row as Row;
+    }
+  }
+
+  async acquireConnection(): Promise<never> {
+    throw new Error('Not implemented in mock');
+  }
+
+  async connect(): Promise<void> {}
+
+  async close(): Promise<void> {}
+}
+
+const fixtureContract = createTestContract({
+  schemaVersion: '1',
+  targetFamily: 'sql',
+  target: 'postgres',
+  storageHash: 'test-hash',
+  profileHash: 'test-profile-hash',
+  storage: {
+    tables: {
+      user: {
+        columns: {
+          id: { nativeType: 'int4', codecId: 'pg/int4@1', nullable: false },
+          email: { nativeType: 'text', codecId: 'pg/text@1', nullable: false },
+        },
+        uniques: [],
+        indexes: [],
+        foreignKeys: [],
+      },
+    },
+  },
+  models: {},
+  relations: {},
+  mappings: { codecTypes: {}, operationTypes: {} },
+});
+
+function createTestRuntime(mockDriver: MockDriver): Runtime {
+  const adapter = createStubAdapter();
+  const stack = createSqlExecutionStack({
+    target: createTestTargetDescriptor(),
+    adapter: createTestAdapterDescriptor(adapter),
+    extensionPacks: [],
+  });
+  const stackInstance = instantiateExecutionStack(stack);
+  const context = createTestContext(fixtureContract, adapter);
+  return createRuntime({
+    stackInstance,
+    context,
+    driver: mockDriver,
+    verify: { mode: 'onFirstUse', requireMarker: false },
+  });
+}
+
+describe('SqlRuntime AsyncIterableResult integration', () => {
+  it('returns AsyncIterableResult from execute', async () => {
+    const driver = new MockDriver();
+    driver.setRows([
+      { id: 1, email: 'test1@example.com' },
+      { id: 2, email: 'test2@example.com' },
+    ]);
+    const runtime = createTestRuntime(driver);
+
+    const plan: ExecutionPlan<{ id: number; email: string }> = {
+      sql: 'SELECT id, email FROM "user" ORDER BY id',
+      params: [],
+      meta: {
+        target: 'postgres',
+        targetFamily: 'sql',
+        storageHash: 'test-hash',
+        lane: 'sql',
+        paramDescriptors: [],
+      },
+    };
+
+    const result = runtime.execute(plan);
+
+    expect(result).toBeInstanceOf(Object);
+    expect(typeof result.toArray).toBe('function');
+    expect(typeof result[Symbol.asyncIterator]).toBe('function');
+
+    await runtime.close();
+  });
+
+  it('preserves type information', async () => {
+    const driver = new MockDriver();
+    driver.setRows([{ id: 1, email: 'test@example.com' }]);
+    const runtime = createTestRuntime(driver);
+
+    const plan: ExecutionPlan<{ id: number; email: string }> = {
+      sql: 'SELECT id, email FROM "user" LIMIT 1',
+      params: [],
+      meta: {
+        target: 'postgres',
+        targetFamily: 'sql',
+        storageHash: 'test-hash',
+        lane: 'sql',
+        paramDescriptors: [],
+      },
+    };
+
+    const result: AsyncIterableResult<{ id: number; email: string }> = runtime.execute(plan);
+    const rows = await result.toArray();
+
+    expect(rows.length).toBe(1);
+    expect(typeof rows[0]!.id).toBe('number');
+    expect(typeof rows[0]!.email).toBe('string');
+
+    await runtime.close();
+  });
+});

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

@@ -0,0 +1,68 @@
+import type { SqlContract, SqlMappings, SqlStorage } from '@prisma-next/sql-contract/types';
+import { expectTypeOf, test } from 'vitest';
+import type { ExecutionContext, 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('ExecutionContext.types is TypeHelperRegistry', () => {
+  // ExecutionContext.types is intentionally loose (Record<string, unknown>)
+  // The strong typing comes from schema(context).types via ExtractSchemaTypes
+  expectTypeOf<ExecutionContext<TestContract>['types']>().toEqualTypeOf<TypeHelperRegistry>();
+
+  // TypeHelperRegistry allows any values - the actual type depends on init hooks
+  expectTypeOf<TypeHelperRegistry>().toEqualTypeOf<Record<string, unknown>>();
+});
+
+test('ExecutionContext preserves contract type parameter', () => {
+  // Verify the contract type is preserved in ExecutionContext
+  expectTypeOf<ExecutionContext<TestContract>['contract']>().toEqualTypeOf<TestContract>();
+
+  // Verify we can access storage.types through the context's contract
+  type ContractStorageTypes = ExecutionContext<TestContract>['contract']['storage']['types'];
+  expectTypeOf<ContractStorageTypes>().toExtend<
+    | {
+        readonly Vector1536: {
+          readonly codecId: 'pg/vector@1';
+          readonly nativeType: 'vector';
+          readonly typeParams: { readonly length: 1536 };
+        };
+      }
+    | undefined
+  >();
+});
+
+test('ExecutionContext accepts generic SqlContract', () => {
+  // Verify ExecutionContext defaults work
+  type DefaultContext = ExecutionContext;
+  expectTypeOf<DefaultContext['contract']>().toExtend<SqlContract<SqlStorage>>();
+  expectTypeOf<DefaultContext['types']>().toEqualTypeOf<TypeHelperRegistry>();
+});

package/test/execution-stack.test.ts

@@ -0,0 +1,166 @@
+import { createExecutionStack } from '@prisma-next/core-execution-plane/stack';
+import { codec, createCodecRegistry } from '@prisma-next/sql-relational-core/ast';
+import { describe, expect, it } from 'vitest';
+import { createExecutionContext, createSqlExecutionStack } from '../src/exports';
+import type {
+  ExecutionContext,
+  SqlRuntimeAdapterDescriptor,
+  SqlRuntimeExtensionDescriptor,
+  SqlRuntimeTargetDescriptor,
+} from '../src/sql-context';
+import { createTestContract } from './utils';
+
+function createStubAdapterDescriptor(): SqlRuntimeAdapterDescriptor<'postgres'> {
+  const registry = createCodecRegistry();
+  registry.register(
+    codec({
+      typeId: 'pg/text@1',
+      targetTypes: ['text'],
+      encode: (value: string) => value,
+      decode: (wire: string) => wire,
+    }),
+  );
+
+  return {
+    kind: 'adapter',
+    id: 'test-adapter',
+    version: '0.0.1',
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    codecs: () => registry,
+    operationSignatures: () => [],
+    parameterizedCodecs: () => [],
+    create() {
+      return Object.assign(
+        { familyId: 'sql' as const, targetId: 'postgres' as const },
+        {
+          profile: {
+            id: 'test-profile',
+            target: 'postgres',
+            capabilities: {},
+            codecs: () => registry,
+          },
+          lower() {
+            return {
+              profileId: 'test-profile',
+              body: Object.freeze({ sql: '', params: [] }),
+            };
+          },
+        },
+      );
+    },
+  };
+}
+
+function createStubTargetDescriptor(): SqlRuntimeTargetDescriptor<'postgres'> {
+  return {
+    kind: 'target',
+    id: 'postgres',
+    version: '0.0.1',
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    codecs: () => createCodecRegistry(),
+    operationSignatures: () => [],
+    parameterizedCodecs: () => [],
+    create() {
+      return { familyId: 'sql' as const, targetId: 'postgres' as const };
+    },
+  };
+}
+
+function createStubExtensionDescriptor(): SqlRuntimeExtensionDescriptor<'postgres'> {
+  const registry = createCodecRegistry();
+  registry.register(
+    codec({
+      typeId: 'pg/uuid@1',
+      targetTypes: ['uuid'],
+      encode: (value: string) => value,
+      decode: (wire: string) => wire,
+    }),
+  );
+
+  const operations = [
+    {
+      forTypeId: 'pg/text@1',
+      method: 'example',
+      args: [],
+      returns: { kind: 'builtin' as const, type: 'string' as const },
+      lowering: {
+        targetFamily: 'sql' as const,
+        strategy: 'function' as const,
+        template: 'example({args})',
+      },
+    },
+  ];
+
+  return {
+    kind: 'extension',
+    id: 'test-extension',
+    version: '0.0.1',
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+    codecs: () => registry,
+    operationSignatures: () => operations,
+    parameterizedCodecs: () => [],
+    create() {
+      return {
+        familyId: 'sql' as const,
+        targetId: 'postgres' as const,
+      };
+    },
+  };
+}
+
+describe('createExecutionStack', () => {
+  it('defaults driver to undefined and extensions to empty', () => {
+    const stack = createExecutionStack({
+      target: createStubTargetDescriptor(),
+      adapter: createStubAdapterDescriptor(),
+    });
+
+    expect(stack.driver).toBeUndefined();
+    expect(stack.extensionPacks).toEqual([]);
+  });
+
+  it('creates an execution context from descriptors-only stack', () => {
+    const contract = createTestContract({
+      storage: { tables: {} },
+    });
+
+    const context = createExecutionContext({
+      contract,
+      stack: {
+        target: createStubTargetDescriptor(),
+        adapter: createStubAdapterDescriptor(),
+        extensionPacks: [createStubExtensionDescriptor()],
+      },
+    }) as ExecutionContext<typeof contract>;
+
+    expect(context.contract).toBe(contract);
+    expect(context.codecs.get('pg/text@1')).toBeDefined();
+    expect(context.codecs.get('pg/uuid@1')).toBeDefined();
+    expect(context.operations.byType('pg/text@1')).toHaveLength(1);
+    expect(context.types).toEqual({});
+  });
+});
+
+describe('createSqlExecutionStack', () => {
+  it('preserves descriptor references and defaults extensions', () => {
+    const target = createStubTargetDescriptor();
+    const adapter = createStubAdapterDescriptor();
+    const stack = createSqlExecutionStack({ target, adapter });
+
+    expect(stack.target).toBe(target);
+    expect(stack.adapter).toBe(adapter);
+    expect(stack.extensionPacks).toEqual([]);
+  });
+
+  it('keeps extension packs intact', () => {
+    const target = createStubTargetDescriptor();
+    const adapter = createStubAdapterDescriptor();
+    const extension = createStubExtensionDescriptor();
+    const stack = createSqlExecutionStack({ target, adapter, extensionPacks: [extension] });
+
+    expect(stack.extensionPacks).toEqual([extension]);
+  });
+});