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

package/src/exports/ast.ts

@@ -1,13 +1,7 @@
 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/sql-codecs';
 export * from '../ast/types';
-export * from '../ast/update';
 export * from '../ast/util';

package/src/exports/guards.ts

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

package/src/exports/query-operations.ts

@@ -0,0 +1 @@
+export * from '../query-operation-registry';

package/src/exports/utils/guards.ts

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

package/src/operations-registry.ts

@@ -3,59 +3,69 @@ 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';
+import {
+  type AnyOperationArg,
+  type BinaryOp,
+  type ExpressionSource,
+  LiteralExpr,
+  OperationExpr,
+  ParamRef,
+} from './ast/types';
+import type {
+  AnyBinaryBuilder,
+  AnyOrderBuilder,
+  ColumnBuilder,
+  ExpressionBuilder,
+  OperationTypes,
+  ValueSource,
+} from './types';
 
-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> = [];
+  const selfExpr = selfBuilder.toExpr();
+
+  const operationArgs: AnyOperationArg[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     const argSpec = signature.args[i];
@@ -64,51 +74,29 @@ function executeOperation(
     }
 
     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,
-      });
+      operationArgs.push(ParamRef.of(arg, { name: `arg_${i}`, codecId: columnMeta.codecId }));
     } 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',
-        value: arg,
-      });
+      operationArgs.push(new LiteralExpr(arg));
     }
   }
 
-  const operationExpr: OperationExpr = {
-    kind: 'operation',
+  const operationExpr = new OperationExpr({
     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
@@ -118,18 +106,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: ValueSource): 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 +128,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 +250,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/plan.ts

@@ -1,6 +1,6 @@
 import type { ExecutionPlan, ParamDescriptor } from '@prisma-next/contract/types';
 import type { StorageColumn } from '@prisma-next/sql-contract/types';
-import type { QueryAst } from './ast/types';
+import type { AnyQueryAst } from './ast/types';
 
 /**
  * SQL query plan produced by lanes before lowering.
@@ -8,13 +8,13 @@ import type { QueryAst } from './ast/types';
  * 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
+ * Structurally aligns with ExecutionPlan<Row, AnyQueryAst> (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;
+  extends Pick<ExecutionPlan<_Row, AnyQueryAst>, 'params' | 'meta'> {
+  readonly ast: AnyQueryAst;
   // Phantom property to preserve generic parameter for type extraction
   // This allows ResultType to extract _Row for SqlQueryPlan values.
   readonly _Row?: _Row;

package/src/query-lane-context.ts

@@ -1,6 +1,68 @@
 import type { OperationRegistry } from '@prisma-next/operations';
 import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
 import type { CodecRegistry } from './ast/codec-types';
+import type { QueryOperationRegistry } from './query-operation-registry';
+
+/**
+ * Registry of initialized type helpers from storage.types.
+ * Each key is a type name from storage.types, and the value is:
+ * - The result of the codec's init hook (if provided), or
+ * - The full StorageTypeInstance metadata (codecId, nativeType, typeParams) if no init hook
+ */
+export type TypeHelperRegistry = Record<string, unknown>;
+
+// =============================================================================
+// JSON Schema Validation Types
+// =============================================================================
+
+/**
+ * A single validation error from JSON Schema validation.
+ */
+export interface JsonSchemaValidationError {
+  readonly path: string;
+  readonly message: string;
+  readonly keyword: string;
+}
+
+/**
+ * Result of a JSON Schema validation.
+ */
+export type JsonSchemaValidationResult =
+  | { readonly valid: true }
+  | { readonly valid: false; readonly errors: ReadonlyArray<JsonSchemaValidationError> };
+
+/**
+ * A compiled JSON Schema validate function.
+ * Returns a structured result indicating whether the value conforms to the schema.
+ */
+export type JsonSchemaValidateFn = (value: unknown) => JsonSchemaValidationResult;
+
+/**
+ * Registry of compiled JSON Schema validators for columns with typed JSON/JSONB.
+ *
+ * Built during context creation by scanning the contract for columns whose codec
+ * descriptor provides an `init` hook that returns a `{ validate }` helper.
+ * Keys are `"table.column"` (e.g., `"user.metadata"`).
+ */
+export interface JsonSchemaValidatorRegistry {
+  /** Get the compiled validator for a column. Key format: "table.column". */
+  get(key: string): JsonSchemaValidateFn | undefined;
+  /** Number of registered validators. */
+  readonly size: number;
+}
+
+export type MutationDefaultsOp = 'create' | 'update';
+
+export type AppliedMutationDefault = {
+  readonly column: string;
+  readonly value: unknown;
+};
+
+export type MutationDefaultsOptions = {
+  readonly op: MutationDefaultsOp;
+  readonly table: string;
+  readonly values: Record<string, unknown>;
+};
 
 /**
  * Minimal context interface for SQL query lanes.
@@ -9,10 +71,26 @@ import type { CodecRegistry } from './ast/codec-types';
  * operation builders. This interface explicitly excludes runtime concerns like
  * adapters, connection management, and transaction state.
  */
-export interface QueryLaneContext<
+export interface ExecutionContext<
   TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
 > {
   readonly contract: TContract;
   readonly operations: OperationRegistry;
   readonly codecs: CodecRegistry;
+  readonly queryOperations: QueryOperationRegistry;
+  /**
+   * Type helper registry for parameterized types.
+   * Schema builders expose these helpers via schema.types.
+   */
+  readonly types: TypeHelperRegistry;
+  /**
+   * Compiled JSON Schema validators for typed JSON/JSONB columns.
+   * Present only when the contract declares columns with JSON Schema typeParams.
+   */
+  readonly jsonSchemaValidators?: JsonSchemaValidatorRegistry;
+  /**
+   * Applies execution-time mutation defaults for the given table.
+   * Returns the applied defaults (caller-provided values always win).
+   */
+  applyMutationDefaults(options: MutationDefaultsOptions): ReadonlyArray<AppliedMutationDefault>;
 }

package/src/query-operation-registry.ts

@@ -0,0 +1,35 @@
+export interface QueryOperationEntry {
+  readonly args: readonly { readonly codecId: string; readonly nullable: boolean }[];
+  readonly returns: { readonly codecId: string; readonly nullable: boolean };
+  readonly lowering: {
+    readonly targetFamily: 'sql';
+    readonly strategy: 'infix' | 'function';
+    readonly template: string;
+  };
+}
+
+export interface QueryOperationDescriptor extends QueryOperationEntry {
+  readonly method: string;
+}
+
+export interface QueryOperationRegistry {
+  register(descriptor: QueryOperationDescriptor): void;
+  entries(): Readonly<Record<string, QueryOperationEntry>>;
+}
+
+export function createQueryOperationRegistry(): QueryOperationRegistry {
+  const map = new Map<string, QueryOperationEntry>();
+
+  return {
+    register(descriptor) {
+      if (map.has(descriptor.method)) {
+        throw new Error(`Query operation "${descriptor.method}" is already registered`);
+      }
+      const { method: _, ...entry } = descriptor;
+      map.set(descriptor.method, entry);
+    },
+    entries() {
+      return Object.freeze(Object.fromEntries(map));
+    },
+  };
+}