@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,189 @@
1
+ import { PROTOCOL_VERSION } from './artifact.js';
2
+ import type { Plain, SetProof } from './query.js';
3
+ import type { Identity } from './route.js';
4
+ /** a row of a dataset: a flat or nested JSON object, replaced whole when it changes */
5
+ export type DatasetRow = Plain;
6
+ /** what a dataset's functions receive; a public dataset has no identity */
7
+ export type DatasetContext = {
8
+ /** the request being answered */
9
+ request: Request;
10
+ /** the request URL, parsed */
11
+ url: URL;
12
+ /** who is asking; set for a principal dataset and absent, not null, for a public one */
13
+ principal?: Identity;
14
+ };
15
+ /** what `seed` receives: the context, and the key after which to start when the request pages */
16
+ export type DatasetSeedContext = DatasetContext & {
17
+ /** rows with a key at or before this are not wanted; a backend may use it to skip them */
18
+ after?: string;
19
+ };
20
+ /** a row that left the dataset, and the cursor at which it did */
21
+ export type DatasetDelete = {
22
+ key: string;
23
+ cursor: number;
24
+ };
25
+ /**
26
+ * What `changes` returns: the net change since a cursor. A key appears in `puts` or in `deletes`,
27
+ * never both. A row that entered the dataset's scope with its own version unchanged is a put; a row
28
+ * that left the scope is a delete. Deciding scope membership is `changes`' job, and spool cannot see
29
+ * it. `proof` is the set proof of the whole collection at `cursor`, when the backend keeps one.
30
+ */
31
+ export type DatasetChanges = {
32
+ /** the cursor these changes bring a device to */
33
+ cursor: number;
34
+ /** keys of the rows to send whole; spool reads them with `read` */
35
+ puts: readonly string[];
36
+ /** keys of the rows to remove */
37
+ deletes: readonly DatasetDelete[];
38
+ /** the collection's proof at `cursor`; without it spool reads the whole collection to make one */
39
+ proof?: SetProof;
40
+ };
41
+ /** what `head` returns: the dataset's current cursor and, when the backend keeps one, its proof */
42
+ export type DatasetHead = {
43
+ /** the current cursor; a device that seeds at it asks for changes after it */
44
+ cursor: number;
45
+ /** the proof at `cursor` */
46
+ proof?: SetProof;
47
+ };
48
+ type MaybePromise<T> = T | Promise<T>;
49
+ /** the declaration `defineDataset` takes */
50
+ export type DatasetDeclaration<Row extends DatasetRow = DatasetRow> = {
51
+ /**
52
+ * `public` rows are the same for everyone. A `principal` dataset holds rows that differ per
53
+ * signed-in principal; it needs `maxStaleMs`, `defineDataset`'s `principalDatasets` option and
54
+ * `createSpool`'s `principalDatasets` flag. Unreviewed.
55
+ */
56
+ scope: 'public' | 'principal';
57
+ /**
58
+ * Principal datasets only, and required there: how long held rows may answer a query after the
59
+ * last sync that returned and verified. Past it the query goes to the network. It is also the
60
+ * longest a device keeps serving rows after the server stopped admitting its principal.
61
+ */
62
+ maxStaleMs?: number;
63
+ /** the row's key; unique, and stable while the row exists */
64
+ key(row: Row): string;
65
+ /**
66
+ * Every row in ascending key order (code unit order), as an array or as pages of rows. With
67
+ * `ctx.after` set it may start after that key. It runs once to admit a seed and once per page.
68
+ */
69
+ seed(ctx: DatasetSeedContext): MaybePromise<readonly Row[] | Iterable<readonly Row[]> | AsyncIterable<readonly Row[]>>;
70
+ /** a keyed read: the rows for these keys, omitting any that no longer exist; never a full load */
71
+ read(ids: readonly string[], ctx: DatasetContext): MaybePromise<readonly Row[]>;
72
+ /** the net change since `since`, or `reset` when it cannot answer */
73
+ changes(since: number, ctx: DatasetContext): MaybePromise<DatasetChanges | 'reset'>;
74
+ /** the oldest cursor `changes` can still answer; a device older than this reseeds */
75
+ horizon(ctx: DatasetContext): MaybePromise<number>;
76
+ /** the current cursor, read before a seed so every later change reaches the device */
77
+ head(ctx: DatasetContext): MaybePromise<DatasetHead>;
78
+ /** a version string for the row shape; a device holding another one reseeds */
79
+ schema: string;
80
+ /** most rows a seed may hold */
81
+ maxRows: number;
82
+ /** most bytes of row JSON a seed may hold */
83
+ maxBytes: number;
84
+ /**
85
+ * Principal datasets only: the field names of `row` that `viewer` may hold, from `null` for an
86
+ * anonymous request. The server sends each viewer only those fields, so the device never holds
87
+ * the others. Absent, every field goes to every viewer.
88
+ */
89
+ fields?(viewer: Identity | null, row: Row): readonly string[];
90
+ /**
91
+ * `always` (the default) answers every seed. `auto` answers a seed only while `datasetBenefit`
92
+ * says the dataset beats both v0.3 and native HTTP; otherwise the seed is refused with `409`.
93
+ */
94
+ provision?: 'always' | 'auto';
95
+ };
96
+ /** a validated dataset */
97
+ export type Dataset<Row extends DatasetRow = DatasetRow> = DatasetDeclaration<Row> & {
98
+ /** the name a device asks for */
99
+ name: string;
100
+ };
101
+ /** what `defineDataset` may be told besides the declaration */
102
+ export type DefineDatasetOptions = {
103
+ /** accept `scope: 'principal'`; `createSpool` still refuses it unless its own flag is on */
104
+ principalDatasets?: boolean;
105
+ };
106
+ /**
107
+ * Declares a dataset. Validates the name, the scope and the limits and returns the declaration with
108
+ * the name attached. Throws `bad-dataset` for a principal scope unless `options.principalDatasets`
109
+ * is true, and for a principal dataset without a positive `maxStaleMs` or with `provision: 'auto'`.
110
+ */
111
+ export declare function defineDataset<Row extends DatasetRow = DatasetRow>(name: string, declaration: DatasetDeclaration<Row>, options?: DefineDatasetOptions): Dataset<Row>;
112
+ /** rows in a seed page when the request names no `limit` */
113
+ export declare const DATASET_PAGE_ROWS = 500;
114
+ /** the most rows one seed page may carry, whatever `limit` asks for */
115
+ export declare const DATASET_PAGE_CAP = 5000;
116
+ /** a row with its key, as it travels */
117
+ export type DatasetPut = {
118
+ key: string;
119
+ row: DatasetRow;
120
+ };
121
+ /**
122
+ * The body of `/.spool/dataset`. A patch has `reset: false` and `proof`. A seed, or a reset, has
123
+ * `reset: true` and one page of rows in `puts`: a page with `next` set is followed by a request
124
+ * with `after=<next>`, and the last page has no `next` and carries `proof`. A page after the first
125
+ * echoes that `after`.
126
+ */
127
+ export type DatasetResponse = {
128
+ protocol: typeof PROTOCOL_VERSION;
129
+ name: string;
130
+ schema: string;
131
+ /** the cursor the response brings a device to */
132
+ cursor: number;
133
+ /** the device drops every row it holds before applying `puts` (unless `after` is set) */
134
+ reset: boolean;
135
+ puts: DatasetPut[];
136
+ deletes: DatasetDelete[];
137
+ /** on a seed page after the first: the key the request paged from */
138
+ after?: string;
139
+ /** on a seed page with more to come: the `after` of the next request */
140
+ next?: string;
141
+ /** the collection's proof at `cursor`; absent on a seed page that has a `next` */
142
+ proof?: SetProof;
143
+ };
144
+ /** what a device asks of `/.spool/dataset` */
145
+ export type DatasetRequest = {
146
+ name: string;
147
+ /** the cursor the device holds; absent for a seed */
148
+ since?: number;
149
+ /** the schema the device holds; required with `since` */
150
+ schema?: string;
151
+ /** the key to page from; seed pages only */
152
+ after?: string;
153
+ /** rows per seed page; the server's default when absent */
154
+ limit?: number;
155
+ };
156
+ /** the query string of a request, for `/.spool/dataset?` */
157
+ export declare function encodeDatasetRequest(request: DatasetRequest): string;
158
+ /** reads a request's parameters; throws `bad-dataset` for a missing name, a bad number, or `since` with `after` */
159
+ export declare function parseDatasetRequest(params: URLSearchParams): DatasetRequest;
160
+ /** validates JSON from `/.spool/dataset`; throws `bad-dataset` */
161
+ export declare function parseDatasetResponse(value: unknown): DatasetResponse;
162
+ /** what {@link applyChanges} returns */
163
+ export type Applied = {
164
+ /** the rows after the response, a new map */
165
+ rows: Map<string, DatasetRow>;
166
+ /** the collection's digest after the response */
167
+ digest: string;
168
+ /** whether the result matches `response.proof`; null when the response carries none */
169
+ matches: boolean | null;
170
+ /** the row hashes after the response; present when the caller passed `options.hashes` */
171
+ hashes?: Map<string, string>;
172
+ };
173
+ /** what {@link applyChanges} may be given besides the rows and the response */
174
+ export type ApplyOptions = {
175
+ /** the hash of every row in `rows`; a replaced or deleted row then costs no hash of its old copy */
176
+ hashes?: ReadonlyMap<string, string>;
177
+ /** the row hash function; {@link rowHash} when absent */
178
+ hash?: (key: string, row: DatasetRow) => Promise<string>;
179
+ };
180
+ /**
181
+ * Applies a response to `rows` and returns the result, leaving `rows` as it was. A reset response
182
+ * without `after` starts from no rows; a later seed page adds to what is held. Deletes apply
183
+ * before puts. `digest` is the digest of `rows` when the caller holds it, which makes the work one
184
+ * row hash per replaced, deleted or added row; without it the digest of `rows` is computed first.
185
+ * With `options.hashes` a replaced or deleted row's old hash is read, not computed, and the result
186
+ * carries the hashes after the response. Pure: no I/O, no clock.
187
+ */
188
+ export declare function applyChanges(rows: ReadonlyMap<string, DatasetRow>, response: DatasetResponse, digest?: string, options?: ApplyOptions): Promise<Applied>;
189
+ export {};
@@ -0,0 +1,212 @@
1
+ import { PROTOCOL_VERSION } from './artifact.js';
2
+ import { ProtocolError } from './errors.js';
3
+ import { DATASET_NAME, digestAdd, digestSub, EMPTY_DIGEST, isSetProof, rowHash, setProof } from './query.js';
4
+ const NAME = DATASET_NAME;
5
+ function bad(name, message) {
6
+ throw new ProtocolError('bad-dataset', `${name}: ${message}`);
7
+ }
8
+ /**
9
+ * Declares a dataset. Validates the name, the scope and the limits and returns the declaration with
10
+ * the name attached. Throws `bad-dataset` for a principal scope unless `options.principalDatasets`
11
+ * is true, and for a principal dataset without a positive `maxStaleMs` or with `provision: 'auto'`.
12
+ */
13
+ export function defineDataset(name, declaration, options = {}) {
14
+ if (typeof name !== 'string' || !NAME.test(name)) {
15
+ return bad(String(name), 'a dataset name is 1 to 128 of letters, digits and . _ : -');
16
+ }
17
+ const scope = declaration.scope;
18
+ if (scope === 'principal' && options.principalDatasets !== true) {
19
+ return bad(name, 'a principal dataset needs the principal datasets flag: pass { principalDatasets: true } here and set the principalDatasets option of createSpool');
20
+ }
21
+ if (scope !== 'public' && scope !== 'principal')
22
+ return bad(name, `unknown scope "${scope}"`);
23
+ if (declaration.fields !== undefined) {
24
+ if (scope !== 'principal')
25
+ return bad(name, 'fields applies to a principal dataset');
26
+ if (typeof declaration.fields !== 'function')
27
+ return bad(name, 'fields must be a function');
28
+ }
29
+ if (scope === 'principal') {
30
+ const stale = declaration.maxStaleMs;
31
+ if (typeof stale !== 'number' || !Number.isSafeInteger(stale) || stale < 1) {
32
+ return bad(name, 'a principal dataset needs maxStaleMs, a positive integer of milliseconds');
33
+ }
34
+ if (declaration.provision === 'auto') {
35
+ return bad(name, 'a principal dataset cannot use provision "auto"');
36
+ }
37
+ }
38
+ else if (declaration.maxStaleMs !== undefined) {
39
+ return bad(name, 'maxStaleMs applies to a principal dataset');
40
+ }
41
+ for (const fn of ['key', 'seed', 'read', 'changes', 'horizon', 'head']) {
42
+ if (typeof declaration[fn] !== 'function')
43
+ return bad(name, `${fn} must be a function`);
44
+ }
45
+ if (typeof declaration.schema !== 'string' || declaration.schema === '') {
46
+ return bad(name, 'schema must be a non-empty string');
47
+ }
48
+ for (const limit of ['maxRows', 'maxBytes']) {
49
+ const value = declaration[limit];
50
+ if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
51
+ return bad(name, `${limit} must be a positive integer`);
52
+ }
53
+ }
54
+ if (declaration.provision !== undefined &&
55
+ !['always', 'auto'].includes(declaration.provision)) {
56
+ return bad(name, 'provision must be "always" or "auto"');
57
+ }
58
+ return { ...declaration, name };
59
+ }
60
+ /** rows in a seed page when the request names no `limit` */
61
+ export const DATASET_PAGE_ROWS = 500;
62
+ /** the most rows one seed page may carry, whatever `limit` asks for */
63
+ export const DATASET_PAGE_CAP = 5000;
64
+ function reject(message) {
65
+ throw new ProtocolError('bad-dataset', message);
66
+ }
67
+ const INTEGER = /^\d{1,15}$/;
68
+ /** the query string of a request, for `/.spool/dataset?` */
69
+ export function encodeDatasetRequest(request) {
70
+ const params = new URLSearchParams({ name: request.name });
71
+ if (request.since !== undefined)
72
+ params.set('since', String(request.since));
73
+ if (request.schema !== undefined)
74
+ params.set('schema', request.schema);
75
+ if (request.after !== undefined)
76
+ params.set('after', request.after);
77
+ if (request.limit !== undefined)
78
+ params.set('limit', String(request.limit));
79
+ return params.toString();
80
+ }
81
+ /** reads a request's parameters; throws `bad-dataset` for a missing name, a bad number, or `since` with `after` */
82
+ export function parseDatasetRequest(params) {
83
+ const name = params.get('name');
84
+ if (name === null || !NAME.test(name))
85
+ return reject('name is required');
86
+ const out = { name };
87
+ const since = params.get('since');
88
+ if (since !== null) {
89
+ if (!INTEGER.test(since))
90
+ return reject('since must be a non-negative integer');
91
+ out.since = Number(since);
92
+ }
93
+ const schema = params.get('schema');
94
+ if (schema !== null)
95
+ out.schema = schema;
96
+ const after = params.get('after');
97
+ if (after !== null)
98
+ out.after = after;
99
+ const limit = params.get('limit');
100
+ if (limit !== null) {
101
+ if (!/^[1-9]\d{0,8}$/.test(limit))
102
+ return reject('limit must be a positive integer');
103
+ out.limit = Math.min(Number(limit), DATASET_PAGE_CAP);
104
+ }
105
+ if (out.since !== undefined && out.schema === undefined) {
106
+ return reject('since needs the schema the device holds');
107
+ }
108
+ if (out.since !== undefined && out.after !== undefined) {
109
+ return reject('since and after are exclusive');
110
+ }
111
+ return out;
112
+ }
113
+ const isPlain = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
114
+ const isCursor = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
115
+ /** validates JSON from `/.spool/dataset`; throws `bad-dataset` */
116
+ export function parseDatasetResponse(value) {
117
+ if (!isPlain(value))
118
+ return reject('dataset response must be an object');
119
+ if (value['protocol'] !== PROTOCOL_VERSION)
120
+ return reject('unsupported protocol version');
121
+ const { name, schema, cursor, reset, puts, deletes, after, next, proof } = value;
122
+ if (typeof name !== 'string' || typeof schema !== 'string') {
123
+ return reject('name and schema must be strings');
124
+ }
125
+ if (!isCursor(cursor))
126
+ return reject('cursor must be a non-negative integer');
127
+ if (typeof reset !== 'boolean')
128
+ return reject('reset must be a boolean');
129
+ if (!Array.isArray(puts))
130
+ return reject('puts must be a list');
131
+ const outPuts = puts.map((put) => {
132
+ if (!isPlain(put) || typeof put['key'] !== 'string' || !isPlain(put['row'])) {
133
+ return reject('a put is { key, row }');
134
+ }
135
+ return { key: put['key'], row: put['row'] };
136
+ });
137
+ if (!Array.isArray(deletes))
138
+ return reject('deletes must be a list');
139
+ const outDeletes = deletes.map((del) => {
140
+ if (!isPlain(del) || typeof del['key'] !== 'string' || !isCursor(del['cursor'])) {
141
+ return reject('a delete is { key, cursor }');
142
+ }
143
+ return { key: del['key'], cursor: del['cursor'] };
144
+ });
145
+ const out = {
146
+ protocol: PROTOCOL_VERSION,
147
+ name,
148
+ schema,
149
+ cursor,
150
+ reset,
151
+ puts: outPuts,
152
+ deletes: outDeletes
153
+ };
154
+ if (after !== undefined) {
155
+ if (typeof after !== 'string')
156
+ return reject('after must be a string');
157
+ out.after = after;
158
+ }
159
+ if (next !== undefined) {
160
+ if (typeof next !== 'string')
161
+ return reject('next must be a string');
162
+ out.next = next;
163
+ }
164
+ if (proof !== undefined) {
165
+ if (!isSetProof(proof))
166
+ return reject('proof must be a set proof');
167
+ out.proof = { kind: 'set', count: proof.count, digest: proof.digest };
168
+ }
169
+ if (out.next === undefined && out.proof === undefined) {
170
+ return reject('a response without next carries a proof');
171
+ }
172
+ return out;
173
+ }
174
+ /**
175
+ * Applies a response to `rows` and returns the result, leaving `rows` as it was. A reset response
176
+ * without `after` starts from no rows; a later seed page adds to what is held. Deletes apply
177
+ * before puts. `digest` is the digest of `rows` when the caller holds it, which makes the work one
178
+ * row hash per replaced, deleted or added row; without it the digest of `rows` is computed first.
179
+ * With `options.hashes` a replaced or deleted row's old hash is read, not computed, and the result
180
+ * carries the hashes after the response. Pure: no I/O, no clock.
181
+ */
182
+ export async function applyChanges(rows, response, digest, options = {}) {
183
+ const hash = options.hash ?? rowHash;
184
+ const fresh = response.reset && response.after === undefined;
185
+ const out = new Map(fresh ? [] : rows);
186
+ const hashes = options.hashes ? new Map(fresh ? [] : options.hashes) : undefined;
187
+ let sum = fresh ? EMPTY_DIGEST : (digest ?? (await setProof(rows)).digest);
188
+ const drop = async (key) => {
189
+ const old = out.get(key);
190
+ if (old === undefined)
191
+ return;
192
+ sum = digestSub(sum, hashes?.get(key) ?? (await hash(key, old)));
193
+ out.delete(key);
194
+ hashes?.delete(key);
195
+ };
196
+ for (const { key } of response.deletes)
197
+ await drop(key);
198
+ for (const { key, row } of response.puts) {
199
+ await drop(key);
200
+ out.set(key, row);
201
+ const added = await hash(key, row);
202
+ hashes?.set(key, added);
203
+ sum = digestAdd(sum, added);
204
+ }
205
+ const proof = response.proof;
206
+ return {
207
+ rows: out,
208
+ digest: sum,
209
+ matches: proof === undefined ? null : proof.count === out.size && proof.digest === sum,
210
+ ...(hashes ? { hashes } : {})
211
+ };
212
+ }
@@ -1,4 +1,5 @@
1
- import { type Scope } from './artifact.js';
1
+ import { PROTOCOL_VERSION, type Scope } from './artifact.js';
2
+ import { type SyncResponse } from './sync.js';
2
3
  /** the header names, lowercase as `Headers` reports them */
3
4
  export declare const HEADERS: {
4
5
  readonly protocol: "spool-protocol";
@@ -9,6 +10,9 @@ export declare const HEADERS: {
9
10
  readonly partition: "spool-partition";
10
11
  readonly vectorSeen: "spool-vector-seen";
11
12
  readonly provision: "spool-provision";
13
+ readonly provisionReason: "spool-provision-reason";
14
+ readonly delta: "spool-delta";
15
+ readonly have: "spool-have";
12
16
  };
13
17
  /** `Spool-Clear` token that wipes everything the worker holds */
14
18
  export declare const CLEAR_ALL = "*";
@@ -47,3 +51,32 @@ export declare function writeEnvelope(headers: Headers, envelope: Envelope): voi
47
51
  export declare function decodeEnvelopeOrClear(headers: Headers): Envelope | undefined;
48
52
  /** reads the spool headers; throws `ProtocolError` on a malformed one */
49
53
  export declare function decodeEnvelope(headers: Headers): Envelope;
54
+ /** the names of the events `/.spool/live` sends, each as the SSE `event` field with one JSON `data` line */
55
+ export declare const LIVE_EVENTS: readonly ["hello", "lease", "delta", "revoked"];
56
+ /** the name of a live event */
57
+ export type LiveEventName = (typeof LIVE_EVENTS)[number];
58
+ /** what each live event carries */
59
+ export type LiveEvents = {
60
+ /** first on every stream: the protocol and the cursor the stream's own deltas follow */
61
+ hello: {
62
+ protocol: typeof PROTOCOL_VERSION;
63
+ cursor: number;
64
+ };
65
+ /**
66
+ * The session is good for `leaseMs` from the moment the page reads the event, and again after the
67
+ * next one. It is a duration so a device clock that is wrong does not change it.
68
+ */
69
+ lease: {
70
+ leaseMs: number;
71
+ };
72
+ /** the tags changed after `from` up to `cursor`, as a `/.spool/sync` answer; public information only */
73
+ delta: LiveDelta;
74
+ /** the session behind the stream ended; the stream closes after this event */
75
+ revoked: Record<string, never>;
76
+ };
77
+ /** a `/.spool/sync` answer for the tags changed after `from`, pushed */
78
+ export type LiveDelta = SyncResponse & {
79
+ from: number;
80
+ };
81
+ /** reads the `data` of a `delta` event; throws `ProtocolError` on a malformed one */
82
+ export declare function parseLiveDelta(value: unknown): LiveDelta;
@@ -1,5 +1,6 @@
1
1
  import { PROTOCOL_VERSION } from './artifact.js';
2
2
  import { ProtocolError } from './errors.js';
3
+ import { parseSyncResponse } from './sync.js';
3
4
  /** the header names, lowercase as `Headers` reports them */
4
5
  export const HEADERS = {
5
6
  protocol: 'spool-protocol',
@@ -9,7 +10,10 @@ export const HEADERS = {
9
10
  vector: 'spool-vector',
10
11
  partition: 'spool-partition',
11
12
  vectorSeen: 'spool-vector-seen',
12
- provision: 'spool-provision'
13
+ provision: 'spool-provision',
14
+ provisionReason: 'spool-provision-reason',
15
+ delta: 'spool-delta',
16
+ have: 'spool-have'
13
17
  };
14
18
  /** `Spool-Clear` token that wipes everything the worker holds */
15
19
  export const CLEAR_ALL = '*';
@@ -170,3 +174,14 @@ export function decodeEnvelope(headers) {
170
174
  }
171
175
  return out;
172
176
  }
177
+ /** the names of the events `/.spool/live` sends, each as the SSE `event` field with one JSON `data` line */
178
+ export const LIVE_EVENTS = ['hello', 'lease', 'delta', 'revoked'];
179
+ /** reads the `data` of a `delta` event; throws `ProtocolError` on a malformed one */
180
+ export function parseLiveDelta(value) {
181
+ const sync = parseSyncResponse(value);
182
+ const from = value.from;
183
+ if (typeof from !== 'number' || !Number.isSafeInteger(from) || from < 0) {
184
+ return bad('from must be a non-negative integer');
185
+ }
186
+ return { ...sync, from };
187
+ }
@@ -1,5 +1,5 @@
1
1
  /** why a protocol value was refused */
2
- export type ProtocolErrorCode = 'bad-pattern' | 'bad-route' | 'bad-header' | 'bad-artifact' | 'bad-sync' | 'bad-beacon' | 'bad-template' | 'bad-manifest' | 'bad-nav';
2
+ export type ProtocolErrorCode = 'bad-pattern' | 'bad-route' | 'bad-header' | 'bad-artifact' | 'bad-sync' | 'bad-bundle' | 'bad-beacon' | 'bad-template' | 'bad-manifest' | 'bad-nav' | 'bad-dataset' | 'dataset-limit' | 'dataset-forbidden' | 'bad-write';
3
3
  /** thrown for malformed protocol input; `code` names the family so callers can map it to a status */
4
4
  export declare class ProtocolError extends Error {
5
5
  readonly code: ProtocolErrorCode;
@@ -6,8 +6,15 @@ export type RecordRef = {
6
6
  export type ProjectionRef = {
7
7
  $projection: string;
8
8
  };
9
+ /**
10
+ * a reference to a row of a dataset the device holds, as `<dataset>/<key>`; the page keeps the id
11
+ * and the row resolves when the page renders, so a change to the row needs no new artifact
12
+ */
13
+ export type RowRef = {
14
+ $row: string;
15
+ };
9
16
  /** what a page's data carries in place of a record or projection stored once elsewhere */
10
- export type Ref = RecordRef | ProjectionRef;
17
+ export type Ref = RecordRef | ProjectionRef | RowRef;
11
18
  /** an authoritative piece of data, stored once by id; its id is the tag that invalidates it */
12
19
  export type RecordEntry = {
13
20
  id: string;
@@ -24,23 +31,33 @@ export type ProjectionEntry = {
24
31
  /** a tree that may reference records and other projections */
25
32
  data: unknown;
26
33
  };
27
- /** the id lists {@link collectRefs} found */
34
+ /** the id lists {@link collectRefs} found; `rows` is set only when there are row references */
28
35
  export type RefSet = {
29
36
  records: string[];
30
37
  projections: string[];
38
+ rows?: string[];
31
39
  };
32
40
  /** the reference to put in a page's data for record `id` */
33
41
  export declare function recordRef(id: string): RecordRef;
34
42
  /** the reference to put in a page's data for projection `id` */
35
43
  export declare function projectionRef(id: string): ProjectionRef;
44
+ /** the reference to put in a page's data for the row `key` of dataset `dataset` */
45
+ export declare function rowRef(dataset: string, key: string): RowRef;
46
+ /** splits a row id into its dataset name and key; the name never holds a `/`, so the first one splits */
47
+ export declare function splitRowId(id: string): {
48
+ dataset: string;
49
+ key: string;
50
+ } | null;
36
51
  /** whether `value` is exactly a reference, with no other keys */
37
52
  export declare function isRef(value: unknown): value is Ref;
38
- /** every record and projection id referenced anywhere in `value`, sorted and unique */
53
+ /** every record, projection and row id referenced anywhere in `value`, sorted and unique */
39
54
  export declare function collectRefs(value: unknown): RefSet;
40
- /** where {@link resolveRefs} looks references up */
55
+ /** where {@link resolveRefs} looks references up; without `row`, a row reference is a refusal */
41
56
  export type RefLookup = {
42
57
  record(id: string): RecordEntry | undefined;
43
58
  projection(id: string): ProjectionEntry | undefined;
59
+ /** the held row `key` of `dataset`, or undefined when it is not held */
60
+ row?(dataset: string, key: string): unknown;
44
61
  };
45
62
  /** the tree with every reference replaced by what it points at, or the first one that is missing */
46
63
  export type Resolved = {
@@ -71,6 +88,8 @@ export type Collected = {
71
88
  export type Collector = {
72
89
  record(id: string, data: unknown): RecordRef;
73
90
  projection(id: string, data: unknown, deps?: readonly string[]): ProjectionRef;
91
+ /** the reference to a dataset row; nothing is registered, the device resolves it from its rows */
92
+ row(dataset: string, key: string): RowRef;
74
93
  /** everything registered so far; throws when a projection reaches an unregistered or cyclic one */
75
94
  collect(version: number): Collected;
76
95
  };
@@ -1,4 +1,5 @@
1
1
  import { ProtocolError } from './errors.js';
2
+ import { DATASET_NAME } from './query.js';
2
3
  /** the reference to put in a page's data for record `id` */
3
4
  export function recordRef(id) {
4
5
  return { $record: id };
@@ -7,6 +8,20 @@ export function recordRef(id) {
7
8
  export function projectionRef(id) {
8
9
  return { $projection: id };
9
10
  }
11
+ /** the reference to put in a page's data for the row `key` of dataset `dataset` */
12
+ export function rowRef(dataset, key) {
13
+ if (!DATASET_NAME.test(dataset) || key === '') {
14
+ bad('a row reference needs a dataset name and a non-empty key');
15
+ }
16
+ return { $row: `${dataset}/${key}` };
17
+ }
18
+ /** splits a row id into its dataset name and key; the name never holds a `/`, so the first one splits */
19
+ export function splitRowId(id) {
20
+ const at = id.indexOf('/');
21
+ if (at < 1 || at === id.length - 1)
22
+ return null;
23
+ return { dataset: id.slice(0, at), key: id.slice(at + 1) };
24
+ }
10
25
  function isPlain(value) {
11
26
  return typeof value === 'object' && value !== null && !Array.isArray(value);
12
27
  }
@@ -18,12 +33,14 @@ export function isRef(value) {
18
33
  if (keys.length !== 1)
19
34
  return false;
20
35
  const key = keys[0];
21
- return (key === '$record' || key === '$projection') && typeof value[key] === 'string';
36
+ return ((key === '$record' || key === '$projection' || key === '$row') &&
37
+ typeof value[key] === 'string');
22
38
  }
23
- /** every record and projection id referenced anywhere in `value`, sorted and unique */
39
+ /** every record, projection and row id referenced anywhere in `value`, sorted and unique */
24
40
  export function collectRefs(value) {
25
41
  const records = new Set();
26
42
  const projections = new Set();
43
+ const rows = new Set();
27
44
  const walk = (node) => {
28
45
  if (Array.isArray(node))
29
46
  return node.forEach(walk);
@@ -32,6 +49,8 @@ export function collectRefs(value) {
32
49
  if (isRef(node)) {
33
50
  if ('$record' in node)
34
51
  records.add(node.$record);
52
+ else if ('$row' in node)
53
+ rows.add(node.$row);
35
54
  else
36
55
  projections.add(node.$projection);
37
56
  return;
@@ -39,7 +58,11 @@ export function collectRefs(value) {
39
58
  Object.values(node).forEach(walk);
40
59
  };
41
60
  walk(value);
42
- return { records: [...records].sort(), projections: [...projections].sort() };
61
+ return {
62
+ records: [...records].sort(),
63
+ projections: [...projections].sort(),
64
+ ...(rows.size > 0 ? { rows: [...rows].sort() } : {})
65
+ };
43
66
  }
44
67
  /**
45
68
  * Replaces every reference in `value` with the record's data or the projection's resolved tree.
@@ -59,6 +82,13 @@ export function resolveRefs(value, lookup) {
59
82
  throw new Error(`record ${node.$record} is not stored`);
60
83
  return record.data;
61
84
  }
85
+ if ('$row' in node) {
86
+ const at = splitRowId(node.$row);
87
+ const row = at ? lookup.row?.(at.dataset, at.key) : undefined;
88
+ if (row === undefined)
89
+ throw new Error(`row ${node.$row} is not held`);
90
+ return row;
91
+ }
62
92
  const id = node.$projection;
63
93
  if (path.includes(id))
64
94
  throw new Error(`projection ${id} reaches itself`);
@@ -157,6 +187,7 @@ export function createCollector() {
157
187
  projections.set(id, { data, deps, text: json });
158
188
  return projectionRef(id);
159
189
  },
190
+ row: rowRef,
160
191
  collect(vector) {
161
192
  const closure = (id, path) => {
162
193
  if (path.includes(id))
@@ -0,0 +1,22 @@
1
+ import type { DatasetRow } from './dataset.js';
2
+ import type { SerializedRoute } from './route.js';
3
+ /** the part of a route the index tables read; a route and a serialized route both carry it */
4
+ export type IndexRoute = Pick<SerializedRoute, 'pattern' | 'scope' | 'family' | 'query'>;
5
+ /** the family routes that index a row by its path, and the fields each dataset's queries read */
6
+ export type IndexPlan = {
7
+ paths: Array<{
8
+ dataset: string;
9
+ pattern: string;
10
+ key: string;
11
+ }>;
12
+ fields: Map<string, string[]>;
13
+ };
14
+ /** one index row: its table, its key, and its value, or `null` when the row leaves the index */
15
+ export type IndexRow = [table: string, key: string, row: DatasetRow | null];
16
+ /** the index tables a route set asks for, read from its public routes */
17
+ export declare function indexPlan(routes: readonly IndexRoute[]): IndexPlan;
18
+ /**
19
+ * The index rows of one row of `dataset`. With no `row` the key leaves the index: the same tables
20
+ * come back with `null` values, since a path depends on the key alone.
21
+ */
22
+ export declare function indexRowsOf(plan: IndexPlan, dataset: string, key: string, row?: DatasetRow): IndexRow[];