@drupflare/spool 0.2.0 → 0.4.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 (118) hide show
  1. package/README.md +499 -43
  2. package/dist/cdn/client.js +1 -1
  3. package/dist/cdn/manifest.json +7 -7
  4. package/dist/cdn/spool-sw.js +1 -1
  5. package/dist/client/activity.d.ts +37 -0
  6. package/dist/client/activity.js +114 -0
  7. package/dist/client/entry.js +34 -1
  8. package/dist/client/index.d.ts +1 -0
  9. package/dist/client/index.js +1 -0
  10. package/dist/client/register.d.ts +23 -1
  11. package/dist/client/register.js +53 -7
  12. package/dist/media/embeds.d.ts +3 -2
  13. package/dist/media/embeds.js +16 -1
  14. package/dist/protocol/config.d.ts +16 -1
  15. package/dist/protocol/config.js +3 -1
  16. package/dist/protocol/dataset.d.ts +183 -0
  17. package/dist/protocol/dataset.js +206 -0
  18. package/dist/protocol/envelope.d.ts +3 -0
  19. package/dist/protocol/envelope.js +14 -3
  20. package/dist/protocol/errors.d.ts +1 -1
  21. package/dist/protocol/graph.d.ts +23 -4
  22. package/dist/protocol/graph.js +34 -3
  23. package/dist/protocol/hash.d.ts +2 -0
  24. package/dist/protocol/hash.js +8 -0
  25. package/dist/protocol/index.d.ts +7 -0
  26. package/dist/protocol/index.js +7 -0
  27. package/dist/protocol/inline.d.ts +14 -0
  28. package/dist/protocol/inline.js +43 -0
  29. package/dist/protocol/navigation.d.ts +81 -0
  30. package/dist/protocol/navigation.js +249 -0
  31. package/dist/protocol/normalise.d.ts +4 -3
  32. package/dist/protocol/normalise.js +6 -4
  33. package/dist/protocol/plan.d.ts +100 -0
  34. package/dist/protocol/plan.js +661 -0
  35. package/dist/protocol/provision.d.ts +52 -1
  36. package/dist/protocol/provision.js +53 -5
  37. package/dist/protocol/query.d.ts +141 -0
  38. package/dist/protocol/query.js +252 -0
  39. package/dist/protocol/route.d.ts +85 -5
  40. package/dist/protocol/route.js +91 -0
  41. package/dist/protocol/write.d.ts +146 -0
  42. package/dist/protocol/write.js +101 -0
  43. package/dist/proxy/bases.d.ts +53 -0
  44. package/dist/proxy/bases.js +76 -0
  45. package/dist/proxy/index.d.ts +1 -0
  46. package/dist/proxy/index.js +1 -0
  47. package/dist/proxy/proxy.js +8 -2
  48. package/dist/report/capacity.d.ts +59 -0
  49. package/dist/report/capacity.js +76 -0
  50. package/dist/report/channels.d.ts +60 -0
  51. package/dist/report/channels.js +65 -0
  52. package/dist/report/dataset.d.ts +48 -0
  53. package/dist/report/dataset.js +93 -0
  54. package/dist/report/derive.d.ts +285 -0
  55. package/dist/report/derive.js +676 -1
  56. package/dist/report/economics.d.ts +11 -1
  57. package/dist/report/economics.js +19 -1
  58. package/dist/report/index.d.ts +5 -0
  59. package/dist/report/index.js +5 -0
  60. package/dist/report/inputs.d.ts +97 -0
  61. package/dist/report/inputs.js +133 -0
  62. package/dist/report/institution.d.ts +284 -0
  63. package/dist/report/institution.js +225 -0
  64. package/dist/report/ledger.d.ts +28 -0
  65. package/dist/report/ledger.js +30 -0
  66. package/dist/report/loops.d.ts +73 -0
  67. package/dist/report/loops.js +101 -0
  68. package/dist/report/measurement.d.ts +1 -1
  69. package/dist/report/measurement.js +6 -1
  70. package/dist/report/model.d.ts +2 -0
  71. package/dist/report/model.js +4 -0
  72. package/dist/report/thirdparty.d.ts +57 -0
  73. package/dist/report/thirdparty.js +111 -0
  74. package/dist/report/traffic.d.ts +11 -2
  75. package/dist/report/traffic.js +13 -3
  76. package/dist/report/trim.d.ts +56 -0
  77. package/dist/report/trim.js +83 -1
  78. package/dist/server/dataset.d.ts +48 -0
  79. package/dist/server/dataset.js +308 -0
  80. package/dist/server/embedded.d.ts +3 -3
  81. package/dist/server/embedded.js +3 -3
  82. package/dist/server/index.d.ts +3 -0
  83. package/dist/server/index.js +3 -0
  84. package/dist/server/spool.d.ts +40 -0
  85. package/dist/server/spool.js +184 -23
  86. package/dist/server/write.d.ts +27 -0
  87. package/dist/server/write.js +127 -0
  88. package/dist/sw/analytics.d.ts +6 -0
  89. package/dist/sw/analytics.js +14 -0
  90. package/dist/sw/dataset-sync.d.ts +76 -0
  91. package/dist/sw/dataset-sync.js +149 -0
  92. package/dist/sw/dataset.d.ts +91 -0
  93. package/dist/sw/dataset.js +318 -0
  94. package/dist/sw/graph/index.d.ts +31 -1
  95. package/dist/sw/graph/index.js +57 -5
  96. package/dist/sw/graph/invalidate.d.ts +15 -3
  97. package/dist/sw/graph/invalidate.js +42 -4
  98. package/dist/sw/idb.js +78 -9
  99. package/dist/sw/partition.d.ts +6 -1
  100. package/dist/sw/partition.js +21 -2
  101. package/dist/sw/principal-dataset.d.ts +64 -0
  102. package/dist/sw/principal-dataset.js +254 -0
  103. package/dist/sw/render.d.ts +8 -1
  104. package/dist/sw/render.js +28 -1
  105. package/dist/sw/replica.d.ts +14 -3
  106. package/dist/sw/replica.js +46 -5
  107. package/dist/sw/router.js +2 -2
  108. package/dist/sw/runtime.d.ts +43 -2
  109. package/dist/sw/runtime.js +440 -29
  110. package/dist/sw/seal.d.ts +13 -0
  111. package/dist/sw/seal.js +13 -4
  112. package/dist/sw/static.d.ts +18 -0
  113. package/dist/sw/static.js +84 -1
  114. package/dist/sw/storage.d.ts +51 -1
  115. package/dist/sw/storage.js +33 -1
  116. package/dist/sw/write.d.ts +107 -0
  117. package/dist/sw/write.js +442 -0
  118. package/package.json +5 -2
@@ -0,0 +1,206 @@
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 (scope === 'principal') {
24
+ const stale = declaration.maxStaleMs;
25
+ if (typeof stale !== 'number' || !Number.isSafeInteger(stale) || stale < 1) {
26
+ return bad(name, 'a principal dataset needs maxStaleMs, a positive integer of milliseconds');
27
+ }
28
+ if (declaration.provision === 'auto') {
29
+ return bad(name, 'a principal dataset cannot use provision "auto"');
30
+ }
31
+ }
32
+ else if (declaration.maxStaleMs !== undefined) {
33
+ return bad(name, 'maxStaleMs applies to a principal dataset');
34
+ }
35
+ for (const fn of ['key', 'seed', 'read', 'changes', 'horizon', 'head']) {
36
+ if (typeof declaration[fn] !== 'function')
37
+ return bad(name, `${fn} must be a function`);
38
+ }
39
+ if (typeof declaration.schema !== 'string' || declaration.schema === '') {
40
+ return bad(name, 'schema must be a non-empty string');
41
+ }
42
+ for (const limit of ['maxRows', 'maxBytes']) {
43
+ const value = declaration[limit];
44
+ if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
45
+ return bad(name, `${limit} must be a positive integer`);
46
+ }
47
+ }
48
+ if (declaration.provision !== undefined &&
49
+ !['always', 'auto'].includes(declaration.provision)) {
50
+ return bad(name, 'provision must be "always" or "auto"');
51
+ }
52
+ return { ...declaration, name };
53
+ }
54
+ /** rows in a seed page when the request names no `limit` */
55
+ export const DATASET_PAGE_ROWS = 500;
56
+ /** the most rows one seed page may carry, whatever `limit` asks for */
57
+ export const DATASET_PAGE_CAP = 5000;
58
+ function reject(message) {
59
+ throw new ProtocolError('bad-dataset', message);
60
+ }
61
+ const INTEGER = /^\d{1,15}$/;
62
+ /** the query string of a request, for `/.spool/dataset?` */
63
+ export function encodeDatasetRequest(request) {
64
+ const params = new URLSearchParams({ name: request.name });
65
+ if (request.since !== undefined)
66
+ params.set('since', String(request.since));
67
+ if (request.schema !== undefined)
68
+ params.set('schema', request.schema);
69
+ if (request.after !== undefined)
70
+ params.set('after', request.after);
71
+ if (request.limit !== undefined)
72
+ params.set('limit', String(request.limit));
73
+ return params.toString();
74
+ }
75
+ /** reads a request's parameters; throws `bad-dataset` for a missing name, a bad number, or `since` with `after` */
76
+ export function parseDatasetRequest(params) {
77
+ const name = params.get('name');
78
+ if (name === null || !NAME.test(name))
79
+ return reject('name is required');
80
+ const out = { name };
81
+ const since = params.get('since');
82
+ if (since !== null) {
83
+ if (!INTEGER.test(since))
84
+ return reject('since must be a non-negative integer');
85
+ out.since = Number(since);
86
+ }
87
+ const schema = params.get('schema');
88
+ if (schema !== null)
89
+ out.schema = schema;
90
+ const after = params.get('after');
91
+ if (after !== null)
92
+ out.after = after;
93
+ const limit = params.get('limit');
94
+ if (limit !== null) {
95
+ if (!/^[1-9]\d{0,8}$/.test(limit))
96
+ return reject('limit must be a positive integer');
97
+ out.limit = Math.min(Number(limit), DATASET_PAGE_CAP);
98
+ }
99
+ if (out.since !== undefined && out.schema === undefined) {
100
+ return reject('since needs the schema the device holds');
101
+ }
102
+ if (out.since !== undefined && out.after !== undefined) {
103
+ return reject('since and after are exclusive');
104
+ }
105
+ return out;
106
+ }
107
+ const isPlain = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
108
+ const isCursor = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
109
+ /** validates JSON from `/.spool/dataset`; throws `bad-dataset` */
110
+ export function parseDatasetResponse(value) {
111
+ if (!isPlain(value))
112
+ return reject('dataset response must be an object');
113
+ if (value['protocol'] !== PROTOCOL_VERSION)
114
+ return reject('unsupported protocol version');
115
+ const { name, schema, cursor, reset, puts, deletes, after, next, proof } = value;
116
+ if (typeof name !== 'string' || typeof schema !== 'string') {
117
+ return reject('name and schema must be strings');
118
+ }
119
+ if (!isCursor(cursor))
120
+ return reject('cursor must be a non-negative integer');
121
+ if (typeof reset !== 'boolean')
122
+ return reject('reset must be a boolean');
123
+ if (!Array.isArray(puts))
124
+ return reject('puts must be a list');
125
+ const outPuts = puts.map((put) => {
126
+ if (!isPlain(put) || typeof put['key'] !== 'string' || !isPlain(put['row'])) {
127
+ return reject('a put is { key, row }');
128
+ }
129
+ return { key: put['key'], row: put['row'] };
130
+ });
131
+ if (!Array.isArray(deletes))
132
+ return reject('deletes must be a list');
133
+ const outDeletes = deletes.map((del) => {
134
+ if (!isPlain(del) || typeof del['key'] !== 'string' || !isCursor(del['cursor'])) {
135
+ return reject('a delete is { key, cursor }');
136
+ }
137
+ return { key: del['key'], cursor: del['cursor'] };
138
+ });
139
+ const out = {
140
+ protocol: PROTOCOL_VERSION,
141
+ name,
142
+ schema,
143
+ cursor,
144
+ reset,
145
+ puts: outPuts,
146
+ deletes: outDeletes
147
+ };
148
+ if (after !== undefined) {
149
+ if (typeof after !== 'string')
150
+ return reject('after must be a string');
151
+ out.after = after;
152
+ }
153
+ if (next !== undefined) {
154
+ if (typeof next !== 'string')
155
+ return reject('next must be a string');
156
+ out.next = next;
157
+ }
158
+ if (proof !== undefined) {
159
+ if (!isSetProof(proof))
160
+ return reject('proof must be a set proof');
161
+ out.proof = { kind: 'set', count: proof.count, digest: proof.digest };
162
+ }
163
+ if (out.next === undefined && out.proof === undefined) {
164
+ return reject('a response without next carries a proof');
165
+ }
166
+ return out;
167
+ }
168
+ /**
169
+ * Applies a response to `rows` and returns the result, leaving `rows` as it was. A reset response
170
+ * without `after` starts from no rows; a later seed page adds to what is held. Deletes apply
171
+ * before puts. `digest` is the digest of `rows` when the caller holds it, which makes the work one
172
+ * row hash per replaced, deleted or added row; without it the digest of `rows` is computed first.
173
+ * With `options.hashes` a replaced or deleted row's old hash is read, not computed, and the result
174
+ * carries the hashes after the response. Pure: no I/O, no clock.
175
+ */
176
+ export async function applyChanges(rows, response, digest, options = {}) {
177
+ const hash = options.hash ?? rowHash;
178
+ const fresh = response.reset && response.after === undefined;
179
+ const out = new Map(fresh ? [] : rows);
180
+ const hashes = options.hashes ? new Map(fresh ? [] : options.hashes) : undefined;
181
+ let sum = fresh ? EMPTY_DIGEST : (digest ?? (await setProof(rows)).digest);
182
+ const drop = async (key) => {
183
+ const old = out.get(key);
184
+ if (old === undefined)
185
+ return;
186
+ sum = digestSub(sum, hashes?.get(key) ?? (await hash(key, old)));
187
+ out.delete(key);
188
+ hashes?.delete(key);
189
+ };
190
+ for (const { key } of response.deletes)
191
+ await drop(key);
192
+ for (const { key, row } of response.puts) {
193
+ await drop(key);
194
+ out.set(key, row);
195
+ const added = await hash(key, row);
196
+ hashes?.set(key, added);
197
+ sum = digestAdd(sum, added);
198
+ }
199
+ const proof = response.proof;
200
+ return {
201
+ rows: out,
202
+ digest: sum,
203
+ matches: proof === undefined ? null : proof.count === out.size && proof.digest === sum,
204
+ ...(hashes ? { hashes } : {})
205
+ };
206
+ }
@@ -9,6 +9,7 @@ export declare const HEADERS: {
9
9
  readonly partition: "spool-partition";
10
10
  readonly vectorSeen: "spool-vector-seen";
11
11
  readonly provision: "spool-provision";
12
+ readonly provisionReason: "spool-provision-reason";
12
13
  };
13
14
  /** `Spool-Clear` token that wipes everything the worker holds */
14
15
  export declare const CLEAR_ALL = "*";
@@ -19,6 +20,8 @@ export type EnvelopeArtifact = {
19
20
  deps: string[];
20
21
  /** the vector cursor the artifact reflects */
21
22
  version: number;
23
+ /** base64url SHA-256 of the artifact's shell as the page body carries it, minus the client tag */
24
+ hash?: string;
22
25
  };
23
26
  /** every spool header of a response, decoded; an absent header is an absent field */
24
27
  export type Envelope = {
@@ -9,11 +9,13 @@ export const HEADERS = {
9
9
  vector: 'spool-vector',
10
10
  partition: 'spool-partition',
11
11
  vectorSeen: 'spool-vector-seen',
12
- provision: 'spool-provision'
12
+ provision: 'spool-provision',
13
+ provisionReason: 'spool-provision-reason'
13
14
  };
14
15
  /** `Spool-Clear` token that wipes everything the worker holds */
15
16
  export const CLEAR_ALL = '*';
16
17
  const PARTITION = /^[A-Za-z0-9_-]{1,128}$/;
18
+ const HASH = /^[A-Za-z0-9_-]{43}$/;
17
19
  function bad(message) {
18
20
  throw new ProtocolError('bad-header', message);
19
21
  }
@@ -43,12 +45,18 @@ export function encodeEnvelope(envelope) {
43
45
  };
44
46
  const { artifact, invalidate, clear, vector, seen, partition } = envelope;
45
47
  if (artifact) {
46
- out[HEADERS.artifact] = [
48
+ const fields = [
47
49
  `id=${encodeURIComponent(artifact.id)}`,
48
50
  `scope=${artifact.scope}`,
49
51
  `deps=${artifact.deps.map(encodeURIComponent).join(',')}`,
50
52
  `v=${artifact.version}`
51
- ].join('; ');
53
+ ];
54
+ if (artifact.hash !== undefined) {
55
+ if (!HASH.test(artifact.hash))
56
+ return bad('hash must be a base64url token');
57
+ fields.push(`h=${artifact.hash}`);
58
+ }
59
+ out[HEADERS.artifact] = fields.join('; ');
52
60
  }
53
61
  const changed = Object.entries(invalidate ?? {});
54
62
  if (changed.length > 0) {
@@ -130,6 +138,9 @@ export function decodeEnvelope(headers) {
130
138
  deps: list(fields.get('deps') ?? '').map((d) => decode(d, 'Spool-Artifact deps')),
131
139
  version: integer(version, 'Spool-Artifact v')
132
140
  };
141
+ const hash = fields.get('h');
142
+ if (hash !== undefined && HASH.test(hash))
143
+ out.artifact.hash = hash;
133
144
  }
134
145
  const invalidate = headers.get(HEADERS.invalidate);
135
146
  if (invalidate !== null) {
@@ -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';
2
+ export type ProtocolErrorCode = 'bad-pattern' | 'bad-route' | 'bad-header' | 'bad-artifact' | 'bad-sync' | '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,2 @@
1
+ /** base64url SHA-256 of the UTF-8 bytes of `text`, without padding */
2
+ export declare function shellHash(text: string): Promise<string>;
@@ -0,0 +1,8 @@
1
+ /** base64url SHA-256 of the UTF-8 bytes of `text`, without padding */
2
+ export async function shellHash(text) {
3
+ const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)));
4
+ let binary = '';
5
+ for (const byte of digest)
6
+ binary += String.fromCharCode(byte);
7
+ return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
8
+ }
@@ -3,13 +3,19 @@ export * from './assembly.js';
3
3
  export * from './beacon.js';
4
4
  export * from './collector.js';
5
5
  export * from './config.js';
6
+ export * from './dataset.js';
6
7
  export * from './envelope.js';
7
8
  export * from './errors.js';
8
9
  export * from './graph.js';
10
+ export * from './hash.js';
11
+ export * from './inline.js';
9
12
  export * from './manifest.js';
13
+ export * from './navigation.js';
10
14
  export * from './normalise.js';
11
15
  export * from './pattern.js';
16
+ export * from './plan.js';
12
17
  export * from './provision.js';
18
+ export * from './query.js';
13
19
  export * from './route.js';
14
20
  export * from './sync.js';
15
21
  export * from './tag.js';
@@ -17,3 +23,4 @@ export * from './template/compile.js';
17
23
  export * from './template/interpret.js';
18
24
  export * from './vector.js';
19
25
  export * from './view.js';
26
+ export * from './write.js';
@@ -3,13 +3,19 @@ export * from './assembly.js';
3
3
  export * from './beacon.js';
4
4
  export * from './collector.js';
5
5
  export * from './config.js';
6
+ export * from './dataset.js';
6
7
  export * from './envelope.js';
7
8
  export * from './errors.js';
8
9
  export * from './graph.js';
10
+ export * from './hash.js';
11
+ export * from './inline.js';
9
12
  export * from './manifest.js';
13
+ export * from './navigation.js';
10
14
  export * from './normalise.js';
11
15
  export * from './pattern.js';
16
+ export * from './plan.js';
12
17
  export * from './provision.js';
18
+ export * from './query.js';
13
19
  export * from './route.js';
14
20
  export * from './sync.js';
15
21
  export * from './tag.js';
@@ -17,3 +23,4 @@ export * from './template/compile.js';
17
23
  export * from './template/interpret.js';
18
24
  export * from './vector.js';
19
25
  export * from './view.js';
26
+ export * from './write.js';
@@ -0,0 +1,14 @@
1
+ /** the opening tag of the element that carries a page's own artifact */
2
+ export declare const INLINE_OPEN = "<script type=\"application/spool+json\" data-spool-artifact>";
3
+ /** `json` with every character that could end or confuse a script element written as a `\u` escape */
4
+ export declare function escapeInline(json: string): string;
5
+ /** the script element that carries `text`, which must already be escaped */
6
+ export declare function inlineElement(text: string): string;
7
+ /**
8
+ * `html` with the element placed before the last `</body>`, or at the end when the page has none.
9
+ */
10
+ export declare function placeInline(html: string, element: string): string;
11
+ /** the text of the last inline element in `html`, or null when there is none */
12
+ export declare function readInline(html: string): string | null;
13
+ /** `html` without any inline element, which is data and no part of the page */
14
+ export declare function stripInline(html: string): string;
@@ -0,0 +1,43 @@
1
+ /** the opening tag of the element that carries a page's own artifact */
2
+ export const INLINE_OPEN = '<script type="application/spool+json" data-spool-artifact>';
3
+ const INLINE_CLOSE = '</script>';
4
+ const UNSAFE = new RegExp(`[<>&${String.fromCharCode(0x2028, 0x2029)}]`, 'g');
5
+ /** `json` with every character that could end or confuse a script element written as a `\u` escape */
6
+ export function escapeInline(json) {
7
+ return json.replace(UNSAFE, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`);
8
+ }
9
+ /** the script element that carries `text`, which must already be escaped */
10
+ export function inlineElement(text) {
11
+ return `${INLINE_OPEN}${text}${INLINE_CLOSE}`;
12
+ }
13
+ /**
14
+ * `html` with the element placed before the last `</body>`, or at the end when the page has none.
15
+ */
16
+ export function placeInline(html, element) {
17
+ let at = -1;
18
+ for (const match of html.matchAll(/<\/body\s*>/gi))
19
+ at = match.index;
20
+ return at < 0 ? html + element : html.slice(0, at) + element + html.slice(at);
21
+ }
22
+ /** the text of the last inline element in `html`, or null when there is none */
23
+ export function readInline(html) {
24
+ const open = html.lastIndexOf(INLINE_OPEN);
25
+ if (open < 0)
26
+ return null;
27
+ const from = open + INLINE_OPEN.length;
28
+ const close = html.indexOf(INLINE_CLOSE, from);
29
+ return close < 0 ? null : html.slice(from, close);
30
+ }
31
+ /** `html` without any inline element, which is data and no part of the page */
32
+ export function stripInline(html) {
33
+ let out = '';
34
+ let at = 0;
35
+ for (;;) {
36
+ const open = html.indexOf(INLINE_OPEN, at);
37
+ const close = open < 0 ? -1 : html.indexOf(INLINE_CLOSE, open + INLINE_OPEN.length);
38
+ if (close < 0)
39
+ return out + html.slice(at);
40
+ out += html.slice(at, open);
41
+ at = close + INLINE_CLOSE.length;
42
+ }
43
+ }
@@ -0,0 +1,81 @@
1
+ /** how the model reads its history; every field is optional */
2
+ export type NavOptions = {
3
+ /** 1 predicts from the last route pattern; 2 uses the last two and backs off to 1 */
4
+ order?: 1 | 2;
5
+ /** observations until a count has lost half its weight; `Infinity` turns decay off */
6
+ halfLife?: number;
7
+ /** pseudo-observations that pull each row toward its prior */
8
+ alpha?: number;
9
+ /** the two-pattern row weighs n / (n + backoff) against the one-pattern row, n being its observations */
10
+ backoff?: number;
11
+ /** counts per one-pattern context, as a population or a public corpus would give them */
12
+ prior?: Record<string, Record<string, number>>;
13
+ /** contexts kept in each table */
14
+ maxContexts?: number;
15
+ /** next routes kept per context */
16
+ maxNext?: number;
17
+ };
18
+ /** a route with its probability and the effective observations behind its context */
19
+ export type NavPrediction = {
20
+ /** the predicted next route pattern */
21
+ route: string;
22
+ /** probability that this route comes next, from 0 to 1 */
23
+ p: number;
24
+ /** effective observations behind the context */
25
+ weight: number;
26
+ };
27
+ /** a row as JSON: its context, its last tick, then each next route with its count and tick */
28
+ export type RowEntry = [
29
+ ctx: string[],
30
+ t: number,
31
+ next: Array<[route: string, n: number, t: number]>
32
+ ];
33
+ /** the model as JSON; `one` holds one-pattern contexts, `two` two-pattern contexts */
34
+ export type NavSnapshot = {
35
+ /** format version; always 1 */
36
+ v: 1;
37
+ /** observations the model had seen when it was saved */
38
+ t: number;
39
+ /** rows for one-route contexts */
40
+ one: RowEntry[];
41
+ /** rows for two-route contexts */
42
+ two: RowEntry[];
43
+ };
44
+ /**
45
+ * Predicts the next route pattern from the ones before it. Counts decay by half every `halfLife`
46
+ * observations, and a route the model has never seen (in counts or prior) is never predicted.
47
+ */
48
+ export declare class NavModel {
49
+ #private;
50
+ constructor(options?: NavOptions);
51
+ /** records that `route` came after `context`, newest route last; an empty context is a no-op */
52
+ observe(context: readonly string[], route: string): void;
53
+ /** the likely next routes, most probable first; routes with no probability are left out */
54
+ predict(context: readonly string[]): NavPrediction[];
55
+ /** the model as a snapshot that fromJSON restores */
56
+ toJSON(): NavSnapshot;
57
+ /** restores a model from toJSON output; throws bad-nav on a malformed snapshot */
58
+ static fromJSON(snapshot: unknown, options?: NavOptions): NavModel;
59
+ }
60
+ /** a Wilson score lower bound for a proportion `p` over `weight` effective observations */
61
+ export declare function lowerBound(p: number, weight: number, z?: number): number;
62
+ /** joules: `avoided` is what a hit keeps off the wire, the rest is what it costs */
63
+ export type NetInput = {
64
+ /** probability the candidate is used, from 0 to 1 */
65
+ p: number;
66
+ /** effective observations behind p */
67
+ weight: number;
68
+ /** joules a hit keeps off the wire */
69
+ avoided: number;
70
+ /** joules to provision the candidate, paid whether or not it is used */
71
+ provision: number;
72
+ /** joules to render the candidate, paid whether or not it is used; default 0 */
73
+ render?: number;
74
+ /** joules to keep the candidate current, paid whether or not it is used; default 0 */
75
+ maintain?: number;
76
+ /** joules of model work the decision costs, paid whether or not it is used; default 0 */
77
+ model?: number;
78
+ };
79
+ /** expected joules of acting on a candidate, with its probability taken at the lower bound */
80
+ export declare function expectedNet(input: NetInput, z?: number): number;
81
+ export declare function shouldAct(input: NetInput, z?: number): boolean;