@prisma-next/sql-relational-core 0.3.0-dev.3 → 0.3.0-dev.31

package/src/ast/select.ts

@@ -0,0 +1,39 @@
+import type {
+  BinaryExpr,
+  ColumnRef,
+  Direction,
+  ExistsExpr,
+  IncludeAst,
+  IncludeRef,
+  JoinAst,
+  OperationExpr,
+  SelectAst,
+  TableRef,
+} 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?: BinaryExpr | ExistsExpr;
+  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;
+}

package/src/ast/types.ts

@@ -0,0 +1,147 @@
+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: Expression;
+  readonly args: ReadonlyArray<Expression | ParamRef | LiteralExpr>;
+  readonly returns: ReturnSpec;
+  readonly lowering: SqlLoweringSpec;
+}
+
+/**
+ * Unified expression type - the canonical AST representation for column references
+ * and operation expressions. This is what all builders convert to via toExpr().
+ */
+export type Expression = ColumnRef | OperationExpr;
+
+/**
+ * Interface for any builder that can produce an Expression.
+ * Implemented by ColumnBuilder and ExpressionBuilder.
+ */
+export interface ExpressionSource {
+  toExpr(): Expression;
+}
+
+export function isOperationExpr(expr: Expression): 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: Expression;
+  readonly right: Expression | 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: Expression; dir: Direction }>;
+    readonly limit?: number;
+    readonly project: ReadonlyArray<{ alias: string; expr: Expression }>;
+  };
+}
+
+export interface SelectAst {
+  readonly kind: 'select';
+  readonly from: TableRef;
+  readonly joins?: ReadonlyArray<JoinAst>;
+  readonly includes?: ReadonlyArray<IncludeAst>;
+  readonly project: ReadonlyArray<{
+    alias: string;
+    expr: Expression | IncludeRef | LiteralExpr;
+  }>;
+  readonly where?: BinaryExpr | ExistsExpr;
+  readonly orderBy?: ReadonlyArray<{ expr: Expression; 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,15 @@
+export {
+  collectColumnRefs,
+  expressionFromSource,
+  extractBaseColumnRef,
+  getColumnInfo,
+  getColumnMeta,
+  getOperationExpr,
+  isColumnBuilder,
+  isExpressionBuilder,
+  isExpressionSource,
+  isOperationExpr,
+  isParamPlaceholder,
+  isValueSource,
+  toExpression,
+} 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,276 @@
+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,
+  Expression,
+  ExpressionSource,
+  LiteralExpr,
+  OperationExpr,
+  ParamRef,
+} from './ast/types';
+import type {
+  AnyBinaryBuilder,
+  AnyOrderBuilder,
+  ColumnBuilder,
+  ExpressionBuilder,
+  OperationTypes,
+  ParamPlaceholder,
+} from './types';
+import { isParamPlaceholder } from './utils/guards';
+
+/**
+ * Type guard to check if a value is an ExpressionSource (has toExpr method).
+ */
+function isExpressionSource(value: unknown): value is ExpressionSource {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'toExpr' in value &&
+    typeof (value as ExpressionSource).toExpr === 'function'
+  );
+}
+
+/**
+ * Executes an operation and returns an ExpressionBuilder.
+ * This is the canonical entrypoint for operation invocation, enabling
+ * future enhancements like telemetry, caching, or tracing.
+ *
+ * The returned ExpressionBuilder:
+ * - Has `kind: 'expression'` to distinguish it from ColumnBuilder
+ * - Contains the operation expression in `expr`
+ * - Provides `toExpr()` method to get the Expression
+ * - Provides comparison and ordering methods for chaining
+ *
+ * @param signature - The operation signature from the registry
+ * @param selfBuilder - The expression source 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 An ExpressionBuilder containing the operation expression
+ */
+function executeOperation(
+  signature: SqlOperationSignature,
+  selfBuilder: ExpressionSource,
+  args: unknown[],
+  columnMeta: StorageColumn,
+  operationRegistry?: OperationRegistry,
+  contractCapabilities?: Record<string, Record<string, boolean>>,
+): ExpressionBuilder {
+  if (args.length !== signature.args.length) {
+    throw planInvalid(
+      `Operation ${signature.method} expects ${signature.args.length} arguments, got ${args.length}`,
+    );
+  }
+
+  // Get the Expression from the self builder using toExpr()
+  const selfExpr: Expression = selfBuilder.toExpr();
+
+  const operationArgs: Array<Expression | ParamRef | LiteralExpr> = [];
+  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') {
+      // Accept ExpressionSource (ColumnBuilder or ExpressionBuilder)
+      if (!isExpressionSource(arg)) {
+        throw planInvalid(
+          `Argument ${i} must be an ExpressionSource (ColumnBuilder or ExpressionBuilder)`,
+        );
+      }
+      // Use toExpr() to get the Expression
+      operationArgs.push(arg.toExpr());
+    } 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 | ExpressionSource): AnyBinaryBuilder =>
+      Object.freeze({
+        kind: 'binary' as const,
+        op,
+        left: operationExpr,
+        right: value,
+      }) as AnyBinaryBuilder;
+
+  const baseResult: ExpressionBuilder = {
+    kind: 'expression' as const,
+    expr: operationExpr,
+    get columnMeta() {
+      return returnColumnMeta;
+    },
+    eq: createComparisonMethod('eq'),
+    neq: createComparisonMethod('neq'),
+    gt: createComparisonMethod('gt'),
+    lt: createComparisonMethod('lt'),
+    gte: createComparisonMethod('gte'),
+    lte: createComparisonMethod('lte'),
+    asc(): AnyOrderBuilder {
+      return Object.freeze({
+        kind: 'order' as const,
+        expr: operationExpr,
+        dir: 'asc' as const,
+      });
+    },
+    desc(): AnyOrderBuilder {
+      return Object.freeze({
+        kind: 'order' as const,
+        expr: operationExpr,
+        dir: 'desc' as const,
+      });
+    },
+    toExpr(): OperationExpr {
+      return operationExpr;
+    },
+    get __jsType(): unknown {
+      return undefined;
+    },
+  };
+
+  // If the return type is a typeId, attach operations for that type
+  if (returnTypeId && operationRegistry) {
+    const resultWithOps = attachOperationsToExpressionBuilder(
+      baseResult,
+      returnColumnMeta,
+      operationRegistry,
+      contractCapabilities,
+    );
+    return Object.freeze(resultWithOps);
+  }
+
+  return Object.freeze(baseResult);
+}
+
+/**
+ * Attaches operation methods to an ExpressionBuilder for chained operations.
+ * When an operation returns a typeId, the result ExpressionBuilder needs
+ * operation methods for that type.
+ */
+function attachOperationsToExpressionBuilder(
+  expressionBuilder: ExpressionBuilder,
+  columnMeta: StorageColumn,
+  registry: OperationRegistry,
+  contractCapabilities?: Record<string, Record<string, boolean>>,
+): ExpressionBuilder {
+  const codecId = columnMeta.codecId;
+  if (!codecId) {
+    return expressionBuilder;
+  }
+
+  const operations = registry.byType(codecId) as SqlOperationSignature[];
+  if (operations.length === 0) {
+    return expressionBuilder;
+  }
+
+  const builderWithOps = expressionBuilder as ExpressionBuilder & Record<string, unknown>;
+
+  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 expression builder
+    builderWithOps[operation.method] = function (this: ExpressionBuilder, ...args: unknown[]) {
+      return executeOperation(operation, this, args, columnMeta, registry, contractCapabilities);
+    };
+  }
+
+  return builderWithOps;
+}
+
+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
+    // Operations return ExpressionBuilder, not ColumnBuilder
+    (builderWithOps as Record<string, unknown>)[operation.method] = function (
+      this: ColumnBuilder<ColumnName, ColumnMeta, JsType, Record<string, never>>,
+      ...args: unknown[]
+    ) {
+      return executeOperation(operation, this, 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,30 @@
+import type { OperationRegistry } from '@prisma-next/operations';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { CodecRegistry } from './ast/codec-types';
+
+/**
+ * Registry of initialized type helpers from storage.types.
+ * Each key is a type name from storage.types, and the value is the initialized helper
+ * (or validated typeParams if no init hook was provided).
+ */
+export type TypeHelperRegistry = Record<string, unknown>;
+
+/**
+ * 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;
+  /**
+   * Optional type helper registry for parameterized types.
+   * When present, schema() will expose these helpers via schema.types.
+   */
+  readonly types?: TypeHelperRegistry;
+}