@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,66 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {DateDay, TimestampMicrosecond, type DataType} from 'apache-arrow';
6
+ import {ExpressionEvaluationError} from '../expressions';
7
+ import {typeKey} from './buffers';
8
+ import type {ArrowExpressionValue} from './types';
9
+
10
+ const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
11
+ const TIMESTAMP =
12
+ /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?(Z|[+-]\d{2}:\d{2})?$/;
13
+
14
+ /** Binds ISO text or an already matching Arrow temporal value to a temporal output. */
15
+ export function bindTemporalCast(source: DataType, target: 'date' | 'timestamp' | 'timestamp_utc') {
16
+ const dateOnly = target === 'date';
17
+ const zoned = target === 'timestamp_utc';
18
+ const type = dateOnly ? new DateDay() : new TimestampMicrosecond(zoned ? 'UTC' : undefined);
19
+ const sourceKey = typeKey(source);
20
+ if (sourceKey !== 'utf8' && sourceKey !== 'null' && sourceKey !== typeKey(type))
21
+ throw new Error('Temporal CAST requires UTF8 or an input of the requested Arrow type');
22
+ return {
23
+ type,
24
+ textInput: false,
25
+ evaluate(value: ArrowExpressionValue): ArrowExpressionValue {
26
+ return typeof value === 'string' ? parseTemporalValue(value, dateOnly, zoned) : value;
27
+ }
28
+ };
29
+ }
30
+
31
+ /** Converts a validated calendar value to Arrow epoch days or exact epoch microseconds. */
32
+ function parseTemporalValue(text: string, dateOnly: boolean, zoned: boolean): number | bigint {
33
+ const match = (dateOnly ? DATE : TIMESTAMP).exec(text.trim());
34
+ const invalid = () =>
35
+ new ExpressionEvaluationError('conversion', 'Invalid text for temporal CAST');
36
+ if (!match) throw invalid();
37
+ const [, yearText, monthText, dayText, hourText, minuteText, secondText, fraction, zone] = match;
38
+ const year = Number(yearText);
39
+ const month = Number(monthText);
40
+ const day = Number(dayText);
41
+ const calendar = new Date(0);
42
+ // setUTCFullYear also handles four-digit years below 0100 without a 1900 offset.
43
+ calendar.setUTCFullYear(year, month - 1, day);
44
+ if (
45
+ calendar.getUTCFullYear() !== year ||
46
+ calendar.getUTCMonth() !== month - 1 ||
47
+ calendar.getUTCDate() !== day
48
+ )
49
+ throw invalid();
50
+ if (dateOnly) return calendar.getTime() / 86_400_000;
51
+ const hour = Number(hourText);
52
+ const minute = Number(minuteText);
53
+ const second = Number(secondText);
54
+ if (hour > 23 || minute > 59 || second > 59 || zoned !== Boolean(zone)) throw invalid();
55
+ let offsetMinutes = 0;
56
+ if (zone && zone !== 'Z') {
57
+ const offsetHour = Number(zone.slice(1, 3));
58
+ const offsetMinute = Number(zone.slice(4));
59
+ if (offsetHour > 23 || offsetMinute > 59) throw invalid();
60
+ offsetMinutes = (zone.startsWith('-') ? -1 : 1) * (offsetHour * 60 + offsetMinute);
61
+ }
62
+ const seconds = hour * 3600 + minute * 60 + second - offsetMinutes * 60;
63
+ return (
64
+ BigInt(calendar.getTime() + seconds * 1000) * 1000n + BigInt((fraction ?? '').padEnd(6, '0'))
65
+ );
66
+ }
@@ -0,0 +1,76 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import type {Field, Schema, RecordBatch, Vector, Table} from 'apache-arrow';
6
+ import type {Expression} from '../expressions';
7
+
8
+ /**
9
+ * Scalar values exposed to user callbacks. Date32 uses epoch days and microsecond
10
+ * timestamps use bigint microseconds, matching their Arrow storage buffers.
11
+ */
12
+ export type ArrowExpressionValue = number | bigint | boolean | string | Uint8Array | null;
13
+
14
+ /** A vector kernel receives full-length inputs and must evaluate only active rows. */
15
+ export type ArrowTableFunctionType = (
16
+ arguments_: readonly Vector[],
17
+ context: {
18
+ /** One byte per row; zero means the row must not be evaluated. */
19
+ activeRows: Uint8Array;
20
+ /** Number of rows in every argument and the returned vector. */
21
+ length: number;
22
+ /** Report a row failure; TRY recovers classified errors, otherwise the call throws. */
23
+ reportError?(row: number, error: unknown): void;
24
+ }
25
+ ) => Vector;
26
+
27
+ /** One schema-bound implementation of a named table function. */
28
+ export type ArrowTableFunctionPrototype = Readonly<{
29
+ /** Ordered argument fields, with exact types, nullability and extension metadata. */
30
+ arguments: readonly Field[];
31
+ /** Declared result field; its name is retained for direct calls. */
32
+ result: Field;
33
+ /** Propagate null arguments, or pass them to the implementation. Defaults to propagate. */
34
+ nullHandling?: 'propagate' | 'call';
35
+ /** Batch implementation, also independently callable with the declared arguments and mask. */
36
+ evaluate: ArrowTableFunctionType;
37
+ /** Optional equivalent primitive implementation used for fused expression execution. */
38
+ evaluateScalar?(...arguments_: ArrowExpressionValue[]): ArrowExpressionValue;
39
+ }>;
40
+
41
+ /** Named overload group; each argument signature must be unique. */
42
+ export type ArrowTableFunction = Readonly<{
43
+ /** Unique expression identifier; built-in names are reserved. */
44
+ name: string;
45
+ /** Typed implementations selected once when compiling a call. */
46
+ prototypes: readonly ArrowTableFunctionPrototype[];
47
+ }>;
48
+
49
+ /** Schema binding shared by predicate and expression compilation. */
50
+ export type ArrowExpressionOptions = Readonly<{
51
+ /** Expected batch schema, validated before evaluation. */
52
+ inputSchema: Schema;
53
+ /** Named function declarations, snapshotted into a private lookup during compilation. */
54
+ functions?: readonly ArrowTableFunction[];
55
+ }>;
56
+
57
+ /** Controls shared by batch and whole-table evaluation. */
58
+ export type ArrowExpressionEvaluationOptions = {
59
+ /** One byte per logical row, including all batches when evaluating a table. */
60
+ activeRows?: Uint8Array;
61
+ /** Checked before and after each batch; synchronous execution does not yield. */
62
+ signal?: AbortSignal;
63
+ };
64
+
65
+ /** A compiled expression preserves row count and returns a non-dictionary vector. */
66
+ export interface CompiledArrowExpression {
67
+ /** Bound result type and nullability. */
68
+ readonly outputField: Field;
69
+ /** Evaluates a batch; optional masks skip rows and produce null at those positions. */
70
+ evaluate(batch: RecordBatch, options?: ArrowExpressionEvaluationOptions): Vector;
71
+ /** Evaluates ordered batches and combines output chunks without copying their buffers. */
72
+ evaluateTable(arrowTable: Table, options?: ArrowExpressionEvaluationOptions): Vector;
73
+ }
74
+
75
+ /** Text or the existing core expression AST. */
76
+ export type ArrowExpression = string | Expression;
@@ -0,0 +1,145 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {DataType, Field, Int32, Schema, Table, Utf8, Vector, vectorFromArray} from 'apache-arrow';
6
+ import {takeArrowTableRows} from '@math.gl/core/arrow';
7
+ import {physicalKey, extensionKey} from './signature';
8
+
9
+ /** Names and cancellation for expanding a nested column into relational rows. */
10
+ export type UnnestArrowColumnOptions = {
11
+ /** Name of the appended child-value column. Must not replace an existing column. */
12
+ valueColumn: string;
13
+ /** Optional map/struct key or one-based list position column. */
14
+ keyColumn?: string;
15
+ /** Optional one-based element position, including for maps. */
16
+ ordinalColumn?: string;
17
+ /** Retain null and empty containers as one row with null key/value. Defaults to false. */
18
+ outer?: boolean;
19
+ /** Synchronous cancellation, checked per source row. */
20
+ signal?: AbortSignal;
21
+ };
22
+
23
+ /**
24
+ * Expands a List, FixedSizeList, Map, or homogeneous Struct column.
25
+ * Parent columns and metadata are retained. Lists preserve element order, maps
26
+ * preserve entry order, and structs use schema field order. Null elements remain
27
+ * rows; null/empty containers produce no rows unless outer is true.
28
+ */
29
+ export function unnestArrowColumn(
30
+ table: Table,
31
+ column: string,
32
+ options: UnnestArrowColumnOptions
33
+ ): Table {
34
+ const input = table.getChild(column);
35
+ if (!input) throw new Error(`Unknown nested column: ${column}`);
36
+ const type = input.type;
37
+ const list = DataType.isList(type) || DataType.isFixedSizeList(type);
38
+ const map = DataType.isMap(type);
39
+ const struct = DataType.isStruct(type);
40
+ if (!list && !map && !struct) throw new Error('UNNEST requires a list, map, or struct column');
41
+ const children = map ? type.children[0]!.type.children : type.children;
42
+ const valueField = children[map ? 1 : 0];
43
+ if (!valueField) throw new Error('UNNEST requires a declared child type');
44
+ if (
45
+ struct &&
46
+ children.some(
47
+ field =>
48
+ physicalKey(field.type) !== physicalKey(valueField.type) ||
49
+ extensionKey(field) !== extensionKey(valueField)
50
+ )
51
+ ) {
52
+ throw new Error('UNNEST struct fields must share one type');
53
+ }
54
+ const keyType = list ? new Int32() : map ? children[0]!.type : new Utf8();
55
+ const fields = [
56
+ ...table.schema.fields,
57
+ valueField.clone({name: options.valueColumn, nullable: true}),
58
+ ...(options.keyColumn ? [new Field(options.keyColumn, keyType, true)] : []),
59
+ ...(options.ordinalColumn ? [new Field(options.ordinalColumn, new Int32(), true)] : [])
60
+ ];
61
+ if (new Set(fields.map(field => field.name)).size !== fields.length) {
62
+ throw new Error('Duplicate UNNEST output name');
63
+ }
64
+ const schema = new Schema(fields, table.schema.metadata);
65
+ const parentRows: number[] = [];
66
+ /** Physical child slices preserve timestamps, dictionaries and nested values. */
67
+ const values: Vector[] = [];
68
+ /** Physical map keys or generated struct/list positions. */
69
+ const keys: Vector[] = [];
70
+ /** One-based position within each parent collection. */
71
+ const positions: (number | null)[] = [];
72
+ /** Current collection position, reset for each parent. */
73
+ let position = 0;
74
+ /** Appends one expanded row while preserving its parent index. */
75
+ function append(row: number, key: Vector, value: Vector, ordinal: number | null): void {
76
+ parentRows.push(row);
77
+ keys.push(key);
78
+ values.push(value);
79
+ positions.push(ordinal);
80
+ }
81
+ /** Tracks logical parent positions across Arrow chunks. */
82
+ let row = 0;
83
+ for (const data of input.data) {
84
+ /** Chunk-local parent validity and offsets. */
85
+ const chunk = new Vector([data]);
86
+ for (let local = 0; local < chunk.length; local++, row++) {
87
+ options.signal?.throwIfAborted();
88
+ const before = parentRows.length;
89
+ position = 0;
90
+ if (chunk.isValid(local)) {
91
+ if (struct) {
92
+ for (let index = 0; index < children.length; index++) {
93
+ append(
94
+ row,
95
+ vectorFromArray([children[index]!.name], keyType),
96
+ new Vector([data.children[index]!]).slice(local, local + 1),
97
+ ++position
98
+ );
99
+ }
100
+ } else {
101
+ /** Collection offsets already account for sliced variable-length parents. */
102
+ const begin =
103
+ list && DataType.isFixedSizeList(type)
104
+ ? (data.offset + local) * type.listSize
105
+ : Number(data.valueOffsets[local]);
106
+ const end =
107
+ list && DataType.isFixedSizeList(type)
108
+ ? begin + type.listSize
109
+ : Number(data.valueOffsets[local + 1]);
110
+ /** Physical collection values, including map entry structs. */
111
+ const child = new Vector([data.children[0]!]);
112
+ for (let index = begin; index < end; index++) {
113
+ options.signal?.throwIfAborted();
114
+ const value = map
115
+ ? child.getChildAt(1)!.slice(index, index + 1)
116
+ : child.slice(index, index + 1);
117
+ const key = map
118
+ ? child.getChildAt(0)!.slice(index, index + 1)
119
+ : vectorFromArray([index - begin + 1], keyType);
120
+ append(row, key, value, ++position);
121
+ }
122
+ }
123
+ }
124
+ if (options.outer && before === parentRows.length)
125
+ append(
126
+ row,
127
+ vectorFromArray([null], keyType),
128
+ vectorFromArray([null], valueField.type),
129
+ null
130
+ );
131
+ }
132
+ }
133
+ if (!parentRows.length) return new Table(schema, []);
134
+ const parents = takeArrowTableRows(table, Int32Array.from(parentRows));
135
+ return new Table(schema, {
136
+ ...Object.fromEntries(
137
+ table.schema.fields.map(field => [field.name, parents.getChild(field.name)!])
138
+ ),
139
+ [options.valueColumn]: new Vector(values.flatMap(value => value.data)),
140
+ ...(options.keyColumn ? {[options.keyColumn]: new Vector(keys.flatMap(key => key.data))} : {}),
141
+ ...(options.ordinalColumn
142
+ ? {[options.ordinalColumn]: vectorFromArray(positions, new Int32())}
143
+ : {})
144
+ });
145
+ }
@@ -0,0 +1,10 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {initializeTaskWorker} from '@math.gl/tasks';
6
+ import {createArrowExpressionTask} from './worker';
7
+
8
+ // Default worker for primitive expressions. Applications can provide their own module worker
9
+ // with local declarations by initializing createArrowExpressionTask({functions}) instead.
10
+ void initializeTaskWorker(createArrowExpressionTask());
@@ -0,0 +1,143 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {Table, RecordBatch, Schema, Struct, Vector, makeData, type Field} from 'apache-arrow';
6
+ import type {Task, TaskWorker} from '@math.gl/tasks';
7
+ import type {
8
+ ParameterizedColumnarPredicate,
9
+ ColumnarPredicateParameterValues
10
+ } from '../expressions';
11
+ import {
12
+ dehydrateArrowTable,
13
+ hydrateArrowTable,
14
+ type DehydratedArrowTable
15
+ } from '@math.gl/core/arrow';
16
+ import {compileArrowExpression} from './compiler';
17
+ import {compileArrowPredicate} from './predicate';
18
+ import type {ArrowExpression, CompiledArrowExpression} from './types';
19
+ import type {ArrowTableFunction} from './types';
20
+
21
+ /** Serializable program, compiled once in each initialized task instance. */
22
+ export type ArrowExpressionProgram =
23
+ | {expression: ArrowExpression; predicate?: never; parameters?: never}
24
+ | {
25
+ predicate: ParameterizedColumnarPredicate;
26
+ parameters?: ColumnarPredicateParameterValues;
27
+ expression?: never;
28
+ };
29
+
30
+ /** Borrowed column-buffer payload; use TaskRunner ownership controls when sending. */
31
+ export type ArrowExpressionTaskInput = {table: DehydratedArrowTable; activeRows?: Uint8Array};
32
+ /** One-column table retains the output field, validity and ordered chunks. */
33
+ export type ArrowExpressionTaskOutput = {table: DehydratedArrowTable};
34
+
35
+ type ExpressionTaskTypes = {
36
+ initialization: ArrowExpressionProgram;
37
+ input: ArrowExpressionTaskInput;
38
+ output: ArrowExpressionTaskOutput;
39
+ state: {program: ArrowExpressionProgram; compiled?: CompiledArrowExpression};
40
+ };
41
+
42
+ /**
43
+ * Creates a reusable task. Construct custom function arrays inside the worker; callbacks never cross
44
+ * the transport. Supply a module-worker URL or factory on the host and initialize the same task
45
+ * with initializeTaskWorker in the worker. A retained task accepts one bound input schema.
46
+ */
47
+ export function createArrowExpressionTask(
48
+ options: {functions?: readonly ArrowTableFunction[]; worker?: TaskWorker} = {}
49
+ ): Task<ExpressionTaskTypes> {
50
+ return {
51
+ id: 'math.gl-arrow-expression',
52
+ worker: options.worker,
53
+ initialize(program) {
54
+ return {program};
55
+ },
56
+ async process(input, _options, context) {
57
+ context.throwIfAborted();
58
+ const table = hydrateArrowTable(input.table);
59
+ const state = context.state;
60
+ state.compiled ||=
61
+ state.program.expression !== undefined
62
+ ? compileArrowExpression(state.program.expression, {
63
+ inputSchema: table.schema,
64
+ functions: options.functions
65
+ })
66
+ : compileArrowPredicate(state.program.predicate!, {
67
+ inputSchema: table.schema,
68
+ functions: options.functions,
69
+ parameters: state.program.parameters
70
+ });
71
+ const compiled = state.compiled;
72
+ const mask = input.activeRows;
73
+ if (mask && (mask.length !== table.numRows || mask.some(value => value !== 0 && value !== 1)))
74
+ throw new Error('activeRows must contain one 0 or 1 per input row');
75
+ // Validate even an empty table against the previously compiled schema.
76
+ compiled.evaluateTable(new Table(table.schema, []), {signal: context.signal});
77
+ const chunks = [];
78
+ let offset = 0;
79
+ for (const batch of table.batches) {
80
+ // Yield to cancellation messages between batches, including before the first batch.
81
+ await new Promise<void>(resolve => setTimeout(resolve, 0));
82
+ context.throwIfAborted();
83
+ chunks.push(
84
+ ...compiled.evaluate(batch, {
85
+ activeRows: mask?.subarray(offset, offset + batch.numRows),
86
+ signal: context.signal
87
+ }).data
88
+ );
89
+ offset += batch.numRows;
90
+ context.reportProgress({completed: offset, total: table.numRows, unit: 'rows'});
91
+ }
92
+ context.throwIfAborted();
93
+ const vector = chunks.length ? new Vector(chunks) : compiled.evaluateTable(table);
94
+ // A mask may introduce nulls even when the logical expression is non-nullable.
95
+ const field = mask ? compiled.outputField.clone({nullable: true}) : compiled.outputField;
96
+ const schema = new Schema([field]);
97
+ const batches = vector.data.map(
98
+ data =>
99
+ new RecordBatch(
100
+ schema,
101
+ makeData({
102
+ type: new Struct([field]),
103
+ length: data.length,
104
+ nullCount: 0,
105
+ children: [data]
106
+ })
107
+ )
108
+ );
109
+ return {table: dehydrateArrowTable(new Table(schema, batches), {copy: 'none'})};
110
+ }
111
+ };
112
+ }
113
+
114
+ /**
115
+ * Prepares borrowed buffers without copying values or detaching the input. TaskRunner defaults
116
+ * to copying them. inputOwnership:'transfer' relinquishes every referenced ArrayBuffer, including
117
+ * buffers shared with slices or other columns; do not read the original table afterward.
118
+ */
119
+ export function prepareArrowExpressionInput(
120
+ arrowTable: Table,
121
+ options: {activeRows?: Uint8Array} = {}
122
+ ): ArrowExpressionTaskInput {
123
+ return {table: dehydrateArrowTable(arrowTable, {copy: 'none'}), activeRows: options.activeRows};
124
+ }
125
+
126
+ /** Hydrates worker results without copying data buffers. */
127
+ export function hydrateArrowExpressionResult(output: ArrowExpressionTaskOutput): {
128
+ field: Field;
129
+ vector: Vector;
130
+ } {
131
+ const table = hydrateArrowTable(output.table);
132
+ if (table.numCols !== 1) throw new Error('Arrow expression task must return exactly one column');
133
+ return {field: table.schema.fields[0]!, vector: table.getChildAt(0)!};
134
+ }
135
+
136
+ export {
137
+ createArrowQueryTask,
138
+ createArrowQueryWorker,
139
+ queryArrowTableInWorker,
140
+ type ArrowQueryWorkerOptions,
141
+ type ArrowQueryWorkerSession,
142
+ type ArrowWorkerQuery
143
+ } from './query-worker';