effect-qb 0.16.0 → 0.17.0

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

@@ -16,6 +16,8 @@ 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,6 +239,20 @@ 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],
@@ -262,8 +278,12 @@ const decodeProjectionValue = (
   }
 
   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,
@@ -289,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
   }
@@ -316,8 +347,8 @@ export const makeRowDecoder = (
   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
@@ -325,12 +356,19 @@ export const makeRowDecoder = (
   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,

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. */

package/src/internal/grouping-key.ts

@@ -1,5 +1,23 @@
 import * as Expression from "./scalar.js"
 import * as ExpressionAst from "./expression-ast.js"
+import * as JsonPath from "./json/path.js"
+import { columnPredicateKey } from "./predicate/runtime.js"
+
+const subqueryPlanIds = new WeakMap<object, string>()
+let nextSubqueryPlanId = 0
+
+const subqueryPlanGroupingKey = (plan: unknown): string => {
+  if (plan === null || typeof plan !== "object") {
+    return "unknown"
+  }
+  const existing = subqueryPlanIds.get(plan)
+  if (existing !== undefined) {
+    return existing
+  }
+  const next = `${nextSubqueryPlanId++}`
+  subqueryPlanIds.set(plan, next)
+  return next
+}
 
 const literalGroupingKey = (value: unknown): string => {
   if (value instanceof Date) {
@@ -20,17 +38,84 @@ const literalGroupingKey = (value: unknown): string => {
   }
 }
 
+const isExpression = (value: unknown): value is Expression.Any =>
+  value !== null && typeof value === "object" && Expression.TypeId in value
+
+const expressionGroupingKey = (value: unknown): string =>
+  isExpression(value) ? groupingKeyOfExpression(value) : "missing"
+
+const escapeGroupingText = (value: string): string =>
+  value
+    .replace(/\\/g, "\\\\")
+    .replace(/,/g, "\\,")
+    .replace(/\|/g, "\\|")
+    .replace(/=/g, "\\=")
+    .replace(/>/g, "\\>")
+
+const jsonSegmentGroupingKey = (segment: unknown): string => {
+  if (segment !== null && typeof segment === "object" && "kind" in segment) {
+    switch ((segment as { readonly kind: string }).kind) {
+      case "key":
+        return `key:${escapeGroupingText((segment as JsonPath.KeySegment).key)}`
+      case "index":
+        return `index:${(segment as JsonPath.IndexSegment).index}`
+      case "wildcard":
+        return "wildcard"
+      case "slice": {
+        const slice = segment as JsonPath.SliceSegment
+        return `slice:${slice.start ?? ""}:${slice.end ?? ""}`
+      }
+      case "descend":
+        return "descend"
+    }
+  }
+  if (typeof segment === "string") {
+    return `key:${escapeGroupingText(segment)}`
+  }
+  if (typeof segment === "number") {
+    return `index:${segment}`
+  }
+  return "unknown"
+}
+
+const jsonPathGroupingKey = (segments: readonly unknown[] | undefined): string =>
+  (segments ?? []).map(jsonSegmentGroupingKey).join(",")
+
+const isJsonPath = (value: unknown): value is JsonPath.Path =>
+  value !== null && typeof value === "object" && JsonPath.TypeId in value
+
+const jsonOpaquePathGroupingKey = (value: unknown): string => {
+  if (isJsonPath(value)) {
+    return `jsonpath:${jsonPathGroupingKey(value.segments)}`
+  }
+  if (typeof value === "string") {
+    return `jsonpath:${escapeGroupingText(value)}`
+  }
+  if (isExpression(value)) {
+    return `jsonpath:${groupingKeyOfExpression(value)}`
+  }
+  return "jsonpath:unknown"
+}
+
+const jsonEntryGroupingKey = (
+  entry: { readonly key: string; readonly value: Expression.Any }
+): string => `${escapeGroupingText(entry.key)}=>${groupingKeyOfExpression(entry.value)}`
+
 export const groupingKeyOfExpression = (expression: Expression.Any): string => {
   const ast = (expression as Expression.Any & {
     readonly [ExpressionAst.TypeId]: ExpressionAst.Any
   })[ExpressionAst.TypeId]
   switch (ast.kind) {
     case "column":
-      return `column:${ast.tableName}.${ast.columnName}`
+      return `column:${columnPredicateKey(ast.tableName, ast.columnName)}`
     case "literal":
       return `literal:${literalGroupingKey(ast.value)}`
     case "cast":
       return `cast(${groupingKeyOfExpression(ast.value)} as ${ast.target.dialect}:${ast.target.kind})`
+    case "collate":
+      return `collate(${groupingKeyOfExpression(ast.value)},${ast.collation.map(escapeGroupingText).join(",")})`
+    case "function":
+      return `function(${escapeGroupingText(ast.name)},${ast.args.map(groupingKeyOfExpression).join(",")})`
     case "isNull":
     case "isNotNull":
     case "not":
@@ -48,8 +133,15 @@ export const groupingKeyOfExpression = (expression: Expression.Any): string => {
     case "gte":
     case "like":
     case "ilike":
+    case "regexMatch":
+    case "regexIMatch":
+    case "regexNotMatch":
+    case "regexNotIMatch":
     case "isDistinctFrom":
     case "isNotDistinctFrom":
+    case "contains":
+    case "containedBy":
+    case "overlaps":
       return `${ast.kind}(${groupingKeyOfExpression(ast.left)},${groupingKeyOfExpression(ast.right)})`
     case "and":
     case "or":
@@ -62,6 +154,54 @@ export const groupingKeyOfExpression = (expression: Expression.Any): string => {
     case "case":
       return `case(${ast.branches.map((branch: ExpressionAst.CaseBranchNode) =>
         `when:${groupingKeyOfExpression(branch.when)}=>${groupingKeyOfExpression(branch.then)}`).join("|")};else:${groupingKeyOfExpression(ast.else)})`
+    case "exists":
+      return `exists(${subqueryPlanGroupingKey(ast.plan)})`
+    case "scalarSubquery":
+      return `scalarSubquery(${subqueryPlanGroupingKey(ast.plan)})`
+    case "inSubquery":
+      return `inSubquery(${groupingKeyOfExpression(ast.left)},${subqueryPlanGroupingKey(ast.plan)})`
+    case "comparisonAny":
+    case "comparisonAll":
+      return `${ast.kind}(${ast.operator},${groupingKeyOfExpression(ast.left)},${subqueryPlanGroupingKey(ast.plan)})`
+    case "jsonGet":
+    case "jsonPath":
+    case "jsonAccess":
+    case "jsonTraverse":
+    case "jsonGetText":
+    case "jsonPathText":
+    case "jsonAccessText":
+    case "jsonTraverseText":
+      return `json(${ast.kind},${expressionGroupingKey(ast.base)},${jsonPathGroupingKey(ast.segments)})`
+    case "jsonHasKey":
+    case "jsonKeyExists":
+    case "jsonHasAnyKeys":
+    case "jsonHasAllKeys":
+      return `json(${ast.kind},${expressionGroupingKey(ast.base)},${(ast.keys ?? []).map(escapeGroupingText).join(",")})`
+    case "jsonConcat":
+    case "jsonMerge":
+      return `json(${ast.kind},${expressionGroupingKey(ast.left)},${expressionGroupingKey(ast.right)},)`
+    case "jsonDelete":
+    case "jsonDeletePath":
+    case "jsonRemove":
+      return `json(${ast.kind},${expressionGroupingKey(ast.base)},${expressionGroupingKey(undefined)},${jsonPathGroupingKey(ast.segments)})`
+    case "jsonSet":
+      return `json(${ast.kind},${expressionGroupingKey(ast.base)},${expressionGroupingKey(ast.newValue)},${jsonPathGroupingKey(ast.segments)})`
+    case "jsonInsert":
+      return `json(${ast.kind},${expressionGroupingKey(ast.base)},${expressionGroupingKey(ast.insert)},${jsonPathGroupingKey(ast.segments)})`
+    case "jsonPathExists":
+    case "jsonPathMatch":
+      return `json(${ast.kind},${expressionGroupingKey(ast.base)},${jsonOpaquePathGroupingKey(ast.query)})`
+    case "jsonBuildObject":
+      return `json(${ast.kind},${(ast.entries ?? []).map(jsonEntryGroupingKey).join("|")})`
+    case "jsonBuildArray":
+      return `json(${ast.kind},${(ast.values ?? []).map(groupingKeyOfExpression).join(",")})`
+    case "jsonToJson":
+    case "jsonToJsonb":
+    case "jsonTypeOf":
+    case "jsonLength":
+    case "jsonKeys":
+    case "jsonStripNulls":
+      return `json(${ast.kind},${expressionGroupingKey(ast.value)})`
     default:
       throw new Error("Unsupported expression for grouping key generation")
   }

package/src/internal/implication-runtime.ts

@@ -5,6 +5,7 @@ import * as Table from "./table.js"
 import type { PredicateFormula } from "./predicate/formula.js"
 import {
   assumeFormulaTrue,
+  columnPredicateKey,
   contradictsFormula,
   guaranteedNonNullKeys,
   guaranteedNullKeys,
@@ -43,7 +44,7 @@ const collectPresenceWitnesses = (
     const expression = selection as unknown as AstBackedExpression
     const ast = expression[ExpressionAst.TypeId]
     if (ast.kind === "column" && expression[Expression.TypeId].nullability === "never") {
-      output.add(`${ast.tableName}.${ast.columnName}`)
+      output.add(columnPredicateKey(ast.tableName, ast.columnName))
     }
     return
   }