@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,625 @@
1
+ import { HEADERS } from '../protocol/envelope.js';
2
+ import { indexPlan, indexRowsOf } from '../protocol/index-rows.js';
3
+ import { matchPattern } from '../protocol/pattern.js';
4
+ import { applyPatch, isWriteKey, isWriteVersion, newWriteId, WRITE_HEADERS, WRITE_STATUS } from '../protocol/write.js';
5
+ import { seal, unseal } from './seal.js';
6
+ const DB = 'spool-writes';
7
+ const QUEUE = 'queue';
8
+ const encoder = new TextEncoder();
9
+ /** a queue in memory, for tests */
10
+ export function memoryWriteStore() {
11
+ const rows = new Map();
12
+ const slot = (name, key) => `${name}\u0000${key}`;
13
+ return {
14
+ get: async (name, key) => structuredClone(rows.get(slot(name, key))),
15
+ put: async (record) => void rows.set(slot(record.name, record.key), structuredClone(record)),
16
+ delete: async (name, key) => void rows.delete(slot(name, key)),
17
+ all: async () => structuredClone([...rows.values()])
18
+ };
19
+ }
20
+ function wrap(request) {
21
+ return new Promise((resolve, reject) => {
22
+ request.onsuccess = () => resolve(request.result);
23
+ request.onerror = () => reject(request.error);
24
+ });
25
+ }
26
+ function done(tx) {
27
+ return new Promise((resolve, reject) => {
28
+ tx.oncomplete = () => resolve();
29
+ tx.onerror = () => reject(tx.error);
30
+ tx.onabort = () => reject(tx.error);
31
+ });
32
+ }
33
+ const rangeOf = (partition) => IDBKeyRange.bound([partition], [partition, []]);
34
+ /**
35
+ * The queue of one partition in its own database, `spool-writes` at version 1 (the shared `spool`
36
+ * database is never raised: older workers open it at 2). A row is `{ partition, name, key, sealed }`:
37
+ * the partition, class and key stay readable as the keys, and the value, the versions, the write
38
+ * id and the conflict are AES-GCM ciphertext under the partition's persistent key, bound to the
39
+ * partition, class and key as additional data. A persistent key is used for every queue, since a key
40
+ * that lives in the worker's memory would lose an unflushed value when the browser stops the worker.
41
+ * The database is created by the first call that reaches the store.
42
+ */
43
+ export function idbWriteStore(factory, partition, vault) {
44
+ let opened;
45
+ const open = () => (opened ??= new Promise((resolve, reject) => {
46
+ const request = factory.open(DB, 1);
47
+ request.onupgradeneeded = () => {
48
+ request.result.createObjectStore(QUEUE, { keyPath: ['partition', 'name', 'key'] });
49
+ };
50
+ request.onsuccess = () => {
51
+ const db = request.result;
52
+ db.onversionchange = () => {
53
+ db.close();
54
+ opened = undefined;
55
+ };
56
+ resolve(db);
57
+ };
58
+ request.onerror = () => reject(request.error);
59
+ }));
60
+ const aad = (name, key) => `${partition}\u0000write\u0000${name}\u0000${key}`;
61
+ async function inStore(mode, run) {
62
+ const db = await open();
63
+ const tx = db.transaction(QUEUE, mode);
64
+ const finished = done(tx);
65
+ const result = await run(tx.objectStore(QUEUE));
66
+ await finished;
67
+ return result;
68
+ }
69
+ const read = async (row) => row && (await unseal(vault, partition, aad(row.name, row.key), row));
70
+ return {
71
+ get: async (name, key) => read(await inStore('readonly', (s) => wrap(s.get([partition, name, key])))),
72
+ put: async (record) => {
73
+ const key = await vault.get(partition, 'persistent', true);
74
+ if (!key)
75
+ throw new Error('no key');
76
+ const sealed = await seal(key, aad(record.name, record.key), record, 'persistent');
77
+ await inStore('readwrite', async (s) => {
78
+ await wrap(s.put({ partition, name: record.name, key: record.key, ...sealed }));
79
+ });
80
+ },
81
+ delete: (name, key) => inStore('readwrite', async (s) => void (await wrap(s.delete([partition, name, key])))),
82
+ all: async () => {
83
+ const rows = await inStore('readonly', (s) => wrap(s.getAll(rangeOf(partition))));
84
+ const out = [];
85
+ for (const row of rows) {
86
+ const value = await read(row);
87
+ if (value)
88
+ out.push(value);
89
+ else {
90
+ await inStore('readwrite', async (s) => void (await wrap(s.delete([partition, row.name, row.key]))));
91
+ }
92
+ }
93
+ return out;
94
+ }
95
+ };
96
+ }
97
+ /**
98
+ * Deletes every row of `partition` from `spool-writes`. A database that was never created stays
99
+ * uncreated: the open is rolled back when it would have made one.
100
+ */
101
+ export async function destroyWrites(factory, partition) {
102
+ const db = await new Promise((resolve) => {
103
+ const request = factory.open(DB);
104
+ request.onupgradeneeded = () => {
105
+ try {
106
+ request.transaction?.abort();
107
+ }
108
+ catch {
109
+ // nothing was created
110
+ }
111
+ };
112
+ request.onsuccess = () => resolve(request.result);
113
+ request.onerror = () => resolve(null);
114
+ request.onblocked = () => resolve(null);
115
+ });
116
+ if (!db)
117
+ return;
118
+ try {
119
+ if (!db.objectStoreNames.contains(QUEUE))
120
+ return;
121
+ const tx = db.transaction(QUEUE, 'readwrite');
122
+ const finished = done(tx);
123
+ tx.objectStore(QUEUE).delete(rangeOf(partition));
124
+ await finished;
125
+ }
126
+ catch {
127
+ // the rows are sealed under a key that is shredded alongside
128
+ }
129
+ finally {
130
+ db.close();
131
+ }
132
+ }
133
+ const browserTimers = {
134
+ set: (fn, ms) => setTimeout(fn, ms),
135
+ clear: (handle) => clearTimeout(handle)
136
+ };
137
+ const refuse = (code, message) => ({
138
+ ok: false,
139
+ code,
140
+ message
141
+ });
142
+ const REFUSAL_CODES = new Set(Object.keys(WRITE_STATUS));
143
+ const codeOf = (body) => {
144
+ const code = body?.code;
145
+ return typeof code === 'string' && REFUSAL_CODES.has(code)
146
+ ? code
147
+ : undefined;
148
+ };
149
+ function conflictOf(body) {
150
+ const conflict = body
151
+ ?.conflict;
152
+ if (!conflict || !isWriteVersion(conflict.version))
153
+ return undefined;
154
+ return 'value' in conflict
155
+ ? { version: conflict.version, value: conflict.value }
156
+ : { version: conflict.version };
157
+ }
158
+ /**
159
+ * The device queue of one partition for declared writes of the `last-value` kind. One record holds
160
+ * the newest value of a `(class, key)` and the version its first edit started from, and a flush sends
161
+ * one request per record. A record leaves the queue only after the server answers 200; any failure
162
+ * leaves it, and a retry sends the same write id. A 412 or a permanent refusal parks the record as
163
+ * `conflicted` with its local value, and nothing sends it again until `resolve`. Every change to the
164
+ * store runs one at a time, and `kill` stops all of them, so a wipe cannot be followed by a send or
165
+ * a store change.
166
+ */
167
+ export class WriteQueue {
168
+ #deps;
169
+ #timers;
170
+ #tail = Promise.resolve();
171
+ #flushing = null;
172
+ #dead = false;
173
+ #timer;
174
+ constructor(deps) {
175
+ this.#deps = deps;
176
+ this.#timers = deps.timers ?? browserTimers;
177
+ }
178
+ /** stops the queue for good: no later call sends or stores anything */
179
+ kill() {
180
+ this.#dead = true;
181
+ this.#disarm();
182
+ }
183
+ /** the deadline a record of `name` falls due at, when its class has one */
184
+ #dueFor(name, now) {
185
+ const delay = this.#deps.classes().find((c) => c.name === name)?.maxDelayMs;
186
+ return delay === undefined ? undefined : now + delay;
187
+ }
188
+ /** sets the timer for `at` unless an earlier one is set */
189
+ #arm(at) {
190
+ if (this.#dead || (this.#timer !== undefined && this.#timer.at <= at))
191
+ return;
192
+ this.#disarm();
193
+ const handle = this.#timers.set(() => this.#fire(), Math.max(0, at - this.#deps.now()));
194
+ this.#timer = { at, handle };
195
+ }
196
+ #disarm() {
197
+ if (this.#timer !== undefined)
198
+ this.#timers.clear(this.#timer.handle);
199
+ this.#timer = undefined;
200
+ }
201
+ #fire() {
202
+ this.#timer = undefined;
203
+ return this.flushDue().catch(() => ({ queued: 0, flushed: 0, conflicted: 0 }));
204
+ }
205
+ /** the earliest deadline a stored record holds, or undefined when none does */
206
+ async #earliest(after = -Infinity) {
207
+ const dues = (await this.#deps.store.all())
208
+ .filter((r) => r.state !== 'conflicted' && r.due !== undefined)
209
+ .map((r) => r.due)
210
+ .filter((due) => due > after);
211
+ return dues.length > 0 ? Math.min(...dues) : undefined;
212
+ }
213
+ /**
214
+ * Sets the timer to the earliest deadline still ahead, or clears it. A deadline already past is left
215
+ * to a later contact, so a store that keeps failing cannot turn the timer into a loop.
216
+ */
217
+ async #rearm() {
218
+ const earliest = await this.#earliest(this.#deps.now());
219
+ this.#disarm();
220
+ if (earliest !== undefined)
221
+ this.#arm(earliest);
222
+ }
223
+ /**
224
+ * Sends every queued record when the earliest deadline has passed, and arms the timer for a later
225
+ * one. The worker calls it at a timer fire and at the first contact of each start, so a record
226
+ * whose deadline passed while the worker was stopped goes out once.
227
+ */
228
+ async flushDue() {
229
+ const earliest = await this.#serial(async () => this.#dead ? undefined : this.#earliest());
230
+ if (earliest === undefined)
231
+ return { queued: 0, flushed: 0, conflicted: 0 };
232
+ if (earliest > this.#deps.now()) {
233
+ this.#arm(earliest);
234
+ return { queued: 0, flushed: 0, conflicted: 0 };
235
+ }
236
+ return this.flush();
237
+ }
238
+ #serial(fn) {
239
+ const run = this.#tail.then(fn, fn);
240
+ this.#tail = run.catch(() => undefined);
241
+ return run;
242
+ }
243
+ /**
244
+ * Queues `value` as the newest for `(name, key)`. An edit folds into the record already there and
245
+ * keeps the version the first edit started from. When a request for the earlier value may have
246
+ * left, the edit waits in `next` so that request and its retry stay byte-identical.
247
+ */
248
+ write(name, key, value, version) {
249
+ if (this.#dead)
250
+ return Promise.resolve(refuse('no-partition', 'the queue was wiped'));
251
+ const config = this.#deps.classes().find((c) => c.name === name);
252
+ if (!config)
253
+ return Promise.resolve(refuse('unknown-write', `no write class "${name}"`));
254
+ if (!isWriteKey(key))
255
+ return Promise.resolve(refuse('bad-key', 'the key is malformed'));
256
+ if (version === undefined || version === null) {
257
+ return Promise.resolve(refuse('missing-version', 'say which version the edit started from'));
258
+ }
259
+ if (!isWriteVersion(version)) {
260
+ return Promise.resolve(refuse('bad-version', 'the version is malformed'));
261
+ }
262
+ let bytes;
263
+ try {
264
+ const text = JSON.stringify({ value });
265
+ if (value === undefined)
266
+ throw new Error('no value');
267
+ bytes = encoder.encode(text).length;
268
+ }
269
+ catch {
270
+ return Promise.resolve(refuse('bad-body', 'the value is not JSON'));
271
+ }
272
+ if (bytes > config.maxBytes) {
273
+ return Promise.resolve(refuse('too-large', `the value is over ${config.maxBytes} bytes`));
274
+ }
275
+ return this.#serial(async () => {
276
+ if (this.#dead)
277
+ return refuse('no-partition', 'the queue was wiped');
278
+ const now = this.#deps.now();
279
+ const held = await this.#deps.store.get(name, key);
280
+ if (!held) {
281
+ const pending = (await this.#deps.store.all()).filter((r) => r.name === name).length;
282
+ if (pending >= config.maxPending) {
283
+ return refuse('too-many', `${config.maxPending} keys of "${name}" are already queued`);
284
+ }
285
+ const due = this.#dueFor(name, now);
286
+ const record = {
287
+ name,
288
+ key,
289
+ value,
290
+ base: version,
291
+ id: newWriteId(),
292
+ state: 'pending',
293
+ queuedAt: now,
294
+ updatedAt: now,
295
+ bytes,
296
+ edits: 1,
297
+ attempts: 0,
298
+ ...(due === undefined ? {} : { due })
299
+ };
300
+ await this.#deps.store.put(record);
301
+ if (due !== undefined)
302
+ this.#arm(due);
303
+ return { ok: true, state: record.state, edits: 1 };
304
+ }
305
+ const sent = held.state === 'flushing' || held.attempts > 0;
306
+ const due = held.due ?? (held.state === 'conflicted' ? undefined : this.#dueFor(name, now));
307
+ const next = {
308
+ ...held,
309
+ updatedAt: now,
310
+ edits: held.edits + 1,
311
+ ...(due === undefined ? {} : { due }),
312
+ ...(sent && held.state !== 'conflicted'
313
+ ? { next: { value, bytes } }
314
+ : { value, bytes })
315
+ };
316
+ await this.#deps.store.put(next);
317
+ if (due !== undefined)
318
+ this.#arm(due);
319
+ return { ok: true, state: next.state, edits: next.edits };
320
+ });
321
+ }
322
+ /** what the page may see of each queued value */
323
+ list() {
324
+ return this.#serial(async () => {
325
+ if (this.#dead)
326
+ return [];
327
+ const records = await this.#deps.store.all();
328
+ return records
329
+ .sort((a, b) => a.queuedAt - b.queuedAt || (a.key < b.key ? -1 : 1))
330
+ .map((r) => ({
331
+ name: r.name,
332
+ key: r.key,
333
+ state: r.state,
334
+ base: r.base,
335
+ queuedAt: r.queuedAt,
336
+ updatedAt: r.updatedAt,
337
+ bytes: r.bytes,
338
+ attempts: r.attempts,
339
+ ...(r.conflict ? { conflict: r.conflict } : {}),
340
+ ...(r.refusal ? { refusal: r.refusal } : {})
341
+ }));
342
+ });
343
+ }
344
+ /**
345
+ * Sends one request per record that is not conflicted, or only `only`'s record, and reports
346
+ * counts. A flush already running is joined. A network failure, a sign-in answer and a turned-off
347
+ * server stop the pass and leave the rest queued.
348
+ */
349
+ flush(only) {
350
+ if (this.#flushing && !only)
351
+ return this.#flushing;
352
+ const run = this.#run(only);
353
+ if (!only) {
354
+ this.#flushing = run.finally(() => {
355
+ this.#flushing = null;
356
+ });
357
+ return this.#flushing;
358
+ }
359
+ return run;
360
+ }
361
+ async #run(only) {
362
+ const counts = { queued: 0, flushed: 0, conflicted: 0 };
363
+ if (this.#dead)
364
+ return counts;
365
+ const records = await this.#serial(async () => this.#dead ? [] : (await this.#deps.store.all()).filter((r) => r.state !== 'conflicted'));
366
+ for (const listed of records) {
367
+ if (only && (listed.name !== only.name || listed.key !== only.key))
368
+ continue;
369
+ const sending = await this.#serial(async () => {
370
+ if (this.#dead)
371
+ return undefined;
372
+ const current = await this.#deps.store.get(listed.name, listed.key);
373
+ if (!current || current.state === 'conflicted')
374
+ return undefined;
375
+ const record = { ...current, state: 'flushing' };
376
+ await this.#deps.store.put(record);
377
+ return record;
378
+ });
379
+ if (!sending)
380
+ continue;
381
+ counts.queued += 1;
382
+ let answer;
383
+ try {
384
+ answer = await this.#deps.send(sending);
385
+ }
386
+ catch {
387
+ answer = undefined;
388
+ }
389
+ // a store that fails leaves the record `flushing`; the retry sends the same id and body
390
+ const stop = await this.#serial(() => this.#settle(sending, answer, counts)).catch(() => true);
391
+ if (stop)
392
+ break;
393
+ }
394
+ if (counts.queued > 0 && !this.#dead)
395
+ this.#deps.onFlush?.(counts);
396
+ if (!this.#dead)
397
+ await this.#serial(() => this.#rearm());
398
+ return counts;
399
+ }
400
+ /** applies the answer to the record, in one store step; true when the pass should stop */
401
+ async #settle(sent, answer, counts) {
402
+ if (this.#dead)
403
+ return true;
404
+ const { store } = this.#deps;
405
+ const now = this.#deps.now();
406
+ const current = await store.get(sent.name, sent.key);
407
+ if (!current)
408
+ return false;
409
+ const retry = async (bumped) => {
410
+ // a failed flush closes the deadline: the record waits for a moment, a start or a new write
411
+ const { due: _due, ...rest } = current;
412
+ await store.put({
413
+ ...rest,
414
+ state: 'pending',
415
+ updatedAt: now,
416
+ attempts: current.attempts + (bumped ? 1 : 0)
417
+ });
418
+ return true;
419
+ };
420
+ if (!answer)
421
+ return retry(true);
422
+ const { status, body } = answer;
423
+ if (status === 200) {
424
+ const version = body?.version;
425
+ if (!isWriteVersion(version))
426
+ return retry(true);
427
+ counts.flushed += 1;
428
+ if (!current.next) {
429
+ await store.delete(current.name, current.key);
430
+ return false;
431
+ }
432
+ const { value, bytes } = current.next;
433
+ const due = this.#dueFor(current.name, now);
434
+ await store.put({
435
+ name: current.name,
436
+ key: current.key,
437
+ value,
438
+ bytes,
439
+ base: version,
440
+ id: newWriteId(),
441
+ state: 'pending',
442
+ queuedAt: current.queuedAt,
443
+ updatedAt: now,
444
+ edits: 1,
445
+ attempts: 0,
446
+ ...(due === undefined ? {} : { due })
447
+ });
448
+ return false;
449
+ }
450
+ const code = codeOf(body);
451
+ if (status === 412) {
452
+ const conflict = conflictOf(body);
453
+ if (conflict) {
454
+ counts.conflicted += 1;
455
+ await store.put(this.#park(current, now, { conflict }));
456
+ return false;
457
+ }
458
+ counts.conflicted += 1;
459
+ await store.put(this.#park(current, now, { refusal: 'unavailable' }));
460
+ return false;
461
+ }
462
+ if (status === 401 || status === 429 || code === 'writes-off' || code === 'sign-in') {
463
+ return retry(false);
464
+ }
465
+ if (status >= 500 || status === 408)
466
+ return retry(true);
467
+ counts.conflicted += 1;
468
+ await store.put(this.#park(current, now, { refusal: code ?? 'unavailable' }));
469
+ return false;
470
+ }
471
+ /** the record as `conflicted`, keeping the newest local value */
472
+ #park(record, now, why) {
473
+ const { next: later, conflict: _c, refusal: _r, due: _d, ...rest } = record;
474
+ return {
475
+ ...rest,
476
+ ...(later ? { value: later.value, bytes: later.bytes } : {}),
477
+ state: 'conflicted',
478
+ updatedAt: now,
479
+ ...why
480
+ };
481
+ }
482
+ /**
483
+ * Settles a conflicted record. `local` keeps the local value, re-bases it onto the server's
484
+ * version, gives it a new write id and flushes that key. `server` drops the local value and
485
+ * returns what the server held.
486
+ */
487
+ async resolve(name, key, use) {
488
+ if (this.#dead)
489
+ return refuse('no-partition', 'the queue was wiped');
490
+ if (use !== 'local' && use !== 'server') {
491
+ return refuse('bad-body', 'resolve with "local" or "server"');
492
+ }
493
+ const outcome = await this.#serial(async () => {
494
+ if (this.#dead)
495
+ return refuse('no-partition', 'the queue was wiped');
496
+ const held = await this.#deps.store.get(name, key);
497
+ if (!held)
498
+ return refuse('no-record', 'nothing is queued for that key');
499
+ if (held.state !== 'conflicted') {
500
+ return refuse('not-conflicted', 'that record has no conflict to resolve');
501
+ }
502
+ if (use === 'server') {
503
+ await this.#deps.store.delete(name, key);
504
+ return { ok: true, ...(held.conflict ? { server: held.conflict } : {}) };
505
+ }
506
+ const { conflict, refusal: _r, ...rest } = held;
507
+ await this.#deps.store.put({
508
+ ...rest,
509
+ base: conflict?.version ?? held.base,
510
+ id: newWriteId(),
511
+ state: 'pending',
512
+ updatedAt: this.#deps.now(),
513
+ edits: 1,
514
+ attempts: 0
515
+ });
516
+ return { ok: true };
517
+ });
518
+ if (!outcome.ok || use === 'server')
519
+ return outcome;
520
+ return { ok: true, flush: await this.flush({ name, key }) };
521
+ }
522
+ }
523
+ const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
524
+ /** the row and its index rows as a prediction; `row` absent predicts the removal of the key */
525
+ function changeOf(plan, dataset, key, row) {
526
+ const entries = [
527
+ [dataset, key, row ?? null],
528
+ ...indexRowsOf(plan, dataset, key, row)
529
+ ];
530
+ return {
531
+ puts: entries.flatMap(([table, id, value]) => value === null ? [] : [[table, id, value]]),
532
+ deletes: entries.flatMap(([table, id, value]) => value === null ? [[table, id]] : [])
533
+ };
534
+ }
535
+ /**
536
+ * Predicts the rows a declared write changed when the answer named no version and sent no delta. The
537
+ * prediction is unconfirmed until the next verified delta settles it; `invalidate` predicts nothing.
538
+ */
539
+ async function predict(response, pack, { write, url, body, routes }) {
540
+ const plan = indexPlan(routes);
541
+ const pathKey = matchPattern(write.pattern, url.pathname)?.[write.key];
542
+ const { dataset } = write;
543
+ if (write.apply === 'invalidate')
544
+ return;
545
+ if (write.apply === 'delete') {
546
+ if (pathKey !== undefined)
547
+ await pack.applyPredicted(changeOf(plan, dataset, pathKey));
548
+ return;
549
+ }
550
+ if (write.apply === 'response') {
551
+ const row = await response
552
+ .clone()
553
+ .json()
554
+ .catch(() => undefined);
555
+ if (!isRecord(row))
556
+ return;
557
+ const id = row[write.key];
558
+ if (typeof id !== 'string' && typeof id !== 'number')
559
+ return;
560
+ const key = String(id);
561
+ if (pathKey !== undefined && pathKey !== key)
562
+ return;
563
+ await pack.applyPredicted(changeOf(plan, dataset, key, row));
564
+ return;
565
+ }
566
+ if (pathKey === undefined)
567
+ return;
568
+ const held = await pack.getRow(dataset, pathKey);
569
+ if (!held)
570
+ return;
571
+ const next = write.apply === 'merge'
572
+ ? isRecord(body)
573
+ ? { ...held, ...body }
574
+ : undefined
575
+ : applyPatch(held, body, write.apply);
576
+ if (next)
577
+ await pack.applyPredicted(changeOf(plan, dataset, pathKey, next));
578
+ }
579
+ /**
580
+ * Brings the held pack to the version a declared write's answer reached. The answer's `Spool-Delta` goes
581
+ * first; one that starts at another version, or that the store refuses, costs one delta fetch to the
582
+ * version the answer names. An answer that names no version and sends no delta is predicted from the
583
+ * write's mode when `sent` is given. An answer with a digest and no delta is predicted, and the digest
584
+ * confirms the prediction or drops it at the cost of one delta fetch. An answer that landed on another
585
+ * origin, after a redirect, applies nothing.
586
+ */
587
+ export async function settleWrite(response, pack, fetchDelta, expected, sent) {
588
+ if (!response.url || new URL(response.url).origin !== expected)
589
+ return;
590
+ const head = await pack.head();
591
+ if (!head)
592
+ return;
593
+ const header = response.headers.get(HEADERS.delta);
594
+ const inline = header === null ? undefined : JSON.parse(header);
595
+ if (inline?.from === head.version) {
596
+ try {
597
+ await pack.applyDelta(inline);
598
+ return;
599
+ }
600
+ catch {
601
+ // refused; the delta route below brings the pack up to the answer's version
602
+ }
603
+ }
604
+ const vector = response.headers.get(HEADERS.vector);
605
+ const reached = inline?.to ?? (vector === null ? undefined : Number(vector));
606
+ if (reached === undefined) {
607
+ if (sent)
608
+ await predict(response, pack, sent);
609
+ return;
610
+ }
611
+ if (!Number.isSafeInteger(reached) || reached <= head.version)
612
+ return;
613
+ const digest = response.headers.get(WRITE_HEADERS.digest);
614
+ if (inline === undefined && sent && digest !== null) {
615
+ await predict(response, pack, sent);
616
+ try {
617
+ await pack.confirmPredicted(reached, digest);
618
+ return;
619
+ }
620
+ catch {
621
+ await pack.dropPredicted();
622
+ }
623
+ }
624
+ await pack.applyDelta(await fetchDelta(head.version, reached));
625
+ }
package/dist/version.d.ts CHANGED
@@ -1,2 +1,2 @@
1
1
  /** the package version; the service worker and page runtime compare it on the handshake */
2
- export declare const VERSION: string;
2
+ export declare const VERSION = "1.0.0";
package/dist/version.js CHANGED
@@ -1,3 +1,2 @@
1
- import pkg from '../package.json' with { type: 'json' };
2
1
  /** the package version; the service worker and page runtime compare it on the handshake */
3
- export const VERSION = pkg.version;
2
+ export const VERSION = '1.0.0';
@@ -0,0 +1,26 @@
1
+ import type { Plugin, ResolvedConfig } from 'vite';
2
+ import { type StaticOption } from '../plugins/static.js';
3
+ import type { Spool } from '../server/spool.js';
4
+ export type { StaticBuildContext, StaticBuildOptions, StaticOption } from '../plugins/static.js';
5
+ /** what `spoolVite` takes */
6
+ export type SpoolViteOptions = {
7
+ /** the instance the app's routes were declared for; the dev server answers from it */
8
+ spool: Spool;
9
+ /**
10
+ * Publishes the static tier into the build's output directory when a client build ends: the page
11
+ * runtime, the worker script, the packs and a `_headers` rule, all served by a static host with no
12
+ * Worker invocation. On by default; `false` turns it off, and an object sets `policy`, `url` or a
13
+ * `spool` made from the build output. The dev server does not publish.
14
+ */
15
+ static?: StaticOption;
16
+ };
17
+ /**
18
+ * A Vite plugin. In `serve` it injects the page runtime tag into HTML entries and serves the worker
19
+ * script and spool's paths from `spool`, and logs each fetch or XHR GET of the dev server's own
20
+ * origin that no data family covers. In a client `build` it publishes the static tier into the
21
+ * output directory (see `static`). The built HTML gets no tag from the plugin: a build goes to the
22
+ * app's spool server, which adds the same tag to each response.
23
+ */
24
+ export declare function spoolVite(options: SpoolViteOptions): Omit<Plugin, 'configResolved'> & {
25
+ configResolved(config: ResolvedConfig): void;
26
+ };