@prisma-next/sql-relational-core 0.3.0-dev.4 → 0.3.0-dev.41

package/src/ast/sql-codecs.ts

@@ -0,0 +1,67 @@
+import { type as arktype } from 'arktype';
+import { codec, defineCodecs } from './codec-types';
+
+export const SQL_CHAR_CODEC_ID = 'sql/char@1' as const;
+export const SQL_VARCHAR_CODEC_ID = 'sql/varchar@1' as const;
+export const SQL_INT_CODEC_ID = 'sql/int@1' as const;
+export const SQL_FLOAT_CODEC_ID = 'sql/float@1' as const;
+
+const lengthParamsSchema = arktype({
+  length: 'number.integer > 0',
+});
+
+type LengthTypeHelper = {
+  readonly kind: 'fixed' | 'variable';
+  readonly maxLength: number;
+};
+
+function createLengthTypeHelper(
+  kind: LengthTypeHelper['kind'],
+): (params: Record<string, unknown>) => LengthTypeHelper {
+  return (params) => ({
+    kind,
+    maxLength: params['length'] as number,
+  });
+}
+
+const sqlCharCodec = codec<typeof SQL_CHAR_CODEC_ID, string, string>({
+  typeId: SQL_CHAR_CODEC_ID,
+  targetTypes: ['char'],
+  encode: (value: string): string => value,
+  decode: (wire: string): string => wire.trimEnd(),
+  paramsSchema: lengthParamsSchema,
+  init: createLengthTypeHelper('fixed'),
+});
+
+const sqlVarcharCodec = codec<typeof SQL_VARCHAR_CODEC_ID, string, string>({
+  typeId: SQL_VARCHAR_CODEC_ID,
+  targetTypes: ['varchar'],
+  encode: (value: string): string => value,
+  decode: (wire: string): string => wire,
+  paramsSchema: lengthParamsSchema,
+  init: createLengthTypeHelper('variable'),
+});
+
+const sqlIntCodec = codec<typeof SQL_INT_CODEC_ID, number, number>({
+  typeId: SQL_INT_CODEC_ID,
+  targetTypes: ['int'],
+  encode: (value) => value,
+  decode: (wire) => wire,
+});
+
+const sqlFloatCodec = codec<typeof SQL_FLOAT_CODEC_ID, number, number>({
+  typeId: SQL_FLOAT_CODEC_ID,
+  targetTypes: ['float'],
+  encode: (value) => value,
+  decode: (wire) => wire,
+});
+
+const codecs = defineCodecs()
+  .add('char', sqlCharCodec)
+  .add('varchar', sqlVarcharCodec)
+  .add('int', sqlIntCodec)
+  .add('float', sqlFloatCodec);
+
+export const sqlCodecDefinitions = codecs.codecDefinitions;
+export const sqlDataTypes = codecs.dataTypes;
+export type SqlCodecTypes = typeof codecs.CodecTypes;

package/src/ast/types.ts

@@ -0,0 +1,187 @@
+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'
+  | 'like'
+  | 'ilike'
+  | 'in'
+  | 'notIn';
+
+export interface ListLiteralExpr {
+  readonly kind: 'listLiteral';
+  readonly values: ReadonlyArray<ParamRef | LiteralExpr>;
+}
+
+export interface BinaryExpr {
+  readonly kind: 'bin';
+  readonly op: BinaryOp;
+  readonly left: Expression;
+  readonly right: Expression | ParamRef | LiteralExpr | ListLiteralExpr;
+}
+
+export interface ExistsExpr {
+  readonly kind: 'exists';
+  readonly not: boolean;
+  readonly subquery: SelectAst;
+}
+
+/**
+ * Unary expression for IS NULL / IS NOT NULL checks.
+ * Used in WHERE clauses to check for null values.
+ */
+export interface NullCheckExpr {
+  readonly kind: 'nullCheck';
+  readonly expr: Expression;
+  readonly isNull: boolean;
+}
+
+export interface AndExpr {
+  readonly kind: 'and';
+  readonly exprs: ReadonlyArray<WhereExpr>;
+}
+
+export interface OrExpr {
+  readonly kind: 'or';
+  readonly exprs: ReadonlyArray<WhereExpr>;
+}
+
+/**
+ * Union type for WHERE clause expressions.
+ */
+export type WhereExpr = BinaryExpr | ExistsExpr | NullCheckExpr | AndExpr | OrExpr;
+
+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?: WhereExpr;
+    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?: WhereExpr;
+  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: WhereExpr;
+  readonly returning?: ReadonlyArray<ColumnRef>;
+}
+
+export interface DeleteAst {
+  readonly kind: 'delete';
+  readonly table: TableRef;
+  readonly where: WhereExpr;
+  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 { 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: WhereExpr;
+  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/exports/ast.ts

@@ -0,0 +1,14 @@
+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/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/exports/utils/guards.ts

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

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,
+    };
+  }
+}