@prisma-next/sql-relational-core 0.3.0-dev.6 → 0.3.0-dev.63

package/src/ast/update.ts

@@ -1,10 +1,10 @@
-import type { BinaryExpr, ColumnRef, ParamRef, TableRef, UpdateAst } from './types';
+import type { ColumnRef, ParamRef, TableRef, UpdateAst, WhereExpr } from './types';
 import { compact } from './util';
 
 export interface CreateUpdateAstOptions {
   readonly table: TableRef;
   readonly set: Record<string, ColumnRef | ParamRef>;
-  readonly where: BinaryExpr;
+  readonly where?: WhereExpr;
   readonly returning?: ReadonlyArray<ColumnRef>;
 }
 

package/src/exports/ast.ts

@@ -8,6 +8,7 @@ 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,15 @@
 export {
   collectColumnRefs,
+  expressionFromSource,
   extractBaseColumnRef,
   getColumnInfo,
   getColumnMeta,
   getOperationExpr,
   isColumnBuilder,
+  isExpressionBuilder,
+  isExpressionSource,
   isOperationExpr,
   isParamPlaceholder,
+  isValueSource,
+  toExpression,
 } from '../utils/guards';

package/src/exports/utils/guards.ts

@@ -0,0 +1 @@
+export * from '../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/query-lane-context.ts

@@ -2,6 +2,67 @@ 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 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 +70,25 @@ 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;
+  /**
+   * 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/schema.ts

@@ -7,21 +7,20 @@ 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 { ExecutionContext } from './query-lane-context';
 import type {
-  AnyColumnBuilderBase,
   BinaryBuilder,
   CodecTypes as CodecTypesType,
   ColumnBuilder,
   ComputeColumnJsType,
+  NullCheckBuilder,
   OperationTypeSignature,
   OperationTypes,
   OrderBuilder,
   ParamPlaceholder,
 } from './types';
-import { isColumnBuilder } from './types';
 
 type TableColumns<Table extends { columns: Record<string, StorageColumn> }> = Table['columns'];
 
@@ -44,7 +43,8 @@ export class ColumnBuilderImpl<
   ColumnName extends string,
   ColumnMeta extends StorageColumn,
   JsType = unknown,
-> {
+> implements ExpressionSource
+{
   readonly kind = 'column' as const;
 
   constructor(
@@ -62,64 +62,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',
+      );
+    }
+    // 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.toExpr(),
+        right: value,
+      }) as BinaryBuilder<ColumnName, ColumnMeta, JsType>;
     }
-    if (value.kind === 'param-placeholder' || isColumnBuilder(value)) {
+    // Must be a ParamPlaceholder
+    if ('kind' in value && value.kind === 'param-placeholder') {
       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');
+    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,10 +139,34 @@ 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>;
   }
+
+  /**
+   * Creates an IS NULL check for this column.
+   * Available on all columns at runtime, but typed to only be visible on nullable columns.
+   */
+  isNull(): NullCheckBuilder<ColumnName, ColumnMeta, JsType> {
+    return Object.freeze({
+      kind: 'nullCheck' as const,
+      expr: this.toExpr(),
+      isNull: true,
+    }) as NullCheckBuilder<ColumnName, ColumnMeta, JsType>;
+  }
+
+  /**
+   * Creates an IS NOT NULL check for this column.
+   * Available on all columns at runtime, but typed to only be visible on nullable columns.
+   */
+  isNotNull(): NullCheckBuilder<ColumnName, ColumnMeta, JsType> {
+    return Object.freeze({
+      kind: 'nullCheck' as const,
+      expr: this.toExpr(),
+      isNull: false,
+    }) as NullCheckBuilder<ColumnName, ColumnMeta, JsType>;
+  }
 }
 
 export class TableBuilderImpl<
@@ -290,12 +326,30 @@ type ExtractSchemaTables<
     TableRef;
 };
 
+/**
+ * Extracts the types registry shape from a contract.
+ * Each key is a type name from storage.types, and the value preserves the
+ * literal type from the contract (including codecId, nativeType, and typeParams).
+ * Returns an empty object type {} when storage.types is undefined.
+ */
+type ExtractSchemaTypes<Contract extends SqlContract<SqlStorage>> =
+  Contract['storage']['types'] extends infer Types
+    ? Types extends Record<string, unknown>
+      ? { readonly [TypeName in keyof Types]: Types[TypeName] }
+      : Record<string, never>
+    : Record<string, never>;
+
 export type SchemaHandle<
   Contract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
   CodecTypes extends CodecTypesType = CodecTypesType,
   Operations extends OperationTypes = Record<string, never>,
 > = {
   readonly tables: ExtractSchemaTables<Contract, CodecTypes, Operations>;
+  /**
+   * Initialized type helpers from storage.types.
+   * Each entry corresponds to a named type instance in the contract's storage.types.
+   */
+  readonly types: ExtractSchemaTypes<Contract>;
 };
 
 type SchemaReturnType<Contract extends SqlContract<SqlStorage>> = SchemaHandle<
@@ -318,16 +372,17 @@ type ToOperationTypes<T> = T extends OperationTypes ? T : NormalizeOperationType
  * Creates a schema handle for building SQL queries.
  *
  * @param context - Query lane context containing contract, codec and operation registries
- * @returns A schema handle with typed table builders
+ * @returns A schema handle with typed table builders and type helpers
  *
  * @example
  * ```typescript
  * const schemaHandle = schema<Contract>(context);
  * const userTable = schemaHandle.tables.user;
+ * const vectorType = schemaHandle.types.Vector1536;
  * ```
  */
 export function schema<Contract extends SqlContract<SqlStorage>>(
-  context: QueryLaneContext<Contract>,
+  context: ExecutionContext<Contract>,
 ): SchemaReturnType<Contract> {
   const contract = context.contract;
   const storage = contract.storage;
@@ -367,7 +422,10 @@ export function schema<Contract extends SqlContract<SqlStorage>>(
     ) as ExtractSchemaTables<Contract, CodecTypes, Operations>[typeof tableName];
   }
 
-  return Object.freeze({ tables }) as SchemaReturnType<Contract>;
+  // Get type helpers from context (populated by runtime context creation)
+  const types = context.types as ExtractSchemaTypes<Contract>;
+
+  return Object.freeze({ tables, types }) as SchemaReturnType<Contract>;
 }
 
 export type { ColumnBuilderImpl as Column, TableBuilderImpl as Table };