effect-qb 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-qb",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -33,11 +33,16 @@
       "types": "./src/mysql.ts",
       "import": "./dist/mysql.js"
     },
+    "./sqlite": {
+      "types": "./src/sqlite.ts",
+      "import": "./dist/sqlite.js"
+    },
     "./package.json": "./package.json"
   },
   "imports": {
     "#postgres": "./src/postgres.ts",
     "#mysql": "./src/mysql.ts",
+    "#sqlite": "./src/sqlite.ts",
     "#internal/*": "./src/internal/*"
   },
   "publishConfig": {
@@ -49,7 +54,7 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@typescript/native-preview": "latest"
+    "@typescript/native-preview": "beta"
   },
   "dependencies": {
     "@effect/experimental": "^0.57.0",

package/src/internal/column-state.ts

@@ -76,6 +76,7 @@ export interface ColumnState<
   readonly defaultValue?: DdlExpression
   readonly generatedValue?: DdlExpression
   readonly ddlType?: string
+  readonly driverValueMapping?: Expression.DriverValueMapping
   readonly identity?: {
     readonly generation: "always" | "byDefault"
   }
@@ -137,6 +138,7 @@ export interface ColumnDefinition<
     readonly defaultValue?: DdlExpression
     readonly generatedValue?: DdlExpression
     readonly ddlType?: string
+    readonly driverValueMapping?: Expression.DriverValueMapping
     readonly identity?: {
       readonly generation: "always" | "byDefault"
     }
@@ -289,6 +291,7 @@ export const makeColumnDefinition = <
     runtime: undefined as Select,
     dbType: metadata.dbType,
     runtimeSchema: schema,
+    driverValueMapping: metadata.driverValueMapping,
     nullability: (metadata.nullable ? "maybe" : "never") as Nullable extends true ? "maybe" : "never",
     dialect: metadata.dbType.dialect,
     kind: "scalar",
@@ -308,6 +311,7 @@ export const makeColumnDefinition = <
     defaultValue: metadata.defaultValue,
     generatedValue: metadata.generatedValue,
     ddlType: metadata.ddlType,
+    driverValueMapping: metadata.driverValueMapping,
     identity: metadata.identity,
     enum: metadata.enum
   }
@@ -379,6 +383,7 @@ export const remapColumnDefinition = <
     runtime: undefined as Select,
     dbType: metadata.dbType,
     runtimeSchema: schema,
+    driverValueMapping: metadata.driverValueMapping,
     nullability: (metadata.nullable ? "maybe" : "never") as Nullable extends true ? "maybe" : "never",
     dialect: metadata.dbType.dialect
   }
@@ -397,6 +402,7 @@ export const remapColumnDefinition = <
     defaultValue: metadata.defaultValue,
     generatedValue: metadata.generatedValue,
     ddlType: metadata.ddlType,
+    driverValueMapping: metadata.driverValueMapping,
     identity: metadata.identity,
     enum: metadata.enum
   }
@@ -443,6 +449,7 @@ export const bindColumn = <
     runtime: undefined as SelectType<Column>,
     dbType: column.metadata.dbType,
     runtimeSchema: schema,
+    driverValueMapping: column.metadata.driverValueMapping,
     nullability: (column.metadata.nullable ? "maybe" : "never") as IsNullable<Column> extends true ? "maybe" : "never",
     dialect: column.metadata.dbType.dialect,
     kind: "scalar",

package/src/internal/column.ts

@@ -123,6 +123,20 @@ type DdlTypedColumn<Column extends AnyColumnDefinition> = ColumnDefinition<
   ReferencesOf<Column>
 > & PreserveBrand<Column>
 
+type DriverValueMappedColumn<Column extends AnyColumnDefinition> = ColumnDefinition<
+  SelectType<Column>,
+  InsertType<Column>,
+  UpdateType<Column>,
+  Column[typeof ColumnTypeId]["dbType"],
+  IsNullable<Column>,
+  HasDefault<Column>,
+  IsGenerated<Column>,
+  IsPrimaryKey<Column>,
+  Column[typeof ColumnTypeId]["unique"],
+  ReferencesOf<Column>,
+  Column[typeof ColumnTypeId]["dependencies"]
+> & PreserveBrand<Column>
+
 type GeneratedColumn<Column extends AnyColumnDefinition> = ColumnDefinition<
   SelectType<Column>,
   InsertType<Column>,
@@ -543,6 +557,14 @@ export const ddlType = <SqlType extends string>(sqlType: SqlType) =>
       ddlType: sqlType
     }) as DdlTypedColumn<Column>
 
+/** Overrides how a column crosses the SQL driver boundary. */
+export const driverValueMapping = (mapping: Expression.DriverValueMapping) =>
+  <Column extends AnyColumnDefinition>(column: Column): DriverValueMappedColumn<Column> =>
+    mapColumn(column, {
+      ...column.metadata,
+      driverValueMapping: mapping
+    }) as DriverValueMappedColumn<Column>
+
 /** Marks a column as a Postgres array type. */
 export const array = <Options extends ArrayOptions | undefined = undefined>(
   options?: Options

package/src/internal/derived-table.ts

@@ -10,11 +10,13 @@ import {
   type LateralSource,
   type QueryPlan,
   getAst,
+  getQueryState,
   makeExpression,
+  currentRequiredList,
   type SelectionOfPlan
 } from "./query.js"
 import * as ExpressionAst from "./expression-ast.js"
-import { flattenSelection } from "./projections.js"
+import { flattenSelection, validateProjections } from "./projections.js"
 
 const DerivedProto = {
   pipe(this: unknown) {
@@ -55,6 +57,24 @@ const setPath = (
 
 const pathAlias = (path: readonly string[]): string => path.join("__")
 
+const assertSourceComplete = (
+  plan: QueryPlan<any, any, any, any, any, any, any, any, any, any>
+): void => {
+  const required = currentRequiredList(plan[Plan.TypeId].required)
+  if (required.length > 0) {
+    throw new Error(`query references sources that are not yet in scope: ${required.join(", ")}`)
+  }
+}
+
+const assertInlineSourceStatement = (
+  plan: QueryPlan<any, any, any, any, any, any, any, any, any, any>
+): void => {
+  const statement = getQueryState(plan).statement
+  if (statement !== "select" && statement !== "set") {
+    throw new Error("inline derived sources only accept select-like query plans")
+  }
+}
+
 const reboundedColumns = <
   PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>,
   Alias extends string
@@ -64,7 +84,9 @@ const reboundedColumns = <
 ): DerivedSelectionOf<SelectionOfPlan<PlanValue>, Alias> => {
   const ast = getAst(plan)
   const selection = {} as Record<string, unknown>
-  for (const projection of flattenSelection(ast.select as Record<string, unknown>)) {
+  const projections = flattenSelection(ast.select as Record<string, unknown>)
+  validateProjections(projections)
+  for (const projection of projections) {
     const expectedAlias = pathAlias(projection.path)
     if (projection.alias !== expectedAlias) {
       throw new Error(
@@ -98,6 +120,8 @@ export const makeDerivedSource = <
   plan: CompletePlan<PlanValue>,
   alias: Alias
 ): DerivedSource<PlanValue, Alias> => {
+  assertInlineSourceStatement(plan)
+  assertSourceComplete(plan)
   const columns = reboundedColumns(plan, alias)
   const derived = attachPipe(Object.create(DerivedProto)) as Record<string, unknown>
   Object.assign(derived, columns)
@@ -119,6 +143,7 @@ export const makeCteSource = <
   alias: Alias,
   recursive = false
 ): CteSource<PlanValue, Alias> => {
+  assertSourceComplete(plan)
   const columns = reboundedColumns(plan, alias)
   const cte = attachPipe(Object.create(DerivedProto)) as Record<string, unknown>
   Object.assign(cte, columns)
@@ -140,6 +165,7 @@ export const makeLateralSource = <
   plan: PlanValue,
   alias: Alias
 ): LateralSource<PlanValue, Alias> => {
+  assertInlineSourceStatement(plan)
   const columns = reboundedColumns(plan, alias)
   const lateral = attachPipe(Object.create(DerivedProto)) as Record<string, unknown>
   Object.assign(lateral, columns)
@@ -148,7 +174,7 @@ export const makeLateralSource = <
   lateral.baseName = alias
   lateral.dialect = plan[Plan.TypeId].dialect
   lateral.plan = plan
-  lateral.required = undefined as never
+  lateral.required = currentRequiredList(plan[Plan.TypeId].required) as never
   lateral.columns = columns
   return lateral as unknown as LateralSource<PlanValue, Alias>
 }

package/src/internal/dialect.ts

@@ -1,3 +1,7 @@
+import type * as Schema from "effect/Schema"
+
+import type * as Expression from "./scalar.js"
+
 /**
  * Mutable rendering state shared while serializing SQL for a concrete dialect.
  *
@@ -6,12 +10,21 @@
  */
 export interface RenderState {
   readonly params: unknown[]
+  readonly valueMappings?: Expression.DriverValueMappings
   readonly ctes: {
     readonly name: string
     readonly sql: string
     readonly recursive?: boolean
   }[]
   readonly cteNames: Set<string>
+  readonly cteSources: Map<string, unknown>
+  readonly rowLocalColumns?: boolean
+}
+
+export interface RenderValueContext {
+  readonly dbType?: Expression.DbType.Any
+  readonly runtimeSchema?: Schema.Schema.Any
+  readonly driverValueMapping?: Expression.DriverValueMapping
 }
 
 /**
@@ -24,7 +37,7 @@ export interface RenderState {
 export interface SqlDialect<Name extends string = string> {
   readonly name: Name
   quoteIdentifier(value: string): string
-  renderLiteral(value: unknown, state: RenderState): string
+  renderLiteral(value: unknown, state: RenderState, context?: RenderValueContext): string
   renderTableReference(tableName: string, baseTableName: string, schemaName?: string): string
   renderConcat(values: readonly string[]): string
 }

package/src/internal/dsl-mutation-runtime.ts

@@ -1,7 +1,11 @@
 import * as Expression from "./scalar.js"
 import * as Plan from "./row-set.js"
+import * as Table from "./table.js"
 
 type DslMutationRuntimeContext = {
+  readonly profile: {
+    readonly dialect: string
+  }
   readonly makePlan: (...args: readonly any[]) => any
   readonly getAst: (plan: any) => any
   readonly getQueryState: (plan: any) => any
@@ -14,13 +18,155 @@ type DslMutationRuntimeContext = {
   readonly buildConflictTarget: (target: any, input: any) => any
   readonly mutationTargetClauses: (target: any) => readonly any[]
   readonly mutationAvailableSources: (target: any) => Record<string, any>
-  readonly normalizeColumnList: (columns: string | readonly string[]) => readonly string[]
+  readonly normalizeConflictColumns: (target: any, columns: string | readonly string[]) => readonly string[]
   readonly targetSourceDetails: (target: any) => { readonly sourceName: string; readonly sourceBaseName: string }
   readonly sourceDetails: (source: any) => { readonly sourceName: string; readonly sourceBaseName: string }
 }
 
+export const expectInsertSourceKind = <
+  Source extends { readonly kind: string } | undefined
+>(
+  source: Source
+): Source => {
+  if (
+    source !== undefined &&
+    source.kind !== "values" &&
+    source.kind !== "query" &&
+    source.kind !== "unnest"
+  ) {
+    throw new Error("Unsupported insert source kind")
+  }
+  return source
+}
+
+export const expectConflictClause = <
+  Conflict extends {
+    readonly kind: string
+    readonly action: string
+    readonly target?: { readonly kind: string }
+  } | undefined
+>(
+  conflict: Conflict
+): Conflict => {
+  if (conflict === undefined) {
+    return conflict
+  }
+  if (conflict.kind !== "conflict") {
+    throw new Error("Unsupported conflict clause kind")
+  }
+  if (conflict.action !== "doNothing" && conflict.action !== "doUpdate") {
+    throw new Error("Unsupported conflict action")
+  }
+  if (
+    conflict.target !== undefined &&
+    conflict.target.kind !== "columns" &&
+    conflict.target.kind !== "constraint"
+  ) {
+    throw new Error("Unsupported conflict target kind")
+  }
+  return conflict
+}
+
 export const makeDslMutationRuntime = (ctx: DslMutationRuntimeContext) => {
+  const aliasedSourceKinds = new Set(["derived", "cte", "lateral", "values", "unnest", "tableFunction"])
+  const isRecord = (value: unknown): value is Record<PropertyKey, unknown> =>
+    typeof value === "object" && value !== null
+
+  const isTableTarget = (target: unknown): boolean =>
+    typeof target === "object" && target !== null && Table.TypeId in target && Plan.TypeId in target
+
+  const hasColumnRecord = (value: Record<PropertyKey, unknown>): boolean => isRecord(value.columns)
+
+  const isAliasedSource = (source: unknown): boolean => {
+    if (!isRecord(source)) {
+      return false
+    }
+    if (isTableTarget(source)) {
+      return true
+    }
+    if (!("kind" in source) || !("name" in source) || !("baseName" in source)) {
+      return false
+    }
+    if (typeof source.kind !== "string" || !aliasedSourceKinds.has(source.kind)) {
+      return false
+    }
+    if (typeof source.name !== "string" || typeof source.baseName !== "string") {
+      return false
+    }
+    switch (source.kind) {
+      case "derived":
+      case "cte":
+      case "lateral":
+        return isRecord(source.plan) && Plan.TypeId in source.plan && hasColumnRecord(source)
+      case "values":
+        return Array.isArray(source.rows) && hasColumnRecord(source)
+      case "unnest":
+        return isRecord(source.arrays) && hasColumnRecord(source)
+      case "tableFunction":
+        return typeof source.functionName === "string" && Array.isArray(source.args) && hasColumnRecord(source)
+    }
+    return false
+  }
+
+  const assertMutationTarget = (target: unknown, apiName: string): void => {
+    if (!isTableTarget(target)) {
+      throw new Error(`${apiName}(...) requires table targets`)
+    }
+  }
+
+  const assertAliasedSource = (source: unknown, apiName: string): void => {
+    if (!isAliasedSource(source)) {
+      throw new Error(`${apiName}(...) requires an aliased source`)
+    }
+  }
+
+  const assertMutationTargets = (
+    target: unknown,
+    apiName: string,
+    options: { readonly allowMultiple?: boolean } = {}
+  ): void => {
+    const targets = Array.isArray(target) ? target : [target]
+    if (targets.length === 0) {
+      throw new Error(`${apiName}(...) requires at least one table target`)
+    }
+    if (Array.isArray(target) && targets.length === 1) {
+      throw new Error(`${apiName}(...) requires a table target, not a single-element target tuple`)
+    }
+    for (const entry of targets) {
+      assertMutationTarget(entry, apiName)
+    }
+    if (targets.length > 1 && options.allowMultiple !== true) {
+      throw new Error(`${apiName}(...) requires a single table target`)
+    }
+    if (targets.length > 1 && ctx.profile.dialect !== "mysql" && ctx.profile.dialect !== "sqlite") {
+      throw new Error(`${apiName}(...) only supports multiple mutation targets for mysql`)
+    }
+  }
+
+  const assertUniqueTargetNames = (targets: readonly { readonly tableName: string }[]): void => {
+    const seen = new Set<string>()
+    for (const target of targets) {
+      if (seen.has(target.tableName)) {
+        throw new Error(`mutation target source names must be unique: ${target.tableName}`)
+      }
+      seen.add(target.tableName)
+    }
+  }
+
+  const assertInsertSelectSource = (sourcePlan: any, selection: Record<string, unknown>): void => {
+    const statement = ctx.getQueryState(sourcePlan).statement
+    if (statement !== "select" && statement !== "set") {
+      throw new Error("insert sources only accept select-like query plans")
+    }
+    for (const value of Object.values(selection)) {
+      if (value === null || typeof value !== "object" || !(Expression.TypeId in value)) {
+        throw new Error("insert sources require a flat selection object")
+      }
+    }
+  }
+
   const insert = (target: any, values?: Record<string, unknown>) => {
+    assertMutationTargets(target, "insert")
     const { sourceName, sourceBaseName } = ctx.targetSourceDetails(target)
     const assignments = values === undefined
       ? []
@@ -102,10 +248,11 @@ export const makeDslMutationRuntime = (ctx: DslMutationRuntimeContext) => {
 
     const sourcePlan = source
     const selection = sourcePlan[Plan.TypeId].selection as Record<string, Expression.Any>
+    assertInsertSelectSource(sourcePlan, selection)
     const columns = ctx.normalizeInsertSelectColumns(selection)
     return ctx.makePlan({
       selection: current.selection,
-      required: ctx.currentRequiredList(sourcePlan[Plan.TypeId].required).filter((name) => name !== sourceName),
+      required: ctx.currentRequiredList(sourcePlan[Plan.TypeId].required),
       available: current.available,
       dialect: current.dialect
     }, {
@@ -124,18 +271,26 @@ export const makeDslMutationRuntime = (ctx: DslMutationRuntimeContext) => {
       const current = plan[Plan.TypeId]
       const currentAst = ctx.getAst(plan)
       const currentQuery = ctx.getQueryState(plan)
+      if (currentQuery.statement !== "insert") {
+        throw new Error(`onConflict(...) is not supported for ${currentQuery.statement} statements`)
+      }
       const insertTarget = currentAst.into!.source
       const conflictTarget = ctx.buildConflictTarget(insertTarget, target)
       const updateAssignments = options.update
         ? ctx.buildMutationAssignments(insertTarget, options.update)
         : []
+      if (options.update !== undefined && updateAssignments.length === 0) {
+        throw new Error("conflict update assignments require at least one assignment")
+      }
       const updateWhere = options.where === undefined
         ? undefined
         : ctx.toDialectExpression(options.where)
+      const targetWhere = conflictTarget.kind === "columns" ? conflictTarget.where : undefined
       const required = [
         ...ctx.currentRequiredList(current.required),
         ...updateAssignments.flatMap((entry) => Object.keys(entry.value[Expression.TypeId].dependencies)),
-        ...(updateWhere ? Object.keys(updateWhere[Expression.TypeId].dependencies) : [])
+        ...(updateWhere ? Object.keys(updateWhere[Expression.TypeId].dependencies) : []),
+        ...(targetWhere ? Object.keys(targetWhere[Expression.TypeId].dependencies) : [])
       ].filter((name, index, list) =>
         !(name in current.available) && list.indexOf(name) === index)
       return ctx.makePlan({
@@ -156,7 +311,9 @@ export const makeDslMutationRuntime = (ctx: DslMutationRuntimeContext) => {
     }
 
   const update = (target: any, values: Record<string, unknown>) => {
+    assertMutationTargets(target, "update", { allowMultiple: true })
     const targets = ctx.mutationTargetClauses(target)
+    assertUniqueTargetNames(targets)
     const primaryTarget = targets[0]!
     const assignments = ctx.buildMutationAssignments(target, values)
     const targetNames = new Set(targets.map((entry: any) => entry.tableName))
@@ -183,9 +340,13 @@ export const makeDslMutationRuntime = (ctx: DslMutationRuntimeContext) => {
   }
 
   const upsert = (target: any, values: Record<string, unknown>, conflictColumns: string | readonly string[], updateValues?: Record<string, unknown>) => {
+    assertMutationTargets(target, "upsert")
     const { sourceName, sourceBaseName } = ctx.targetSourceDetails(target)
     const assignments = ctx.buildMutationAssignments(target, values)
     const updateAssignments = updateValues ? ctx.buildMutationAssignments(target, updateValues) : []
+    if (updateValues !== undefined && updateAssignments.length === 0) {
+      throw new Error("upsert update assignments require at least one assignment")
+    }
     const required = [
       ...assignments.flatMap((entry) => Object.keys(entry.value[Expression.TypeId].dependencies)),
       ...updateAssignments.flatMap((entry) => Object.keys(entry.value[Expression.TypeId].dependencies))
@@ -215,7 +376,7 @@ export const makeDslMutationRuntime = (ctx: DslMutationRuntimeContext) => {
         kind: "conflict",
         target: {
           kind: "columns",
-          columns: ctx.normalizeColumnList(conflictColumns) as readonly [string, ...string[]]
+          columns: ctx.normalizeConflictColumns(target, conflictColumns) as readonly [string, ...string[]]
         },
         action: updateAssignments.length > 0 ? "doUpdate" : "doNothing",
         values: updateAssignments.length > 0 ? updateAssignments : undefined
@@ -229,7 +390,9 @@ export const makeDslMutationRuntime = (ctx: DslMutationRuntimeContext) => {
   }
 
   const delete_ = (target: any) => {
+    assertMutationTargets(target, "delete", { allowMultiple: true })
     const targets = ctx.mutationTargetClauses(target)
+    assertUniqueTargetNames(targets)
     const primaryTarget = targets[0]!
     return ctx.makePlan({
       selection: {},
@@ -250,6 +413,7 @@ export const makeDslMutationRuntime = (ctx: DslMutationRuntimeContext) => {
   }
 
   const truncate = (target: any, options: { readonly restartIdentity?: boolean; readonly cascade?: boolean } = {}) => {
+    assertMutationTargets(target, "truncate")
     const { sourceName, sourceBaseName } = ctx.targetSourceDetails(target)
     return ctx.makePlan({
       selection: {},
@@ -279,8 +443,13 @@ export const makeDslMutationRuntime = (ctx: DslMutationRuntimeContext) => {
   }
 
   const merge = (target: any, source: any, on: any, options: any = {}) => {
+    assertMutationTargets(target, "merge")
+    assertAliasedSource(source, "merge")
     const { sourceName: targetName, sourceBaseName: targetBaseName } = ctx.targetSourceDetails(target)
     const { sourceName: usingName, sourceBaseName: usingBaseName } = ctx.sourceDetails(source)
+    if (targetName === usingName) {
+      throw new Error(`merge(...) source name must differ from target source name: ${targetName}`)
+    }
     const onExpression = ctx.toDialectExpression(on)
     const matched = options.whenMatched
     const notMatched = options.whenNotMatched