@drupflare/spool 0.3.0 → 1.0.0

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 (206) hide show
  1. package/README.md +279 -1607
  2. package/dist/angular/index.d.ts +13 -0
  3. package/dist/angular/index.js +25 -0
  4. package/dist/angular/pages.d.ts +28 -0
  5. package/dist/angular/pages.js +85 -0
  6. package/dist/cdn/client.js +1 -1
  7. package/dist/cdn/location.d.ts +6 -0
  8. package/dist/cdn/location.js +8 -0
  9. package/dist/cdn/manifest.json +7 -7
  10. package/dist/cdn/spool-sw.js +1 -1
  11. package/dist/client/bootstrap.d.ts +57 -0
  12. package/dist/client/bootstrap.js +307 -0
  13. package/dist/client/contact.d.ts +24 -0
  14. package/dist/client/contact.js +66 -0
  15. package/dist/client/declared.d.ts +23 -0
  16. package/dist/client/declared.js +68 -0
  17. package/dist/client/entry.js +123 -2
  18. package/dist/client/gate.d.ts +1 -0
  19. package/dist/client/gate.js +148 -0
  20. package/dist/client/index.d.ts +25 -0
  21. package/dist/client/index.js +1 -0
  22. package/dist/client/live.d.ts +66 -0
  23. package/dist/client/live.js +225 -0
  24. package/dist/client/navigate-entry.d.ts +1 -0
  25. package/dist/client/navigate-entry.js +4 -0
  26. package/dist/client/navigate.d.ts +54 -0
  27. package/dist/client/navigate.js +272 -0
  28. package/dist/client/persist.d.ts +2 -0
  29. package/dist/client/persist.js +9 -0
  30. package/dist/client/register.d.ts +34 -2
  31. package/dist/client/register.js +64 -7
  32. package/dist/express/index.d.ts +11 -0
  33. package/dist/express/index.js +209 -0
  34. package/dist/hono/index.d.ts +19 -0
  35. package/dist/hono/index.js +49 -0
  36. package/dist/next/index.d.ts +33 -0
  37. package/dist/next/index.js +41 -0
  38. package/dist/next/pages.d.ts +22 -0
  39. package/dist/next/pages.js +39 -0
  40. package/dist/node/listener.d.ts +3 -0
  41. package/dist/node/listener.js +57 -2
  42. package/dist/nuxt/index.d.ts +22 -0
  43. package/dist/nuxt/index.js +104 -0
  44. package/dist/nuxt/pages.d.ts +26 -0
  45. package/dist/nuxt/pages.js +48 -0
  46. package/dist/nuxt/runtime/index.d.ts +24 -0
  47. package/dist/nuxt/runtime/index.js +58 -0
  48. package/dist/plugins/coverage.d.ts +14 -0
  49. package/dist/plugins/coverage.js +27 -0
  50. package/dist/plugins/mode.d.ts +19 -0
  51. package/dist/plugins/mode.js +20 -0
  52. package/dist/plugins/path.d.ts +16 -0
  53. package/dist/plugins/path.js +139 -0
  54. package/dist/plugins/report.d.ts +22 -0
  55. package/dist/plugins/report.js +18 -0
  56. package/dist/plugins/routes.d.ts +38 -0
  57. package/dist/plugins/routes.js +52 -0
  58. package/dist/plugins/static.d.ts +42 -0
  59. package/dist/plugins/static.js +97 -0
  60. package/dist/protocol/bundle.d.ts +111 -0
  61. package/dist/protocol/bundle.js +428 -0
  62. package/dist/protocol/config.d.ts +80 -1
  63. package/dist/protocol/config.js +31 -1
  64. package/dist/protocol/dataset.d.ts +189 -0
  65. package/dist/protocol/dataset.js +212 -0
  66. package/dist/protocol/envelope.d.ts +34 -1
  67. package/dist/protocol/envelope.js +16 -1
  68. package/dist/protocol/errors.d.ts +1 -1
  69. package/dist/protocol/graph.d.ts +23 -4
  70. package/dist/protocol/graph.js +34 -3
  71. package/dist/protocol/index-rows.d.ts +22 -0
  72. package/dist/protocol/index-rows.js +53 -0
  73. package/dist/protocol/index.d.ts +5 -0
  74. package/dist/protocol/index.js +5 -0
  75. package/dist/protocol/normalise.d.ts +4 -4
  76. package/dist/protocol/normalise.js +9 -5
  77. package/dist/protocol/plan.d.ts +100 -0
  78. package/dist/protocol/plan.js +661 -0
  79. package/dist/protocol/provision.d.ts +46 -0
  80. package/dist/protocol/provision.js +38 -0
  81. package/dist/protocol/query.d.ts +66 -5
  82. package/dist/protocol/query.js +103 -4
  83. package/dist/protocol/ring.d.ts +58 -0
  84. package/dist/protocol/ring.js +6 -0
  85. package/dist/protocol/route.d.ts +63 -13
  86. package/dist/protocol/route.js +126 -6
  87. package/dist/protocol/tag.d.ts +22 -2
  88. package/dist/protocol/tag.js +25 -4
  89. package/dist/protocol/view.d.ts +2 -0
  90. package/dist/protocol/view.js +8 -2
  91. package/dist/protocol/views.d.ts +6 -0
  92. package/dist/protocol/views.js +15 -0
  93. package/dist/protocol/write.d.ts +234 -0
  94. package/dist/protocol/write.js +343 -0
  95. package/dist/proxy/eligible.d.ts +22 -1
  96. package/dist/proxy/eligible.js +62 -15
  97. package/dist/proxy/proxy.js +28 -18
  98. package/dist/react-router/index.d.ts +20 -0
  99. package/dist/react-router/index.js +60 -0
  100. package/dist/react-router/pages.d.ts +34 -0
  101. package/dist/react-router/pages.js +83 -0
  102. package/dist/report/dataset.d.ts +48 -0
  103. package/dist/report/dataset.js +93 -0
  104. package/dist/report/demand.d.ts +49 -0
  105. package/dist/report/demand.js +60 -0
  106. package/dist/report/derive.d.ts +285 -0
  107. package/dist/report/derive.js +676 -1
  108. package/dist/report/economics.d.ts +66 -1
  109. package/dist/report/economics.js +208 -1
  110. package/dist/report/headline.d.ts +158 -0
  111. package/dist/report/headline.js +473 -0
  112. package/dist/report/index.d.ts +4 -0
  113. package/dist/report/index.js +4 -0
  114. package/dist/report/inputs.d.ts +176 -0
  115. package/dist/report/inputs.js +248 -0
  116. package/dist/report/institution.d.ts +188 -1
  117. package/dist/report/institution.js +146 -0
  118. package/dist/report/loops.d.ts +73 -0
  119. package/dist/report/loops.js +101 -0
  120. package/dist/report/measurement.d.ts +1 -1
  121. package/dist/report/measurement.js +7 -1
  122. package/dist/report/model.d.ts +2 -0
  123. package/dist/report/model.js +4 -0
  124. package/dist/report/thirdparty.d.ts +57 -0
  125. package/dist/report/thirdparty.js +111 -0
  126. package/dist/report/traffic.d.ts +8 -0
  127. package/dist/report/traffic.js +7 -0
  128. package/dist/report/trim.d.ts +56 -0
  129. package/dist/report/trim.js +83 -1
  130. package/dist/server/bundle.d.ts +55 -0
  131. package/dist/server/bundle.js +172 -0
  132. package/dist/server/dataset.d.ts +54 -0
  133. package/dist/server/dataset.js +355 -0
  134. package/dist/server/embedded.d.ts +7 -3
  135. package/dist/server/embedded.js +7 -3
  136. package/dist/server/index.d.ts +6 -0
  137. package/dist/server/index.js +6 -0
  138. package/dist/server/live-sockets.d.ts +54 -0
  139. package/dist/server/live-sockets.js +131 -0
  140. package/dist/server/live.d.ts +146 -0
  141. package/dist/server/live.js +228 -0
  142. package/dist/server/ring.d.ts +77 -0
  143. package/dist/server/ring.js +311 -0
  144. package/dist/server/spool.d.ts +158 -3
  145. package/dist/server/spool.js +578 -41
  146. package/dist/server/static.d.ts +42 -0
  147. package/dist/server/static.js +29 -0
  148. package/dist/server/stub.d.ts +43 -5
  149. package/dist/server/stub.js +126 -8
  150. package/dist/server/write.d.ts +49 -0
  151. package/dist/server/write.js +223 -0
  152. package/dist/stores/durable-object.d.ts +46 -0
  153. package/dist/stores/durable-object.js +114 -0
  154. package/dist/sw/analytics.d.ts +7 -1
  155. package/dist/sw/analytics.js +16 -2
  156. package/dist/sw/coverage.d.ts +6 -0
  157. package/dist/sw/coverage.js +34 -0
  158. package/dist/sw/dataset-sync.d.ts +76 -0
  159. package/dist/sw/dataset-sync.js +149 -0
  160. package/dist/sw/dataset.d.ts +91 -0
  161. package/dist/sw/dataset.js +318 -0
  162. package/dist/sw/family.d.ts +15 -0
  163. package/dist/sw/family.js +48 -0
  164. package/dist/sw/graph/index.d.ts +31 -1
  165. package/dist/sw/graph/index.js +57 -5
  166. package/dist/sw/graph/invalidate.d.ts +15 -3
  167. package/dist/sw/graph/invalidate.js +42 -4
  168. package/dist/sw/idb.d.ts +2 -0
  169. package/dist/sw/idb.js +80 -11
  170. package/dist/sw/index.d.ts +2 -0
  171. package/dist/sw/index.js +1 -0
  172. package/dist/sw/pack/store.d.ts +128 -0
  173. package/dist/sw/pack/store.js +737 -0
  174. package/dist/sw/partition.d.ts +6 -1
  175. package/dist/sw/partition.js +21 -2
  176. package/dist/sw/policy.d.ts +2 -0
  177. package/dist/sw/policy.js +11 -0
  178. package/dist/sw/principal-dataset.d.ts +64 -0
  179. package/dist/sw/principal-dataset.js +254 -0
  180. package/dist/sw/probe.d.ts +16 -0
  181. package/dist/sw/probe.js +25 -0
  182. package/dist/sw/render.d.ts +7 -2
  183. package/dist/sw/render.js +19 -5
  184. package/dist/sw/replica.d.ts +12 -3
  185. package/dist/sw/replica.js +40 -5
  186. package/dist/sw/router.d.ts +3 -2
  187. package/dist/sw/router.js +15 -2
  188. package/dist/sw/runtime.d.ts +90 -2
  189. package/dist/sw/runtime.js +857 -61
  190. package/dist/sw/scheduler.d.ts +6 -1
  191. package/dist/sw/scheduler.js +22 -5
  192. package/dist/sw/seal.d.ts +13 -0
  193. package/dist/sw/seal.js +13 -4
  194. package/dist/sw/static.d.ts +18 -0
  195. package/dist/sw/static.js +84 -1
  196. package/dist/sw/storage.d.ts +51 -1
  197. package/dist/sw/storage.js +33 -1
  198. package/dist/sw/write.d.ts +147 -0
  199. package/dist/sw/write.js +625 -0
  200. package/dist/version.d.ts +1 -1
  201. package/dist/version.js +1 -2
  202. package/dist/vite/index.d.ts +26 -0
  203. package/dist/vite/index.js +66 -0
  204. package/dist/vue/index.d.ts +36 -0
  205. package/dist/vue/index.js +53 -0
  206. package/package.json +65 -4
@@ -0,0 +1,661 @@
1
+ import { ProtocolError } from './errors.js';
2
+ import { DATASET_NAME } from './query.js';
3
+ /** the fewest rows a table holds before its fields are indexed; below it a scan is cheaper */
4
+ export const INDEX_MIN_ROWS = 200;
5
+ const PAGE = /^[1-9]\d{0,14}$/;
6
+ const NUMBER_TEXT = /^[+-]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i;
7
+ const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
8
+ const OPS = ['eq', 'in', 'gte', 'lte', 'prefix'];
9
+ const AGGREGATES = ['count', 'sum', 'min', 'max', 'avg'];
10
+ const PLAN_KEYS = ['from', 'join', 'where', 'group', 'sort', 'pageSize', 'limit'];
11
+ /** a plan read something SQLite would compare differently; the answer is the network's */
12
+ class NotLocal extends Error {
13
+ }
14
+ const own = (row, field) => Object.hasOwn(row, field) ? (row[field] ?? null) : null;
15
+ const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
16
+ const typeRank = (value) => typeof value === 'number' ? 1 : typeof value === 'string' ? 2 : 0;
17
+ const asciiLower = (text) => text.replace(/[A-Z]+/g, (m) => m.toLowerCase());
18
+ /** a stored value the engine compares exactly as SQLite does; anything else makes a plan not local */
19
+ export function plainValue(value) {
20
+ if (value === null || value === undefined)
21
+ return true;
22
+ if (typeof value === 'number')
23
+ return Number.isFinite(value);
24
+ if (typeof value === 'string')
25
+ return !LONE_SURROGATE.test(value) && !value.includes('\0');
26
+ return false;
27
+ }
28
+ /** UTF-8 byte order, which SQLite's BINARY collation uses; UTF-16 unit order differs above U+FFFF */
29
+ export function compareText(a, b) {
30
+ const n = Math.min(a.length, b.length);
31
+ for (let i = 0; i < n; i++) {
32
+ const x = a.charCodeAt(i);
33
+ const y = b.charCodeAt(i);
34
+ if (x === y)
35
+ continue;
36
+ const surrogateX = x >= 0xd800 && x <= 0xdfff;
37
+ const surrogateY = y >= 0xd800 && y <= 0xdfff;
38
+ if (surrogateX !== surrogateY)
39
+ return surrogateX ? 1 : -1;
40
+ return x - y;
41
+ }
42
+ return a.length - b.length;
43
+ }
44
+ /** NULL first, then numbers, then text; the order SQLite sorts a column with no affinity by */
45
+ function compareValues(a, b) {
46
+ const ra = typeRank(a);
47
+ const rb = typeRank(b);
48
+ if (ra !== rb)
49
+ return ra - rb;
50
+ if (ra === 0)
51
+ return 0;
52
+ if (ra === 1)
53
+ return a < b ? -1 : a > b ? 1 : 0;
54
+ return compareText(a, b);
55
+ }
56
+ function compareTuples(a, b) {
57
+ for (let i = 0; i < a.length; i++) {
58
+ const order = compareValues(a[i], b[i]);
59
+ if (order !== 0)
60
+ return order;
61
+ }
62
+ return 0;
63
+ }
64
+ const sameValue = (a, b) => typeRank(a) !== 0 && typeRank(a) === typeRank(b) && a === b;
65
+ const sortKeys = (keys) => keys.sort(compareText);
66
+ /** the first index whose entry satisfies `pred`, for a predicate that is false then true over the list */
67
+ function lowerBound(list, pred) {
68
+ let lo = 0;
69
+ let hi = list.length;
70
+ while (lo < hi) {
71
+ const mid = (lo + hi) >>> 1;
72
+ if (pred(list[mid]))
73
+ hi = mid;
74
+ else
75
+ lo = mid + 1;
76
+ }
77
+ return lo;
78
+ }
79
+ /**
80
+ * Lazy per-field indexes over one table. Each index is built on first use and is only an
81
+ * optimisation: a plan gives the same answer with or without one.
82
+ */
83
+ export class TableIndex {
84
+ #keys;
85
+ #rows;
86
+ #clean = new Map();
87
+ #equal = new Map();
88
+ #sorted = new Map();
89
+ #built = 0;
90
+ #entries = 0;
91
+ constructor(keys, rows) {
92
+ this.#keys = keys;
93
+ this.#rows = rows;
94
+ }
95
+ /** how many field indexes have been built */
96
+ get built() {
97
+ return this.#built;
98
+ }
99
+ /** how many entries the built indexes hold, across every field */
100
+ get entries() {
101
+ return this.#entries;
102
+ }
103
+ /** whether every row's `field` holds a value {@link plainValue} accepts */
104
+ clean(field) {
105
+ let ok = this.#clean.get(field);
106
+ if (ok === undefined) {
107
+ ok = this.#keys.every((key) => plainValue(own(this.#rows.get(key), field)));
108
+ this.#clean.set(field, ok);
109
+ }
110
+ return ok;
111
+ }
112
+ /** the keys whose `field` equals one of `values`, ascending */
113
+ equal(field, values) {
114
+ const map = this.#equalMap(field);
115
+ const single = values.length === 1 ? map.get(`${typeRank(values[0])}${String(values[0])}`) : undefined;
116
+ if (single)
117
+ return [...single];
118
+ const found = new Set();
119
+ for (const value of values) {
120
+ for (const key of map.get(`${typeRank(value)}${String(value)}`) ?? [])
121
+ found.add(key);
122
+ }
123
+ return sortKeys([...found]);
124
+ }
125
+ /** the keys whose `field` is at least or at most `value`, within the value's type, ascending */
126
+ range(field, op, value) {
127
+ const list = this.#sortedFor(`r\0${field}`, field, (v) => typeRank(v) === 0 ? undefined : v);
128
+ const rank = typeRank(value);
129
+ const blockStart = lowerBound(list, (e) => typeRank(e[0]) >= rank);
130
+ const blockEnd = lowerBound(list, (e) => typeRank(e[0]) > rank);
131
+ const [from, to] = op === 'gte'
132
+ ? [lowerBound(list, (e) => compareValues(e[0], value) >= 0), blockEnd]
133
+ : [blockStart, lowerBound(list, (e) => compareValues(e[0], value) > 0)];
134
+ return sortKeys(list.slice(Math.max(from, blockStart), to).map((e) => e[1]));
135
+ }
136
+ /** the keys whose `field` starts with `text`, ascending */
137
+ prefix(field, fold, text) {
138
+ const list = this.#sortedFor(`p\0${fold ?? ''}\0${field}`, field, (v) => typeof v === 'string' ? (fold === 'ascii' ? asciiLower(v) : v) : undefined);
139
+ const wanted = fold === 'ascii' ? asciiLower(text) : text;
140
+ const keys = [];
141
+ for (let i = lowerBound(list, (e) => compareValues(e[0], wanted) >= 0); i < list.length; i++) {
142
+ const [value, key] = list[i];
143
+ if (!value.startsWith(wanted))
144
+ break;
145
+ keys.push(key);
146
+ }
147
+ return sortKeys(keys);
148
+ }
149
+ #equalMap(field) {
150
+ let map = this.#equal.get(field);
151
+ if (!map) {
152
+ map = new Map();
153
+ for (const key of this.#keys) {
154
+ const value = own(this.#rows.get(key), field);
155
+ if (typeRank(value) === 0)
156
+ continue;
157
+ const tag = `${typeRank(value)}${String(value)}`;
158
+ const list = map.get(tag);
159
+ if (list)
160
+ list.push(key);
161
+ else
162
+ map.set(tag, [key]);
163
+ this.#entries += 1;
164
+ }
165
+ this.#equal.set(field, map);
166
+ this.#built += 1;
167
+ }
168
+ return map;
169
+ }
170
+ #sortedFor(id, field, pick) {
171
+ let list = this.#sorted.get(id);
172
+ if (!list) {
173
+ list = [];
174
+ for (const key of this.#keys) {
175
+ const value = pick(own(this.#rows.get(key), field));
176
+ if (value !== undefined)
177
+ list.push([value, key]);
178
+ }
179
+ list.sort((a, b) => compareValues(a[0], b[0]) || compareText(a[1], b[1]));
180
+ this.#sorted.set(id, list);
181
+ this.#built += 1;
182
+ this.#entries += list.length;
183
+ }
184
+ return list;
185
+ }
186
+ }
187
+ /** the value a plan reads for a field of a table, under the same rule with or without an index */
188
+ function cleanIn(table, field) {
189
+ if (table.index)
190
+ return table.index.clean(field);
191
+ return table.keys.every((key) => plainValue(own(table.rows.get(key), field)));
192
+ }
193
+ /** the field's reference: a base field (join -1) or a joined row's field */
194
+ function resolve(plan, ref) {
195
+ if (plan.from.includes(ref))
196
+ return { join: -1, field: ref };
197
+ const dot = ref.indexOf('.');
198
+ if (dot < 0)
199
+ return undefined;
200
+ const as = ref.slice(0, dot);
201
+ const field = ref.slice(dot + 1);
202
+ const join = (plan.join ?? []).findIndex((j) => j.as === as);
203
+ if (join < 0 || !(plan.join?.[join]?.fields ?? []).includes(field))
204
+ return undefined;
205
+ return { join, field };
206
+ }
207
+ function read(combo, ref) {
208
+ if (ref.join < 0)
209
+ return own(combo.base, ref.field);
210
+ const right = combo.joined[ref.join];
211
+ return right ? own(right, ref.field) : null;
212
+ }
213
+ function compileValues(cond, raw) {
214
+ if (cond.op !== 'in' && raw.length !== 1)
215
+ return null;
216
+ const out = [];
217
+ for (const text of raw) {
218
+ if (cond.type === 'number') {
219
+ if (!NUMBER_TEXT.test(text))
220
+ return null;
221
+ const n = Number(text);
222
+ if (!Number.isFinite(n))
223
+ return null;
224
+ out.push(n);
225
+ }
226
+ else {
227
+ if (text.includes('\0'))
228
+ return null;
229
+ out.push(text);
230
+ }
231
+ }
232
+ return out;
233
+ }
234
+ function matchesCondition(active, value) {
235
+ const { cond, values } = active;
236
+ if (cond.op === 'eq' || cond.op === 'in')
237
+ return values.some((v) => sameValue(value, v));
238
+ if (cond.op === 'gte' || cond.op === 'lte') {
239
+ const first = values[0];
240
+ if (typeRank(value) === 0 || typeRank(value) !== typeRank(first))
241
+ return false;
242
+ const order = compareValues(value, first);
243
+ return cond.op === 'gte' ? order >= 0 : order <= 0;
244
+ }
245
+ if (typeof value !== 'string')
246
+ return false;
247
+ const wanted = values[0];
248
+ return cond.fold === 'ascii'
249
+ ? asciiLower(value).startsWith(asciiLower(wanted))
250
+ : value.startsWith(wanted);
251
+ }
252
+ /** the keys of a joined table that a base row matches, ascending */
253
+ function matches(join, table, base) {
254
+ const value = own(base, join.on[0]);
255
+ if (join.on[1] === null) {
256
+ return typeof value === 'string' && table.rows.has(value) ? [value] : [];
257
+ }
258
+ if (typeRank(value) === 0)
259
+ return [];
260
+ const field = join.on[1];
261
+ if (table.index && table.keys.length >= INDEX_MIN_ROWS) {
262
+ return table.index.equal(field, [value]);
263
+ }
264
+ return table.keys.filter((key) => sameValue(own(table.rows.get(key), field), value));
265
+ }
266
+ function expand(joins, targets, combo, depth, out) {
267
+ if (depth === joins.length) {
268
+ out.push(combo);
269
+ return;
270
+ }
271
+ const join = joins[depth];
272
+ const table = targets[depth];
273
+ const found = matches(join, table, combo.base);
274
+ if (found.length === 0) {
275
+ if (join.type === 'left') {
276
+ expand(joins, targets, { ...combo, keys: [...combo.keys, null], joined: [...combo.joined, null] }, depth + 1, out);
277
+ }
278
+ return;
279
+ }
280
+ for (const key of found) {
281
+ const right = table.rows.get(key);
282
+ expand(joins, targets, { base: combo.base, keys: [...combo.keys, key], joined: [...combo.joined, right] }, depth + 1, out);
283
+ }
284
+ }
285
+ function aggregate(plan, agg, members) {
286
+ if (agg === 'count')
287
+ return members.length;
288
+ const [kind, field] = Object.entries(agg)[0];
289
+ const ref = resolve(plan, field);
290
+ const values = members.map((m) => read(m, ref)).filter((v) => v !== null);
291
+ if (kind === 'count')
292
+ return values.length;
293
+ if (kind === 'min' || kind === 'max') {
294
+ if (values.length === 0)
295
+ return null;
296
+ return values.reduce((best, v) => {
297
+ const order = compareValues(v, best);
298
+ return kind === 'min' ? (order < 0 ? v : best) : order > 0 ? v : best;
299
+ });
300
+ }
301
+ if (values.length === 0)
302
+ return null;
303
+ let sum = 0;
304
+ for (const v of values) {
305
+ if (typeof v !== 'number' || !Number.isSafeInteger(v))
306
+ throw new NotLocal();
307
+ sum += v;
308
+ if (!Number.isSafeInteger(sum))
309
+ throw new NotLocal();
310
+ }
311
+ return kind === 'sum' ? sum : sum / values.length;
312
+ }
313
+ function projectRow(plan, combo) {
314
+ const fields = plan.from.map((field) => [field, own(combo.base, field)]);
315
+ const joined = (plan.join ?? []).map((join, i) => {
316
+ const right = combo.joined[i];
317
+ const values = join.fields.map((field) => [field, right ? own(right, field) : null]);
318
+ return [join.as, Object.fromEntries(values)];
319
+ });
320
+ return Object.fromEntries([...fields, ...joined]);
321
+ }
322
+ function groupItems(plan, group, kept, sorts) {
323
+ const byRefs = group.by.map((field) => resolve(plan, field));
324
+ const groups = new Map();
325
+ if (group.by.length === 0)
326
+ groups.set('[]', { by: [], members: [] });
327
+ for (const combo of kept) {
328
+ const by = byRefs.map((ref) => read(combo, ref));
329
+ const tag = JSON.stringify(by.map((v) => (v === null ? '0' : `${typeRank(v)}${String(v)}`)));
330
+ const found = groups.get(tag) ?? { by, members: [] };
331
+ found.members.push(combo);
332
+ groups.set(tag, found);
333
+ }
334
+ const aggregates = Object.entries(group.aggregates);
335
+ return [...groups.values()].map(({ by, members }) => {
336
+ const row = Object.fromEntries([
337
+ ...group.by.map((field, i) => [field, by[i] ?? null]),
338
+ ...aggregates.map(([name, agg]) => [name, aggregate(plan, agg, members)])
339
+ ]);
340
+ return { row, sort: sorts.map((name) => row[name]), tie: by };
341
+ });
342
+ }
343
+ function run(plan, search, tables) {
344
+ const params = new URLSearchParams(search);
345
+ const conditions = plan.where ?? [];
346
+ const joins = plan.join ?? [];
347
+ for (const key of new Set(params.keys())) {
348
+ if (key !== 'sort' && key !== 'page' && !conditions.some((c) => c.param === key))
349
+ return null;
350
+ }
351
+ const active = [];
352
+ for (const cond of conditions) {
353
+ const raw = params.getAll(cond.param);
354
+ if (raw.length === 0)
355
+ continue;
356
+ const values = compileValues(cond, raw);
357
+ if (!values)
358
+ return null;
359
+ active.push({ cond, ref: resolve(plan, cond.field), values });
360
+ }
361
+ const sortParams = params.getAll('sort');
362
+ if (sortParams.length > 1)
363
+ return null;
364
+ const sorts = [];
365
+ if (sortParams.length === 1) {
366
+ const raw = sortParams[0];
367
+ const desc = raw.startsWith('-');
368
+ const name = desc ? raw.slice(1) : raw;
369
+ if (!(plan.sort ?? []).includes(name))
370
+ return null;
371
+ sorts.push({ name, desc });
372
+ }
373
+ const pageParams = params.getAll('page');
374
+ if (pageParams.length > 1)
375
+ return null;
376
+ let page = 1;
377
+ if (pageParams.length === 1) {
378
+ if (!PAGE.test(pageParams[0]))
379
+ return null;
380
+ page = Number(pageParams[0]);
381
+ }
382
+ const base = tables.base;
383
+ const targets = [];
384
+ for (const join of joins) {
385
+ const table = tables.joined(join.dataset);
386
+ if (!table)
387
+ return null;
388
+ targets.push(table);
389
+ }
390
+ for (const field of plan.from)
391
+ if (!cleanIn(base, field))
392
+ return null;
393
+ for (let i = 0; i < joins.length; i++) {
394
+ const join = joins[i];
395
+ const fields = join.on[1] === null ? join.fields : [...join.fields, join.on[1]];
396
+ for (const field of fields)
397
+ if (!cleanIn(targets[i], field))
398
+ return null;
399
+ }
400
+ let keys = base.keys;
401
+ const first = active.find((a) => a.ref.join < 0);
402
+ if (first && base.index && base.keys.length >= INDEX_MIN_ROWS) {
403
+ const { cond, ref, values } = first;
404
+ keys =
405
+ cond.op === 'gte' || cond.op === 'lte'
406
+ ? base.index.range(ref.field, cond.op, values[0])
407
+ : cond.op === 'prefix'
408
+ ? base.index.prefix(ref.field, cond.fold, values[0])
409
+ : base.index.equal(ref.field, values);
410
+ }
411
+ const combos = [];
412
+ for (const key of keys) {
413
+ const row = base.rows.get(key);
414
+ expand(joins, targets, { base: row, keys: [key], joined: [] }, 0, combos);
415
+ }
416
+ const kept = combos.filter((c) => active.every((a) => matchesCondition(a, read(c, a.ref))));
417
+ const group = plan.group;
418
+ const sortNames = sorts.map((s) => s.name);
419
+ let items;
420
+ if (group) {
421
+ items = groupItems(plan, group, kept, sortNames);
422
+ }
423
+ else {
424
+ if (kept.length > plan.limit)
425
+ return null;
426
+ const sortRefs = sortNames.map((name) => resolve(plan, name));
427
+ items = kept.map((combo) => ({
428
+ row: projectRow(plan, combo),
429
+ sort: sortRefs.map((ref) => read(combo, ref)),
430
+ tie: combo.keys
431
+ }));
432
+ }
433
+ if (items.length > plan.limit)
434
+ return null;
435
+ items.sort((a, b) => {
436
+ for (let i = 0; i < sorts.length; i++) {
437
+ const order = compareValues(a.sort[i], b.sort[i]);
438
+ if (order !== 0)
439
+ return sorts[i]?.desc ? -order : order;
440
+ }
441
+ return compareTuples(a.tie, b.tie);
442
+ });
443
+ const total = items.length;
444
+ const size = plan.pageSize;
445
+ const pages = Math.max(1, Math.ceil(total / size));
446
+ if (page > pages)
447
+ return null;
448
+ return {
449
+ items: items.slice((page - 1) * size, page * size).map((item) => item.row),
450
+ total,
451
+ page,
452
+ pages
453
+ };
454
+ }
455
+ /**
456
+ * Answers a query string from held tables under `plan`, or returns null when the answer is not
457
+ * local: an unknown or repeated parameter, a value the plan refuses, a float or text in a sum, a
458
+ * table that is not held, a boolean or nested value in a declared field, or more result rows than
459
+ * `limit`. Equal to the SQL the plan describes, row for row.
460
+ */
461
+ export function evaluatePlan(plan, search, tables) {
462
+ try {
463
+ return run(plan, search, tables);
464
+ }
465
+ catch (error) {
466
+ if (error instanceof NotLocal)
467
+ return null;
468
+ throw error;
469
+ }
470
+ }
471
+ /** the page data for a plan route: the stored data with the rows under `list` and a `query` view */
472
+ export function shapePlan(list, plan, data, search, tables) {
473
+ if (!tables)
474
+ return { ok: false, reason: 'plan needs its datasets' };
475
+ const result = evaluatePlan(plan, search, tables);
476
+ if (!result)
477
+ return { ok: false, reason: 'query is not one the route declares' };
478
+ const { items, total, page, pages } = result;
479
+ return {
480
+ ok: true,
481
+ data: { ...(isObject(data) ? data : {}), [list]: items, query: { total, page, pages } }
482
+ };
483
+ }
484
+ function fail(pattern, message) {
485
+ throw new ProtocolError('bad-route', `${pattern}: ${message}`);
486
+ }
487
+ const isName = (value) => typeof value === 'string' && value !== '' && !value.includes('.');
488
+ function names(pattern, value, what) {
489
+ if (!Array.isArray(value) || !value.every(isName) || new Set(value).size !== value.length) {
490
+ fail(pattern, `query.plan.${what} must be a list of distinct field names`);
491
+ }
492
+ return [...value];
493
+ }
494
+ function checkAggregate(pattern, plan, spec) {
495
+ if (spec === 'count')
496
+ return 'count';
497
+ if (!isObject(spec))
498
+ fail(pattern, 'query.plan.group.aggregates must be "count" or one aggregate object');
499
+ const kinds = Object.keys(spec);
500
+ const kind = kinds[0];
501
+ const field = spec[kind];
502
+ if (kinds.length !== 1 || !AGGREGATES.includes(kind)) {
503
+ fail(pattern, `unknown aggregate ${JSON.stringify(spec)}`);
504
+ }
505
+ if (typeof field !== 'string' || !resolve(plan, field)) {
506
+ fail(pattern, `aggregate field ${JSON.stringify(field)} is not readable`);
507
+ }
508
+ return { [kind]: field };
509
+ }
510
+ /** the validated copy of a plan; throws `bad-route` for a plan the engine could not answer exactly */
511
+ export function checkPlan(pattern, value) {
512
+ if (!isObject(value))
513
+ fail(pattern, 'query.plan must be an object');
514
+ for (const key of Object.keys(value)) {
515
+ if (!PLAN_KEYS.includes(key))
516
+ fail(pattern, `unknown query.plan option "${key}"`);
517
+ }
518
+ const from = names(pattern, value['from'], 'from');
519
+ const joins = [];
520
+ const plan = { from, join: joins, pageSize: 1, limit: 1 };
521
+ if (value['join'] !== undefined) {
522
+ if (!Array.isArray(value['join']))
523
+ fail(pattern, 'query.plan.join must be a list');
524
+ for (const raw of value['join']) {
525
+ if (!isObject(raw))
526
+ fail(pattern, 'query.plan.join entries must be objects');
527
+ for (const key of Object.keys(raw)) {
528
+ if (!['dataset', 'on', 'type', 'as', 'fields'].includes(key)) {
529
+ fail(pattern, `unknown query.plan.join option "${key}"`);
530
+ }
531
+ }
532
+ const { dataset, on, type, as } = raw;
533
+ if (typeof dataset !== 'string' || !DATASET_NAME.test(dataset)) {
534
+ fail(pattern, 'query.plan.join.dataset must be a dataset name');
535
+ }
536
+ const [onBase, onRight] = Array.isArray(on) ? on : [];
537
+ if (typeof onBase !== 'string' ||
538
+ !from.includes(onBase) ||
539
+ !(onRight === null || isName(onRight))) {
540
+ fail(pattern, 'query.plan.join.on must be [base field, right field or null]');
541
+ }
542
+ if (type !== 'inner' && type !== 'left') {
543
+ fail(pattern, 'query.plan.join.type must be "inner" or "left"');
544
+ }
545
+ if (!isName(as) || from.includes(as) || joins.some((j) => j.as === as)) {
546
+ fail(pattern, 'query.plan.join.as must be a new name');
547
+ }
548
+ joins.push({
549
+ dataset,
550
+ on: [onBase, onRight],
551
+ type,
552
+ as,
553
+ fields: names(pattern, raw['fields'], 'join.fields')
554
+ });
555
+ }
556
+ }
557
+ const where = [];
558
+ const params = new Set();
559
+ if (value['where'] !== undefined) {
560
+ if (!Array.isArray(value['where']))
561
+ fail(pattern, 'query.plan.where must be a list');
562
+ for (const raw of value['where']) {
563
+ if (!isObject(raw))
564
+ fail(pattern, 'query.plan.where entries must be objects');
565
+ for (const key of Object.keys(raw)) {
566
+ if (!['field', 'op', 'param', 'type', 'fold'].includes(key)) {
567
+ fail(pattern, `unknown query.plan.where option "${key}"`);
568
+ }
569
+ }
570
+ const { field, op, param, type, fold } = raw;
571
+ if (typeof field !== 'string' || !resolve(plan, field)) {
572
+ fail(pattern, `query.plan.where.field ${JSON.stringify(field)} is not readable`);
573
+ }
574
+ if (typeof op !== 'string' || !OPS.includes(op)) {
575
+ fail(pattern, `unknown query.plan.where operator ${JSON.stringify(op)}`);
576
+ }
577
+ if (typeof param !== 'string' || param === '' || param === 'sort' || param === 'page') {
578
+ fail(pattern, 'query.plan.where.param must be a parameter name');
579
+ }
580
+ if (params.has(param))
581
+ fail(pattern, `query.plan.where.param "${param}" is used twice`);
582
+ if (type !== 'string' && type !== 'number') {
583
+ fail(pattern, 'query.plan.where.type must be "string" or "number"');
584
+ }
585
+ if (op === 'prefix' && type !== 'string')
586
+ fail(pattern, 'prefix takes a string');
587
+ if (fold !== undefined && !(op === 'prefix' && fold === 'ascii')) {
588
+ fail(pattern, 'query.plan.where.fold is "ascii" on prefix only');
589
+ }
590
+ params.add(param);
591
+ where.push({
592
+ field,
593
+ op: op,
594
+ param,
595
+ type,
596
+ ...(fold === undefined ? {} : { fold: 'ascii' })
597
+ });
598
+ }
599
+ }
600
+ let group;
601
+ if (value['group'] !== undefined) {
602
+ const raw = value['group'];
603
+ if (!isObject(raw))
604
+ fail(pattern, 'query.plan.group must be an object');
605
+ for (const key of Object.keys(raw)) {
606
+ if (!['by', 'aggregates'].includes(key))
607
+ fail(pattern, `unknown query.plan.group option "${key}"`);
608
+ }
609
+ const by = raw['by'] === undefined ? [] : names(pattern, raw['by'], 'group.by');
610
+ if (!by.every((field) => from.includes(field))) {
611
+ fail(pattern, 'query.plan.group.by names base fields only');
612
+ }
613
+ if (!isObject(raw['aggregates']))
614
+ fail(pattern, 'query.plan.group.aggregates must be an object');
615
+ const aggregates = {};
616
+ for (const [name, spec] of Object.entries(raw['aggregates'])) {
617
+ if (!isName(name) || by.includes(name)) {
618
+ fail(pattern, `query.plan.group.aggregates cannot name "${name}"`);
619
+ }
620
+ aggregates[name] = checkAggregate(pattern, plan, spec);
621
+ }
622
+ group = { by, aggregates };
623
+ }
624
+ let sort;
625
+ if (value['sort'] !== undefined) {
626
+ if (!Array.isArray(value['sort']))
627
+ fail(pattern, 'query.plan.sort must be a list of names');
628
+ sort = [];
629
+ for (const name of value['sort']) {
630
+ if (typeof name !== 'string' ||
631
+ name === '' ||
632
+ name.startsWith('-') ||
633
+ sort.includes(name)) {
634
+ fail(pattern, `query.plan.sort cannot name ${JSON.stringify(name)}`);
635
+ }
636
+ const known = group
637
+ ? group.by.includes(name) || Object.hasOwn(group.aggregates, name)
638
+ : resolve(plan, name) !== undefined;
639
+ if (!known)
640
+ fail(pattern, `query.plan.sort names ${JSON.stringify(name)}, which is not readable`);
641
+ sort.push(name);
642
+ }
643
+ }
644
+ const { pageSize, limit } = value;
645
+ if (typeof pageSize !== 'number' || !Number.isSafeInteger(pageSize) || pageSize < 1) {
646
+ fail(pattern, 'query.plan.pageSize must be a positive integer');
647
+ }
648
+ if (typeof limit !== 'number' || !Number.isSafeInteger(limit) || limit < pageSize) {
649
+ fail(pattern, 'query.plan.limit must be an integer at least pageSize');
650
+ }
651
+ const out = { from, pageSize, limit };
652
+ if (joins.length > 0)
653
+ out.join = joins;
654
+ if (where.length > 0)
655
+ out.where = where;
656
+ if (group)
657
+ out.group = group;
658
+ if (sort)
659
+ out.sort = sort;
660
+ return out;
661
+ }