@prisma-next/sql-relational-core 0.3.0-dev.10 → 0.3.0-dev.113

package/src/types.ts

@@ -7,28 +7,38 @@ import type { ArgSpec, ReturnSpec } from '@prisma-next/operations';
 import type { SqlContract, SqlStorage, StorageColumn } from '@prisma-next/sql-contract/types';
 import type { SqlLoweringSpec } from '@prisma-next/sql-operations';
 import type {
+  AnyExpression,
+  AnyQueryAst,
   BinaryOp,
   ColumnRef,
   Direction,
+  ExpressionSource,
   OperationExpr,
   ParamRef,
-  QueryAst,
 } from './ast/types';
 import type { SqlQueryPlan } from './plan';
-import type { QueryLaneContext } from './query-lane-context';
+import type { ExecutionContext } from './query-lane-context';
 
 export interface ParamPlaceholder {
   readonly kind: 'param-placeholder';
   readonly name: string;
 }
 
+/**
+ * ValueSource represents any value that can appear in a comparison or as an argument.
+ * This includes:
+ * - ParamPlaceholder: A parameter placeholder (e.g., `param('userId')`)
+ * - ExpressionSource: Something that can be converted to an Expression (ColumnBuilder, ExpressionBuilder)
+ */
+export type ValueSource = ParamPlaceholder | ExpressionSource;
+
 export interface OrderBuilder<
-  ColumnName extends string = string,
-  ColumnMeta extends StorageColumn = StorageColumn,
-  JsType = unknown,
+  _ColumnName extends string = string,
+  _ColumnMeta extends StorageColumn = StorageColumn,
+  _JsType = unknown,
 > {
   readonly kind: 'order';
-  readonly expr: ColumnBuilder<ColumnName, ColumnMeta, JsType> | OperationExpr;
+  readonly expr: AnyExpression;
   readonly dir: Direction;
 }
 
@@ -45,6 +55,9 @@ export function createOrderBuilder(
 /**
  * ColumnBuilder with optional operation methods based on the column's typeId.
  * When Operations is provided and the column's typeId matches, operation methods are included.
+ * Implements ExpressionSource to provide type-safe conversion to ColumnRef.
+ *
+ * For nullable columns (ColumnMeta['nullable'] extends true), includes isNull() and isNotNull() methods.
  */
 export type ColumnBuilder<
   ColumnName extends string = string,
@@ -56,20 +69,17 @@ export type ColumnBuilder<
   readonly table: string;
   readonly column: ColumnName;
   readonly columnMeta: ColumnMeta;
-  eq(value: ParamPlaceholder | AnyColumnBuilderBase): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
-  neq(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
-  gt(value: ParamPlaceholder | AnyColumnBuilderBase): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
-  lt(value: ParamPlaceholder | AnyColumnBuilderBase): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
-  gte(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
-  lte(
-    value: ParamPlaceholder | AnyColumnBuilderBase,
-  ): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
+  // Methods accept ValueSource (ParamPlaceholder or ExpressionSource)
+  eq(value: ValueSource): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
+  neq(value: ValueSource): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
+  gt(value: ValueSource): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
+  lt(value: ValueSource): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
+  gte(value: ValueSource): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
+  lte(value: ValueSource): BinaryBuilder<ColumnName, ColumnMeta, JsType>;
   asc(): OrderBuilder<ColumnName, ColumnMeta, JsType>;
   desc(): OrderBuilder<ColumnName, ColumnMeta, JsType>;
+  /** Converts this column builder to a ColumnRef expression */
+  toExpr(): ColumnRef;
   // Helper property for type extraction (not used at runtime)
   readonly __jsType: JsType;
 } & (ColumnMeta['codecId'] extends string
@@ -81,17 +91,92 @@ export type ColumnBuilder<
         JsType
       >
     : Record<string, never>
-  : Record<string, never>);
+  : Record<string, never>) &
+  (ColumnMeta['nullable'] extends true
+    ? NullableMethods<ColumnName, ColumnMeta, JsType>
+    : Record<string, never>);
 
 export interface BinaryBuilder<
+  _ColumnName extends string = string,
+  _ColumnMeta extends StorageColumn = StorageColumn,
+  _JsType = unknown,
+> {
+  readonly kind: 'binary';
+  readonly op: BinaryOp;
+  readonly left: AnyExpression;
+  readonly right: ValueSource;
+}
+
+/**
+ * Builder for IS NULL / IS NOT NULL checks.
+ * Used to build unary null check expressions in WHERE clauses.
+ */
+export interface NullCheckBuilder<
+  _ColumnName extends string = string,
+  _ColumnMeta extends StorageColumn = StorageColumn,
+  _JsType = unknown,
+> {
+  readonly kind: 'nullCheck';
+  readonly expr: AnyExpression;
+  readonly isNull: boolean;
+}
+
+/**
+ * Union type for unary builders (currently just NullCheckBuilder).
+ * Extensible for future unary operators.
+ */
+export type UnaryBuilder = NullCheckBuilder;
+
+// Forward declare AnyBinaryBuilder and AnyOrderBuilder for use in ExpressionBuilder
+export type AnyBinaryBuilder = BinaryBuilder;
+export type AnyOrderBuilder = OrderBuilder;
+export type AnyUnaryBuilder = UnaryBuilder;
+
+/**
+ * Methods available only on nullable columns.
+ * These are conditionally added to ColumnBuilder when ColumnMeta['nullable'] is true.
+ * Note: Index signature is required for compatibility with AnyColumnBuilderBase's index signature.
+ */
+export interface NullableMethods<
   ColumnName extends string = string,
   ColumnMeta extends StorageColumn = StorageColumn,
   JsType = unknown,
 > {
-  readonly kind: 'binary';
-  readonly op: BinaryOp;
-  readonly left: ColumnBuilder<ColumnName, ColumnMeta, JsType> | OperationExpr;
-  readonly right: ParamPlaceholder | AnyColumnBuilderBase;
+  /** Creates an IS NULL check for this column */
+  isNull(): NullCheckBuilder<ColumnName, ColumnMeta, JsType>;
+  /** Creates an IS NOT NULL check for this column */
+  isNotNull(): NullCheckBuilder<ColumnName, ColumnMeta, JsType>;
+  /** Index signature for compatibility with AnyColumnBuilderBase */
+  readonly [key: string]: unknown;
+}
+
+/**
+ * ExpressionBuilder represents the result of an operation (e.g., col.distance(...)).
+ * Unlike ColumnBuilder (which represents a column), ExpressionBuilder represents
+ * an operation expression and provides the same DSL methods for chaining.
+ *
+ * Implements ExpressionSource to provide type-safe conversion to OperationExpr.
+ */
+export interface ExpressionBuilder<JsType = unknown> extends ExpressionSource {
+  readonly kind: 'expression';
+  readonly expr: OperationExpr;
+  readonly columnMeta: StorageColumn;
+
+  // Methods accept ValueSource (ParamPlaceholder or ExpressionSource)
+  eq(value: ValueSource): AnyBinaryBuilder;
+  neq(value: ValueSource): AnyBinaryBuilder;
+  gt(value: ValueSource): AnyBinaryBuilder;
+  lt(value: ValueSource): AnyBinaryBuilder;
+  gte(value: ValueSource): AnyBinaryBuilder;
+  lte(value: ValueSource): AnyBinaryBuilder;
+  asc(): AnyOrderBuilder;
+  desc(): AnyOrderBuilder;
+
+  /** Converts this expression builder to the underlying OperationExpr */
+  toExpr(): OperationExpr;
+
+  // Helper property for type extraction (not used at runtime)
+  readonly __jsType: JsType;
 }
 
 // Helper aliases for usage sites where the specific column parameters are irrelevant
@@ -108,15 +193,20 @@ export type AnyColumnBuilderBase = {
   readonly table: string;
   readonly column: string;
   readonly columnMeta: StorageColumn;
-  eq(value: ParamPlaceholder | AnyColumnBuilderBase): AnyBinaryBuilder;
-  neq(value: ParamPlaceholder | AnyColumnBuilderBase): AnyBinaryBuilder;
-  gt(value: ParamPlaceholder | AnyColumnBuilderBase): AnyBinaryBuilder;
-  lt(value: ParamPlaceholder | AnyColumnBuilderBase): AnyBinaryBuilder;
-  gte(value: ParamPlaceholder | AnyColumnBuilderBase): AnyBinaryBuilder;
-  lte(value: ParamPlaceholder | AnyColumnBuilderBase): AnyBinaryBuilder;
+  // Methods accept ValueSource (ParamPlaceholder or ExpressionSource)
+  eq(value: ValueSource): AnyBinaryBuilder;
+  neq(value: ValueSource): AnyBinaryBuilder;
+  gt(value: ValueSource): AnyBinaryBuilder;
+  lt(value: ValueSource): AnyBinaryBuilder;
+  gte(value: ValueSource): AnyBinaryBuilder;
+  lte(value: ValueSource): AnyBinaryBuilder;
   asc(): AnyOrderBuilder;
   desc(): AnyOrderBuilder;
+  toExpr(): ColumnRef;
   readonly __jsType: unknown;
+  // Optional nullable methods (present when columnMeta.nullable is true)
+  isNull?(): AnyUnaryBuilder;
+  isNotNull?(): AnyUnaryBuilder;
   // Allow any operation methods (from conditional type)
   readonly [key: string]: unknown;
 };
@@ -130,8 +220,13 @@ export type AnyColumnBuilder =
       any
     >
   | AnyColumnBuilderBase;
-export type AnyBinaryBuilder = BinaryBuilder<string, StorageColumn, unknown>;
-export type AnyOrderBuilder = OrderBuilder<string, StorageColumn, unknown>;
+
+/**
+ * Union type for any builder that can produce an Expression.
+ * Used in DSL method signatures where either a column or operation result can be passed.
+ */
+// TODO: do we still need this? can we just replace it with ExpressionSource
+export type AnyExpressionSource = AnyColumnBuilder | ExpressionBuilder;
 
 export function isColumnBuilder(value: unknown): value is AnyColumnBuilder {
   return (
@@ -167,6 +262,136 @@ type ExtractCodecOutputType<
     : never
   : never;
 
+/**
+ * Extracts the model name for a given table from the contract mappings.
+ */
+type ExtractTableToModel<
+  Contract extends SqlContract<SqlStorage>,
+  TableName extends string,
+> = Contract['mappings'] extends {
+  readonly tableToModel: infer TableToModel;
+}
+  ? TableToModel extends Record<string, string>
+    ? TableName extends keyof TableToModel
+      ? TableToModel[TableName]
+      : never
+    : never
+  : never;
+
+/**
+ * Extracts the field name for a given table column from the contract mappings.
+ */
+type ExtractColumnToField<
+  Contract extends SqlContract<SqlStorage>,
+  TableName extends string,
+  ColumnName extends string,
+> = Contract['mappings'] extends {
+  readonly columnToField: infer ColumnToField;
+}
+  ? ColumnToField extends Record<string, Record<string, string>>
+    ? TableName extends keyof ColumnToField
+      ? ColumnName extends keyof ColumnToField[TableName]
+        ? ColumnToField[TableName][ColumnName]
+        : never
+      : never
+    : never
+  : never;
+
+/**
+ * Extracts the field value type from a model's fields.
+ */
+type ExtractFieldValue<
+  Contract extends SqlContract<SqlStorage>,
+  ModelName extends string,
+  FieldName extends string,
+> = Contract['models'] extends infer Models
+  ? Models extends Record<string, unknown>
+    ? ModelName extends keyof Models
+      ? Models[ModelName] extends { readonly fields: infer Fields }
+        ? Fields extends Record<string, unknown>
+          ? FieldName extends keyof Fields
+            ? Fields[FieldName]
+            : never
+          : never
+        : never
+      : never
+    : never
+  : never;
+
+/**
+ * Extracts the JavaScript type for a column from model mappings if available.
+ * Returns `never` if the column maps to a ModelField object (which indicates
+ * a relation that should fall through to codec-based type resolution).
+ *
+ * The check for ModelField uses `Exclude<keyof FieldValue, 'column'> extends never`
+ * to ensure we only skip pure `{ column: string }` marker objects, not richer
+ * object types that happen to include a `column` property.
+ */
+type ExtractColumnJsTypeFromModels<
+  Contract extends SqlContract<SqlStorage>,
+  TableName extends string,
+  ColumnName extends string,
+> = ExtractTableToModel<Contract, TableName> extends infer ModelName
+  ? ModelName extends string
+    ? ExtractColumnToField<Contract, TableName, ColumnName> extends infer FieldName
+      ? FieldName extends string
+        ? ExtractFieldValue<Contract, ModelName, FieldName> extends infer FieldValue
+          ? FieldValue extends { readonly column: string }
+            ? Exclude<keyof FieldValue, 'column'> extends never
+              ? never
+              : FieldValue
+            : FieldValue
+          : never
+        : never
+      : never
+    : never
+  : never;
+
+/**
+ * Resolves type params for a column from either:
+ * - inline `columnMeta.typeParams`, or
+ * - `columnMeta.typeRef` (resolving into `contract.storage.types[typeRef].typeParams`).
+ */
+type ResolveColumnTypeParams<
+  Contract extends SqlContract<SqlStorage>,
+  ColumnMeta extends StorageColumn,
+> = ColumnMeta extends { typeParams: infer Params }
+  ? Params extends object
+    ? Params
+    : undefined
+  : ColumnMeta extends { typeRef: infer TypeRef extends string }
+    ? Contract['storage'] extends { types: infer Types }
+      ? Types extends Record<string, unknown>
+        ? TypeRef extends keyof Types
+          ? Types[TypeRef] extends { typeParams: infer Params }
+            ? Params extends object
+              ? Params
+              : undefined
+            : undefined
+          : undefined
+        : undefined
+      : undefined
+    : undefined;
+
+/**
+ * If a codec entry exposes a type-level parameterized output surface, compute the output type
+ * for a specific params object. Falls back to `never` if not supported.
+ *
+ * This enables lane typing to incorporate `columnMeta.typeParams` without branching on codec IDs
+ * in core lane code.
+ */
+type ExtractParameterizedCodecOutputType<
+  CodecId extends string,
+  Params,
+  CodecTypes extends Record<string, { readonly output: unknown }>,
+> = CodecId extends keyof CodecTypes
+  ? CodecTypes[CodecId] extends { readonly parameterizedOutput: infer Fn }
+    ? Fn extends (params: Params) => infer Out
+      ? Out
+      : never
+    : never
+  : never;
+
 /**
  * Type-level operation signature.
  * Represents an operation at the type level, similar to OperationSignature at runtime.
@@ -251,7 +476,7 @@ type OperationMethods<
 /**
  * Maps operation argument specs to TypeScript argument types.
  * - typeId args: ColumnBuilder (accepts base columns or operation results)
- * - param args: ParamPlaceholder
+ * - param args: unknown (raw value; converted to ParamRef at operation build time)
  * - literal args: unknown (could be more specific in future)
  */
 type OperationArgs<Args extends ReadonlyArray<ArgSpec>> = Args extends readonly [
@@ -264,34 +489,30 @@ type OperationArgs<Args extends ReadonlyArray<ArgSpec>> = Args extends readonly
   : [];
 
 type ArgToType<Arg extends ArgSpec> = Arg extends { kind: 'typeId' }
-  ? AnyColumnBuilder
-  : Arg extends { kind: 'param' }
-    ? ParamPlaceholder
-    : Arg extends { kind: 'literal' }
-      ? unknown
-      : never;
+  ? AnyExpressionSource
+  : unknown;
 
 /**
  * Maps operation return spec to return type.
- * - builtin types: ColumnBuilder with appropriate JsType (matches runtime behavior)
- * - typeId types: ColumnBuilder (for now, could be more specific in future)
+ * Operations return ExpressionBuilder, not ColumnBuilder, because the result
+ * represents an expression (OperationExpr) rather than a column reference.
  */
 type OperationReturn<
   Returns extends ReturnSpec,
-  ColumnName extends string,
-  ColumnMeta extends StorageColumn,
+  _ColumnName extends string,
+  _ColumnMeta extends StorageColumn,
   _JsType,
 > = Returns extends { kind: 'builtin'; type: infer T }
   ? T extends 'number'
-    ? ColumnBuilder<ColumnName, ColumnMeta, number>
+    ? ExpressionBuilder<number>
     : T extends 'boolean'
-      ? ColumnBuilder<ColumnName, ColumnMeta, boolean>
+      ? ExpressionBuilder<boolean>
       : T extends 'string'
-        ? ColumnBuilder<ColumnName, ColumnMeta, string>
-        : ColumnBuilder<ColumnName, ColumnMeta, unknown>
+        ? ExpressionBuilder<string>
+        : ExpressionBuilder<unknown>
   : Returns extends { kind: 'typeId' }
-    ? AnyColumnBuilder
-    : ColumnBuilder<ColumnName, ColumnMeta, unknown>;
+    ? ExpressionBuilder<unknown>
+    : ExpressionBuilder<unknown>;
 
 /**
  * Computes JavaScript type for a column at column creation time.
@@ -308,23 +529,47 @@ type ColumnMetaTypeId<ColumnMeta> = ColumnMeta extends { codecId: infer CodecId
     : never;
 
 export type ComputeColumnJsType<
-  _Contract extends SqlContract<SqlStorage>,
-  _TableName extends string,
-  _ColumnName extends string,
+  Contract extends SqlContract<SqlStorage>,
+  TableName extends string,
+  ColumnName extends string,
   ColumnMeta extends StorageColumn,
   CodecTypes extends Record<string, { readonly output: unknown }>,
-> = ColumnMeta extends { nullable: infer Nullable }
-  ? ColumnMetaTypeId<ColumnMeta> extends infer TypeId
-    ? TypeId extends string
-      ? ExtractCodecOutputType<TypeId, CodecTypes> extends infer CodecOutput
-        ? [CodecOutput] extends [never]
-          ? unknown // Codec not found in CodecTypes
-          : Nullable extends true
-            ? CodecOutput | null
-            : CodecOutput
+> = ExtractColumnJsTypeFromModels<Contract, TableName, ColumnName> extends infer FromModels
+  ? [FromModels] extends [never]
+    ? ColumnMeta extends { nullable: infer Nullable }
+      ? ColumnMetaTypeId<ColumnMeta> extends infer TypeId
+        ? TypeId extends string
+          ? ResolveColumnTypeParams<Contract, ColumnMeta> extends infer Params
+            ? Params extends object
+              ? ExtractParameterizedCodecOutputType<
+                  TypeId,
+                  Params,
+                  CodecTypes
+                > extends infer ParamOutput
+                ? [ParamOutput] extends [never]
+                  ? ExtractCodecOutputType<TypeId, CodecTypes> extends infer CodecOutput
+                    ? [CodecOutput] extends [never]
+                      ? unknown // Codec not found in CodecTypes
+                      : Nullable extends true
+                        ? CodecOutput | null
+                        : CodecOutput
+                    : unknown
+                  : Nullable extends true
+                    ? ParamOutput | null
+                    : ParamOutput
+                : unknown
+              : ExtractCodecOutputType<TypeId, CodecTypes> extends infer CodecOutput
+                ? [CodecOutput] extends [never]
+                  ? unknown // Codec not found in CodecTypes
+                  : Nullable extends true
+                    ? CodecOutput | null
+                    : CodecOutput
+                : unknown
+            : unknown
+          : unknown
         : unknown
       : unknown
-    : unknown
+    : FromModels
   : unknown;
 
 /**
@@ -336,31 +581,33 @@ export type ComputeColumnJsType<
 /**
  * Extracts the inferred JsType carried by a ColumnBuilder.
  */
-type ExtractJsTypeFromColumnBuilder<CB extends AnyColumnBuilder> = CB extends ColumnBuilder<
-  infer _ColumnName extends string,
-  infer _ColumnMeta extends StorageColumn,
-  infer JsType,
-  infer _Ops
->
-  ? JsType
-  : never;
+type ExtractJsTypeFromColumnBuilder<CB extends AnyColumnBuilder> =
+  CB extends ColumnBuilder<
+    infer _ColumnName extends string,
+    infer _ColumnMeta extends StorageColumn,
+    infer JsType,
+    infer _Ops
+  >
+    ? JsType
+    : never;
 
 export type InferProjectionRow<P extends Record<string, AnyColumnBuilder>> = {
   [K in keyof P]: ExtractJsTypeFromColumnBuilder<P[K]>;
 };
 
 /**
- * Nested projection type - allows recursive nesting of ColumnBuilder or nested objects.
+ * Nested projection type - allows recursive nesting of ColumnBuilder, ExpressionBuilder, or nested objects.
  */
 export type NestedProjection = Record<
   string,
-  | AnyColumnBuilder
+  | AnyExpressionSource
   | Record<
       string,
-      | AnyColumnBuilder
+      | AnyExpressionSource
       | Record<
           string,
-          AnyColumnBuilder | Record<string, AnyColumnBuilder | Record<string, AnyColumnBuilder>>
+          | AnyExpressionSource
+          | Record<string, AnyExpressionSource | Record<string, AnyExpressionSource>>
         >
     >
 >;
@@ -383,17 +630,19 @@ type ExtractIncludeType<
  * by looking up the include alias in the Includes type map.
  */
 export type InferNestedProjectionRow<
-  P extends Record<string, AnyColumnBuilder | boolean | NestedProjection>,
+  P extends Record<string, AnyExpressionSource | boolean | NestedProjection>,
   CodecTypes extends Record<string, { readonly output: unknown }> = Record<string, never>,
   Includes extends Record<string, unknown> = Record<string, never>,
 > = {
-  [K in keyof P]: P[K] extends AnyColumnBuilder
-    ? ExtractJsTypeFromColumnBuilder<P[K]>
-    : P[K] extends true
-      ? Array<ExtractIncludeType<K & string, Includes>> // Include reference - infers Array<ChildShape> from Includes map
-      : P[K] extends NestedProjection
-        ? InferNestedProjectionRow<P[K], CodecTypes, Includes>
-        : never;
+  [K in keyof P]: P[K] extends ExpressionBuilder<infer JsType>
+    ? JsType
+    : P[K] extends AnyColumnBuilder
+      ? ExtractJsTypeFromColumnBuilder<P[K]>
+      : P[K] extends true
+        ? Array<ExtractIncludeType<K & string, Includes>> // Include reference - infers Array<ChildShape> from Includes map
+        : P[K] extends NestedProjection
+          ? InferNestedProjectionRow<P[K], CodecTypes, Includes>
+          : never;
 };
 
 /**
@@ -435,10 +684,10 @@ export type HasIncludeManyCapabilities<TContract extends SqlContract<SqlStorage>
     : false;
 
 /**
- * SQL-specific Plan type that refines the ast field to use QueryAst.
+ * SQL-specific Plan type that refines the ast field to use AnyQueryAst.
  * This is the type used by SQL query builders.
  */
-export type SqlPlan<Row = unknown> = ExecutionPlan<Row, QueryAst>;
+export type SqlPlan<Row = unknown> = ExecutionPlan<Row, AnyQueryAst>;
 
 /**
  * Helper types for extracting contract structure.
@@ -536,7 +785,7 @@ export interface BuildOptions {
 export interface SqlBuilderOptions<
   TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
 > {
-  readonly context: QueryLaneContext<TContract>;
+  readonly context: ExecutionContext<TContract>;
 }
 
 /**