npm - effect-qb - Versions diffs - 0.12.3 - Mend

effect-qb 0.12.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (81) hide show

package/README.md +1294 -0
package/dist/mysql.js +57575 -0
package/dist/postgres.js +6303 -0
package/package.json +42 -0
package/src/internal/aggregation-validation.ts +57 -0
package/src/internal/case-analysis.ts +50 -0
package/src/internal/coercion-analysis.ts +30 -0
package/src/internal/coercion-errors.ts +29 -0
package/src/internal/coercion-kind.ts +32 -0
package/src/internal/coercion-normalize.ts +7 -0
package/src/internal/coercion-rules.ts +25 -0
package/src/internal/column-state.ts +453 -0
package/src/internal/column.ts +417 -0
package/src/internal/datatypes/define.ts +44 -0
package/src/internal/datatypes/lookup.ts +280 -0
package/src/internal/datatypes/shape.ts +72 -0
package/src/internal/derived-table.ts +149 -0
package/src/internal/dialect.ts +30 -0
package/src/internal/executor.ts +390 -0
package/src/internal/expression-ast.ts +349 -0
package/src/internal/expression.ts +325 -0
package/src/internal/grouping-key.ts +82 -0
package/src/internal/json/ast.ts +63 -0
package/src/internal/json/errors.ts +13 -0
package/src/internal/json/path.ts +227 -0
package/src/internal/json/shape.ts +1 -0
package/src/internal/json/types.ts +386 -0
package/src/internal/mysql-dialect.ts +39 -0
package/src/internal/mysql-renderer.ts +37 -0
package/src/internal/plan.ts +64 -0
package/src/internal/postgres-dialect.ts +34 -0
package/src/internal/postgres-renderer.ts +40 -0
package/src/internal/predicate-analysis.ts +71 -0
package/src/internal/predicate-atom.ts +43 -0
package/src/internal/predicate-branches.ts +40 -0
package/src/internal/predicate-context.ts +279 -0
package/src/internal/predicate-formula.ts +100 -0
package/src/internal/predicate-key.ts +28 -0
package/src/internal/predicate-nnf.ts +12 -0
package/src/internal/predicate-normalize.ts +202 -0
package/src/internal/projection-alias.ts +15 -0
package/src/internal/projections.ts +101 -0
package/src/internal/query-ast.ts +297 -0
package/src/internal/query-factory.ts +6757 -0
package/src/internal/query-requirements.ts +40 -0
package/src/internal/query.ts +1590 -0
package/src/internal/renderer.ts +102 -0
package/src/internal/runtime-normalize.ts +344 -0
package/src/internal/runtime-schema.ts +428 -0
package/src/internal/runtime-value.ts +85 -0
package/src/internal/schema-derivation.ts +131 -0
package/src/internal/sql-expression-renderer.ts +1353 -0
package/src/internal/table-options.ts +225 -0
package/src/internal/table.ts +674 -0
package/src/mysql/column.ts +30 -0
package/src/mysql/datatypes/index.ts +6 -0
package/src/mysql/datatypes/spec.ts +180 -0
package/src/mysql/errors/catalog.ts +51662 -0
package/src/mysql/errors/fields.ts +21 -0
package/src/mysql/errors/index.ts +18 -0
package/src/mysql/errors/normalize.ts +232 -0
package/src/mysql/errors/requirements.ts +73 -0
package/src/mysql/executor.ts +134 -0
package/src/mysql/query.ts +189 -0
package/src/mysql/renderer.ts +19 -0
package/src/mysql/table.ts +157 -0
package/src/mysql.ts +18 -0
package/src/postgres/column.ts +20 -0
package/src/postgres/datatypes/index.ts +8 -0
package/src/postgres/datatypes/spec.ts +264 -0
package/src/postgres/errors/catalog.ts +452 -0
package/src/postgres/errors/fields.ts +48 -0
package/src/postgres/errors/index.ts +4 -0
package/src/postgres/errors/normalize.ts +209 -0
package/src/postgres/errors/requirements.ts +65 -0
package/src/postgres/errors/types.ts +38 -0
package/src/postgres/executor.ts +131 -0
package/src/postgres/query.ts +189 -0
package/src/postgres/renderer.ts +29 -0
package/src/postgres/table.ts +157 -0
package/src/postgres.ts +18 -0

package/src/internal/predicate-normalize.ts ADDED Viewed

@@ -0,0 +1,202 @@
+import type * as Expression from "./expression.js"
+import type * as ExpressionAst from "./expression-ast.js"
+import type { ColumnKeyOfExpression, ValueKey } from "./predicate-key.js"
+import type { AllFormula, AnyFormula, AtomFormula, FalseFormula, NotFormula, PredicateFormula, TrueFormula } from "./predicate-formula.js"
+import type { EqColumnAtom, EqLiteralAtom, NeqLiteralAtom, NonNullAtom, NullAtom, UnknownAtom } from "./predicate-atom.js"
+type AstOf<Value extends Expression.Any> = Value extends {
+  readonly [ExpressionAst.TypeId]: infer Ast extends ExpressionAst.Any
+} ? Ast : never
+type LiteralValueOfExpression<Value extends Expression.Any> = AstOf<Value> extends ExpressionAst.LiteralNode<infer Literal>
+  ? Literal
+  : never
+type True = TrueFormula
+type False = FalseFormula
+type UnknownTag<Tag extends string> = AtomFormula<UnknownAtom<Tag>>
+type AtomOf<Atom extends import("./predicate-atom.js").PredicateAtom> = AtomFormula<Atom>
+type FactOf<Atom extends import("./predicate-atom.js").PredicateAtom> = AtomFormula<Atom>
+type NonNullFactsOfExpression<Value extends Expression.Any> =
+  [ColumnKeyOfExpression<Value>] extends [never]
+    ? never
+    : FactOf<NonNullAtom<ColumnKeyOfExpression<Value>>>
+type CombineFacts<
+  Left extends PredicateFormula,
+  Right extends PredicateFormula
+> = [Left] extends [never]
+  ? Right
+  : [Right] extends [never]
+    ? Left
+    : import("./predicate-formula.js").NormalizeBooleanConstants<AllFormula<[Left, Right]>>
+type FactsOfExpressions<Values extends readonly Expression.Any[]> =
+  Values extends readonly [
+    infer Head extends Expression.Any,
+    ...infer Tail extends readonly Expression.Any[]
+  ]
+    ? CombineFacts<FormulaOfExpression<Head>, FactsOfExpressions<Tail>>
+    : never
+type FormulaOfEq<
+  Left extends Expression.Any,
+  Right extends Expression.Any
+> =
+  [ColumnKeyOfExpression<Left>] extends [never]
+    ? [ColumnKeyOfExpression<Right>] extends [never]
+      ? LiteralValueOfExpression<Left> extends infer LeftLiteral
+        ? LiteralValueOfExpression<Right> extends infer RightLiteral
+          ? [LeftLiteral] extends [never]
+            ? UnknownTag<"eq:unsupported">
+            : [RightLiteral] extends [never]
+              ? UnknownTag<"eq:unsupported">
+              : LeftLiteral extends null
+                ? False
+                : RightLiteral extends null
+                  ? False
+              : [LeftLiteral] extends [RightLiteral]
+                ? True
+                : False
+          : UnknownTag<"eq:unsupported">
+        : UnknownTag<"eq:unsupported">
+      : LiteralValueOfExpression<Left> extends infer LeftLiteral
+        ? [LeftLiteral] extends [never]
+          ? UnknownTag<"eq:unsupported">
+          : LeftLiteral extends null
+            ? False
+            : AtomOf<EqLiteralAtom<ColumnKeyOfExpression<Right>, ValueKey<LeftLiteral>>>
+        : UnknownTag<"eq:unsupported">
+    : [ColumnKeyOfExpression<Right>] extends [never]
+      ? LiteralValueOfExpression<Right> extends infer RightLiteral
+        ? [RightLiteral] extends [never]
+          ? UnknownTag<"eq:unsupported">
+          : RightLiteral extends null
+            ? False
+            : AtomOf<EqLiteralAtom<ColumnKeyOfExpression<Left>, ValueKey<RightLiteral>>>
+        : UnknownTag<"eq:unsupported">
+      : AtomOf<import("./predicate-atom.js").EqColumnAtom<ColumnKeyOfExpression<Left>, ColumnKeyOfExpression<Right>>>
+type FormulaOfVariadic<
+  Kind extends ExpressionAst.VariadicKind,
+  Values extends readonly Expression.Any[]
+> = Kind extends "and"
+  ? import("./predicate-formula.js").NormalizeBooleanConstants<import("./predicate-formula.js").AllFormula<{
+      readonly [K in keyof Values]: Values[K] extends Expression.Any ? FormulaOfExpression<Values[K]> : never
+    } & readonly PredicateFormula[]>>
+  : Kind extends "or"
+    ? import("./predicate-formula.js").NormalizeBooleanConstants<import("./predicate-formula.js").AnyFormula<{
+        readonly [K in keyof Values]: Values[K] extends Expression.Any ? FormulaOfExpression<Values[K]> : never
+      } & readonly PredicateFormula[]>>
+    : Kind extends "in" | "notIn" | "between"
+      ? FactsOfExpressions<Values> extends infer Facts extends PredicateFormula
+        ? [Facts] extends [never]
+          ? UnknownTag<`variadic:${Kind}`>
+          : Facts
+        : UnknownTag<`variadic:${Kind}`>
+    : UnknownTag<`variadic:${Kind}`>
+export type FormulaOfExpression<Value extends Expression.Any> =
+  AstOf<Value> extends infer Ast extends ExpressionAst.Any
+    ? Ast extends ExpressionAst.LiteralNode<infer Literal>
+      ? Literal extends true
+        ? True
+        : Literal extends false
+          ? False
+          : UnknownTag<"literal:non-boolean">
+      : Ast extends ExpressionAst.UnaryNode<infer Kind extends ExpressionAst.UnaryKind, infer Inner extends Expression.Any>
+        ? Kind extends "isNull"
+    ? [ColumnKeyOfExpression<Inner>] extends [never]
+            ? UnknownTag<"isNull:unsupported">
+            : AtomOf<NullAtom<ColumnKeyOfExpression<Inner>>>
+          : Kind extends "isNotNull"
+            ? [ColumnKeyOfExpression<Inner>] extends [never]
+              ? UnknownTag<"isNotNull:unsupported">
+              : AtomOf<NonNullAtom<ColumnKeyOfExpression<Inner>>>
+            : Kind extends "not"
+              ? import("./predicate-formula.js").Not<FormulaOfExpression<Inner>>
+              : UnknownTag<`unary:${Kind}`>
+        : Ast extends ExpressionAst.BinaryNode<"eq", infer Left extends Expression.Any, infer Right extends Expression.Any>
+          ? FormulaOfEq<Left, Right>
+          : Ast extends ExpressionAst.BinaryNode<"neq", infer Left extends Expression.Any, infer Right extends Expression.Any>
+            ? Left extends Expression.Any
+              ? Right extends Expression.Any
+                ? [ColumnKeyOfExpression<Left>] extends [never]
+                  ? [ColumnKeyOfExpression<Right>] extends [never]
+                    ? LiteralValueOfExpression<Left> extends infer LeftLiteral
+                      ? LiteralValueOfExpression<Right> extends infer RightLiteral
+                        ? [LeftLiteral] extends [never]
+                          ? UnknownTag<"neq:unsupported">
+                          : [RightLiteral] extends [never]
+                            ? UnknownTag<"neq:unsupported">
+                            : LeftLiteral extends null
+                              ? False
+                              : RightLiteral extends null
+                                ? False
+                                : [LeftLiteral] extends [RightLiteral]
+                                  ? False
+                                  : True
+                        : UnknownTag<"neq:unsupported">
+                      : UnknownTag<"neq:unsupported">
+                    : CombineFacts<NonNullFactsOfExpression<Left>, NonNullFactsOfExpression<Right>>
+                  : CombineFacts<NonNullFactsOfExpression<Left>, NonNullFactsOfExpression<Right>>
+                : UnknownTag<"neq:unsupported">
+              : UnknownTag<"neq:unsupported">
+            : Ast extends ExpressionAst.BinaryNode<infer Kind extends "lt" | "lte" | "gt" | "gte" | "like" | "ilike" | "isDistinctFrom" | "isNotDistinctFrom" | "contains" | "containedBy" | "overlaps", infer Left extends Expression.Any, infer Right extends Expression.Any>
+              ? Kind extends "isNotDistinctFrom"
+                ? Left extends Expression.Any
+                  ? Right extends Expression.Any
+                    ? LiteralValueOfExpression<Left> extends infer LeftLiteral
+                      ? LiteralValueOfExpression<Right> extends infer RightLiteral
+                        ? [LeftLiteral] extends [never]
+                          ? [RightLiteral] extends [never]
+                            ? UnknownTag<"isNotDistinctFrom:unsupported">
+                            : RightLiteral extends null
+                              ? [ColumnKeyOfExpression<Left>] extends [never]
+                                ? UnknownTag<"isNotDistinctFrom:unsupported">
+                                : AtomOf<NullAtom<ColumnKeyOfExpression<Left>>>
+                              : UnknownTag<"isNotDistinctFrom:unsupported">
+                          : LeftLiteral extends null
+                            ? [ColumnKeyOfExpression<Right>] extends [never]
+                              ? UnknownTag<"isNotDistinctFrom:unsupported">
+                              : AtomOf<NullAtom<ColumnKeyOfExpression<Right>>>
+                            : RightLiteral extends null
+                              ? [ColumnKeyOfExpression<Left>] extends [never]
+                                ? UnknownTag<"isNotDistinctFrom:unsupported">
+                                : AtomOf<NullAtom<ColumnKeyOfExpression<Left>>>
+                              : [ColumnKeyOfExpression<Left>] extends [never]
+                                ? [ColumnKeyOfExpression<Right>] extends [never]
+                                  ? CombineFacts<NonNullFactsOfExpression<Left>, NonNullFactsOfExpression<Right>>
+                                  : AtomOf<EqLiteralAtom<ColumnKeyOfExpression<Right>, ValueKey<LeftLiteral>>>
+                                : AtomOf<EqLiteralAtom<ColumnKeyOfExpression<Left>, ValueKey<RightLiteral>>>
+                        : UnknownTag<"isNotDistinctFrom:unsupported">
+                      : UnknownTag<"isNotDistinctFrom:unsupported">
+                    : UnknownTag<"isNotDistinctFrom:unsupported">
+                  : UnknownTag<"isNotDistinctFrom:unsupported">
+                : Kind extends "isDistinctFrom"
+                  ? UnknownTag<"isDistinctFrom:unsupported">
+                  : CombineFacts<NonNullFactsOfExpression<Left>, NonNullFactsOfExpression<Right>>
+              : Ast extends ExpressionAst.VariadicNode<"and", infer Values extends readonly Expression.Any[]>
+                ? import("./predicate-formula.js").NormalizeBooleanConstants<import("./predicate-formula.js").AllFormula<{
+                    readonly [K in keyof Values]: Values[K] extends Expression.Any ? FormulaOfExpression<Values[K]> : never
+                  } & readonly PredicateFormula[]>>
+                : Ast extends ExpressionAst.VariadicNode<"or", infer Values extends readonly Expression.Any[]>
+                  ? import("./predicate-formula.js").NormalizeBooleanConstants<import("./predicate-formula.js").AnyFormula<{
+                      readonly [K in keyof Values]: Values[K] extends Expression.Any ? FormulaOfExpression<Values[K]> : never
+                    } & readonly PredicateFormula[]>>
+                  : Ast extends ExpressionAst.VariadicNode<infer Kind extends "in" | "notIn" | "between", infer Values extends readonly Expression.Any[]>
+                    ? CombineFacts<NonNullFactsOfExpression<Values[number]>, UnknownTag<`variadic:${Kind}`>>
+                    : Ast extends ExpressionAst.BinaryNode<infer Kind extends ExpressionAst.BinaryKind, infer Left extends Expression.Any, infer Right extends Expression.Any>
+                      ? Kind extends "eq"
+                        ? FormulaOfEq<Left, Right>
+                        : CombineFacts<NonNullFactsOfExpression<Left>, NonNullFactsOfExpression<Right>>
+                      : UnknownTag<`expr:${Ast["kind"]}`>
+    : UnknownTag<"missing-ast">
+export type FormulaOfPredicate<Value> =
+  Value extends true ? True :
+    Value extends false ? False :
+      Value extends Expression.Any ? FormulaOfExpression<Value> :
+        UnknownTag<"predicate:unsupported">

package/src/internal/projection-alias.ts ADDED Viewed

@@ -0,0 +1,15 @@
+/** Symbol used to attach explicit projection-alias metadata to an expression. */
+export const TypeId: unique symbol = Symbol.for("effect-qb/ProjectionAlias")
+export type TypeId = typeof TypeId
+/**
+ * Projection-alias metadata carried by a runtime expression wrapper.
+ *
+ * This is intentionally orthogonal to the scalar expression AST. Aliasing does
+ * not change SQL semantics; it only changes how a selected expression is named
+ * in the rendered `SELECT ... AS ...` list.
+ */
+export interface State<Alias extends string = string> {
+  readonly alias: Alias
+}

package/src/internal/projections.ts ADDED Viewed

@@ -0,0 +1,101 @@
+import * as Expression from "./expression.js"
+import * as ProjectionAlias from "./projection-alias.js"
+/**
+ * Flat projection metadata shared by renderers and executors.
+ *
+ * `path` identifies where a value should be decoded in the nested result row,
+ * while `alias` is the flat SQL column alias used by the rendered query.
+ */
+export interface Projection {
+  readonly path: readonly string[]
+  readonly alias: string
+}
+/** Selection leaf paired with its resolved projection alias. */
+export interface FlattenedProjection {
+  readonly path: readonly string[]
+  readonly expression: Expression.Any
+  readonly alias: string
+}
+const aliasFromPath = (path: readonly string[]): string => path.join("__")
+const isExpression = (value: unknown): value is Expression.Any =>
+  typeof value === "object" && value !== null && Expression.TypeId in value
+const projectionAliasOf = (expression: Expression.Any): string | undefined =>
+  ProjectionAlias.TypeId in expression
+    ? (expression as Expression.Any & {
+        readonly [ProjectionAlias.TypeId]: ProjectionAlias.State
+      })[ProjectionAlias.TypeId].alias
+    : undefined
+const pathKeyOf = (path: readonly string[]): string => JSON.stringify(path)
+const formatProjectionPath = (path: readonly string[]): string => path.join(".")
+const isPrefixPath = (
+  left: readonly string[],
+  right: readonly string[]
+): boolean =>
+  left.length < right.length && left.every((segment, index) => segment === right[index])
+/**
+ * Flattens a nested selection object into leaf expressions with decode paths
+ * and resolved SQL aliases.
+ */
+export const flattenSelection = (
+  selection: Record<string, unknown>,
+  path: readonly string[] = []
+): ReadonlyArray<FlattenedProjection> => {
+  const fields: Array<FlattenedProjection> = []
+  for (const [key, value] of Object.entries(selection)) {
+    const nextPath = [...path, key]
+    if (isExpression(value)) {
+      fields.push({
+        path: nextPath,
+        expression: value,
+        alias: projectionAliasOf(value) ?? aliasFromPath(nextPath)
+      })
+      continue
+    }
+    fields.push(...flattenSelection(value as Record<string, unknown>, nextPath))
+  }
+  return fields
+}
+/**
+ * Validates the flattened projection set shared by renderer and executor code.
+ *
+ * This rejects:
+ * - duplicate SQL aliases
+ * - duplicate decode paths
+ * - conflicting prefix paths like `profile` and `profile.id`
+ */
+export const validateProjections = (projections: readonly Projection[]): void => {
+  const seen = new Set<string>()
+  const pathKeys = new Set<string>()
+  for (const projection of projections) {
+    if (seen.has(projection.alias)) {
+      throw new Error(`Duplicate projection alias: ${projection.alias}`)
+    }
+    seen.add(projection.alias)
+    const pathKey = pathKeyOf(projection.path)
+    if (pathKeys.has(pathKey)) {
+      throw new Error(`Duplicate projection path: ${formatProjectionPath(projection.path)}`)
+    }
+    pathKeys.add(pathKey)
+  }
+  for (let index = 0; index < projections.length; index++) {
+    const current = projections[index]!
+    for (let compareIndex = index + 1; compareIndex < projections.length; compareIndex++) {
+      const other = projections[compareIndex]!
+      if (isPrefixPath(current.path, other.path) || isPrefixPath(other.path, current.path)) {
+        throw new Error(
+          `Conflicting projection paths: ${formatProjectionPath(current.path)} conflicts with ${formatProjectionPath(other.path)}`
+        )
+      }
+    }
+  }
+}

package/src/internal/query-ast.ts ADDED Viewed

@@ -0,0 +1,297 @@
+import type * as Expression from "./expression.js"
+/** Symbol used to attach query-clause AST metadata to query-plan values. */
+export const TypeId: unique symbol = Symbol.for("effect-qb/QueryAst")
+export type TypeId = typeof TypeId
+/** Statement kinds supported by the current query AST. */
+export type QueryStatement =
+  | "select"
+  | "set"
+  | "insert"
+  | "update"
+  | "delete"
+  | "truncate"
+  | "merge"
+  | "transaction"
+  | "commit"
+  | "rollback"
+  | "savepoint"
+  | "rollbackTo"
+  | "releaseSavepoint"
+  | "createTable"
+  | "createIndex"
+  | "dropIndex"
+  | "alterTable"
+  | "dropTable"
+/** Base `FROM` clause recorded by the query AST. */
+export interface FromClause<TableName extends string = string> {
+  readonly kind: "from"
+  readonly tableName: TableName
+  readonly baseTableName: string
+  readonly source: unknown
+}
+/** Boolean predicate recorded in a `WHERE` clause. */
+export interface WhereClause<Predicate extends Expression.Any = Expression.Any> {
+  readonly kind: "where"
+  readonly predicate: Predicate
+}
+/** Boolean predicate recorded in a `HAVING` clause. */
+export interface HavingClause<Predicate extends Expression.Any = Expression.Any> {
+  readonly kind: "having"
+  readonly predicate: Predicate
+}
+/** Assignment recorded in a mutation statement. */
+export interface AssignmentClause<Value extends Expression.Any = Expression.Any> {
+  readonly tableName?: string
+  readonly columnName: string
+  readonly value: Value
+}
+/** One row in a multi-row `values (...)` insert source. */
+export interface InsertValuesRowClause<
+  Values extends readonly AssignmentClause[] = readonly AssignmentClause[]
+> {
+  readonly values: Values
+}
+/** Additional insert source kinds beyond a single literal row. */
+export type InsertSourceClause =
+  | {
+      readonly kind: "values"
+      readonly columns: readonly [string, ...string[]]
+      readonly rows: readonly [InsertValuesRowClause, ...InsertValuesRowClause[]]
+    }
+  | {
+      readonly kind: "query"
+      readonly columns: readonly [string, ...string[]]
+      readonly query: unknown
+    }
+  | {
+      readonly kind: "unnest"
+      readonly columns: readonly [string, ...string[]]
+      readonly values: readonly {
+        readonly columnName: string
+        readonly values: readonly unknown[]
+      }[]
+    }
+/** One branch inside a `merge` statement. */
+export type MergeMatchedClause<
+  Predicate extends Expression.Any | undefined = Expression.Any | undefined
+> =
+  | {
+      readonly kind: "update"
+      readonly values: readonly AssignmentClause[]
+      readonly predicate?: Predicate
+    }
+  | {
+      readonly kind: "delete"
+      readonly predicate?: Predicate
+    }
+/** Insert branch inside a `merge` statement. */
+export interface MergeNotMatchedClause<
+  Predicate extends Expression.Any | undefined = Expression.Any | undefined
+> {
+  readonly kind: "insert"
+  readonly values: readonly AssignmentClause[]
+  readonly predicate?: Predicate
+}
+/** Payload recorded by a `merge` statement. */
+export interface MergeClause<
+  On extends Expression.Any = Expression.Any,
+  Predicate extends Expression.Any | undefined = Expression.Any | undefined
+> {
+  readonly kind: "merge"
+  readonly on: On
+  readonly whenMatched?: MergeMatchedClause<Predicate>
+  readonly whenNotMatched?: MergeNotMatchedClause<Predicate>
+}
+/** DDL payload recorded by schema-manipulation statements. */
+export type DdlClause =
+  | {
+      readonly kind: "createTable"
+      readonly ifNotExists: boolean
+    }
+  | {
+      readonly kind: "dropTable"
+      readonly ifExists: boolean
+    }
+  | {
+      readonly kind: "createIndex"
+      readonly name: string
+      readonly columns: readonly [string, ...string[]]
+      readonly unique: boolean
+      readonly ifNotExists: boolean
+    }
+  | {
+      readonly kind: "dropIndex"
+      readonly name: string
+      readonly ifExists: boolean
+    }
+/** Truncate payload recorded by a truncate statement. */
+export interface TruncateClause {
+  readonly kind: "truncate"
+  readonly restartIdentity: boolean
+  readonly cascade: boolean
+}
+/** Transaction-control payload recorded by transactional statements. */
+export type TransactionClause =
+  | {
+      readonly kind: "transaction"
+      readonly isolationLevel?: "read committed" | "repeatable read" | "serializable"
+      readonly readOnly?: boolean
+    }
+  | {
+      readonly kind: "commit"
+    }
+  | {
+      readonly kind: "rollback"
+    }
+  | {
+      readonly kind: "savepoint"
+      readonly name: string
+    }
+  | {
+      readonly kind: "rollbackTo"
+      readonly name: string
+    }
+  | {
+      readonly kind: "releaseSavepoint"
+      readonly name: string
+    }
+  | {
+      readonly kind: "dropTable"
+      readonly ifExists: boolean
+    }
+  | {
+      readonly kind: "createIndex"
+      readonly name: string
+      readonly columns: readonly [string, ...string[]]
+      readonly unique: boolean
+      readonly ifNotExists: boolean
+    }
+  | {
+      readonly kind: "dropIndex"
+      readonly name: string
+      readonly ifExists: boolean
+    }
+/** Locking mode attached to a select statement. */
+export interface LockClause {
+  readonly kind: "lock"
+  readonly mode: "update" | "share" | "lowPriority" | "ignore" | "quick"
+  readonly nowait?: boolean
+  readonly skipLocked?: boolean
+}
+/** Conflict target attached to a Postgres insert statement. */
+export type ConflictTargetClause =
+  | {
+      readonly kind: "columns"
+      readonly columns: readonly [string, ...string[]]
+      readonly where?: Expression.Any
+    }
+  | {
+      readonly kind: "constraint"
+      readonly name: string
+    }
+/** Conflict clause attached to an insert statement. */
+export interface ConflictClause {
+  readonly kind: "conflict"
+  readonly target?: ConflictTargetClause
+  readonly action: "doNothing" | "doUpdate"
+  readonly values?: readonly AssignmentClause[]
+  readonly where?: Expression.Any
+}
+/** Join kinds supported by the current query layer. */
+export type JoinKind = "inner" | "left" | "right" | "full" | "cross"
+/** Join clause recorded by the query AST. */
+export interface JoinClause<
+  TableName extends string = string,
+  Kind extends JoinKind = JoinKind,
+  On extends Expression.Any | undefined = Expression.Any | undefined
+> {
+  readonly kind: Kind
+  readonly tableName: TableName
+  readonly baseTableName: string
+  readonly source: unknown
+  readonly on?: On
+}
+/** Sort direction recorded by an `ORDER BY` clause. */
+export type OrderDirection = "asc" | "desc"
+/** Ordering clause recorded by the query AST. */
+export interface OrderByClause<Value extends Expression.Any = Expression.Any> {
+  readonly kind: "orderBy"
+  readonly value: Value
+  readonly direction: OrderDirection
+}
+/** Set-operator kinds supported by compound queries. */
+export type SetOperatorKind = "union" | "intersect" | "except"
+/** Compound-query clause recorded by the query AST. */
+export interface SetOperationClause {
+  readonly kind: SetOperatorKind
+  readonly all?: boolean
+  readonly query: unknown
+}
+/**
+ * Internal query AST stored alongside public `Plan` metadata.
+ *
+ * The public plan state tracks selection, required sources, available sources,
+ * and dialect. This AST captures the clause ordering needed to eventually
+ * render or optimize a SQL query.
+ */
+export interface Ast<
+  Selection = unknown,
+  Grouped extends string = never,
+  Statement extends QueryStatement = "select"
+> {
+  readonly kind: Statement
+  readonly select: Selection
+  readonly distinct?: boolean
+  readonly distinctOn?: readonly Expression.Any[]
+  readonly setBase?: unknown
+  readonly recursive?: boolean
+  readonly from?: FromClause
+  readonly fromSources?: readonly FromClause[]
+  readonly into?: FromClause
+  readonly target?: FromClause
+  readonly targets?: readonly FromClause[]
+  readonly using?: FromClause
+  readonly values?: readonly AssignmentClause[]
+  readonly insertSource?: InsertSourceClause
+  readonly set?: readonly AssignmentClause[]
+  readonly ddl?: DdlClause
+  readonly truncate?: TruncateClause
+  readonly merge?: MergeClause
+  readonly transaction?: TransactionClause
+  readonly lock?: LockClause
+  readonly conflict?: ConflictClause
+  readonly where: readonly WhereClause[]
+  readonly having: readonly HavingClause[]
+  readonly joins: readonly JoinClause[]
+  readonly groupBy: readonly Expression.Any[]
+  readonly orderBy: readonly OrderByClause[]
+  readonly limit?: Expression.Any
+  readonly offset?: Expression.Any
+  readonly setOperations?: readonly SetOperationClause[]
+  readonly groupedSources?: Grouped
+}