@prisma-next/sql-relational-core 0.3.0-dev.2 → 0.3.0-dev.21

package/src/ast/types.ts

@@ -0,0 +1,133 @@
+import type { ReturnSpec } from '@prisma-next/operations';
+import type { SqlLoweringSpec } from '@prisma-next/sql-operations';
+
+// SQL-specific AST types and supporting types
+// These types are needed by adapters and runtime for SQL query execution
+
+export type Direction = 'asc' | 'desc';
+
+export interface TableRef {
+  readonly kind: 'table';
+  readonly name: string;
+}
+
+export interface ColumnRef {
+  readonly kind: 'col';
+  readonly table: string;
+  readonly column: string;
+}
+
+export interface ParamRef {
+  readonly kind: 'param';
+  readonly index: number;
+  readonly name?: string;
+}
+
+export interface LiteralExpr {
+  readonly kind: 'literal';
+  readonly value: unknown;
+}
+
+export interface OperationExpr {
+  readonly kind: 'operation';
+  readonly method: string;
+  readonly forTypeId: string;
+  readonly self: ColumnRef | OperationExpr;
+  readonly args: ReadonlyArray<ColumnRef | ParamRef | LiteralExpr | OperationExpr>;
+  readonly returns: ReturnSpec;
+  readonly lowering: SqlLoweringSpec;
+}
+
+export function isOperationExpr(expr: ColumnRef | OperationExpr): expr is OperationExpr {
+  return expr.kind === 'operation';
+}
+
+export type BinaryOp = 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte';
+
+export interface BinaryExpr {
+  readonly kind: 'bin';
+  readonly op: BinaryOp;
+  readonly left: ColumnRef | OperationExpr;
+  readonly right: ColumnRef | ParamRef;
+}
+
+export interface ExistsExpr {
+  readonly kind: 'exists';
+  readonly not: boolean;
+  readonly subquery: SelectAst;
+}
+
+export type JoinOnExpr = {
+  readonly kind: 'eqCol';
+  readonly left: ColumnRef;
+  readonly right: ColumnRef;
+};
+
+export interface JoinAst {
+  readonly kind: 'join';
+  readonly joinType: 'inner' | 'left' | 'right' | 'full';
+  readonly table: TableRef;
+  readonly on: JoinOnExpr;
+}
+
+export interface IncludeRef {
+  readonly kind: 'includeRef';
+  readonly alias: string;
+}
+
+export interface IncludeAst {
+  readonly kind: 'includeMany';
+  readonly alias: string;
+  readonly child: {
+    readonly table: TableRef;
+    readonly on: JoinOnExpr;
+    readonly where?: BinaryExpr | ExistsExpr;
+    readonly orderBy?: ReadonlyArray<{ expr: ColumnRef | OperationExpr; dir: Direction }>;
+    readonly limit?: number;
+    readonly project: ReadonlyArray<{ alias: string; expr: ColumnRef | OperationExpr }>;
+  };
+}
+
+export interface SelectAst {
+  readonly kind: 'select';
+  readonly from: TableRef;
+  readonly joins?: ReadonlyArray<JoinAst>;
+  readonly includes?: ReadonlyArray<IncludeAst>;
+  readonly project: ReadonlyArray<{
+    alias: string;
+    expr: ColumnRef | IncludeRef | OperationExpr | LiteralExpr;
+  }>;
+  readonly where?: BinaryExpr | ExistsExpr;
+  readonly orderBy?: ReadonlyArray<{ expr: ColumnRef | OperationExpr; dir: Direction }>;
+  readonly limit?: number;
+}
+
+export interface InsertAst {
+  readonly kind: 'insert';
+  readonly table: TableRef;
+  readonly values: Record<string, ColumnRef | ParamRef>;
+  readonly returning?: ReadonlyArray<ColumnRef>;
+}
+
+export interface UpdateAst {
+  readonly kind: 'update';
+  readonly table: TableRef;
+  readonly set: Record<string, ColumnRef | ParamRef>;
+  readonly where: BinaryExpr;
+  readonly returning?: ReadonlyArray<ColumnRef>;
+}
+
+export interface DeleteAst {
+  readonly kind: 'delete';
+  readonly table: TableRef;
+  readonly where: BinaryExpr;
+  readonly returning?: ReadonlyArray<ColumnRef>;
+}
+
+export type QueryAst = SelectAst | InsertAst | UpdateAst | DeleteAst;
+
+export interface LoweredStatement {
+  readonly sql: string;
+  readonly params: readonly unknown[];
+  readonly annotations?: Record<string, unknown>;
+}

package/src/ast/update.ts

@@ -0,0 +1,19 @@
+import type { BinaryExpr, ColumnRef, ParamRef, TableRef, UpdateAst } from './types';
+import { compact } from './util';
+
+export interface CreateUpdateAstOptions {
+  readonly table: TableRef;
+  readonly set: Record<string, ColumnRef | ParamRef>;
+  readonly where: BinaryExpr;
+  readonly returning?: ReadonlyArray<ColumnRef>;
+}
+
+export function createUpdateAst(options: CreateUpdateAstOptions): UpdateAst {
+  return compact({
+    kind: 'update',
+    table: options.table,
+    set: options.set,
+    where: options.where,
+    returning: options.returning,
+  }) as UpdateAst;
+}

package/src/ast/util.ts

@@ -0,0 +1,9 @@
+export function compact<T extends Record<string, unknown>>(o: T): T {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(o)) {
+    if (v === undefined || v === null) continue;
+    if (Array.isArray(v) && v.length === 0) continue;
+    out[k] = v;
+  }
+  return out as T;
+}

package/src/errors.ts

@@ -0,0 +1 @@
+export { planInvalid, planUnsupported } from '@prisma-next/plan';

package/src/exports/ast.ts

@@ -0,0 +1,13 @@
+export * from '../ast/adapter-types';
+export * from '../ast/codec-types';
+export * from '../ast/common';
+export * from '../ast/delete';
+export * from '../ast/driver-types';
+export * from '../ast/insert';
+export * from '../ast/join';
+export * from '../ast/order';
+export * from '../ast/predicate';
+export * from '../ast/select';
+export * from '../ast/types';
+export * from '../ast/update';
+export * from '../ast/util';

package/src/exports/errors.ts

@@ -0,0 +1 @@
+export { planInvalid, planUnsupported } from '../errors';

package/src/exports/guards.ts

@@ -0,0 +1,10 @@
+export {
+  collectColumnRefs,
+  extractBaseColumnRef,
+  getColumnInfo,
+  getColumnMeta,
+  getOperationExpr,
+  isColumnBuilder,
+  isOperationExpr,
+  isParamPlaceholder,
+} from '../utils/guards';

package/src/exports/operations-registry.ts

@@ -0,0 +1 @@
+export { attachOperationsToColumnBuilder } from '../operations-registry';

package/src/exports/param.ts

@@ -0,0 +1,2 @@
+export type { Parameter } from '../param';
+export { param } from '../param';

package/src/exports/plan.ts

@@ -0,0 +1 @@
+export * from '../plan';

package/src/exports/query-lane-context.ts

@@ -0,0 +1 @@
+export * from '../query-lane-context';

package/src/exports/schema.ts

@@ -0,0 +1,6 @@
+export type {
+  ColumnBuilderImpl as Column,
+  SchemaHandle,
+  TableBuilderImpl as Table,
+} from '../schema';
+export { ColumnBuilderImpl, schema, TableBuilderImpl } from '../schema';

package/src/exports/types.ts

@@ -0,0 +1 @@
+export * from '../types';

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './exports/ast';
+export * from './exports/errors';
+export * from './exports/operations-registry';
+export * from './exports/param';
+export * from './exports/plan';
+export * from './exports/query-lane-context';
+export * from './exports/schema';
+export * from './exports/types';

package/src/operations-registry.ts

@@ -0,0 +1,237 @@
+import type { OperationRegistry } from '@prisma-next/operations';
+import { hasAllCapabilities } from '@prisma-next/operations';
+import { planInvalid } from '@prisma-next/plan';
+import type { StorageColumn } from '@prisma-next/sql-contract/types';
+import type { SqlOperationSignature } from '@prisma-next/sql-operations';
+import type { BinaryOp, ColumnRef, LiteralExpr, OperationExpr, ParamRef } from './ast/types';
+import type { AnyColumnBuilder, ColumnBuilder, OperationTypes, ParamPlaceholder } from './types';
+import { isParamPlaceholder } from './utils/guards';
+
+function isColumnBuilder(value: unknown): value is AnyColumnBuilder {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'kind' in value &&
+    (value as { kind: unknown }).kind === 'column'
+  );
+}
+
+/**
+ * Executes an operation and returns a column-shaped result object.
+ * This is the canonical entrypoint for operation invocation, enabling
+ * future enhancements like telemetry, caching, or tracing.
+ *
+ * @param signature - The operation signature from the registry
+ * @param selfBuilder - The column builder that the operation is called on
+ * @param args - The arguments passed to the operation
+ * @param columnMeta - The metadata of the column the operation is called on
+ * @returns A column-shaped builder with the operation expression attached
+ */
+function executeOperation(
+  signature: SqlOperationSignature,
+  selfBuilder: AnyColumnBuilder,
+  args: unknown[],
+  columnMeta: StorageColumn,
+  operationRegistry?: OperationRegistry,
+  contractCapabilities?: Record<string, Record<string, boolean>>,
+): AnyColumnBuilder & { _operationExpr?: OperationExpr } {
+  if (args.length !== signature.args.length) {
+    throw planInvalid(
+      `Operation ${signature.method} expects ${signature.args.length} arguments, got ${args.length}`,
+    );
+  }
+
+  // Check if this column builder has an existing operation expression
+  const selfBuilderWithExpr = selfBuilder as unknown as {
+    _operationExpr?: OperationExpr;
+    table: string;
+    column: string;
+  };
+  const selfExpr: ColumnRef | OperationExpr = selfBuilderWithExpr._operationExpr
+    ? selfBuilderWithExpr._operationExpr
+    : {
+        kind: 'col',
+        table: selfBuilderWithExpr.table,
+        column: selfBuilderWithExpr.column,
+      };
+
+  const operationArgs: Array<ColumnRef | ParamRef | LiteralExpr | OperationExpr> = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const argSpec = signature.args[i];
+    if (!argSpec) {
+      throw planInvalid(`Missing argument spec for argument ${i}`);
+    }
+
+    if (argSpec.kind === 'param') {
+      if (!isParamPlaceholder(arg)) {
+        throw planInvalid(`Argument ${i} must be a parameter placeholder`);
+      }
+      operationArgs.push({
+        kind: 'param',
+        index: 0,
+        name: arg.name,
+      });
+    } else if (argSpec.kind === 'typeId') {
+      if (!isColumnBuilder(arg)) {
+        throw planInvalid(`Argument ${i} must be a ColumnBuilder`);
+      }
+      const colBuilderWithExpr = arg as unknown as {
+        _operationExpr?: OperationExpr;
+        table: string;
+        column: string;
+      };
+      // Check if the column builder has an operation expression
+      if (colBuilderWithExpr._operationExpr) {
+        operationArgs.push(colBuilderWithExpr._operationExpr);
+      } else {
+        // Fall back to raw ColumnRef
+        operationArgs.push({
+          kind: 'col',
+          table: colBuilderWithExpr.table,
+          column: colBuilderWithExpr.column,
+        });
+      }
+    } else if (argSpec.kind === 'literal') {
+      operationArgs.push({
+        kind: 'literal',
+        value: arg,
+      });
+    }
+  }
+
+  const operationExpr: OperationExpr = {
+    kind: 'operation',
+    method: signature.method,
+    forTypeId: signature.forTypeId,
+    self: selfExpr,
+    args: operationArgs,
+    returns: signature.returns,
+    lowering: signature.lowering,
+  };
+
+  const returnTypeId = signature.returns.kind === 'typeId' ? signature.returns.type : undefined;
+  const returnColumnMeta: StorageColumn = returnTypeId
+    ? {
+        ...columnMeta,
+        codecId: returnTypeId,
+      }
+    : columnMeta;
+
+  const createComparisonMethod = (op: BinaryOp) => (value: ParamPlaceholder) =>
+    Object.freeze({
+      kind: 'binary' as const,
+      op,
+      left: operationExpr,
+      right: value,
+    });
+
+  const baseResult = {
+    kind: 'column' as const,
+    table: selfBuilderWithExpr.table,
+    column: selfBuilderWithExpr.column,
+    get columnMeta() {
+      return returnColumnMeta;
+    },
+    eq: createComparisonMethod('eq'),
+    neq: createComparisonMethod('neq'),
+    gt: createComparisonMethod('gt'),
+    lt: createComparisonMethod('lt'),
+    gte: createComparisonMethod('gte'),
+    lte: createComparisonMethod('lte'),
+    asc() {
+      return Object.freeze({
+        kind: 'order' as const,
+        expr: operationExpr,
+        dir: 'asc' as const,
+      });
+    },
+    desc() {
+      return Object.freeze({
+        kind: 'order' as const,
+        expr: operationExpr,
+        dir: 'desc' as const,
+      });
+    },
+    _operationExpr: operationExpr,
+  } as unknown as AnyColumnBuilder & {
+    _operationExpr?: OperationExpr;
+  };
+
+  // If the return type is a typeId, attach operations for that type
+  if (returnTypeId && operationRegistry) {
+    const resultWithOps = attachOperationsToColumnBuilder(
+      baseResult as ColumnBuilder<string, StorageColumn, unknown, Record<string, never>>,
+      returnColumnMeta,
+      operationRegistry,
+      contractCapabilities,
+    ) as AnyColumnBuilder & {
+      _operationExpr?: OperationExpr;
+    };
+    return Object.freeze(resultWithOps);
+  }
+
+  return Object.freeze(baseResult);
+}
+
+export function attachOperationsToColumnBuilder<
+  ColumnName extends string,
+  ColumnMeta extends StorageColumn,
+  JsType = unknown,
+  Operations extends OperationTypes = Record<string, never>,
+>(
+  columnBuilder: ColumnBuilder<ColumnName, ColumnMeta, JsType, Record<string, never>>,
+  columnMeta: ColumnMeta,
+  registry: OperationRegistry | undefined,
+  contractCapabilities?: Record<string, Record<string, boolean>>,
+): ColumnBuilder<ColumnName, ColumnMeta, JsType, Operations> {
+  if (!registry) {
+    return columnBuilder as ColumnBuilder<ColumnName, ColumnMeta, JsType, Operations>;
+  }
+
+  // Use codecId to look up operations registered for this column's type
+  const codecId = columnMeta.codecId;
+  if (!codecId) {
+    return columnBuilder as ColumnBuilder<ColumnName, ColumnMeta, JsType, Operations>;
+  }
+
+  const operations = registry.byType(codecId) as SqlOperationSignature[];
+  if (operations.length === 0) {
+    return columnBuilder as ColumnBuilder<ColumnName, ColumnMeta, JsType, Operations>;
+  }
+
+  const builderWithOps = columnBuilder as unknown as ColumnBuilder<
+    ColumnName,
+    ColumnMeta,
+    JsType,
+    Operations
+  >;
+
+  for (const operation of operations) {
+    if (operation.capabilities && operation.capabilities.length > 0) {
+      if (!contractCapabilities) {
+        continue;
+      }
+
+      if (!hasAllCapabilities(operation.capabilities, contractCapabilities)) {
+        continue;
+      }
+    }
+    // Method sugar: attach operation as a method on the column builder
+    (builderWithOps as Record<string, unknown>)[operation.method] = function (
+      this: ColumnBuilder<ColumnName, ColumnMeta, JsType, Record<string, never>>,
+      ...args: unknown[]
+    ) {
+      return executeOperation(
+        operation,
+        this as unknown as ColumnBuilder<string, StorageColumn, unknown>,
+        args,
+        columnMeta,
+        registry,
+        contractCapabilities,
+      );
+    };
+  }
+
+  return builderWithOps;
+}

package/src/param.ts

@@ -0,0 +1,15 @@
+import { planInvalid } from '@prisma-next/plan';
+import type { ParamPlaceholder } from './types';
+
+export type Parameter = ParamPlaceholder;
+
+export function param(name: string): Parameter {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw planInvalid('Parameter name must be a non-empty string');
+  }
+
+  return Object.freeze({
+    kind: 'param-placeholder' as const,
+    name,
+  }) satisfies Parameter;
+}

package/src/plan.ts

@@ -0,0 +1,39 @@
+import type { ExecutionPlan, ParamDescriptor } from '@prisma-next/contract/types';
+import type { StorageColumn } from '@prisma-next/sql-contract/types';
+import type { QueryAst } from './ast/types';
+
+/**
+ * SQL query plan produced by lanes before lowering.
+ *
+ * Lanes build ASTs and metadata but do not perform SQL lowering.
+ * The `sql` field is absent - lowering happens in the runtime executor.
+ *
+ * Structurally aligns with ExecutionPlan<Row, QueryAst> (without sql field) to maintain
+ * compatibility with ExecutionPlan/Plan-based utilities.
+ * The generic parameter `_Row` is preserved for type extraction via ResultType.
+ */
+export interface SqlQueryPlan<_Row = unknown>
+  extends Pick<ExecutionPlan<_Row, QueryAst>, 'params' | 'meta'> {
+  readonly ast: QueryAst;
+  // Phantom property to preserve generic parameter for type extraction
+  // This allows ResultType to extract _Row for SqlQueryPlan values.
+  readonly _Row?: _Row;
+}
+
+/**
+ * Augments the last ParamDescriptor in the array with codecId and nativeType from columnMeta.
+ * This is used when building WHERE expressions to ensure param descriptors have type information.
+ */
+export function augmentDescriptorWithColumnMeta(
+  descriptors: ParamDescriptor[],
+  columnMeta: StorageColumn | undefined,
+): void {
+  const descriptor = descriptors[descriptors.length - 1];
+  if (descriptor && columnMeta) {
+    descriptors[descriptors.length - 1] = {
+      ...descriptor,
+      codecId: columnMeta.codecId,
+      nativeType: columnMeta.nativeType,
+    };
+  }
+}

package/src/query-lane-context.ts

@@ -0,0 +1,18 @@
+import type { OperationRegistry } from '@prisma-next/operations';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { CodecRegistry } from './ast/codec-types';
+
+/**
+ * Minimal context interface for SQL query lanes.
+ *
+ * Lanes only need contract, operations, and codecs to build typed ASTs and attach
+ * operation builders. This interface explicitly excludes runtime concerns like
+ * adapters, connection management, and transaction state.
+ */
+export interface QueryLaneContext<
+  TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
+> {
+  readonly contract: TContract;
+  readonly operations: OperationRegistry;
+  readonly codecs: CodecRegistry;
+}