effect-qb 0.13.0 → 0.15.0

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 (146) hide show
  1. package/README.md +6 -1431
  2. package/dist/mysql.js +61945 -3611
  3. package/dist/postgres/metadata.js +2818 -0
  4. package/dist/postgres.js +9942 -5591
  5. package/package.json +21 -10
  6. package/src/internal/aggregation-validation.ts +3 -3
  7. package/src/internal/case-analysis.d.ts +18 -0
  8. package/src/internal/case-analysis.ts +4 -4
  9. package/src/internal/coercion/analysis.d.ts +7 -0
  10. package/src/internal/{coercion-analysis.ts → coercion/analysis.ts} +3 -3
  11. package/src/internal/coercion/errors.d.ts +17 -0
  12. package/src/internal/{coercion-errors.ts → coercion/errors.ts} +1 -1
  13. package/src/internal/coercion/kind.d.ts +4 -0
  14. package/src/internal/{coercion-kind.ts → coercion/kind.ts} +2 -2
  15. package/src/internal/{coercion-normalize.ts → coercion/normalize.ts} +1 -1
  16. package/src/internal/coercion/rules.d.ts +6 -0
  17. package/src/internal/{coercion-rules.ts → coercion/rules.ts} +2 -2
  18. package/src/internal/column-state.d.ts +190 -0
  19. package/src/internal/column-state.ts +119 -56
  20. package/src/internal/column.ts +387 -149
  21. package/src/internal/datatypes/define.d.ts +17 -0
  22. package/src/internal/datatypes/define.ts +18 -34
  23. package/src/internal/datatypes/lookup.d.ts +44 -0
  24. package/src/internal/datatypes/lookup.ts +61 -152
  25. package/src/internal/datatypes/shape.d.ts +16 -0
  26. package/src/internal/datatypes/shape.ts +1 -1
  27. package/src/internal/derived-table.d.ts +4 -0
  28. package/src/internal/derived-table.ts +21 -16
  29. package/src/internal/dsl-mutation-runtime.ts +378 -0
  30. package/src/internal/dsl-plan-runtime.ts +387 -0
  31. package/src/internal/dsl-query-runtime.ts +160 -0
  32. package/src/internal/dsl-transaction-ddl-runtime.ts +263 -0
  33. package/src/internal/executor.ts +173 -38
  34. package/src/internal/expression-ast.ts +19 -5
  35. package/src/internal/grouping-key.d.ts +3 -0
  36. package/src/internal/grouping-key.ts +1 -1
  37. package/src/internal/implication-runtime.d.ts +15 -0
  38. package/src/internal/implication-runtime.ts +171 -0
  39. package/src/internal/json/ast.d.ts +30 -0
  40. package/src/internal/json/ast.ts +1 -1
  41. package/src/internal/json/errors.d.ts +8 -0
  42. package/src/internal/json/path.d.ts +75 -0
  43. package/src/internal/json/path.ts +1 -1
  44. package/src/internal/json/types.d.ts +62 -0
  45. package/src/internal/predicate/analysis.d.ts +20 -0
  46. package/src/internal/{predicate-analysis.ts → predicate/analysis.ts} +13 -3
  47. package/src/internal/predicate/atom.d.ts +28 -0
  48. package/src/internal/{predicate-branches.ts → predicate/branches.ts} +2 -2
  49. package/src/internal/predicate/context.d.ts +67 -0
  50. package/src/internal/{predicate-context.ts → predicate/context.ts} +111 -32
  51. package/src/internal/predicate/formula.d.ts +35 -0
  52. package/src/internal/{predicate-formula.ts → predicate/formula.ts} +32 -20
  53. package/src/internal/predicate/key.d.ts +11 -0
  54. package/src/internal/{predicate-key.ts → predicate/key.ts} +2 -2
  55. package/src/internal/{predicate-nnf.ts → predicate/nnf.ts} +2 -2
  56. package/src/internal/predicate/normalize.d.ts +53 -0
  57. package/src/internal/predicate/normalize.ts +273 -0
  58. package/src/internal/predicate/runtime.d.ts +31 -0
  59. package/src/internal/predicate/runtime.ts +679 -0
  60. package/src/internal/projection-alias.d.ts +13 -0
  61. package/src/internal/projections.d.ts +31 -0
  62. package/src/internal/projections.ts +1 -1
  63. package/src/internal/query-ast.d.ts +217 -0
  64. package/src/internal/query-ast.ts +1 -1
  65. package/src/internal/query-requirements.d.ts +20 -0
  66. package/src/internal/query.d.ts +775 -0
  67. package/src/internal/query.ts +767 -275
  68. package/src/internal/renderer.ts +7 -21
  69. package/src/internal/row-set.d.ts +53 -0
  70. package/src/internal/{plan.ts → row-set.ts} +23 -11
  71. package/src/internal/{runtime-normalize.ts → runtime/normalize.ts} +9 -31
  72. package/src/internal/{runtime-schema.ts → runtime/schema.ts} +84 -55
  73. package/src/internal/runtime/value.d.ts +22 -0
  74. package/src/internal/{runtime-value.ts → runtime/value.ts} +2 -2
  75. package/src/internal/scalar.d.ts +107 -0
  76. package/src/internal/scalar.ts +191 -0
  77. package/src/internal/schema-derivation.d.ts +105 -0
  78. package/src/internal/schema-derivation.ts +93 -21
  79. package/src/internal/schema-expression.d.ts +18 -0
  80. package/src/internal/schema-expression.ts +75 -0
  81. package/src/internal/table-options.d.ts +94 -0
  82. package/src/internal/table-options.ts +94 -8
  83. package/src/internal/table.d.ts +173 -0
  84. package/src/internal/table.ts +135 -54
  85. package/src/mysql/column.ts +95 -18
  86. package/src/mysql/datatypes/index.ts +58 -3
  87. package/src/mysql/errors/generated.ts +57336 -0
  88. package/src/mysql/errors/index.ts +1 -0
  89. package/src/mysql/errors/normalize.ts +55 -53
  90. package/src/mysql/errors/types.ts +74 -0
  91. package/src/mysql/executor.ts +69 -7
  92. package/src/mysql/function/aggregate.ts +1 -5
  93. package/src/mysql/function/core.ts +1 -3
  94. package/src/mysql/function/index.ts +1 -1
  95. package/src/mysql/function/string.ts +1 -5
  96. package/src/mysql/function/temporal.ts +12 -15
  97. package/src/mysql/function/window.ts +1 -6
  98. package/src/{internal/mysql-dialect.ts → mysql/internal/dialect.ts} +1 -1
  99. package/src/mysql/internal/dsl.ts +6115 -0
  100. package/src/{internal/mysql-renderer.ts → mysql/internal/renderer.ts} +6 -6
  101. package/src/mysql/internal/sql-expression-renderer.ts +1455 -0
  102. package/src/mysql/json.ts +2 -0
  103. package/src/mysql/query.ts +111 -86
  104. package/src/mysql/renderer.ts +1 -1
  105. package/src/mysql/table.ts +1 -1
  106. package/src/mysql.ts +6 -4
  107. package/src/postgres/cast.ts +30 -0
  108. package/src/postgres/column.ts +178 -20
  109. package/src/postgres/datatypes/index.d.ts +515 -0
  110. package/src/postgres/datatypes/index.ts +49 -5
  111. package/src/postgres/datatypes/spec.d.ts +412 -0
  112. package/src/postgres/errors/generated.ts +2636 -0
  113. package/src/postgres/errors/index.ts +1 -0
  114. package/src/postgres/errors/normalize.ts +47 -62
  115. package/src/postgres/errors/types.ts +92 -34
  116. package/src/postgres/executor.ts +37 -5
  117. package/src/postgres/function/aggregate.ts +1 -5
  118. package/src/postgres/function/core.ts +20 -2
  119. package/src/postgres/function/index.ts +1 -1
  120. package/src/postgres/function/string.ts +1 -5
  121. package/src/postgres/function/temporal.ts +12 -15
  122. package/src/postgres/function/window.ts +1 -6
  123. package/src/{internal/postgres-dialect.ts → postgres/internal/dialect.ts} +1 -1
  124. package/src/{internal/query-factory.ts → postgres/internal/dsl.ts} +1568 -2120
  125. package/src/{internal/postgres-renderer.ts → postgres/internal/renderer.ts} +6 -6
  126. package/src/postgres/internal/schema-ddl.ts +108 -0
  127. package/src/postgres/internal/schema-model.ts +150 -0
  128. package/src/{internal → postgres/internal}/sql-expression-renderer.ts +112 -46
  129. package/src/postgres/json.ts +493 -0
  130. package/src/postgres/metadata.ts +31 -0
  131. package/src/postgres/query.ts +113 -86
  132. package/src/postgres/renderer.ts +3 -13
  133. package/src/postgres/schema-expression.ts +17 -0
  134. package/src/postgres/schema-management.ts +204 -0
  135. package/src/postgres/schema.ts +35 -0
  136. package/src/postgres/table.ts +316 -42
  137. package/src/postgres/type.ts +31 -0
  138. package/src/postgres.ts +20 -4
  139. package/CHANGELOG.md +0 -134
  140. package/src/internal/expression.ts +0 -327
  141. package/src/internal/predicate-normalize.ts +0 -202
  142. package/src/mysql/function/json.ts +0 -4
  143. package/src/mysql/private/query.ts +0 -13
  144. package/src/postgres/function/json.ts +0 -4
  145. package/src/postgres/private/query.ts +0 -13
  146. /package/src/internal/{predicate-atom.ts → predicate/atom.ts} +0 -0
@@ -1,7 +1,8 @@
1
1
  import { pipeArguments, type Pipeable } from "effect/Pipeable"
2
+ import type * as Schema from "effect/Schema"
2
3
 
3
- import * as Expression from "./expression.js"
4
- import * as Plan from "./plan.js"
4
+ import * as Expression from "./scalar.js"
5
+ import * as RowSet from "./row-set.js"
5
6
  import * as Table from "./table.js"
6
7
  import * as ExpressionAst from "./expression-ast.js"
7
8
  import * as QueryAst from "./query-ast.js"
@@ -9,8 +10,10 @@ import type { JsonNode } from "./json/ast.js"
9
10
  import type * as JsonPath from "./json/path.js"
10
11
  import type { QueryCapability } from "./query-requirements.js"
11
12
  import type { CaseBranchAssumeFalse, CaseBranchAssumeTrue, CaseBranchDecision } from "./case-analysis.js"
12
- import type { GuaranteedNonNullKeys, GuaranteedNullKeys, GuaranteedSourceNames } from "./predicate-analysis.js"
13
- import type { PredicateFormula, TrueFormula } from "./predicate-formula.js"
13
+ import type { ContradictsFormula, GuaranteedNonNullKeys, GuaranteedNullKeys, GuaranteedSourceNames } from "./predicate/analysis.js"
14
+ import type { ColumnKeyOfExpression } from "./predicate/key.js"
15
+ import type { PredicateFormula, TrueFormula } from "./predicate/formula.js"
16
+ import { trueFormula } from "./predicate/runtime.js"
14
17
 
15
18
  export type {
16
19
  MergeCapabilities,
@@ -23,7 +26,7 @@ export type {
23
26
  RuntimeOfDbType,
24
27
  TextCompatibleDbType,
25
28
  CastableDbType
26
- } from "./coercion-analysis.js"
29
+ } from "./coercion/analysis.js"
27
30
  export type {
28
31
  CanonicalSegment as JsonPathSegment,
29
32
  DescendSegment as JsonPathDescendSegment,
@@ -58,12 +61,12 @@ export type {
58
61
  export type {
59
62
  CoercionKind,
60
63
  CoercionKindOf
61
- } from "./coercion-kind.js"
64
+ } from "./coercion/kind.js"
62
65
  export type {
63
66
  CanCastDbType,
64
67
  CanCompareDbTypes,
65
68
  CanContainDbTypes
66
- } from "./coercion-rules.js"
69
+ } from "./coercion/rules.js"
67
70
  export type {
68
71
  ConflictClause,
69
72
  LockClause,
@@ -97,12 +100,12 @@ const PlanProto = {
97
100
  }
98
101
 
99
102
  /** Internal symbol used to preserve query-only phantom metadata through inference. */
100
- const QueryTypeId: unique symbol = Symbol.for("effect-qb/Query/internal")
103
+ export const QueryTypeId: unique symbol = Symbol.for("effect-qb/Query/internal")
101
104
 
102
105
  type InsertSourceState = "ready" | "missing"
103
106
 
104
107
  /** Internal phantom state tracked on query plans. */
105
- interface QueryState<
108
+ export interface QueryState<
106
109
  Outstanding extends string,
107
110
  AvailableNames extends string,
108
111
  Grouped extends string,
@@ -122,14 +125,12 @@ interface QueryState<
122
125
  readonly insertSource: InsertState
123
126
  }
124
127
 
125
- /** Source provenance attached to an expression. */
126
- export type SourceOf<Value extends Expression.Any> = Value[typeof Expression.TypeId]["source"]
127
128
  /** Effective SQL dialect carried by an expression. */
128
129
  export type DialectOf<Value extends Expression.Any> = Value[typeof Expression.TypeId]["dialect"]
129
- /** Source dependency map carried by an expression. */
130
+ /** Source dependency union carried by an expression. */
130
131
  export type DependenciesOf<Value extends Expression.Any> = Expression.DependenciesOf<Value>
131
132
  /** Aggregation kind carried by an expression. */
132
- export type AggregationOf<Value extends Expression.Any> = Value[typeof Expression.TypeId]["aggregation"]
133
+ export type KindOf<Value extends Expression.Any> = Value[typeof Expression.TypeId]["kind"]
133
134
  type AstOf<Value extends Expression.Any> = Value extends { readonly [ExpressionAst.TypeId]: infer Ast extends ExpressionAst.Any } ? Ast : never
134
135
 
135
136
  /**
@@ -141,11 +142,11 @@ type AstOf<Value extends Expression.Any> = Value extends { readonly [ExpressionA
141
142
  export type LiteralValue = string | number | boolean | null | Date
142
143
 
143
144
  /** Runtime expression type produced by `literal(...)` for a primitive value. */
144
- type LiteralExpression<Value extends LiteralValue> = Expression.Expression<
145
+ type LiteralExpression<Value extends LiteralValue> = Expression.Scalar<
145
146
  Value,
146
147
  LiteralDbType<Value>,
147
148
  LiteralNullability<Value>,
148
- "postgres",
149
+ string,
149
150
  "scalar",
150
151
  never
151
152
  >
@@ -159,21 +160,19 @@ type LiteralExpression<Value extends LiteralValue> = Expression.Expression<
159
160
  export type ExpressionInput = Expression.Any | LiteralValue
160
161
 
161
162
  /** Input accepted by numeric clauses such as `limit(...)` and `offset(...)`. */
162
- export type NumericExpressionInput = Expression.Expression<
163
+ export type NumericExpressionInput = Expression.Scalar<
163
164
  number,
164
165
  Expression.DbType.Any,
165
166
  Expression.Nullability,
166
167
  string,
167
168
  "scalar",
168
- any,
169
- Expression.SourceDependencies,
170
- Expression.SourceNullabilityMode
169
+ Expression.BindingId
171
170
  > | number
172
171
 
173
172
  /** Values accepted by mutation payload fields. */
174
173
  export type MutationValueInput<Value> =
175
174
  | Value
176
- | Expression.Expression<Value, Expression.DbType.Any, Expression.Nullability, string, Expression.AggregationKind, any, any, any>
175
+ | Expression.Scalar<Value, Expression.DbType.Any, Expression.Nullability, string, Expression.ScalarKind, Expression.BindingId>
177
176
 
178
177
  /** Maps a payload shape to values or expressions of the same runtime type. */
179
178
  export type MutationInputOf<Shape> = {
@@ -183,74 +182,64 @@ export type MutationInputOf<Shape> = {
183
182
  type Simplify<T> = { readonly [K in keyof T]: T[K] } & {}
184
183
 
185
184
  /** Input accepted by boolean plan clauses such as `where(...)` and joins. */
186
- export type PredicateInput = Expression.Expression<
185
+ export type PredicateInput = Expression.Scalar<
187
186
  boolean,
188
187
  Expression.DbType.Any,
189
188
  Expression.Nullability,
190
189
  string,
191
190
  "scalar",
192
- any,
193
- Expression.SourceDependencies,
194
- Expression.SourceNullabilityMode
191
+ Expression.BindingId
195
192
  > | boolean
196
193
 
197
194
  /** Input accepted by `having(...)`. */
198
- export type HavingPredicateInput = Expression.Expression<
195
+ export type HavingPredicateInput = Expression.Scalar<
199
196
  boolean,
200
197
  Expression.DbType.Any,
201
198
  Expression.Nullability,
202
199
  string,
203
200
  "scalar" | "aggregate",
204
- any,
205
- Expression.SourceDependencies,
206
- Expression.SourceNullabilityMode
201
+ Expression.BindingId
207
202
  > | boolean
208
203
 
209
204
  /** Input accepted by `GROUP BY`. */
210
- export type GroupByInput = Expression.Expression<
205
+ export type GroupByInput = Expression.Scalar<
211
206
  any,
212
207
  Expression.DbType.Any,
213
208
  Expression.Nullability,
214
209
  string,
215
210
  "scalar",
216
- any
211
+ Expression.BindingId
217
212
  >
218
213
 
219
214
  /** Maps a literal runtime value to its SQL-level DB type descriptor. */
220
215
  type LiteralDbType<Value extends LiteralValue> =
221
- Value extends string ? Expression.DbType.PgText :
222
- Value extends number ? Expression.DbType.PgNumeric :
223
- Value extends boolean ? Expression.DbType.PgBool :
224
- Value extends Date ? Expression.DbType.PgTimestamp :
225
- Expression.DbType.Base<"postgres", "null">
216
+ Value extends string ? Expression.DbType.Base<string, "text"> :
217
+ Value extends number ? Expression.DbType.Base<string, "numeric"> :
218
+ Value extends boolean ? Expression.DbType.Base<string, "boolean"> :
219
+ Value extends Date ? Expression.DbType.Base<string, "timestamp"> :
220
+ Expression.DbType.Base<string, "null">
226
221
 
227
222
  /** Maps a literal runtime value to its static nullability state. */
228
223
  type LiteralNullability<Value extends LiteralValue> = Value extends null ? "always" : "never"
229
224
  /** Converts a supported input into its canonical expression type. */
230
225
  type AsExpression<Value extends ExpressionInput> = Value extends Expression.Any ? Value : LiteralExpression<Extract<Value, LiteralValue>>
231
- /** Extracts provenance from an operator input after coercion. */
232
- type SourceOfInput<Value extends ExpressionInput> = SourceOf<AsExpression<Value>>
233
226
  /** Extracts dialect from an operator input after coercion. */
234
227
  type DialectOfInput<Value extends ExpressionInput> = DialectOf<AsExpression<Value>>
235
228
  /** Extracts dependencies from an operator input after coercion. */
236
229
  type DependenciesOfInput<Value extends ExpressionInput> = DependenciesOf<AsExpression<Value>>
237
- /** Extracts required sources from an operator input after coercion. */
238
- type RequiredFromInput<Value extends ExpressionInput> = RequiredFromDependencies<DependenciesOfInput<Value>>
230
+ /** Extracts required bindings from an operator input after coercion. */
231
+ type RequiredFromInput<Value extends ExpressionInput> = DependenciesOfInput<Value>
239
232
  /** String-valued expressions accepted by text operators. */
240
- export type StringExpressionInput = Expression.Expression<
233
+ export type StringExpressionInput = Expression.Scalar<
241
234
  string | null,
242
235
  Expression.DbType.Any,
243
236
  Expression.Nullability,
244
237
  string,
245
- Expression.AggregationKind,
246
- any,
247
- Expression.SourceDependencies,
248
- Expression.SourceNullabilityMode
238
+ Expression.ScalarKind,
239
+ Expression.BindingId
249
240
  > | string
250
241
  /** Converts a string operator input into its canonical expression type. */
251
242
  type AsStringExpression<Value extends StringExpressionInput> = Value extends Expression.Any ? Value : LiteralExpression<Extract<Value, string>>
252
- /** Extracts provenance from a string operator input after coercion. */
253
- type SourceOfStringInput<Value extends StringExpressionInput> = SourceOf<AsStringExpression<Value>>
254
243
  /** Extracts dialect from a string operator input after coercion. */
255
244
  type DialectOfStringInput<Value extends StringExpressionInput> = DialectOf<AsStringExpression<Value>>
256
245
  /** Extracts dependencies from a string operator input after coercion. */
@@ -258,10 +247,8 @@ type DependenciesOfStringInput<Value extends StringExpressionInput> = Dependenci
258
247
  /** Extracts intrinsic nullability from a string operator input after coercion. */
259
248
  type NullabilityOfStringInput<Value extends StringExpressionInput> = Expression.NullabilityOf<AsStringExpression<Value>>
260
249
 
261
- /** Extracts a required table name from expression provenance. */
262
- type RequiredFromSource<Source> = Source extends { readonly tableName: infer Name extends string } ? Name : never
263
- /** Extracts required table names from an expression dependency map. */
264
- export type RequiredFromDependencies<Dependencies extends Expression.SourceDependencies> = Extract<keyof Dependencies, string>
250
+ /** Extracts required bindings from an expression dependency union. */
251
+ export type RequiredFromDependencies<Dependencies extends Expression.BindingId> = Dependencies
265
252
 
266
253
  type LiteralGroupingKey<Value> =
267
254
  Value extends string ? `string:${Value}` :
@@ -376,8 +363,13 @@ type GroupingKeyOfAst<Ast extends ExpressionAst.Any> =
376
363
  ? "exists(subquery)"
377
364
  : never
378
365
 
379
- /** Canonical grouping identity for an expression AST. */
380
- export type GroupingKeyOfExpression<Value extends Expression.Any> = GroupingKeyOfAst<AstOf<Value>>
366
+ /** Canonical grouping identity for an expression. */
367
+ export type GroupingKeyOfExpression<Value extends Expression.Any> =
368
+ Expression.GroupKeyOf<Value> extends infer GroupKey extends string
369
+ ? string extends GroupKey
370
+ ? GroupingKeyOfAst<AstOf<Value>>
371
+ : GroupKey
372
+ : GroupingKeyOfAst<AstOf<Value>>
381
373
 
382
374
  /**
383
375
  * Recursive selection tree accepted by `select(...)`.
@@ -416,7 +408,7 @@ export type ExtractDialect<Selection> = Selection extends Expression.Any
416
408
  * The query layer only needs the plan metadata and the static table name. It
417
409
  * deliberately avoids depending on the full table-definition surface.
418
410
  */
419
- export type TableLike<Name extends string = string, Dialect extends string = string> = Plan.Plan<any, any, Record<string, Plan.Source>, Dialect> & {
411
+ export type TableLike<Name extends string = string, Dialect extends string = string> = RowSet.RowSet<any, any, Record<string, RowSet.AnySource>, Dialect> & {
420
412
  readonly [Table.TypeId]: {
421
413
  readonly name: Name
422
414
  readonly baseName: string
@@ -554,6 +546,9 @@ export type TableFunctionSource<
554
546
  readonly columns: DerivedSelectionOf<Selection, Alias>
555
547
  }
556
548
 
549
+ /** Broad structural shape for table-function sources when used as composable inputs. */
550
+ export type AnyTableFunctionSource = TableFunctionSource<Record<string, Expression.Any>, string, string, string>
551
+
557
552
  /** Accepts either a physical table or a derived table source. */
558
553
  type DerivedSourceShape = {
559
554
  readonly kind: "derived"
@@ -642,6 +637,271 @@ export type MutationTargetLike = Table.AnyTable
642
637
  export type MutationTargetTuple = readonly [MutationTargetLike, MutationTargetLike, ...MutationTargetLike[]]
643
638
  export type MutationTargetInput = MutationTargetLike | MutationTargetTuple
644
639
 
640
+ type JsonMutationDbKindError<
641
+ ColumnName extends string,
642
+ ExpectedKind extends string,
643
+ ReceivedKind extends string
644
+ > = {
645
+ readonly __effect_qb_error__: "effect-qb: incompatible json mutation value"
646
+ readonly __effect_qb_column__: ColumnName
647
+ readonly __effect_qb_reason__: "json kinds do not match"
648
+ readonly __effect_qb_expected_json_kind__: ExpectedKind
649
+ readonly __effect_qb_received_json_kind__: ReceivedKind
650
+ readonly __effect_qb_hint__: "Use the dialect Json helpers that match the target json kind"
651
+ }
652
+
653
+ type JsonMutationShapeError<
654
+ ColumnName extends string,
655
+ Expected,
656
+ Received
657
+ > = {
658
+ readonly __effect_qb_error__: "effect-qb: incompatible json mutation value"
659
+ readonly __effect_qb_column__: ColumnName
660
+ readonly __effect_qb_reason__: "json value is not assignable to the target column schema"
661
+ readonly __effect_qb_json_issues__: JsonShapeIssues<Expected, Received>
662
+ readonly __effect_qb_hint__: "Inspect __effect_qb_json_issues__ or the __effect_qb_json_issue__... sentinel keys to find the failing nested paths"
663
+ } & JsonIssueSentinels<Expected, Received>
664
+
665
+ type MutationValueShapeError<
666
+ ColumnName extends string,
667
+ Expected,
668
+ Received
669
+ > = {
670
+ readonly __effect_qb_error__: "effect-qb: incompatible mutation value"
671
+ readonly __effect_qb_column__: ColumnName
672
+ readonly __effect_qb_reason__: "value is not assignable to the target column schema"
673
+ readonly __effect_qb_expected_type__: Expected
674
+ readonly __effect_qb_received_type__: Received
675
+ }
676
+
677
+ type MutationUnknownColumnError<ColumnName extends string> = {
678
+ readonly __effect_qb_error__: "effect-qb: unknown mutation column"
679
+ readonly __effect_qb_column__: ColumnName
680
+ readonly __effect_qb_hint__: "Use only columns that exist on the target table"
681
+ }
682
+
683
+ type MutationRequiredKeys<Shape> = Extract<{
684
+ [K in keyof Shape]-?: {} extends Pick<Shape, K> ? never : K
685
+ }[keyof Shape], string>
686
+
687
+ type MutationExtraKeys<TargetShape, SourceShape> = Exclude<Extract<keyof SourceShape, string>, Extract<keyof TargetShape, string>>
688
+
689
+ type MutationMissingKeys<TargetShape, SourceShape> = Exclude<MutationRequiredKeys<TargetShape>, Extract<keyof SourceShape, string>>
690
+
691
+ type JsonPathDisplay<Path extends string> = Path extends "" ? "(root)" : Path
692
+
693
+ type JsonObjectKeyPath<Path extends string, Key extends string> = Path extends ""
694
+ ? Key
695
+ : `${Path}.${Key}`
696
+
697
+ type JsonArrayPath<Path extends string> = Path extends ""
698
+ ? "[number]"
699
+ : `${Path}[number]`
700
+
701
+ type JsonTupleIndexPath<
702
+ Path extends string,
703
+ Index extends string
704
+ > = Path extends ""
705
+ ? `[${Index}]`
706
+ : `${Path}[${Index}]`
707
+
708
+ type JsonIssueKeyPath<Path extends string> = Path extends ""
709
+ ? "root"
710
+ : Path
711
+
712
+ type JsonShapeIssue<
713
+ Path extends string,
714
+ Kind extends string,
715
+ Expected,
716
+ Received
717
+ > = {
718
+ readonly path: JsonPathDisplay<Path>
719
+ readonly issue: Kind
720
+ readonly expected: Expected
721
+ readonly received: Received
722
+ }
723
+
724
+ type JsonSharedKeys<Expected, Received> = Extract<Extract<keyof Expected, keyof Received>, string>
725
+
726
+ type JsonIssueSentinelKeys<Issues> = Issues extends {
727
+ readonly path: infer Path extends string
728
+ readonly issue: infer Kind extends string
729
+ }
730
+ ? `__effect_qb_json_issue__${JsonIssueKeyPath<Path>}__${Kind}`
731
+ : never
732
+
733
+ type JsonIssueSentinels<
734
+ Expected,
735
+ Received
736
+ > = {
737
+ readonly [K in JsonIssueSentinelKeys<JsonShapeIssues<Expected, Received>>]: true
738
+ }
739
+
740
+ type JsonObjectShapeIssues<
741
+ Expected extends object,
742
+ Received extends object,
743
+ Path extends string
744
+ > =
745
+ | {
746
+ readonly [K in MutationMissingKeys<Expected, Received>]:
747
+ JsonShapeIssue<JsonObjectKeyPath<Path, K>, "missing_required_property", Expected[K], undefined>
748
+ }[MutationMissingKeys<Expected, Received>]
749
+ | {
750
+ readonly [K in JsonSharedKeys<Expected, Received>]:
751
+ JsonShapeIssues<Expected[K], Received[K], JsonObjectKeyPath<Path, K>>
752
+ }[JsonSharedKeys<Expected, Received>]
753
+
754
+ type JsonTupleIndices<Value extends readonly unknown[]> = Extract<keyof Value, `${number}`>
755
+
756
+ type JsonTupleShapeIssues<
757
+ Expected extends readonly unknown[],
758
+ Received extends readonly unknown[],
759
+ Path extends string
760
+ > =
761
+ | {
762
+ readonly [K in Exclude<JsonTupleIndices<Expected>, JsonTupleIndices<Received>>]:
763
+ JsonShapeIssue<JsonTupleIndexPath<Path, K>, "missing_required_property", Expected[K], undefined>
764
+ }[Exclude<JsonTupleIndices<Expected>, JsonTupleIndices<Received>>]
765
+ | {
766
+ readonly [K in Extract<JsonTupleIndices<Expected>, JsonTupleIndices<Received>>]:
767
+ JsonShapeIssues<Expected[K], Received[K], JsonTupleIndexPath<Path, K>>
768
+ }[Extract<JsonTupleIndices<Expected>, JsonTupleIndices<Received>>]
769
+
770
+ type JsonShapeIssues<
771
+ Expected,
772
+ Received,
773
+ Path extends string = ""
774
+ > = [Received] extends [Expected]
775
+ ? never
776
+ : [Expected] extends [readonly (infer ExpectedElement)[]]
777
+ ? [Received] extends [readonly (infer ReceivedElement)[]]
778
+ ? number extends Expected["length"]
779
+ ? JsonShapeIssues<ExpectedElement, ReceivedElement, JsonArrayPath<Path>>
780
+ : number extends Received["length"]
781
+ ? JsonShapeIssues<ExpectedElement, ReceivedElement, JsonArrayPath<Path>>
782
+ : JsonTupleShapeIssues<Expected, Received, Path> extends infer Issues
783
+ ? [Issues] extends [never]
784
+ ? JsonShapeIssue<Path, "type_mismatch", Expected, Received>
785
+ : Issues
786
+ : never
787
+ : JsonShapeIssue<Path, "type_mismatch", Expected, Received>
788
+ : [Expected] extends [object]
789
+ ? [Expected] extends [Function]
790
+ ? JsonShapeIssue<Path, "type_mismatch", Expected, Received>
791
+ : [Received] extends [object]
792
+ ? [Received] extends [Function]
793
+ ? JsonShapeIssue<Path, "type_mismatch", Expected, Received>
794
+ : JsonObjectShapeIssues<Expected & object, Received & object, Path> extends infer Issues
795
+ ? [Issues] extends [never]
796
+ ? JsonShapeIssue<Path, "type_mismatch", Expected, Received>
797
+ : Issues
798
+ : never
799
+ : JsonShapeIssue<Path, "type_mismatch", Expected, Received>
800
+ : JsonShapeIssue<Path, "type_mismatch", Expected, Received>
801
+
802
+ type MutationAcceptedInput<Column> =
803
+ Column extends Expression.Scalar<infer Runtime, any, any, any, any, any>
804
+ ? MutationValueInput<Runtime>
805
+ : never
806
+
807
+ type MutationValueCompatibilityIssue<
808
+ Column,
809
+ Value,
810
+ ColumnName extends string
811
+ > = Column extends Expression.Scalar<any, infer ColumnDb extends Expression.DbType.Any, any, any, any, any>
812
+ ? ColumnDb extends Expression.DbType.Json<infer ColumnDialect extends string, infer ExpectedKind>
813
+ ? Value extends Expression.Scalar<any, infer ValueDb extends Expression.DbType.Any, any, any, any, any>
814
+ ? ValueDb extends Expression.DbType.Json<ColumnDialect, infer ReceivedKind>
815
+ ? [ExpectedKind] extends [ReceivedKind]
816
+ ? [ReceivedKind] extends [ExpectedKind]
817
+ ? Value extends Expression.Scalar<infer ReceivedRuntime, any, any, any, any, any>
818
+ ? Column extends Expression.Scalar<infer ExpectedRuntime, any, any, any, any, any>
819
+ ? [ReceivedRuntime] extends [ExpectedRuntime]
820
+ ? never
821
+ : JsonMutationShapeError<ColumnName, ExpectedRuntime, ReceivedRuntime>
822
+ : never
823
+ : never
824
+ : JsonMutationDbKindError<ColumnName, ExpectedKind, ReceivedKind>
825
+ : JsonMutationDbKindError<ColumnName, ExpectedKind, ReceivedKind>
826
+ : Value extends Expression.Scalar<infer ReceivedRuntime, any, any, any, any, any>
827
+ ? Column extends Expression.Scalar<infer ExpectedRuntime, any, any, any, any, any>
828
+ ? [ReceivedRuntime] extends [ExpectedRuntime]
829
+ ? never
830
+ : JsonMutationShapeError<ColumnName, ExpectedRuntime, ReceivedRuntime>
831
+ : never
832
+ : Column extends Expression.Scalar<infer ExpectedRuntime, any, any, any, any, any>
833
+ ? [Value] extends [ExpectedRuntime]
834
+ ? never
835
+ : JsonMutationShapeError<ColumnName, ExpectedRuntime, Value>
836
+ : never
837
+ : Column extends Expression.Scalar<infer ExpectedRuntime, any, any, any, any, any>
838
+ ? [Value] extends [ExpectedRuntime]
839
+ ? never
840
+ : JsonMutationShapeError<ColumnName, ExpectedRuntime, Value>
841
+ : never
842
+ : Value extends Expression.Scalar<infer ReceivedRuntime, any, any, any, any, any>
843
+ ? Column extends Expression.Scalar<infer ExpectedRuntime, any, any, any, any, any>
844
+ ? [ReceivedRuntime] extends [ExpectedRuntime]
845
+ ? never
846
+ : MutationValueShapeError<ColumnName, ExpectedRuntime, ReceivedRuntime>
847
+ : never
848
+ : Column extends Expression.Scalar<infer ExpectedRuntime, any, any, any, any, any>
849
+ ? [Value] extends [ExpectedRuntime]
850
+ ? never
851
+ : MutationValueShapeError<ColumnName, ExpectedRuntime, Value>
852
+ : never
853
+ : unknown
854
+
855
+ type MutationExpectedValue<
856
+ Column,
857
+ Value,
858
+ ColumnName extends string
859
+ > = [MutationValueCompatibilityIssue<Column, Value, ColumnName>] extends [never]
860
+ ? MutationAcceptedInput<Column>
861
+ : MutationValueCompatibilityIssue<Column, Value, ColumnName>
862
+
863
+ type MutationShapeOf<
864
+ Statement extends "insert" | "update",
865
+ Target extends MutationTargetLike
866
+ > = Statement extends "insert" ? Table.InsertOf<Target> : Table.UpdateOf<Target>
867
+
868
+ type MutationColumnAt<
869
+ Target extends MutationTargetLike,
870
+ Key extends string
871
+ > = Target extends {
872
+ readonly [Table.TypeId]: {
873
+ readonly fields: Record<Key, infer Column>
874
+ }
875
+ }
876
+ ? Column
877
+ : never
878
+
879
+ type MutationValueShape<
880
+ Shape,
881
+ Target extends MutationTargetLike,
882
+ Values extends Record<string, unknown>
883
+ > = {
884
+ readonly [K in Extract<keyof Values, string>]:
885
+ K extends Extract<keyof Shape, string>
886
+ ? MutationExpectedValue<MutationColumnAt<Target, K>, Values[K], K>
887
+ : MutationUnknownColumnError<K>
888
+ }
889
+
890
+ type MutationKeyShape<Shape> = {
891
+ readonly [K in keyof Shape]: unknown
892
+ }
893
+
894
+ export type MutationValuesInput<
895
+ Statement extends "insert" | "update",
896
+ Target extends MutationTargetLike,
897
+ Values extends Record<string, unknown>,
898
+ Shape = MutationShapeOf<Statement, Target>
899
+ > = Simplify<
900
+ Values &
901
+ MutationKeyShape<Shape> &
902
+ MutationValueShape<Shape, Target, Values>
903
+ >
904
+
645
905
  /** Extracts a source name from either a table or a derived source. */
646
906
  export type SourceNameOf<Source extends SourceLike> =
647
907
  Source extends TableLike<infer Name, any> ? Name :
@@ -729,15 +989,13 @@ type DerivedLeafExpression<
729
989
  Value extends Expression.Any,
730
990
  Alias extends string,
731
991
  ColumnName extends string
732
- > = Expression.Expression<
992
+ > = Expression.Scalar<
733
993
  Expression.RuntimeOf<Value>,
734
994
  Expression.DbTypeOf<Value>,
735
995
  Expression.NullabilityOf<Value>,
736
996
  DialectOf<Value>,
737
997
  "scalar",
738
- Expression.ColumnSource<Alias, ColumnName, Alias>,
739
- Record<Alias, true>,
740
- "propagate"
998
+ Alias
741
999
  > & {
742
1000
  readonly [ExpressionAst.TypeId]: ExpressionAst.ColumnNode<Alias, ColumnName>
743
1001
  }
@@ -758,41 +1016,60 @@ export type DerivedSelectionOf<
758
1016
  /** Extracts the static SQL table name from a table-like value. */
759
1017
  export type TableNameOf<T extends TableLike> = T[typeof Table.TypeId]["name"]
760
1018
  /** Extracts the effective dialect from a table-like value. */
761
- export type TableDialectOf<T extends TableLike> = T[typeof Plan.TypeId]["dialect"]
1019
+ export type TableDialectOf<T extends TableLike> = T[typeof RowSet.TypeId]["dialect"]
762
1020
  /** Names of sources already available to a plan. */
763
- type AvailableNames<Available extends Record<string, Plan.Source>> = Extract<keyof Available, string>
1021
+ type AvailableNames<Available extends Record<string, RowSet.AnySource>> = Extract<keyof Available, string>
764
1022
  /** Availability mode of a named source within the current plan scope. */
765
1023
  type SourceModeOf<
766
- Available extends Record<string, Plan.Source>,
1024
+ Available extends Record<string, RowSet.AnySource>,
767
1025
  Name extends string
768
1026
  > = Name extends keyof Available ? Available[Name]["mode"] : never
769
1027
  type TrueAssumptions = TrueFormula
770
1028
 
1029
+ /** Extracts the public plan state carried under `RowSet.TypeId`. */
1030
+ type QueryPlanParts<
1031
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1032
+ > = PlanValue[typeof RowSet.TypeId]
1033
+
1034
+ /** Extracts the internal phantom query state carried under `QueryTypeId`. */
1035
+ type QueryPlanState<
1036
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1037
+ > = PlanValue[typeof QueryTypeId]
1038
+
771
1039
  /** Extracts the selection carried by a query plan. */
772
- export type SelectionOfPlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
773
- PlanValue[typeof Plan.TypeId]["selection"]
1040
+ export type SelectionOfPlan<
1041
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1042
+ > = QueryPlanParts<PlanValue>["selection"]
774
1043
  /** Extracts the public required-source state carried by a query plan. */
775
- export type RequiredOfPlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
776
- PlanValue[typeof Plan.TypeId]["required"]
1044
+ export type RequiredOfPlan<
1045
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1046
+ > = QueryPlanParts<PlanValue>["required"]
777
1047
  /** Extracts the available-source scope carried by a query plan. */
778
- export type AvailableOfPlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
779
- PlanValue[typeof Plan.TypeId]["available"]
1048
+ export type AvailableOfPlan<
1049
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1050
+ > = QueryPlanParts<PlanValue>["available"]
780
1051
  /** Extracts the effective dialect carried by a query plan. */
781
- export type PlanDialectOf<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
782
- PlanValue[typeof Plan.TypeId]["dialect"]
1052
+ export type PlanDialectOf<
1053
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1054
+ > = QueryPlanParts<PlanValue>["dialect"]
783
1055
  /** Extracts the grouped-source phantom carried by a query plan. */
784
- export type GroupedOfPlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
785
- PlanValue extends QueryPlan<any, any, any, any, infer Grouped, any, any, any, any, any> ? Grouped : never
1056
+ export type GroupedOfPlan<
1057
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1058
+ > = QueryPlanState<PlanValue>["grouped"]
786
1059
  /** Extracts the available-name phantom carried by a query plan. */
787
- export type ScopedNamesOfPlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
788
- PlanValue extends QueryPlan<any, any, any, any, any, infer ScopedNames, any, any, any, any> ? ScopedNames : never
1060
+ export type ScopedNamesOfPlan<
1061
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1062
+ > = QueryPlanState<PlanValue>["availableNames"]
789
1063
  /** Extracts the outstanding-required-source phantom carried by a query plan. */
790
- export type OutstandingOfPlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
791
- PlanValue extends QueryPlan<any, any, any, any, any, any, infer Outstanding, any, any, any> ? Outstanding : never
792
- export type AssumptionsOfPlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
793
- PlanValue extends QueryPlan<any, any, any, any, any, any, any, infer Assumptions, any, any> ? Assumptions : TrueAssumptions
794
- export type CapabilitiesOfPlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
795
- PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, infer Capabilities, any> ? Capabilities : never
1064
+ export type OutstandingOfPlan<
1065
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1066
+ > = QueryPlanState<PlanValue>["required"]
1067
+ export type AssumptionsOfPlan<
1068
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1069
+ > = QueryPlanState<PlanValue>["assumptions"]
1070
+ export type CapabilitiesOfPlan<
1071
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1072
+ > = QueryPlanState<PlanValue>["capabilities"]
796
1073
  /** Extracts capabilities contributed by a source wrapper. */
797
1074
  export type SourceCapabilitiesOf<Source extends SourceLike> =
798
1075
  Source extends TableLike<any, any> ? never :
@@ -801,14 +1078,39 @@ export type SourceCapabilitiesOf<Source extends SourceLike> =
801
1078
  Source extends { readonly kind: "lateral"; readonly plan: infer PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any> } ? CapabilitiesOfPlan<PlanValue> :
802
1079
  never
803
1080
  /** Extracts the statement kind carried by a query plan. */
804
- export type StatementOfPlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
805
- PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, infer Statement> ? Statement : never
1081
+ export type StatementOfPlan<
1082
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1083
+ > = QueryPlanState<PlanValue>["statement"]
806
1084
  /** Extracts the mutation target phantom carried by a query plan. */
807
- export type MutationTargetOfPlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
808
- PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, infer Target> ? Target : never
1085
+ export type MutationTargetOfPlan<
1086
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1087
+ > = QueryPlanState<PlanValue>["target"]
809
1088
  /** Extracts whether an insert plan still needs a source attached. */
810
- export type InsertSourceStateOfPlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
811
- PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, infer InsertState> ? InsertState : "ready"
1089
+ export type InsertSourceStateOfPlan<
1090
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1091
+ > = QueryPlanState<PlanValue>["insertSource"]
1092
+ export type StateOfPlan<
1093
+ PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any, any, any>
1094
+ > = QueryPlanParts<PlanValue>
1095
+
1096
+ type PresenceWitnessKeysOfSelection<Selection> = Selection extends Expression.Any
1097
+ ? AstOf<Selection> extends ExpressionAst.ColumnNode<any, any>
1098
+ ? Expression.NullabilityOf<Selection> extends "never"
1099
+ ? ColumnKeyOfExpression<Selection>
1100
+ : never
1101
+ : never
1102
+ : Selection extends Record<string, any>
1103
+ ? {
1104
+ readonly [K in keyof Selection]: PresenceWitnessKeysOfSelection<Selection[K]>
1105
+ }[keyof Selection]
1106
+ : never
1107
+
1108
+ export type PresenceWitnessKeysOfSource<Source extends SourceLike> =
1109
+ Source extends TableLike<any, any>
1110
+ ? PresenceWitnessKeysOfSelection<Source[typeof RowSet.TypeId]["selection"]>
1111
+ : Source extends { readonly columns: infer Columns }
1112
+ ? PresenceWitnessKeysOfSelection<Columns>
1113
+ : never
812
1114
 
813
1115
  /**
814
1116
  * Adds a single source entry to the set of available sources.
@@ -816,17 +1118,21 @@ export type InsertSourceStateOfPlan<PlanValue extends QueryPlan<any, any, any, a
816
1118
  * This is used by `from(...)` and the join builders.
817
1119
  */
818
1120
  export type AddAvailable<
819
- Available extends Record<string, Plan.Source>,
1121
+ Available extends Record<string, RowSet.AnySource>,
820
1122
  Name extends string,
821
- Mode extends Plan.SourceMode = "required"
822
- > = Available & Record<Name, Plan.Source<Name, Mode>>
1123
+ Mode extends RowSet.SourceMode = "required",
1124
+ PresentFormula extends PredicateFormula = TrueFormula,
1125
+ PresenceWitness extends string = never
1126
+ > = Available & Record<Name, RowSet.Source<Name, Mode, PresentFormula, PresenceWitness>>
823
1127
 
824
1128
  export type AddAvailableMany<
825
- Available extends Record<string, Plan.Source>,
1129
+ Available extends Record<string, RowSet.AnySource>,
826
1130
  Names extends string,
827
- Mode extends Plan.SourceMode = "required"
1131
+ Mode extends RowSet.SourceMode = "required",
1132
+ PresentFormula extends PredicateFormula = TrueFormula,
1133
+ PresenceWitness extends string = never
828
1134
  > = Available & {
829
- readonly [K in Names]: Plan.Source<K, Mode>
1135
+ readonly [K in Names]: RowSet.Source<K, Mode, PresentFormula, PresenceWitness>
830
1136
  }
831
1137
 
832
1138
  /** Join mode projected into the plan's source-scope mode lattice. */
@@ -835,25 +1141,38 @@ export type JoinSourceMode<Kind extends QueryAst.JoinKind> = Kind extends "left"
835
1141
  : "required"
836
1142
 
837
1143
  type DemoteAllAvailable<
838
- Available extends Record<string, Plan.Source>
1144
+ Available extends Record<string, RowSet.AnySource>
839
1145
  > = {
840
- readonly [K in keyof Available]: Available[K] extends Plan.Source<infer Name extends string, any>
841
- ? Plan.Source<Name, "optional">
1146
+ readonly [K in keyof Available]: Available[K] extends RowSet.Source<
1147
+ infer Name extends string,
1148
+ any,
1149
+ infer PresentFormula extends PredicateFormula,
1150
+ infer PresenceWitness extends string
1151
+ >
1152
+ ? RowSet.Source<Name, "optional", PresentFormula, PresenceWitness>
842
1153
  : never
843
1154
  }
844
1155
 
845
1156
  export type ExistingAvailableAfterJoin<
846
- Available extends Record<string, Plan.Source>,
1157
+ Available extends Record<string, RowSet.AnySource>,
847
1158
  Kind extends QueryAst.JoinKind
848
1159
  > = Kind extends "right" | "full"
849
1160
  ? DemoteAllAvailable<Available>
850
1161
  : Available
851
1162
 
852
1163
  export type AvailableAfterJoin<
853
- Available extends Record<string, Plan.Source>,
1164
+ Available extends Record<string, RowSet.AnySource>,
854
1165
  JoinedName extends string,
855
- Kind extends QueryAst.JoinKind
856
- > = AddAvailable<ExistingAvailableAfterJoin<Available, Kind>, JoinedName, JoinSourceMode<Kind>>
1166
+ Kind extends QueryAst.JoinKind,
1167
+ PresentFormula extends PredicateFormula = TrueFormula,
1168
+ PresenceWitness extends string = never
1169
+ > = AddAvailable<
1170
+ ExistingAvailableAfterJoin<Available, Kind>,
1171
+ JoinedName,
1172
+ JoinSourceMode<Kind>,
1173
+ PresentFormula,
1174
+ PresenceWitness
1175
+ >
857
1176
 
858
1177
  /**
859
1178
  * Computes the next `required` set after introducing an additional expression.
@@ -862,7 +1181,7 @@ export type AvailableAfterJoin<
862
1181
  */
863
1182
  export type AddExpressionRequired<
864
1183
  Required,
865
- Available extends Record<string, Plan.Source>,
1184
+ Available extends Record<string, RowSet.AnySource>,
866
1185
  Value extends ExpressionInput
867
1186
  > = Exclude<Required | RequiredFromInput<Value>, AvailableNames<Available>>
868
1187
 
@@ -874,7 +1193,7 @@ export type AddExpressionRequired<
874
1193
  */
875
1194
  export type AddJoinRequired<
876
1195
  Required,
877
- Available extends Record<string, Plan.Source>,
1196
+ Available extends Record<string, RowSet.AnySource>,
878
1197
  JoinedName extends string,
879
1198
  Predicate extends PredicateInput | never,
880
1199
  Kind extends QueryAst.JoinKind = "inner"
@@ -885,8 +1204,8 @@ export type AddJoinRequired<
885
1204
 
886
1205
  /** Merges two aggregation kinds through a derived expression. */
887
1206
  export type MergeAggregation<
888
- Left extends Expression.AggregationKind,
889
- Right extends Expression.AggregationKind
1207
+ Left extends Expression.ScalarKind,
1208
+ Right extends Expression.ScalarKind
890
1209
  > = Left extends "window"
891
1210
  ? "window"
892
1211
  : Right extends "window"
@@ -900,9 +1219,9 @@ export type MergeAggregation<
900
1219
  /** Folds aggregation kinds across a tuple of expressions. */
901
1220
  type MergeAggregationTuple<
902
1221
  Values extends readonly Expression.Any[],
903
- Current extends Expression.AggregationKind = "scalar"
1222
+ Current extends Expression.ScalarKind = "scalar"
904
1223
  > = Values extends readonly [infer Head extends Expression.Any, ...infer Tail extends readonly Expression.Any[]]
905
- ? MergeAggregationTuple<Tail, MergeAggregation<Current, AggregationOf<Head>>>
1224
+ ? MergeAggregationTuple<Tail, MergeAggregation<Current, KindOf<Head>>>
906
1225
  : Current
907
1226
 
908
1227
  /** Merges two nullability states for null-propagating scalar operators. */
@@ -932,23 +1251,18 @@ export type TupleDialect<
932
1251
  Values extends readonly Expression.Any[]
933
1252
  > = Values[number] extends never ? never : DialectOf<Values[number]>
934
1253
 
935
- /** Source union across a tuple of expressions. */
936
- export type TupleSource<
937
- Values extends readonly Expression.Any[]
938
- > = Values[number] extends never ? never : SourceOf<Values[number]>
939
-
940
1254
  /** Converts a union into an intersection. */
941
1255
  type UnionToIntersection<Union> = (
942
1256
  Union extends any ? (value: Union) => void : never
943
1257
  ) extends (value: infer Intersection) => void ? Intersection : never
944
1258
 
945
- /** Dependency-map intersection suitable for provenance unions across a tuple. */
1259
+ /** Dependency union across a tuple of scalar expressions. */
946
1260
  export type TupleDependencies<
947
1261
  Values extends readonly Expression.Any[]
948
- > = DependencyRecord<Values[number] extends never ? never : Extract<keyof DependenciesOf<Values[number]>, string>>
1262
+ > = Values[number] extends never ? never : DependenciesOf<Values[number]>
949
1263
 
950
- /** Builds a canonical dependency map from a string union of table names. */
951
- export type DependencyRecord<Keys extends string> = [Keys] extends [never] ? {} : Record<Keys, true>
1264
+ /** Builds the canonical dependency union from a string union of table names. */
1265
+ export type DependencyRecord<Keys extends string> = Keys
952
1266
 
953
1267
  /** Grouped expression identities carried by a tuple of scalar expressions. */
954
1268
  export type GroupedKeysFromValues<
@@ -959,7 +1273,7 @@ export type GroupedKeysFromValues<
959
1273
 
960
1274
  /** Whether a selection contains any aggregate expressions. */
961
1275
  type SelectionHasAggregate<Selection> = Selection extends Expression.Any
962
- ? AggregationOf<Selection> extends "aggregate" ? true : false
1276
+ ? KindOf<Selection> extends "aggregate" ? true : false
963
1277
  : Selection extends Record<string, any>
964
1278
  ? Extract<{
965
1279
  [K in keyof Selection]: SelectionHasAggregate<Selection[K]>
@@ -971,9 +1285,9 @@ type IsGroupedSelectionValid<
971
1285
  Selection,
972
1286
  Grouped extends string
973
1287
  > = Selection extends Expression.Any
974
- ? AggregationOf<Selection> extends "aggregate"
1288
+ ? KindOf<Selection> extends "aggregate"
975
1289
  ? true
976
- : AggregationOf<Selection> extends "window"
1290
+ : KindOf<Selection> extends "window"
977
1291
  ? false
978
1292
  : RequiredFromDependencies<DependenciesOf<Selection>> extends never
979
1293
  ? true
@@ -1009,7 +1323,7 @@ type MergeNullabilityStates<
1009
1323
 
1010
1324
  type FoldEffectiveNullability<
1011
1325
  Values extends readonly Expression.Any[],
1012
- Available extends Record<string, Plan.Source>,
1326
+ Available extends Record<string, RowSet.AnySource>,
1013
1327
  Assumptions extends PredicateFormula
1014
1328
  > = Extract<{
1015
1329
  [K in keyof Values]: Values[K] extends Expression.Any ? EffectiveNullability<Values[K], Available, Assumptions> : never
@@ -1023,7 +1337,7 @@ type FoldEffectiveNullability<
1023
1337
 
1024
1338
  type CoalesceEffectiveNullability<
1025
1339
  Values extends readonly Expression.Any[],
1026
- Available extends Record<string, Plan.Source>,
1340
+ Available extends Record<string, RowSet.AnySource>,
1027
1341
  Assumptions extends PredicateFormula
1028
1342
  > = Extract<{
1029
1343
  [K in keyof Values]: Values[K] extends Expression.Any ? EffectiveNullability<Values[K], Available, Assumptions> : never
@@ -1040,42 +1354,183 @@ type NullabilityOfOutput<Output> =
1040
1354
  ? Exclude<Output, null> extends never ? "always" : "maybe"
1041
1355
  : "never"
1042
1356
 
1043
- type RequiredTablesFromAssumptions<Assumptions extends PredicateFormula> =
1044
- GuaranteedSourceNames<Assumptions>
1357
+ type PreciseFactSet<Value extends string> = string extends Value ? never : Value
1358
+
1359
+ type KnownGuaranteedNullKeys<
1360
+ Assumptions extends PredicateFormula
1361
+ > = PreciseFactSet<GuaranteedNullKeys<Assumptions>>
1362
+
1363
+ type KnownGuaranteedNonNullKeys<
1364
+ Assumptions extends PredicateFormula
1365
+ > = PreciseFactSet<GuaranteedNonNullKeys<Assumptions>>
1366
+
1367
+ type KnownGuaranteedSourceNames<
1368
+ Assumptions extends PredicateFormula
1369
+ > = PreciseFactSet<GuaranteedSourceNames<Assumptions>>
1370
+
1371
+ type ExplicitlyRequiredSourceNames<
1372
+ Available extends Record<string, RowSet.AnySource>
1373
+ > = Extract<{
1374
+ readonly [K in keyof Available]:
1375
+ Available[K] extends RowSet.Source<any, infer Mode extends RowSet.SourceMode>
1376
+ ? Mode extends "required" ? K : never
1377
+ : never
1378
+ }[keyof Available], string>
1379
+
1380
+ type PresentFormulaOfSource<Source extends RowSet.AnySource> =
1381
+ Source extends RowSet.Source<any, any, infer PresentFormula extends PredicateFormula, any>
1382
+ ? PresentFormula
1383
+ : TrueFormula
1384
+
1385
+ type PresenceWitnessesOfSource<Source extends RowSet.AnySource> =
1386
+ Source extends RowSet.Source<any, any, any, infer PresenceWitness extends string>
1387
+ ? PresenceWitness
1388
+ : never
1389
+
1390
+ type ImpliedSourceNamesFromRequired<
1391
+ Available extends Record<string, RowSet.AnySource>,
1392
+ Required extends string
1393
+ > = Extract<{
1394
+ readonly [K in Extract<keyof Available, string>]:
1395
+ K extends Required
1396
+ ? PreciseFactSet<GuaranteedSourceNames<PresentFormulaOfSource<Available[K]>>>
1397
+ : never
1398
+ }[Extract<keyof Available, string>], string>
1399
+
1400
+ type ExpandRequiredSourceNames<
1401
+ Available extends Record<string, RowSet.AnySource>,
1402
+ Required extends string
1403
+ > = ExpandRequiredSourceNamesStep<
1404
+ Available,
1405
+ Required,
1406
+ Required | ImpliedSourceNamesFromRequired<Available, Required>
1407
+ >
1408
+
1409
+ type ExpandRequiredSourceNamesStep<
1410
+ Available extends Record<string, RowSet.AnySource>,
1411
+ Current extends string,
1412
+ Next extends string
1413
+ > = [Exclude<Next, Current>] extends [never]
1414
+ ? Current
1415
+ : ExpandRequiredSourceNames<Available, Next>
1416
+
1417
+ type DirectlyAbsentSourceNames<
1418
+ Available extends Record<string, RowSet.AnySource>,
1419
+ Assumptions extends PredicateFormula
1420
+ > = Extract<{
1421
+ readonly [K in Extract<keyof Available, string>]:
1422
+ K extends string
1423
+ ? PresenceWitnessesOfSource<Available[K]> extends infer Witnesses extends string
1424
+ ? Extract<Witnesses, KnownGuaranteedNullKeys<Assumptions>> extends never
1425
+ ? ContradictsFormula<Assumptions, PresentFormulaOfSource<Available[K]>> extends true
1426
+ ? K
1427
+ : never
1428
+ : K
1429
+ : never
1430
+ : never
1431
+ }[Extract<keyof Available, string>], string>
1432
+
1433
+ type ImpliedAbsentSourceNames<
1434
+ Available extends Record<string, RowSet.AnySource>,
1435
+ Absent extends string
1436
+ > = Extract<{
1437
+ readonly [K in Extract<keyof Available, string>]:
1438
+ Extract<PreciseFactSet<GuaranteedSourceNames<PresentFormulaOfSource<Available[K]>>>, Absent> extends never
1439
+ ? never
1440
+ : K
1441
+ }[Extract<keyof Available, string>], string>
1442
+
1443
+ type ExpandAbsentSourceNames<
1444
+ Available extends Record<string, RowSet.AnySource>,
1445
+ Current extends string
1446
+ > = ExpandAbsentSourceNamesStep<
1447
+ Available,
1448
+ Current,
1449
+ Current | ImpliedAbsentSourceNames<Available, Current>
1450
+ >
1451
+
1452
+ type ExpandAbsentSourceNamesStep<
1453
+ Available extends Record<string, RowSet.AnySource>,
1454
+ Current extends string,
1455
+ Next extends string
1456
+ > = [Exclude<Next, Current>] extends [never]
1457
+ ? Current
1458
+ : ExpandAbsentSourceNames<Available, Next>
1459
+
1460
+ type AbsentSourceNamesInScope<
1461
+ Available extends Record<string, RowSet.AnySource>,
1462
+ Assumptions extends PredicateFormula
1463
+ > = ExpandAbsentSourceNames<Available, DirectlyAbsentSourceNames<Available, Assumptions>>
1464
+
1465
+ type RequiredSourceNamesInScope<
1466
+ Available extends Record<string, RowSet.AnySource>,
1467
+ Assumptions extends PredicateFormula
1468
+ > = Exclude<
1469
+ ExpandRequiredSourceNames<
1470
+ Available,
1471
+ ExplicitlyRequiredSourceNames<Available> | KnownGuaranteedSourceNames<Assumptions>
1472
+ >,
1473
+ AbsentSourceNamesInScope<Available, Assumptions>
1474
+ >
1045
1475
 
1046
1476
  type EffectiveAvailable<
1047
- Available extends Record<string, Plan.Source>,
1477
+ Available extends Record<string, RowSet.AnySource>,
1048
1478
  Assumptions extends PredicateFormula
1049
1479
  > = {
1050
- readonly [K in keyof Available]: Available[K] & {
1051
- readonly mode: K extends RequiredTablesFromAssumptions<Assumptions> ? "required" : Available[K]["mode"]
1052
- }
1480
+ readonly [K in keyof Available]:
1481
+ Available[K] extends RowSet.Source<
1482
+ infer Name extends string,
1483
+ infer Mode extends RowSet.SourceMode,
1484
+ infer PresentFormula extends PredicateFormula,
1485
+ infer PresenceWitness extends string
1486
+ >
1487
+ ? RowSet.Source<
1488
+ Name,
1489
+ K extends RequiredSourceNamesInScope<Available, Assumptions> ? "required" : Mode,
1490
+ PresentFormula,
1491
+ PresenceWitness
1492
+ > & {
1493
+ readonly baseName?: Available[K]["baseName"]
1494
+ }
1495
+ : never
1053
1496
  }
1054
1497
 
1498
+ type HasAbsentSource<
1499
+ Dependencies extends Expression.BindingId,
1500
+ Available extends Record<string, RowSet.AnySource>,
1501
+ Assumptions extends PredicateFormula
1502
+ > = Extract<Dependencies, AbsentSourceNamesInScope<Available, Assumptions>> extends never ? false : true
1503
+
1504
+ type OptionalSourceNamesInScope<
1505
+ Available extends Record<string, RowSet.AnySource>
1506
+ > = Extract<{
1507
+ [K in keyof Available & string]: SourceModeOf<Available, K> extends "optional" ? K : never
1508
+ }[keyof Available & string], string>
1509
+
1055
1510
  type BaseEffectiveNullability<
1056
1511
  Value extends Expression.Any,
1057
- Available extends Record<string, Plan.Source>,
1512
+ Available extends Record<string, RowSet.AnySource>,
1058
1513
  Assumptions extends PredicateFormula
1059
1514
  > = AstOf<Value> extends ExpressionAst.ColumnNode<infer TableName extends string, infer ColumnName extends string>
1060
- ? `${TableName}.${ColumnName}` extends GuaranteedNullKeys<Assumptions>
1515
+ ? TableName extends AbsentSourceNamesInScope<Available, Assumptions>
1516
+ ? "always"
1517
+ : `${TableName}.${ColumnName}` extends KnownGuaranteedNullKeys<Assumptions>
1061
1518
  ? "always"
1062
- : `${TableName}.${ColumnName}` extends GuaranteedNonNullKeys<Assumptions>
1519
+ : `${TableName}.${ColumnName}` extends KnownGuaranteedNonNullKeys<Assumptions>
1063
1520
  ? "never"
1064
1521
  : Expression.NullabilityOf<Value> extends "always" ? "always"
1065
- : Expression.SourceNullabilityOf<Value> extends "resolved"
1066
- ? Expression.NullabilityOf<Value>
1067
- : HasOptionalSource<DependenciesOf<Value>, Available> extends true ? "maybe"
1068
- : Expression.NullabilityOf<Value>
1522
+ : HasAbsentSource<DependenciesOf<Value>, Available, Assumptions> extends true ? "always"
1523
+ : HasOptionalSource<DependenciesOf<Value>, Available> extends true ? "maybe"
1524
+ : Expression.NullabilityOf<Value>
1069
1525
  : Expression.NullabilityOf<Value> extends "always" ? "always"
1070
- : Expression.SourceNullabilityOf<Value> extends "resolved"
1071
- ? Expression.NullabilityOf<Value>
1526
+ : HasAbsentSource<DependenciesOf<Value>, Available, Assumptions> extends true ? "always"
1072
1527
  : HasOptionalSource<DependenciesOf<Value>, Available> extends true ? "maybe"
1073
- : Expression.NullabilityOf<Value>
1528
+ : Expression.NullabilityOf<Value>
1074
1529
 
1075
1530
  type CaseOutputOf<
1076
1531
  Branches extends readonly ExpressionAst.CaseBranchNode[],
1077
1532
  Else extends Expression.Any,
1078
- Available extends Record<string, Plan.Source>,
1533
+ Available extends Record<string, RowSet.AnySource>,
1079
1534
  Assumptions extends PredicateFormula
1080
1535
  > = Branches extends readonly [
1081
1536
  infer Head extends ExpressionAst.CaseBranchNode,
@@ -1092,54 +1547,71 @@ type CaseOutputOf<
1092
1547
  : ExpressionOutput<Else, EffectiveAvailable<Available, Assumptions>, Assumptions>
1093
1548
 
1094
1549
  /** Effective nullability of an expression after source-scope nullability is applied. */
1550
+ type EffectiveNullabilityOfAst<
1551
+ Value extends Expression.Any,
1552
+ Ast extends ExpressionAst.Any,
1553
+ Available extends Record<string, RowSet.AnySource>,
1554
+ Assumptions extends PredicateFormula = TrueAssumptions
1555
+ > = Ast extends ExpressionAst.ColumnNode<any, any>
1556
+ ? BaseEffectiveNullability<Value, Available, Assumptions>
1557
+ : Ast extends ExpressionAst.LiteralNode<any>
1558
+ ? Expression.NullabilityOf<Value>
1559
+ : Ast extends ExpressionAst.UnaryNode<infer Kind, infer UnaryValue extends Expression.Any>
1560
+ ? Kind extends "upper" | "lower" | "not"
1561
+ ? EffectiveNullability<UnaryValue, Available, Assumptions>
1562
+ : Kind extends "isNull" | "isNotNull" | "count"
1563
+ ? "never"
1564
+ : Expression.NullabilityOf<Value>
1565
+ : Ast extends ExpressionAst.BinaryNode<"eq", infer Left extends Expression.Any, infer Right extends Expression.Any>
1566
+ ? EffectiveNullability<Left, Available, Assumptions> extends "never"
1567
+ ? EffectiveNullability<Right, Available, Assumptions> extends "never" ? "never" : "maybe"
1568
+ : "maybe"
1569
+ : Ast extends ExpressionAst.VariadicNode<infer Kind, infer Values extends readonly Expression.Any[]>
1570
+ ? Kind extends "coalesce"
1571
+ ? CoalesceEffectiveNullability<Values, Available, Assumptions>
1572
+ : Kind extends "and" | "or" | "concat"
1573
+ ? FoldEffectiveNullability<Values, Available, Assumptions>
1574
+ : BaseEffectiveNullability<Value, Available, Assumptions>
1575
+ : Ast extends ExpressionAst.CaseNode<infer Branches extends readonly ExpressionAst.CaseBranchNode[], infer Else extends Expression.Any>
1576
+ ? NullabilityOfOutput<CaseOutputOf<Branches, Else, Available, Assumptions>>
1577
+ : BaseEffectiveNullability<Value, Available, Assumptions>
1578
+
1095
1579
  export type EffectiveNullability<
1096
1580
  Value extends Expression.Any,
1097
- Available extends Record<string, Plan.Source>,
1581
+ Available extends Record<string, RowSet.AnySource>,
1098
1582
  Assumptions extends PredicateFormula = TrueAssumptions
1099
1583
  > =
1100
1584
  AstOf<Value> extends infer Ast extends ExpressionAst.Any
1101
- ? Ast extends ExpressionAst.ColumnNode<any, any>
1102
- ? BaseEffectiveNullability<Value, Available, Assumptions>
1103
- : Ast extends ExpressionAst.LiteralNode<any>
1104
- ? Expression.NullabilityOf<Value>
1105
- : Ast extends ExpressionAst.UnaryNode<infer Kind, infer UnaryValue extends Expression.Any>
1106
- ? Kind extends "upper" | "lower" | "not"
1107
- ? EffectiveNullability<UnaryValue, Available, Assumptions>
1108
- : Kind extends "isNull" | "isNotNull" | "count"
1109
- ? "never"
1110
- : Expression.NullabilityOf<Value>
1111
- : Ast extends ExpressionAst.BinaryNode<"eq", infer Left extends Expression.Any, infer Right extends Expression.Any>
1112
- ? EffectiveNullability<Left, Available, Assumptions> extends "never"
1113
- ? EffectiveNullability<Right, Available, Assumptions> extends "never" ? "never" : "maybe"
1114
- : "maybe"
1115
- : Ast extends ExpressionAst.VariadicNode<infer Kind, infer Values extends readonly Expression.Any[]>
1116
- ? Kind extends "coalesce"
1117
- ? CoalesceEffectiveNullability<Values, Available, Assumptions>
1118
- : Kind extends "and" | "or" | "concat"
1119
- ? FoldEffectiveNullability<Values, Available, Assumptions>
1120
- : BaseEffectiveNullability<Value, Available, Assumptions>
1121
- : Ast extends ExpressionAst.CaseNode<infer Branches extends readonly ExpressionAst.CaseBranchNode[], infer Else extends Expression.Any>
1122
- ? NullabilityOfOutput<CaseOutputOf<Branches, Else, Available, Assumptions>>
1123
- : BaseEffectiveNullability<Value, Available, Assumptions>
1585
+ ? EffectiveNullabilityOfAst<Value, Ast, Available, Assumptions>
1124
1586
  : BaseEffectiveNullability<Value, Available, Assumptions>
1125
1587
 
1126
1588
  /** Result runtime type of an expression after effective nullability is resolved. */
1127
1589
  export type ExpressionOutput<
1128
1590
  Value extends Expression.Any,
1129
- Available extends Record<string, Plan.Source>,
1591
+ Available extends Record<string, RowSet.AnySource>,
1130
1592
  Assumptions extends PredicateFormula = TrueAssumptions
1131
- > = AstOf<Value> extends ExpressionAst.CaseNode<infer Branches extends readonly ExpressionAst.CaseBranchNode[], infer Else extends Expression.Any>
1132
- ? CaseOutputOf<Branches, Else, Available, Assumptions>
1133
- : EffectiveNullability<Value, Available, Assumptions> extends "never"
1134
- ? Expression.RuntimeOf<Value>
1135
- : EffectiveNullability<Value, Available, Assumptions> extends "always"
1136
- ? null
1137
- : Expression.RuntimeOf<Value> | null
1593
+ > = AstOf<Value> extends infer Ast extends ExpressionAst.Any
1594
+ ? Ast extends ExpressionAst.CaseNode<infer Branches extends readonly ExpressionAst.CaseBranchNode[], infer Else extends Expression.Any>
1595
+ ? CaseOutputOf<Branches, Else, Available, Assumptions>
1596
+ : EffectiveNullabilityOfAst<Value, Ast, Available, Assumptions> extends infer Nullability
1597
+ ? Expression.NullabilityOf<Value> extends infer BaseNullability
1598
+ ? Expression.RuntimeOf<Value> extends infer Runtime
1599
+ ? Nullability extends "never"
1600
+ ? BaseNullability extends "never"
1601
+ ? Runtime
1602
+ : NonNullable<Runtime>
1603
+ : Nullability extends "always"
1604
+ ? null
1605
+ : Runtime | null
1606
+ : never
1607
+ : never
1608
+ : never
1609
+ : never
1138
1610
 
1139
1611
  /** Result runtime type of a nested selection after source-scope nullability is resolved. */
1140
1612
  export type OutputOfSelection<
1141
1613
  Selection,
1142
- Available extends Record<string, Plan.Source>,
1614
+ Available extends Record<string, RowSet.AnySource>,
1143
1615
  Assumptions extends PredicateFormula = TrueAssumptions
1144
1616
  > = Selection extends Expression.Any
1145
1617
  ? ExpressionOutput<Selection, Available, Assumptions>
@@ -1149,22 +1621,36 @@ export type OutputOfSelection<
1149
1621
  }
1150
1622
  : never
1151
1623
 
1152
- /** Resolved row type produced by a concrete query plan. */
1153
- export type ResultRow<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> = OutputOfSelection<
1154
- PlanValue[typeof Plan.TypeId]["selection"],
1155
- EffectiveAvailable<PlanValue[typeof Plan.TypeId]["available"], AssumptionsOfPlan<PlanValue>>,
1156
- AssumptionsOfPlan<PlanValue>
1624
+ type ResolvedSelectionOutput<
1625
+ Selection,
1626
+ Available extends Record<string, RowSet.AnySource>,
1627
+ Assumptions extends PredicateFormula
1628
+ > = OutputOfSelection<
1629
+ Selection,
1630
+ EffectiveAvailable<Available, Assumptions>,
1631
+ Assumptions
1157
1632
  >
1158
1633
 
1634
+ /** Resolved row type produced by a concrete query plan. */
1635
+ export type ResultRow<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
1636
+ SelectionOfPlan<PlanValue> extends infer Selection
1637
+ ? AvailableOfPlan<PlanValue> extends infer Available extends Record<string, RowSet.AnySource>
1638
+ ? AssumptionsOfPlan<PlanValue> extends infer Assumptions extends PredicateFormula
1639
+ ? ResolvedSelectionOutput<Selection, Available, Assumptions>
1640
+ : never
1641
+ : never
1642
+ : never
1643
+
1159
1644
  /** Resolved row collection type produced by a concrete query plan. */
1160
1645
  export type ResultRows<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> = ReadonlyArray<ResultRow<PlanValue>>
1161
1646
 
1162
1647
  /** Conservative runtime row shape produced by remapping projection aliases. */
1163
- export type RuntimeResultRow<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> = OutputOfSelection<
1164
- PlanValue[typeof Plan.TypeId]["selection"],
1165
- PlanValue[typeof Plan.TypeId]["available"],
1166
- TrueAssumptions
1167
- >
1648
+ export type RuntimeResultRow<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
1649
+ SelectionOfPlan<PlanValue> extends infer Selection
1650
+ ? AvailableOfPlan<PlanValue> extends infer Available extends Record<string, RowSet.AnySource>
1651
+ ? OutputOfSelection<Selection, Available, TrueAssumptions>
1652
+ : never
1653
+ : never
1168
1654
 
1169
1655
  /** Conservative runtime row collection type. */
1170
1656
  export type RuntimeResultRows<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> = ReadonlyArray<RuntimeResultRow<PlanValue>>
@@ -1197,7 +1683,7 @@ type DialectCompatibilityError<
1197
1683
  EngineDialect extends string
1198
1684
  > = PlanValue & {
1199
1685
  readonly __effect_qb_error__: "effect-qb: plan dialect is not compatible with the target renderer or executor"
1200
- readonly __effect_qb_plan_dialect__: PlanValue[typeof Plan.TypeId]["dialect"]
1686
+ readonly __effect_qb_plan_dialect__: PlanValue[typeof RowSet.TypeId]["dialect"]
1201
1687
  readonly __effect_qb_target_dialect__: EngineDialect
1202
1688
  readonly __effect_qb_hint__: "Use the matching dialect module or renderer/executor"
1203
1689
  }
@@ -1224,25 +1710,23 @@ type InsertHasOptionalDefaults<
1224
1710
  /** Narrows a query plan to aggregate-compatible selections. */
1225
1711
  export type AggregationCompatiblePlan<
1226
1712
  PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>
1227
- > = PlanValue extends QueryPlan<infer Selection, any, any, any, infer Grouped, any, any, any, any, any>
1228
- ? IsAggregationCompatibleSelection<Selection, Grouped> extends true ? PlanValue : AggregationCompatibilityError<PlanValue>
1229
- : never
1713
+ > = IsAggregationCompatibleSelection<SelectionOfPlan<PlanValue>, GroupedOfPlan<PlanValue>> extends true
1714
+ ? PlanValue
1715
+ : AggregationCompatibilityError<PlanValue>
1230
1716
 
1231
1717
  /** Narrows a query plan to aggregate-compatible, source-complete plans. */
1232
1718
  export type CompletePlan<PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
1233
- PlanValue extends QueryPlan<infer Selection, infer Required, any, any, infer Grouped, any, any, any, any, infer Statement, any, infer InsertState>
1234
- ? Statement extends "insert"
1235
- ? InsertState extends "missing"
1236
- ? InsertHasOptionalDefaults<PlanValue> extends true
1237
- ? PlanValue
1238
- : InsertSourceCompletenessError<PlanValue>
1239
- : HasKnownOutstanding<Required> extends true
1240
- ? SourceCompletenessError<PlanValue, Extract<Required, string>>
1241
- : IsAggregationCompatibleSelection<Selection, Grouped> extends true ? PlanValue : AggregationCompatibilityError<PlanValue>
1242
- : HasKnownOutstanding<Required> extends true
1243
- ? SourceCompletenessError<PlanValue, Extract<Required, string>>
1244
- : IsAggregationCompatibleSelection<Selection, Grouped> extends true ? PlanValue : AggregationCompatibilityError<PlanValue>
1245
- : never
1719
+ StatementOfPlan<PlanValue> extends "insert"
1720
+ ? InsertSourceStateOfPlan<PlanValue> extends "missing"
1721
+ ? InsertHasOptionalDefaults<PlanValue> extends true
1722
+ ? PlanValue
1723
+ : InsertSourceCompletenessError<PlanValue>
1724
+ : HasKnownOutstanding<RequiredOfPlan<PlanValue>> extends true
1725
+ ? SourceCompletenessError<PlanValue, Extract<RequiredOfPlan<PlanValue>, string>>
1726
+ : IsAggregationCompatibleSelection<SelectionOfPlan<PlanValue>, GroupedOfPlan<PlanValue>> extends true ? PlanValue : AggregationCompatibilityError<PlanValue>
1727
+ : HasKnownOutstanding<RequiredOfPlan<PlanValue>> extends true
1728
+ ? SourceCompletenessError<PlanValue, Extract<RequiredOfPlan<PlanValue>, string>>
1729
+ : IsAggregationCompatibleSelection<SelectionOfPlan<PlanValue>, GroupedOfPlan<PlanValue>> extends true ? PlanValue : AggregationCompatibilityError<PlanValue>
1246
1730
 
1247
1731
  /** Whether a plan dialect is compatible with a target engine dialect. */
1248
1732
  type IsDialectCompatible<
@@ -1258,7 +1742,7 @@ type IsDialectCompatible<
1258
1742
  export type DialectCompatiblePlan<
1259
1743
  PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>,
1260
1744
  EngineDialect extends string
1261
- > = IsDialectCompatible<PlanValue[typeof Plan.TypeId]["dialect"], EngineDialect> extends true
1745
+ > = IsDialectCompatible<PlanValue[typeof RowSet.TypeId]["dialect"], EngineDialect> extends true
1262
1746
  ? CompletePlan<PlanValue>
1263
1747
  : DialectCompatibilityError<PlanValue, EngineDialect>
1264
1748
 
@@ -1266,7 +1750,7 @@ export type DialectCompatiblePlan<
1266
1750
  export type DialectCompatibleNestedPlan<
1267
1751
  PlanValue extends QueryPlan<any, any, any, any, any, any, any, any, any, any>,
1268
1752
  EngineDialect extends string
1269
- > = IsDialectCompatible<PlanValue[typeof Plan.TypeId]["dialect"], EngineDialect> extends true
1753
+ > = IsDialectCompatible<PlanValue[typeof RowSet.TypeId]["dialect"], EngineDialect> extends true
1270
1754
  ? AggregationCompatiblePlan<PlanValue>
1271
1755
  : DialectCompatibilityError<PlanValue, EngineDialect>
1272
1756
 
@@ -1351,11 +1835,9 @@ export type SetCompatibleRightPlan<
1351
1835
 
1352
1836
  /** True when any of an expression's dependencies are optional in the current scope. */
1353
1837
  type HasOptionalSource<
1354
- Dependencies extends Expression.SourceDependencies,
1355
- Available extends Record<string, Plan.Source>
1356
- > = Extract<{
1357
- [K in keyof Dependencies & string]: SourceModeOf<Available, K> extends "optional" ? true : never
1358
- }[keyof Dependencies & string], true> extends never ? false : true
1838
+ Dependencies extends Expression.BindingId,
1839
+ Available extends Record<string, RowSet.AnySource>
1840
+ > = Extract<Dependencies, OptionalSourceNamesInScope<Available>> extends never ? false : true
1359
1841
 
1360
1842
  /**
1361
1843
  * Concrete query-plan value produced by the query DSL.
@@ -1367,65 +1849,51 @@ type HasOptionalSource<
1367
1849
  export type QueryPlan<
1368
1850
  Selection,
1369
1851
  Required = never,
1370
- Available extends Record<string, Plan.Source> = {},
1852
+ Available extends Record<string, RowSet.AnySource> = {},
1371
1853
  Dialect extends string = never,
1372
1854
  Grouped extends string = never,
1373
- ScopedNames extends string = Extract<keyof Available, string>,
1374
- Outstanding extends string = Extract<Required, string>,
1855
+ ScopedNames extends string = never,
1856
+ Outstanding extends string = never,
1375
1857
  Assumptions extends PredicateFormula = TrueAssumptions,
1376
1858
  Capabilities extends QueryCapability = "read",
1377
1859
  Statement extends QueryAst.QueryStatement = "select",
1378
- Target = unknown,
1860
+ Target = any,
1379
1861
  InsertState extends InsertSourceState = InsertSourceState
1380
- > = Plan.Plan<Selection, Required, Available, Dialect> & {
1381
- readonly [Plan.TypeId]: Plan.State<Selection, Required, Available, Dialect>
1862
+ > = RowSet.RowSet<Selection, Required, Available, Dialect> & {
1863
+ readonly [QueryTypeId]: QueryState<
1864
+ Outstanding,
1865
+ ScopedNames,
1866
+ Grouped,
1867
+ Assumptions,
1868
+ Capabilities,
1869
+ Statement,
1870
+ Target,
1871
+ InsertState
1872
+ >
1382
1873
  readonly [QueryAst.TypeId]: QueryAst.Ast<Selection, Grouped, Statement>
1383
- readonly [QueryTypeId]: QueryState<Outstanding, ScopedNames, Grouped, Assumptions, Capabilities, Statement, Target, InsertState>
1384
1874
  }
1385
1875
 
1386
- /**
1387
- * Normalizes expression provenance into a flat list.
1388
- *
1389
- * Single-source expressions store one provenance object, while derived
1390
- * operators may carry multiple sources. This helper hides that shape
1391
- * difference.
1392
- */
1393
- const normalizeSources = (source: unknown): readonly unknown[] =>
1394
- source === undefined ? [] : Array.isArray(source) ? source : [source]
1395
-
1396
- /**
1397
- * Merges the provenance of two expressions into one normalized runtime value.
1398
- *
1399
- * The result is:
1400
- * - `undefined` when neither side is sourced
1401
- * - a single provenance object when exactly one source exists
1402
- * - an array when multiple sources are involved
1403
- */
1404
- export const mergeSources = (left: unknown, right?: unknown): unknown => {
1405
- const values = [...normalizeSources(left), ...normalizeSources(right)]
1406
- if (values.length === 0) {
1407
- return undefined
1408
- }
1409
- if (values.length === 1) {
1410
- return values[0]
1411
- }
1412
- return values
1876
+ export namespace Plan {
1877
+ export type Any = QueryPlan<any, any, any, any, any, any, any, any, any, any>
1413
1878
  }
1414
1879
 
1415
- /** Merges two expression dependency maps into a single normalized record. */
1416
- export const mergeDependencies = (
1417
- left: Expression.SourceDependencies,
1418
- right: Expression.SourceDependencies = {}
1419
- ): Expression.SourceDependencies => ({
1420
- ...left,
1421
- ...right
1422
- })
1880
+ /** Merges two expression dependency records into a single normalized record. */
1881
+ export const mergeDependencies = <
1882
+ Left extends Expression.BindingId = never,
1883
+ Right extends Expression.BindingId = never
1884
+ >(
1885
+ left: Record<Left, true> | undefined,
1886
+ right: Record<Right, true> | undefined = undefined
1887
+ ): Record<Left | Right, true> => ({
1888
+ ...(left ?? {}),
1889
+ ...(right ?? {})
1890
+ }) as Record<Left | Right, true>
1423
1891
 
1424
1892
  /** Merges expression aggregation kinds at runtime. */
1425
1893
  export const mergeAggregationRuntime = (
1426
- left: Expression.AggregationKind,
1427
- right: Expression.AggregationKind = "scalar"
1428
- ): Expression.AggregationKind =>
1894
+ left: Expression.ScalarKind,
1895
+ right: Expression.ScalarKind = "scalar"
1896
+ ): Expression.ScalarKind =>
1429
1897
  left === "window" || right === "window"
1430
1898
  ? "window"
1431
1899
  : left === "aggregate" || right === "aggregate"
@@ -1435,10 +1903,10 @@ export const mergeAggregationRuntime = (
1435
1903
  /** Folds runtime aggregation across a list of expressions. */
1436
1904
  export const mergeAggregationManyRuntime = (
1437
1905
  values: readonly Expression.Any[]
1438
- ): Expression.AggregationKind =>
1906
+ ): Expression.ScalarKind =>
1439
1907
  values.reduce(
1440
- (current, value) => mergeAggregationRuntime(current, value[Expression.TypeId].aggregation),
1441
- "scalar" as Expression.AggregationKind
1908
+ (current, value) => mergeAggregationRuntime(current, value[Expression.TypeId].kind),
1909
+ "scalar" as Expression.ScalarKind
1442
1910
  )
1443
1911
 
1444
1912
  /** Merges expression nullability for null-propagating scalar operators. */
@@ -1461,19 +1929,14 @@ export const mergeNullabilityManyRuntime = (
1461
1929
  "never" as Expression.Nullability
1462
1930
  )
1463
1931
 
1464
- /** Merges provenance across a variadic expression input list. */
1465
- export const mergeManySources = (values: readonly Expression.Any[]): unknown =>
1466
- values.reduce<unknown>(
1467
- (current, value) => mergeSources(current, value[Expression.TypeId].source),
1468
- undefined
1469
- )
1470
-
1471
1932
  /** Merges dependency maps across a variadic expression input list. */
1472
- export const mergeManyDependencies = (values: readonly Expression.Any[]): Expression.SourceDependencies =>
1473
- values.reduce(
1474
- (current, value) => mergeDependencies(current, value[Expression.TypeId].dependencies),
1475
- {} as Expression.SourceDependencies
1476
- )
1933
+ export const mergeManyDependencies = <Values extends readonly Expression.Any[]>(
1934
+ values: Values
1935
+ ): Record<TupleDependencies<Values>, true> =>
1936
+ values.reduce<Record<string, true>>(
1937
+ (current, value) => mergeDependencies(current, value[Expression.TypeId].dependencies) as Record<string, true>,
1938
+ {}
1939
+ ) as Record<TupleDependencies<Values>, true>
1477
1940
 
1478
1941
  /**
1479
1942
  * Creates a runtime expression object from fully computed static metadata.
@@ -1486,19 +1949,41 @@ export const makeExpression = <
1486
1949
  Db extends Expression.DbType.Any,
1487
1950
  Nullable extends Expression.Nullability,
1488
1951
  Dialect extends string,
1489
- Aggregation extends Expression.AggregationKind,
1490
- Source,
1491
- Dependencies extends Expression.SourceDependencies = {},
1492
- SourceNullability extends Expression.SourceNullabilityMode = "propagate",
1493
- Ast extends ExpressionAst.Any = ExpressionAst.Any
1952
+ Kind extends Expression.ScalarKind,
1953
+ Deps extends Expression.BindingId = never,
1954
+ Ast extends ExpressionAst.Any = ExpressionAst.Any,
1955
+ GroupKey extends string = GroupingKeyOfAst<Ast>
1494
1956
  >(
1495
- state: Expression.State<Runtime, Db, Nullable, Dialect, Aggregation, Source, Dependencies, SourceNullability>,
1957
+ state: {
1958
+ readonly runtime: Runtime
1959
+ readonly dbType: Db
1960
+ readonly runtimeSchema?: Schema.Schema.Any
1961
+ readonly nullability: Nullable
1962
+ readonly dialect: Dialect
1963
+ readonly kind?: Kind
1964
+ readonly dependencies?: Record<string, true>
1965
+ },
1496
1966
  ast: Ast
1497
- ): Expression.Expression<Runtime, Db, Nullable, Dialect, Aggregation, Source, Dependencies, SourceNullability> & {
1967
+ ): Expression.Scalar<Runtime, Db, Nullable, Dialect, Kind, Deps, GroupKey> & {
1498
1968
  readonly [ExpressionAst.TypeId]: Ast
1499
1969
  } => {
1500
1970
  const expression = Object.create(ExpressionProto)
1501
- expression[Expression.TypeId] = state
1971
+ Object.defineProperty(expression, "pipe", {
1972
+ configurable: true,
1973
+ writable: true,
1974
+ value: function(this: unknown) {
1975
+ return pipeArguments(expression, arguments)
1976
+ }
1977
+ })
1978
+ expression[Expression.TypeId] = {
1979
+ runtime: state.runtime,
1980
+ dbType: state.dbType,
1981
+ runtimeSchema: state.runtimeSchema,
1982
+ nullability: state.nullability,
1983
+ dialect: state.dialect,
1984
+ kind: state.kind ?? ("scalar" as Kind),
1985
+ dependencies: state.dependencies ?? {}
1986
+ } as Expression.State<Runtime, Db, Nullable, Dialect, Kind, Deps>
1502
1987
  expression[ExpressionAst.TypeId] = ast
1503
1988
  return expression
1504
1989
  }
@@ -1510,7 +1995,7 @@ export const makeExpression = <
1510
1995
  export const makePlan = <
1511
1996
  Selection,
1512
1997
  Required,
1513
- Available extends Record<string, Plan.Source>,
1998
+ Available extends Record<string, RowSet.AnySource>,
1514
1999
  Dialect extends string,
1515
2000
  Grouped extends string = never,
1516
2001
  ScopedNames extends string = Extract<keyof Available, string>,
@@ -1518,10 +2003,10 @@ export const makePlan = <
1518
2003
  Assumptions extends PredicateFormula = TrueAssumptions,
1519
2004
  Capabilities extends QueryCapability = "read",
1520
2005
  Statement extends QueryAst.QueryStatement = "select",
1521
- Target = never,
1522
- InsertState extends InsertSourceState = "ready"
2006
+ Target = any,
2007
+ InsertState extends InsertSourceState = InsertSourceState
1523
2008
  >(
1524
- state: Plan.State<Selection, Required, Available, Dialect>,
2009
+ state: RowSet.State<Selection, Required, Available, Dialect>,
1525
2010
  ast: QueryAst.Ast<Selection, Grouped, Statement>,
1526
2011
  _assumptions?: Assumptions,
1527
2012
  _capabilities?: Capabilities,
@@ -1530,13 +2015,20 @@ export const makePlan = <
1530
2015
  _insertState?: InsertState
1531
2016
  ): QueryPlan<Selection, Required, Available, Dialect, Grouped, ScopedNames, Outstanding, Assumptions, Capabilities, Statement, Target, InsertState> => {
1532
2017
  const plan = Object.create(PlanProto)
1533
- plan[Plan.TypeId] = state
2018
+ Object.defineProperty(plan, "pipe", {
2019
+ configurable: true,
2020
+ writable: true,
2021
+ value: function(this: unknown) {
2022
+ return pipeArguments(plan, arguments)
2023
+ }
2024
+ })
2025
+ plan[RowSet.TypeId] = state
1534
2026
  plan[QueryAst.TypeId] = ast
1535
2027
  plan[QueryTypeId] = {
1536
2028
  required: undefined as unknown as Outstanding,
1537
2029
  availableNames: undefined as unknown as ScopedNames,
1538
2030
  grouped: undefined as unknown as Grouped,
1539
- assumptions: undefined as unknown as Assumptions,
2031
+ assumptions: ((_assumptions ?? trueFormula()) as Assumptions),
1540
2032
  capabilities: undefined as unknown as Capabilities,
1541
2033
  statement: (_statement ?? ("select" as Statement)) as Statement,
1542
2034
  target: (_target ?? (undefined as unknown as Target)) as Target,