effect-qb 0.15.0 → 0.17.0

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

@@ -22,8 +22,122 @@ type DslPlanRuntimeContext = {
   readonly attachInsertSource: (plan: any, source: any) => any
 }
 
+export const renderSelectLockMode = (mode: unknown): string => {
+  switch (mode) {
+    case "update":
+      return "for update"
+    case "share":
+      return "for share"
+  }
+  throw new Error("lock(...) mode must be update or share for select statements")
+}
+
+export const renderMysqlMutationLockMode = (
+  mode: unknown,
+  statement: "update" | "delete"
+): string => {
+  switch (mode) {
+    case "lowPriority":
+      return " low_priority"
+    case "ignore":
+      return " ignore"
+    case "quick":
+      if (statement === "delete") {
+        return " quick"
+      }
+      break
+  }
+  throw new Error(
+    statement === "update"
+      ? "lock(...) mode must be lowPriority or ignore for update statements"
+      : "lock(...) mode must be lowPriority, quick, or ignore for delete statements"
+  )
+}
+
 export const makeDslPlanRuntime = (ctx: DslPlanRuntimeContext) => {
+  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 isPlan = (value: unknown): boolean => isRecord(value) && Plan.TypeId in value
+  const hasColumnRecord = (value: Record<PropertyKey, unknown>): boolean => isRecord(value.columns)
+
+  const sourceRequiredList = (source: any): readonly string[] =>
+    typeof source === "object" && source !== null && "required" in source
+      ? ctx.currentRequiredList(source.required)
+      : []
+
+  const isAliasedSource = (source: unknown): boolean => {
+    if (!isRecord(source)) {
+      return false
+    }
+    if (Table.TypeId in 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 isPlan(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 assertAliasedSource = (source: unknown, message: string): void => {
+    if (!isAliasedSource(source)) {
+      throw new Error(message)
+    }
+  }
+
+  const assertPlanComplete = (plan: any): void => {
+    const required = ctx.currentRequiredList(plan[Plan.TypeId].required)
+    if (required.length > 0) {
+      throw new Error(`query references sources that are not yet in scope: ${required.join(", ")}`)
+    }
+  }
+
+  const assertSourceNameAvailable = (available: Record<string, unknown>, sourceName: string): void => {
+    if (sourceName in available) {
+      throw new Error(`query source name is already in scope: ${sourceName}`)
+    }
+  }
+
+  const assertSelectHasBaseSourceForJoin = (statement: string, available: Record<string, unknown>): void => {
+    if (statement === "select" && Object.keys(available).length === 0) {
+      throw new Error("select joins require a from(...) source before joining")
+    }
+  }
+
+  const supportsJoinSources = (statement: string): boolean =>
+    statement === "select" || statement === "update" || statement === "delete"
+
+  const assertSetOperandStatement = (plan: any): void => {
+    const statement = ctx.getQueryState(plan).statement
+    if (statement !== "select" && statement !== "set") {
+      throw new Error("set operator operands only accept select-like query plans")
+    }
+  }
+
   const buildSetOperation = (kind: string, all: boolean, left: any, right: any) => {
+    assertSetOperandStatement(left)
+    assertSetOperandStatement(right)
+    assertPlanComplete(left)
+    assertPlanComplete(right)
     const leftState = left[Plan.TypeId]
     const leftAst = ctx.getAst(left)
     const basePlan = leftAst.kind === "set"
@@ -92,32 +206,33 @@ export const makeDslPlanRuntime = (ctx: DslPlanRuntimeContext) => {
         return ctx.attachInsertSource(plan, source)
       }
 
-      if (
-        typeof source !== "object" ||
-        source === null ||
-        ("kind" in source && source.kind === "values" && !("name" in source)) ||
-        (!(Table.TypeId in source) && !("name" in source && "baseName" in source))
-      ) {
-        throw new Error("from(...) requires an aliased source in select/update statements")
+      assertAliasedSource(source, "from(...) requires an aliased source in select/update statements")
+
+      if (currentQuery.statement === "select" && currentAst.from !== undefined) {
+        throw new Error("select statements accept only one from(...) source; use joins for additional sources")
       }
 
       const sourceLike = source
       const { sourceName, sourceBaseName } = ctx.sourceDetails(sourceLike)
       const presenceWitnesses = ctx.presenceWitnessesOfSourceLike(sourceLike)
+      const sourceRequired = sourceRequiredList(sourceLike)
+      assertSourceNameAvailable(current.available, sourceName)
 
       if (currentQuery.statement === "select") {
+        const nextAvailable = {
+          [sourceName]: {
+            name: sourceName,
+            mode: "required",
+            baseName: sourceBaseName,
+            _presentFormula: ctx.trueFormula(),
+            _presenceWitnesses: presenceWitnesses
+          }
+        }
         return ctx.makePlan({
           selection: current.selection,
-          required: ctx.currentRequiredList(current.required).filter((name) => name !== sourceName),
-          available: {
-            [sourceName]: {
-              name: sourceName,
-              mode: "required",
-              baseName: sourceBaseName,
-              _presentFormula: ctx.trueFormula(),
-              _presenceWitnesses: presenceWitnesses
-            }
-          },
+          required: [...ctx.currentRequiredList(current.required), ...sourceRequired].filter((name, index, values) =>
+            !(name in nextAvailable) && values.indexOf(name) === index),
+          available: nextAvailable,
           dialect: current.dialect
         }, {
           ...currentAst,
@@ -143,7 +258,8 @@ export const makeDslPlanRuntime = (ctx: DslPlanRuntimeContext) => {
         }
         return ctx.makePlan({
           selection: current.selection,
-          required: ctx.currentRequiredList(current.required).filter((name) => !(name in nextAvailable)),
+          required: [...ctx.currentRequiredList(current.required), ...sourceRequired].filter((name, index, values) =>
+            !(name in nextAvailable) && values.indexOf(name) === index),
           available: nextAvailable,
           dialect: current.dialect
         }, {
@@ -193,8 +309,16 @@ export const makeDslPlanRuntime = (ctx: DslPlanRuntimeContext) => {
       const current = plan[Plan.TypeId]
       const currentAst = ctx.getAst(plan)
       const currentQuery = ctx.getQueryState(plan)
+      if (supportsJoinSources(currentQuery.statement)) {
+        assertAliasedSource(table, "join(...) requires an aliased source in select/update/delete statements")
+        assertSelectHasBaseSourceForJoin(currentQuery.statement, current.available)
+      }
       const { sourceName, sourceBaseName } = ctx.sourceDetails(table)
       const presenceWitnesses = ctx.presenceWitnessesOfSourceLike(table)
+      const sourceRequired = sourceRequiredList(table)
+      if (supportsJoinSources(currentQuery.statement)) {
+        assertSourceNameAvailable(current.available, sourceName)
+      }
       const nextAvailable = {
         ...current.available,
         [sourceName]: {
@@ -207,7 +331,8 @@ export const makeDslPlanRuntime = (ctx: DslPlanRuntimeContext) => {
       }
       return ctx.makePlan({
         selection: current.selection,
-        required: ctx.currentRequiredList(current.required).filter((name) => !(name in nextAvailable)),
+        required: [...ctx.currentRequiredList(current.required), ...sourceRequired].filter((name, index, values) =>
+          !(name in nextAvailable) && values.indexOf(name) === index),
         available: nextAvailable,
         dialect: current.dialect ?? table[Plan.TypeId]?.dialect ?? table.dialect
       }, {
@@ -228,8 +353,16 @@ export const makeDslPlanRuntime = (ctx: DslPlanRuntimeContext) => {
       const currentQuery = ctx.getQueryState(plan)
       const onExpression = ctx.toDialectExpression(on)
       const onFormula = ctx.formulaOfExpressionRuntime(onExpression)
+      if (supportsJoinSources(currentQuery.statement)) {
+        assertAliasedSource(table, "join(...) requires an aliased source in select/update/delete statements")
+        assertSelectHasBaseSourceForJoin(currentQuery.statement, current.available)
+      }
       const { sourceName, sourceBaseName } = ctx.sourceDetails(table)
       const presenceWitnesses = ctx.presenceWitnessesOfSourceLike(table)
+      const sourceRequired = sourceRequiredList(table)
+      if (supportsJoinSources(currentQuery.statement)) {
+        assertSourceNameAvailable(current.available, sourceName)
+      }
       const baseAvailable = (kind === "right" || kind === "full"
         ? Object.fromEntries(
           Object.entries(current.available as Record<string, any>).map(([name, source]) => [name, {
@@ -253,7 +386,7 @@ export const makeDslPlanRuntime = (ctx: DslPlanRuntimeContext) => {
       }
       return ctx.makePlan({
         selection: current.selection,
-        required: [...ctx.currentRequiredList(current.required), ...ctx.extractRequiredFromDialectInputRuntime(on)].filter((name, index, values) =>
+        required: [...ctx.currentRequiredList(current.required), ...sourceRequired, ...ctx.extractRequiredFromDialectInputRuntime(on)].filter((name, index, values) =>
           !(name in nextAvailable) && values.indexOf(name) === index),
         available: nextAvailable,
         dialect: current.dialect ?? table.dialect ?? onExpression[Expression.TypeId].dialect
@@ -275,6 +408,9 @@ export const makeDslPlanRuntime = (ctx: DslPlanRuntimeContext) => {
 
   const orderBy = (value: any, direction: "asc" | "desc" = "asc") =>
     (plan: any) => {
+      if (direction !== "asc" && direction !== "desc") {
+        throw new Error("orderBy(...) direction must be asc or desc")
+      }
       const current = plan[Plan.TypeId]
       const currentAst = ctx.getAst(plan)
       const currentQuery = ctx.getQueryState(plan)
@@ -301,6 +437,15 @@ export const makeDslPlanRuntime = (ctx: DslPlanRuntimeContext) => {
       const current = plan[Plan.TypeId]
       const currentAst = ctx.getAst(plan)
       const currentQuery = ctx.getQueryState(plan)
+      if (currentQuery.statement === "select") {
+        renderSelectLockMode(mode)
+      }
+      if (ctx.profile.dialect === "mysql" && currentQuery.statement === "update") {
+        renderMysqlMutationLockMode(mode, "update")
+      }
+      if (ctx.profile.dialect === "mysql" && currentQuery.statement === "delete") {
+        renderMysqlMutationLockMode(mode, "delete")
+      }
       return ctx.makePlan({
         selection: current.selection,
         required: current.required,

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

@@ -1,5 +1,6 @@
 import * as Expression from "./scalar.js"
 import * as Plan from "./row-set.js"
+import { flattenSelection } from "./projections.js"
 
 type DslQueryRuntimeContext = {
   readonly profile: {
@@ -19,6 +20,36 @@ type DslQueryRuntimeContext = {
 }
 
 export const makeDslQueryRuntime = (ctx: DslQueryRuntimeContext) => {
+  const assertSelectionObject = (apiName: string, selection: any): void => {
+    if (
+      selection === null ||
+      typeof selection !== "object" ||
+      Array.isArray(selection) ||
+      Expression.TypeId in selection
+    ) {
+      throw new Error(`${apiName}(...) expects a projection object`)
+    }
+  }
+
+  const assertSelectionTree = (apiName: string, selection: any): void => {
+    const visit = (value: any, isRoot: boolean): void => {
+      if (value !== null && typeof value === "object" && Expression.TypeId in value) {
+        return
+      }
+      if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${apiName}(...) selection leaves must be expressions`)
+      }
+      const nested = Object.values(value)
+      if (!isRoot && nested.length === 0) {
+        throw new Error(`${apiName}(...) projection objects cannot contain empty nested selections`)
+      }
+      for (const item of nested) {
+        visit(item, false)
+      }
+    }
+    visit(selection, true)
+  }
+
   const values = (rows: readonly [Record<string, any>, ...Record<string, any>[]]) => {
     if (rows.length === 0) {
       throw new Error("values(...) requires at least one row")
@@ -28,10 +59,14 @@ export const makeDslQueryRuntime = (ctx: DslQueryRuntimeContext) => {
       ...Record<string, Expression.Any>[]
     ]
     const columnNames = Object.keys(normalizedRows[0]!)
+    if (columnNames.length === 0) {
+      throw new Error("values(...) rows must specify at least one column")
+    }
+    const columnNameSet = new Set(columnNames)
     for (const row of normalizedRows) {
       const rowKeys = Object.keys(row)
-      if (rowKeys.length !== columnNames.length || !rowKeys.every((key, index) => key === columnNames[index])) {
-        throw new Error("values(...) rows must project the same columns in the same order")
+      if (rowKeys.length !== columnNames.length || !rowKeys.every((key) => columnNameSet.has(key))) {
+        throw new Error("values(...) rows must project the same columns")
       }
     }
     return Object.assign(Object.create(ctx.ValuesInputProto), {
@@ -97,8 +132,10 @@ export const makeDslQueryRuntime = (ctx: DslQueryRuntimeContext) => {
     return Object.assign(source, columns)
   }
 
-  const select = (selection: any) =>
-    ctx.makePlan({
+  const select = (selection: any = {}) => {
+    assertSelectionObject("select", selection)
+    assertSelectionTree("select", selection)
+    return ctx.makePlan({
       selection,
       required: ctx.extractRequiredRuntime(selection),
       available: {},
@@ -112,9 +149,13 @@ export const makeDslQueryRuntime = (ctx: DslQueryRuntimeContext) => {
       groupBy: [],
       orderBy: []
     }, undefined, "read", "select")
+  }
 
   const groupBy = (...values: readonly Expression.Any[]) =>
     (plan: any) => {
+      if (values.length === 0) {
+        throw new Error("groupBy(...) requires at least one expression")
+      }
       const current = plan[Plan.TypeId]
       const currentAst = ctx.getAst(plan)
       const currentQuery = ctx.getQueryState(plan)
@@ -132,11 +173,23 @@ export const makeDslQueryRuntime = (ctx: DslQueryRuntimeContext) => {
       }, currentQuery.assumptions, currentQuery.capabilities, currentQuery.statement)
     }
 
-  const returning = (selection: any) =>
-    (plan: any) => {
+  const returning = (selection: any) => {
+    assertSelectionObject("returning", selection)
+    assertSelectionTree("returning", selection)
+    if (flattenSelection(selection as Record<string, unknown>).length === 0) {
+      throw new Error("returning(...) requires at least one selected expression")
+    }
+    return (plan: any) => {
       const current = plan[Plan.TypeId]
       const currentAst = ctx.getAst(plan)
       const currentQuery = ctx.getQueryState(plan)
+      if (
+        currentQuery.statement !== "insert" &&
+        currentQuery.statement !== "update" &&
+        currentQuery.statement !== "delete"
+      ) {
+        throw new Error(`returning(...) is not supported for ${currentQuery.statement} statements`)
+      }
       return ctx.makePlan({
         selection,
         required: [...ctx.currentRequiredList(current.required), ...ctx.extractRequiredRuntime(selection)].filter((name, index, list) =>
@@ -148,6 +201,7 @@ export const makeDslQueryRuntime = (ctx: DslQueryRuntimeContext) => {
         select: selection
       }, currentQuery.assumptions, currentQuery.capabilities, currentQuery.statement, currentQuery.target, currentQuery.insertSource)
     }
+  }
 
   return {
     values,

package/src/internal/dsl-transaction-ddl-runtime.ts

@@ -1,4 +1,5 @@
 import * as Plan from "./row-set.js"
+import * as Table from "./table.js"
 
 type DslTransactionDdlRuntimeContext = {
   readonly profile: {
@@ -10,9 +11,71 @@ type DslTransactionDdlRuntimeContext = {
   readonly defaultIndexName: (tableName: string, columns: readonly string[], unique: boolean) => string
 }
 
+const allowedIsolationLevels = new Set(["read committed", "repeatable read", "serializable"])
+
+export const renderTransactionIsolationLevel = (isolationLevel: unknown): string => {
+  if (isolationLevel === undefined) {
+    return ""
+  }
+  if (typeof isolationLevel !== "string" || !allowedIsolationLevels.has(isolationLevel)) {
+    throw new Error("Unsupported transaction isolation level")
+  }
+  return `isolation level ${isolationLevel}`
+}
+
+export const expectDdlClauseKind = <
+  Ddl extends { readonly kind: string },
+  Kind extends Ddl["kind"]
+>(
+  ddl: Ddl | undefined,
+  kind: Kind
+): Extract<Ddl, { readonly kind: Kind }> => {
+  if (ddl === undefined || ddl.kind !== kind) {
+    throw new Error("Unsupported DDL statement kind")
+  }
+  return ddl as Extract<Ddl, { readonly kind: Kind }>
+}
+
+export const expectTruncateClause = <
+  Truncate extends { readonly kind: string }
+>(
+  truncate: Truncate | undefined
+): Extract<Truncate, { readonly kind: "truncate" }> => {
+  if (truncate === undefined || truncate.kind !== "truncate") {
+    throw new Error("Unsupported truncate statement kind")
+  }
+  return truncate as Extract<Truncate, { readonly kind: "truncate" }>
+}
+
+const validateIsolationLevel = (isolationLevel: unknown): void => {
+  renderTransactionIsolationLevel(isolationLevel)
+}
+
 export const makeDslTransactionDdlRuntime = (ctx: DslTransactionDdlRuntimeContext) => {
-  const transaction = (options: { readonly isolationLevel?: any; readonly readOnly?: boolean } = {}) =>
-    ctx.makePlan({
+  const isRecord = (value: unknown): value is Record<PropertyKey, unknown> =>
+    typeof value === "object" && value !== null
+
+  const assertTableTarget = (target: unknown, apiName: string): void => {
+    if (!isRecord(target) || !(Table.TypeId in target) || !(Plan.TypeId in target)) {
+      throw new Error(`${apiName}(...) requires a table target`)
+    }
+  }
+
+  const validateIndexColumns = (target: any, columns: readonly string[]): void => {
+    const fields = target[Table.TypeId]?.fields as Record<string, unknown> | undefined
+    if (fields === undefined) {
+      return
+    }
+    for (const columnName of columns) {
+      if (!(columnName in fields)) {
+        throw new Error(`effect-qb: unknown index column '${columnName}'`)
+      }
+    }
+  }
+
+  const transaction = (options: { readonly isolationLevel?: any; readonly readOnly?: boolean } = {}) => {
+    validateIsolationLevel(options.isolationLevel)
+    return ctx.makePlan({
       selection: {},
       required: [],
       available: {},
@@ -31,6 +94,7 @@ export const makeDslTransactionDdlRuntime = (ctx: DslTransactionDdlRuntimeContex
       groupBy: [],
       orderBy: []
     }, undefined, "transaction", "transaction")
+  }
 
   const commit = () =>
     ctx.makePlan({
@@ -131,6 +195,7 @@ export const makeDslTransactionDdlRuntime = (ctx: DslTransactionDdlRuntimeContex
     }, undefined, "transaction", "releaseSavepoint")
 
   const createTable = (target: any, options: { readonly ifNotExists?: boolean } = {}) => {
+    assertTableTarget(target, "createTable")
     const { sourceName, sourceBaseName } = ctx.targetSourceDetails(target)
     return ctx.makePlan({
       selection: {},
@@ -159,6 +224,7 @@ export const makeDslTransactionDdlRuntime = (ctx: DslTransactionDdlRuntimeContex
   }
 
   const dropTable = (target: any, options: { readonly ifExists?: boolean } = {}) => {
+    assertTableTarget(target, "dropTable")
     const { sourceName, sourceBaseName } = ctx.targetSourceDetails(target)
     return ctx.makePlan({
       selection: {},
@@ -187,7 +253,9 @@ export const makeDslTransactionDdlRuntime = (ctx: DslTransactionDdlRuntimeContex
   }
 
   const createIndex = (target: any, columns: string | readonly string[], options: { readonly name?: string; readonly unique?: boolean; readonly ifNotExists?: boolean } = {}) => {
+    assertTableTarget(target, "createIndex")
     const normalizedColumns = ctx.normalizeColumnList(columns)
+    validateIndexColumns(target, normalizedColumns)
     const { sourceName, sourceBaseName } = ctx.targetSourceDetails(target)
     return ctx.makePlan({
       selection: {},
@@ -219,7 +287,9 @@ export const makeDslTransactionDdlRuntime = (ctx: DslTransactionDdlRuntimeContex
   }
 
   const dropIndex = (target: any, columns: string | readonly string[], options: { readonly name?: string; readonly ifExists?: boolean } = {}) => {
+    assertTableTarget(target, "dropIndex")
     const normalizedColumns = ctx.normalizeColumnList(columns)
+    validateIndexColumns(target, normalizedColumns)
     const { sourceName, sourceBaseName } = ctx.targetSourceDetails(target)
     return ctx.makePlan({
       selection: {},

package/src/internal/executor.ts

@@ -9,13 +9,15 @@ import * as Stream from "effect/Stream"
 import * as Expression from "./scalar.js"
 import * as ExpressionAst from "./expression-ast.js"
 import { resolveImplicationScope, type ImplicationScope } from "./implication-runtime.js"
-import { normalizeDbValue } from "./runtime/normalize.js"
+import { fromDriverValue } from "./runtime/driver-value-mapping.js"
 import { expressionRuntimeSchema } from "./runtime/schema.js"
 import { flattenSelection } from "./projections.js"
 import * as Query from "./query.js"
 import * as QueryAst from "./query-ast.js"
 import * as Renderer from "./renderer.js"
 import * as Plan from "./row-set.js"
+import { columnPredicateKey } from "./predicate/runtime.js"
+import { isJsonValue } from "./runtime/normalize.js"
 
 /** Flat database row keyed by rendered projection aliases. */
 export type FlatRow = Readonly<Record<string, unknown>>
@@ -221,7 +223,7 @@ const effectiveRuntimeNullability = (
     return "always"
   }
   if (ast.kind === "column") {
-    const key = `${ast.tableName}.${ast.columnName}`
+    const key = columnPredicateKey(ast.tableName, ast.columnName)
     if (scope.absentSourceNames.has(ast.tableName) || scope.nullKeys.has(key)) {
       return "always"
     }
@@ -237,26 +239,51 @@ const effectiveRuntimeNullability = (
     : nullability
 }
 
+const dbTypeAllowsTopLevelJsonNull = (
+  dbType: Expression.DbType.Any
+): boolean => {
+  if ("base" in dbType) {
+    return dbTypeAllowsTopLevelJsonNull(dbType.base)
+  }
+  return ("variant" in dbType && dbType.variant === "json") || dbType.runtime === "json"
+}
+
+const schemaAcceptsNull = (
+  schema: Schema.Schema.Any | undefined
+): boolean =>
+  schema !== undefined && (Schema.is(schema) as (value: unknown) => boolean)(null)
+
 const decodeProjectionValue = (
   rendered: Renderer.RenderedQuery<any, any>,
   projection: Renderer.RenderedQuery<any, any>["projections"][number],
   expression: Expression.Any,
   raw: unknown,
   scope: ImplicationScope,
-  driverMode: DriverMode
+  driverMode: DriverMode,
+  valueMappings?: Expression.DriverValueMappings
 ): unknown => {
   let normalized = raw
   if (driverMode === "raw") {
     try {
-      normalized = normalizeDbValue(expression[Expression.TypeId].dbType, raw)
+      normalized = fromDriverValue(raw, {
+        dialect: rendered.dialect,
+        dbType: expression[Expression.TypeId].dbType,
+        runtimeSchema: expression[Expression.TypeId].runtimeSchema,
+        driverValueMapping: expression[Expression.TypeId].driverValueMapping,
+        valueMappings
+      })
     } catch (cause) {
       throw makeRowDecodeError(rendered, projection, expression, raw, "normalize", cause)
     }
   }
 
   const nullability = effectiveRuntimeNullability(expression, scope)
+  const schema = expressionRuntimeSchema(expression, { assumptions: scope.assumptions })
   if (normalized === null) {
     if (nullability === "never") {
+      if (dbTypeAllowsTopLevelJsonNull(expression[Expression.TypeId].dbType) && schemaAcceptsNull(schema)) {
+        return null
+      }
       throw makeRowDecodeError(
         rendered,
         projection,
@@ -282,7 +309,18 @@ const decodeProjectionValue = (
     )
   }
 
-  const schema = expressionRuntimeSchema(expression, { assumptions: scope.assumptions })
+  if (dbTypeAllowsTopLevelJsonNull(expression[Expression.TypeId].dbType) && !isJsonValue(normalized)) {
+    throw makeRowDecodeError(
+      rendered,
+      projection,
+      expression,
+      raw,
+      "schema",
+      new Error("Expected a JSON value"),
+      normalized
+    )
+  }
+
   if (schema === undefined) {
     return normalized
   }
@@ -303,30 +341,39 @@ export const makeRowDecoder = (
   plan: Query.Plan.Any,
   options: {
     readonly driverMode?: DriverMode
+    readonly valueMappings?: Expression.DriverValueMappings
   } = {}
 ): ((row: FlatRow) => any) => {
   const projections = flattenSelection(
     Query.getAst(plan).select as Record<string, unknown>
   )
-  const byAlias = new Map(
-    projections.map((projection) => [projection.alias, projection.expression] as const)
+  const byPath = new Map(
+    projections.map((projection) => [JSON.stringify(projection.path), projection.expression] as const)
   )
   const driverMode = options.driverMode ?? "raw"
+  const valueMappings = options.valueMappings ?? rendered.valueMappings
   const scope = resolveImplicationScope(plan[Plan.TypeId].available, Query.getQueryState(plan).assumptions)
   return (row) => {
     const decoded: Record<string, unknown> = {}
     for (const projection of rendered.projections) {
-      if (!(projection.alias in row)) {
-        continue
-      }
-      const expression = byAlias.get(projection.alias)
+      const expression = byPath.get(JSON.stringify(projection.path))
       if (expression === undefined) {
-        continue
+        throw new Error(`Rendered projection path '${projection.path.join(".")}' does not exist in the query selection`)
+      }
+      if (!(projection.alias in row)) {
+        throw makeRowDecodeError(
+          rendered,
+          projection,
+          expression,
+          undefined,
+          "schema",
+          new Error(`Missing required projection alias '${projection.alias}'`)
+        )
       }
       setPath(
         decoded,
         projection.path,
-        decodeProjectionValue(rendered, projection, expression, row[projection.alias], scope, driverMode)
+        decodeProjectionValue(rendered, projection, expression, row[projection.alias], scope, driverMode, valueMappings)
       )
     }
     return decoded
@@ -339,6 +386,7 @@ export const decodeChunk = (
   rows: Chunk.Chunk<FlatRow>,
   options: {
     readonly driverMode?: DriverMode
+    readonly valueMappings?: Expression.DriverValueMappings
   } = {}
 ): Chunk.Chunk<any> => {
   const decodeRow = makeRowDecoder(rendered, plan, options)
@@ -351,6 +399,7 @@ export const decodeRows = (
   rows: ReadonlyArray<FlatRow>,
   options: {
     readonly driverMode?: DriverMode
+    readonly valueMappings?: Expression.DriverValueMappings
   } = {}
 ): ReadonlyArray<any> => {
   const decodeRow = makeRowDecoder(rendered, plan, options)

package/src/internal/expression-ast.ts

@@ -36,11 +36,12 @@ export interface CastNode<
 
 /** Explicit collation captured by the internal expression AST. */
 export interface CollateNode<
-  Value extends Expression.Any = Expression.Any
+  Value extends Expression.Any = Expression.Any,
+  Collation extends readonly [string, ...string[]] = readonly [string, ...string[]]
 > {
   readonly kind: "collate"
   readonly value: Value
-  readonly collation: readonly [string, ...string[]]
+  readonly collation: Collation
 }
 
 /** General SQL function call captured by the internal expression AST. */