@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,1778 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {
6
+ Binary,
7
+ Bool,
8
+ Precision,
9
+ DataType,
10
+ Field,
11
+ Float64,
12
+ Float32,
13
+ Float16,
14
+ FixedSizeList,
15
+ Dictionary,
16
+ Int64,
17
+ TimestampMicrosecond,
18
+ Int32,
19
+ Uint8,
20
+ Null,
21
+ Utf8,
22
+ vectorFromArray,
23
+ makeData,
24
+ makeVector,
25
+ type RecordBatch,
26
+ Vector,
27
+ type Table,
28
+ type Schema
29
+ } from 'apache-arrow';
30
+ import {compareUTF8, parseUTF8Number, parseUTF8BigInt, parseUTF8Boolean} from '@math.gl/core/utf8';
31
+ import {parse, validateExpressionAST, type Expression} from '../expressions';
32
+ import {ColumnReader, typeKey, valueType, validateValue, createValueValidator} from './buffers';
33
+ import {bindCast} from './cast';
34
+ import {compileUTF8Like} from './like';
35
+ import {float16Values, roundFloat16} from './float16';
36
+ import {physicalKey, extensionKey} from './signature';
37
+ import {ExpressionEvaluationError, isExpressionEvaluationError} from '../expressions';
38
+ import {createFunctionLookup} from './registry';
39
+ import {
40
+ isTupleType,
41
+ nullTupleVector,
42
+ maskTupleVector,
43
+ validateTupleVector,
44
+ selectTupleVectors,
45
+ compileArrayLiteral
46
+ } from './list-values';
47
+ import type {
48
+ ArrowTableFunction,
49
+ ArrowTableFunctionPrototype,
50
+ ArrowExpression,
51
+ ArrowExpressionOptions,
52
+ ArrowExpressionEvaluationOptions,
53
+ ArrowExpressionValue,
54
+ CompiledArrowExpression
55
+ } from './types';
56
+
57
+ type BindingOptions = ArrowExpressionOptions & {
58
+ functionLookup: ReadonlyMap<string, ArrowTableFunction>;
59
+ };
60
+
61
+ type Mask = Uint8Array;
62
+ type ExecutionContext = {failed?: Uint8Array};
63
+ type Range = [Uint8Array, number, number];
64
+ type Prepared = {
65
+ get: (row: number) => ArrowExpressionValue;
66
+ bytes?: (row: number) => Range | null;
67
+ isNull?: (row: number) => boolean;
68
+ vector?: Vector;
69
+ };
70
+ type Node = {
71
+ /** Preconverted literal storage, shared by all batches of a compiled expression. */
72
+ constant?: Prepared;
73
+ field: Field;
74
+ hasKernel: boolean;
75
+ prepare: (batch: RecordBatch, active: Mask, context: ExecutionContext) => Prepared;
76
+ };
77
+ const encoder = new TextEncoder();
78
+ const bool = new Bool();
79
+
80
+ /** Compiles a core expression AST against a fixed Arrow schema. */
81
+ export function compileArrowExpression(
82
+ expression: ArrowExpression,
83
+ options: ArrowExpressionOptions
84
+ ): CompiledArrowExpression {
85
+ const fields = [...options.inputSchema.fields];
86
+ if (new Set(fields.map(field => field.name)).size !== fields.length)
87
+ throw new Error('Expression input field names must be unique');
88
+ const ast = parse(expression);
89
+ validateExpressionAST(ast);
90
+ const root = bind(ast, {
91
+ ...options,
92
+ functionLookup: createFunctionLookup(options.functions)
93
+ });
94
+ const keys = fields.map(field => ({
95
+ name: field.name,
96
+ type: physicalKey(field.type),
97
+ nullable: field.nullable,
98
+ extension: extensionKey(field)
99
+ }));
100
+ const validateSchema = (schema: Schema) => {
101
+ if (
102
+ schema.fields.length !== keys.length ||
103
+ schema.fields.some((field, index) => {
104
+ const expected = keys[index]!;
105
+ return (
106
+ field.name !== expected.name ||
107
+ physicalKey(field.type) !== expected.type ||
108
+ field.nullable !== expected.nullable ||
109
+ extensionKey(field) !== expected.extension
110
+ );
111
+ })
112
+ )
113
+ throw new Error('Arrow expression input schema mismatch');
114
+ };
115
+ const validateMask = (mask: Uint8Array | undefined, length: number) => {
116
+ if (mask && (mask.length !== length || mask.some(value => value !== 0 && value !== 1)))
117
+ throw new Error('activeRows must contain one 0 or 1 per input row');
118
+ };
119
+ const evaluate = (
120
+ batch: RecordBatch,
121
+ evaluation: ArrowExpressionEvaluationOptions = {}
122
+ ): Vector => {
123
+ evaluation.signal?.throwIfAborted();
124
+ validateSchema(batch.schema);
125
+ validateMask(evaluation.activeRows, batch.numRows);
126
+ const active = evaluation.activeRows
127
+ ? evaluation.activeRows.slice()
128
+ : new Uint8Array(batch.numRows).fill(1);
129
+ const prepared = root.prepare(batch, active, {});
130
+ const result = isTupleType(root.field.type)
131
+ ? maskTupleVector(prepared.vector!, active)
132
+ : isNestedType(root.field.type)
133
+ ? nestedVector(prepared.vector!, root.field.type, active)
134
+ : prepared.vector &&
135
+ (root.constant ||
136
+ (!DataType.isDictionary(prepared.vector.type) && !active.some(value => !value)))
137
+ ? prepared.vector
138
+ : output(root.field, active, prepared.get);
139
+ evaluation.signal?.throwIfAborted();
140
+ return result;
141
+ };
142
+ return Object.freeze({
143
+ outputField: root.field,
144
+ evaluate,
145
+ evaluateTable(arrowTable: Table, evaluation: ArrowExpressionEvaluationOptions = {}): Vector {
146
+ evaluation.signal?.throwIfAborted();
147
+ validateSchema(arrowTable.schema);
148
+ validateMask(evaluation.activeRows, arrowTable.numRows);
149
+ let offset = 0;
150
+ const chunks = arrowTable.batches.flatMap(batch => {
151
+ const activeRows = evaluation.activeRows?.subarray(offset, offset + batch.numRows);
152
+ offset += batch.numRows;
153
+ return evaluate(batch, {...evaluation, activeRows}).data;
154
+ });
155
+ return chunks.length
156
+ ? new Vector(chunks)
157
+ : isTupleType(root.field.type)
158
+ ? nullTupleVector(root.field.type, 0)
159
+ : isNestedType(root.field.type)
160
+ ? vectorFromArray([], root.field.type)
161
+ : output(root.field, new Uint8Array(0), () => null);
162
+ }
163
+ });
164
+ }
165
+
166
+ /** Binds a registered function call using the same expression compiler. */
167
+ export function compileArrowFunction(
168
+ name: string,
169
+ arguments_: readonly ArrowExpression[],
170
+ options: ArrowExpressionOptions
171
+ ): CompiledArrowExpression {
172
+ return compileArrowExpression(
173
+ {
174
+ type: 'CallExpression',
175
+ callee: {type: 'Identifier', name},
176
+ arguments: arguments_.map(argument => parse(argument))
177
+ } as Expression,
178
+ options
179
+ );
180
+ }
181
+
182
+ /** Compiles a packed floating-point source-column projection, preserving Float64 unless explicitly narrowed. */
183
+ export function compileArrowArray(
184
+ columns: readonly string[],
185
+ options: ArrowExpressionOptions & {type?: 'float16' | 'float32' | 'float64' | 'uint8'}
186
+ ): CompiledArrowExpression {
187
+ if (
188
+ !Array.isArray(columns) ||
189
+ !columns.length ||
190
+ columns.length > 4096 ||
191
+ Array.from(columns).some(name => typeof name !== 'string' || !name.length)
192
+ )
193
+ throw new Error('ARRAY requires 1 to 4096 source column names');
194
+ if (
195
+ options.type !== undefined &&
196
+ !['float16', 'float32', 'float64', 'uint8'].includes(options.type)
197
+ )
198
+ throw new Error('Unsupported ARRAY component type');
199
+ return compileArrowExpression(
200
+ {
201
+ type: 'CallExpression',
202
+ callee: {type: 'Identifier', name: options.type ? `array_${options.type}` : 'array'},
203
+ arguments: columns.map(name => ({type: 'Identifier', name}))
204
+ } as Expression,
205
+ options
206
+ );
207
+ }
208
+
209
+ /** Builds one vector while validating output values before Arrow can truncate them. */
210
+ function output(
211
+ field: Field,
212
+ active: Mask,
213
+ evaluate: (row: number) => ArrowExpressionValue
214
+ ): Vector {
215
+ const type = valueType(field.type);
216
+ const validate = createValueValidator(type);
217
+ if (DataType.isUtf8(type) || DataType.isBinary(type) || DataType.isFixedSizeBinary(type)) {
218
+ const values: ArrowExpressionValue[] = new Array(active.length).fill(null);
219
+ for (let row = 0; row < active.length; row++)
220
+ if (active[row]) {
221
+ const value = evaluate(row);
222
+ if (value === null && !field.nullable)
223
+ throw new Error(`Non-nullable expression ${field.name} returned null`);
224
+ validate(value);
225
+ values[row] = value;
226
+ }
227
+ return vectorFromArray(values as any[], field.type);
228
+ }
229
+ if (DataType.isNull(type)) {
230
+ for (let row = 0; row < active.length; row++) if (active[row]) validate(evaluate(row));
231
+ return makeVector(makeData({type, length: active.length}));
232
+ }
233
+ const isBoolean = DataType.isBool(type);
234
+ const data = isBoolean
235
+ ? new Uint8Array(Math.ceil(active.length / 8))
236
+ : new type.ArrayType(active.length);
237
+ const numericData =
238
+ DataType.isFloat(type) && type.precision === Precision.HALF
239
+ ? float16Values(data as Uint16Array)
240
+ : data;
241
+ const validity = new Uint8Array(Math.ceil(active.length / 8));
242
+ let nullCount = 0;
243
+ for (let row = 0; row < active.length; row++) {
244
+ if (!active[row]) {
245
+ nullCount++;
246
+ continue;
247
+ }
248
+ const value = evaluate(row);
249
+ if (value === null) {
250
+ if (!field.nullable) throw new Error(`Non-nullable expression ${field.name} returned null`);
251
+ nullCount++;
252
+ continue;
253
+ }
254
+ validate(value);
255
+ validity[row >> 3] |= 1 << (row & 7);
256
+ if (isBoolean) {
257
+ if (value) data[row >> 3] |= 1 << (row & 7);
258
+ } else numericData[row] = value as any;
259
+ }
260
+ return makeVector(
261
+ makeData({
262
+ type,
263
+ data,
264
+ length: active.length,
265
+ nullBitmap: validity,
266
+ nullCount
267
+ } as any)
268
+ );
269
+ }
270
+
271
+ /** Wraps a source vector without materializing rows or decoding string operands. */
272
+ function sourceReader(vector: Vector): Prepared {
273
+ const data = vector.data[0];
274
+ if (
275
+ vector.data.length === 1 &&
276
+ (DataType.isInt(data.type) ||
277
+ (DataType.isFloat(data.type) && data.type.precision !== Precision.HALF))
278
+ ) {
279
+ const values = data.values,
280
+ bitmap = data.nullBitmap,
281
+ offset = data.offset;
282
+ const valid = data.nullCount
283
+ ? (row: number) => Boolean(bitmap[(offset + row) >> 3]! & (1 << ((offset + row) & 7)))
284
+ : () => true;
285
+ return {
286
+ vector,
287
+ get: row => (valid(row) ? (values[row] as number | bigint) : null),
288
+ isNull: row => !valid(row)
289
+ };
290
+ }
291
+ const reader = new ColumnReader(vector);
292
+ return {
293
+ vector,
294
+ get: row => reader.get(row),
295
+ isNull: row => !reader.isValid(row),
296
+ bytes:
297
+ typeKey(vector.type) === 'utf8'
298
+ ? row => (reader.isValid(row) ? reader.utf8(row) : null)
299
+ : undefined
300
+ };
301
+ }
302
+
303
+ /** Keeps nested values on the vector path, with parent validity available to null tests. */
304
+ function vectorReader(vector: Vector): Prepared {
305
+ try {
306
+ typeKey(vector.type);
307
+ return sourceReader(vector);
308
+ } catch {
309
+ // Nested layouts have no scalar callback representation.
310
+ }
311
+ const reader = new ColumnReader(vector);
312
+ return {
313
+ vector,
314
+ isNull: row => !reader.isValid(row),
315
+ get: () => {
316
+ throw new Error('Nested values require a vector kernel');
317
+ }
318
+ };
319
+ }
320
+
321
+ /** Obtains UTF-8 bytes, encoding only values returned by scalar functions. */
322
+ function bytes(value: Prepared, row: number): Range | null {
323
+ if (value.bytes) return value.bytes(row);
324
+ const text = value.get(row);
325
+ if (text === null) return null;
326
+ const encoded = encoder.encode(text as string);
327
+ return [encoded, 0, encoded.length];
328
+ }
329
+
330
+ /** Wraps scalar reads only inside a recovery scope; normal fused paths avoid these guards. */
331
+ function bind(ast: any, options: BindingOptions, expected?: DataType, vectorInput = false): Node {
332
+ const node = bindNode(ast, options, expected, vectorInput);
333
+ return {
334
+ ...node,
335
+ prepare(batch, active, context) {
336
+ const mask = context.failed
337
+ ? active.map((value, row) => (value && !context.failed![row] ? 1 : 0))
338
+ : active;
339
+ const prepared = node.prepare(batch, mask, context);
340
+ if (!context.failed) return prepared;
341
+ const guard = <T>(row: number, read: () => T): T | null => {
342
+ if (!mask[row] || context.failed![row]) return null;
343
+ try {
344
+ const value = read();
345
+ return context.failed![row] ? null : value;
346
+ } catch (error) {
347
+ if (!isExpressionEvaluationError(error)) throw error;
348
+ context.failed![row] = 1;
349
+ return null;
350
+ }
351
+ };
352
+ return {
353
+ ...prepared,
354
+ get: row => guard(row, () => prepared.get(row)),
355
+ bytes: prepared.bytes ? row => guard(row, () => prepared.bytes!(row)) : undefined,
356
+ isNull: row =>
357
+ guard(row, () => (prepared.isNull ? prepared.isNull(row) : prepared.get(row) === null)) ??
358
+ true
359
+ };
360
+ }
361
+ };
362
+ }
363
+
364
+ /** Resolves earlier scalar inputs before later kernels can run in a recovery scope. */
365
+ function prepareInput(
366
+ node: Node,
367
+ batch: RecordBatch,
368
+ active: Mask,
369
+ context: ExecutionContext,
370
+ force: boolean
371
+ ): Prepared {
372
+ const prepared = node.prepare(batch, active, context);
373
+ if (!context.failed || !force || prepared.vector) return prepared;
374
+ const mask = active.map((value, row) => (value && !context.failed![row] ? 1 : 0));
375
+ const field = new Field(node.field.name, node.field.type, true, node.field.metadata);
376
+ return sourceReader(output(field, mask, prepared.get));
377
+ }
378
+
379
+ /** Binds supported syntax to fused per-row operations and explicit vector boundaries. */
380
+ function bindNode(
381
+ ast: any,
382
+ options: BindingOptions,
383
+ expected?: DataType,
384
+ vectorInput = false
385
+ ): Node {
386
+ if (isSignedLiteral(ast)) {
387
+ const value = ast.operator === '-' ? -ast.argument.value : ast.argument.value;
388
+ return bind({type: 'Literal', value}, options, expected, vectorInput);
389
+ }
390
+ if (ast.type === 'ArrayExpression') {
391
+ if (!expected) throw new Error('Array literals require a declared list type');
392
+ const materialize = compileArrayLiteral(ast, expected);
393
+ return {
394
+ field: new Field('literal', expected, false),
395
+ hasKernel: false,
396
+ prepare: (_batch, active) => vectorReader(materialize(active.length))
397
+ };
398
+ }
399
+ if (ast.type === 'Identifier') {
400
+ const index = options.inputSchema.fields.findIndex(field => field.name === ast.name);
401
+ if (index < 0) throw new Error(`Unknown Arrow expression field: ${ast.name}`);
402
+ const source = options.inputSchema.fields[index]!;
403
+ const tuple = isTupleType(source.type);
404
+ if (!vectorInput && !tuple) typeKey(source.type);
405
+ return {
406
+ field: new Field(
407
+ source.name,
408
+ vectorInput ? source.type : valueType(source.type),
409
+ source.nullable,
410
+ source.metadata
411
+ ),
412
+ hasKernel: false,
413
+ prepare: batch => {
414
+ const vector = batch.getChildAt(index)!;
415
+ return vectorInput || tuple ? vectorReader(vector) : sourceReader(vector);
416
+ }
417
+ };
418
+ }
419
+ if (ast.type === 'Literal') {
420
+ if (vectorInput && expected && DataType.isDictionary(expected))
421
+ throw new Error('Dictionary function arguments require a dictionary-encoded source column');
422
+ // Dates enter as immutable parameter snapshots; physical Arrow storage uses days
423
+ // or microseconds, chosen once from the receiving schema.
424
+ const date = ast.value instanceof Date ? ast.value : undefined;
425
+ let value: ArrowExpressionValue = date
426
+ ? expected && DataType.isDate(expected)
427
+ ? Math.floor(date.getTime() / 86400000)
428
+ : BigInt(date.getTime()) * 1000n
429
+ : ast.value;
430
+ if (value instanceof Uint8Array) value = new Uint8Array(value);
431
+ if (
432
+ expected &&
433
+ DataType.isInt(expected) &&
434
+ expected.bitWidth === 64 &&
435
+ typeof value === 'number' &&
436
+ Number.isSafeInteger(value)
437
+ )
438
+ value = BigInt(value);
439
+ const type =
440
+ expected ??
441
+ (date
442
+ ? new TimestampMicrosecond('UTC')
443
+ : value instanceof Uint8Array
444
+ ? new Binary()
445
+ : value === null
446
+ ? new Null()
447
+ : typeof value === 'boolean'
448
+ ? bool
449
+ : typeof value === 'number'
450
+ ? new Float64()
451
+ : typeof value === 'bigint'
452
+ ? new Int64()
453
+ : new Utf8());
454
+ if (value === null && isTupleType(type))
455
+ return {
456
+ field: new Field('literal', type, true),
457
+ hasKernel: false,
458
+ prepare: (_batch, active) => vectorReader(nullTupleVector(type, active.length))
459
+ };
460
+ if (value === null && DataType.isList(type)) {
461
+ const dictionary = vectorFromArray([null], type);
462
+ return {
463
+ field: new Field('literal', type, true),
464
+ hasKernel: false,
465
+ prepare: (_batch, active) =>
466
+ vectorReader(
467
+ makeVector(
468
+ makeData({
469
+ type: new Dictionary(type, new Int32()),
470
+ length: active.length,
471
+ data: new Int32Array(active.length),
472
+ dictionary
473
+ })
474
+ )
475
+ )
476
+ };
477
+ }
478
+ if (value === null && isNestedType(type))
479
+ return {
480
+ field: new Field('literal', type, true),
481
+ hasKernel: false,
482
+ prepare: (_batch, active) =>
483
+ vectorReader(vectorFromArray(Array(active.length).fill(null), type))
484
+ };
485
+ validateValue(value, type);
486
+ const rounded = roundToType(type)(value);
487
+ if (typeof value === 'number' && Number.isFinite(value) && !Number.isFinite(rounded))
488
+ throw new Error(`Numeric literal overflow for ${type}`);
489
+ // A tagged UTF-8 parameter supplies physical bytes. Check the optional annotation
490
+ // against the portable value once, so edited external ASTs cannot change semantics.
491
+ const encoded =
492
+ typeof value === 'string'
493
+ ? ast.utf8 instanceof Uint8Array &&
494
+ new TextDecoder('utf-8', {ignoreBOM: true}).decode(ast.utf8) === value
495
+ ? new Uint8Array(ast.utf8)
496
+ : encoder.encode(value)
497
+ : undefined;
498
+ const range: Range | undefined = encoded ? [encoded, 0, encoded.length] : undefined;
499
+ const constant: Prepared = {
500
+ get: () => rounded,
501
+ isNull: () => value === null,
502
+ bytes: range ? () => range : undefined
503
+ };
504
+ return {
505
+ field: new Field('literal', type, value === null),
506
+ hasKernel: false,
507
+ constant,
508
+ prepare: (_batch, active) => {
509
+ if (!encoded) return constant;
510
+ let vector: Vector | undefined;
511
+ return {
512
+ ...constant,
513
+ // Comparisons only read bytes. Materialize physical UTF-8 only when a
514
+ // projection or vector function actually requests a batch-sized vector.
515
+ get vector() {
516
+ if (!vector) vector = repeatUTF8(encoded, active);
517
+ return vector;
518
+ }
519
+ };
520
+ }
521
+ };
522
+ }
523
+ if (ast.type === 'CallExpression') return bindCall(ast, options, expected);
524
+ if (ast.type === 'ConditionalExpression') {
525
+ const condition = bind(ast.test, options, bool);
526
+ requireType(condition, 'bool');
527
+ // A computed conditional produces logical values, even when passed to a vector kernel.
528
+ // Raw dictionary encodings are retained only for direct source arguments.
529
+ let yes: Node, no: Node;
530
+ if (isContextualLiteral(ast.consequent) && !isContextualLiteral(ast.alternate)) {
531
+ no = bind(ast.alternate, options, expected);
532
+ yes = bind(ast.consequent, options, no.field.type);
533
+ } else {
534
+ yes = bind(ast.consequent, options, expected);
535
+ no = bind(
536
+ ast.alternate,
537
+ options,
538
+ isContextualLiteral(ast.alternate) && !DataType.isNull(yes.field.type)
539
+ ? yes.field.type
540
+ : expected
541
+ );
542
+ if (isContextualLiteral(ast.consequent) && !DataType.isNull(no.field.type))
543
+ yes = bind(ast.consequent, options, no.field.type);
544
+ }
545
+ const tuple = isTupleType(yes.field.type);
546
+ const list = DataType.isList(yes.field.type);
547
+ const nested = isNestedType(yes.field.type);
548
+ if (nested) {
549
+ if (physicalKey(yes.field.type) !== physicalKey(no.field.type))
550
+ throw new Error('Arrow expression operand types must match');
551
+ if (
552
+ !isContextualLiteral(ast.consequent) &&
553
+ !isContextualLiteral(ast.alternate) &&
554
+ extensionKey(yes.field) !== extensionKey(no.field)
555
+ )
556
+ throw new Error('Arrow expression branch extension metadata must match');
557
+ } else sameType(yes, no);
558
+ const metadata = isContextualLiteral(ast.consequent) ? no.field.metadata : yes.field.metadata;
559
+ const field = new Field(
560
+ 'conditional',
561
+ yes.field.type,
562
+ yes.field.nullable || no.field.nullable,
563
+ metadata
564
+ );
565
+ return {
566
+ field,
567
+ hasKernel: nested || condition.hasKernel || yes.hasKernel || no.hasKernel,
568
+ prepare(batch, active, context) {
569
+ const test = condition.prepare(batch, active, context);
570
+ // A vector kernel must receive its branch mask before it executes. Pure scalar paths stay lazy.
571
+ const selected =
572
+ nested || yes.hasKernel || no.hasKernel
573
+ ? active.map((value, row) => (value && test.get(row) === true ? 1 : 0))
574
+ : undefined;
575
+ const a = yes.prepare(batch, selected ?? active, context);
576
+ const b = no.prepare(
577
+ batch,
578
+ selected ? active.map((value, row) => (value && !selected[row] ? 1 : 0)) : active,
579
+ context
580
+ );
581
+ if (list && DataType.isDictionary(a.vector!.type) && DataType.isDictionary(b.vector!.type))
582
+ return vectorReader(
583
+ selectListVectors(field.type, a.vector!, b.vector!, selected!, active)
584
+ );
585
+ if (tuple) {
586
+ const validActive = context.failed
587
+ ? active.map((value, row) => (value && !context.failed![row] ? 1 : 0))
588
+ : active;
589
+ const yesMask = validActive.map((value, row) => (value && selected![row] ? 1 : 0));
590
+ const noMask = validActive.map((value, row) => (value && !selected![row] ? 1 : 0));
591
+ validateTupleVector(a.vector!, yes.field, yesMask);
592
+ validateTupleVector(b.vector!, no.field, noMask);
593
+ return vectorReader(
594
+ selectTupleVectors(field.type, a.vector!, b.vector!, yesMask, validActive)
595
+ );
596
+ }
597
+ if (nested) {
598
+ const values = Array.from(active, (valid, row) =>
599
+ valid && !context.failed?.[row]
600
+ ? nestedValue((selected![row] ? a : b).vector!.get(row), field.type)
601
+ : null
602
+ );
603
+ return vectorReader(vectorFromArray(values, field.type));
604
+ }
605
+ const choose = (row: number) =>
606
+ (selected ? selected[row] : test.get(row) === true) ? a : b;
607
+ return {
608
+ get: row => choose(row).get(row),
609
+ isNull: row => {
610
+ const branch = choose(row);
611
+ return branch.isNull ? branch.isNull(row) : branch.get(row) === null;
612
+ },
613
+ bytes: typeKey(field.type) === 'utf8' ? row => bytes(choose(row), row) : undefined
614
+ };
615
+ }
616
+ };
617
+ }
618
+ if (ast.type === 'UnaryExpression') {
619
+ const argument = bind(ast.argument, options, ast.operator === '!' ? bool : undefined);
620
+ if (ast.operator === '!') requireType(argument, 'bool');
621
+ else if (ast.operator === '+' || ast.operator === '-') requireNumeric(argument);
622
+ else throw new Error(`Unsupported unary operator: ${ast.operator}`);
623
+ const validate = createValueValidator(argument.field.type);
624
+ const round = roundToType(argument.field.type);
625
+ return {
626
+ field: new Field('unary', argument.field.type, argument.field.nullable),
627
+ hasKernel: argument.hasKernel,
628
+ prepare(batch, active, context) {
629
+ const child = argument.prepare(batch, active, context);
630
+ return {
631
+ get: row => {
632
+ const value = child.get(row);
633
+ if (value === null) return null;
634
+ const result =
635
+ ast.operator === '!' ? !value : ast.operator === '+' ? value : -(value as any);
636
+ validate(result);
637
+ return round(result);
638
+ }
639
+ };
640
+ }
641
+ };
642
+ }
643
+ if (ast.type === 'BinaryExpression' || ast.type === 'LogicalExpression')
644
+ return bindBinary(ast, options);
645
+ throw new Error(`Unsupported Arrow expression syntax: ${ast.type}`);
646
+ }
647
+
648
+ /** Rejects implicit coercion between operands. */
649
+ function sameType(a: Node, b: Node): void {
650
+ if (typeKey(a.field.type) !== typeKey(b.field.type))
651
+ throw new Error('Arrow expression operand types must match');
652
+ }
653
+ /** Requires a particular primitive type. */
654
+ function requireType(node: Node, key: string): void {
655
+ if (typeKey(node.field.type) !== key) throw new Error(`Arrow expression requires ${key}`);
656
+ }
657
+ /** Requires a numeric primitive. */
658
+ function requireNumeric(node: Node): void {
659
+ if (!DataType.isInt(node.field.type) && !DataType.isFloat(node.field.type))
660
+ throw new Error('Arrow expression requires numeric operands');
661
+ }
662
+
663
+ /** Fuses primitive operations; only kernel boundaries require a mask prepass. */
664
+ function bindBinary(ast: any, options: BindingOptions): Node {
665
+ const op = ast.operator,
666
+ logical = op === '&&' || op === '||';
667
+ let left = bind(ast.left, options, logical ? bool : undefined),
668
+ right = bind(ast.right, options, logical ? bool : undefined);
669
+ if (!logical) {
670
+ if (isContextualLiteral(ast.left) && !DataType.isNull(right.field.type))
671
+ left = bind(ast.left, options, right.field.type);
672
+ if (isContextualLiteral(ast.right)) right = bind(ast.right, options, left.field.type);
673
+ }
674
+ sameType(left, right);
675
+ const comparison = ['==', '===', '!=', '!==', '<', '<=', '>', '>='].includes(op);
676
+ if (logical) requireType(left, 'bool');
677
+ else if (!comparison) {
678
+ if (!['+', '-', '*', '/', '%'].includes(op))
679
+ throw new Error(`Unsupported binary operator: ${op}`);
680
+ requireNumeric(left);
681
+ }
682
+ const type = left.field.type,
683
+ utf8 = typeKey(type) === 'utf8',
684
+ binary = DataType.isBinary(type) || DataType.isFixedSizeBinary(type),
685
+ integer = DataType.isInt(type);
686
+ const validate = createValueValidator(type);
687
+ const round = roundToType(type);
688
+ const field = new Field(
689
+ 'expression',
690
+ logical || comparison ? bool : type,
691
+ left.field.nullable || right.field.nullable
692
+ );
693
+ return {
694
+ field,
695
+ hasKernel: left.hasKernel || right.hasKernel,
696
+ prepare(batch, active, context) {
697
+ const a = prepareInput(left, batch, active, context, left.hasKernel || right.hasKernel);
698
+ let truth: Uint8Array | undefined;
699
+ let mask = active;
700
+ if (logical && right.hasKernel) {
701
+ truth = new Uint8Array(active.length);
702
+ mask = active.map((value, row) => {
703
+ if (!value) return 0;
704
+ const x = a.get(row);
705
+ truth![row] = x === null ? 2 : x ? 1 : 0;
706
+ return (op === '&&' ? x !== false : x !== true) ? 1 : 0;
707
+ });
708
+ }
709
+ const b = right.prepare(batch, mask, context);
710
+ return {
711
+ get: row => {
712
+ if (logical) {
713
+ const x = truth ? (truth[row] === 2 ? null : truth[row] === 1) : a.get(row);
714
+ if (op === '&&' && x === false) return false;
715
+ if (op === '||' && x === true) return true;
716
+ const y = b.get(row);
717
+ return op === '&&'
718
+ ? y === false
719
+ ? false
720
+ : x === null || y === null
721
+ ? null
722
+ : true
723
+ : y === true
724
+ ? true
725
+ : x === null || y === null
726
+ ? null
727
+ : false;
728
+ }
729
+ if (utf8) {
730
+ const x = bytes(a, row),
731
+ y = bytes(b, row);
732
+ if (!x || !y) return null;
733
+ return compare(op, compareUTF8(x[0], x[1], x[2], y[0], y[1], y[2]), 0);
734
+ }
735
+ const x = a.get(row) as any,
736
+ y = b.get(row) as any;
737
+ if (x === null || y === null) return null;
738
+ if (binary) return compare(op, compareUTF8(x, 0, x.length, y, 0, y.length), 0);
739
+ if (comparison) return compare(op, x, y);
740
+ if ((op === '/' || op === '%') && (y === 0 || y === 0n))
741
+ throw new ExpressionEvaluationError('divisionByZero', 'Division by zero');
742
+ const result =
743
+ op === '+'
744
+ ? x + y
745
+ : op === '-'
746
+ ? x - y
747
+ : op === '*'
748
+ ? x * y
749
+ : op === '/'
750
+ ? integer && typeof x === 'number'
751
+ ? Math.trunc(x / y)
752
+ : x / y
753
+ : x % y;
754
+ validate(result);
755
+ const rounded = round(result);
756
+ if (!integer && Number.isFinite(x) && Number.isFinite(y) && !Number.isFinite(rounded))
757
+ throw new ExpressionEvaluationError('overflow', 'Floating expression overflow');
758
+ return rounded;
759
+ }
760
+ };
761
+ }
762
+ };
763
+ }
764
+
765
+ /** Primitive comparisons preserve IEEE NaN behavior. */
766
+ function compare(op: string, a: any, b: any): boolean {
767
+ switch (op) {
768
+ case '==':
769
+ case '===':
770
+ return a === b;
771
+ case '!=':
772
+ case '!==':
773
+ return a !== b;
774
+ case '<':
775
+ return a < b;
776
+ case '<=':
777
+ return a <= b;
778
+ case '>':
779
+ return a > b;
780
+ case '>=':
781
+ return a >= b;
782
+ default:
783
+ throw new Error('Invalid comparison');
784
+ }
785
+ }
786
+
787
+ /** Selects broadcast list arguments without decoding their elements. */
788
+ function selectListVectors(
789
+ type: DataType,
790
+ left: Vector,
791
+ right: Vector,
792
+ selected: Mask,
793
+ active: Mask
794
+ ): Vector {
795
+ if (!DataType.isDictionary(left.type) || !DataType.isDictionary(right.type))
796
+ throw new Error('Computed List arguments require array literal branches');
797
+ const a = left.data[0]!,
798
+ b = right.data[0]!;
799
+ const leftDictionary = a.dictionary!,
800
+ rightDictionary = b.dictionary!;
801
+ const indices = new Int32Array(active.length);
802
+ const valid = new Uint8Array(active.length);
803
+ for (let row = 0; row < active.length; row++) {
804
+ if (!active[row]) continue;
805
+ if (selected[row]) {
806
+ indices[row] = Number(a.values[row]);
807
+ valid[row] = a.getValid(row) ? 1 : 0;
808
+ } else {
809
+ indices[row] = leftDictionary.length + Number(b.values[row]);
810
+ valid[row] = b.getValid(row) ? 1 : 0;
811
+ }
812
+ }
813
+ return maskTupleVector(
814
+ makeVector(
815
+ makeData({
816
+ type: new Dictionary(type, new Int32()),
817
+ length: active.length,
818
+ data: indices,
819
+ dictionary: leftDictionary.concat(rightDictionary)
820
+ })
821
+ ),
822
+ valid
823
+ );
824
+ }
825
+
826
+ /** Materializes one recovery boundary without retrying callbacks or leaking row errors outward. */
827
+ function bindRecovery(
828
+ name: string,
829
+ expressions: any[],
830
+ options: BindingOptions,
831
+ expected?: DataType
832
+ ): Node {
833
+ if (expected && DataType.isDictionary(expected))
834
+ throw new Error('Dictionary function arguments require a dictionary-encoded source column');
835
+ if (name === 'TRY' ? expressions.length < 1 || expressions.length > 2 : !expressions.length)
836
+ throw new Error(`${name} has an invalid argument count`);
837
+ const indices = expressions.map((_, index) => index);
838
+ const ordered = [
839
+ ...indices.filter(index => !isContextualLiteral(expressions[index])),
840
+ ...indices.filter(index => isContextualLiteral(expressions[index]))
841
+ ];
842
+ let anchor = 0;
843
+ let candidate: Node | undefined;
844
+ for (const index of ordered) {
845
+ const expression = expressions[index];
846
+ if (!expected && isContextualLiteral(expression) && containsContextualArray(expression))
847
+ continue;
848
+ const node = bind(expression, options, expected);
849
+ if (!candidate || !DataType.isNull(node.field.type)) {
850
+ anchor = index;
851
+ candidate = node;
852
+ }
853
+ if (!DataType.isNull(node.field.type)) break;
854
+ }
855
+ const first = candidate ?? bind(expressions[anchor], options, expected);
856
+ const nodes = expressions.map((expression, index) =>
857
+ index === anchor ? first : bind(expression, options, first.field.type)
858
+ );
859
+ for (const [index, node] of nodes.entries()) {
860
+ if (
861
+ physicalKey(node.field.type) !== physicalKey(first.field.type) ||
862
+ (!isContextualLiteral(expressions[index]) &&
863
+ extensionKey(node.field) !== extensionKey(first.field))
864
+ )
865
+ throw new Error(`${name} arguments must have matching types and metadata`);
866
+ }
867
+ const field = new Field(name.toLowerCase(), first.field.type, true, first.field.metadata);
868
+ const tuple = isTupleType(field.type);
869
+ const list = Boolean(expected && DataType.isList(expected) && DataType.isList(field.type));
870
+ if (!tuple && !list) typeKey(field.type);
871
+ return {
872
+ field,
873
+ hasKernel: true,
874
+ prepare(batch, active, context) {
875
+ const failed = new Uint8Array(active.length);
876
+ const childContext = name === 'TRY' ? {failed} : context;
877
+ const child = nodes[0]!.prepare(batch, active, childContext);
878
+ const nullable = (node: Node) =>
879
+ new Field(node.field.name, node.field.type, true, node.field.metadata);
880
+ const materialize = (node: Node, prepared: Prepared, mask: Mask): Vector =>
881
+ tuple || list
882
+ ? maskTupleVector(prepared.vector!, mask)
883
+ : output(nullable(node), mask, prepared.get);
884
+ const original = materialize(nodes[0]!, child, active);
885
+ const reader = tuple ? undefined : new ColumnReader(original);
886
+ let result = original;
887
+ let pending = active.map((value, row) =>
888
+ value &&
889
+ (name === 'TRY' ? failed[row] : tuple ? !original.isValid(row) : !reader!.isValid(row))
890
+ ? 1
891
+ : 0
892
+ );
893
+ // Mask reported errors before selecting nested fallback values.
894
+ if ((tuple || list) && name === 'TRY')
895
+ result = maskTupleVector(
896
+ result,
897
+ active.map((value, row) => (value && !failed[row] ? 1 : 0))
898
+ );
899
+ for (let index = 1; index < nodes.length && pending.some(Boolean); index++) {
900
+ const node = nodes[index]!;
901
+ const fallback = node.prepare(batch, pending, context);
902
+ const vector = materialize(node, fallback, pending);
903
+ const keep = active.map((value, row) => (value && !pending[row] ? 1 : 0));
904
+ if (tuple)
905
+ result = selectTupleVectors(field.type as FixedSizeList, result, vector, keep, active);
906
+ else if (list) result = selectListVectors(field.type, result, vector, keep, active);
907
+ else {
908
+ const a = new ColumnReader(result),
909
+ b = new ColumnReader(vector);
910
+ result = output(field, active, row => (pending[row] ? b.get(row) : a.get(row)));
911
+ }
912
+ const next = tuple ? undefined : new ColumnReader(vector);
913
+ pending = pending.map((value, row) =>
914
+ value && (tuple ? !vector.isValid(row) : !next!.isValid(row)) ? 1 : 0
915
+ );
916
+ }
917
+ return vectorReader(result);
918
+ }
919
+ };
920
+ }
921
+
922
+ /** Labels opaque WKB bytes as geometry and preserves metadata from existing WKB fields. */
923
+ function bindGeometryCast(argument: Node): Node {
924
+ const source = valueType(argument.field.type);
925
+ const metadata = new Map(argument.field.metadata);
926
+ const extension = metadata.get('ARROW:extension:name');
927
+ if (
928
+ (!DataType.isBinary(source) && !DataType.isNull(source)) ||
929
+ (extension && extension !== 'geoarrow.wkb')
930
+ )
931
+ throw new Error('GEOMETRY CAST requires Binary WKB input');
932
+ metadata.set('ARROW:extension:name', 'geoarrow.wkb');
933
+ return {
934
+ ...argument,
935
+ field: new Field('cast', new Binary(), argument.field.nullable, metadata),
936
+ prepare(batch, active, context) {
937
+ const child = argument.prepare(batch, active, context);
938
+ return {get: row => child.get(row)};
939
+ }
940
+ };
941
+ }
942
+
943
+ /** Binds a bounded IN list once, keeping the tested expression and casts as one subtree. */
944
+ function bindMembership(arguments_: any[], options: BindingOptions): Node {
945
+ if (
946
+ arguments_.length < 2 ||
947
+ arguments_.length > 4097 ||
948
+ arguments_.slice(1).some(value => value.type !== 'Literal' && !isSignedLiteral(value))
949
+ )
950
+ throw new Error('IN requires a value and 1 to 4096 scalar literals');
951
+ const argument = bind(arguments_[0], options);
952
+ const utf8 = typeKey(argument.field.type) === 'utf8';
953
+ const binary =
954
+ DataType.isBinary(argument.field.type) || DataType.isFixedSizeBinary(argument.field.type);
955
+ const literals = arguments_.slice(1).map(value => bind(value, options, argument.field.type));
956
+ // Every membership item is a scalar literal: convert and index once at compilation.
957
+ const prepared = literals.map(value => value.constant!);
958
+ const values = new Set(prepared.map(value => value.get(0)));
959
+ const ranges: Range[] = utf8
960
+ ? prepared.map(value => bytes(value, 0)).filter((range): range is Range => range !== null)
961
+ : binary
962
+ ? prepared.flatMap(value => {
963
+ const data = value.get(0) as Uint8Array | null;
964
+ return data === null ? [] : [[data, 0, data.length] as Range];
965
+ })
966
+ : [];
967
+ ranges.sort((a, b) => compareUTF8(a[0], a[1], a[2], b[0], b[1], b[2]));
968
+ return {
969
+ field: new Field(
970
+ 'in',
971
+ bool,
972
+ argument.field.nullable || literals.some(value => value.field.nullable)
973
+ ),
974
+ hasKernel: argument.hasKernel,
975
+ prepare(batch, active, context) {
976
+ const source = argument.prepare(batch, active, context);
977
+ return {
978
+ get(row) {
979
+ if (utf8 || binary) {
980
+ const data = binary ? (source.get(row) as Uint8Array | null) : null;
981
+ const value: Range | null = utf8
982
+ ? bytes(source, row)
983
+ : data === null
984
+ ? null
985
+ : [data, 0, data.length];
986
+ if (!value) return null;
987
+ if (containsByteRange(ranges, value)) return true;
988
+ } else {
989
+ const value = source.get(row);
990
+ if (value === null) return null;
991
+ if (!Number.isNaN(value) && values.has(value)) return true;
992
+ }
993
+ return values.has(null) ? null : false;
994
+ }
995
+ };
996
+ }
997
+ };
998
+ }
999
+
1000
+ /** Broadcasts pre-encoded text to Arrow storage without re-encoding strings per row. */
1001
+ function repeatUTF8(encoded: Uint8Array, active: Mask): Vector<Utf8> {
1002
+ const count = active.reduce((sum, value) => sum + value, 0);
1003
+ const data = new Uint8Array(count * encoded.length);
1004
+ const offsets = new Int32Array(active.length + 1);
1005
+ const validity = new Uint8Array(Math.ceil(active.length / 8));
1006
+ let position = 0;
1007
+ for (let row = 0; row < active.length; row++) {
1008
+ if (active[row]) {
1009
+ data.set(encoded, position);
1010
+ position += encoded.length;
1011
+ validity[row >> 3] |= 1 << (row & 7);
1012
+ }
1013
+ offsets[row + 1] = position;
1014
+ }
1015
+ return makeVector(
1016
+ makeData({
1017
+ type: new Utf8(),
1018
+ length: active.length,
1019
+ data,
1020
+ valueOffsets: offsets,
1021
+ nullBitmap: validity,
1022
+ nullCount: active.length - count
1023
+ })
1024
+ );
1025
+ }
1026
+
1027
+ /** Searches pre-sorted UTF-8 or binary constants without decoding source values. */
1028
+ function containsByteRange(ranges: readonly Range[], value: Range): boolean {
1029
+ let low = 0;
1030
+ let high = ranges.length - 1;
1031
+ while (low <= high) {
1032
+ const middle = (low + high) >>> 1;
1033
+ const candidate = ranges[middle]!;
1034
+ const order = compareUTF8(
1035
+ value[0],
1036
+ value[1],
1037
+ value[2],
1038
+ candidate[0],
1039
+ candidate[1],
1040
+ candidate[2]
1041
+ );
1042
+ if (order === 0) return true;
1043
+ if (order < 0) high = middle - 1;
1044
+ else low = middle + 1;
1045
+ }
1046
+ return false;
1047
+ }
1048
+
1049
+ /** Binds SQL pattern matching and precompiles literal patterns. */
1050
+ function bindLike(args: any[], options: BindingOptions, insensitive: boolean): Node {
1051
+ if (args.length < 2 || args.length > 3) throw new Error('LIKE requires two or three arguments');
1052
+ const value = bind(args[0], options, new Utf8());
1053
+ const pattern = bind(args[1], options, new Utf8());
1054
+ requireType(value, 'utf8');
1055
+ requireType(pattern, 'utf8');
1056
+ const escape = args[2];
1057
+ if (escape && (escape.type !== 'Literal' || typeof escape.value !== 'string')) {
1058
+ throw new Error('LIKE ESCAPE requires a literal character');
1059
+ }
1060
+ const compile = (text: string) => compileUTF8Like(text, insensitive, escape?.value);
1061
+ const literal = args[1].type === 'Literal' && typeof args[1].value === 'string';
1062
+ const matcher = literal ? compile(args[1].value) : undefined;
1063
+ return {
1064
+ field: new Field('like', bool, value.field.nullable || pattern.field.nullable),
1065
+ hasKernel: value.hasKernel || pattern.hasKernel,
1066
+ prepare(batch, active, context) {
1067
+ const source = value.prepare(batch, active, context);
1068
+ const patterns = pattern.prepare(batch, active, context);
1069
+ return {
1070
+ get(row) {
1071
+ const range = bytes(source, row);
1072
+ const text = patterns.get(row) as string | null;
1073
+ if (!range || text === null) return null;
1074
+ return (matcher || compile(text))(...range);
1075
+ }
1076
+ };
1077
+ }
1078
+ };
1079
+ }
1080
+
1081
+ /** Converts a number to a byte without typed-array wraparound. */
1082
+ function convertByte(value: number, normalized: boolean): number {
1083
+ if (!Number.isFinite(value))
1084
+ throw new ExpressionEvaluationError('conversion', 'Byte conversion requires a finite number');
1085
+ if (normalized) {
1086
+ if (value < 0 || value > 1)
1087
+ throw new ExpressionEvaluationError('domain', 'PACK_UNORM8 requires values in [0, 1]');
1088
+ return Math.round(value * 255);
1089
+ }
1090
+ const integer = Math.trunc(value);
1091
+ if (integer < 0 || integer > 255)
1092
+ throw new ExpressionEvaluationError('overflow', 'UINT8 cast overflow');
1093
+ return integer;
1094
+ }
1095
+
1096
+ /** Packs fixed-size numeric tuples directly from child buffers, including sliced inputs. */
1097
+ function bindPackUnorm8(arguments_: any[], options: BindingOptions): Node {
1098
+ if (arguments_.length !== 1) throw new Error('PACK_UNORM8 requires one fixed-size numeric array');
1099
+ const argument = bind(arguments_[0], options, undefined, true);
1100
+ const inputType = argument.field.type;
1101
+ if (!DataType.isFixedSizeList(inputType) || !inputType.listSize || inputType.listSize > 4096)
1102
+ throw new Error('PACK_UNORM8 requires a fixed-size numeric array of 1 to 4096 components');
1103
+ const width = inputType.listSize;
1104
+ const child = inputType.children[0]!;
1105
+ if (!DataType.isInt(valueType(child.type)) && !DataType.isFloat(valueType(child.type)))
1106
+ throw new Error('PACK_UNORM8 requires numeric components');
1107
+ const type = new FixedSizeList(width, new Field('value', new Uint8(), false));
1108
+ const field = new Field('pack_unorm8', type, argument.field.nullable || child.nullable);
1109
+ return {
1110
+ field,
1111
+ hasKernel: true,
1112
+ prepare(batch, active, context) {
1113
+ const input = argument.prepare(batch, active, context).vector!;
1114
+ const parent = new ColumnReader(input);
1115
+ const components = new ColumnReader(input.getChildAt(0)!);
1116
+ const result = nullTupleVector(type, active.length);
1117
+ const data = result.data[0]!;
1118
+ const bytes = data.children[0]!.values as Uint8Array;
1119
+ const rowValues = new Float64Array(width);
1120
+ for (let row = 0; row < active.length; row++) {
1121
+ if (!active[row] || context.failed?.[row] || !parent.isValid(row)) continue;
1122
+ const start = row * width;
1123
+ let valid = true;
1124
+ for (let component = 0; component < width; component++) {
1125
+ const value = components.get(start + component);
1126
+ if (value === null) {
1127
+ valid = false;
1128
+ break;
1129
+ }
1130
+ rowValues[component] = Number(value);
1131
+ }
1132
+ if (!valid) continue;
1133
+ try {
1134
+ for (let component = 0; component < width; component++)
1135
+ bytes[start + component] = convertByte(rowValues[component]!, true);
1136
+ } catch (error) {
1137
+ if (!context.failed || !isExpressionEvaluationError(error)) throw error;
1138
+ context.failed[row] = 1;
1139
+ bytes.fill(0, start, start + width);
1140
+ continue;
1141
+ }
1142
+ data.setValid(row, true);
1143
+ }
1144
+ return vectorReader(result);
1145
+ }
1146
+ };
1147
+ }
1148
+
1149
+ /** Identifies the Arrow layouts that can be traversed with nested extraction. */
1150
+ function isNestedType(type: DataType): boolean {
1151
+ return DataType.isStruct(type) || DataType.isList(type) || DataType.isFixedSizeList(type);
1152
+ }
1153
+
1154
+ /** Converts nested Arrow values to builder inputs while preserving scalar values. */
1155
+ function nestedValue(value: any, type: DataType): unknown {
1156
+ if (value == null) return null;
1157
+ if (DataType.isList(type) || DataType.isFixedSizeList(type))
1158
+ return Array.from(value as Vector, item => nestedValue(item, type.valueType));
1159
+ if (DataType.isStruct(type))
1160
+ return Object.fromEntries(
1161
+ type.children.map(field => [field.name, nestedValue(value[field.name], field.type)])
1162
+ );
1163
+ return value;
1164
+ }
1165
+
1166
+ /** Masks nested results without coercing their child types. */
1167
+ function nestedVector(vector: Vector, type: DataType, active: Mask): Vector {
1168
+ if (!active.includes(0)) return vector;
1169
+ return vectorFromArray(
1170
+ Array.from(active, (valid, row) => (valid ? nestedValue(vector.get(row), type) : null)),
1171
+ type
1172
+ );
1173
+ }
1174
+
1175
+ /** Binds list indexing and named struct access against the input Arrow types. */
1176
+ function bindNestedExtract(
1177
+ name: 'LIST_EXTRACT' | 'STRUCT_EXTRACT',
1178
+ args: readonly Expression[],
1179
+ options: BindingOptions
1180
+ ): Node {
1181
+ if (args.length !== 2) throw new Error(`${name} requires two arguments`);
1182
+ const input = bind(args[0], options, undefined, true);
1183
+ const inputType = input.field.type;
1184
+ const selector = args[1]!;
1185
+ let child: Field;
1186
+ let index: Node | undefined;
1187
+
1188
+ if (name === 'LIST_EXTRACT') {
1189
+ if (!DataType.isList(inputType) && !DataType.isFixedSizeList(inputType))
1190
+ throw new Error('LIST_EXTRACT requires an Arrow List or FixedSizeList');
1191
+ child = inputType.children[0]!;
1192
+ index = bind(selector, options);
1193
+ if (
1194
+ !DataType.isInt(index.field.type) &&
1195
+ !DataType.isFloat(index.field.type) &&
1196
+ !DataType.isNull(index.field.type)
1197
+ )
1198
+ throw new Error('LIST_EXTRACT requires an integer index');
1199
+ } else {
1200
+ if (!DataType.isStruct(inputType)) throw new Error('STRUCT_EXTRACT requires an Arrow Struct');
1201
+ if (selector.type !== 'Literal' || typeof selector.value !== 'string')
1202
+ throw new Error('STRUCT_EXTRACT requires a literal field name');
1203
+ const field = inputType.children.find(candidate => candidate.name === selector.value);
1204
+ if (!field) throw new Error(`Unknown Arrow struct field: ${selector.value}`);
1205
+ child = field;
1206
+ }
1207
+ const field = new Field(child.name, valueType(child.type), true, child.metadata);
1208
+ return {
1209
+ field,
1210
+ hasKernel: true,
1211
+ prepare(batch, active, context) {
1212
+ const inputValues = input.prepare(batch, active, context).vector!;
1213
+ const positions = index?.prepare(batch, active, context);
1214
+ const childValues = index ? undefined : inputValues.getChild(child.name)!;
1215
+ const values = Array.from(active, (valid, row) => {
1216
+ if (!valid || !inputValues.isValid(row)) return null;
1217
+ if (!positions) return nestedValue(childValues!.get(row), field.type);
1218
+
1219
+ const position = positions.get(row);
1220
+ if (position === null) return null;
1221
+ const offset = Number(position);
1222
+ if (!Number.isSafeInteger(offset)) return null;
1223
+ const list = inputValues.get(row) as Vector;
1224
+ const element = offset < 0 ? list.length + offset : offset - 1;
1225
+ return element >= 0 && element < list.length
1226
+ ? nestedValue(list.get(element), field.type)
1227
+ : null;
1228
+ });
1229
+ return vectorReader(vectorFromArray(values, field.type));
1230
+ }
1231
+ };
1232
+ }
1233
+
1234
+ /** Binds built-ins and custom functions, materializing arguments only for vector kernels. */
1235
+ function bindCall(ast: any, options: BindingOptions, expected?: DataType): Node {
1236
+ if (ast.callee.type !== 'Identifier')
1237
+ throw new Error('Only registered named function calls are supported');
1238
+ let name = ast.callee.name;
1239
+ const recovery = recoveryName(ast);
1240
+ if (recovery) return bindRecovery(recovery, ast.arguments, options, expected);
1241
+ if (ast.sqlFunction) {
1242
+ const matches = [
1243
+ ...options.functionLookup.keys(),
1244
+ 'array',
1245
+ 'array_float16',
1246
+ 'array_float32',
1247
+ 'array_float64',
1248
+ 'array_uint8',
1249
+ 'PACK_UNORM8',
1250
+ 'EPOCH_MS',
1251
+ 'LIST_EXTRACT',
1252
+ 'STRUCT_EXTRACT',
1253
+ 'cast',
1254
+ 'like',
1255
+ 'ilike',
1256
+ 'concat',
1257
+ 'concatStrict',
1258
+ 'upper',
1259
+ 'lower',
1260
+ 'capitalize',
1261
+ 'isNull',
1262
+ 'isNotNull',
1263
+ 'parseNumber',
1264
+ 'parseBigInt',
1265
+ 'parseBoolean',
1266
+ 'toFloat64',
1267
+ 'toInt32',
1268
+ 'toInt64'
1269
+ ].filter(key => key.toUpperCase() === name.toUpperCase());
1270
+ if (matches.length > 1) throw new Error(`Ambiguous SQL function: ${name}`);
1271
+ name = matches[0] ?? name;
1272
+ }
1273
+ if (name === 'LIST_EXTRACT' || name === 'STRUCT_EXTRACT')
1274
+ return bindNestedExtract(name, ast.arguments, options);
1275
+ if (name === 'PACK_UNORM8') return bindPackUnorm8(ast.arguments, options);
1276
+ if (['array', 'array_float16', 'array_float32', 'array_float64', 'array_uint8'].includes(name)) {
1277
+ if (!ast.arguments.length || ast.arguments.length > 4096)
1278
+ throw new Error('ARRAY requires 1 to 4096 numeric expressions');
1279
+ const arguments_ = ast.arguments.map((value: any) => bind(value, options)) as Node[];
1280
+ if (
1281
+ arguments_.some(
1282
+ value =>
1283
+ !DataType.isFloat(valueType(value.field.type)) &&
1284
+ !DataType.isInt(valueType(value.field.type))
1285
+ )
1286
+ )
1287
+ throw new Error('ARRAY requires numeric expressions');
1288
+ const component =
1289
+ name === 'array_uint8'
1290
+ ? new Uint8()
1291
+ : name === 'array_float16'
1292
+ ? new Float16()
1293
+ : name === 'array_float32'
1294
+ ? new Float32()
1295
+ : name === 'array_float64' ||
1296
+ arguments_.every(value => DataType.isInt(valueType(value.field.type))) ||
1297
+ arguments_.some(value => typeKey(value.field.type) === 'f2')
1298
+ ? new Float64()
1299
+ : arguments_.some(value => typeKey(value.field.type) === 'f1')
1300
+ ? new Float32()
1301
+ : new Float16();
1302
+ const type = new FixedSizeList(arguments_.length, new Field('value', component, false));
1303
+ const field = new Field(
1304
+ 'array',
1305
+ type,
1306
+ arguments_.some(value => value.field.nullable)
1307
+ );
1308
+ return {
1309
+ field,
1310
+ hasKernel: true,
1311
+ prepare(batch, active, context) {
1312
+ const values = arguments_.map(value =>
1313
+ prepareInput(
1314
+ value,
1315
+ batch,
1316
+ active,
1317
+ context,
1318
+ arguments_.some(argument => argument.hasKernel)
1319
+ )
1320
+ );
1321
+ const vector = nullTupleVector(type, active.length),
1322
+ data = vector.data[0]!,
1323
+ output =
1324
+ DataType.isFloat(component) && component.precision === Precision.HALF
1325
+ ? float16Values(data.children[0]!.values as Uint16Array)
1326
+ : data.children[0]!.values;
1327
+ const rowValues: (number | bigint | null)[] = new Array(values.length);
1328
+ for (let row = 0; row < active.length; row++) {
1329
+ if (!active[row]) continue;
1330
+ for (let column = 0; column < values.length; column++)
1331
+ rowValues[column] = values[column]!.get(row) as number | bigint | null;
1332
+ if (rowValues.some(value => value === null)) continue;
1333
+ try {
1334
+ for (let column = 0; column < values.length; column++) {
1335
+ const index = row * values.length + column;
1336
+ const value = Number(rowValues[column]);
1337
+ output[index] = name === 'array_uint8' ? convertByte(value, false) : value;
1338
+ if (Number.isFinite(value) && !Number.isFinite(output[index]))
1339
+ throw new ExpressionEvaluationError('overflow', 'ARRAY cast overflow');
1340
+ }
1341
+ } catch (error) {
1342
+ if (!context.failed || !isExpressionEvaluationError(error)) throw error;
1343
+ context.failed[row] = 1;
1344
+ output.fill(0, row * values.length, (row + 1) * values.length);
1345
+ continue;
1346
+ }
1347
+ data.setValid(row, true);
1348
+ }
1349
+ return vectorReader(vector);
1350
+ }
1351
+ };
1352
+ }
1353
+ if (name === 'like' || name === 'ilike')
1354
+ return bindLike(ast.arguments, options, name === 'ilike');
1355
+ if (name === 'upper' || name === 'lower' || name === 'capitalize') {
1356
+ if (ast.arguments.length !== 1) throw new Error('Case conversion requires one argument');
1357
+ const arg = bind(ast.arguments[0], options, new Utf8());
1358
+ requireType(arg, 'utf8');
1359
+ return {
1360
+ field: new Field(name, new Utf8(), arg.field.nullable),
1361
+ hasKernel: arg.hasKernel,
1362
+ prepare(batch, active, context) {
1363
+ const input = arg.prepare(batch, active, context);
1364
+ return {
1365
+ get(row) {
1366
+ const value = input.get(row) as string | null;
1367
+ if (!value) return value;
1368
+ if (name === 'upper') return value.toUpperCase();
1369
+ if (name === 'lower') return value.toLowerCase();
1370
+ const first = String.fromCodePoint(value.codePointAt(0)!);
1371
+ return first.toUpperCase() + value.slice(first.length);
1372
+ }
1373
+ };
1374
+ }
1375
+ };
1376
+ }
1377
+ if (name === 'concat' || name === 'concatStrict') {
1378
+ if (!ast.arguments.length) throw new Error('CONCAT requires at least one argument');
1379
+ const args = ast.arguments.map((arg: any) => bind(arg, options, new Utf8()));
1380
+ for (const arg of args) requireType(arg, 'utf8');
1381
+ const strict = name === 'concatStrict';
1382
+ return {
1383
+ field: new Field(
1384
+ 'concat',
1385
+ new Utf8(),
1386
+ strict && args.some((arg: Node) => arg.field.nullable)
1387
+ ),
1388
+ hasKernel: args.some((arg: Node) => arg.hasKernel),
1389
+ prepare(batch, active, context) {
1390
+ const inputs = args.map((arg: Node) => arg.prepare(batch, active, context));
1391
+ return {
1392
+ get(row) {
1393
+ let result = '';
1394
+ for (const input of inputs) {
1395
+ const value = input.get(row);
1396
+ if (value === null && strict) return null;
1397
+ if (value !== null) result += value;
1398
+ }
1399
+ return result;
1400
+ }
1401
+ };
1402
+ }
1403
+ };
1404
+ }
1405
+ if (name === 'in') return bindMembership(ast.arguments, options);
1406
+ if (name === 'EPOCH_MS') {
1407
+ if (ast.arguments.length !== 1) throw new Error('EPOCH_MS requires one argument');
1408
+ const argument = bind(ast.arguments[0], options);
1409
+ const key = typeKey(argument.field.type);
1410
+ if (key !== 'date32' && !key.startsWith('timestamp_us:')) {
1411
+ throw new Error('EPOCH_MS requires DATE or microsecond TIMESTAMP');
1412
+ }
1413
+ return {
1414
+ field: new Field('epoch_ms', new Float64(), argument.field.nullable),
1415
+ hasKernel: argument.hasKernel,
1416
+ prepare(batch, active, context) {
1417
+ const input = argument.prepare(batch, active, context);
1418
+ return {
1419
+ get(row) {
1420
+ const value = input.get(row);
1421
+ if (value === null) return null;
1422
+ // Divide before conversion to retain submillisecond precision around the epoch.
1423
+ return key === 'date32'
1424
+ ? Number(value) * 86400000
1425
+ : Number((value as bigint) / 1000n) + Number((value as bigint) % 1000n) / 1000;
1426
+ }
1427
+ };
1428
+ }
1429
+ };
1430
+ }
1431
+ if (name === 'cast') {
1432
+ if (ast.arguments.length !== 2 || ast.arguments[1]?.type !== 'Literal')
1433
+ throw new Error('cast requires a value and a literal scalar target');
1434
+ const argument = bind(ast.arguments[0], options);
1435
+ const target = ast.arguments[1].value;
1436
+ if (target === 'geometry') return bindGeometryCast(argument);
1437
+ const cast = bindCast(argument.field.type, target);
1438
+ return {
1439
+ field: new Field('cast', cast.type, argument.field.nullable),
1440
+ hasKernel: argument.hasKernel,
1441
+ prepare(batch, active, context) {
1442
+ const child = argument.prepare(batch, active, context);
1443
+ return {
1444
+ get: row =>
1445
+ cast.textInput && !DataType.isUtf8(valueType(cast.type))
1446
+ ? cast.evaluate(null, bytes(child, row))
1447
+ : cast.evaluate(child.get(row))
1448
+ };
1449
+ }
1450
+ };
1451
+ }
1452
+ const conversion = ['toFloat64', 'toInt32', 'toInt64'].includes(name);
1453
+ const nullTest = name === 'isNull' || name === 'isNotNull';
1454
+ if (conversion || nullTest || ['parseNumber', 'parseBigInt', 'parseBoolean'].includes(name)) {
1455
+ if (ast.arguments.length !== 1) throw new Error(`${name} requires one argument`);
1456
+ const argument = bind(ast.arguments[0], options);
1457
+ if (conversion) requireNumeric(argument);
1458
+ else if (!nullTest) requireType(argument, 'utf8');
1459
+ const type =
1460
+ name === 'parseNumber' || name === 'toFloat64'
1461
+ ? new Float64()
1462
+ : name === 'toInt32'
1463
+ ? new Int32()
1464
+ : name === 'parseBigInt' || name === 'toInt64'
1465
+ ? new Int64()
1466
+ : bool;
1467
+ const validate = createValueValidator(type);
1468
+ const round = roundToType(type);
1469
+ const field = new Field(name, type, conversion ? argument.field.nullable : !nullTest);
1470
+ return {
1471
+ field,
1472
+ hasKernel: argument.hasKernel,
1473
+ prepare(batch, active, context) {
1474
+ const child = argument.prepare(batch, active, context);
1475
+ return {
1476
+ get: row => {
1477
+ if (nullTest) {
1478
+ const missing = child.isNull ? child.isNull(row) : child.get(row) === null;
1479
+ return name === 'isNull' ? missing : !missing;
1480
+ }
1481
+ if (conversion) {
1482
+ const value = child.get(row);
1483
+ if (value === null) return null;
1484
+ if (name === 'toInt64' && typeof value === 'number' && !Number.isInteger(value))
1485
+ throw new ExpressionEvaluationError(
1486
+ 'conversion',
1487
+ 'Int64 conversion requires a finite integer'
1488
+ );
1489
+ const result = name === 'toInt64' ? BigInt(value as number | bigint) : Number(value);
1490
+ validate(result);
1491
+ return result;
1492
+ }
1493
+ const range = bytes(child, row);
1494
+ if (!range) return null;
1495
+ const [buffer, start, end] = range;
1496
+ const result =
1497
+ (name === 'parseNumber'
1498
+ ? parseUTF8Number(buffer, start, end)
1499
+ : name === 'parseBigInt'
1500
+ ? parseUTF8BigInt(buffer, start, end)
1501
+ : parseUTF8Boolean(buffer, start, end)) ?? null;
1502
+ validate(result);
1503
+ return round(result);
1504
+ }
1505
+ };
1506
+ }
1507
+ };
1508
+ }
1509
+ const group = options.functionLookup.get(name);
1510
+ if (!group) throw new Error(`Unknown Arrow function: ${name}`);
1511
+ const inferred = ast.arguments.map((argument: any) =>
1512
+ needsArgumentContext(argument) ? undefined : bind(argument, options, undefined, true)
1513
+ ) as (Node | undefined)[];
1514
+ const candidates: {prototype: ArrowTableFunctionPrototype; arguments: Node[]; cost: number}[] =
1515
+ [];
1516
+ const allLiteralArguments = ast.arguments.every(isContextualLiteral);
1517
+ let contextualError: unknown;
1518
+ for (const prototype of group.prototypes) {
1519
+ if (ast.arguments.length !== prototype.arguments.length) continue;
1520
+ let cost = 0;
1521
+ const arguments_: Node[] = [];
1522
+ let compatible = true;
1523
+ for (let index = 0; index < ast.arguments.length; index++) {
1524
+ const argument = ast.arguments[index],
1525
+ field = prototype.arguments[index]!,
1526
+ source = inferred[index];
1527
+ let bound: Node;
1528
+ if (isContextualLiteral(argument) || !source) {
1529
+ try {
1530
+ bound = bind(argument, options, field.type, !prototype.evaluateScalar);
1531
+ } catch (error) {
1532
+ contextualError = error;
1533
+ compatible = false;
1534
+ break;
1535
+ }
1536
+ if (
1537
+ source &&
1538
+ allLiteralArguments &&
1539
+ physicalKey(valueType(source.field.type)) !== physicalKey(field.type)
1540
+ )
1541
+ cost += 4;
1542
+ } else {
1543
+ bound = source!;
1544
+ }
1545
+ // Contextual binding can retain a column's physical type (for example
1546
+ // flag ? intColumn : null). Validate it just like an inferred argument.
1547
+ const sourceType = valueType(bound.field.type);
1548
+ if (DataType.isDictionary(bound.field.type) && !DataType.isDictionary(field.type)) cost += 1;
1549
+ if (
1550
+ physicalKey(DataType.isDictionary(field.type) ? bound.field.type : sourceType) !==
1551
+ physicalKey(field.type)
1552
+ ) {
1553
+ if (
1554
+ DataType.isFloat(sourceType) &&
1555
+ DataType.isFloat(field.type) &&
1556
+ sourceType.precision < field.type.precision
1557
+ ) {
1558
+ cost += field.type.precision - sourceType.precision;
1559
+ const child = bound,
1560
+ round = roundToType(field.type);
1561
+ bound = {
1562
+ field: new Field(
1563
+ child.field.name,
1564
+ field.type,
1565
+ child.field.nullable,
1566
+ child.field.metadata
1567
+ ),
1568
+ hasKernel: child.hasKernel,
1569
+ prepare(batch, active, context) {
1570
+ const prepared = child.prepare(batch, active, context);
1571
+ return {get: row => round(prepared.get(row))};
1572
+ }
1573
+ };
1574
+ } else {
1575
+ compatible = false;
1576
+ break;
1577
+ }
1578
+ }
1579
+ if (
1580
+ [...field.metadata].some(([key, value]) => bound.field.metadata.get(key) !== value) ||
1581
+ (prototype.nullHandling === 'call' && bound.field.nullable && !field.nullable)
1582
+ ) {
1583
+ compatible = false;
1584
+ break;
1585
+ }
1586
+ arguments_.push(bound);
1587
+ }
1588
+ if (compatible) candidates.push({prototype, arguments: arguments_, cost});
1589
+ }
1590
+ const untypedNumeric = (value: any): boolean =>
1591
+ (value.type === 'Literal' && (value.value === null || typeof value.value === 'number')) ||
1592
+ isSignedLiteral(value) ||
1593
+ Boolean(recoveryName(value) && value.arguments.every(untypedNumeric)) ||
1594
+ (value.type === 'ConditionalExpression' &&
1595
+ untypedNumeric(value.consequent) &&
1596
+ untypedNumeric(value.alternate));
1597
+ const allFloat64 = (prototype: ArrowTableFunctionPrototype) =>
1598
+ prototype.arguments.every(
1599
+ field => DataType.isFloat(field.type) && field.type.precision === Precision.DOUBLE
1600
+ );
1601
+ if (
1602
+ ast.arguments.every(untypedNumeric) &&
1603
+ candidates.every(candidate =>
1604
+ candidate.prototype.arguments.every(
1605
+ field => DataType.isInt(field.type) || DataType.isFloat(field.type)
1606
+ )
1607
+ ) &&
1608
+ candidates.some(candidate => allFloat64(candidate.prototype))
1609
+ ) {
1610
+ for (const candidate of candidates) if (!allFloat64(candidate.prototype)) candidate.cost++;
1611
+ }
1612
+ candidates.sort((a, b) => a.cost - b.cost);
1613
+ if (!candidates.length && group.prototypes.length === 1 && contextualError) throw contextualError;
1614
+ if (!candidates.length)
1615
+ throw new Error(`Argument type mismatch or wrong argument count for ${name}`);
1616
+ if (candidates[1]?.cost === candidates[0]!.cost)
1617
+ throw new Error(`Ambiguous Arrow function call: ${name}`);
1618
+ const declaration = candidates[0]!.prototype;
1619
+ const arguments_ = candidates[0]!.arguments;
1620
+ const evaluateVector = declaration.evaluateScalar ? undefined : declaration.evaluate;
1621
+ const result = declaration.result;
1622
+ const tuple = isTupleType(result.type);
1623
+ if (tuple && declaration.evaluateScalar)
1624
+ throw new Error('Fixed-size list results require a vector-only function');
1625
+ if (declaration.evaluateScalar) for (const argument of arguments_) typeKey(argument.field.type);
1626
+ if (!tuple) typeKey(result.type);
1627
+ const validate = tuple ? undefined : createValueValidator(result.type);
1628
+ const round = tuple ? undefined : roundToType(result.type);
1629
+ const field = new Field(
1630
+ result.name,
1631
+ valueType(result.type),
1632
+ result.nullable ||
1633
+ (declaration.nullHandling !== 'call' && arguments_.some(argument => argument.field.nullable)),
1634
+ result.metadata
1635
+ );
1636
+ return {
1637
+ field,
1638
+ hasKernel: Boolean(evaluateVector) || arguments_.some(argument => argument.hasKernel),
1639
+ prepare(batch, active, context) {
1640
+ const children = arguments_.map(argument =>
1641
+ prepareInput(
1642
+ argument,
1643
+ batch,
1644
+ active,
1645
+ context,
1646
+ Boolean(evaluateVector) || arguments_.some(value => value.hasKernel)
1647
+ )
1648
+ );
1649
+ let kernel: Prepared | undefined;
1650
+ let mask = active;
1651
+ if (evaluateVector && active.some(Boolean)) {
1652
+ const vectors = children.map(
1653
+ (child, index) =>
1654
+ child.vector ??
1655
+ output(
1656
+ arguments_[index]!.field,
1657
+ context.failed
1658
+ ? active.map((value, row) => (value && !context.failed![row] ? 1 : 0))
1659
+ : active,
1660
+ child.get
1661
+ )
1662
+ );
1663
+ const readers = vectors.map(vector => new ColumnReader(vector));
1664
+ mask = active.map((value, row) =>
1665
+ value &&
1666
+ !context.failed?.[row] &&
1667
+ (declaration.nullHandling === 'call' || readers.every(reader => reader.isValid(row)))
1668
+ ? 1
1669
+ : 0
1670
+ );
1671
+ if (mask.some(Boolean)) {
1672
+ const vector = evaluateVector(vectors, {
1673
+ activeRows: mask,
1674
+ length: active.length,
1675
+ reportError(row, error) {
1676
+ if (!Number.isInteger(row) || row < 0 || row >= active.length || !mask[row])
1677
+ throw new Error('Kernel reported an inactive or invalid row');
1678
+ if (!context.failed || !isExpressionEvaluationError(error)) throw error;
1679
+ context.failed[row] = 1;
1680
+ mask[row] = 0;
1681
+ }
1682
+ });
1683
+ if (
1684
+ vector.length !== active.length ||
1685
+ (tuple
1686
+ ? physicalKey(vector.type) !== physicalKey(result.type)
1687
+ : typeKey(vector.type) !== typeKey(result.type))
1688
+ )
1689
+ throw new Error(`Invalid kernel result for ${name}`);
1690
+ if (tuple) {
1691
+ validateTupleVector(vector, result, mask);
1692
+ return vectorReader(maskTupleVector(vector, mask));
1693
+ }
1694
+ kernel = sourceReader(vector);
1695
+ }
1696
+ }
1697
+ if (isTupleType(result.type))
1698
+ return vectorReader(nullTupleVector(result.type, active.length));
1699
+ return {
1700
+ get: row => {
1701
+ let value: ArrowExpressionValue;
1702
+ if (evaluateVector) {
1703
+ if (!mask[row] || !kernel) return null;
1704
+ value = kernel.get(row);
1705
+ } else {
1706
+ const args = children.map(child => child.get(row));
1707
+ if (context.failed?.[row]) return null;
1708
+ if (declaration.nullHandling !== 'call' && args.some(value => value === null))
1709
+ return null;
1710
+ value = declaration.evaluateScalar!(...args);
1711
+ }
1712
+ if (value === null && !result.nullable)
1713
+ throw new Error(`Function ${name} returned null for a non-nullable result`);
1714
+ validate!(value);
1715
+ return round!(value);
1716
+ }
1717
+ };
1718
+ }
1719
+ };
1720
+ }
1721
+
1722
+ /** Preserve declared Float32 precision at fused operation boundaries. */
1723
+ function roundToType(type: DataType): (value: ArrowExpressionValue) => ArrowExpressionValue {
1724
+ if (typeKey(type) === 'f0') {
1725
+ const round = roundFloat16();
1726
+ return value => (value === null ? null : round(value as number));
1727
+ }
1728
+ return typeKey(type) === 'f1'
1729
+ ? value => (value === null ? null : Math.fround(value as number))
1730
+ : value => value;
1731
+ }
1732
+
1733
+ /** A signed number is one literal, including the negative limit of a signed integer. */
1734
+ function isSignedLiteral(ast: any): boolean {
1735
+ return (
1736
+ ast.type === 'UnaryExpression' &&
1737
+ (ast.operator === '+' || ast.operator === '-') &&
1738
+ ast.argument.type === 'Literal' &&
1739
+ typeof ast.argument.value === 'number'
1740
+ );
1741
+ }
1742
+ function recoveryName(ast: any): 'TRY' | 'COALESCE' | undefined {
1743
+ if (ast.type !== 'CallExpression' || ast.callee.type !== 'Identifier') return undefined;
1744
+ const name = ast.sqlFunction ? ast.callee.name.toUpperCase() : ast.callee.name;
1745
+ return name === 'TRY' || name === 'COALESCE' ? name : undefined;
1746
+ }
1747
+
1748
+ function containsContextualArray(ast: any): boolean {
1749
+ return (
1750
+ ast.type === 'ArrayExpression' ||
1751
+ (ast.type === 'ConditionalExpression' &&
1752
+ (containsContextualArray(ast.consequent) || containsContextualArray(ast.alternate))) ||
1753
+ Boolean(recoveryName(ast) && ast.arguments.some(containsContextualArray))
1754
+ );
1755
+ }
1756
+
1757
+ function isContextualLiteral(ast: any): boolean {
1758
+ return (
1759
+ ast.type === 'Literal' ||
1760
+ ast.type === 'ArrayExpression' ||
1761
+ isSignedLiteral(ast) ||
1762
+ Boolean(recoveryName(ast) && ast.arguments.every(isContextualLiteral)) ||
1763
+ (ast.type === 'ConditionalExpression' &&
1764
+ isContextualLiteral(ast.consequent) &&
1765
+ isContextualLiteral(ast.alternate))
1766
+ );
1767
+ }
1768
+
1769
+ /** Array and null branches receive their list/tuple type from the selected prototype. */
1770
+ function needsArgumentContext(ast: any): boolean {
1771
+ return (
1772
+ ast.type === 'ArrayExpression' ||
1773
+ (ast.type === 'Literal' && ast.value === null) ||
1774
+ Boolean(recoveryName(ast) && ast.arguments.some(containsContextualArray)) ||
1775
+ (ast.type === 'ConditionalExpression' &&
1776
+ (needsArgumentContext(ast.consequent) || needsArgumentContext(ast.alternate)))
1777
+ );
1778
+ }