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

package/src/sql/select-builder.ts

@@ -0,0 +1,434 @@
+import type { ParamDescriptor } from '@prisma-next/contract/types';
+import type { SqlContract, SqlStorage, StorageColumn } from '@prisma-next/sql-contract/types';
+import type {
+  ColumnRef,
+  Direction,
+  IncludeAst,
+  IncludeRef,
+  JoinAst,
+  OperationExpr,
+  TableRef,
+  WhereExpr,
+} from '@prisma-next/sql-relational-core/ast';
+import {
+  createJoinOnBuilder,
+  createOrderByItem,
+  createSelectAst,
+  createTableRef,
+} from '@prisma-next/sql-relational-core/ast';
+import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import type { ExecutionContext } from '@prisma-next/sql-relational-core/query-lane-context';
+import type {
+  AnyBinaryBuilder,
+  AnyOrderBuilder,
+  AnyUnaryBuilder,
+  BinaryBuilder,
+  BuildOptions,
+  InferNestedProjectionRow,
+  JoinOnBuilder,
+  JoinOnPredicate,
+  NestedProjection,
+  OrderBuilder,
+  SqlBuilderOptions,
+  UnaryBuilder,
+} from '@prisma-next/sql-relational-core/types';
+import { isExpressionBuilder } from '@prisma-next/sql-relational-core/utils/guards';
+import type { ProjectionInput } from '../types/internal';
+import { checkIncludeCapabilities } from '../utils/capabilities';
+import {
+  errorChildProjectionEmpty,
+  errorFromMustBeCalled,
+  errorIncludeAliasCollision,
+  errorLimitMustBeNonNegativeInteger,
+  errorMissingAlias,
+  errorSelectMustBeCalled,
+  errorSelfJoinNotSupported,
+  errorUnknownTable,
+} from '../utils/errors';
+import type { BuilderState, IncludeState, JoinState, ProjectionState } from '../utils/state';
+import {
+  buildIncludeAst,
+  type IncludeChildBuilder,
+  IncludeChildBuilderImpl,
+} from './include-builder';
+import { buildJoinAst } from './join-builder';
+import { buildMeta } from './plan';
+import { buildWhereExpr } from './predicate-builder';
+import { buildProjectionState } from './projection';
+
+export class SelectBuilderImpl<
+  TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
+  Row = unknown,
+  CodecTypes extends Record<string, { readonly output: unknown }> = Record<string, never>,
+  Includes extends Record<string, unknown> = Record<string, never>,
+> {
+  private readonly contract: TContract;
+  private readonly codecTypes: CodecTypes;
+  private readonly context: ExecutionContext<TContract>;
+  private state: BuilderState = {};
+
+  constructor(options: SqlBuilderOptions<TContract>, state?: BuilderState) {
+    this.context = options.context;
+    this.contract = options.context.contract;
+    this.codecTypes = options.context.contract.mappings.codecTypes as CodecTypes;
+    if (state) {
+      this.state = state;
+    }
+  }
+
+  from(table: TableRef): SelectBuilderImpl<TContract, unknown, CodecTypes, Record<string, never>> {
+    return new SelectBuilderImpl<TContract, unknown, CodecTypes, Record<string, never>>(
+      {
+        context: this.context,
+      },
+      { ...this.state, from: table },
+    );
+  }
+
+  innerJoin(
+    table: TableRef,
+    on: (on: JoinOnBuilder) => JoinOnPredicate,
+  ): SelectBuilderImpl<TContract, Row, CodecTypes, Includes> {
+    return this._addJoin('inner', table, on);
+  }
+
+  leftJoin(
+    table: TableRef,
+    on: (on: JoinOnBuilder) => JoinOnPredicate,
+  ): SelectBuilderImpl<TContract, Row, CodecTypes, Includes> {
+    return this._addJoin('left', table, on);
+  }
+
+  rightJoin(
+    table: TableRef,
+    on: (on: JoinOnBuilder) => JoinOnPredicate,
+  ): SelectBuilderImpl<TContract, Row, CodecTypes, Includes> {
+    return this._addJoin('right', table, on);
+  }
+
+  fullJoin(
+    table: TableRef,
+    on: (on: JoinOnBuilder) => JoinOnPredicate,
+  ): SelectBuilderImpl<TContract, Row, CodecTypes, Includes> {
+    return this._addJoin('full', table, on);
+  }
+
+  includeMany<
+    ChildProjection extends NestedProjection,
+    ChildRow = InferNestedProjectionRow<ChildProjection, CodecTypes>,
+    AliasName extends string = string,
+  >(
+    childTable: TableRef,
+    on: (on: JoinOnBuilder) => JoinOnPredicate,
+    childBuilder: (
+      child: IncludeChildBuilder<TContract, CodecTypes, unknown>,
+    ) => IncludeChildBuilder<TContract, CodecTypes, ChildRow>,
+    options?: { alias?: AliasName },
+  ): SelectBuilderImpl<TContract, Row, CodecTypes, Includes & { [K in AliasName]: ChildRow }> {
+    checkIncludeCapabilities(this.contract);
+
+    if (!this.contract.storage.tables[childTable.name]) {
+      errorUnknownTable(childTable.name);
+    }
+
+    const joinOnBuilder = createJoinOnBuilder();
+    const onPredicate = on(joinOnBuilder);
+
+    // Validate ON uses column equality
+    // TypeScript can't narrow ColumnBuilder properly, so we assert
+    const onLeft = onPredicate.left as { table: string; column: string };
+    const onRight = onPredicate.right as { table: string; column: string };
+    if (onLeft.table === onRight.table) {
+      errorSelfJoinNotSupported();
+    }
+
+    // Build child builder
+    const childBuilderImpl = new IncludeChildBuilderImpl<TContract, CodecTypes, unknown>(
+      this.contract,
+      this.codecTypes,
+      childTable,
+    );
+    const builtChild = childBuilder(
+      childBuilderImpl as IncludeChildBuilder<TContract, CodecTypes, unknown>,
+    );
+    const childState = (
+      builtChild as IncludeChildBuilderImpl<TContract, CodecTypes, ChildRow>
+    ).getState();
+
+    // Validate child projection is non-empty
+    if (childState.childProjection.aliases.length === 0) {
+      errorChildProjectionEmpty();
+    }
+
+    // Determine alias
+    const alias = options?.alias ?? childTable.name;
+
+    // Check for alias collisions with existing projection
+    if (this.state.projection) {
+      if (this.state.projection.aliases.includes(alias)) {
+        errorIncludeAliasCollision(alias, 'projection');
+      }
+    }
+
+    // Check for alias collisions with existing includes
+    const existingIncludes = this.state.includes ?? [];
+    if (existingIncludes.some((inc) => inc.alias === alias)) {
+      errorIncludeAliasCollision(alias, 'include');
+    }
+
+    const includeState: IncludeState = {
+      alias,
+      table: childTable,
+      on: onPredicate,
+      childProjection: childState.childProjection,
+      ...(childState.childWhere !== undefined ? { childWhere: childState.childWhere } : {}),
+      ...(childState.childOrderBy !== undefined ? { childOrderBy: childState.childOrderBy } : {}),
+      ...(childState.childLimit !== undefined ? { childLimit: childState.childLimit } : {}),
+    };
+
+    const newIncludes = [...existingIncludes, includeState];
+
+    // Type-level: Update Includes map with new include
+    // The AliasName generic parameter is inferred from options.alias, allowing TypeScript
+    // to track include definitions across multiple includeMany() calls and infer correct
+    // array types when select() includes boolean true for include references
+    type NewIncludes = Includes & { [K in AliasName]: ChildRow };
+
+    return new SelectBuilderImpl<TContract, Row, CodecTypes, NewIncludes>(
+      {
+        context: this.context,
+      },
+      { ...this.state, includes: newIncludes },
+    );
+  }
+
+  private _addJoin(
+    joinType: 'inner' | 'left' | 'right' | 'full',
+    table: TableRef,
+    on: (on: JoinOnBuilder) => JoinOnPredicate,
+  ): SelectBuilderImpl<TContract, Row, CodecTypes, Includes> {
+    const fromTable = this.ensureFrom();
+
+    if (!this.contract.storage.tables[table.name]) {
+      errorUnknownTable(table.name);
+    }
+
+    if (table.name === fromTable.name) {
+      errorSelfJoinNotSupported();
+    }
+
+    const joinOnBuilder = createJoinOnBuilder();
+    const onPredicate = on(joinOnBuilder);
+
+    const joinState: JoinState = {
+      joinType,
+      table,
+      on: onPredicate,
+    };
+
+    const existingJoins = this.state.joins ?? [];
+    const newJoins = [...existingJoins, joinState];
+
+    return new SelectBuilderImpl<TContract, Row, CodecTypes, Includes>(
+      {
+        context: this.context,
+      },
+      { ...this.state, joins: newJoins },
+    );
+  }
+
+  where(
+    expr: AnyBinaryBuilder | AnyUnaryBuilder,
+  ): SelectBuilderImpl<TContract, Row, CodecTypes, Includes> {
+    return new SelectBuilderImpl<TContract, Row, CodecTypes, Includes>(
+      {
+        context: this.context,
+      },
+      { ...this.state, where: expr },
+    );
+  }
+
+  select<P extends ProjectionInput>(
+    projection: P,
+  ): SelectBuilderImpl<
+    TContract,
+    InferNestedProjectionRow<P, CodecTypes, Includes>,
+    CodecTypes,
+    Includes
+  > {
+    const table = this.ensureFrom();
+    const projectionState = buildProjectionState(table, projection, this.state.includes);
+
+    return new SelectBuilderImpl<
+      TContract,
+      InferNestedProjectionRow<P, CodecTypes, Includes>,
+      CodecTypes,
+      Includes
+    >(
+      {
+        context: this.context,
+      },
+      { ...this.state, projection: projectionState },
+    );
+  }
+
+  orderBy(order: AnyOrderBuilder): SelectBuilderImpl<TContract, Row, CodecTypes, Includes> {
+    return new SelectBuilderImpl<TContract, Row, CodecTypes, Includes>(
+      {
+        context: this.context,
+      },
+      { ...this.state, orderBy: order },
+    );
+  }
+
+  limit(count: number): SelectBuilderImpl<TContract, Row, CodecTypes, Includes> {
+    if (!Number.isInteger(count) || count < 0) {
+      errorLimitMustBeNonNegativeInteger();
+    }
+
+    return new SelectBuilderImpl<TContract, Row, CodecTypes, Includes>(
+      {
+        context: this.context,
+      },
+      { ...this.state, limit: count },
+    );
+  }
+
+  build(options?: BuildOptions): SqlQueryPlan<Row> {
+    const table = this.ensureFrom();
+    const projection = this.ensureProjection();
+
+    const paramsMap = (options?.params ?? {}) as Record<string, unknown>;
+    const contractTable = this.contract.storage.tables[table.name];
+
+    if (!contractTable) {
+      errorUnknownTable(table.name);
+    }
+
+    const paramDescriptors: ParamDescriptor[] = [];
+    const paramValues: unknown[] = [];
+    const paramCodecs: Record<string, string> = {};
+
+    const whereResult = this.state.where
+      ? buildWhereExpr(this.contract, this.state.where, paramsMap, paramDescriptors, paramValues)
+      : undefined;
+    const whereExpr = whereResult?.expr;
+
+    if (whereResult?.codecId && whereResult.paramName) {
+      paramCodecs[whereResult.paramName] = whereResult.codecId;
+    }
+
+    const orderByClause = this.state.orderBy
+      ? (() => {
+          const orderBy = this.state.orderBy as OrderBuilder<string, StorageColumn, unknown>;
+          // orderBy.expr is already an Expression (ColumnRef or OperationExpr)
+          return [createOrderByItem(orderBy.expr, orderBy.dir)];
+        })()
+      : undefined;
+
+    const joins = this.state.joins?.map((join) => buildJoinAst(join));
+
+    const includes = this.state.includes?.map((include) =>
+      buildIncludeAst(include, this.contract, paramsMap, paramDescriptors, paramValues),
+    );
+
+    // Build projection with support for includeRef and OperationExpr
+    const projectEntries: Array<{ alias: string; expr: ColumnRef | IncludeRef | OperationExpr }> =
+      [];
+    for (let i = 0; i < projection.aliases.length; i++) {
+      const alias = projection.aliases[i];
+      if (!alias) {
+        errorMissingAlias(i);
+      }
+      const column = projection.columns[i];
+
+      // Check if this alias matches an include alias first
+      // Include placeholders have null columns
+      const matchingInclude = this.state.includes?.find((inc) => inc.alias === alias);
+      if (matchingInclude) {
+        // This is an include reference - column can be null for placeholders
+        projectEntries.push({
+          alias,
+          expr: { kind: 'includeRef', alias },
+        });
+      } else if (column && isExpressionBuilder(column)) {
+        // This is an ExpressionBuilder (operation result) - use its expr
+        projectEntries.push({
+          alias,
+          expr: column.expr,
+        });
+      } else if (column) {
+        // This is a regular ColumnBuilder - use toExpr() to get ColumnRef
+        const columnRef = column.toExpr();
+        projectEntries.push({
+          alias,
+          expr: columnRef,
+        });
+      }
+    }
+
+    const ast = createSelectAst({
+      from: createTableRef(table.name),
+      joins,
+      includes,
+      project: projectEntries,
+      where: whereExpr,
+      orderBy: orderByClause,
+      limit: this.state.limit,
+    } as {
+      from: TableRef;
+      joins?: ReadonlyArray<JoinAst>;
+      includes?: ReadonlyArray<IncludeAst>;
+      project: ReadonlyArray<{ alias: string; expr: ColumnRef | IncludeRef | OperationExpr }>;
+      where?: WhereExpr;
+      orderBy?: ReadonlyArray<{ expr: ColumnRef | OperationExpr; dir: Direction }>;
+      limit?: number;
+    });
+
+    const planMeta = buildMeta({
+      contract: this.contract,
+      table,
+      projection,
+      joins: this.state.joins,
+      includes: this.state.includes,
+      paramDescriptors,
+      paramCodecs,
+      where: this.state.where,
+      orderBy: this.state.orderBy,
+    } as {
+      contract: SqlContract<SqlStorage>;
+      table: TableRef;
+      projection: ProjectionState;
+      joins?: ReadonlyArray<JoinState>;
+      includes?: ReadonlyArray<IncludeState>;
+      where?: BinaryBuilder | UnaryBuilder;
+      orderBy?: AnyOrderBuilder;
+      paramDescriptors: ParamDescriptor[];
+      paramCodecs?: Record<string, string>;
+    });
+
+    const queryPlan: SqlQueryPlan<Row> = Object.freeze({
+      ast,
+      params: paramValues,
+      meta: planMeta,
+    });
+
+    return queryPlan;
+  }
+
+  private ensureFrom() {
+    if (!this.state.from) {
+      errorFromMustBeCalled();
+    }
+
+    return this.state.from;
+  }
+
+  private ensureProjection() {
+    if (!this.state.projection) {
+      errorSelectMustBeCalled();
+    }
+
+    return this.state.projection;
+  }
+}

package/src/types/internal.ts

@@ -0,0 +1,42 @@
+import type { ParamDescriptor } from '@prisma-next/contract/types';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { TableRef } from '@prisma-next/sql-relational-core/ast';
+import type {
+  AnyBinaryBuilder,
+  AnyExpressionSource,
+  AnyOrderBuilder,
+  AnyUnaryBuilder,
+  NestedProjection,
+} from '@prisma-next/sql-relational-core/types';
+import type { ProjectionState } from '../utils/state';
+
+export type ProjectionInput = Record<string, AnyExpressionSource | boolean | NestedProjection>;
+
+export interface MetaBuildArgs {
+  readonly contract: SqlContract<SqlStorage>;
+  readonly table: TableRef;
+  readonly projection: ProjectionState;
+  readonly joins?: ReadonlyArray<{
+    readonly joinType: 'inner' | 'left' | 'right' | 'full';
+    readonly table: TableRef;
+    readonly on: {
+      readonly left: unknown;
+      readonly right: unknown;
+    };
+  }>;
+  readonly includes?: ReadonlyArray<{
+    readonly alias: string;
+    readonly table: TableRef;
+    readonly on: {
+      readonly left: unknown;
+      readonly right: unknown;
+    };
+    readonly childProjection: ProjectionState;
+    readonly childWhere?: AnyBinaryBuilder | AnyUnaryBuilder;
+    readonly childOrderBy?: AnyOrderBuilder;
+  }>;
+  readonly where?: AnyBinaryBuilder | AnyUnaryBuilder;
+  readonly orderBy?: AnyOrderBuilder;
+  readonly paramDescriptors: ParamDescriptor[];
+  readonly paramCodecs?: Record<string, string>;
+}

package/src/types/public.ts

@@ -0,0 +1,36 @@
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { TableRef } from '@prisma-next/sql-relational-core/ast';
+import type { ParamPlaceholder, RawFactory } from '@prisma-next/sql-relational-core/types';
+import type { DeleteBuilder, InsertBuilder, UpdateBuilder } from '../sql/mutation-builder';
+import type { SelectBuilderImpl } from '../sql/select-builder';
+
+export type { TableRef } from '@prisma-next/sql-relational-core/ast';
+export type {
+  AnyColumnBuilder,
+  BuildOptions,
+  InferReturningRow,
+  ParamPlaceholder,
+  RawFactory,
+  SqlBuilderOptions,
+} from '@prisma-next/sql-relational-core/types';
+
+export type SelectBuilder<
+  TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
+  Row = unknown,
+  CodecTypes extends Record<string, { readonly output: unknown }> = Record<string, never>,
+  Includes extends Record<string, unknown> = Record<string, never>,
+> = SelectBuilderImpl<TContract, Row, CodecTypes, Includes> & {
+  readonly raw: RawFactory;
+  insert(
+    table: TableRef,
+    values: Record<string, ParamPlaceholder>,
+  ): InsertBuilder<TContract, CodecTypes>;
+  update(
+    table: TableRef,
+    set: Record<string, ParamPlaceholder>,
+  ): UpdateBuilder<TContract, CodecTypes>;
+  delete(table: TableRef): DeleteBuilder<TContract, CodecTypes>;
+};
+
+export type { IncludeChildBuilder } from '../sql/include-builder';
+export type { DeleteBuilder, InsertBuilder, UpdateBuilder } from '../sql/mutation-builder';

package/src/utils/assertions.ts

@@ -0,0 +1,34 @@
+import { planInvalid } from '@prisma-next/plan';
+import type { AnyColumnBuilder } from '@prisma-next/sql-relational-core/types';
+
+/**
+ * Asserts that a ColumnBuilder has table and column properties.
+ */
+export function assertColumnBuilder(col: unknown, context: string): AnyColumnBuilder {
+  if (
+    typeof col === 'object' &&
+    col !== null &&
+    'table' in col &&
+    'column' in col &&
+    typeof (col as { table: unknown }).table === 'string' &&
+    typeof (col as { column: unknown }).column === 'string'
+  ) {
+    return col as AnyColumnBuilder;
+  }
+  throw planInvalid(`ColumnBuilder missing table/column in ${context}`);
+}
+
+/**
+ * Asserts that a JoinOnPredicate has valid left and right columns.
+ */
+export function assertJoinOnPredicate(on: {
+  left?: { table?: string; column?: string };
+  right?: { table?: string; column?: string };
+}): asserts on is {
+  left: { table: string; column: string };
+  right: { table: string; column: string };
+} {
+  if (!on.left?.table || !on.left?.column || !on.right?.table || !on.right?.column) {
+    throw planInvalid('JoinOnPredicate missing required table/column properties');
+  }
+}

package/src/utils/capabilities.ts

@@ -0,0 +1,39 @@
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import {
+  errorIncludeCapabilitiesNotTrue,
+  errorIncludeRequiresCapabilities,
+  errorReturningCapabilityNotTrue,
+  errorReturningRequiresCapability,
+} from './errors';
+
+export function checkIncludeCapabilities(contract: SqlContract<SqlStorage>): void {
+  const target = contract.target;
+  const contractCapabilities = contract.capabilities;
+  const declaredTargetCapabilities = contractCapabilities?.[target];
+
+  if (!contractCapabilities || !declaredTargetCapabilities) {
+    errorIncludeRequiresCapabilities(target);
+  }
+
+  if (
+    declaredTargetCapabilities['lateral'] !== true ||
+    declaredTargetCapabilities['jsonAgg'] !== true
+  ) {
+    errorIncludeCapabilitiesNotTrue(target, {
+      lateral: declaredTargetCapabilities['lateral'],
+      jsonAgg: declaredTargetCapabilities['jsonAgg'],
+    });
+  }
+}
+
+export function checkReturningCapability(contract: SqlContract<SqlStorage>): void {
+  const target = contract.target;
+  const capabilities = contract.capabilities;
+  if (!capabilities || !capabilities[target]) {
+    errorReturningRequiresCapability(target);
+  }
+  const targetCapabilities = capabilities[target];
+  if (targetCapabilities['returning'] !== true) {
+    errorReturningCapabilityNotTrue(target, targetCapabilities['returning']);
+  }
+}