@prisma-next/sql-relational-core 0.3.0-pr.99.1 → 0.3.0-pr.99.2

package/src/ast/predicate.ts

@@ -1,17 +1,9 @@
-import type {
-  BinaryExpr,
-  BinaryOp,
-  ColumnRef,
-  ExistsExpr,
-  OperationExpr,
-  ParamRef,
-  SelectAst,
-} from './types';
+import type { BinaryExpr, BinaryOp, ExistsExpr, Expression, ParamRef, SelectAst } from './types';
 
 export function createBinaryExpr(
   op: BinaryOp,
-  left: ColumnRef | OperationExpr,
-  right: ColumnRef | ParamRef,
+  left: Expression,
+  right: Expression | ParamRef,
 ): BinaryExpr {
   return {
     kind: 'bin',

package/src/ast/types.ts

@@ -32,13 +32,27 @@ export interface OperationExpr {
   readonly kind: 'operation';
   readonly method: string;
   readonly forTypeId: string;
-  readonly self: ColumnRef | OperationExpr;
-  readonly args: ReadonlyArray<ColumnRef | ParamRef | LiteralExpr | OperationExpr>;
+  readonly self: Expression;
+  readonly args: ReadonlyArray<Expression | ParamRef | LiteralExpr>;
   readonly returns: ReturnSpec;
   readonly lowering: SqlLoweringSpec;
 }
 
-export function isOperationExpr(expr: ColumnRef | OperationExpr): expr is OperationExpr {
+/**
+ * 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';
 }
 
@@ -47,8 +61,8 @@ 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;
+  readonly left: Expression;
+  readonly right: Expression | ParamRef;
 }
 
 export interface ExistsExpr {
@@ -82,9 +96,9 @@ export interface IncludeAst {
     readonly table: TableRef;
     readonly on: JoinOnExpr;
     readonly where?: BinaryExpr | ExistsExpr;
-    readonly orderBy?: ReadonlyArray<{ expr: ColumnRef | OperationExpr; dir: Direction }>;
+    readonly orderBy?: ReadonlyArray<{ expr: Expression; dir: Direction }>;
     readonly limit?: number;
-    readonly project: ReadonlyArray<{ alias: string; expr: ColumnRef | OperationExpr }>;
+    readonly project: ReadonlyArray<{ alias: string; expr: Expression }>;
   };
 }
 
@@ -95,10 +109,10 @@ export interface SelectAst {
   readonly includes?: ReadonlyArray<IncludeAst>;
   readonly project: ReadonlyArray<{
     alias: string;
-    expr: ColumnRef | IncludeRef | OperationExpr | LiteralExpr;
+    expr: Expression | IncludeRef | LiteralExpr;
   }>;
   readonly where?: BinaryExpr | ExistsExpr;
-  readonly orderBy?: ReadonlyArray<{ expr: ColumnRef | OperationExpr; dir: Direction }>;
+  readonly orderBy?: ReadonlyArray<{ expr: Expression; dir: Direction }>;
   readonly limit?: number;
 }
 

package/src/exports/guards.ts

@@ -1,10 +1,15 @@
 export {
   collectColumnRefs,
+  expressionFromSource,
   extractBaseColumnRef,
   getColumnInfo,
   getColumnMeta,
   getOperationExpr,
   isColumnBuilder,
+  isExpressionBuilder,
+  isExpressionSource,
   isOperationExpr,
   isParamPlaceholder,
+  isValueSource,
+  toExpression,
 } from '../utils/guards';

package/src/operations-registry.ts

@@ -3,59 +3,71 @@ 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 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';
 
-function isColumnBuilder(value: unknown): value is AnyColumnBuilder {
+/**
+ * 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 &&
-    'kind' in value &&
-    (value as { kind: unknown }).kind === 'column'
+    'toExpr' in value &&
+    typeof (value as ExpressionSource).toExpr === 'function'
   );
 }
 
 /**
- * Executes an operation and returns a column-shaped result object.
+ * 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 column builder that the operation is called on
+ * @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 A column-shaped builder with the operation expression attached
+ * @returns An ExpressionBuilder containing the operation expression
  */
 function executeOperation(
   signature: SqlOperationSignature,
-  selfBuilder: AnyColumnBuilder,
+  selfBuilder: ExpressionSource,
   args: unknown[],
   columnMeta: StorageColumn,
   operationRegistry?: OperationRegistry,
   contractCapabilities?: Record<string, Record<string, boolean>>,
-): AnyColumnBuilder & { _operationExpr?: OperationExpr } {
+): ExpressionBuilder {
   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> = [];
+  // 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];
@@ -73,25 +85,14 @@ function executeOperation(
         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,
-        });
+      // 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',
@@ -118,18 +119,19 @@ function executeOperation(
       }
     : 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,
+  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;
     },
@@ -139,41 +141,84 @@ function executeOperation(
     lt: createComparisonMethod('lt'),
     gte: createComparisonMethod('gte'),
     lte: createComparisonMethod('lte'),
-    asc() {
+    asc(): AnyOrderBuilder {
       return Object.freeze({
         kind: 'order' as const,
         expr: operationExpr,
         dir: 'asc' as const,
       });
     },
-    desc() {
+    desc(): AnyOrderBuilder {
       return Object.freeze({
         kind: 'order' as const,
         expr: operationExpr,
         dir: 'desc' as const,
       });
     },
-    _operationExpr: operationExpr,
-  } as unknown as AnyColumnBuilder & {
-    _operationExpr?: OperationExpr;
+    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 = attachOperationsToColumnBuilder(
-      baseResult as ColumnBuilder<string, StorageColumn, unknown, Record<string, never>>,
+    const resultWithOps = attachOperationsToExpressionBuilder(
+      baseResult,
       returnColumnMeta,
       operationRegistry,
       contractCapabilities,
-    ) as AnyColumnBuilder & {
-      _operationExpr?: OperationExpr;
-    };
+    );
     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,
@@ -218,18 +263,12 @@ export function attachOperationsToColumnBuilder<
       }
     }
     // 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 as unknown as ColumnBuilder<string, StorageColumn, unknown>,
-        args,
-        columnMeta,
-        registry,
-        contractCapabilities,
-      );
+      return executeOperation(operation, this, args, columnMeta, registry, contractCapabilities);
     };
   }
 

package/src/schema.ts

@@ -7,11 +7,10 @@ import type {
   SqlStorage,
   StorageColumn,
 } from '@prisma-next/sql-contract/types';
-import type { BinaryOp, TableRef } from './ast/types';
+import type { BinaryOp, ColumnRef, ExpressionSource, TableRef } from './ast/types';
 import { attachOperationsToColumnBuilder } from './operations-registry';
 import type { QueryLaneContext } from './query-lane-context';
 import type {
-  AnyColumnBuilderBase,
   BinaryBuilder,
   CodecTypes as CodecTypesType,
   ColumnBuilder,
@@ -21,7 +20,6 @@ import type {
   OrderBuilder,
   ParamPlaceholder,
 } from './types';
-import { isColumnBuilder } from './types';
 
 type TableColumns<Table extends { columns: Record<string, StorageColumn> }> = Table['columns'];
 
@@ -44,7 +42,8 @@ export class ColumnBuilderImpl<
   ColumnName extends string,
   ColumnMeta extends StorageColumn,
   JsType = unknown,
-> {
+> implements ExpressionSource
+{
   readonly kind = 'column' as const;
 
   constructor(
@@ -62,64 +61,76 @@ export class ColumnBuilderImpl<
     return undefined as unknown as JsType;
   }
 
+  /**
+   * Converts this column builder to a ColumnRef expression.
+   * This is the canonical way to get an AST node from a builder.
+   */
+  toExpr(): ColumnRef {
+    return Object.freeze({
+      kind: 'col' as const,
+      table: this.table,
+      column: this.column,
+    });
+  }
+
   private createBinaryBuilder(
     op: BinaryOp,
-    value: ParamPlaceholder | AnyColumnBuilderBase,
+    value: ParamPlaceholder | ExpressionSource,
   ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     if (value == null) {
-      throw planInvalid('Parameter placeholder or column builder required for column comparison');
+      throw planInvalid(
+        'Parameter placeholder or expression source required for column comparison',
+      );
     }
-    if (value.kind === 'param-placeholder' || isColumnBuilder(value)) {
+    // Check for ExpressionSource first (has toExpr method)
+    if ('toExpr' in value && typeof value.toExpr === 'function') {
       return Object.freeze({
         kind: 'binary' as const,
         op,
-        left: this as unknown as ColumnBuilder<ColumnName, ColumnMeta, JsType>,
+        left: this.toExpr(),
         right: value,
       }) as BinaryBuilder<ColumnName, ColumnMeta, JsType>;
     }
-    throw planInvalid('Parameter placeholder or column builder required for column comparison');
+    // Must be a ParamPlaceholder
+    if ('kind' in value && value.kind === 'param-placeholder') {
+      return Object.freeze({
+        kind: 'binary' as const,
+        op,
+        left: this.toExpr(),
+        right: value,
+      }) as BinaryBuilder<ColumnName, ColumnMeta, JsType>;
+    }
+    throw planInvalid('Parameter placeholder or expression source required for column comparison');
   }
 
-  eq(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  eq(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('eq', value);
   }
 
-  neq(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  neq(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('neq', value);
   }
 
-  gt(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  gt(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('gt', value);
   }
 
-  lt(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  lt(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('lt', value);
   }
 
-  gte(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  gte(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('gte', value);
   }
 
-  lte(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
+  lte(value: ParamPlaceholder | ExpressionSource): BinaryBuilder<ColumnName, ColumnMeta, JsType> {
     return this.createBinaryBuilder('lte', value);
   }
 
   asc(): OrderBuilder<ColumnName, ColumnMeta, JsType> {
     return Object.freeze({
       kind: 'order' as const,
-      expr: this as unknown as ColumnBuilder<ColumnName, ColumnMeta, JsType>,
+      expr: this.toExpr(),
       dir: 'asc' as const,
     }) as OrderBuilder<ColumnName, ColumnMeta, JsType>;
   }
@@ -127,7 +138,7 @@ export class ColumnBuilderImpl<
   desc(): OrderBuilder<ColumnName, ColumnMeta, JsType> {
     return Object.freeze({
       kind: 'order' as const,
-      expr: this as unknown as ColumnBuilder<ColumnName, ColumnMeta, JsType>,
+      expr: this.toExpr(),
       dir: 'desc' as const,
     }) as OrderBuilder<ColumnName, ColumnMeta, JsType>;
   }