effect-qb 0.12.3

package/src/internal/expression-ast.ts

@@ -0,0 +1,349 @@
+import type * as Expression from "./expression.js"
+import type * as Query from "./query.js"
+import type * as JsonPath from "./json/path.js"
+import type { JsonNode } from "./json/ast.js"
+
+/** Symbol used to attach internal expression-AST metadata to runtime values. */
+export const TypeId: unique symbol = Symbol.for("effect-qb/ExpressionAst")
+
+export type TypeId = typeof TypeId
+
+/** Bound column reference captured by the internal expression AST. */
+export interface ColumnNode<
+  TableName extends string = string,
+  ColumnName extends string = string
+> {
+  readonly kind: "column"
+  readonly tableName: TableName
+  readonly columnName: ColumnName
+}
+
+/** Constant literal captured by the internal expression AST. */
+export interface LiteralNode<Value = unknown> {
+  readonly kind: "literal"
+  readonly value: Value
+}
+
+/** Explicit type cast captured by the internal expression AST. */
+export interface CastNode<
+  Value extends Expression.Any = Expression.Any,
+  Target extends Expression.DbType.Any = Expression.DbType.Any
+> {
+  readonly kind: "cast"
+  readonly value: Value
+  readonly target: Target
+}
+
+/** `excluded.column` reference used inside insert conflict handlers. */
+export interface ExcludedNode<
+  ColumnName extends string = string
+> {
+  readonly kind: "excluded"
+  readonly columnName: ColumnName
+}
+
+/** Unary expression kinds supported by the current query layer. */
+export type UnaryKind =
+  | "isNull"
+  | "isNotNull"
+  | "not"
+  | "upper"
+  | "lower"
+  | "count"
+  | "max"
+  | "min"
+
+/** Unary expression node. */
+export interface UnaryNode<
+  Kind extends UnaryKind = UnaryKind,
+  Value extends Expression.Any = Expression.Any
+> {
+  readonly kind: Kind
+  readonly value: Value
+}
+
+/** Binary expression kinds supported by the current query layer. */
+export type BinaryKind =
+  | "eq"
+  | "neq"
+  | "lt"
+  | "lte"
+  | "gt"
+  | "gte"
+  | "like"
+  | "ilike"
+  | "isDistinctFrom"
+  | "isNotDistinctFrom"
+  | "contains"
+  | "containedBy"
+  | "overlaps"
+
+/** Binary expression node. */
+export interface BinaryNode<
+  Kind extends BinaryKind = BinaryKind,
+  Left extends Expression.Any = Expression.Any,
+  Right extends Expression.Any = Expression.Any
+> {
+  readonly kind: Kind
+  readonly left: Left
+  readonly right: Right
+}
+
+/** Variadic expression kinds supported by the current query layer. */
+export type VariadicKind = "and" | "or" | "coalesce" | "concat" | "in" | "notIn" | "between"
+
+/** Variadic expression node. */
+export interface VariadicNode<
+  Kind extends VariadicKind = VariadicKind,
+  Values extends readonly Expression.Any[] = readonly Expression.Any[]
+> {
+  readonly kind: Kind
+  readonly values: Values
+}
+
+/** One `when ... then ...` branch inside a searched `case`. */
+export interface CaseBranchNode<
+  Predicate extends Expression.Any = Expression.Any,
+  Then extends Expression.Any = Expression.Any
+> {
+  readonly when: Predicate
+  readonly then: Then
+}
+
+/** Searched `case when ... then ... else ... end` expression node. */
+export interface CaseNode<
+  Branches extends readonly CaseBranchNode[] = readonly CaseBranchNode[],
+  Else extends Expression.Any = Expression.Any
+> {
+  readonly kind: "case"
+  readonly branches: Branches
+  readonly else: Else
+}
+
+/** `exists (<subquery>)` expression node. */
+export interface ExistsNode<
+  PlanValue extends Query.QueryPlan<any, any, any, any, any, any, any, any, any, any> = Query.QueryPlan<any, any, any, any, any, any, any, any, any, any>
+> {
+  readonly kind: "exists"
+  readonly plan: PlanValue
+}
+
+/** Scalar subquery expression node. */
+export interface ScalarSubqueryNode<
+  PlanValue extends Query.QueryPlan<any, any, any, any, any, any, any, any, any, any> = Query.QueryPlan<any, any, any, any, any, any, any, any, any, any>
+> {
+  readonly kind: "scalarSubquery"
+  readonly plan: PlanValue
+}
+
+/** `value in (<subquery>)` expression node. */
+export interface InSubqueryNode<
+  Left extends Expression.Any = Expression.Any,
+  PlanValue extends Query.QueryPlan<any, any, any, any, any, any, any, any, any, any> = Query.QueryPlan<any, any, any, any, any, any, any, any, any, any>
+> {
+  readonly kind: "inSubquery"
+  readonly left: Left
+  readonly plan: PlanValue
+}
+
+/** `value <op> any|all (<subquery>)` expression node. */
+export interface QuantifiedComparisonNode<
+  Kind extends "comparisonAny" | "comparisonAll" = "comparisonAny" | "comparisonAll",
+  Operator extends "eq" | "neq" | "lt" | "lte" | "gt" | "gte" = "eq" | "neq" | "lt" | "lte" | "gt" | "gte",
+  Left extends Expression.Any = Expression.Any,
+  PlanValue extends Query.QueryPlan<any, any, any, any, any, any, any, any, any, any> = Query.QueryPlan<any, any, any, any, any, any, any, any, any, any>
+> {
+  readonly kind: Kind
+  readonly operator: Operator
+  readonly left: Left
+  readonly plan: PlanValue
+}
+
+/** Ordering term inside a window specification. */
+export interface WindowOrderByNode<
+  Value extends Expression.Any = Expression.Any
+> {
+  readonly value: Value
+  readonly direction: "asc" | "desc"
+}
+
+/** Window function kinds supported by the query layer. */
+export type WindowKind = "rowNumber" | "rank" | "denseRank" | "over"
+
+/** Window function expression node. */
+export interface WindowNode<
+  Kind extends WindowKind = WindowKind,
+  Value extends Expression.Any | undefined = Expression.Any | undefined,
+  PartitionBy extends readonly Expression.Any[] = readonly Expression.Any[],
+  OrderBy extends readonly WindowOrderByNode[] = readonly WindowOrderByNode[]
+> {
+  readonly kind: "window"
+  readonly function: Kind
+  readonly value?: Value
+  readonly partitionBy: PartitionBy
+  readonly orderBy: OrderBy
+}
+
+export type JsonSegmentTuple = readonly any[]
+
+export type JsonAccessKind =
+  | "jsonGet"
+  | "jsonPath"
+  | "jsonAccess"
+  | "jsonTraverse"
+  | "jsonGetText"
+  | "jsonPathText"
+  | "jsonAccessText"
+  | "jsonTraverseText"
+
+export interface JsonAccessNode<
+  Kind extends JsonAccessKind = JsonAccessKind,
+  Base extends Expression.Any = Expression.Any,
+  Segments extends JsonSegmentTuple = JsonSegmentTuple
+> {
+  readonly kind: Kind
+  readonly base: Base
+  readonly segments: Segments
+}
+
+export type JsonKeyPredicateKind =
+  | "jsonHasKey"
+  | "jsonKeyExists"
+  | "jsonHasAnyKeys"
+  | "jsonHasAllKeys"
+
+export interface JsonKeyPredicateNode<
+  Kind extends JsonKeyPredicateKind = JsonKeyPredicateKind,
+  Base extends Expression.Any = Expression.Any,
+  Keys extends readonly string[] = readonly string[]
+> {
+  readonly kind: Kind
+  readonly base: Base
+  readonly keys: Keys
+}
+
+export type JsonBinaryKind = "jsonConcat" | "jsonMerge"
+
+export interface JsonBinaryNode<
+  Kind extends JsonBinaryKind = JsonBinaryKind,
+  Left extends Expression.Any = Expression.Any,
+  Right extends Expression.Any = Expression.Any
+> {
+  readonly kind: Kind
+  readonly left: Left
+  readonly right: Right
+}
+
+export type JsonDeleteKind = "jsonDelete" | "jsonDeletePath" | "jsonRemove"
+
+export interface JsonDeleteNode<
+  Kind extends JsonDeleteKind = JsonDeleteKind,
+  Base extends Expression.Any = Expression.Any,
+  Segments extends JsonSegmentTuple = JsonSegmentTuple
+> {
+  readonly kind: Kind
+  readonly base: Base
+  readonly segments: Segments
+}
+
+export interface JsonSetNode<
+  Base extends Expression.Any = Expression.Any,
+  Segments extends JsonSegmentTuple = JsonSegmentTuple,
+  NewValue extends Expression.Any = Expression.Any
+> {
+  readonly kind: "jsonSet"
+  readonly base: Base
+  readonly segments: Segments
+  readonly newValue: NewValue
+  readonly createMissing: boolean
+}
+
+export interface JsonInsertNode<
+  Base extends Expression.Any = Expression.Any,
+  Segments extends JsonSegmentTuple = JsonSegmentTuple,
+  Insert extends Expression.Any = Expression.Any
+> {
+  readonly kind: "jsonInsert"
+  readonly base: Base
+  readonly segments: Segments
+  readonly insert: Insert
+  readonly insertAfter: boolean
+}
+
+export type JsonQueryPredicateKind = "jsonPathExists" | "jsonPathMatch"
+
+export interface JsonQueryPredicateNode<
+  Kind extends JsonQueryPredicateKind = JsonQueryPredicateKind,
+  Base extends Expression.Any = Expression.Any,
+  QueryValue extends Expression.Any | JsonPath.Path<any> | string = Expression.Any | JsonPath.Path<any> | string
+> {
+  readonly kind: Kind
+  readonly base: Base
+  readonly query: QueryValue
+}
+
+export interface JsonBuildObjectEntryNode<
+  Key extends string = string,
+  Value extends Expression.Any = Expression.Any
+> {
+  readonly key: Key
+  readonly value: Value
+}
+
+export interface JsonBuildObjectNode<
+  Entries extends readonly JsonBuildObjectEntryNode[] = readonly JsonBuildObjectEntryNode[]
+> {
+  readonly kind: "jsonBuildObject"
+  readonly entries: Entries
+}
+
+export interface JsonBuildArrayNode<
+  Values extends readonly Expression.Any[] = readonly Expression.Any[]
+> {
+  readonly kind: "jsonBuildArray"
+  readonly values: Values
+}
+
+export interface JsonWrapNode<
+  Kind extends "jsonToJson" | "jsonToJsonb" = "jsonToJson" | "jsonToJsonb",
+  Value extends Expression.Any = Expression.Any
+> {
+  readonly kind: Kind
+  readonly value: Value
+}
+
+export interface JsonUnaryNode<
+  Kind extends "jsonTypeOf" | "jsonLength" | "jsonKeys" | "jsonStripNulls" = "jsonTypeOf" | "jsonLength" | "jsonKeys" | "jsonStripNulls",
+  Value extends Expression.Any = Expression.Any
+> {
+  readonly kind: Kind
+  readonly value: Value
+}
+
+/** Union of all internal expression nodes. */
+export type Any =
+  | ColumnNode
+  | LiteralNode
+  | CastNode
+  | ExcludedNode
+  | UnaryNode
+  | BinaryNode
+  | VariadicNode
+  | CaseNode
+  | ExistsNode
+  | ScalarSubqueryNode
+  | InSubqueryNode
+  | QuantifiedComparisonNode
+  | WindowNode
+  | JsonNode
+  | JsonAccessNode
+  | JsonKeyPredicateNode
+  | JsonBinaryNode
+  | JsonDeleteNode
+  | JsonSetNode
+  | JsonInsertNode
+  | JsonQueryPredicateNode
+  | JsonBuildObjectNode
+  | JsonBuildArrayNode
+  | JsonWrapNode
+  | JsonUnaryNode

package/src/internal/expression.ts

@@ -0,0 +1,325 @@
+import type { Pipeable } from "effect/Pipeable"
+import type * as Schema from "effect/Schema"
+import type { RuntimeOfDbType as RuntimeOfDbTypeLookup } from "./datatypes/lookup.js"
+
+export type {
+  BigIntString,
+  DecimalString,
+  InstantString,
+  JsonPrimitive,
+  JsonValue,
+  LocalDateString,
+  LocalDateTimeString,
+  LocalTimeString,
+  OffsetTimeString,
+  YearString
+} from "./runtime-value.js"
+
+/** Symbol used to attach expression metadata to runtime values. */
+export const TypeId: unique symbol = Symbol.for("effect-qb/Expression")
+
+export type TypeId = typeof TypeId
+
+/**
+ * Bound source provenance for a column-like expression.
+ *
+ * `tableName` is the logical source identity currently visible to the query
+ * layer. For aliased sources this is the alias, while `baseTableName` retains
+ * the underlying physical table name for downstream renderer work.
+ */
+export interface ColumnSource<
+  TableName extends string = string,
+  ColumnName extends string = string,
+  BaseTableName extends string = TableName
+> {
+  readonly tableName: TableName
+  readonly columnName: ColumnName
+  readonly baseTableName: BaseTableName
+}
+
+/**
+ * Three-state nullability lattice.
+ *
+ * `"never"` means non-null, `"maybe"` means nullable, and `"always"` means the
+ * expression is known to be `null`.
+ */
+export type Nullability = "never" | "maybe" | "always"
+
+/**
+ * High-level classification of an expression.
+ *
+ * - `scalar`: regular per-row expression
+ * - `aggregate`: grouped expression such as `count(*)`
+ * - `window`: windowed expression such as `row_number() over (...)`
+ */
+export type AggregationKind = "scalar" | "aggregate" | "window"
+
+/**
+ * Whether an expression should still be promoted by optional-source scope.
+ *
+ * Most expressions propagate optional-source nullability because a missing
+ * joined row turns their inputs into `null`. Some expressions, such as
+ * `coalesce(...)`, `is null`, and aggregates, already model their own
+ * null-handling semantics and should not be promoted again by plan scope.
+ */
+export type SourceNullabilityMode = "propagate" | "resolved"
+
+/**
+ * Phantom dependency map of source names referenced by an expression.
+ *
+ * This is intentionally separate from runtime provenance (`source`). The
+ * dependency map is the cheap, composable type-level representation used by the
+ * query layer to resolve scope-sensitive nullability after joins. Dependencies
+ * are tracked by logical source identity, which means aliased sources are kept
+ * distinct from one another even when they point at the same base table.
+ */
+export type SourceDependencies = Record<string, true>
+
+/** Database-type descriptors carried alongside decoded runtime types. */
+export declare namespace DbType {
+  /** Base SQL type descriptor. */
+  export interface Base<Dialect extends string, Kind extends string> {
+    readonly dialect: Dialect
+    readonly kind: Kind
+  }
+
+  /** JSON-like database type. */
+  export interface Json<
+    Dialect extends string = "postgres",
+    SchemaName extends string = "json"
+  > extends Base<Dialect, SchemaName>
+  {
+    readonly variant: "json"
+  }
+
+  /** Array database type. */
+  export interface Array<
+    Dialect extends string = string,
+    Element extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly element: Element
+  }
+
+  /** Range database type. */
+  export interface Range<
+    Dialect extends string = string,
+    Subtype extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly subtype: Subtype
+  }
+
+  /** Multirange database type. */
+  export interface Multirange<
+    Dialect extends string = string,
+    Subtype extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly subtype: Subtype
+  }
+
+  /** Composite/record database type. */
+  export interface Composite<
+    Dialect extends string = string,
+    Fields extends Record<string, Any> = Record<string, any>,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly fields: Fields
+  }
+
+  /** Named domain database type. */
+  export interface Domain<
+    Dialect extends string = string,
+    BaseType extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly base: BaseType
+  }
+
+  /** Enumeration database type. */
+  export interface Enum<
+    Dialect extends string = string,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly variant: "enum"
+  }
+
+  /** Set database type. */
+  export interface Set<
+    Dialect extends string = string,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly variant: "set"
+  }
+
+  export type PgUuid = Base<"postgres", "uuid">
+  export type PgText = Base<"postgres", "text">
+  export type PgVarchar = Base<"postgres", "varchar">
+  export type PgChar = Base<"postgres", "char">
+  export type PgCitext = Base<"postgres", "citext">
+  export type PgInt2 = Base<"postgres", "int2">
+  export type PgInt4 = Base<"postgres", "int4">
+  export type PgInt8 = Base<"postgres", "int8">
+  export type PgNumeric = Base<"postgres", "numeric">
+  export type PgFloat4 = Base<"postgres", "float4">
+  export type PgFloat8 = Base<"postgres", "float8">
+  export type PgBool = Base<"postgres", "bool">
+  export type PgDate = Base<"postgres", "date">
+  export type PgTime = Base<"postgres", "time">
+  export type PgTimestamp = Base<"postgres", "timestamp">
+  export type PgInterval = Base<"postgres", "interval">
+  export type PgBytea = Base<"postgres", "bytea">
+  export type PgJsonb = Base<"postgres", "jsonb">
+  export type PgArray<Element extends Any = any> = Array<"postgres", Element, string>
+  export type PgRange<Subtype extends Any = any, Kind extends string = string> = Range<"postgres", Subtype, Kind>
+  export type PgMultirange<Subtype extends Any = any, Kind extends string = string> = Multirange<"postgres", Subtype, Kind>
+  export type PgComposite<Fields extends Record<string, Any> = Record<string, any>, Kind extends string = string> = Composite<"postgres", Fields, Kind>
+  export type PgDomain<BaseType extends Any = any, Kind extends string = string> = Domain<"postgres", BaseType, Kind>
+
+  export type MySqlUuid = Base<"mysql", "uuid">
+  export type MySqlText = Base<"mysql", "text">
+  export type MySqlVarchar = Base<"mysql", "varchar">
+  export type MySqlChar = Base<"mysql", "char">
+  export type MySqlTinyInt = Base<"mysql", "tinyint">
+  export type MySqlSmallInt = Base<"mysql", "smallint">
+  export type MySqlMediumInt = Base<"mysql", "mediumint">
+  export type MySqlInt = Base<"mysql", "int">
+  export type MySqlBigInt = Base<"mysql", "bigint">
+  export type MySqlNumeric = Base<"mysql", "decimal">
+  export type MySqlFloat = Base<"mysql", "float">
+  export type MySqlDouble = Base<"mysql", "double">
+  export type MySqlBool = Base<"mysql", "boolean">
+  export type MySqlDate = Base<"mysql", "date">
+  export type MySqlTime = Base<"mysql", "time">
+  export type MySqlDatetime = Base<"mysql", "datetime">
+  export type MySqlTimestamp = Base<"mysql", "timestamp">
+  export type MySqlBinary = Base<"mysql", "binary">
+  export type MySqlVarBinary = Base<"mysql", "varbinary">
+  export type MySqlBlob = Base<"mysql", "blob">
+  export type MySqlArray<Element extends Any = any> = Array<"mysql", Element, string>
+  export type MySqlComposite<Fields extends Record<string, Any> = Record<string, any>, Kind extends string = string> = Composite<"mysql", Fields, Kind>
+  export type MySqlDomain<BaseType extends Any = any, Kind extends string = string> = Domain<"mysql", BaseType, Kind>
+
+  export type Any =
+    | PgUuid
+    | PgText
+    | PgVarchar
+    | PgChar
+    | PgCitext
+    | PgInt2
+    | PgInt4
+    | PgInt8
+    | PgNumeric
+    | PgFloat4
+    | PgFloat8
+    | PgBool
+    | PgDate
+    | PgTime
+    | PgTimestamp
+    | PgInterval
+    | PgBytea
+    | PgJsonb
+    | PgArray
+    | PgRange
+    | PgMultirange
+    | PgComposite
+    | PgDomain
+    | MySqlUuid
+    | MySqlText
+    | MySqlVarchar
+    | MySqlChar
+    | MySqlTinyInt
+    | MySqlSmallInt
+    | MySqlMediumInt
+    | MySqlInt
+    | MySqlBigInt
+    | MySqlNumeric
+    | MySqlFloat
+    | MySqlDouble
+    | MySqlBool
+    | MySqlDate
+    | MySqlTime
+    | MySqlDatetime
+    | MySqlTimestamp
+    | MySqlBinary
+    | MySqlVarBinary
+    | MySqlBlob
+    | MySqlArray
+    | MySqlComposite
+    | MySqlDomain
+    | Json
+    | Base<string, string>
+    | Array<string, any, string>
+    | Range<string, any, string>
+    | Multirange<string, any, string>
+    | Composite<string, Record<string, any>, string>
+    | Domain<string, any, string>
+    | Enum<string, string>
+    | Set<string, string>
+  }
+
+/** Canonical static metadata stored on an expression. */
+export interface State<
+  Runtime,
+  Db extends DbType.Any,
+  Nullable extends Nullability,
+  Dialect extends string,
+  Aggregation extends AggregationKind,
+  Source = never,
+  Dependencies extends SourceDependencies = {},
+  SourceNullability extends SourceNullabilityMode = "propagate"
+> {
+  readonly runtime: Runtime
+  readonly dbType: Db
+  readonly runtimeSchema?: Schema.Schema.Any
+  readonly nullability: Nullable
+  readonly dialect: Dialect
+  readonly aggregation: Aggregation
+  readonly source: Source
+  readonly sourceNullability: SourceNullability
+  /**
+   * Type-level source dependency map used for lazy nullability resolution.
+   *
+   * Unlike `source`, which preserves runtime provenance detail for diagnostics
+   * and plan assembly, `dependencies` only needs to record which tables are
+   * referenced at all.
+   */
+  readonly dependencies: Dependencies
+}
+
+/**
+ * A typed SQL expression.
+ *
+ * `Runtime` is the decoded TypeScript type while `Db` captures the SQL-level
+ * type identity. Both are needed: multiple SQL types may decode to the same
+ * runtime type but still have different comparison/cast semantics.
+ */
+export interface Expression<
+  Runtime,
+  Db extends DbType.Any,
+  Nullable extends Nullability = "never",
+  Dialect extends string = Db["dialect"],
+  Aggregation extends AggregationKind = "scalar",
+  Source = never,
+  Dependencies extends SourceDependencies = {},
+  SourceNullability extends SourceNullabilityMode = "propagate"
+> extends Pipeable {
+  readonly [TypeId]: State<Runtime, Db, Nullable, Dialect, Aggregation, Source, Dependencies, SourceNullability>
+}
+
+/** Convenience alias for any expression-like value. */
+export type Any = Expression<any, DbType.Any, Nullability, string, AggregationKind, any, SourceDependencies, SourceNullabilityMode>
+/** Extracts an expression's decoded runtime type. */
+export type RuntimeOf<Value extends Any> = Value[typeof TypeId]["runtime"]
+/** Extracts an expression's database-type descriptor. */
+export type DbTypeOf<Value extends Any> = Value[typeof TypeId]["dbType"]
+/** Extracts an expression's nullability state. */
+export type NullabilityOf<Value extends Any> = Value[typeof TypeId]["nullability"]
+/** Extracts an expression's source dependency map. */
+export type DependenciesOf<Value extends Any> = Value[typeof TypeId]["dependencies"]
+/** Extracts how plan-scope nullability should apply to an expression. */
+export type SourceNullabilityOf<Value extends Any> = Value[typeof TypeId]["sourceNullability"]
+
+/** Maps a database type descriptor back to its decoded runtime type. */
+export type RuntimeOfDbType<Db extends DbType.Any> = RuntimeOfDbTypeLookup<Db>