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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (256) hide show
  1. package/dist/arrow/aggregates.js +1 -1
  2. package/dist/arrow/aggregates.js.map +1 -1
  3. package/dist/arrow/buffers.js.map +1 -1
  4. package/dist/arrow/cast.d.ts +1 -1
  5. package/dist/arrow/cast.js +1 -1
  6. package/dist/arrow/cast.js.map +1 -1
  7. package/dist/arrow/compiler.d.ts.map +1 -1
  8. package/dist/arrow/compiler.js +146 -29
  9. package/dist/arrow/compiler.js.map +1 -1
  10. package/dist/arrow/index.cjs +124 -23
  11. package/dist/arrow/index.cjs.map +1 -1
  12. package/dist/arrow/index.d.ts.map +1 -1
  13. package/dist/arrow/index.js.map +1 -1
  14. package/dist/arrow/list-values.d.ts.map +1 -1
  15. package/dist/arrow/list-values.js +27 -6
  16. package/dist/arrow/list-values.js.map +1 -1
  17. package/dist/arrow/predicate.d.ts.map +1 -1
  18. package/dist/arrow/predicate.js.map +1 -1
  19. package/dist/arrow/query-arrow-sql.d.ts +2 -2
  20. package/dist/arrow/query-arrow-sql.d.ts.map +1 -1
  21. package/dist/arrow/query-arrow-sql.js +40 -8
  22. package/dist/arrow/query-arrow-sql.js.map +1 -1
  23. package/dist/arrow/query-arrow-table.d.ts +1 -1
  24. package/dist/arrow/query-arrow-table.d.ts.map +1 -1
  25. package/dist/arrow/query-arrow-table.js +1 -1
  26. package/dist/arrow/query-arrow-table.js.map +1 -1
  27. package/dist/arrow/query-worker.d.ts +1 -1
  28. package/dist/arrow/query-worker.d.ts.map +1 -1
  29. package/dist/arrow/query-worker.js +1 -1
  30. package/dist/arrow/query-worker.js.map +1 -1
  31. package/dist/arrow/registry.d.ts.map +1 -1
  32. package/dist/arrow/registry.js +1 -0
  33. package/dist/arrow/registry.js.map +1 -1
  34. package/dist/arrow/relational-query.js +2 -2
  35. package/dist/arrow/relational-query.js.map +1 -1
  36. package/dist/arrow/temporal-cast.js.map +1 -1
  37. package/dist/arrow/types.d.ts.map +1 -1
  38. package/dist/arrow/unnest-arrow-column.d.ts +22 -0
  39. package/dist/arrow/unnest-arrow-column.d.ts.map +1 -0
  40. package/dist/arrow/unnest-arrow-column.js +112 -0
  41. package/dist/arrow/unnest-arrow-column.js.map +1 -0
  42. package/dist/arrow/worker.cjs +130 -29
  43. package/dist/arrow/worker.cjs.map +1 -1
  44. package/dist/arrow/worker.d.ts +1 -1
  45. package/dist/arrow/worker.d.ts.map +1 -1
  46. package/dist/arrow/worker.js +1 -1
  47. package/dist/arrow/worker.js.map +1 -1
  48. package/dist/{color → color-functions}/index.cjs +2 -2
  49. package/dist/{color → color-functions}/index.cjs.map +1 -1
  50. package/dist/color-functions/index.d.ts.map +1 -0
  51. package/dist/color-functions/index.js.map +1 -0
  52. package/dist/expressions/ast.js +3 -1
  53. package/dist/expressions/ast.js.map +1 -1
  54. package/dist/expressions/expression-eval.d.ts +10 -1
  55. package/dist/expressions/expression-eval.d.ts.map +1 -1
  56. package/dist/expressions/expression-eval.js.map +1 -1
  57. package/dist/expressions/index.cjs +1 -1
  58. package/dist/expressions/index.cjs.map +1 -1
  59. package/dist/index.cjs +2792 -2363
  60. package/dist/index.cjs.map +3 -3
  61. package/dist/index.d.ts +2 -0
  62. package/dist/index.d.ts.map +1 -1
  63. package/dist/index.js +1 -0
  64. package/dist/index.js.map +1 -1
  65. package/dist/{math → math-functions}/index.cjs +2 -2
  66. package/dist/{math → math-functions}/index.cjs.map +1 -1
  67. package/dist/math-functions/index.d.ts.map +1 -0
  68. package/dist/math-functions/index.js.map +1 -0
  69. package/dist/parser/bind-sql-predicate.d.ts.map +1 -0
  70. package/dist/parser/bind-sql-predicate.js.map +1 -0
  71. package/dist/{sql → parser}/index.cjs +348 -129
  72. package/dist/parser/index.cjs.map +6 -0
  73. package/dist/{sql → parser}/index.d.ts +2 -0
  74. package/dist/parser/index.d.ts.map +1 -0
  75. package/dist/{sql → parser}/index.js +1 -0
  76. package/dist/parser/index.js.map +1 -0
  77. package/dist/parser/parameter-snapshots.d.ts +21 -0
  78. package/dist/parser/parameter-snapshots.d.ts.map +1 -0
  79. package/dist/parser/parameter-snapshots.js +85 -0
  80. package/dist/parser/parameter-snapshots.js.map +1 -0
  81. package/dist/{sql → parser}/parse-sql-expression.d.ts +8 -2
  82. package/dist/parser/parse-sql-expression.d.ts.map +1 -0
  83. package/dist/{sql → parser}/parse-sql-expression.js +51 -5
  84. package/dist/parser/parse-sql-expression.js.map +1 -0
  85. package/dist/parser/parse-sql-predicate.d.ts.map +1 -0
  86. package/dist/parser/parse-sql-predicate.js.map +1 -0
  87. package/dist/{sql → parser}/parse-sql-query.d.ts +2 -1
  88. package/dist/parser/parse-sql-query.d.ts.map +1 -0
  89. package/dist/{sql → parser}/parse-sql-query.js +21 -6
  90. package/dist/parser/parse-sql-query.js.map +1 -0
  91. package/dist/{sql → parser}/parse-sql-select.d.ts +4 -2
  92. package/dist/parser/parse-sql-select.d.ts.map +1 -0
  93. package/dist/{sql → parser}/parse-sql-select.js +6 -3
  94. package/dist/parser/parse-sql-select.js.map +1 -0
  95. package/dist/{sql → parser}/parse-sql-statement.d.ts +9 -5
  96. package/dist/parser/parse-sql-statement.d.ts.map +1 -0
  97. package/dist/{sql → parser}/parse-sql-statement.js +39 -14
  98. package/dist/parser/parse-sql-statement.js.map +1 -0
  99. package/dist/parser/query-types.d.ts.map +1 -0
  100. package/dist/parser/query-types.js.map +1 -0
  101. package/dist/parser/sql-parameters.d.ts +29 -0
  102. package/dist/parser/sql-parameters.d.ts.map +1 -0
  103. package/dist/parser/sql-parameters.js +110 -0
  104. package/dist/parser/sql-parameters.js.map +1 -0
  105. package/dist/parser/sql-parse-error.d.ts.map +1 -0
  106. package/dist/parser/sql-parse-error.js.map +1 -0
  107. package/dist/parser/sql-predicate-schema.d.ts.map +1 -0
  108. package/dist/parser/sql-predicate-schema.js.map +1 -0
  109. package/dist/parser/sql-predicate-types.d.ts.map +1 -0
  110. package/dist/parser/sql-predicate-types.js.map +1 -0
  111. package/dist/parser/sql-predicate.d.ts.map +1 -0
  112. package/dist/parser/sql-predicate.js.map +1 -0
  113. package/dist/scales/arrow-domains.d.ts +8 -1
  114. package/dist/scales/arrow-domains.d.ts.map +1 -1
  115. package/dist/scales/arrow-domains.js +48 -6
  116. package/dist/scales/arrow-domains.js.map +1 -1
  117. package/dist/scales/arrow-scales.d.ts +28 -4
  118. package/dist/scales/arrow-scales.d.ts.map +1 -1
  119. package/dist/scales/arrow-scales.js +158 -12
  120. package/dist/scales/arrow-scales.js.map +1 -1
  121. package/dist/scales/compile-scale.d.ts +1 -6
  122. package/dist/scales/compile-scale.d.ts.map +1 -1
  123. package/dist/scales/compile-scale.js +1 -191
  124. package/dist/scales/compile-scale.js.map +1 -1
  125. package/dist/scales/conformance.cjs +180 -0
  126. package/dist/scales/conformance.cjs.map +6 -0
  127. package/dist/scales/conformance.d.ts +26 -0
  128. package/dist/scales/conformance.d.ts.map +1 -0
  129. package/dist/scales/conformance.js +164 -0
  130. package/dist/scales/conformance.js.map +1 -0
  131. package/dist/scales/hdr-colors.d.ts +1 -12
  132. package/dist/scales/hdr-colors.d.ts.map +1 -1
  133. package/dist/scales/hdr-colors.js +1 -111
  134. package/dist/scales/hdr-colors.js.map +1 -1
  135. package/dist/scales/index.cjs +3738 -618
  136. package/dist/scales/index.cjs.map +3 -3
  137. package/dist/scales/index.d.ts +2 -1
  138. package/dist/scales/index.d.ts.map +1 -1
  139. package/dist/scales/index.js +2 -1
  140. package/dist/scales/index.js.map +1 -1
  141. package/dist/scales/palettes.d.ts +1 -4
  142. package/dist/scales/palettes.d.ts.map +1 -1
  143. package/dist/scales/palettes.js +1 -81
  144. package/dist/scales/palettes.js.map +1 -1
  145. package/dist/scales/parse-sql-scale.d.ts +14 -1
  146. package/dist/scales/parse-sql-scale.d.ts.map +1 -1
  147. package/dist/scales/parse-sql-scale.js +110 -18
  148. package/dist/scales/parse-sql-scale.js.map +1 -1
  149. package/dist/scales/quantile-sketch.d.ts +1 -21
  150. package/dist/scales/quantile-sketch.d.ts.map +1 -1
  151. package/dist/scales/quantile-sketch.js +1 -104
  152. package/dist/scales/quantile-sketch.js.map +1 -1
  153. package/dist/scales/scale-types.d.ts +1 -91
  154. package/dist/scales/scale-types.d.ts.map +1 -1
  155. package/dist/scales/scale-types.js +1 -115
  156. package/dist/scales/scale-types.js.map +1 -1
  157. package/dist/scales/streaming-domains.d.ts.map +1 -1
  158. package/dist/scales/streaming-domains.js +8 -2
  159. package/dist/scales/streaming-domains.js.map +1 -1
  160. package/package.json +19 -19
  161. package/src/arrow/aggregates.ts +1 -1
  162. package/src/arrow/buffers.ts +1 -1
  163. package/src/arrow/cast.ts +3 -3
  164. package/src/arrow/compiler.ts +155 -36
  165. package/src/arrow/index.ts +1 -1
  166. package/src/arrow/list-values.ts +28 -7
  167. package/src/arrow/predicate.ts +1 -1
  168. package/src/arrow/query-arrow-sql.ts +38 -10
  169. package/src/arrow/query-arrow-table.ts +3 -3
  170. package/src/arrow/query-worker.ts +5 -1
  171. package/src/arrow/registry.ts +1 -0
  172. package/src/arrow/relational-query.ts +2 -2
  173. package/src/arrow/temporal-cast.ts +1 -1
  174. package/src/arrow/types.ts +1 -1
  175. package/src/arrow/unnest-arrow-column.ts +145 -0
  176. package/src/arrow/worker.ts +6 -2
  177. package/src/expressions/ast.ts +3 -1
  178. package/src/expressions/expression-eval.ts +10 -1
  179. package/src/index.ts +14 -0
  180. package/src/{math → math-functions}/index.ts +2 -2
  181. package/src/{sql → parser}/index.ts +15 -0
  182. package/src/parser/parameter-snapshots.ts +103 -0
  183. package/src/{sql → parser}/parse-sql-expression.ts +49 -6
  184. package/src/{sql → parser}/parse-sql-query.ts +24 -6
  185. package/src/{sql → parser}/parse-sql-select.ts +14 -8
  186. package/src/{sql → parser}/parse-sql-statement.ts +42 -24
  187. package/src/{sql → parser}/query-types.ts +1 -1
  188. package/src/parser/sql-parameters.ts +174 -0
  189. package/src/scales/arrow-domains.ts +66 -7
  190. package/src/scales/arrow-scales.ts +221 -14
  191. package/src/scales/compile-scale.ts +1 -213
  192. package/src/scales/conformance.ts +186 -0
  193. package/src/scales/hdr-colors.ts +1 -122
  194. package/src/scales/index.ts +3 -1
  195. package/src/scales/palettes.ts +1 -82
  196. package/src/scales/parse-sql-scale.ts +126 -21
  197. package/src/scales/quantile-sketch.ts +1 -102
  198. package/src/scales/scale-types.ts +1 -220
  199. package/src/scales/streaming-domains.ts +8 -2
  200. package/dist/color/index.d.ts.map +0 -1
  201. package/dist/color/index.js.map +0 -1
  202. package/dist/math/index.d.ts.map +0 -1
  203. package/dist/math/index.js.map +0 -1
  204. package/dist/scales/arrow-scales.cjs +0 -3837
  205. package/dist/scales/arrow-scales.cjs.map +0 -6
  206. package/dist/sql/bind-sql-predicate.d.ts.map +0 -1
  207. package/dist/sql/bind-sql-predicate.js.map +0 -1
  208. package/dist/sql/index.cjs.map +0 -6
  209. package/dist/sql/index.d.ts.map +0 -1
  210. package/dist/sql/index.js.map +0 -1
  211. package/dist/sql/parse-sql-expression.d.ts.map +0 -1
  212. package/dist/sql/parse-sql-expression.js.map +0 -1
  213. package/dist/sql/parse-sql-predicate.d.ts.map +0 -1
  214. package/dist/sql/parse-sql-predicate.js.map +0 -1
  215. package/dist/sql/parse-sql-query.d.ts.map +0 -1
  216. package/dist/sql/parse-sql-query.js.map +0 -1
  217. package/dist/sql/parse-sql-select.d.ts.map +0 -1
  218. package/dist/sql/parse-sql-select.js.map +0 -1
  219. package/dist/sql/parse-sql-statement.d.ts.map +0 -1
  220. package/dist/sql/parse-sql-statement.js.map +0 -1
  221. package/dist/sql/query-types.d.ts.map +0 -1
  222. package/dist/sql/query-types.js.map +0 -1
  223. package/dist/sql/sql-parse-error.d.ts.map +0 -1
  224. package/dist/sql/sql-parse-error.js.map +0 -1
  225. package/dist/sql/sql-predicate-schema.d.ts.map +0 -1
  226. package/dist/sql/sql-predicate-schema.js.map +0 -1
  227. package/dist/sql/sql-predicate-types.d.ts.map +0 -1
  228. package/dist/sql/sql-predicate-types.js.map +0 -1
  229. package/dist/sql/sql-predicate.d.ts.map +0 -1
  230. package/dist/sql/sql-predicate.js.map +0 -1
  231. package/src/expressions/vendor/jsep/README.md +0 -22
  232. /package/dist/{color → color-functions}/index.d.ts +0 -0
  233. /package/dist/{color → color-functions}/index.js +0 -0
  234. /package/dist/{math → math-functions}/index.d.ts +0 -0
  235. /package/dist/{math → math-functions}/index.js +0 -0
  236. /package/dist/{sql → parser}/bind-sql-predicate.d.ts +0 -0
  237. /package/dist/{sql → parser}/bind-sql-predicate.js +0 -0
  238. /package/dist/{sql → parser}/parse-sql-predicate.d.ts +0 -0
  239. /package/dist/{sql → parser}/parse-sql-predicate.js +0 -0
  240. /package/dist/{sql → parser}/query-types.d.ts +0 -0
  241. /package/dist/{sql → parser}/query-types.js +0 -0
  242. /package/dist/{sql → parser}/sql-parse-error.d.ts +0 -0
  243. /package/dist/{sql → parser}/sql-parse-error.js +0 -0
  244. /package/dist/{sql → parser}/sql-predicate-schema.d.ts +0 -0
  245. /package/dist/{sql → parser}/sql-predicate-schema.js +0 -0
  246. /package/dist/{sql → parser}/sql-predicate-types.d.ts +0 -0
  247. /package/dist/{sql → parser}/sql-predicate-types.js +0 -0
  248. /package/dist/{sql → parser}/sql-predicate.d.ts +0 -0
  249. /package/dist/{sql → parser}/sql-predicate.js +0 -0
  250. /package/src/{color → color-functions}/index.ts +0 -0
  251. /package/src/{sql → parser}/bind-sql-predicate.ts +0 -0
  252. /package/src/{sql → parser}/parse-sql-predicate.ts +0 -0
  253. /package/src/{sql → parser}/sql-parse-error.ts +0 -0
  254. /package/src/{sql → parser}/sql-predicate-schema.ts +0 -0
  255. /package/src/{sql → parser}/sql-predicate-types.ts +0 -0
  256. /package/src/{sql → parser}/sql-predicate.ts +0 -0
@@ -12,15 +12,24 @@ import {
12
12
  Uint16,
13
13
  vectorFromArray,
14
14
  type RecordBatch,
15
+ type Schema,
15
16
  type Table,
16
17
  type Vector
17
18
  } from 'apache-arrow';
18
19
  import {compileArrowExpression} from '../arrow/compiler';
19
20
  import {nullTupleVector} from '../arrow/list-values';
20
- import type {ArrowExpression} from '../arrow/types';
21
+ import type {ArrowExpression, ArrowTableFunction} from '../arrow/types';
21
22
  import {compileResolvedScale} from './compile-scale';
22
- import {arrowScaleValue, resolveArrowDomains, resolveArrowQuantiles} from './arrow-domains';
23
- import type {ParsedSQLScale} from './parse-sql-scale';
23
+ import {
24
+ arrowScaleValue,
25
+ resolveArrowDomains,
26
+ resolveArrowExpressionStatistics,
27
+ resolveArrowQuantiles
28
+ } from './arrow-domains';
29
+ import {parseSQLScaleAST, type ParsedSQLScale} from './parse-sql-scale';
30
+ import {parseSQLExpression} from '../parser/parse-sql-expression';
31
+ import type {Expression} from '../expressions';
32
+ import type {CompiledArrowExpression} from '../arrow/types';
24
33
  import type {ResolvedScale, ScaleColor, ScaleSpec, ScaleValue} from './scale-types';
25
34
 
26
35
  export type CompiledArrowScale = Readonly<{
@@ -75,22 +84,89 @@ function toVector(rows: (number | ScaleColor | null)[], spec: ScaleSpec): Vector
75
84
  return vector;
76
85
  }
77
86
 
87
+ /** Determines the number of classes declared by the range. */
88
+ function getClassCount(spec: ScaleSpec): number | undefined {
89
+ if (spec.range.type === 'palette') return spec.range.count;
90
+ return spec.type === 'quantile' && spec.range.type === 'colors'
91
+ ? spec.range.values.length
92
+ : undefined;
93
+ }
94
+
78
95
  /** Compile a shared domain + range and bind its per-row Arrow expression once. */
79
96
  export function compileArrowScale(
80
97
  table: Table,
81
98
  parsed: ParsedSQLScale,
82
- resolvedDomain?: readonly ScaleValue[]
99
+ resolvedDomain?: readonly ScaleValue[],
100
+ functions?: readonly ArrowTableFunction[]
83
101
  ): CompiledArrowScale {
84
- const domain = resolvedDomain ?? resolveArrowDomains(table, [parsed.scale.domain])[0]!;
102
+ /** Class count used by the palette for quantile classification. */
103
+ const classCount = getClassCount(parsed.scale);
104
+ if (parsed.scale.type === 'quantile' && (!classCount || parsed.scale.domain.type === 'fixed')) {
105
+ throw new Error('Quantile scale requires a class count and a data-derived domain');
106
+ }
107
+ if (parsed.scale.domain.type === 'expression-extent') {
108
+ const resolution = resolveArrowExpressionStatistics(
109
+ table,
110
+ parsed.scale.domain.expression as Expression,
111
+ parsed.scale.type === 'quantile' ? classCount : undefined,
112
+ functions
113
+ );
114
+ return bindArrowScale(
115
+ table.schema,
116
+ parsed,
117
+ {...resolution, domain: resolvedDomain ?? resolution.domain},
118
+ functions
119
+ );
120
+ }
121
+ /** Resolved inputs shared with the schema-only binder. */
122
+ const resolution: ArrowScaleResolution = {
123
+ domain: resolvedDomain ?? resolveArrowDomains(table, [parsed.scale.domain])[0]!,
124
+ ...(parsed.scale.type === 'quantile' && parsed.scale.domain.type !== 'fixed'
125
+ ? {quantileBreaks: resolveArrowQuantiles(table, parsed.scale.domain.column, classCount!)}
126
+ : {})
127
+ };
128
+ return bindArrowScale(table.schema, parsed, resolution, functions);
129
+ }
130
+
131
+ /** Statistics needed to bind a scale without retaining its source table. */
132
+ export type ArrowScaleResolution = Readonly<{
133
+ /** Resolved extent, categories, or explicit domain stops. */
134
+ domain: readonly ScaleValue[];
135
+ /** Required for quantile classification. Supply one break per class boundary. */
136
+ quantileBreaks?: readonly number[];
137
+ }>;
138
+
139
+ /** Binds a resolved scale to an Arrow schema without reading any rows. */
140
+ export function bindArrowScale(
141
+ inputSchema: Schema,
142
+ parsed: ParsedSQLScale,
143
+ {domain, quantileBreaks}: ArrowScaleResolution,
144
+ functions?: readonly ArrowTableFunction[]
145
+ ): CompiledArrowScale {
146
+ /** Break points used by classified scales. */
85
147
  let thresholds: readonly number[] | undefined;
148
+ /** Scale transform and classification family. */
86
149
  const kind = parsed.scale.type;
87
- const classCount = parsed.scale.range.type === 'palette' ? parsed.scale.range.count : undefined;
150
+ /** Number of discrete classes declared by the palette, if any. */
151
+ const classCount = getClassCount(parsed.scale);
88
152
  if (kind === 'quantile') {
89
- if (!classCount || parsed.scale.domain.type === 'fixed') {
90
- throw new Error('Quantile scale requires a class count and a source column');
153
+ if (
154
+ classCount === undefined ||
155
+ !Number.isSafeInteger(classCount) ||
156
+ classCount < 2 ||
157
+ quantileBreaks?.length !== classCount - 1
158
+ ) {
159
+ throw new Error('Quantile scale requires one resolved break per class boundary');
160
+ }
161
+ if (
162
+ quantileBreaks.some(
163
+ (value, index) =>
164
+ !Number.isFinite(value) || (index > 0 && value < quantileBreaks[index - 1]!)
165
+ )
166
+ ) {
167
+ throw new Error('Quantile scale breaks must be finite and nondecreasing');
91
168
  }
92
- const column = parsed.scale.domain.column;
93
- thresholds = resolveArrowQuantiles(table, column, classCount);
169
+ thresholds = quantileBreaks;
94
170
  } else if (kind === 'quantize') {
95
171
  if (
96
172
  !classCount ||
@@ -112,10 +188,14 @@ export function compileArrowScale(
112
188
  }
113
189
  thresholds = domain as readonly number[];
114
190
  }
191
+ /** Evaluator shared by Arrow output and descriptor consumers. */
115
192
  const scale = compileResolvedScale(parsed.scale, domain, thresholds);
193
+ /** Input expression bound once to the source schema. */
116
194
  const compiled = compileArrowExpression(parsed.value as ArrowExpression, {
117
- inputSchema: table.schema
195
+ inputSchema,
196
+ functions
118
197
  });
198
+ /** Maps one vector to the selected scalar or color encoding. */
119
199
  const evaluateVector = (input: Vector): Vector => {
120
200
  const result: (number | ScaleColor | null)[] = Array.from({length: input.length}, (_, i) => {
121
201
  const value = arrowScaleValue(input.get(i));
@@ -140,17 +220,144 @@ export function compileArrowScale(
140
220
  */
141
221
  export function compileArrowScales<K extends string>(
142
222
  table: Table,
143
- expressions: Readonly<Record<K, ParsedSQLScale>>
223
+ expressions: Readonly<Record<K, ParsedSQLScale>>,
224
+ functions?: readonly ArrowTableFunction[]
144
225
  ): Record<K, CompiledArrowScale> {
145
226
  const entries = Object.entries(expressions) as [K, ParsedSQLScale][];
227
+ const columnEntries = entries.filter(
228
+ ([, parsed]) => parsed.scale.domain.type !== 'expression-extent'
229
+ );
146
230
  const domains = resolveArrowDomains(
147
231
  table,
148
- entries.map(([, parsed]) => parsed.scale.domain)
232
+ columnEntries.map(([, parsed]) => parsed.scale.domain)
149
233
  );
234
+ const domainsByKey = new Map(columnEntries.map(([key], index) => [key, domains[index]!]));
150
235
  return Object.fromEntries(
151
- entries.map(([key, parsed], index) => [key, compileArrowScale(table, parsed, domains[index])])
236
+ entries.map(([key, parsed]) => [
237
+ key,
238
+ compileArrowScale(table, parsed, domainsByKey.get(key), functions)
239
+ ])
152
240
  ) as Record<K, CompiledArrowScale>;
153
241
  }
154
242
 
155
243
  export {createStreamingDomainAccumulator} from './streaming-domains';
156
244
  export type {StreamingDomainOptions} from './streaming-domains';
245
+
246
+ /** A composed expression with one authoritative descriptor per scale call, in traversal order. */
247
+ export type CompiledArrowScaleExpression = CompiledArrowExpression & {
248
+ /** Domains resolve against the complete input table, independently of CASE branch selection. */
249
+ readonly scales: readonly ResolvedScale[];
250
+ };
251
+
252
+ /**
253
+ * Compiles SQL containing scales inside CASE, COALESCE, or other expressions.
254
+ * Domains resolve once over the complete table. Per-row scale inputs obey the
255
+ * expression compiler's active-row masks, so unselected CASE branches are not evaluated.
256
+ * Recompile after changing the source data to refresh data-derived domains.
257
+ */
258
+ export function compileArrowScaleExpression(
259
+ table: Table,
260
+ expression: string | Expression,
261
+ functions: readonly ArrowTableFunction[] = []
262
+ ): CompiledArrowScaleExpression {
263
+ /** Parsed caller expression; rewriting never mutates it. */
264
+ const ast = typeof expression === 'string' ? parseSQLExpression(expression) : expression;
265
+ /** Reserved caller identifiers and generated function names. */
266
+ const names = new Set(functions.map(fn => fn.name.toUpperCase()));
267
+ /** Resolved descriptors in outer-before-inner traversal order. */
268
+ const scales: ResolvedScale[] = [];
269
+ /** Caller functions followed by generated scale functions. */
270
+ const declarations = [...functions];
271
+ /** Reserves user identifiers before allocating internal function names. */
272
+ function reserve(node: unknown): void {
273
+ if (!node || typeof node !== 'object') return;
274
+ if ('type' in node && node.type === 'Identifier' && 'name' in node)
275
+ names.add(String(node.name).toUpperCase());
276
+ for (const value of Object.values(node)) reserve(value);
277
+ }
278
+ reserve(ast);
279
+ /** Monotonic suffix for collision-free internal names. */
280
+ let nextName = 0;
281
+ /** Replaces each scale call with a typed vector function bound to its resolved domain. */
282
+ function visit(node: any): any {
283
+ if (!node || typeof node !== 'object') return node;
284
+ if (Array.isArray(node)) return node.map(visit);
285
+ if (
286
+ node.type === 'CallExpression' &&
287
+ node.callee?.type === 'Identifier' &&
288
+ /^SCALE_(LINEAR|SQRT|LOG|COLOR|DIVERGING|ORDINAL|QUANTILE|QUANTIZE|THRESHOLD)$/i.test(
289
+ node.callee.name
290
+ )
291
+ ) {
292
+ /** Reserve descriptor order before recursively resolving nested scale inputs. */
293
+ const scaleIndex = scales.length;
294
+ scales.length++;
295
+ /** Rewrite the value before parsing so computed domains reference generated functions too. */
296
+ const valueExpression = visit(node.arguments[0]);
297
+ /** Validated outer scale with nested inputs already bound. */
298
+ const parsed = parseSQLScaleAST({
299
+ ...node,
300
+ arguments: [valueExpression, ...node.arguments.slice(1)]
301
+ });
302
+ /** Whole-table domain and sampler, using all nested function declarations. */
303
+ const {scale} = compileArrowScale(table, parsed, undefined, declarations);
304
+ scales[scaleIndex] = scale;
305
+ /** Input type for the generated vector function overload. */
306
+ const input = compileArrowExpression(parsed.value as ArrowExpression, {
307
+ inputSchema: table.schema,
308
+ functions: declarations
309
+ });
310
+ /** Private function identifier that cannot shadow a caller name. */
311
+ let name: string;
312
+ do {
313
+ name = '__scale_' + nextName++;
314
+ } while (names.has(name.toUpperCase()));
315
+ names.add(name.toUpperCase());
316
+ declarations.push({
317
+ name,
318
+ prototypes: [
319
+ {
320
+ arguments: [input.outputField],
321
+ result: new Field(name, toVector([], parsed.scale).type, true),
322
+ nullHandling: 'call',
323
+ evaluate: ([values], {activeRows, length}) =>
324
+ toVector(
325
+ Array.from({length}, (_, row) => {
326
+ if (!activeRows[row]) return null;
327
+ /** Active scalar input with Arrow integer normalization. */
328
+ const value = arrowScaleValue(values!.get(row));
329
+ if (
330
+ value !== null &&
331
+ value !== undefined &&
332
+ typeof value !== 'number' &&
333
+ typeof value !== 'string'
334
+ ) {
335
+ throw new Error('Scale input must be numeric or categorical');
336
+ }
337
+ return scale.sample((value ?? null) as ScaleValue | null) as
338
+ | number
339
+ | ScaleColor
340
+ | null;
341
+ }),
342
+ parsed.scale
343
+ )
344
+ }
345
+ ]
346
+ });
347
+ return {
348
+ type: 'CallExpression',
349
+ callee: {type: 'Identifier', name},
350
+ arguments: [parsed.value]
351
+ };
352
+ }
353
+ return Object.fromEntries(Object.entries(node).map(([key, value]) => [key, visit(value)]));
354
+ }
355
+ /** Ordinary Arrow expression after removing every supported scale call. */
356
+ const rewritten = visit(ast);
357
+ /** Final evaluator with caller and generated declarations. */
358
+ const compiled = compileArrowExpression(rewritten, {
359
+ inputSchema: table.schema,
360
+ functions: declarations
361
+ });
362
+ return {...compiled, scales};
363
+ }
@@ -2,216 +2,4 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
  // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
4
 
5
- import {
6
- createResolvedScale,
7
- type ResolvedScale,
8
- type ResolvedScaleDescriptor,
9
- type ScaleColor,
10
- type ScaleColorEncoding,
11
- type ScaleSpec,
12
- type ScaleValue
13
- } from './scale-types';
14
- import {resolvePalette} from './palettes';
15
- import {convertScaleColor, decodeSRGB, encodeSRGB} from './hdr-colors';
16
-
17
- /** Encoding of the built-in palette stops and the sRGB interpolation helpers. */
18
- const SRGB: ScaleColorEncoding = {primaries: 'srgb', transfer: 'srgb', format: 'rgba32float'};
19
-
20
- const clamp01 = (value: number): number => Math.min(1, Math.max(0, value));
21
- function toOklab(color: ScaleColor): [number, number, number] {
22
- const [r, g, b] = color.slice(0, 3).map(decodeSRGB);
23
- const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
24
- const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
25
- const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
26
- return [
27
- 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
28
- 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
29
- 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s
30
- ];
31
- }
32
- function fromOklab([L, a, b]: number[]): [number, number, number] {
33
- const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
34
- const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
35
- const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
36
- return [
37
- encodeSRGB(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
38
- encodeSRGB(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
39
- encodeSRGB(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s)
40
- ];
41
- }
42
- function interpolateColor(
43
- a: ScaleColor,
44
- b: ScaleColor,
45
- t: number,
46
- space: ScaleSpec['interpolation'] = 'srgb'
47
- ): ScaleColor {
48
- if (space === 'jzazbz') {
49
- throw new Error('Jzazbz interpolation is not implemented yet');
50
- }
51
- const mix = (x: number, y: number) => x + (y - x) * t;
52
- const alpha = mix(a[3], b[3]);
53
- if (space === 'oklab') {
54
- const lhs = toOklab(a),
55
- rhs = toOklab(b);
56
- const rgb = fromOklab(lhs.map((v, i) => mix(v, rhs[i]!)));
57
- return [rgb[0], rgb[1], rgb[2], alpha];
58
- }
59
- if (space === 'linear-srgb') {
60
- return [
61
- encodeSRGB(mix(decodeSRGB(a[0]), decodeSRGB(b[0]))),
62
- encodeSRGB(mix(decodeSRGB(a[1]), decodeSRGB(b[1]))),
63
- encodeSRGB(mix(decodeSRGB(a[2]), decodeSRGB(b[2]))),
64
- alpha
65
- ];
66
- }
67
- return [mix(a[0], b[0]), mix(a[1], b[1]), mix(a[2], b[2]), alpha];
68
- }
69
-
70
- function normalize(value: number, a: number, b: number, type: ScaleSpec['type']): number {
71
- if (a === b) return 0.5;
72
- if (type === 'log') {
73
- if (a <= 0 || b <= 0 || value <= 0) return NaN;
74
- return Math.log(value / a) / Math.log(b / a);
75
- }
76
- if (type === 'sqrt') {
77
- if (a < 0 || b < 0 || value < 0) return NaN;
78
- return (Math.sqrt(value) - Math.sqrt(a)) / (Math.sqrt(b) - Math.sqrt(a));
79
- }
80
- if (type === 'symlog') {
81
- const symlog = (v: number) => Math.sign(v) * Math.log1p(Math.abs(v));
82
- return (symlog(value) - symlog(a)) / (symlog(b) - symlog(a));
83
- }
84
- return (value - a) / (b - a);
85
- }
86
-
87
- function numericValues(domain: readonly ScaleValue[]): number[] {
88
- if (!domain.length || domain.some(v => typeof v !== 'number' || !Number.isFinite(v))) {
89
- throw new Error('Numeric scale requires a finite numeric domain');
90
- }
91
- return domain as number[];
92
- }
93
-
94
- /**
95
- * Compile one resolved scale. Domain, class breaks and palette stops are the
96
- * authoritative metadata consumed by renderers and legends alike.
97
- */
98
- export function compileResolvedScale(
99
- spec: ScaleSpec,
100
- domain: readonly ScaleValue[],
101
- thresholds?: readonly number[]
102
- ): ResolvedScale {
103
- const colorType = [
104
- 'sequential',
105
- 'diverging',
106
- 'ordinal',
107
- 'quantize',
108
- 'quantile',
109
- 'threshold',
110
- 'piecewise'
111
- ].includes(spec.type);
112
- if (colorType && spec.range.type === 'numeric') throw new Error('Color scale requires colors');
113
- if (!colorType && spec.range.type !== 'numeric')
114
- throw new Error('Numeric scale requires numeric range');
115
- const classes = spec.range.type === 'palette' ? spec.range.count : undefined;
116
- let palette = colorType ? resolvePalette(spec.range, classes) : undefined;
117
- if (thresholds?.length && thresholds.length + 1 !== (palette?.length ?? 0))
118
- throw new Error('Scale class count must match palette color count');
119
- if (spec.type === 'quantile' && thresholds) {
120
- // Repeated breakpoints create empty classes. Keep the colors of the intervals that remain.
121
- const original = thresholds;
122
- thresholds = original.filter((value, i) => i === 0 || value !== original[i - 1]);
123
- palette = palette!.filter(
124
- (_, i) => i === 0 || i === original.length || original[i - 1] !== original[i]
125
- );
126
- }
127
- const encoding = spec.encoding ?? SRGB;
128
- const paletteStops =
129
- palette && spec.range.type === 'palette' && spec.encoding
130
- ? palette.map(color => convertScaleColor(color, SRGB, encoding))
131
- : palette;
132
- const space = spec.interpolation ?? 'srgb';
133
- const workingStops =
134
- paletteStops && (space === 'linear-srgb' || space === 'oklab')
135
- ? paletteStops.map(color => convertScaleColor(color, encoding, SRGB))
136
- : paletteStops;
137
- if (spec.type === 'ordinal' && domain.length > (paletteStops?.length ?? 0)) {
138
- throw new Error('Ordinal palette must have at least one color per category');
139
- }
140
- const resolvedRange: ResolvedScaleDescriptor['range'] =
141
- spec.range.type === 'numeric' ? spec.range : {type: 'colors', values: paletteStops!};
142
- const descriptor: ResolvedScaleDescriptor = {
143
- ...spec,
144
- domain: [...domain],
145
- range: resolvedRange,
146
- ...(spec.range.type === 'palette' ? {palette: spec.range.name} : {}),
147
- ...(thresholds ? {thresholds: [...thresholds]} : {})
148
- };
149
- const isOrdinal = spec.type === 'ordinal';
150
- const values = isOrdinal ? domain : numericValues(domain);
151
- const numerical = isOrdinal ? [] : numericValues(domain);
152
- if (!isOrdinal && numerical.length < 2) throw new Error('Numeric domain requires two endpoints');
153
- const pivot = spec.type === 'diverging' ? spec.pivot : undefined;
154
- if (pivot !== undefined && !(numerical[0]! < pivot && pivot < numerical[numerical.length - 1]!))
155
- throw new Error('Diverging scale pivot must be between the domain endpoints');
156
- const breaks = thresholds ?? [];
157
- if (['quantile', 'quantize', 'threshold'].includes(spec.type) && !thresholds) {
158
- throw new Error(`${spec.type} scale requires resolved class breaks`);
159
- }
160
- const sample = (value: ScaleValue | null): number | ScaleColor | null => {
161
- if (value === null) return spec.nullColor ?? null;
162
- if (isOrdinal) {
163
- const index = values.indexOf(value);
164
- return index === -1 ? (spec.nullColor ?? null) : paletteStops![index]!;
165
- }
166
- if (typeof value !== 'number' || !Number.isFinite(value)) return spec.nullColor ?? null;
167
- const min = numerical[0]!,
168
- max = numerical[numerical.length - 1]!;
169
- if (value < min && spec.underColor) return spec.underColor;
170
- if (value > max && spec.overColor) return spec.overColor;
171
-
172
- if (spec.type === 'quantile' || spec.type === 'quantize' || spec.type === 'threshold') {
173
- const index = breaks.findIndex(boundary => value < boundary);
174
- const colorIndex = index < 0 ? breaks.length : index;
175
- return paletteStops![Math.min(colorIndex, paletteStops!.length - 1)]!;
176
- }
177
-
178
- // Piecewise ranges use the resolved domain values as positioned stops.
179
- const stopCount = colorType
180
- ? paletteStops!.length
181
- : (resolvedRange as {values: readonly number[]}).values.length;
182
- if (numerical.length !== 2 && numerical.length !== stopCount) {
183
- throw new Error('Piecewise domain and range stops must have equal lengths');
184
- }
185
- let segment = 0;
186
- let t: number;
187
- if (numerical.length === 2) {
188
- t =
189
- pivot === undefined
190
- ? normalize(value, min, max, spec.type)
191
- : value <= pivot
192
- ? normalize(value, min, pivot, spec.type) / 2
193
- : 0.5 + normalize(value, pivot, max, spec.type) / 2;
194
- if (spec.clamp ?? colorType) t = clamp01(t);
195
- const position = t * (stopCount - 1);
196
- segment = Math.min(stopCount - 2, Math.max(0, Math.floor(position)));
197
- t = position - segment;
198
- } else {
199
- while (segment < numerical.length - 2 && value > numerical[segment + 1]!) segment++;
200
- t = normalize(value, numerical[segment]!, numerical[segment + 1]!, spec.type);
201
- if (spec.clamp ?? colorType) t = clamp01(t);
202
- }
203
- if (!Number.isFinite(t)) return spec.nullColor ?? null;
204
- if (colorType) {
205
- const color = interpolateColor(
206
- workingStops![segment]!,
207
- workingStops![segment + 1]!,
208
- t,
209
- space
210
- );
211
- return workingStops === paletteStops ? color : convertScaleColor(color, SRGB, encoding);
212
- }
213
- const numbers = (resolvedRange as {values: readonly number[]}).values;
214
- return numbers[segment]! + (numbers[segment + 1]! - numbers[segment]!) * t;
215
- };
216
- return createResolvedScale(descriptor, sample);
217
- }
5
+ export * from '@math.gl/core/color';
@@ -0,0 +1,186 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import type {ResolvedScaleDescriptor, ScaleColor, ScaleValue} from './scale-types';
6
+
7
+ /** One backend-independent sampling expectation, before storage-format quantization. */
8
+ export type ScaleConformanceSample = Readonly<{
9
+ /** Input value; null represents an invalid source row. */
10
+ input: ScaleValue | null;
11
+ /** Expected numeric value, color channels, or invalid output. */
12
+ expected: number | ScaleColor | null;
13
+ }>;
14
+
15
+ /** Serializable fixture for CPU, worker, and GPU scale implementations. */
16
+ export type ScaleConformanceCase = Readonly<{
17
+ /** Stable descriptive case identifier. */
18
+ id: string;
19
+ /** Resolved domain, range, class breaks, and color interpretation. */
20
+ descriptor: ResolvedScaleDescriptor;
21
+ /** Maximum absolute error per numeric component, including alpha. */
22
+ absoluteTolerance: number;
23
+ /** Independently specified expected values, not generated by the sampler under test. */
24
+ samples: readonly ScaleConformanceSample[];
25
+ }>;
26
+
27
+ /**
28
+ * Small portable conformance corpus. Import this optional entry only in tests;
29
+ * the runtime scales entry does not import these fixtures. Storage packing and
30
+ * approximate domain resolution need separate backend-specific tests.
31
+ */
32
+ export const SCALE_CONFORMANCE_CASES: readonly ScaleConformanceCase[] = [
33
+ {
34
+ id: 'linear-extrapolation',
35
+ descriptor: {type: 'linear', domain: [0, 10], range: {type: 'numeric', values: [0, 100]}},
36
+ absoluteTolerance: 0.00001,
37
+ samples: [
38
+ {input: null, expected: null},
39
+ {input: -1, expected: -10},
40
+ {input: 0, expected: 0},
41
+ {input: 5, expected: 50},
42
+ {input: 11, expected: 110}
43
+ ]
44
+ },
45
+ {
46
+ id: 'log-domain',
47
+ descriptor: {type: 'log', domain: [1, 100], range: {type: 'numeric', values: [0, 1]}},
48
+ absoluteTolerance: 0.00001,
49
+ samples: [
50
+ {input: 0, expected: null},
51
+ {input: 1, expected: 0},
52
+ {input: 10, expected: 0.5},
53
+ {input: 100, expected: 1}
54
+ ]
55
+ },
56
+ {
57
+ id: 'linear-srgb-interpolation',
58
+ descriptor: {
59
+ type: 'sequential',
60
+ domain: [0, 1],
61
+ interpolation: 'linear-srgb',
62
+ range: {
63
+ type: 'colors',
64
+ values: [
65
+ [0, 0, 0, 0],
66
+ [1, 1, 1, 1]
67
+ ]
68
+ }
69
+ },
70
+ absoluteTolerance: 0.00001,
71
+ samples: [
72
+ {input: -1, expected: [0, 0, 0, 0]},
73
+ {input: 0.5, expected: [0.7353569830524495, 0.7353569830524495, 0.7353569830524495, 0.5]},
74
+ {input: 2, expected: [1, 1, 1, 1]}
75
+ ]
76
+ },
77
+ {
78
+ id: 'null-under-over-colors',
79
+ descriptor: {
80
+ type: 'sequential',
81
+ domain: [0, 1],
82
+ range: {
83
+ type: 'colors',
84
+ values: [
85
+ [0, 0, 0, 1],
86
+ [1, 1, 1, 1]
87
+ ]
88
+ },
89
+ nullColor: [0, 0, 0, 0],
90
+ underColor: [1, 0, 0, 1],
91
+ overColor: [0, 0, 1, 1]
92
+ },
93
+ absoluteTolerance: 0.00001,
94
+ samples: [
95
+ {input: null, expected: [0, 0, 0, 0]},
96
+ {input: -1, expected: [1, 0, 0, 1]},
97
+ {input: 0, expected: [0, 0, 0, 1]},
98
+ {input: 1, expected: [1, 1, 1, 1]},
99
+ {input: 2, expected: [0, 0, 1, 1]}
100
+ ]
101
+ },
102
+ {
103
+ id: 'quantile-boundary-after-duplicate-removal',
104
+ descriptor: {
105
+ type: 'quantile',
106
+ domain: [0, 10],
107
+ thresholds: [5],
108
+ range: {
109
+ type: 'colors',
110
+ values: [
111
+ [0, 0, 0, 1],
112
+ [1, 1, 1, 1]
113
+ ]
114
+ }
115
+ },
116
+ absoluteTolerance: 0,
117
+ samples: [
118
+ {input: 4.999, expected: [0, 0, 0, 1]},
119
+ {input: 5, expected: [1, 1, 1, 1]},
120
+ {input: 10, expected: [1, 1, 1, 1]}
121
+ ]
122
+ },
123
+ {
124
+ id: 'linear-encoding-conversion',
125
+ descriptor: {
126
+ type: 'sequential',
127
+ domain: [0, 1],
128
+ interpolation: 'linear-srgb',
129
+ range: {
130
+ type: 'colors',
131
+ values: [
132
+ [0, 0, 0, 1],
133
+ [1, 1, 1, 1]
134
+ ]
135
+ },
136
+ encoding: {primaries: 'srgb', transfer: 'linear', format: 'rgba32float'}
137
+ },
138
+ absoluteTolerance: 0.00001,
139
+ samples: [{input: 0.5, expected: [0.5, 0.5, 0.5, 1]}]
140
+ },
141
+ {
142
+ id: 'ordinal-unknown-category',
143
+ descriptor: {
144
+ type: 'ordinal',
145
+ domain: ['first', 'second'],
146
+ range: {
147
+ type: 'colors',
148
+ values: [
149
+ [1, 0, 0, 1],
150
+ [0, 0, 1, 1]
151
+ ]
152
+ }
153
+ },
154
+ absoluteTolerance: 0,
155
+ samples: [
156
+ {input: 'first', expected: [1, 0, 0, 1]},
157
+ {input: 'second', expected: [0, 0, 1, 1]},
158
+ {input: 'unknown', expected: null}
159
+ ]
160
+ },
161
+ {
162
+ id: 'hdr-linear-extended-channels',
163
+ descriptor: {
164
+ type: 'sequential',
165
+ domain: [0, 1],
166
+ range: {
167
+ type: 'colors',
168
+ values: [
169
+ [0, 0, 0, 0],
170
+ [4, 2, -0.5, 1]
171
+ ]
172
+ },
173
+ encoding: {
174
+ primaries: 'rec2020',
175
+ transfer: 'linear',
176
+ format: 'rgba32float',
177
+ referenceWhiteNits: 203
178
+ }
179
+ },
180
+ absoluteTolerance: 0.00001,
181
+ samples: [
182
+ {input: 0.5, expected: [2, 1, -0.25, 0.5]},
183
+ {input: 1, expected: [4, 2, -0.5, 1]}
184
+ ]
185
+ }
186
+ ];