@prisma-next/sql-relational-core 0.3.0-dev.4 → 0.3.0-dev.41

package/src/ast/codec-types.ts

@@ -0,0 +1,444 @@
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { Type } from 'arktype';
+import type { O } from 'ts-toolbelt';
+
+/**
+ * Descriptor for parameterized codecs that require type parameter validation.
+ * Shared between adapter (compile-time) and runtime layers to avoid duplication.
+ *
+ * @template TParams - The shape of the type parameters (e.g., `{ length: number }`)
+ * @template THelper - The type returned by the optional `init` hook
+ */
+export interface CodecParamsDescriptor<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.
+   * 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;
+}
+
+/**
+ * Codec metadata for database-specific type information.
+ * Used for schema introspection and verification.
+ */
+export interface CodecMeta {
+  readonly db?: {
+    readonly sql?: {
+      readonly postgres?: {
+        readonly nativeType: string; // e.g. 'integer', 'text', 'vector', 'timestamp with time zone'
+      };
+    };
+  };
+}
+
+/**
+ * Codec interface for encoding/decoding values between wire format and JavaScript types.
+ *
+ * Codecs are pure, synchronous functions with no side effects or IO.
+ * They provide deterministic conversion between database wire types and JS values.
+ */
+export interface Codec<
+  Id extends string = string,
+  TWire = unknown,
+  TJs = unknown,
+  TParams = Record<string, unknown>,
+  THelper = unknown,
+> {
+  /**
+   * Namespaced codec identifier in format 'namespace/name@version'
+   * Examples: 'pg/text@1', 'pg/uuid@1', 'pg/timestamptz@1'
+   */
+  readonly id: Id;
+
+  /**
+   * Contract scalar type IDs that this codec can handle.
+   * Examples: ['text'], ['int4', 'float8'], ['timestamp', 'timestamptz']
+   */
+  readonly targetTypes: readonly string[];
+
+  /**
+   * Optional metadata for database-specific type information.
+   * Used for schema introspection and verification.
+   */
+  readonly meta?: CodecMeta;
+
+  /**
+   * Optional params schema for parameterized codecs.
+   * If provided, typeParams are validated against this schema.
+   */
+  readonly paramsSchema?: Type<TParams>;
+
+  /**
+   * Optional init hook for building runtime helper state from validated params.
+   *
+   * Useful when parameterized types need derived data at runtime, for example:
+   * - normalize typeParams into a stable helper shape consumed by lanes/adapters
+   * - precompute reusable values once during context creation
+   * - avoid repeating typeParams parsing logic during query execution
+   *
+   * Example:
+   *   { length: 255 } -> { kind: 'variable', maxLength: 255 }
+   *
+   * **Convention for JSON/JSONB codecs**: When the helper includes a `validate`
+   * property of type `JsonSchemaValidateFn`, the runtime will use it to enforce
+   * JSON Schema conformance during encoding and decoding. The property is
+   * discovered via duck typing (`helper?.validate`) for flexibility across
+   * different codec types.
+   */
+  readonly init?: (params: TParams) => THelper;
+
+  /**
+   * Decode a wire value (from database) to JavaScript type.
+   * Must be synchronous and pure (no side effects).
+   */
+  decode(wire: TWire): TJs;
+
+  /**
+   * Encode a JavaScript value to wire format (for database).
+   * Optional - if not provided, values pass through unchanged.
+   * Must be synchronous and pure (no side effects).
+   */
+  encode?(value: TJs): TWire;
+}
+
+/**
+ * Registry interface for codecs organized by ID and by contract scalar type.
+ *
+ * The registry allows looking up codecs by their namespaced ID or by the
+ * contract scalar types they handle. Multiple codecs may handle the same
+ * scalar type; ordering in byScalar reflects preference (adapter first,
+ * then packs, then app overrides).
+ */
+export interface CodecRegistry {
+  get(id: string): Codec<string> | undefined;
+  has(id: string): boolean;
+  getByScalar(scalar: string): readonly Codec<string>[];
+  getDefaultCodec(scalar: string): Codec<string> | undefined;
+  register(codec: Codec<string>): void;
+  [Symbol.iterator](): Iterator<Codec<string>>;
+  values(): IterableIterator<Codec<string>>;
+}
+
+/**
+ * Implementation of CodecRegistry.
+ */
+class CodecRegistryImpl implements CodecRegistry {
+  private readonly _byId = new Map<string, Codec<string>>();
+  private readonly _byScalar = new Map<string, Codec<string>[]>();
+
+  /**
+   * Map-like interface for codec lookup by ID.
+   * Example: registry.get('pg/text@1')
+   */
+  get(id: string): Codec<string> | undefined {
+    return this._byId.get(id);
+  }
+
+  /**
+   * Check if a codec with the given ID is registered.
+   */
+  has(id: string): boolean {
+    return this._byId.has(id);
+  }
+
+  /**
+   * Get all codecs that handle a given scalar type.
+   * Returns an empty frozen array if no codecs are found.
+   * Example: registry.getByScalar('text') → [codec1, codec2, ...]
+   */
+  getByScalar(scalar: string): readonly Codec<string>[] {
+    return this._byScalar.get(scalar) ?? Object.freeze([]);
+  }
+
+  /**
+   * Get the default codec for a scalar type (first registered codec).
+   * Returns undefined if no codec handles this scalar type.
+   */
+  getDefaultCodec(scalar: string): Codec<string> | undefined {
+    const _codecs = this._byScalar.get(scalar);
+    return _codecs?.[0];
+  }
+
+  /**
+   * Register a codec in the registry.
+   * Throws an error if a codec with the same ID is already registered.
+   *
+   * @param codec - The codec to register
+   * @throws Error if a codec with the same ID already exists
+   */
+  register(codec: Codec<string>): void {
+    if (this._byId.has(codec.id)) {
+      throw new Error(`Codec with ID '${codec.id}' is already registered`);
+    }
+
+    this._byId.set(codec.id, codec);
+
+    // Update byScalar mapping
+    for (const scalarType of codec.targetTypes) {
+      const existing = this._byScalar.get(scalarType);
+      if (existing) {
+        existing.push(codec);
+      } else {
+        this._byScalar.set(scalarType, [codec]);
+      }
+    }
+  }
+
+  /**
+   * Returns an iterator over all registered codecs.
+   * Useful for iterating through codecs from another registry.
+   */
+  *[Symbol.iterator](): Iterator<Codec<string>> {
+    for (const codec of this._byId.values()) {
+      yield codec;
+    }
+  }
+
+  /**
+   * Returns an iterable of all registered codecs.
+   */
+  values(): IterableIterator<Codec<string>> {
+    return this._byId.values();
+  }
+}
+
+/**
+ * Codec factory - creates a codec with typeId and encode/decode functions.
+ */
+export function codec<
+  Id extends string,
+  TWire,
+  TJs,
+  TParams = Record<string, unknown>,
+  THelper = unknown,
+>(config: {
+  typeId: Id;
+  targetTypes: readonly string[];
+  encode: (value: TJs) => TWire;
+  decode: (wire: TWire) => TJs;
+  meta?: CodecMeta;
+  paramsSchema?: Type<TParams>;
+  init?: (params: TParams) => THelper;
+}): Codec<Id, TWire, TJs, TParams, THelper> {
+  return {
+    id: config.typeId,
+    targetTypes: config.targetTypes,
+    ...ifDefined('meta', config.meta),
+    ...ifDefined('paramsSchema', config.paramsSchema),
+    ...ifDefined('init', config.init),
+    encode: config.encode,
+    decode: config.decode,
+  };
+}
+
+/**
+ * Type helpers to extract codec types.
+ */
+export type CodecId<T> =
+  T extends Codec<infer Id, unknown, unknown>
+    ? Id
+    : T extends { readonly id: infer Id }
+      ? Id
+      : never;
+export type CodecInput<T> = T extends Codec<string, unknown, infer JsT> ? JsT : never;
+export type CodecOutput<T> = T extends Codec<string, unknown, infer JsT> ? JsT : never;
+
+/**
+ * Type helper to extract codec types from builder instance.
+ */
+export type ExtractCodecTypes<
+  ScalarNames extends { readonly [K in keyof ScalarNames]: Codec<string> } = Record<never, never>,
+> = {
+  readonly [K in keyof ScalarNames as ScalarNames[K] extends Codec<infer Id, unknown, unknown>
+    ? Id
+    : never]: {
+    readonly input: CodecInput<ScalarNames[K]>;
+    readonly output: CodecOutput<ScalarNames[K]>;
+  };
+};
+
+/**
+ * Type helper to extract data type IDs from builder instance.
+ * Uses ExtractCodecTypes which preserves literal types as keys.
+ * Since ExtractCodecTypes<Record<K, ScalarNames[K]>> has exactly one key (the Id),
+ * we extract it by creating a mapped type that uses the Id as both key and value,
+ * then extract the value type. This preserves literal types.
+ */
+export type ExtractDataTypes<
+  ScalarNames extends { readonly [K in keyof ScalarNames]: Codec<string> },
+> = {
+  readonly [K in keyof ScalarNames]: {
+    readonly [Id in keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>]: Id;
+  }[keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>];
+};
+
+/**
+ * Builder interface for declaring codecs.
+ */
+export interface CodecDefBuilder<
+  ScalarNames extends { readonly [K in keyof ScalarNames]: Codec<string> } = Record<never, never>,
+> {
+  readonly CodecTypes: ExtractCodecTypes<ScalarNames>;
+
+  add<ScalarName extends string, CodecImpl extends Codec<string>>(
+    scalarName: ScalarName,
+    codecImpl: CodecImpl,
+  ): CodecDefBuilder<
+    O.Overwrite<ScalarNames, Record<ScalarName, CodecImpl>> & Record<ScalarName, CodecImpl>
+  >;
+
+  readonly codecDefinitions: {
+    readonly [K in keyof ScalarNames]: {
+      readonly typeId: ScalarNames[K] extends Codec<infer Id extends string, unknown, unknown>
+        ? Id
+        : never;
+      readonly scalar: K;
+      readonly codec: ScalarNames[K];
+      readonly input: CodecInput<ScalarNames[K]>;
+      readonly output: CodecOutput<ScalarNames[K]>;
+      readonly jsType: CodecOutput<ScalarNames[K]>;
+    };
+  };
+
+  readonly dataTypes: {
+    readonly [K in keyof ScalarNames]: {
+      readonly [Id in keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>]: Id;
+    }[keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>];
+  };
+}
+
+/**
+ * Implementation of CodecDefBuilder.
+ */
+class CodecDefBuilderImpl<
+  ScalarNames extends { readonly [K in keyof ScalarNames]: Codec<string> } = Record<never, never>,
+> implements CodecDefBuilder<ScalarNames>
+{
+  private readonly _codecs: ScalarNames;
+
+  public readonly CodecTypes: ExtractCodecTypes<ScalarNames>;
+  public readonly dataTypes: {
+    readonly [K in keyof ScalarNames]: {
+      readonly [Id in keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>]: Id;
+    }[keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>];
+  };
+
+  constructor(codecs: ScalarNames) {
+    this._codecs = codecs;
+
+    // Populate CodecTypes from codecs
+    const codecTypes: Record<string, { readonly input: unknown; readonly output: unknown }> = {};
+    for (const [, codecImpl] of Object.entries(this._codecs)) {
+      const codecImplTyped = codecImpl as Codec<string>;
+      codecTypes[codecImplTyped.id] = {
+        input: undefined as unknown as CodecInput<typeof codecImplTyped>,
+        output: undefined as unknown as CodecOutput<typeof codecImplTyped>,
+      };
+    }
+    this.CodecTypes = codecTypes as ExtractCodecTypes<ScalarNames>;
+
+    // Populate dataTypes from codecs - extract id property from each codec
+    // Build object preserving keys from ScalarNames
+    // Type assertion is safe because we know ScalarNames structure matches the return type
+    // biome-ignore lint/suspicious/noExplicitAny: dynamic codec mapping requires any
+    const dataTypes = {} as any;
+    for (const key in this._codecs) {
+      if (Object.hasOwn(this._codecs, key)) {
+        const codec = this._codecs[key] as Codec<string>;
+        dataTypes[key] = codec.id;
+      }
+    }
+    this.dataTypes = dataTypes as {
+      readonly [K in keyof ScalarNames]: {
+        readonly [Id in keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>]: Id;
+      }[keyof ExtractCodecTypes<Record<K, ScalarNames[K]>>];
+    };
+  }
+
+  add<ScalarName extends string, CodecImpl extends Codec<string>>(
+    scalarName: ScalarName,
+    codecImpl: CodecImpl,
+  ): CodecDefBuilder<
+    O.Overwrite<ScalarNames, Record<ScalarName, CodecImpl>> & Record<ScalarName, CodecImpl>
+  > {
+    return new CodecDefBuilderImpl({
+      ...this._codecs,
+      [scalarName]: codecImpl,
+    } as O.Overwrite<ScalarNames, Record<ScalarName, CodecImpl>> & Record<ScalarName, CodecImpl>);
+  }
+
+  /**
+   * Derive codecDefinitions structure.
+   */
+  get codecDefinitions(): {
+    readonly [K in keyof ScalarNames]: {
+      readonly typeId: ScalarNames[K] extends Codec<infer Id, unknown, unknown> ? Id : never;
+      readonly scalar: K;
+      readonly codec: ScalarNames[K];
+      readonly input: CodecInput<ScalarNames[K]>;
+      readonly output: CodecOutput<ScalarNames[K]>;
+      readonly jsType: CodecOutput<ScalarNames[K]>;
+    };
+  } {
+    const result: Record<
+      string,
+      {
+        typeId: string;
+        scalar: string;
+        codec: Codec;
+        input: unknown;
+        output: unknown;
+        jsType: unknown;
+      }
+    > = {};
+
+    for (const [scalarName, codecImpl] of Object.entries(this._codecs)) {
+      const codec = codecImpl as Codec<string>;
+      result[scalarName] = {
+        typeId: codec.id,
+        scalar: scalarName,
+        codec: codec,
+        input: undefined as unknown as CodecInput<typeof codec>,
+        output: undefined as unknown as CodecOutput<typeof codec>,
+        jsType: undefined as unknown as CodecOutput<typeof codec>,
+      };
+    }
+
+    return result as {
+      readonly [K in keyof ScalarNames]: {
+        readonly typeId: ScalarNames[K] extends Codec<infer Id extends string, unknown, unknown>
+          ? Id
+          : never;
+        readonly scalar: K;
+        readonly codec: ScalarNames[K];
+        readonly input: CodecInput<ScalarNames[K]>;
+        readonly output: CodecOutput<ScalarNames[K]>;
+        readonly jsType: CodecOutput<ScalarNames[K]>;
+      };
+    };
+  }
+}
+
+/**
+ * Create a new codec registry.
+ */
+export function createCodecRegistry(): CodecRegistry {
+  return new CodecRegistryImpl();
+}
+
+/**
+ * Create a new codec definition builder.
+ */
+export function defineCodecs(): CodecDefBuilder<Record<never, never>> {
+  return new CodecDefBuilderImpl({});
+}

package/src/ast/common.ts

@@ -0,0 +1,36 @@
+import type { ColumnRef, LiteralExpr, OperationExpr, ParamRef, TableRef } from './types';
+import { compact } from './util';
+
+export function createTableRef(name: string): TableRef {
+  return {
+    kind: 'table',
+    name,
+  };
+}
+
+export function createColumnRef(table: string, column: string): ColumnRef {
+  return {
+    kind: 'col',
+    table,
+    column,
+  };
+}
+
+export function createParamRef(index: number, name?: string): ParamRef {
+  return compact({
+    kind: 'param',
+    index,
+    name,
+  }) as ParamRef;
+}
+
+export function createOperationExpr(operation: OperationExpr): OperationExpr {
+  return operation;
+}
+
+export function createLiteralExpr(value: unknown): LiteralExpr {
+  return {
+    kind: 'literal',
+    value,
+  };
+}

package/src/ast/delete.ts

@@ -0,0 +1,17 @@
+import type { ColumnRef, DeleteAst, TableRef, WhereExpr } from './types';
+import { compact } from './util';
+
+export interface CreateDeleteAstOptions {
+  readonly table: TableRef;
+  readonly where: WhereExpr;
+  readonly returning?: ReadonlyArray<ColumnRef>;
+}
+
+export function createDeleteAst(options: CreateDeleteAstOptions): DeleteAst {
+  return compact({
+    kind: 'delete',
+    table: options.table,
+    where: options.where,
+    returning: options.returning,
+  }) as DeleteAst;
+}

package/src/ast/driver-types.ts

@@ -0,0 +1,42 @@
+export interface SqlExecuteRequest {
+  readonly sql: string;
+  readonly params?: readonly unknown[];
+}
+
+export interface SqlQueryResult<Row = Record<string, unknown>> {
+  readonly rows: ReadonlyArray<Row>;
+  readonly rowCount?: number | null;
+  readonly [key: string]: unknown;
+}
+
+export interface SqlExplainResult<Row = Record<string, unknown>> {
+  readonly rows: ReadonlyArray<Row>;
+}
+
+export type SqlDriverState = 'unbound' | 'connected' | 'closed';
+
+export interface SqlDriver<TBinding = void> extends SqlQueryable {
+  readonly state?: SqlDriverState;
+  connect(binding: TBinding): Promise<void>;
+  acquireConnection(): Promise<SqlConnection>;
+  close(): Promise<void>;
+}
+
+export interface SqlConnection extends SqlQueryable {
+  beginTransaction(): Promise<SqlTransaction>;
+  release(): Promise<void>;
+}
+
+export interface SqlTransaction extends SqlQueryable {
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+
+export interface SqlQueryable {
+  execute<Row = Record<string, unknown>>(request: SqlExecuteRequest): AsyncIterable<Row>;
+  explain?(request: SqlExecuteRequest): Promise<SqlExplainResult>;
+  query<Row = Record<string, unknown>>(
+    sql: string,
+    params?: readonly unknown[],
+  ): Promise<SqlQueryResult<Row>>;
+}

package/src/ast/insert.ts

@@ -0,0 +1,17 @@
+import type { ColumnRef, InsertAst, ParamRef, TableRef } from './types';
+import { compact } from './util';
+
+export interface CreateInsertAstOptions {
+  readonly table: TableRef;
+  readonly values: Record<string, ColumnRef | ParamRef>;
+  readonly returning?: ReadonlyArray<ColumnRef>;
+}
+
+export function createInsertAst(options: CreateInsertAstOptions): InsertAst {
+  return compact({
+    kind: 'insert',
+    table: options.table,
+    values: options.values,
+    returning: options.returning,
+  }) as InsertAst;
+}

package/src/ast/join.ts

@@ -0,0 +1,54 @@
+import { planInvalid } from '@prisma-next/plan';
+import type { AnyColumnBuilder, JoinOnBuilder, JoinOnPredicate } from '../types';
+import { isColumnBuilder } from '../types';
+import type { ColumnRef, JoinAst, JoinOnExpr, TableRef } from './types';
+
+export function createJoin(
+  joinType: 'inner' | 'left' | 'right' | 'full',
+  table: TableRef,
+  on: JoinOnExpr,
+): JoinAst {
+  return {
+    kind: 'join',
+    joinType,
+    table,
+    on,
+  };
+}
+
+export function createJoinOnExpr(left: ColumnRef, right: ColumnRef): JoinOnExpr {
+  return {
+    kind: 'eqCol',
+    left,
+    right,
+  };
+}
+
+class JoinOnBuilderImpl implements JoinOnBuilder {
+  eqCol(left: AnyColumnBuilder, right: AnyColumnBuilder): JoinOnPredicate {
+    if (!left || !isColumnBuilder(left)) {
+      throw planInvalid('Join ON left operand must be a column');
+    }
+
+    if (!right || !isColumnBuilder(right)) {
+      throw planInvalid('Join ON right operand must be a column');
+    }
+
+    // TypeScript can't narrow ColumnBuilder properly, so we assert
+    const leftCol = left as unknown as { table: string; column: string };
+    const rightCol = right as unknown as { table: string; column: string };
+    if (leftCol.table === rightCol.table) {
+      throw planInvalid('Self-joins are not supported in MVP');
+    }
+
+    return {
+      kind: 'join-on',
+      left: left as AnyColumnBuilder,
+      right: right as AnyColumnBuilder,
+    };
+  }
+}
+
+export function createJoinOnBuilder(): JoinOnBuilder {
+  return new JoinOnBuilderImpl();
+}

package/src/ast/order.ts

@@ -0,0 +1,11 @@
+import type { ColumnRef, Direction, OperationExpr } from './types';
+
+export function createOrderByItem(
+  expr: ColumnRef | OperationExpr,
+  dir: 'asc' | 'desc',
+): { expr: ColumnRef | OperationExpr; dir: Direction } {
+  return {
+    expr,
+    dir,
+  };
+}

package/src/ast/predicate.ts

@@ -0,0 +1,40 @@
+import type {
+  BinaryExpr,
+  BinaryOp,
+  ExistsExpr,
+  Expression,
+  ListLiteralExpr,
+  LiteralExpr,
+  NullCheckExpr,
+  ParamRef,
+  SelectAst,
+} from './types';
+
+export function createBinaryExpr(
+  op: BinaryOp,
+  left: Expression,
+  right: Expression | ParamRef | LiteralExpr | ListLiteralExpr,
+): BinaryExpr {
+  return {
+    kind: 'bin',
+    op,
+    left,
+    right,
+  };
+}
+
+export function createExistsExpr(not: boolean, subquery: SelectAst): ExistsExpr {
+  return {
+    kind: 'exists',
+    not,
+    subquery,
+  };
+}
+
+export function createNullCheckExpr(expr: Expression, isNull: boolean): NullCheckExpr {
+  return {
+    kind: 'nullCheck',
+    expr,
+    isNull,
+  };
+}

package/src/ast/select.ts

@@ -0,0 +1,38 @@
+import type {
+  ColumnRef,
+  Direction,
+  IncludeAst,
+  IncludeRef,
+  JoinAst,
+  OperationExpr,
+  SelectAst,
+  TableRef,
+  WhereExpr,
+} from './types';
+import { compact } from './util';
+
+export interface CreateSelectAstOptions {
+  readonly from: TableRef;
+  readonly joins?: ReadonlyArray<JoinAst>;
+  readonly includes?: ReadonlyArray<IncludeAst>;
+  readonly project: ReadonlyArray<{
+    alias: string;
+    expr: ColumnRef | IncludeRef | OperationExpr;
+  }>;
+  readonly where?: WhereExpr;
+  readonly orderBy?: ReadonlyArray<{ expr: ColumnRef | OperationExpr; dir: Direction }>;
+  readonly limit?: number;
+}
+
+export function createSelectAst(options: CreateSelectAstOptions): SelectAst {
+  return compact({
+    kind: 'select',
+    from: options.from,
+    joins: options.joins,
+    includes: options.includes,
+    project: options.project,
+    where: options.where,
+    orderBy: options.orderBy,
+    limit: options.limit,
+  }) as SelectAst;
+}