@math.gl/sql 0.0.0-stage → 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 (353) hide show
  1. package/LICENSE +249 -0
  2. package/README.md +26 -2
  3. package/THIRD-PARTY-NOTICES.md +5 -0
  4. package/dist/arrow/aggregates.d.ts +46 -0
  5. package/dist/arrow/aggregates.d.ts.map +1 -0
  6. package/dist/arrow/aggregates.js +289 -0
  7. package/dist/arrow/aggregates.js.map +1 -0
  8. package/dist/arrow/buffers.d.ts +30 -0
  9. package/dist/arrow/buffers.d.ts.map +1 -0
  10. package/dist/arrow/buffers.js +177 -0
  11. package/dist/arrow/buffers.js.map +1 -0
  12. package/dist/arrow/cast.d.ts +19 -0
  13. package/dist/arrow/cast.d.ts.map +1 -0
  14. package/dist/arrow/cast.js +138 -0
  15. package/dist/arrow/cast.js.map +1 -0
  16. package/dist/arrow/compiler.d.ts +10 -0
  17. package/dist/arrow/compiler.d.ts.map +1 -0
  18. package/dist/arrow/compiler.js +1538 -0
  19. package/dist/arrow/compiler.js.map +1 -0
  20. package/dist/arrow/float16.d.ts +7 -0
  21. package/dist/arrow/float16.d.ts.map +1 -0
  22. package/dist/arrow/float16.js +26 -0
  23. package/dist/arrow/float16.js.map +1 -0
  24. package/dist/arrow/index.cjs +3321 -0
  25. package/dist/arrow/index.cjs.map +6 -0
  26. package/dist/arrow/index.d.ts +5 -0
  27. package/dist/arrow/index.d.ts.map +1 -0
  28. package/dist/arrow/index.js +7 -0
  29. package/dist/arrow/index.js.map +1 -0
  30. package/dist/arrow/like.d.ts +3 -0
  31. package/dist/arrow/like.d.ts.map +1 -0
  32. package/dist/arrow/like.js +75 -0
  33. package/dist/arrow/like.js.map +1 -0
  34. package/dist/arrow/list-values.d.ts +14 -0
  35. package/dist/arrow/list-values.d.ts.map +1 -0
  36. package/dist/arrow/list-values.js +201 -0
  37. package/dist/arrow/list-values.js.map +1 -0
  38. package/dist/arrow/predicate.d.ts +7 -0
  39. package/dist/arrow/predicate.d.ts.map +1 -0
  40. package/dist/arrow/predicate.js +10 -0
  41. package/dist/arrow/predicate.js.map +1 -0
  42. package/dist/arrow/query-arrow-aggregate-snapshots.d.ts +24 -0
  43. package/dist/arrow/query-arrow-aggregate-snapshots.d.ts.map +1 -0
  44. package/dist/arrow/query-arrow-aggregate-snapshots.js +64 -0
  45. package/dist/arrow/query-arrow-aggregate-snapshots.js.map +1 -0
  46. package/dist/arrow/query-arrow-sql.d.ts +8 -0
  47. package/dist/arrow/query-arrow-sql.d.ts.map +1 -0
  48. package/dist/arrow/query-arrow-sql.js +223 -0
  49. package/dist/arrow/query-arrow-sql.js.map +1 -0
  50. package/dist/arrow/query-arrow-table.d.ts +36 -0
  51. package/dist/arrow/query-arrow-table.d.ts.map +1 -0
  52. package/dist/arrow/query-arrow-table.js +208 -0
  53. package/dist/arrow/query-arrow-table.js.map +1 -0
  54. package/dist/arrow/query-worker-entry.d.ts +2 -0
  55. package/dist/arrow/query-worker-entry.d.ts.map +1 -0
  56. package/dist/arrow/query-worker-entry.js +7 -0
  57. package/dist/arrow/query-worker-entry.js.map +1 -0
  58. package/dist/arrow/query-worker.d.ts +65 -0
  59. package/dist/arrow/query-worker.d.ts.map +1 -0
  60. package/dist/arrow/query-worker.js +135 -0
  61. package/dist/arrow/query-worker.js.map +1 -0
  62. package/dist/arrow/registry.d.ts +4 -0
  63. package/dist/arrow/registry.d.ts.map +1 -0
  64. package/dist/arrow/registry.js +66 -0
  65. package/dist/arrow/registry.js.map +1 -0
  66. package/dist/arrow/relational-query.d.ts +36 -0
  67. package/dist/arrow/relational-query.d.ts.map +1 -0
  68. package/dist/arrow/relational-query.js +174 -0
  69. package/dist/arrow/relational-query.js.map +1 -0
  70. package/dist/arrow/replace-arrow-columns.d.ts +8 -0
  71. package/dist/arrow/replace-arrow-columns.d.ts.map +1 -0
  72. package/dist/arrow/replace-arrow-columns.js +63 -0
  73. package/dist/arrow/replace-arrow-columns.js.map +1 -0
  74. package/dist/arrow/signature.d.ts +6 -0
  75. package/dist/arrow/signature.d.ts.map +1 -0
  76. package/dist/arrow/signature.js +51 -0
  77. package/dist/arrow/signature.js.map +1 -0
  78. package/dist/arrow/temporal-cast.d.ts +9 -0
  79. package/dist/arrow/temporal-cast.d.ts.map +1 -0
  80. package/dist/arrow/temporal-cast.js +60 -0
  81. package/dist/arrow/temporal-cast.js.map +1 -0
  82. package/dist/arrow/types.d.ts +62 -0
  83. package/dist/arrow/types.d.ts.map +1 -0
  84. package/dist/arrow/types.js +5 -0
  85. package/dist/arrow/types.js.map +1 -0
  86. package/dist/arrow/unnest-arrow-column.d.ts +22 -0
  87. package/dist/arrow/unnest-arrow-column.d.ts.map +1 -0
  88. package/dist/arrow/unnest-arrow-column.js +112 -0
  89. package/dist/arrow/unnest-arrow-column.js.map +1 -0
  90. package/dist/arrow/worker-entry.d.ts +2 -0
  91. package/dist/arrow/worker-entry.d.ts.map +1 -0
  92. package/dist/arrow/worker-entry.js +9 -0
  93. package/dist/arrow/worker-entry.js.map +1 -0
  94. package/dist/arrow/worker.cjs +4074 -0
  95. package/dist/arrow/worker.cjs.map +6 -0
  96. package/dist/arrow/worker.d.ts +58 -0
  97. package/dist/arrow/worker.d.ts.map +1 -0
  98. package/dist/arrow/worker.js +84 -0
  99. package/dist/arrow/worker.js.map +1 -0
  100. package/dist/color-functions/index.cjs +382 -0
  101. package/dist/color-functions/index.cjs.map +6 -0
  102. package/dist/color-functions/index.d.ts +26 -0
  103. package/dist/color-functions/index.d.ts.map +1 -0
  104. package/dist/color-functions/index.js +306 -0
  105. package/dist/color-functions/index.js.map +1 -0
  106. package/dist/diagnostic-log.d.ts +8 -0
  107. package/dist/diagnostic-log.d.ts.map +1 -0
  108. package/dist/diagnostic-log.js +15 -0
  109. package/dist/diagnostic-log.js.map +1 -0
  110. package/dist/expressions/ast.d.ts +12 -0
  111. package/dist/expressions/ast.d.ts.map +1 -0
  112. package/dist/expressions/ast.js +114 -0
  113. package/dist/expressions/ast.js.map +1 -0
  114. package/dist/expressions/columnar-predicate.d.ts +56 -0
  115. package/dist/expressions/columnar-predicate.d.ts.map +1 -0
  116. package/dist/expressions/columnar-predicate.js +176 -0
  117. package/dist/expressions/columnar-predicate.js.map +1 -0
  118. package/dist/expressions/evaluation-error.d.ts +14 -0
  119. package/dist/expressions/evaluation-error.d.ts.map +1 -0
  120. package/dist/expressions/evaluation-error.js +26 -0
  121. package/dist/expressions/evaluation-error.js.map +1 -0
  122. package/dist/expressions/expression-eval.d.ts +105 -0
  123. package/dist/expressions/expression-eval.d.ts.map +1 -0
  124. package/dist/expressions/expression-eval.js +330 -0
  125. package/dist/expressions/expression-eval.js.map +1 -0
  126. package/dist/expressions/function-libraries.d.ts +63 -0
  127. package/dist/expressions/function-libraries.d.ts.map +1 -0
  128. package/dist/expressions/function-libraries.js +69 -0
  129. package/dist/expressions/function-libraries.js.map +1 -0
  130. package/dist/expressions/function-registry.d.ts +93 -0
  131. package/dist/expressions/function-registry.d.ts.map +1 -0
  132. package/dist/expressions/function-registry.js +139 -0
  133. package/dist/expressions/function-registry.js.map +1 -0
  134. package/dist/expressions/get.d.ts +9 -0
  135. package/dist/expressions/get.d.ts.map +1 -0
  136. package/dist/expressions/get.js +32 -0
  137. package/dist/expressions/get.js.map +1 -0
  138. package/dist/expressions/index.cjs +1888 -0
  139. package/dist/expressions/index.cjs.map +6 -0
  140. package/dist/expressions/index.d.ts +13 -0
  141. package/dist/expressions/index.d.ts.map +1 -0
  142. package/dist/expressions/index.js +14 -0
  143. package/dist/expressions/index.js.map +1 -0
  144. package/dist/expressions/numeric-functions.d.ts +277 -0
  145. package/dist/expressions/numeric-functions.d.ts.map +1 -0
  146. package/dist/expressions/numeric-functions.js +52 -0
  147. package/dist/expressions/numeric-functions.js.map +1 -0
  148. package/dist/expressions/parse-expression-string.d.ts +21 -0
  149. package/dist/expressions/parse-expression-string.d.ts.map +1 -0
  150. package/dist/expressions/parse-expression-string.js +61 -0
  151. package/dist/expressions/parse-expression-string.js.map +1 -0
  152. package/dist/expressions/predicate-expression.d.ts +7 -0
  153. package/dist/expressions/predicate-expression.d.ts.map +1 -0
  154. package/dist/expressions/predicate-expression.js +112 -0
  155. package/dist/expressions/predicate-expression.js.map +1 -0
  156. package/dist/expressions/scalar-type.d.ts +6 -0
  157. package/dist/expressions/scalar-type.d.ts.map +1 -0
  158. package/dist/expressions/scalar-type.js +23 -0
  159. package/dist/expressions/scalar-type.js.map +1 -0
  160. package/dist/expressions/vendor/jsep/runtime.d.ts +3 -0
  161. package/dist/expressions/vendor/jsep/runtime.d.ts.map +1 -0
  162. package/dist/expressions/vendor/jsep/runtime.js +972 -0
  163. package/dist/expressions/vendor/jsep/runtime.js.map +1 -0
  164. package/dist/expressions/vendor/jsep/types.d.ts +148 -0
  165. package/dist/expressions/vendor/jsep/types.d.ts.map +1 -0
  166. package/dist/expressions/vendor/jsep/types.js +6 -0
  167. package/dist/expressions/vendor/jsep/types.js.map +1 -0
  168. package/dist/index.cjs +5294 -0
  169. package/dist/index.cjs.map +6 -0
  170. package/dist/index.d.ts +11 -0
  171. package/dist/index.d.ts.map +1 -0
  172. package/dist/index.js +11 -0
  173. package/dist/index.js.map +1 -0
  174. package/dist/math-functions/index.cjs +444 -0
  175. package/dist/math-functions/index.cjs.map +6 -0
  176. package/dist/math-functions/index.d.ts +44 -0
  177. package/dist/math-functions/index.d.ts.map +1 -0
  178. package/dist/math-functions/index.js +182 -0
  179. package/dist/math-functions/index.js.map +1 -0
  180. package/dist/parser/bind-sql-predicate.d.ts +4 -0
  181. package/dist/parser/bind-sql-predicate.d.ts.map +1 -0
  182. package/dist/parser/bind-sql-predicate.js +11 -0
  183. package/dist/parser/bind-sql-predicate.js.map +1 -0
  184. package/dist/parser/index.cjs +1807 -0
  185. package/dist/parser/index.cjs.map +6 -0
  186. package/dist/parser/index.d.ts +12 -0
  187. package/dist/parser/index.d.ts.map +1 -0
  188. package/dist/parser/index.js +11 -0
  189. package/dist/parser/index.js.map +1 -0
  190. package/dist/parser/parameter-snapshots.d.ts +21 -0
  191. package/dist/parser/parameter-snapshots.d.ts.map +1 -0
  192. package/dist/parser/parameter-snapshots.js +85 -0
  193. package/dist/parser/parameter-snapshots.js.map +1 -0
  194. package/dist/parser/parse-sql-expression.d.ts +50 -0
  195. package/dist/parser/parse-sql-expression.d.ts.map +1 -0
  196. package/dist/parser/parse-sql-expression.js +501 -0
  197. package/dist/parser/parse-sql-expression.js.map +1 -0
  198. package/dist/parser/parse-sql-predicate.d.ts +13 -0
  199. package/dist/parser/parse-sql-predicate.d.ts.map +1 -0
  200. package/dist/parser/parse-sql-predicate.js +365 -0
  201. package/dist/parser/parse-sql-predicate.js.map +1 -0
  202. package/dist/parser/parse-sql-query.d.ts +9 -0
  203. package/dist/parser/parse-sql-query.d.ts.map +1 -0
  204. package/dist/parser/parse-sql-query.js +81 -0
  205. package/dist/parser/parse-sql-query.js.map +1 -0
  206. package/dist/parser/parse-sql-select.d.ts +57 -0
  207. package/dist/parser/parse-sql-select.d.ts.map +1 -0
  208. package/dist/parser/parse-sql-select.js +247 -0
  209. package/dist/parser/parse-sql-select.js.map +1 -0
  210. package/dist/parser/parse-sql-statement.d.ts +54 -0
  211. package/dist/parser/parse-sql-statement.d.ts.map +1 -0
  212. package/dist/parser/parse-sql-statement.js +207 -0
  213. package/dist/parser/parse-sql-statement.js.map +1 -0
  214. package/dist/parser/query-types.d.ts +56 -0
  215. package/dist/parser/query-types.d.ts.map +1 -0
  216. package/dist/parser/query-types.js +5 -0
  217. package/dist/parser/query-types.js.map +1 -0
  218. package/dist/parser/sql-parameters.d.ts +29 -0
  219. package/dist/parser/sql-parameters.d.ts.map +1 -0
  220. package/dist/parser/sql-parameters.js +110 -0
  221. package/dist/parser/sql-parameters.js.map +1 -0
  222. package/dist/parser/sql-parse-error.d.ts +13 -0
  223. package/dist/parser/sql-parse-error.d.ts.map +1 -0
  224. package/dist/parser/sql-parse-error.js +20 -0
  225. package/dist/parser/sql-parse-error.js.map +1 -0
  226. package/dist/parser/sql-predicate-schema.d.ts +164 -0
  227. package/dist/parser/sql-predicate-schema.d.ts.map +1 -0
  228. package/dist/parser/sql-predicate-schema.js +249 -0
  229. package/dist/parser/sql-predicate-schema.js.map +1 -0
  230. package/dist/parser/sql-predicate-types.d.ts +48 -0
  231. package/dist/parser/sql-predicate-types.d.ts.map +1 -0
  232. package/dist/parser/sql-predicate-types.js +9 -0
  233. package/dist/parser/sql-predicate-types.js.map +1 -0
  234. package/dist/parser/sql-predicate.d.ts +6 -0
  235. package/dist/parser/sql-predicate.d.ts.map +1 -0
  236. package/dist/parser/sql-predicate.js +8 -0
  237. package/dist/parser/sql-predicate.js.map +1 -0
  238. package/dist/scales/arrow-domains.d.ts +22 -0
  239. package/dist/scales/arrow-domains.d.ts.map +1 -0
  240. package/dist/scales/arrow-domains.js +166 -0
  241. package/dist/scales/arrow-domains.js.map +1 -0
  242. package/dist/scales/arrow-scales.d.ts +44 -0
  243. package/dist/scales/arrow-scales.d.ts.map +1 -0
  244. package/dist/scales/arrow-scales.js +255 -0
  245. package/dist/scales/arrow-scales.js.map +1 -0
  246. package/dist/scales/compile-scale.d.ts +2 -0
  247. package/dist/scales/compile-scale.d.ts.map +1 -0
  248. package/dist/scales/compile-scale.js +5 -0
  249. package/dist/scales/compile-scale.js.map +1 -0
  250. package/dist/scales/conformance.cjs +180 -0
  251. package/dist/scales/conformance.cjs.map +6 -0
  252. package/dist/scales/conformance.d.ts +26 -0
  253. package/dist/scales/conformance.d.ts.map +1 -0
  254. package/dist/scales/conformance.js +164 -0
  255. package/dist/scales/conformance.js.map +1 -0
  256. package/dist/scales/hdr-colors.d.ts +2 -0
  257. package/dist/scales/hdr-colors.d.ts.map +1 -0
  258. package/dist/scales/hdr-colors.js +5 -0
  259. package/dist/scales/hdr-colors.js.map +1 -0
  260. package/dist/scales/index.cjs +4334 -0
  261. package/dist/scales/index.cjs.map +6 -0
  262. package/dist/scales/index.d.ts +10 -0
  263. package/dist/scales/index.d.ts.map +1 -0
  264. package/dist/scales/index.js +11 -0
  265. package/dist/scales/index.js.map +1 -0
  266. package/dist/scales/palettes.d.ts +2 -0
  267. package/dist/scales/palettes.d.ts.map +1 -0
  268. package/dist/scales/palettes.js +5 -0
  269. package/dist/scales/palettes.js.map +1 -0
  270. package/dist/scales/parse-sql-scale.d.ts +27 -0
  271. package/dist/scales/parse-sql-scale.d.ts.map +1 -0
  272. package/dist/scales/parse-sql-scale.js +257 -0
  273. package/dist/scales/parse-sql-scale.js.map +1 -0
  274. package/dist/scales/quantile-sketch.d.ts +2 -0
  275. package/dist/scales/quantile-sketch.d.ts.map +1 -0
  276. package/dist/scales/quantile-sketch.js +5 -0
  277. package/dist/scales/quantile-sketch.js.map +1 -0
  278. package/dist/scales/scale-types.d.ts +2 -0
  279. package/dist/scales/scale-types.d.ts.map +1 -0
  280. package/dist/scales/scale-types.js +5 -0
  281. package/dist/scales/scale-types.js.map +1 -0
  282. package/dist/scales/streaming-domains.d.ts +18 -0
  283. package/dist/scales/streaming-domains.d.ts.map +1 -0
  284. package/dist/scales/streaming-domains.js +115 -0
  285. package/dist/scales/streaming-domains.js.map +1 -0
  286. package/package.json +92 -4
  287. package/src/arrow/aggregates.ts +386 -0
  288. package/src/arrow/buffers.ts +177 -0
  289. package/src/arrow/cast.ts +160 -0
  290. package/src/arrow/compiler.ts +1778 -0
  291. package/src/arrow/float16.ts +25 -0
  292. package/src/arrow/index.ts +22 -0
  293. package/src/arrow/like.ts +72 -0
  294. package/src/arrow/list-values.ts +221 -0
  295. package/src/arrow/predicate.ts +19 -0
  296. package/src/arrow/query-arrow-aggregate-snapshots.ts +107 -0
  297. package/src/arrow/query-arrow-sql.ts +255 -0
  298. package/src/arrow/query-arrow-table.ts +298 -0
  299. package/src/arrow/query-worker-entry.ts +8 -0
  300. package/src/arrow/query-worker.ts +194 -0
  301. package/src/arrow/registry.ts +87 -0
  302. package/src/arrow/relational-query.ts +247 -0
  303. package/src/arrow/replace-arrow-columns.ts +71 -0
  304. package/src/arrow/signature.ts +50 -0
  305. package/src/arrow/temporal-cast.ts +66 -0
  306. package/src/arrow/types.ts +76 -0
  307. package/src/arrow/unnest-arrow-column.ts +145 -0
  308. package/src/arrow/worker-entry.ts +10 -0
  309. package/src/arrow/worker.ts +143 -0
  310. package/src/color-functions/index.ts +405 -0
  311. package/src/diagnostic-log.ts +20 -0
  312. package/src/expressions/ast.ts +143 -0
  313. package/src/expressions/columnar-predicate.ts +293 -0
  314. package/src/expressions/evaluation-error.ts +29 -0
  315. package/src/expressions/expression-eval.ts +489 -0
  316. package/src/expressions/function-libraries.ts +126 -0
  317. package/src/expressions/function-registry.ts +171 -0
  318. package/src/expressions/get.ts +37 -0
  319. package/src/expressions/index.ts +40 -0
  320. package/src/expressions/numeric-functions.ts +99 -0
  321. package/src/expressions/parse-expression-string.ts +80 -0
  322. package/src/expressions/predicate-expression.ts +128 -0
  323. package/src/expressions/scalar-type.ts +39 -0
  324. package/src/expressions/vendor/jsep/LICENSE.txt +23 -0
  325. package/src/expressions/vendor/jsep/runtime.ts +949 -0
  326. package/src/expressions/vendor/jsep/types.ts +191 -0
  327. package/src/index.ts +54 -0
  328. package/src/math-functions/index.ts +235 -0
  329. package/src/parser/bind-sql-predicate.ts +21 -0
  330. package/src/parser/index.ts +43 -0
  331. package/src/parser/parameter-snapshots.ts +103 -0
  332. package/src/parser/parse-sql-expression.ts +500 -0
  333. package/src/parser/parse-sql-predicate.ts +454 -0
  334. package/src/parser/parse-sql-query.ts +90 -0
  335. package/src/parser/parse-sql-select.ts +272 -0
  336. package/src/parser/parse-sql-statement.ts +260 -0
  337. package/src/parser/query-types.ts +71 -0
  338. package/src/parser/sql-parameters.ts +174 -0
  339. package/src/parser/sql-parse-error.ts +33 -0
  340. package/src/parser/sql-predicate-schema.ts +279 -0
  341. package/src/parser/sql-predicate-types.ts +91 -0
  342. package/src/parser/sql-predicate.ts +28 -0
  343. package/src/scales/arrow-domains.ts +190 -0
  344. package/src/scales/arrow-scales.ts +363 -0
  345. package/src/scales/compile-scale.ts +5 -0
  346. package/src/scales/conformance.ts +186 -0
  347. package/src/scales/hdr-colors.ts +5 -0
  348. package/src/scales/index.ts +37 -0
  349. package/src/scales/palettes.ts +5 -0
  350. package/src/scales/parse-sql-scale.ts +300 -0
  351. package/src/scales/quantile-sketch.ts +5 -0
  352. package/src/scales/scale-types.ts +5 -0
  353. package/src/scales/streaming-domains.ts +139 -0
@@ -0,0 +1,190 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
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';
9
+ import type {ScaleDomain, ScaleValue} from './scale-types';
10
+
11
+ type DomainStatistics = {
12
+ readonly values: number[];
13
+ readonly categories: Set<ScaleValue>;
14
+ min: number;
15
+ max: number;
16
+ };
17
+
18
+ /** Converts 64-bit Arrow integers only when the scale can represent them exactly. */
19
+ export function arrowScaleValue(value: unknown): unknown {
20
+ if (typeof value !== 'bigint') return value;
21
+ const numeric = Number(value);
22
+ if (!Number.isSafeInteger(numeric))
23
+ throw new RangeError('Scale integer exceeds the safe numeric range');
24
+ return numeric;
25
+ }
26
+
27
+ /** Exact type-7 interpolated quantile; caller supplies sorted finite samples. */
28
+ export function quantileSorted(sorted: readonly number[], probability: number): number {
29
+ if (!sorted.length || !Number.isFinite(probability) || probability < 0 || probability > 1) {
30
+ throw new Error('Quantile requires nonempty finite samples and a probability in [0, 1]');
31
+ }
32
+ const index = (sorted.length - 1) * probability;
33
+ const lower = Math.floor(index);
34
+ const fraction = index - lower;
35
+ return sorted[lower]! + fraction * (sorted[Math.ceil(index)]! - sorted[lower]!);
36
+ }
37
+
38
+ /**
39
+ * Resolve multiple data-dependent domains in one pass per referenced Arrow column.
40
+ * Extents use O(1) state; exact percentile domains retain samples to sort.
41
+ * Callers needing bounded approximate quantiles should supply a future sketch backend.
42
+ */
43
+ export function resolveArrowDomains(
44
+ table: Table,
45
+ domains: readonly ScaleDomain[],
46
+ functions?: readonly ArrowTableFunction[]
47
+ ): readonly (readonly ScaleValue[])[] {
48
+ const columns = new Map<string, DomainStatistics>();
49
+ const needsSamples = new Set<string>();
50
+ const needsCategories = new Set<string>();
51
+ for (const domain of domains) {
52
+ if (domain.type === 'expression-extent') continue;
53
+ if (domain.type === 'percentile') needsSamples.add(domain.column);
54
+ if (domain.type === 'categories') needsCategories.add(domain.column);
55
+ if (domain.type !== 'fixed' && !table.getChild(domain.column)) {
56
+ throw new Error(`Unknown scale domain column: ${domain.column}`);
57
+ }
58
+ }
59
+ for (const domain of domains) {
60
+ if (
61
+ domain.type === 'fixed' ||
62
+ domain.type === 'expression-extent' ||
63
+ columns.has(domain.column)
64
+ )
65
+ continue;
66
+ const vector = table.getChild(domain.column)!;
67
+ const state: DomainStatistics = {
68
+ values: [],
69
+ categories: new Set(),
70
+ min: Infinity,
71
+ max: -Infinity
72
+ };
73
+ const samples = needsSamples.has(domain.column);
74
+ for (let row = 0; row < vector.length; row++) {
75
+ const value = arrowScaleValue(vector.get(row));
76
+ if (value === null || value === undefined) continue;
77
+ if (typeof value === 'string') {
78
+ if (needsCategories.has(domain.column)) state.categories.add(value);
79
+ continue;
80
+ }
81
+ if (typeof value !== 'number' || !Number.isFinite(value)) {
82
+ throw new Error(`Unsupported scale domain value in ${domain.column} at row ${row}`);
83
+ }
84
+ if (needsCategories.has(domain.column)) state.categories.add(value);
85
+ if (value < state.min) state.min = value;
86
+ if (value > state.max) state.max = value;
87
+ if (samples) state.values.push(value);
88
+ }
89
+ if (samples) state.values.sort((a, b) => a - b);
90
+ columns.set(domain.column, state);
91
+ }
92
+
93
+ return domains.map(domain => {
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
+ }
103
+ const data = columns.get(domain.column)!;
104
+ if (domain.type === 'categories') {
105
+ const values = [...data.categories];
106
+ if (domain.order !== 'first-seen')
107
+ values.sort((a, b) =>
108
+ typeof a === 'number' && typeof b === 'number' ? a - b : a < b ? -1 : a > b ? 1 : 0
109
+ );
110
+ if (!values.length) throw new Error(`Empty categorical scale domain: ${domain.column}`);
111
+ return values;
112
+ }
113
+ if (!Number.isFinite(data.min) || !Number.isFinite(data.max)) {
114
+ throw new Error(`Empty numeric scale domain: ${domain.column}`);
115
+ }
116
+ if (domain.type === 'percentile') {
117
+ return [quantileSorted(data.values, domain.lower), quantileSorted(data.values, domain.upper)];
118
+ }
119
+ if (domain.type === 'symmetric') {
120
+ const radius = Math.max(Math.abs(data.min - domain.pivot), Math.abs(data.max - domain.pivot));
121
+ return [domain.pivot - radius, domain.pivot + radius];
122
+ }
123
+ if (domain.includeZero) return [Math.min(0, data.min), Math.max(0, data.max)];
124
+ return [data.min, data.max];
125
+ });
126
+ }
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
+
157
+ /** Exact, deterministic quantile class breaks; duplicate values may produce empty classes. */
158
+ export function resolveArrowQuantiles(
159
+ table: Table,
160
+ column: string,
161
+ classes: number
162
+ ): readonly number[] {
163
+ const vector = table.getChild(column);
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[] {
172
+ const values: number[] = [];
173
+ for (let row = 0; row < vector.length; row++) {
174
+ const value = arrowScaleValue(vector.get(row));
175
+ if (value === null || value === undefined) continue;
176
+ if (typeof value !== 'number' || !Number.isFinite(value)) {
177
+ throw new Error(`${label} must be finite numeric`);
178
+ }
179
+ values.push(value);
180
+ }
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
+ }
189
+ return Array.from({length: classes - 1}, (_, i) => quantileSorted(values, (i + 1) / classes));
190
+ }
@@ -0,0 +1,363 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {
6
+ Field,
7
+ FixedSizeList,
8
+ Float16,
9
+ Float32,
10
+ Float64,
11
+ Uint8,
12
+ Uint16,
13
+ vectorFromArray,
14
+ type RecordBatch,
15
+ type Schema,
16
+ type Table,
17
+ type Vector
18
+ } from 'apache-arrow';
19
+ import {compileArrowExpression} from '../arrow/compiler';
20
+ import {nullTupleVector} from '../arrow/list-values';
21
+ import type {ArrowExpression, ArrowTableFunction} from '../arrow/types';
22
+ import {compileResolvedScale} from './compile-scale';
23
+ import {
24
+ arrowScaleValue,
25
+ resolveArrowDomains,
26
+ resolveArrowExpressionStatistics,
27
+ resolveArrowQuantiles
28
+ } from './arrow-domains';
29
+ import {parseSQLScaleAST, type ParsedSQLScale} from './parse-sql-scale';
30
+ import {parseSQLExpression} from '../parser/parse-sql-expression';
31
+ import type {Expression} from '../expressions';
32
+ import type {CompiledArrowExpression} from '../arrow/types';
33
+ import type {ResolvedScale, ScaleColor, ScaleSpec, ScaleValue} from './scale-types';
34
+
35
+ export type CompiledArrowScale = Readonly<{
36
+ /** Authoritative sampler and resolved legend metadata. */
37
+ scale: ResolvedScale;
38
+ /** Evaluates the same scale against the parsed value expression, preserving row count. */
39
+ evaluate(table: Table): Vector;
40
+ evaluateBatch(batch: RecordBatch): Vector;
41
+ }>;
42
+
43
+ function asColor(value: number | ScaleColor | null): ScaleColor | null {
44
+ if (value === null) return null;
45
+ if (typeof value === 'number') throw new Error('Expected a color-valued scale');
46
+ return value;
47
+ }
48
+
49
+ function toVector(rows: (number | ScaleColor | null)[], spec: ScaleSpec): Vector {
50
+ const numeric = spec.range.type === 'numeric';
51
+ if (numeric) {
52
+ return vectorFromArray(rows as (number | null)[], new Float64());
53
+ }
54
+ const format = spec.encoding?.format ?? 'rgba8unorm';
55
+ const type =
56
+ format === 'rgba8unorm'
57
+ ? new Uint8()
58
+ : format === 'rgba16unorm'
59
+ ? new Uint16()
60
+ : format === 'rgba16float'
61
+ ? new Float16()
62
+ : new Float32();
63
+ const factor = format === 'rgba8unorm' ? 255 : format === 'rgba16unorm' ? 65535 : undefined;
64
+ const vector = nullTupleVector(new FixedSizeList(4, new Field('item', type, false)), rows.length);
65
+ const channels = vector.getChildAt(0)!;
66
+ for (let row = 0; row < rows.length; row++) {
67
+ const color = asColor(rows[row]!);
68
+ if (!color) continue;
69
+ for (let component = 0; component < 4; component++) {
70
+ const channel = color[component]!;
71
+ if (
72
+ !Number.isFinite(channel) ||
73
+ (format === 'rgba16float' && Math.abs(channel) >= 65520) ||
74
+ (format === 'rgba32float' && !Number.isFinite(Math.fround(channel)))
75
+ )
76
+ throw new Error('Scale color cannot be represented in the requested format');
77
+ channels.set(
78
+ row * 4 + component,
79
+ factor === undefined ? channel : Math.round(Math.max(0, Math.min(1, channel)) * factor)
80
+ );
81
+ }
82
+ vector.data[0]!.setValid(row, true);
83
+ }
84
+ return vector;
85
+ }
86
+
87
+ /** Determines the number of classes declared by the range. */
88
+ function getClassCount(spec: ScaleSpec): number | undefined {
89
+ if (spec.range.type === 'palette') return spec.range.count;
90
+ return spec.type === 'quantile' && spec.range.type === 'colors'
91
+ ? spec.range.values.length
92
+ : undefined;
93
+ }
94
+
95
+ /** Compile a shared domain + range and bind its per-row Arrow expression once. */
96
+ export function compileArrowScale(
97
+ table: Table,
98
+ parsed: ParsedSQLScale,
99
+ resolvedDomain?: readonly ScaleValue[],
100
+ functions?: readonly ArrowTableFunction[]
101
+ ): CompiledArrowScale {
102
+ /** Class count used by the palette for quantile classification. */
103
+ const classCount = getClassCount(parsed.scale);
104
+ if (parsed.scale.type === 'quantile' && (!classCount || parsed.scale.domain.type === 'fixed')) {
105
+ throw new Error('Quantile scale requires a class count and a data-derived domain');
106
+ }
107
+ if (parsed.scale.domain.type === 'expression-extent') {
108
+ const resolution = resolveArrowExpressionStatistics(
109
+ table,
110
+ parsed.scale.domain.expression as Expression,
111
+ parsed.scale.type === 'quantile' ? classCount : undefined,
112
+ functions
113
+ );
114
+ return bindArrowScale(
115
+ table.schema,
116
+ parsed,
117
+ {...resolution, domain: resolvedDomain ?? resolution.domain},
118
+ functions
119
+ );
120
+ }
121
+ /** Resolved inputs shared with the schema-only binder. */
122
+ const resolution: ArrowScaleResolution = {
123
+ domain: resolvedDomain ?? resolveArrowDomains(table, [parsed.scale.domain])[0]!,
124
+ ...(parsed.scale.type === 'quantile' && parsed.scale.domain.type !== 'fixed'
125
+ ? {quantileBreaks: resolveArrowQuantiles(table, parsed.scale.domain.column, classCount!)}
126
+ : {})
127
+ };
128
+ return bindArrowScale(table.schema, parsed, resolution, functions);
129
+ }
130
+
131
+ /** Statistics needed to bind a scale without retaining its source table. */
132
+ export type ArrowScaleResolution = Readonly<{
133
+ /** Resolved extent, categories, or explicit domain stops. */
134
+ domain: readonly ScaleValue[];
135
+ /** Required for quantile classification. Supply one break per class boundary. */
136
+ quantileBreaks?: readonly number[];
137
+ }>;
138
+
139
+ /** Binds a resolved scale to an Arrow schema without reading any rows. */
140
+ export function bindArrowScale(
141
+ inputSchema: Schema,
142
+ parsed: ParsedSQLScale,
143
+ {domain, quantileBreaks}: ArrowScaleResolution,
144
+ functions?: readonly ArrowTableFunction[]
145
+ ): CompiledArrowScale {
146
+ /** Break points used by classified scales. */
147
+ let thresholds: readonly number[] | undefined;
148
+ /** Scale transform and classification family. */
149
+ const kind = parsed.scale.type;
150
+ /** Number of discrete classes declared by the palette, if any. */
151
+ const classCount = getClassCount(parsed.scale);
152
+ if (kind === 'quantile') {
153
+ if (
154
+ classCount === undefined ||
155
+ !Number.isSafeInteger(classCount) ||
156
+ classCount < 2 ||
157
+ quantileBreaks?.length !== classCount - 1
158
+ ) {
159
+ throw new Error('Quantile scale requires one resolved break per class boundary');
160
+ }
161
+ if (
162
+ quantileBreaks.some(
163
+ (value, index) =>
164
+ !Number.isFinite(value) || (index > 0 && value < quantileBreaks[index - 1]!)
165
+ )
166
+ ) {
167
+ throw new Error('Quantile scale breaks must be finite and nondecreasing');
168
+ }
169
+ thresholds = quantileBreaks;
170
+ } else if (kind === 'quantize') {
171
+ if (
172
+ !classCount ||
173
+ domain.length !== 2 ||
174
+ typeof domain[0] !== 'number' ||
175
+ typeof domain[1] !== 'number'
176
+ ) {
177
+ throw new Error('Quantize scale requires a numeric extent and a class count');
178
+ }
179
+ thresholds = Array.from(
180
+ {length: classCount - 1},
181
+ (_, i) =>
182
+ (domain[0] as number) +
183
+ (((domain[1] as number) - (domain[0] as number)) * (i + 1)) / classCount
184
+ );
185
+ } else if (kind === 'threshold') {
186
+ if (domain.some(value => typeof value !== 'number')) {
187
+ throw new Error('Thresholds require numeric domain values');
188
+ }
189
+ thresholds = domain as readonly number[];
190
+ }
191
+ /** Evaluator shared by Arrow output and descriptor consumers. */
192
+ const scale = compileResolvedScale(parsed.scale, domain, thresholds);
193
+ /** Input expression bound once to the source schema. */
194
+ const compiled = compileArrowExpression(parsed.value as ArrowExpression, {
195
+ inputSchema,
196
+ functions
197
+ });
198
+ /** Maps one vector to the selected scalar or color encoding. */
199
+ const evaluateVector = (input: Vector): Vector => {
200
+ const result: (number | ScaleColor | null)[] = Array.from({length: input.length}, (_, i) => {
201
+ const value = arrowScaleValue(input.get(i));
202
+ if (value === null || value === undefined) return scale.sample(null);
203
+ if (typeof value !== 'number' && typeof value !== 'string') {
204
+ throw new Error('Scale expression must produce scalar numeric or categorical values');
205
+ }
206
+ return scale.sample(value) as number | ScaleColor | null;
207
+ });
208
+ return toVector(result, parsed.scale);
209
+ };
210
+ return {
211
+ scale,
212
+ evaluate: input => evaluateVector(compiled.evaluateTable(input)),
213
+ evaluateBatch: batch => evaluateVector(compiled.evaluate(batch))
214
+ };
215
+ }
216
+
217
+ /**
218
+ * Compile several scales, sharing one Arrow domain scan for repeated columns.
219
+ * Returns independent samplers, vectors and authoritative descriptors.
220
+ */
221
+ export function compileArrowScales<K extends string>(
222
+ table: Table,
223
+ expressions: Readonly<Record<K, ParsedSQLScale>>,
224
+ functions?: readonly ArrowTableFunction[]
225
+ ): Record<K, CompiledArrowScale> {
226
+ const entries = Object.entries(expressions) as [K, ParsedSQLScale][];
227
+ const columnEntries = entries.filter(
228
+ ([, parsed]) => parsed.scale.domain.type !== 'expression-extent'
229
+ );
230
+ const domains = resolveArrowDomains(
231
+ table,
232
+ columnEntries.map(([, parsed]) => parsed.scale.domain)
233
+ );
234
+ const domainsByKey = new Map(columnEntries.map(([key], index) => [key, domains[index]!]));
235
+ return Object.fromEntries(
236
+ entries.map(([key, parsed]) => [
237
+ key,
238
+ compileArrowScale(table, parsed, domainsByKey.get(key), functions)
239
+ ])
240
+ ) as Record<K, CompiledArrowScale>;
241
+ }
242
+
243
+ export {createStreamingDomainAccumulator} from './streaming-domains';
244
+ export type {StreamingDomainOptions} from './streaming-domains';
245
+
246
+ /** A composed expression with one authoritative descriptor per scale call, in traversal order. */
247
+ export type CompiledArrowScaleExpression = CompiledArrowExpression & {
248
+ /** Domains resolve against the complete input table, independently of CASE branch selection. */
249
+ readonly scales: readonly ResolvedScale[];
250
+ };
251
+
252
+ /**
253
+ * Compiles SQL containing scales inside CASE, COALESCE, or other expressions.
254
+ * Domains resolve once over the complete table. Per-row scale inputs obey the
255
+ * expression compiler's active-row masks, so unselected CASE branches are not evaluated.
256
+ * Recompile after changing the source data to refresh data-derived domains.
257
+ */
258
+ export function compileArrowScaleExpression(
259
+ table: Table,
260
+ expression: string | Expression,
261
+ functions: readonly ArrowTableFunction[] = []
262
+ ): CompiledArrowScaleExpression {
263
+ /** Parsed caller expression; rewriting never mutates it. */
264
+ const ast = typeof expression === 'string' ? parseSQLExpression(expression) : expression;
265
+ /** Reserved caller identifiers and generated function names. */
266
+ const names = new Set(functions.map(fn => fn.name.toUpperCase()));
267
+ /** Resolved descriptors in outer-before-inner traversal order. */
268
+ const scales: ResolvedScale[] = [];
269
+ /** Caller functions followed by generated scale functions. */
270
+ const declarations = [...functions];
271
+ /** Reserves user identifiers before allocating internal function names. */
272
+ function reserve(node: unknown): void {
273
+ if (!node || typeof node !== 'object') return;
274
+ if ('type' in node && node.type === 'Identifier' && 'name' in node)
275
+ names.add(String(node.name).toUpperCase());
276
+ for (const value of Object.values(node)) reserve(value);
277
+ }
278
+ reserve(ast);
279
+ /** Monotonic suffix for collision-free internal names. */
280
+ let nextName = 0;
281
+ /** Replaces each scale call with a typed vector function bound to its resolved domain. */
282
+ function visit(node: any): any {
283
+ if (!node || typeof node !== 'object') return node;
284
+ if (Array.isArray(node)) return node.map(visit);
285
+ if (
286
+ node.type === 'CallExpression' &&
287
+ node.callee?.type === 'Identifier' &&
288
+ /^SCALE_(LINEAR|SQRT|LOG|COLOR|DIVERGING|ORDINAL|QUANTILE|QUANTIZE|THRESHOLD)$/i.test(
289
+ node.callee.name
290
+ )
291
+ ) {
292
+ /** Reserve descriptor order before recursively resolving nested scale inputs. */
293
+ const scaleIndex = scales.length;
294
+ scales.length++;
295
+ /** Rewrite the value before parsing so computed domains reference generated functions too. */
296
+ const valueExpression = visit(node.arguments[0]);
297
+ /** Validated outer scale with nested inputs already bound. */
298
+ const parsed = parseSQLScaleAST({
299
+ ...node,
300
+ arguments: [valueExpression, ...node.arguments.slice(1)]
301
+ });
302
+ /** Whole-table domain and sampler, using all nested function declarations. */
303
+ const {scale} = compileArrowScale(table, parsed, undefined, declarations);
304
+ scales[scaleIndex] = scale;
305
+ /** Input type for the generated vector function overload. */
306
+ const input = compileArrowExpression(parsed.value as ArrowExpression, {
307
+ inputSchema: table.schema,
308
+ functions: declarations
309
+ });
310
+ /** Private function identifier that cannot shadow a caller name. */
311
+ let name: string;
312
+ do {
313
+ name = '__scale_' + nextName++;
314
+ } while (names.has(name.toUpperCase()));
315
+ names.add(name.toUpperCase());
316
+ declarations.push({
317
+ name,
318
+ prototypes: [
319
+ {
320
+ arguments: [input.outputField],
321
+ result: new Field(name, toVector([], parsed.scale).type, true),
322
+ nullHandling: 'call',
323
+ evaluate: ([values], {activeRows, length}) =>
324
+ toVector(
325
+ Array.from({length}, (_, row) => {
326
+ if (!activeRows[row]) return null;
327
+ /** Active scalar input with Arrow integer normalization. */
328
+ const value = arrowScaleValue(values!.get(row));
329
+ if (
330
+ value !== null &&
331
+ value !== undefined &&
332
+ typeof value !== 'number' &&
333
+ typeof value !== 'string'
334
+ ) {
335
+ throw new Error('Scale input must be numeric or categorical');
336
+ }
337
+ return scale.sample((value ?? null) as ScaleValue | null) as
338
+ | number
339
+ | ScaleColor
340
+ | null;
341
+ }),
342
+ parsed.scale
343
+ )
344
+ }
345
+ ]
346
+ });
347
+ return {
348
+ type: 'CallExpression',
349
+ callee: {type: 'Identifier', name},
350
+ arguments: [parsed.value]
351
+ };
352
+ }
353
+ return Object.fromEntries(Object.entries(node).map(([key, value]) => [key, visit(value)]));
354
+ }
355
+ /** Ordinary Arrow expression after removing every supported scale call. */
356
+ const rewritten = visit(ast);
357
+ /** Final evaluator with caller and generated declarations. */
358
+ const compiled = compileArrowExpression(rewritten, {
359
+ inputSchema: table.schema,
360
+ functions: declarations
361
+ });
362
+ return {...compiled, scales};
363
+ }
@@ -0,0 +1,5 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ export * from '@math.gl/core/color';