@math.gl/sql 5.0.0-beta.11 → 5.0.0-beta.12

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 (256) hide show
  1. package/dist/arrow/aggregates.js +1 -1
  2. package/dist/arrow/aggregates.js.map +1 -1
  3. package/dist/arrow/buffers.js.map +1 -1
  4. package/dist/arrow/cast.d.ts +1 -1
  5. package/dist/arrow/cast.js +1 -1
  6. package/dist/arrow/cast.js.map +1 -1
  7. package/dist/arrow/compiler.d.ts.map +1 -1
  8. package/dist/arrow/compiler.js +146 -29
  9. package/dist/arrow/compiler.js.map +1 -1
  10. package/dist/arrow/index.cjs +124 -23
  11. package/dist/arrow/index.cjs.map +1 -1
  12. package/dist/arrow/index.d.ts.map +1 -1
  13. package/dist/arrow/index.js.map +1 -1
  14. package/dist/arrow/list-values.d.ts.map +1 -1
  15. package/dist/arrow/list-values.js +27 -6
  16. package/dist/arrow/list-values.js.map +1 -1
  17. package/dist/arrow/predicate.d.ts.map +1 -1
  18. package/dist/arrow/predicate.js.map +1 -1
  19. package/dist/arrow/query-arrow-sql.d.ts +2 -2
  20. package/dist/arrow/query-arrow-sql.d.ts.map +1 -1
  21. package/dist/arrow/query-arrow-sql.js +40 -8
  22. package/dist/arrow/query-arrow-sql.js.map +1 -1
  23. package/dist/arrow/query-arrow-table.d.ts +1 -1
  24. package/dist/arrow/query-arrow-table.d.ts.map +1 -1
  25. package/dist/arrow/query-arrow-table.js +1 -1
  26. package/dist/arrow/query-arrow-table.js.map +1 -1
  27. package/dist/arrow/query-worker.d.ts +1 -1
  28. package/dist/arrow/query-worker.d.ts.map +1 -1
  29. package/dist/arrow/query-worker.js +1 -1
  30. package/dist/arrow/query-worker.js.map +1 -1
  31. package/dist/arrow/registry.d.ts.map +1 -1
  32. package/dist/arrow/registry.js +1 -0
  33. package/dist/arrow/registry.js.map +1 -1
  34. package/dist/arrow/relational-query.js +2 -2
  35. package/dist/arrow/relational-query.js.map +1 -1
  36. package/dist/arrow/temporal-cast.js.map +1 -1
  37. package/dist/arrow/types.d.ts.map +1 -1
  38. package/dist/arrow/unnest-arrow-column.d.ts +22 -0
  39. package/dist/arrow/unnest-arrow-column.d.ts.map +1 -0
  40. package/dist/arrow/unnest-arrow-column.js +112 -0
  41. package/dist/arrow/unnest-arrow-column.js.map +1 -0
  42. package/dist/arrow/worker.cjs +130 -29
  43. package/dist/arrow/worker.cjs.map +1 -1
  44. package/dist/arrow/worker.d.ts +1 -1
  45. package/dist/arrow/worker.d.ts.map +1 -1
  46. package/dist/arrow/worker.js +1 -1
  47. package/dist/arrow/worker.js.map +1 -1
  48. package/dist/{color → color-functions}/index.cjs +2 -2
  49. package/dist/{color → color-functions}/index.cjs.map +1 -1
  50. package/dist/color-functions/index.d.ts.map +1 -0
  51. package/dist/color-functions/index.js.map +1 -0
  52. package/dist/expressions/ast.js +3 -1
  53. package/dist/expressions/ast.js.map +1 -1
  54. package/dist/expressions/expression-eval.d.ts +10 -1
  55. package/dist/expressions/expression-eval.d.ts.map +1 -1
  56. package/dist/expressions/expression-eval.js.map +1 -1
  57. package/dist/expressions/index.cjs +1 -1
  58. package/dist/expressions/index.cjs.map +1 -1
  59. package/dist/index.cjs +2792 -2363
  60. package/dist/index.cjs.map +3 -3
  61. package/dist/index.d.ts +2 -0
  62. package/dist/index.d.ts.map +1 -1
  63. package/dist/index.js +1 -0
  64. package/dist/index.js.map +1 -1
  65. package/dist/{math → math-functions}/index.cjs +2 -2
  66. package/dist/{math → math-functions}/index.cjs.map +1 -1
  67. package/dist/math-functions/index.d.ts.map +1 -0
  68. package/dist/math-functions/index.js.map +1 -0
  69. package/dist/parser/bind-sql-predicate.d.ts.map +1 -0
  70. package/dist/parser/bind-sql-predicate.js.map +1 -0
  71. package/dist/{sql → parser}/index.cjs +348 -129
  72. package/dist/parser/index.cjs.map +6 -0
  73. package/dist/{sql → parser}/index.d.ts +2 -0
  74. package/dist/parser/index.d.ts.map +1 -0
  75. package/dist/{sql → parser}/index.js +1 -0
  76. package/dist/parser/index.js.map +1 -0
  77. package/dist/parser/parameter-snapshots.d.ts +21 -0
  78. package/dist/parser/parameter-snapshots.d.ts.map +1 -0
  79. package/dist/parser/parameter-snapshots.js +85 -0
  80. package/dist/parser/parameter-snapshots.js.map +1 -0
  81. package/dist/{sql → parser}/parse-sql-expression.d.ts +8 -2
  82. package/dist/parser/parse-sql-expression.d.ts.map +1 -0
  83. package/dist/{sql → parser}/parse-sql-expression.js +51 -5
  84. package/dist/parser/parse-sql-expression.js.map +1 -0
  85. package/dist/parser/parse-sql-predicate.d.ts.map +1 -0
  86. package/dist/parser/parse-sql-predicate.js.map +1 -0
  87. package/dist/{sql → parser}/parse-sql-query.d.ts +2 -1
  88. package/dist/parser/parse-sql-query.d.ts.map +1 -0
  89. package/dist/{sql → parser}/parse-sql-query.js +21 -6
  90. package/dist/parser/parse-sql-query.js.map +1 -0
  91. package/dist/{sql → parser}/parse-sql-select.d.ts +4 -2
  92. package/dist/parser/parse-sql-select.d.ts.map +1 -0
  93. package/dist/{sql → parser}/parse-sql-select.js +6 -3
  94. package/dist/parser/parse-sql-select.js.map +1 -0
  95. package/dist/{sql → parser}/parse-sql-statement.d.ts +9 -5
  96. package/dist/parser/parse-sql-statement.d.ts.map +1 -0
  97. package/dist/{sql → parser}/parse-sql-statement.js +39 -14
  98. package/dist/parser/parse-sql-statement.js.map +1 -0
  99. package/dist/parser/query-types.d.ts.map +1 -0
  100. package/dist/parser/query-types.js.map +1 -0
  101. package/dist/parser/sql-parameters.d.ts +29 -0
  102. package/dist/parser/sql-parameters.d.ts.map +1 -0
  103. package/dist/parser/sql-parameters.js +110 -0
  104. package/dist/parser/sql-parameters.js.map +1 -0
  105. package/dist/parser/sql-parse-error.d.ts.map +1 -0
  106. package/dist/parser/sql-parse-error.js.map +1 -0
  107. package/dist/parser/sql-predicate-schema.d.ts.map +1 -0
  108. package/dist/parser/sql-predicate-schema.js.map +1 -0
  109. package/dist/parser/sql-predicate-types.d.ts.map +1 -0
  110. package/dist/parser/sql-predicate-types.js.map +1 -0
  111. package/dist/parser/sql-predicate.d.ts.map +1 -0
  112. package/dist/parser/sql-predicate.js.map +1 -0
  113. package/dist/scales/arrow-domains.d.ts +8 -1
  114. package/dist/scales/arrow-domains.d.ts.map +1 -1
  115. package/dist/scales/arrow-domains.js +48 -6
  116. package/dist/scales/arrow-domains.js.map +1 -1
  117. package/dist/scales/arrow-scales.d.ts +28 -4
  118. package/dist/scales/arrow-scales.d.ts.map +1 -1
  119. package/dist/scales/arrow-scales.js +158 -12
  120. package/dist/scales/arrow-scales.js.map +1 -1
  121. package/dist/scales/compile-scale.d.ts +1 -6
  122. package/dist/scales/compile-scale.d.ts.map +1 -1
  123. package/dist/scales/compile-scale.js +1 -191
  124. package/dist/scales/compile-scale.js.map +1 -1
  125. package/dist/scales/conformance.cjs +180 -0
  126. package/dist/scales/conformance.cjs.map +6 -0
  127. package/dist/scales/conformance.d.ts +26 -0
  128. package/dist/scales/conformance.d.ts.map +1 -0
  129. package/dist/scales/conformance.js +164 -0
  130. package/dist/scales/conformance.js.map +1 -0
  131. package/dist/scales/hdr-colors.d.ts +1 -12
  132. package/dist/scales/hdr-colors.d.ts.map +1 -1
  133. package/dist/scales/hdr-colors.js +1 -111
  134. package/dist/scales/hdr-colors.js.map +1 -1
  135. package/dist/scales/index.cjs +3738 -618
  136. package/dist/scales/index.cjs.map +3 -3
  137. package/dist/scales/index.d.ts +2 -1
  138. package/dist/scales/index.d.ts.map +1 -1
  139. package/dist/scales/index.js +2 -1
  140. package/dist/scales/index.js.map +1 -1
  141. package/dist/scales/palettes.d.ts +1 -4
  142. package/dist/scales/palettes.d.ts.map +1 -1
  143. package/dist/scales/palettes.js +1 -81
  144. package/dist/scales/palettes.js.map +1 -1
  145. package/dist/scales/parse-sql-scale.d.ts +14 -1
  146. package/dist/scales/parse-sql-scale.d.ts.map +1 -1
  147. package/dist/scales/parse-sql-scale.js +110 -18
  148. package/dist/scales/parse-sql-scale.js.map +1 -1
  149. package/dist/scales/quantile-sketch.d.ts +1 -21
  150. package/dist/scales/quantile-sketch.d.ts.map +1 -1
  151. package/dist/scales/quantile-sketch.js +1 -104
  152. package/dist/scales/quantile-sketch.js.map +1 -1
  153. package/dist/scales/scale-types.d.ts +1 -91
  154. package/dist/scales/scale-types.d.ts.map +1 -1
  155. package/dist/scales/scale-types.js +1 -115
  156. package/dist/scales/scale-types.js.map +1 -1
  157. package/dist/scales/streaming-domains.d.ts.map +1 -1
  158. package/dist/scales/streaming-domains.js +8 -2
  159. package/dist/scales/streaming-domains.js.map +1 -1
  160. package/package.json +19 -19
  161. package/src/arrow/aggregates.ts +1 -1
  162. package/src/arrow/buffers.ts +1 -1
  163. package/src/arrow/cast.ts +3 -3
  164. package/src/arrow/compiler.ts +155 -36
  165. package/src/arrow/index.ts +1 -1
  166. package/src/arrow/list-values.ts +28 -7
  167. package/src/arrow/predicate.ts +1 -1
  168. package/src/arrow/query-arrow-sql.ts +38 -10
  169. package/src/arrow/query-arrow-table.ts +3 -3
  170. package/src/arrow/query-worker.ts +5 -1
  171. package/src/arrow/registry.ts +1 -0
  172. package/src/arrow/relational-query.ts +2 -2
  173. package/src/arrow/temporal-cast.ts +1 -1
  174. package/src/arrow/types.ts +1 -1
  175. package/src/arrow/unnest-arrow-column.ts +145 -0
  176. package/src/arrow/worker.ts +6 -2
  177. package/src/expressions/ast.ts +3 -1
  178. package/src/expressions/expression-eval.ts +10 -1
  179. package/src/index.ts +14 -0
  180. package/src/{math → math-functions}/index.ts +2 -2
  181. package/src/{sql → parser}/index.ts +15 -0
  182. package/src/parser/parameter-snapshots.ts +103 -0
  183. package/src/{sql → parser}/parse-sql-expression.ts +49 -6
  184. package/src/{sql → parser}/parse-sql-query.ts +24 -6
  185. package/src/{sql → parser}/parse-sql-select.ts +14 -8
  186. package/src/{sql → parser}/parse-sql-statement.ts +42 -24
  187. package/src/{sql → parser}/query-types.ts +1 -1
  188. package/src/parser/sql-parameters.ts +174 -0
  189. package/src/scales/arrow-domains.ts +66 -7
  190. package/src/scales/arrow-scales.ts +221 -14
  191. package/src/scales/compile-scale.ts +1 -213
  192. package/src/scales/conformance.ts +186 -0
  193. package/src/scales/hdr-colors.ts +1 -122
  194. package/src/scales/index.ts +3 -1
  195. package/src/scales/palettes.ts +1 -82
  196. package/src/scales/parse-sql-scale.ts +126 -21
  197. package/src/scales/quantile-sketch.ts +1 -102
  198. package/src/scales/scale-types.ts +1 -220
  199. package/src/scales/streaming-domains.ts +8 -2
  200. package/dist/color/index.d.ts.map +0 -1
  201. package/dist/color/index.js.map +0 -1
  202. package/dist/math/index.d.ts.map +0 -1
  203. package/dist/math/index.js.map +0 -1
  204. package/dist/scales/arrow-scales.cjs +0 -3837
  205. package/dist/scales/arrow-scales.cjs.map +0 -6
  206. package/dist/sql/bind-sql-predicate.d.ts.map +0 -1
  207. package/dist/sql/bind-sql-predicate.js.map +0 -1
  208. package/dist/sql/index.cjs.map +0 -6
  209. package/dist/sql/index.d.ts.map +0 -1
  210. package/dist/sql/index.js.map +0 -1
  211. package/dist/sql/parse-sql-expression.d.ts.map +0 -1
  212. package/dist/sql/parse-sql-expression.js.map +0 -1
  213. package/dist/sql/parse-sql-predicate.d.ts.map +0 -1
  214. package/dist/sql/parse-sql-predicate.js.map +0 -1
  215. package/dist/sql/parse-sql-query.d.ts.map +0 -1
  216. package/dist/sql/parse-sql-query.js.map +0 -1
  217. package/dist/sql/parse-sql-select.d.ts.map +0 -1
  218. package/dist/sql/parse-sql-select.js.map +0 -1
  219. package/dist/sql/parse-sql-statement.d.ts.map +0 -1
  220. package/dist/sql/parse-sql-statement.js.map +0 -1
  221. package/dist/sql/query-types.d.ts.map +0 -1
  222. package/dist/sql/query-types.js.map +0 -1
  223. package/dist/sql/sql-parse-error.d.ts.map +0 -1
  224. package/dist/sql/sql-parse-error.js.map +0 -1
  225. package/dist/sql/sql-predicate-schema.d.ts.map +0 -1
  226. package/dist/sql/sql-predicate-schema.js.map +0 -1
  227. package/dist/sql/sql-predicate-types.d.ts.map +0 -1
  228. package/dist/sql/sql-predicate-types.js.map +0 -1
  229. package/dist/sql/sql-predicate.d.ts.map +0 -1
  230. package/dist/sql/sql-predicate.js.map +0 -1
  231. package/src/expressions/vendor/jsep/README.md +0 -22
  232. /package/dist/{color → color-functions}/index.d.ts +0 -0
  233. /package/dist/{color → color-functions}/index.js +0 -0
  234. /package/dist/{math → math-functions}/index.d.ts +0 -0
  235. /package/dist/{math → math-functions}/index.js +0 -0
  236. /package/dist/{sql → parser}/bind-sql-predicate.d.ts +0 -0
  237. /package/dist/{sql → parser}/bind-sql-predicate.js +0 -0
  238. /package/dist/{sql → parser}/parse-sql-predicate.d.ts +0 -0
  239. /package/dist/{sql → parser}/parse-sql-predicate.js +0 -0
  240. /package/dist/{sql → parser}/query-types.d.ts +0 -0
  241. /package/dist/{sql → parser}/query-types.js +0 -0
  242. /package/dist/{sql → parser}/sql-parse-error.d.ts +0 -0
  243. /package/dist/{sql → parser}/sql-parse-error.js +0 -0
  244. /package/dist/{sql → parser}/sql-predicate-schema.d.ts +0 -0
  245. /package/dist/{sql → parser}/sql-predicate-schema.js +0 -0
  246. /package/dist/{sql → parser}/sql-predicate-types.d.ts +0 -0
  247. /package/dist/{sql → parser}/sql-predicate-types.js +0 -0
  248. /package/dist/{sql → parser}/sql-predicate.d.ts +0 -0
  249. /package/dist/{sql → parser}/sql-predicate.js +0 -0
  250. /package/src/{color → color-functions}/index.ts +0 -0
  251. /package/src/{sql → parser}/bind-sql-predicate.ts +0 -0
  252. /package/src/{sql → parser}/parse-sql-predicate.ts +0 -0
  253. /package/src/{sql → parser}/sql-parse-error.ts +0 -0
  254. /package/src/{sql → parser}/sql-predicate-schema.ts +0 -0
  255. /package/src/{sql → parser}/sql-predicate-types.ts +0 -0
  256. /package/src/{sql → parser}/sql-predicate.ts +0 -0
@@ -2,7 +2,8 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
  // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
4
 
5
- import type {Expression} from '../expressions/index';
5
+ import type {SQLParameterOptions} from './sql-parameters';
6
+ import type {Expression} from '../expressions';
6
7
  import {SQLExpressionReader, SQL_RESERVED_WORDS} from './parse-sql-expression';
7
8
  import {SQLQueryReader} from './parse-sql-select';
8
9
 
@@ -11,7 +12,9 @@ export type SQLTableBinding = Readonly<{name: string; alias?: string}>;
11
12
 
12
13
  /** A join whose condition is interpreted by the query planner. */
13
14
  export type SQLJoin = Readonly<{
14
- type: 'inner' | 'left' | 'semi' | 'anti';
15
+ type: 'inner' | 'left' | 'semi' | 'anti' | 'cross';
16
+ /** Experimental lateral collection expansion. */
17
+ unnest?: Readonly<{expression: Expression; columns: readonly string[]; ordinality: boolean}>;
15
18
  table: SQLTableBinding;
16
19
  on: Expression;
17
20
  }>;
@@ -37,10 +40,7 @@ export type SQLSelectStatement = Readonly<{
37
40
  }>;
38
41
 
39
42
  /** Options for interpreting named parameters in a relational SELECT. */
40
- export type SQLSelectStatementOptions = Readonly<{
41
- /** Supplies the AST for a named parameter such as :minimum. */
42
- parseParameter?: (name: string) => Expression;
43
- }>;
43
+ export type SQLSelectStatementOptions = SQLParameterOptions;
44
44
 
45
45
  /** Parses a SELECT with a required FROM, without assuming an execution engine. */
46
46
  export function parseSQLSelectStatement(
@@ -90,6 +90,30 @@ function readSelect(reader: RelationalQueryReader): SQLSelectStatement {
90
90
  const from = readTable(reader);
91
91
  const joins: SQLJoin[] = [];
92
92
  for (let type = readJoinType(reader); type; type = readJoinType(reader)) {
93
+ if (reader.takeKeyword('UNNEST')) {
94
+ reader.expectSymbol('(');
95
+ const expression = reader.selectionExpression();
96
+ reader.expectSymbol(')');
97
+ const ordinality = reader.takeKeyword('WITH');
98
+ if (ordinality) reader.expectKeyword('ORDINALITY');
99
+ reader.expectKeyword('AS');
100
+ const alias = reader.identifier();
101
+ reader.expectSymbol('(');
102
+ const columns = readList(reader, () => reader.identifier());
103
+ reader.expectSymbol(')');
104
+ if (type === 'left') {
105
+ reader.expectKeyword('ON');
106
+ reader.expectKeyword('TRUE');
107
+ } else if (type !== 'cross') throw reader.error('UNNEST requires CROSS JOIN or LEFT JOIN');
108
+ joins.push({
109
+ type,
110
+ table: {name: alias, alias},
111
+ on: {type: 'Literal', value: true},
112
+ unnest: {expression, columns, ordinality}
113
+ });
114
+ continue;
115
+ }
116
+ if (type === 'cross') throw reader.error('CROSS JOIN requires UNNEST');
93
117
  const table = readTable(reader);
94
118
  reader.expectKeyword('ON');
95
119
  joins.push({type, table, on: reader.selectionExpression()});
@@ -123,6 +147,10 @@ function readTable(reader: RelationalQueryReader): SQLTableBinding {
123
147
  }
124
148
 
125
149
  function readJoinType(reader: SQLQueryReader): SQLJoin['type'] | undefined {
150
+ if (reader.takeKeyword('CROSS')) {
151
+ reader.expectKeyword('JOIN');
152
+ return 'cross';
153
+ }
126
154
  if (reader.takeKeyword('JOIN')) return 'inner';
127
155
  let type: SQLJoin['type'];
128
156
  if (reader.takeKeyword('INNER')) type = 'inner';
@@ -153,11 +181,16 @@ function readList<T>(reader: SQLQueryReader, readItem: () => T): T[] {
153
181
  }
154
182
 
155
183
  class RelationalQueryReader extends SQLQueryReader {
184
+ /** Requires punctuation with a positioned diagnostic. */
185
+ expectSymbol(symbol: string): void {
186
+ if (!this.takeSymbol(symbol)) throw this.error(`Expected ${symbol}`);
187
+ }
188
+
156
189
  constructor(
157
190
  sql: string,
158
191
  private readonly options: SQLSelectStatementOptions
159
192
  ) {
160
- super(sql);
193
+ super(sql, options);
161
194
  }
162
195
 
163
196
  tableName(): string {
@@ -192,12 +225,8 @@ class RelationalQueryReader extends SQLQueryReader {
192
225
  }
193
226
 
194
227
  class RelationalExpressionReader extends SQLExpressionReader {
195
- constructor(
196
- source: string,
197
- position: number,
198
- private readonly options: SQLSelectStatementOptions
199
- ) {
200
- super(source, position);
228
+ constructor(source: string, position: number, options: SQLSelectStatementOptions) {
229
+ super(source, position, options);
201
230
  }
202
231
 
203
232
  override space(): void {
@@ -205,17 +234,6 @@ class RelationalExpressionReader extends SQLExpressionReader {
205
234
  super.space();
206
235
  }
207
236
 
208
- protected override extendedPrimary(): Expression | undefined {
209
- if (this.source[this.position] !== ':') return undefined;
210
- const parameter = /^:([A-Za-z_][A-Za-z0-9_]*)/.exec(this.source.slice(this.position));
211
- if (!parameter || !this.options.parseParameter) {
212
- throw this.error('SQL named parameters require a name and parseParameter callback');
213
- }
214
- this.position += parameter[0].length;
215
- this.token();
216
- return this.node(this.options.parseParameter(parameter[1]!));
217
- }
218
-
219
237
  /** Preserves dot access until the planner can resolve table aliases. */
220
238
  protected override memberAccess(object: Expression, name: string): Expression {
221
239
  const property = this.node({type: 'Identifier', name});
@@ -2,7 +2,7 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
  // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
4
 
5
- import type {Expression} from '../expressions/index';
5
+ import type {Expression} from '../expressions';
6
6
  import type {ColumnarPredicate, ColumnarPredicateProperty} from '../expressions/columnar-predicate';
7
7
 
8
8
  /** One source column selected for logical output, optionally under a new name. */
@@ -0,0 +1,174 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {
6
+ isSQLParameterSnapshot,
7
+ snapshotParameter,
8
+ type SQLParameterSnapshot
9
+ } from './parameter-snapshots';
10
+ import type {Expression} from '../expressions';
11
+ import {
12
+ isColumnarPredicateValue,
13
+ type ColumnarPredicateValue
14
+ } from '../expressions/columnar-predicate';
15
+
16
+ /** Numeric typed arrays accepted as array parameters (Uint8Array is binary unless tagged). */
17
+ export type SQLNumericArray =
18
+ | Float32Array
19
+ | Float64Array
20
+ | Int8Array
21
+ | Uint8Array
22
+ | Uint8ClampedArray
23
+ | Int16Array
24
+ | Uint16Array
25
+ | Int32Array
26
+ | Uint32Array;
27
+
28
+ /** Explicit interpretation of byte storage; numeric arrays may also use this form. */
29
+ export type SQLBinaryParameter =
30
+ | Readonly<{type: 'utf8' | 'binary'; value: Uint8Array}>
31
+ | Readonly<{type: 'array'; value: SQLNumericArray}>;
32
+
33
+ /** Bound SQL value, including flat lists and numeric tuples used by color palettes. */
34
+ export type SQLParameterValue =
35
+ | ColumnarPredicateValue
36
+ | SQLNumericArray
37
+ | SQLBinaryParameter
38
+ | null
39
+ | readonly number[]
40
+ | readonly string[]
41
+ | readonly (readonly number[] | SQLNumericArray)[];
42
+
43
+ /** Caller-owned values keyed by case-sensitive names without the leading colon. */
44
+ export type SQLParameters = Readonly<Record<string, SQLParameterValue>>;
45
+
46
+ /** Bind values directly, or retain the existing custom AST interpretation callback. */
47
+ export type SQLParameterOptions = Readonly<{
48
+ /** Values referenced by SQL placeholders such as `:minimum` or `:colors`. */
49
+ parameters?: SQLParameters | SQLParameterSnapshot;
50
+ /** Custom interpretation of a placeholder; mutually exclusive with parameters. */
51
+ parseParameter?: (name: string) => Expression;
52
+ }>;
53
+
54
+ /** Rejects ambiguous binding configuration even when a statement has no placeholders. */
55
+ export function validateSQLParameterOptions(options: SQLParameterOptions): void {
56
+ if (options.parameters !== undefined && options.parseParameter !== undefined) {
57
+ throw new Error('SQL parameters and parseParameter are mutually exclusive');
58
+ }
59
+ }
60
+
61
+ /** Resolves a named value into a copied literal AST without interpreting it as SQL. */
62
+ export function bindSQLParameter(name: string, options: SQLParameterOptions): Expression {
63
+ if (options.parseParameter) return options.parseParameter(name);
64
+ if (isSQLParameterSnapshot(options.parameters))
65
+ return snapshotParameter(options.parameters as SQLParameterSnapshot, name);
66
+ if (!Object.prototype.hasOwnProperty.call(options.parameters ?? {}, name)) {
67
+ throw new Error(`SQL parameter ":${name}" requires a value`);
68
+ }
69
+ const value = options.parameters![name];
70
+ if (isNumericArray(value) && !(value instanceof Uint8Array))
71
+ return typedArrayLiteral(value, name);
72
+ if (value && typeof value === 'object' && 'type' in value) {
73
+ if (value.type === 'array' && isNumericArray(value.value))
74
+ return typedArrayLiteral(value.value, name);
75
+ if ((value.type === 'utf8' || value.type === 'binary') && value.value instanceof Uint8Array) {
76
+ const data = new Uint8Array(value.value);
77
+ if (value.type === 'binary') return literal(data);
78
+ try {
79
+ // Retain the portable string value and its supplied physical representation.
80
+ // Scalar evaluators use value; Arrow comparisons consume utf8 directly.
81
+ return {
82
+ type: 'Literal',
83
+ value: new TextDecoder('utf-8', {fatal: true, ignoreBOM: true}).decode(data),
84
+ utf8: data
85
+ } as Expression;
86
+ } catch {
87
+ throw new Error(`SQL parameter ":${name}" requires valid UTF-8 bytes`);
88
+ }
89
+ }
90
+ throw new Error(`SQL parameter ":${name}" has an unsupported binary format`);
91
+ }
92
+ if (Array.isArray(value)) {
93
+ if (
94
+ value.length > 4096 ||
95
+ !(
96
+ Array.from(value).every(item => typeof item === 'number' && Number.isFinite(item)) ||
97
+ Array.from(value).every(item => typeof item === 'string') ||
98
+ Array.from(value).every(
99
+ item =>
100
+ (Array.isArray(item) || isNumericArray(item)) &&
101
+ item.length <= 4096 &&
102
+ Array.from(item).every(
103
+ component => typeof component === 'number' && Number.isFinite(component)
104
+ )
105
+ )
106
+ )
107
+ )
108
+ throw new Error(`SQL parameter ":${name}" has an unsupported array value`);
109
+ return arrayLiteral(value, name);
110
+ }
111
+ if (value !== null && !isColumnarPredicateValue(value)) {
112
+ throw new Error(`SQL parameter ":${name}" has an unsupported value`);
113
+ }
114
+ return literal(
115
+ value instanceof Date
116
+ ? new Date(value.getTime())
117
+ : value instanceof Uint8Array
118
+ ? new Uint8Array(value)
119
+ : value
120
+ );
121
+ }
122
+
123
+ /** Builds an independent array tree; array elements are never identifiers or executable text. */
124
+ function arrayLiteral(values: readonly unknown[], name: string): Expression {
125
+ return {
126
+ type: 'ArrayExpression',
127
+ elements: Array.from(values, value =>
128
+ Array.isArray(value)
129
+ ? arrayLiteral(value, name)
130
+ : isNumericArray(value)
131
+ ? typedArrayLiteral(value, name)
132
+ : literal(value)
133
+ )
134
+ } as Expression;
135
+ }
136
+
137
+ /** Creates a typed literal, including scalar values that cannot be represented in JSON. */
138
+ function literal(value: unknown): Expression {
139
+ if (value instanceof Uint8Array || value instanceof Date)
140
+ return {type: 'Literal', value} as Expression;
141
+ return {
142
+ type: 'Literal',
143
+ value,
144
+ raw: typeof value === 'bigint' ? String(value) : JSON.stringify(value)
145
+ } as Expression;
146
+ }
147
+
148
+ /** Recognizes supported numeric storage without treating DataView or bigint arrays as numbers. */
149
+ function isNumericArray(value: unknown): value is SQLNumericArray {
150
+ return (
151
+ value instanceof Float32Array ||
152
+ value instanceof Float64Array ||
153
+ value instanceof Int8Array ||
154
+ value instanceof Uint8Array ||
155
+ value instanceof Uint8ClampedArray ||
156
+ value instanceof Int16Array ||
157
+ value instanceof Uint16Array ||
158
+ value instanceof Int32Array ||
159
+ value instanceof Uint32Array
160
+ );
161
+ }
162
+
163
+ /** Snapshots typed input and supplies equivalent portable elements for non-Arrow evaluators. */
164
+ function typedArrayLiteral(value: SQLNumericArray, name: string): Expression {
165
+ if (value.length > 4096 || !value.every(Number.isFinite)) {
166
+ throw new Error(`SQL parameter ":${name}" has an unsupported numeric array`);
167
+ }
168
+ const typedValues = value instanceof Uint8Array ? new Uint8Array(value) : value.slice();
169
+ return {
170
+ type: 'ArrayExpression',
171
+ elements: Array.from(typedValues, item => literal(item)),
172
+ typedValues
173
+ } as Expression;
174
+ }
@@ -2,7 +2,10 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
  // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
4
 
5
- import type {Table} from 'apache-arrow';
5
+ import type {Table, Vector} from 'apache-arrow';
6
+ import {compileArrowExpression} from '../arrow/compiler';
7
+ import type {ArrowExpression, ArrowTableFunction} from '../arrow/types';
8
+ import type {Expression} from '../expressions';
6
9
  import type {ScaleDomain, ScaleValue} from './scale-types';
7
10
 
8
11
  type DomainStatistics = {
@@ -39,12 +42,14 @@ export function quantileSorted(sorted: readonly number[], probability: number):
39
42
  */
40
43
  export function resolveArrowDomains(
41
44
  table: Table,
42
- domains: readonly ScaleDomain[]
45
+ domains: readonly ScaleDomain[],
46
+ functions?: readonly ArrowTableFunction[]
43
47
  ): readonly (readonly ScaleValue[])[] {
44
48
  const columns = new Map<string, DomainStatistics>();
45
49
  const needsSamples = new Set<string>();
46
50
  const needsCategories = new Set<string>();
47
51
  for (const domain of domains) {
52
+ if (domain.type === 'expression-extent') continue;
48
53
  if (domain.type === 'percentile') needsSamples.add(domain.column);
49
54
  if (domain.type === 'categories') needsCategories.add(domain.column);
50
55
  if (domain.type !== 'fixed' && !table.getChild(domain.column)) {
@@ -52,7 +57,12 @@ export function resolveArrowDomains(
52
57
  }
53
58
  }
54
59
  for (const domain of domains) {
55
- if (domain.type === 'fixed' || columns.has(domain.column)) continue;
60
+ if (
61
+ domain.type === 'fixed' ||
62
+ domain.type === 'expression-extent' ||
63
+ columns.has(domain.column)
64
+ )
65
+ continue;
56
66
  const vector = table.getChild(domain.column)!;
57
67
  const state: DomainStatistics = {
58
68
  values: [],
@@ -82,6 +92,14 @@ export function resolveArrowDomains(
82
92
 
83
93
  return domains.map(domain => {
84
94
  if (domain.type === 'fixed') return [...domain.values];
95
+ if (domain.type === 'expression-extent') {
96
+ return resolveArrowExpressionStatistics(
97
+ table,
98
+ domain.expression as Expression,
99
+ undefined,
100
+ functions
101
+ ).domain;
102
+ }
85
103
  const data = columns.get(domain.column)!;
86
104
  if (domain.type === 'categories') {
87
105
  const values = [...data.categories];
@@ -107,25 +125,66 @@ export function resolveArrowDomains(
107
125
  });
108
126
  }
109
127
 
128
+ /** Resolves numeric statistics over an evaluated row expression. */
129
+ export function resolveArrowExpressionStatistics(
130
+ table: Table,
131
+ expression: Expression,
132
+ classes?: number,
133
+ functions?: readonly ArrowTableFunction[]
134
+ ): {domain: readonly number[]; quantileBreaks?: readonly number[]} {
135
+ const compiled = compileArrowExpression(expression as ArrowExpression, {
136
+ inputSchema: table.schema,
137
+ functions
138
+ });
139
+ const values = readNumericSamples(compiled.evaluateTable(table), 'Quantile expression');
140
+ if (!values.length) throw new Error('Empty numeric scale expression domain');
141
+ if (classes === undefined) {
142
+ let min = Infinity;
143
+ let max = -Infinity;
144
+ for (const value of values) {
145
+ min = Math.min(min, value);
146
+ max = Math.max(max, value);
147
+ }
148
+ return {domain: [min, max]};
149
+ }
150
+ values.sort((a, b) => a - b);
151
+ return {
152
+ domain: [values[0]!, values[values.length - 1]!],
153
+ quantileBreaks: computeQuantileBreaks(values, classes)
154
+ };
155
+ }
156
+
110
157
  /** Exact, deterministic quantile class breaks; duplicate values may produce empty classes. */
111
158
  export function resolveArrowQuantiles(
112
159
  table: Table,
113
160
  column: string,
114
161
  classes: number
115
162
  ): readonly number[] {
116
- if (!Number.isSafeInteger(classes) || classes < 2)
117
- throw new Error('Quantile classes must be >= 2');
118
163
  const vector = table.getChild(column);
119
164
  if (!vector) throw new Error(`Unknown quantile column: ${column}`);
165
+ const values = readNumericSamples(vector, `Quantile column ${column}`);
166
+ values.sort((a, b) => a - b);
167
+ return computeQuantileBreaks(values, classes);
168
+ }
169
+
170
+ /** Collects finite numbers and skips missing rows. */
171
+ function readNumericSamples(vector: Vector, label: string): number[] {
120
172
  const values: number[] = [];
121
173
  for (let row = 0; row < vector.length; row++) {
122
174
  const value = arrowScaleValue(vector.get(row));
123
175
  if (value === null || value === undefined) continue;
124
176
  if (typeof value !== 'number' || !Number.isFinite(value)) {
125
- throw new Error(`Quantile column ${column} must be finite numeric`);
177
+ throw new Error(`${label} must be finite numeric`);
126
178
  }
127
179
  values.push(value);
128
180
  }
129
- values.sort((a, b) => a - b);
181
+ return values;
182
+ }
183
+
184
+ /** Computes exact class cuts from sorted finite samples. */
185
+ function computeQuantileBreaks(values: number[], classes: number): readonly number[] {
186
+ if (!Number.isSafeInteger(classes) || classes < 2) {
187
+ throw new Error('Quantile classes must be >= 2');
188
+ }
130
189
  return Array.from({length: classes - 1}, (_, i) => quantileSorted(values, (i + 1) / classes));
131
190
  }