@prisma-next/sql-builder 0.0.1

package/README.md

@@ -0,0 +1,68 @@
+# @prisma-next/sql-builder
+
+Type-safe SQL query builder for Prisma Next with runtime execution.
+
+## Usage
+
+```typescript
+import { sql } from '@prisma-next/sql-builder/runtime';
+
+const db = sql({ context, runtime });
+
+// SELECT with WHERE
+const user = await db.users
+  .select('id', 'email')
+  .where((f, fns) => fns.eq(f.id, 1))
+  .first();
+
+// Aliased expression select
+const rows = await db.users
+  .select('id')
+  .select('userName', (f) => f.name)
+  .all();
+
+// JOIN
+const rows = await db.users
+  .innerJoin(db.posts, (f, fns) => fns.eq(f.users.id, f.posts.user_id))
+  .select('name', 'title')
+  .all();
+
+// Self-join via .as()
+const rows = await db.users
+  .as('invitee')
+  .innerJoin(db.users.as('inviter'), (f, fns) =>
+    fns.eq(f.invitee.invited_by_id, f.inviter.id),
+  )
+  .select('name')
+  .all();
+
+// Subquery as join source
+const sub = db.posts.select('user_id', 'title').as('sub');
+const rows = await db.users
+  .innerJoin(sub, (f, fns) => fns.eq(f.users.id, f.sub.user_id))
+  .select('name', 'title')
+  .all();
+
+// GROUP BY with aggregate
+const counts = await db.posts
+  .select('user_id')
+  .select('cnt', (_f, fns) => fns.count())
+  .groupBy('user_id')
+  .having((_f, fns) => fns.gt(fns.count(), 1))
+  .all();
+```
+
+## Dependencies
+
+- `@prisma-next/sql-relational-core` — AST nodes, execution context, query operation registry
+- `@prisma-next/sql-runtime` — Runtime type for query execution
+
+## Architecture
+
+- **Domain:** SQL
+- **Layer:** Lanes
+- **Plane:** Runtime
+
+## Status
+
+See [STATUS.md](./STATUS.md) for covered clauses and known gaps.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@prisma-next/sql-builder",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "SQL builder lane for Prisma Next",
+  "scripts": {
+    "build": "tsdown",
+    "preemit": "pnpm --filter @prisma-next/cli... build",
+    "emit": "node ../../../1-framework/3-tooling/cli/dist/cli.js contract emit --config test/fixtures/prisma-next.config.ts",
+    "emit:check": "pnpm emit && git diff --exit-code test/fixtures/generated/",
+    "test": "vitest run --passWithNoTests",
+    "~test:coverage": "vitest run --coverage --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  },
+  "dependencies": {
+    "@prisma-next/sql-relational-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@prisma-next/adapter-postgres": "workspace:*",
+    "@prisma-next/cli": "workspace:*",
+    "@prisma-next/contract": "workspace:*",
+    "@prisma-next/core-execution-plane": "workspace:*",
+    "@prisma-next/driver-postgres": "workspace:*",
+    "@prisma-next/extension-pgvector": "workspace:*",
+    "@prisma-next/family-sql": "workspace:*",
+    "@prisma-next/ids": "^0.0.1",
+    "@prisma-next/sql-contract": "workspace:*",
+    "@prisma-next/sql-runtime": "workspace:*",
+    "@prisma-next/sql-contract-ts": "workspace:*",
+    "@prisma-next/target-postgres": "workspace:*",
+    "@prisma-next/test-utils": "workspace:*",
+    "@prisma-next/tsconfig": "workspace:*",
+    "@prisma-next/tsdown": "workspace:*",
+    "@types/pg": "catalog:",
+    "pg": "catalog:",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./types": "./dist/exports/types.mjs",
+    "./runtime": "./dist/runtime/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/2-sql/4-lanes/sql-builder"
+  }
+}

package/src/exports/types.ts

@@ -0,0 +1,8 @@
+export type { AggregateFunctions, Expression, Functions } from '../expression';
+export type { ResolveRow } from '../resolve';
+export type { GatedMethod, QueryContext, Scope, ScopeField, Subquery } from '../scope';
+export type { Db } from '../types/db';
+export type { GroupedQuery } from '../types/grouped-query';
+export type { DeleteQuery, InsertQuery, UpdateQuery } from '../types/mutation-query';
+export type { SelectQuery } from '../types/select-query';
+export type { TableProxy } from '../types/table-proxy';

package/src/expression.ts

@@ -0,0 +1,158 @@
+import type { QueryOperationTypesBase } from '@prisma-next/sql-contract/types';
+import type {
+  Expand,
+  ExpressionType,
+  QueryContext,
+  Scope,
+  ScopeField,
+  ScopeTable,
+  Subquery,
+} from './scope';
+
+export type Expression<T extends ScopeField> = {
+  [ExpressionType]: T;
+  buildAst(): import('@prisma-next/sql-relational-core/ast').AnyExpression;
+};
+
+export type WithField<Source, Field extends ScopeField, Alias extends string> = Expand<
+  Source & { [K in Alias]: Field }
+>;
+
+export type WithFields<
+  Source,
+  FromScope extends ScopeTable,
+  Columns extends readonly (keyof FromScope)[],
+> = Expand<Source & Pick<FromScope, Columns[number]>>;
+
+export type ExtractScopeFields<T extends Record<string, Expression<ScopeField>>> = {
+  [K in keyof T]: T[K] extends Expression<infer F extends ScopeField> ? F : never;
+};
+
+export type FieldProxy<AvailableScope extends Scope> = {
+  [K in keyof AvailableScope['topLevel']]: Expression<AvailableScope['topLevel'][K]>;
+} & {
+  [TableName in keyof AvailableScope['namespaces']]: {
+    [K in keyof AvailableScope['namespaces'][TableName]]: Expression<
+      AvailableScope['namespaces'][TableName][K]
+    >;
+  };
+};
+
+export type ExpressionOrValue<
+  T extends ScopeField,
+  CT extends Record<string, { readonly input: unknown }>,
+> = Expression<T> | (T['codecId'] extends keyof CT ? CT[T['codecId']]['input'] : never);
+
+export type BooleanCodecType = { codecId: 'pg/bool@1'; nullable: boolean };
+
+export type ExpressionBuilder<AvailableScope extends Scope, QC extends QueryContext> = (
+  fields: FieldProxy<AvailableScope>,
+  fns: Functions<QC>,
+) => Expression<BooleanCodecType>;
+
+export type OrderByDirection = 'asc' | 'desc';
+export type OrderByNulls = 'first' | 'last';
+
+export type OrderByOptions = {
+  direction?: OrderByDirection;
+  nulls?: OrderByNulls;
+};
+
+export type OrderByScope<
+  AvailableScope extends Scope,
+  RowType extends Record<string, ScopeField>,
+> = {
+  topLevel: Expand<AvailableScope['topLevel'] & RowType>;
+  namespaces: AvailableScope['namespaces'];
+};
+
+type ExtensionFunctionArgs<
+  Args extends readonly ScopeField[],
+  CT extends Record<string, { readonly input: unknown }>,
+> = { [I in keyof Args]: ExpressionOrValue<Args[I], CT> };
+
+type DeriveExtFunctions<
+  OT extends QueryOperationTypesBase,
+  CT extends Record<string, { readonly input: unknown }>,
+> = {
+  [K in keyof OT]: (
+    ...args: ExtensionFunctionArgs<OT[K]['args'], CT>
+  ) => Expression<OT[K]['returns']>;
+};
+
+export type BuiltinFunctions<CT extends Record<string, { readonly input: unknown }>> = {
+  eq: <CodecId extends string>(
+    a: ExpressionOrValue<{ codecId: CodecId; nullable: boolean }, CT> | null,
+    b: ExpressionOrValue<{ codecId: CodecId; nullable: boolean }, CT> | null,
+  ) => Expression<BooleanCodecType>;
+  ne: <T extends ScopeField>(
+    a: ExpressionOrValue<T, CT> | null,
+    b: ExpressionOrValue<T, CT> | null,
+  ) => Expression<BooleanCodecType>;
+  gt: <T extends ScopeField>(
+    a: ExpressionOrValue<T, CT>,
+    b: ExpressionOrValue<T, CT>,
+  ) => Expression<BooleanCodecType>;
+  gte: <T extends ScopeField>(
+    a: ExpressionOrValue<T, CT>,
+    b: ExpressionOrValue<T, CT>,
+  ) => Expression<BooleanCodecType>;
+  lt: <T extends ScopeField>(
+    a: ExpressionOrValue<T, CT>,
+    b: ExpressionOrValue<T, CT>,
+  ) => Expression<BooleanCodecType>;
+  lte: <T extends ScopeField>(
+    a: ExpressionOrValue<T, CT>,
+    b: ExpressionOrValue<T, CT>,
+  ) => Expression<BooleanCodecType>;
+  and: (...ands: ExpressionOrValue<BooleanCodecType, CT>[]) => Expression<BooleanCodecType>;
+  or: (...ors: ExpressionOrValue<BooleanCodecType, CT>[]) => Expression<BooleanCodecType>;
+
+  exists: (subquery: Subquery<Record<string, ScopeField>>) => Expression<BooleanCodecType>;
+  notExists: (subquery: Subquery<Record<string, ScopeField>>) => Expression<BooleanCodecType>;
+
+  in: {
+    <CodecId extends string>(
+      expr: Expression<{ codecId: CodecId; nullable: boolean }>,
+      subquery: Subquery<Record<string, { codecId: CodecId; nullable: boolean }>>,
+    ): Expression<BooleanCodecType>;
+    <CodecId extends string>(
+      expr: Expression<{ codecId: CodecId; nullable: boolean }>,
+      values: Array<ExpressionOrValue<{ codecId: CodecId; nullable: boolean }, CT>>,
+    ): Expression<BooleanCodecType>;
+  };
+
+  notIn: {
+    <CodecId extends string>(
+      expr: Expression<{ codecId: CodecId; nullable: boolean }>,
+      subquery: Subquery<Record<string, { codecId: CodecId; nullable: boolean }>>,
+    ): Expression<BooleanCodecType>;
+    <CodecId extends string>(
+      expr: Expression<{ codecId: CodecId; nullable: boolean }>,
+      values: Array<ExpressionOrValue<{ codecId: CodecId; nullable: boolean }, CT>>,
+    ): Expression<BooleanCodecType>;
+  };
+};
+
+export type Functions<QC extends QueryContext> = BuiltinFunctions<QC['codecTypes']> &
+  DeriveExtFunctions<QC['queryOperationTypes'], QC['codecTypes']>;
+
+export type CountField = { codecId: 'pg/int8@1'; nullable: false };
+
+export type AggregateOnlyFunctions = {
+  count: (expr?: Expression<ScopeField>) => Expression<CountField>;
+  sum: <T extends ScopeField>(
+    expr: Expression<T>,
+  ) => Expression<{ codecId: T['codecId']; nullable: true }>;
+  avg: <T extends ScopeField>(
+    expr: Expression<T>,
+  ) => Expression<{ codecId: T['codecId']; nullable: true }>;
+  min: <T extends ScopeField>(
+    expr: Expression<T>,
+  ) => Expression<{ codecId: T['codecId']; nullable: true }>;
+  max: <T extends ScopeField>(
+    expr: Expression<T>,
+  ) => Expression<{ codecId: T['codecId']; nullable: true }>;
+};
+
+export type AggregateFunctions<QC extends QueryContext> = Functions<QC> & AggregateOnlyFunctions;

package/src/index.ts

@@ -0,0 +1,8 @@
+export type { AggregateFunctions, Expression, Functions } from './expression';
+export type { ResolveRow } from './resolve';
+export type { GatedMethod, QueryContext, Scope, ScopeField, Subquery } from './scope';
+export type { Db } from './types/db';
+export type { GroupedQuery } from './types/grouped-query';
+export type { DeleteQuery, InsertQuery, UpdateQuery } from './types/mutation-query';
+export type { SelectQuery } from './types/select-query';
+export type { TableProxy } from './types/table-proxy';

package/src/resolve.ts

@@ -0,0 +1,14 @@
+import type { Expand, ScopeField } from './scope';
+
+/// Given a row type of { <fieldName>: { codecId: <codecId>, nullable: <nullable> } }, return a record of { <fieldName>: <codecOutputType> }
+/// Also resolves nullability of the field.
+export type ResolveRow<
+  Row extends Record<string, ScopeField>,
+  CodecTypes extends Record<string, { readonly output: unknown }>,
+> = Expand<{
+  -readonly [K in keyof Row]: Row[K]['codecId'] extends keyof CodecTypes
+    ? Row[K]['nullable'] extends true
+      ? CodecTypes[Row[K]['codecId']]['output'] | null
+      : CodecTypes[Row[K]['codecId']]['output']
+    : unknown;
+}>;

package/src/runtime/builder-base.ts

@@ -0,0 +1,369 @@
+import type { PlanMeta } from '@prisma-next/contract/types';
+import type { StorageTable } from '@prisma-next/sql-contract/types';
+import {
+  AndExpr,
+  type AnyExpression as AstExpression,
+  IdentifierRef,
+  OrderByItem,
+  ProjectionItem,
+  SelectAst,
+  type TableSource,
+} from '@prisma-next/sql-relational-core/ast';
+import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import type {
+  AppliedMutationDefault,
+  MutationDefaultsOptions,
+} from '@prisma-next/sql-relational-core/query-lane-context';
+import type { QueryOperationEntry } from '@prisma-next/sql-relational-core/query-operations';
+import type {
+  AggregateFunctions,
+  Expression,
+  FieldProxy,
+  OrderByOptions,
+  OrderByScope,
+} from '../expression';
+import type {
+  GatedMethod,
+  MergeScopes,
+  NullableScope,
+  QueryContext,
+  Scope,
+  ScopeField,
+  ScopeTable,
+} from '../scope';
+import type { ExpressionImpl } from './expression-impl';
+import { createFieldProxy } from './field-proxy';
+import { createAggregateFunctions, createFunctions } from './functions';
+
+export type ExprCallback = (fields: FieldProxy<Scope>, fns: unknown) => Expression<ScopeField>;
+
+export class BuilderBase<Capabilities = unknown> {
+  protected readonly ctx: BuilderContext;
+
+  constructor(ctx: BuilderContext) {
+    this.ctx = ctx;
+  }
+
+  protected _gate<Req extends Record<string, Record<string, boolean>>, Args extends unknown[], R>(
+    required: Req,
+    methodName: string,
+    method: (...args: Args) => R,
+  ): GatedMethod<Capabilities, Req, (...args: Args) => R> {
+    return ((...args: Args): R => {
+      assertCapability(this.ctx, required, methodName);
+      return method(...args);
+    }) as GatedMethod<Capabilities, Req, (...args: Args) => R>;
+  }
+}
+
+export interface BuilderState {
+  readonly from: TableSource;
+  readonly joins: readonly import('@prisma-next/sql-relational-core/ast').JoinAst[];
+  readonly projections: readonly ProjectionItem[];
+  readonly where: readonly AstExpression[];
+  readonly orderBy: readonly OrderByItem[];
+  readonly groupBy: readonly AstExpression[];
+  readonly having: AstExpression | undefined;
+  readonly limit: number | undefined;
+  readonly offset: number | undefined;
+  readonly distinct: true | undefined;
+  readonly distinctOn: readonly AstExpression[] | undefined;
+  readonly scope: Scope;
+  readonly rowFields: Record<string, ScopeField>;
+}
+
+export interface BuilderContext {
+  readonly capabilities: Record<string, Record<string, boolean>>;
+  readonly queryOperationTypes: Readonly<Record<string, QueryOperationEntry>>;
+  readonly target: string;
+  readonly storageHash: string;
+  readonly applyMutationDefaults: (
+    options: MutationDefaultsOptions,
+  ) => ReadonlyArray<AppliedMutationDefault>;
+}
+
+export function emptyState(from: TableSource, scope: Scope): BuilderState {
+  return {
+    from,
+    joins: [],
+    projections: [],
+    where: [],
+    orderBy: [],
+    groupBy: [],
+    having: undefined,
+    limit: undefined,
+    offset: undefined,
+    distinct: undefined,
+    distinctOn: undefined,
+    scope,
+    rowFields: {},
+  };
+}
+
+export function cloneState(state: BuilderState, overrides: Partial<BuilderState>): BuilderState {
+  return { ...state, ...overrides };
+}
+
+export function combineWhereExprs(exprs: readonly AstExpression[]): AstExpression | undefined {
+  if (exprs.length === 0) return undefined;
+  if (exprs.length === 1) return exprs[0];
+  return AndExpr.of(exprs);
+}
+
+export function buildSelectAst(state: BuilderState): SelectAst {
+  const where = combineWhereExprs(state.where);
+  return new SelectAst({
+    from: state.from,
+    joins: state.joins.length > 0 ? state.joins : undefined,
+    projection: state.projections,
+    where,
+    orderBy: state.orderBy.length > 0 ? state.orderBy : undefined,
+    distinct: state.distinct,
+    distinctOn: state.distinctOn && state.distinctOn.length > 0 ? state.distinctOn : undefined,
+    groupBy: state.groupBy.length > 0 ? state.groupBy : undefined,
+    having: state.having,
+    limit: state.limit,
+    offset: state.offset,
+    selectAllIntent: undefined,
+  });
+}
+
+export function buildQueryPlan<Row = unknown>(
+  ast: import('@prisma-next/sql-relational-core/ast').AnyQueryAst,
+  rowFields: Record<string, ScopeField>,
+  ctx: BuilderContext,
+): SqlQueryPlan<Row> {
+  const projectionTypes: Record<string, string> = {};
+  const codecs: Record<string, string> = {};
+  for (const [alias, field] of Object.entries(rowFields)) {
+    projectionTypes[alias] = field.codecId;
+    codecs[alias] = field.codecId;
+  }
+
+  const paramRefs = ast.collectParamRefs();
+  const seen = new Set<import('@prisma-next/sql-relational-core/ast').ParamRef>();
+  const uniqueRefs: import('@prisma-next/sql-relational-core/ast').ParamRef[] = [];
+  for (const ref of paramRefs) {
+    if (!seen.has(ref)) {
+      seen.add(ref);
+      uniqueRefs.push(ref);
+    }
+  }
+  const paramValues = uniqueRefs.map((r) => r.value);
+  const paramDescriptors = uniqueRefs.map((ref, i) => ({
+    index: i + 1,
+    source: 'dsl' as const,
+    ...(ref.codecId ? { codecId: ref.codecId } : {}),
+  }));
+
+  for (const [i, ref] of uniqueRefs.entries()) {
+    if (ref.codecId) codecs[`$${i + 1}`] = ref.codecId;
+  }
+
+  const hasProjectionTypes = Object.keys(projectionTypes).length > 0;
+  const hasCodecs = Object.keys(codecs).length > 0;
+
+  const meta: PlanMeta = Object.freeze({
+    target: ctx.target,
+    storageHash: ctx.storageHash,
+    lane: 'dsl',
+    paramDescriptors,
+    ...(hasProjectionTypes ? { projectionTypes } : {}),
+    ...(hasCodecs ? { annotations: Object.freeze({ codecs: Object.freeze(codecs) }) } : {}),
+  });
+
+  return Object.freeze({ ast, params: paramValues, meta });
+}
+
+export function buildPlan<Row = unknown>(
+  state: BuilderState,
+  ctx: BuilderContext,
+): SqlQueryPlan<Row> {
+  return buildQueryPlan<Row>(buildSelectAst(state), state.rowFields, ctx);
+}
+
+export function tableToScope(name: string, table: StorageTable): Scope {
+  const fields: ScopeTable = {};
+  for (const [colName, col] of Object.entries(table.columns)) {
+    fields[colName] = { codecId: col.codecId, nullable: col.nullable };
+  }
+  return { topLevel: { ...fields }, namespaces: { [name]: fields } };
+}
+
+export function mergeScopes<A extends Scope, B extends Scope>(a: A, b: B): MergeScopes<A, B> {
+  const topLevel: ScopeTable = {};
+  for (const [k, v] of Object.entries(a.topLevel)) {
+    if (!(k in b.topLevel)) topLevel[k] = v;
+  }
+  for (const [k, v] of Object.entries(b.topLevel)) {
+    if (!(k in a.topLevel)) topLevel[k] = v;
+  }
+  return {
+    topLevel,
+    namespaces: { ...a.namespaces, ...b.namespaces },
+  } as MergeScopes<A, B>;
+}
+
+export function nullableScope<S extends Scope>(scope: S): NullableScope<S> {
+  const mkNullable = (tbl: ScopeTable): ScopeTable => {
+    const result: ScopeTable = {};
+    for (const [k, v] of Object.entries(tbl)) {
+      result[k] = { codecId: v.codecId, nullable: true };
+    }
+    return result;
+  };
+  const namespaces: Record<string, ScopeTable> = {};
+  for (const [k, v] of Object.entries(scope.namespaces)) {
+    namespaces[k] = mkNullable(v);
+  }
+  return { topLevel: mkNullable(scope.topLevel), namespaces } as NullableScope<S>;
+}
+
+export function orderByScopeOf<S extends Scope, R extends Record<string, ScopeField>>(
+  scope: S,
+  rowFields: R,
+): OrderByScope<S, R> {
+  return {
+    topLevel: { ...scope.topLevel, ...rowFields },
+    namespaces: scope.namespaces,
+  };
+}
+
+export function assertCapability(
+  ctx: BuilderContext,
+  required: Record<string, Record<string, boolean>>,
+  methodName: string,
+): void {
+  for (const [ns, keys] of Object.entries(required)) {
+    for (const key of Object.keys(keys)) {
+      if (!ctx.capabilities[ns]?.[key]) {
+        throw new Error(`${methodName}() requires capability ${ns}.${key}`);
+      }
+    }
+  }
+}
+
+export function resolveSelectArgs(
+  args: unknown[],
+  scope: Scope,
+  ctx: BuilderContext,
+): { projections: ProjectionItem[]; newRowFields: Record<string, ScopeField> } {
+  const projections: ProjectionItem[] = [];
+  const newRowFields: Record<string, ScopeField> = {};
+
+  if (args.length === 0) return { projections, newRowFields };
+
+  if (typeof args[0] === 'string' && (args.length === 1 || typeof args[1] !== 'function')) {
+    for (const colName of args as string[]) {
+      const field = scope.topLevel[colName];
+      if (!field) throw new Error(`Column "${colName}" not found in scope`);
+      projections.push(ProjectionItem.of(colName, IdentifierRef.of(colName)));
+      newRowFields[colName] = field;
+    }
+    return { projections, newRowFields };
+  }
+
+  if (typeof args[0] === 'string' && typeof args[1] === 'function') {
+    const alias = args[0] as string;
+    const exprFn = args[1] as (
+      f: FieldProxy<Scope>,
+      fns: AggregateFunctions<QueryContext>,
+    ) => Expression<ScopeField>;
+    const fns = createAggregateFunctions(ctx.queryOperationTypes);
+    const result = exprFn(createFieldProxy(scope), fns);
+    projections.push(ProjectionItem.of(alias, result.buildAst()));
+    newRowFields[alias] = (result as ExpressionImpl).field;
+    return { projections, newRowFields };
+  }
+
+  if (typeof args[0] === 'function') {
+    const callbackFn = args[0] as (
+      f: FieldProxy<Scope>,
+      fns: AggregateFunctions<QueryContext>,
+    ) => Record<string, Expression<ScopeField>>;
+    const fns = createAggregateFunctions(ctx.queryOperationTypes);
+    const record = callbackFn(createFieldProxy(scope), fns);
+    for (const [key, expr] of Object.entries(record)) {
+      projections.push(ProjectionItem.of(key, expr.buildAst()));
+      newRowFields[key] = (expr as ExpressionImpl).field;
+    }
+    return { projections, newRowFields };
+  }
+
+  throw new Error('Invalid .select() arguments');
+}
+
+export function resolveOrderBy(
+  arg: unknown,
+  options: OrderByOptions | undefined,
+  scope: Scope,
+  rowFields: Record<string, ScopeField>,
+  ctx: BuilderContext,
+  useAggregateFns: boolean,
+): OrderByItem {
+  const dir = options?.direction ?? 'asc';
+
+  if (typeof arg === 'string') {
+    const combined = orderByScopeOf(scope, rowFields);
+    if (!(arg in combined.topLevel))
+      throw new Error(`Column "${arg}" not found in scope for orderBy`);
+    const expr = IdentifierRef.of(arg);
+    return dir === 'asc' ? OrderByItem.asc(expr) : OrderByItem.desc(expr);
+  }
+
+  if (typeof arg === 'function') {
+    const combined = orderByScopeOf(scope, rowFields);
+    const fns = useAggregateFns
+      ? createAggregateFunctions(ctx.queryOperationTypes)
+      : createFunctions(ctx.queryOperationTypes);
+    const result = (arg as ExprCallback)(createFieldProxy(combined), fns);
+    return dir === 'asc' ? OrderByItem.asc(result.buildAst()) : OrderByItem.desc(result.buildAst());
+  }
+
+  throw new Error('Invalid orderBy argument');
+}
+
+export function resolveGroupBy(
+  args: unknown[],
+  scope: Scope,
+  rowFields: Record<string, ScopeField>,
+  ctx: BuilderContext,
+): AstExpression[] {
+  if (typeof args[0] === 'string') {
+    const combined = orderByScopeOf(scope, rowFields);
+    return (args as string[]).map((colName) => {
+      if (!(colName in combined.topLevel))
+        throw new Error(`Column "${colName}" not found in scope for groupBy`);
+      return IdentifierRef.of(colName);
+    });
+  }
+
+  if (typeof args[0] === 'function') {
+    const combined = orderByScopeOf(scope, rowFields);
+    const fns = createFunctions(ctx.queryOperationTypes);
+    const result = (args[0] as ExprCallback)(createFieldProxy(combined), fns);
+    return [result.buildAst()];
+  }
+
+  throw new Error('Invalid groupBy arguments');
+}
+
+export function resolveDistinctOn(
+  args: unknown[],
+  scope: Scope,
+  rowFields: Record<string, ScopeField>,
+  ctx: BuilderContext,
+): AstExpression[] {
+  if (args.length === 1 && typeof args[0] === 'function') {
+    const combined = orderByScopeOf(scope, rowFields);
+    const fns = createFunctions(ctx.queryOperationTypes);
+    const result = (args[0] as ExprCallback)(createFieldProxy(combined), fns);
+    return [result.buildAst()];
+  }
+  const combined = orderByScopeOf(scope, rowFields);
+  return (args as string[]).map((colName) => {
+    if (!(colName in combined.topLevel))
+      throw new Error(`Column "${colName}" not found in scope for distinctOn`);
+    return IdentifierRef.of(colName);
+  });
+}