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

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@prisma-next/sql-lane",
-  "version": "0.3.0-dev.4",
+  "version": "0.3.0-dev.5",
   "type": "module",
   "sideEffects": false,
   "description": "Relational DSL and raw SQL helpers for Prisma Next",
   "dependencies": {
-    "@prisma-next/contract": "0.3.0-dev.4",
-    "@prisma-next/plan": "0.3.0-dev.4",
-    "@prisma-next/sql-contract": "0.3.0-dev.4",
-    "@prisma-next/sql-relational-core": "0.3.0-dev.4"
+    "@prisma-next/plan": "0.3.0-dev.5",
+    "@prisma-next/sql-contract": "0.3.0-dev.5",
+    "@prisma-next/sql-relational-core": "0.3.0-dev.5",
+    "@prisma-next/contract": "0.3.0-dev.5"
   },
   "devDependencies": {
     "@types/pg": "8.16.0",
@@ -17,12 +17,13 @@
     "tsup": "8.5.1",
     "typescript": "5.9.3",
     "vitest": "4.0.16",
-    "@prisma-next/sql-contract-ts": "0.3.0-dev.4",
-    "@prisma-next/sql-runtime": "0.3.0-dev.4",
+    "@prisma-next/sql-contract-ts": "0.3.0-dev.5",
+    "@prisma-next/sql-runtime": "0.3.0-dev.5",
     "@prisma-next/test-utils": "0.0.1"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "exports": {
     ".": {
@@ -35,7 +36,7 @@
     }
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts",
+    "build": "tsup --config tsup.config.ts && tsc --project tsconfig.build.json",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --project tsconfig.json --noEmit",

package/src/exports/sql.ts

@@ -0,0 +1,12 @@
+export type {
+  ColumnsOf,
+  RawFactory,
+  RawFunctionOptions,
+  RawTemplateOptions,
+  SqlBuilderOptions,
+  TableKey,
+  TablesOf,
+} from '@prisma-next/sql-relational-core/types';
+export { rawOptions } from '../raw';
+export type { SelectBuilder } from '../sql/builder';
+export { createJoinOnBuilder, sql } from '../sql/builder';

package/src/index.ts

@@ -0,0 +1,13 @@
+export type {
+  ColumnsOf,
+  JoinOnBuilder,
+  RawFactory,
+  RawFunctionOptions,
+  RawTemplateOptions,
+  SqlBuilderOptions,
+  TableKey,
+  TablesOf,
+} from '@prisma-next/sql-relational-core/types';
+export { rawOptions } from './raw';
+export type { IncludeChildBuilder, SelectBuilder } from './sql/builder';
+export { createJoinOnBuilder, sql } from './sql/builder';

package/src/raw.ts

@@ -0,0 +1,230 @@
+import type {
+  ExecutionPlan,
+  ParamDescriptor,
+  PlanMeta,
+  PlanRefs,
+} from '@prisma-next/contract/types';
+import { planInvalid } from '@prisma-next/plan';
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type {
+  RawFactory,
+  RawFunctionOptions,
+  RawTemplateFactory,
+  RawTemplateOptions,
+} from '@prisma-next/sql-relational-core/types';
+
+const RAW_OPTIONS_SENTINEL = Symbol('rawOptions');
+
+type TemplateInvocation = {
+  readonly sql: string;
+  readonly params: readonly unknown[];
+  readonly paramDescriptors: ReadonlyArray<ParamDescriptor>;
+};
+
+interface RawPlanBuildArgs {
+  readonly contract: SqlContract<SqlStorage>;
+  readonly sql: string;
+  readonly params: readonly unknown[];
+  readonly paramDescriptors: ReadonlyArray<ParamDescriptor>;
+  readonly options?: RawTemplateOptions;
+}
+
+export function createRawFactory(contract: SqlContract<SqlStorage>): RawFactory {
+  const factory = ((first: TemplateStringsArray | string, ...rest: unknown[]) => {
+    if (isTemplateInvocation(first)) {
+      const { values, options } = splitTemplateValues(rest);
+      const compiled = compileTemplateToPositional(first, values);
+      return buildRawPlan({
+        contract,
+        sql: compiled.sql,
+        params: compiled.params,
+        paramDescriptors: compiled.paramDescriptors,
+        ...(options ? { options } : {}),
+      });
+    }
+
+    const text = first;
+    const [options] = rest as [RawFunctionOptions | undefined];
+
+    if (!options) {
+      throw planInvalid('Function form requires params option');
+    }
+
+    if (!Array.isArray(options.params)) {
+      throw planInvalid('Function form params must be an array');
+    }
+
+    const paramDescriptors = buildSequentialDescriptors(options.params.length);
+
+    return buildRawPlan({
+      contract,
+      sql: text,
+      params: options.params,
+      paramDescriptors,
+      options,
+    });
+  }) as RawFactory;
+
+  factory.with = (options: RawTemplateOptions) => {
+    return ((strings: TemplateStringsArray, ...values: readonly unknown[]) => {
+      const compiled = compileTemplateToPositional(strings, values);
+      return buildRawPlan({
+        contract,
+        sql: compiled.sql,
+        params: compiled.params,
+        paramDescriptors: compiled.paramDescriptors,
+        options,
+      });
+    }) as RawTemplateFactory;
+  };
+
+  return factory;
+}
+
+function compileTemplateToPositional(
+  strings: TemplateStringsArray,
+  values: readonly unknown[],
+): TemplateInvocation {
+  let sql = '';
+  const params: unknown[] = [];
+  const paramDescriptors: ParamDescriptor[] = [];
+
+  strings.forEach((part, index) => {
+    sql += part;
+
+    if (index < values.length) {
+      const value = values[index];
+      const placeholderIndex = params.push(value);
+      sql += `$${placeholderIndex}`;
+      paramDescriptors.push({
+        index: placeholderIndex,
+        name: `p${placeholderIndex}`,
+        source: 'raw',
+      });
+    }
+  });
+
+  return {
+    sql,
+    params,
+    paramDescriptors,
+  };
+}
+
+function buildRawPlan(args: RawPlanBuildArgs): ExecutionPlan {
+  const params = Array.from(args.params);
+  const descriptors = args.paramDescriptors.map((descriptor) =>
+    Object.freeze({ ...descriptor, source: 'raw' as const }),
+  );
+
+  const meta = buildRawMeta({
+    contract: args.contract,
+    paramDescriptors: descriptors,
+    ...(args.options ? { options: args.options } : {}),
+  });
+
+  return Object.freeze({
+    sql: args.sql,
+    params: Object.freeze(params),
+    meta,
+  });
+}
+
+interface RawMetaBuildArgs {
+  readonly contract: SqlContract<SqlStorage>;
+  readonly paramDescriptors: ReadonlyArray<ParamDescriptor>;
+  readonly options?: RawTemplateOptions;
+}
+
+function buildRawMeta(args: RawMetaBuildArgs): PlanMeta {
+  const { contract, paramDescriptors, options } = args;
+
+  const meta: PlanMeta = {
+    target: contract.target,
+    targetFamily: contract.targetFamily,
+    coreHash: contract.coreHash,
+    ...(contract.profileHash !== undefined ? { profileHash: contract.profileHash } : {}),
+    lane: 'raw',
+    paramDescriptors: Object.freeze([...paramDescriptors]),
+    ...(options?.annotations ? { annotations: Object.freeze({ ...options.annotations }) } : {}),
+    ...(options?.refs ? { refs: freezeRefs(options.refs) } : {}),
+    ...(options?.projection ? { projection: Object.freeze([...options.projection]) } : {}),
+  };
+
+  return Object.freeze(meta);
+}
+
+function freezeRefs(refs: PlanRefs): PlanRefs {
+  return Object.freeze({
+    ...(refs.tables ? { tables: Object.freeze([...refs.tables]) } : {}),
+    ...(refs.columns
+      ? {
+          columns: Object.freeze(
+            refs.columns.map((col: { table: string; column: string }) => Object.freeze({ ...col })),
+          ),
+        }
+      : {}),
+    ...(refs.indexes
+      ? {
+          indexes: Object.freeze(
+            refs.indexes.map(
+              (index: { table: string; columns: ReadonlyArray<string>; name?: string }) =>
+                Object.freeze({
+                  ...index,
+                  columns: Object.freeze([...index.columns]),
+                }),
+            ),
+          ),
+        }
+      : {}),
+  });
+}
+
+function buildSequentialDescriptors(count: number): ReadonlyArray<ParamDescriptor> {
+  return Array.from({ length: count }, (_, idx) =>
+    Object.freeze({
+      index: idx + 1,
+      name: `p${idx + 1}`,
+      source: 'raw' as const,
+    }),
+  );
+}
+
+function isTemplateInvocation(value: unknown): value is TemplateStringsArray {
+  return Array.isArray(value) && Object.hasOwn(value, 'raw');
+}
+
+interface RawTemplateOptionsSentinel {
+  readonly [RAW_OPTIONS_SENTINEL]: true;
+  readonly value: RawTemplateOptions;
+}
+
+export function rawOptions(options: RawTemplateOptions): RawTemplateOptionsSentinel {
+  return Object.freeze({
+    [RAW_OPTIONS_SENTINEL]: true as const,
+    value: options,
+  });
+}
+
+function splitTemplateValues(values: readonly unknown[]): {
+  readonly values: readonly unknown[];
+  readonly options?: RawTemplateOptions;
+} {
+  if (values.length === 0) {
+    return { values };
+  }
+
+  const last = values[values.length - 1];
+  if (!isOptionsSentinel(last)) {
+    return { values };
+  }
+
+  return {
+    values: values.slice(0, values.length - 1),
+    options: last.value,
+  };
+}
+
+function isOptionsSentinel(value: unknown): value is RawTemplateOptionsSentinel {
+  return typeof value === 'object' && value !== null && RAW_OPTIONS_SENTINEL in value;
+}

package/src/sql/builder.ts

@@ -0,0 +1,66 @@
+import type {
+  ExtractCodecTypes,
+  ExtractOperationTypes,
+  SqlContract,
+  SqlStorage,
+} from '@prisma-next/sql-contract/types';
+import type { TableRef } from '@prisma-next/sql-relational-core/ast';
+import { createJoinOnBuilder } from '@prisma-next/sql-relational-core/ast';
+import type { ParamPlaceholder, SqlBuilderOptions } from '@prisma-next/sql-relational-core/types';
+import { createRawFactory } from '../raw';
+import type { SelectBuilder } from '../types/public';
+import { DeleteBuilderImpl, InsertBuilderImpl, UpdateBuilderImpl } from './mutation-builder';
+import { SelectBuilderImpl } from './select-builder';
+
+export { createJoinOnBuilder };
+export type { DeleteBuilder, InsertBuilder, SelectBuilder, UpdateBuilder } from '../types/public';
+export type { IncludeChildBuilder } from './include-builder';
+
+export function sql<
+  TContract extends SqlContract<SqlStorage>,
+  CodecTypesOverride extends Record<
+    string,
+    { readonly output: unknown }
+  > = ExtractCodecTypes<TContract>,
+>(
+  options: SqlBuilderOptions<TContract>,
+): SelectBuilder<TContract, unknown, CodecTypesOverride, ExtractOperationTypes<TContract>> {
+  type CodecTypes = CodecTypesOverride;
+  type Operations = ExtractOperationTypes<TContract>;
+  const builder = new SelectBuilderImpl<TContract, unknown, CodecTypes, Record<string, never>>(
+    options,
+  ) as SelectBuilder<TContract, unknown, CodecTypes, Operations>;
+  const rawFactory = createRawFactory(options.context.contract);
+
+  Object.defineProperty(builder, 'raw', {
+    value: rawFactory,
+    enumerable: true,
+    configurable: false,
+  });
+
+  Object.defineProperty(builder, 'insert', {
+    value: (table: TableRef, values: Record<string, ParamPlaceholder>) => {
+      return new InsertBuilderImpl<TContract, CodecTypes>(options, table, values);
+    },
+    enumerable: true,
+    configurable: false,
+  });
+
+  Object.defineProperty(builder, 'update', {
+    value: (table: TableRef, set: Record<string, ParamPlaceholder>) => {
+      return new UpdateBuilderImpl<TContract, CodecTypes>(options, table, set);
+    },
+    enumerable: true,
+    configurable: false,
+  });
+
+  Object.defineProperty(builder, 'delete', {
+    value: (table: TableRef) => {
+      return new DeleteBuilderImpl<TContract, CodecTypes>(options, table);
+    },
+    enumerable: true,
+    configurable: false,
+  });
+
+  return builder;
+}

package/src/sql/context.ts

@@ -0,0 +1,10 @@
+import type { SqlContract, SqlStorage } from '@prisma-next/sql-contract/types';
+import type { QueryLaneContext } from '@prisma-next/sql-relational-core/query-lane-context';
+
+export type SqlContext<TContract extends SqlContract<SqlStorage>> = QueryLaneContext<TContract>;
+
+export function createSqlContext<TContract extends SqlContract<SqlStorage>>(
+  context: QueryLaneContext<TContract>,
+): SqlContext<TContract> {
+  return context;
+}

package/src/sql/include-builder.ts

@@ -0,0 +1,248 @@
+import type { ParamDescriptor } from '@prisma-next/contract/types';
+import type { SqlContract, SqlStorage, StorageColumn } from '@prisma-next/sql-contract/types';
+import type {
+  BinaryExpr,
+  ColumnRef,
+  IncludeAst,
+  OperationExpr,
+  TableRef,
+} from '@prisma-next/sql-relational-core/ast';
+import {
+  createColumnRef,
+  createJoinOnExpr,
+  createOrderByItem,
+  createTableRef,
+} from '@prisma-next/sql-relational-core/ast';
+import type {
+  AnyBinaryBuilder,
+  AnyOrderBuilder,
+  BinaryBuilder,
+  CodecTypes as CodecTypesMap,
+  InferNestedProjectionRow,
+  NestedProjection,
+  OrderBuilder,
+} from '@prisma-next/sql-relational-core/types';
+import {
+  extractBaseColumnRef,
+  isOperationExpr,
+} from '@prisma-next/sql-relational-core/utils/guards';
+import {
+  errorChildProjectionMustBeSpecified,
+  errorLimitMustBeNonNegativeInteger,
+  errorMissingColumnForAlias,
+} from '../utils/errors';
+import type { IncludeState, ProjectionState } from '../utils/state';
+import { buildWhereExpr } from './predicate-builder';
+import { buildProjectionState } from './projection';
+
+export interface IncludeChildBuilder<
+  TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
+  CodecTypes extends Record<string, { readonly output: unknown }> = Record<string, never>,
+  ChildRow = unknown,
+> {
+  select<P extends NestedProjection>(
+    projection: P,
+  ): IncludeChildBuilder<TContract, CodecTypes, InferNestedProjectionRow<P, CodecTypes>>;
+  where(expr: AnyBinaryBuilder): IncludeChildBuilder<TContract, CodecTypes, ChildRow>;
+  orderBy(order: AnyOrderBuilder): IncludeChildBuilder<TContract, CodecTypes, ChildRow>;
+  limit(count: number): IncludeChildBuilder<TContract, CodecTypes, ChildRow>;
+}
+
+export class IncludeChildBuilderImpl<
+  TContract extends SqlContract<SqlStorage> = SqlContract<SqlStorage>,
+  CodecTypes extends CodecTypesMap = CodecTypesMap,
+  ChildRow = unknown,
+> implements IncludeChildBuilder<TContract, CodecTypes, ChildRow>
+{
+  private readonly contract: TContract;
+  private readonly codecTypes: CodecTypes;
+  private readonly table: TableRef;
+  private childProjection?: ProjectionState;
+  private childWhere?: BinaryBuilder;
+  private childOrderBy?: OrderBuilder;
+  private childLimit?: number;
+
+  constructor(contract: TContract, codecTypes: CodecTypes, table: TableRef) {
+    this.contract = contract;
+    this.codecTypes = codecTypes;
+    this.table = table;
+  }
+
+  select<P extends NestedProjection>(
+    projection: P,
+  ): IncludeChildBuilderImpl<TContract, CodecTypes, InferNestedProjectionRow<P, CodecTypes>> {
+    const projectionState = buildProjectionState(this.table, projection);
+    const builder = new IncludeChildBuilderImpl<
+      TContract,
+      CodecTypes,
+      InferNestedProjectionRow<P, CodecTypes>
+    >(this.contract, this.codecTypes, this.table);
+    builder.childProjection = projectionState;
+    if (this.childWhere !== undefined) {
+      builder.childWhere = this.childWhere;
+    }
+    if (this.childOrderBy !== undefined) {
+      builder.childOrderBy = this.childOrderBy;
+    }
+    if (this.childLimit !== undefined) {
+      builder.childLimit = this.childLimit;
+    }
+    return builder;
+  }
+
+  where(expr: AnyBinaryBuilder): IncludeChildBuilderImpl<TContract, CodecTypes, ChildRow> {
+    const builder = new IncludeChildBuilderImpl<TContract, CodecTypes, ChildRow>(
+      this.contract,
+      this.codecTypes,
+      this.table,
+    );
+    if (this.childProjection !== undefined) {
+      builder.childProjection = this.childProjection;
+    }
+    builder.childWhere = expr;
+    if (this.childOrderBy !== undefined) {
+      builder.childOrderBy = this.childOrderBy;
+    }
+    if (this.childLimit !== undefined) {
+      builder.childLimit = this.childLimit;
+    }
+    return builder;
+  }
+
+  orderBy(order: AnyOrderBuilder): IncludeChildBuilderImpl<TContract, CodecTypes, ChildRow> {
+    const builder = new IncludeChildBuilderImpl<TContract, CodecTypes, ChildRow>(
+      this.contract,
+      this.codecTypes,
+      this.table,
+    );
+    if (this.childProjection !== undefined) {
+      builder.childProjection = this.childProjection;
+    }
+    if (this.childWhere !== undefined) {
+      builder.childWhere = this.childWhere;
+    }
+    builder.childOrderBy = order;
+    if (this.childLimit !== undefined) {
+      builder.childLimit = this.childLimit;
+    }
+    return builder;
+  }
+
+  limit(count: number): IncludeChildBuilderImpl<TContract, CodecTypes, ChildRow> {
+    if (!Number.isInteger(count) || count < 0) {
+      errorLimitMustBeNonNegativeInteger();
+    }
+
+    const builder = new IncludeChildBuilderImpl<TContract, CodecTypes, ChildRow>(
+      this.contract,
+      this.codecTypes,
+      this.table,
+    );
+    if (this.childProjection !== undefined) {
+      builder.childProjection = this.childProjection;
+    }
+    if (this.childWhere !== undefined) {
+      builder.childWhere = this.childWhere;
+    }
+    if (this.childOrderBy !== undefined) {
+      builder.childOrderBy = this.childOrderBy;
+    }
+    builder.childLimit = count;
+    return builder;
+  }
+
+  getState(): {
+    childProjection: ProjectionState;
+    childWhere?: AnyBinaryBuilder;
+    childOrderBy?: AnyOrderBuilder;
+    childLimit?: number;
+  } {
+    if (!this.childProjection) {
+      errorChildProjectionMustBeSpecified();
+    }
+    const state: {
+      childProjection: ProjectionState;
+      childWhere?: AnyBinaryBuilder;
+      childOrderBy?: AnyOrderBuilder;
+      childLimit?: number;
+    } = {
+      childProjection: this.childProjection,
+    };
+    if (this.childWhere !== undefined) {
+      state.childWhere = this.childWhere;
+    }
+    if (this.childOrderBy !== undefined) {
+      state.childOrderBy = this.childOrderBy;
+    }
+    if (this.childLimit !== undefined) {
+      state.childLimit = this.childLimit;
+    }
+    return state;
+  }
+}
+
+export function buildIncludeAst(
+  include: IncludeState,
+  contract: SqlContract<SqlStorage>,
+  paramsMap: Record<string, unknown>,
+  paramDescriptors: ParamDescriptor[],
+  paramValues: unknown[],
+): IncludeAst {
+  const childOrderBy = include.childOrderBy
+    ? (() => {
+        const orderBy = include.childOrderBy as OrderBuilder<string, StorageColumn, unknown>;
+        const orderExpr = orderBy.expr;
+        const expr: ColumnRef | OperationExpr = (() => {
+          if (isOperationExpr(orderExpr)) {
+            const baseCol = extractBaseColumnRef(orderExpr);
+            return createColumnRef(baseCol.table, baseCol.column);
+          }
+          // orderExpr is ColumnBuilder - TypeScript can't narrow properly
+          const colBuilder = orderExpr as { table: string; column: string };
+          return createColumnRef(colBuilder.table, colBuilder.column);
+        })();
+        return [createOrderByItem(expr, orderBy.dir)];
+      })()
+    : undefined;
+
+  let childWhere: BinaryExpr | undefined;
+  if (include.childWhere) {
+    const whereResult = buildWhereExpr(
+      contract,
+      include.childWhere,
+      paramsMap,
+      paramDescriptors,
+      paramValues,
+    );
+    childWhere = whereResult.expr;
+  }
+
+  const onLeft = include.on.left as { table: string; column: string };
+  const onRight = include.on.right as { table: string; column: string };
+  const leftCol = createColumnRef(onLeft.table, onLeft.column);
+  const rightCol = createColumnRef(onRight.table, onRight.column);
+  const onExpr = createJoinOnExpr(leftCol, rightCol);
+
+  return {
+    kind: 'includeMany' as const,
+    alias: include.alias,
+    child: {
+      table: createTableRef(include.table.name),
+      on: onExpr,
+      ...(childWhere ? { where: childWhere } : {}),
+      ...(childOrderBy ? { orderBy: childOrderBy } : {}),
+      ...(typeof include.childLimit === 'number' ? { limit: include.childLimit } : {}),
+      project: include.childProjection.aliases.map((alias, idx) => {
+        const column = include.childProjection.columns[idx];
+        if (!column || !alias) {
+          errorMissingColumnForAlias(alias ?? 'unknown', idx);
+        }
+
+        return {
+          alias,
+          expr: createColumnRef(column.table, column.column),
+        };
+      }),
+    },
+  };
+}

package/src/sql/join-builder.ts

@@ -0,0 +1,18 @@
+import type { JoinAst } from '@prisma-next/sql-relational-core/ast';
+import {
+  createColumnRef,
+  createJoin,
+  createJoinOnExpr,
+  createTableRef,
+} from '@prisma-next/sql-relational-core/ast';
+import type { JoinState } from '../utils/state';
+
+export function buildJoinAst(join: JoinState): JoinAst {
+  // TypeScript can't narrow ColumnBuilder properly, so we assert
+  const onLeft = join.on.left as { table: string; column: string };
+  const onRight = join.on.right as { table: string; column: string };
+  const leftCol = createColumnRef(onLeft.table, onLeft.column);
+  const rightCol = createColumnRef(onRight.table, onRight.column);
+  const onExpr = createJoinOnExpr(leftCol, rightCol);
+  return createJoin(join.joinType, createTableRef(join.table.name), onExpr);
+}