@drupflare/spool 0.2.0 → 0.3.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 (62) hide show
  1. package/README.md +256 -22
  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 +2 -1
  8. package/dist/client/index.d.ts +1 -0
  9. package/dist/client/index.js +1 -0
  10. package/dist/media/embeds.d.ts +3 -2
  11. package/dist/media/embeds.js +16 -1
  12. package/dist/protocol/envelope.d.ts +2 -0
  13. package/dist/protocol/envelope.js +12 -2
  14. package/dist/protocol/errors.d.ts +1 -1
  15. package/dist/protocol/hash.d.ts +2 -0
  16. package/dist/protocol/hash.js +8 -0
  17. package/dist/protocol/index.d.ts +4 -0
  18. package/dist/protocol/index.js +4 -0
  19. package/dist/protocol/inline.d.ts +14 -0
  20. package/dist/protocol/inline.js +43 -0
  21. package/dist/protocol/navigation.d.ts +81 -0
  22. package/dist/protocol/navigation.js +249 -0
  23. package/dist/protocol/normalise.d.ts +4 -3
  24. package/dist/protocol/normalise.js +6 -4
  25. package/dist/protocol/provision.d.ts +6 -1
  26. package/dist/protocol/provision.js +15 -5
  27. package/dist/protocol/query.d.ts +80 -0
  28. package/dist/protocol/query.js +153 -0
  29. package/dist/protocol/route.d.ts +80 -4
  30. package/dist/protocol/route.js +63 -0
  31. package/dist/proxy/bases.d.ts +53 -0
  32. package/dist/proxy/bases.js +76 -0
  33. package/dist/proxy/index.d.ts +1 -0
  34. package/dist/proxy/index.js +1 -0
  35. package/dist/proxy/proxy.js +8 -2
  36. package/dist/report/capacity.d.ts +59 -0
  37. package/dist/report/capacity.js +76 -0
  38. package/dist/report/channels.d.ts +60 -0
  39. package/dist/report/channels.js +65 -0
  40. package/dist/report/index.d.ts +3 -0
  41. package/dist/report/index.js +3 -0
  42. package/dist/report/institution.d.ts +97 -0
  43. package/dist/report/institution.js +79 -0
  44. package/dist/report/ledger.d.ts +28 -0
  45. package/dist/report/ledger.js +30 -0
  46. package/dist/report/measurement.d.ts +1 -1
  47. package/dist/report/measurement.js +4 -1
  48. package/dist/report/traffic.d.ts +11 -2
  49. package/dist/report/traffic.js +13 -3
  50. package/dist/server/embedded.d.ts +3 -3
  51. package/dist/server/embedded.js +3 -3
  52. package/dist/server/index.d.ts +1 -0
  53. package/dist/server/index.js +1 -0
  54. package/dist/server/spool.d.ts +20 -0
  55. package/dist/server/spool.js +62 -9
  56. package/dist/sw/render.d.ts +3 -1
  57. package/dist/sw/render.js +14 -1
  58. package/dist/sw/replica.d.ts +2 -0
  59. package/dist/sw/replica.js +6 -0
  60. package/dist/sw/router.js +2 -2
  61. package/dist/sw/runtime.js +104 -9
  62. package/package.json +4 -2
@@ -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
+ }
@@ -6,10 +6,14 @@ export * from './config.js';
6
6
  export * from './envelope.js';
7
7
  export * from './errors.js';
8
8
  export * from './graph.js';
9
+ export * from './hash.js';
10
+ export * from './inline.js';
9
11
  export * from './manifest.js';
12
+ export * from './navigation.js';
10
13
  export * from './normalise.js';
11
14
  export * from './pattern.js';
12
15
  export * from './provision.js';
16
+ export * from './query.js';
13
17
  export * from './route.js';
14
18
  export * from './sync.js';
15
19
  export * from './tag.js';
@@ -6,10 +6,14 @@ export * from './config.js';
6
6
  export * from './envelope.js';
7
7
  export * from './errors.js';
8
8
  export * from './graph.js';
9
+ export * from './hash.js';
10
+ export * from './inline.js';
9
11
  export * from './manifest.js';
12
+ export * from './navigation.js';
10
13
  export * from './normalise.js';
11
14
  export * from './pattern.js';
12
15
  export * from './provision.js';
16
+ export * from './query.js';
13
17
  export * from './route.js';
14
18
  export * from './sync.js';
15
19
  export * from './tag.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;
@@ -0,0 +1,249 @@
1
+ import { ProtocolError } from './errors.js';
2
+ const SNAPSHOT_KEYS = ['v', 't', 'one', 'two'];
3
+ const round3 = (x) => Math.round(x * 1000) / 1000;
4
+ const keyOf = (ctx) => JSON.stringify(ctx);
5
+ function range(ok, name) {
6
+ if (!ok)
7
+ throw new RangeError(`nav option ${name} is out of range`);
8
+ }
9
+ function refuse(what) {
10
+ throw new ProtocolError('bad-nav', `nav snapshot ${what}`);
11
+ }
12
+ function isRecord(v) {
13
+ return typeof v === 'object' && v !== null && !Array.isArray(v);
14
+ }
15
+ function isRoute(v) {
16
+ return typeof v === 'string' && v.length > 0;
17
+ }
18
+ function isTick(v, max) {
19
+ return typeof v === 'number' && Number.isSafeInteger(v) && v >= 0 && v <= max;
20
+ }
21
+ function entryOf(row) {
22
+ const next = [...row.next].map(([route, c]) => [route, c.n, c.t]);
23
+ return [[...row.ctx], row.t, next];
24
+ }
25
+ function dropOldest(table) {
26
+ let oldest = '';
27
+ let oldestT = Infinity;
28
+ for (const [key, row] of table) {
29
+ if (row.t < oldestT) {
30
+ oldest = key;
31
+ oldestT = row.t;
32
+ }
33
+ }
34
+ table.delete(oldest);
35
+ }
36
+ function restore(table, entries, size, tick) {
37
+ for (const item of entries) {
38
+ if (!Array.isArray(item) || item.length !== 3)
39
+ refuse('has a malformed row');
40
+ const [ctx, t, next] = item;
41
+ if (!Array.isArray(ctx) || ctx.length !== size || !ctx.every(isRoute)) {
42
+ refuse('has a malformed context');
43
+ }
44
+ if (!isTick(t, tick) || t === 0)
45
+ refuse('has a row touched outside the model');
46
+ if (!Array.isArray(next))
47
+ refuse('has a malformed row');
48
+ const key = keyOf(ctx);
49
+ if (table.has(key))
50
+ refuse('repeats a context');
51
+ const row = { ctx, t, next: new Map() };
52
+ for (const pair of next) {
53
+ if (!Array.isArray(pair) || pair.length !== 3)
54
+ refuse('has a malformed route');
55
+ const [route, n, touch] = pair;
56
+ if (!isRoute(route) || row.next.has(route))
57
+ refuse('has a malformed route');
58
+ if (typeof n !== 'number')
59
+ refuse('has a count that is not a number');
60
+ if (n < 0)
61
+ refuse('has a negative count');
62
+ if (!isTick(touch, tick) || touch === 0)
63
+ refuse('has a route touched outside the model');
64
+ row.next.set(route, { n, t: touch });
65
+ }
66
+ table.set(key, row);
67
+ }
68
+ }
69
+ /**
70
+ * Predicts the next route pattern from the ones before it. Counts decay by half every `halfLife`
71
+ * observations, and a route the model has never seen (in counts or prior) is never predicted.
72
+ */
73
+ export class NavModel {
74
+ #order;
75
+ #halfLife;
76
+ #alpha;
77
+ #backoff;
78
+ #prior;
79
+ #maxContexts;
80
+ #maxNext;
81
+ #one = new Map();
82
+ #two = new Map();
83
+ #tick = 0;
84
+ constructor(options = {}) {
85
+ const order = options.order ?? 1;
86
+ const halfLife = options.halfLife ?? 200;
87
+ const alpha = options.alpha ?? 1;
88
+ const backoff = options.backoff ?? 5;
89
+ const prior = options.prior ?? {};
90
+ const maxContexts = options.maxContexts ?? 64;
91
+ const maxNext = options.maxNext ?? 16;
92
+ range(order === 1 || order === 2, 'order');
93
+ range(halfLife > 0, 'halfLife');
94
+ range(alpha >= 0 && Number.isFinite(alpha), 'alpha');
95
+ range(backoff >= 0 && Number.isFinite(backoff), 'backoff');
96
+ range(Number.isSafeInteger(maxContexts) && maxContexts >= 1, 'maxContexts');
97
+ range(Number.isSafeInteger(maxNext) && maxNext >= 1, 'maxNext');
98
+ for (const row of Object.values(prior)) {
99
+ for (const n of Object.values(row))
100
+ range(n >= 0 && Number.isFinite(n), 'prior');
101
+ }
102
+ this.#order = order;
103
+ this.#halfLife = halfLife;
104
+ this.#alpha = alpha;
105
+ this.#backoff = backoff;
106
+ this.#prior = prior;
107
+ this.#maxContexts = maxContexts;
108
+ this.#maxNext = maxNext;
109
+ }
110
+ /** records that `route` came after `context`, newest route last; an empty context is a no-op */
111
+ observe(context, route) {
112
+ if (context.length === 0)
113
+ return;
114
+ this.#tick += 1;
115
+ this.#touch(this.#one, context.slice(-1), route);
116
+ if (this.#order === 2 && context.length >= 2) {
117
+ this.#touch(this.#two, context.slice(-2), route);
118
+ }
119
+ }
120
+ /** the likely next routes, most probable first; routes with no probability are left out */
121
+ predict(context) {
122
+ if (context.length === 0)
123
+ return [];
124
+ const last = context[context.length - 1] ?? '';
125
+ const one = this.#one.get(keyOf(context.slice(-1)));
126
+ const two = this.#order === 2 && context.length >= 2
127
+ ? this.#two.get(keyOf(context.slice(-2)))
128
+ : undefined;
129
+ const prior = Object.hasOwn(this.#prior, last) ? this.#prior[last] : undefined;
130
+ const p1 = this.#distribution(one, prior);
131
+ // the prior's counts are evidence about the mean, so they count toward the weight
132
+ const priorMass = prior ? Object.values(prior).reduce((sum, n) => sum + n, 0) : 0;
133
+ const w1 = (one ? this.#rowWeight(one) : 0) + priorMass;
134
+ const p2 = this.#distribution(two);
135
+ const w2 = two ? this.#rowWeight(two) : 0;
136
+ const lambda = w2 === 0 ? 0 : w2 / (w2 + this.#backoff);
137
+ const weight = lambda * w2 + (1 - lambda) * w1;
138
+ const out = [];
139
+ for (const route of new Set([...p1.keys(), ...p2.keys()])) {
140
+ const p = lambda * (p2.get(route) ?? 0) + (1 - lambda) * (p1.get(route) ?? 0);
141
+ if (p > 0)
142
+ out.push({ route, p, weight });
143
+ }
144
+ return out.sort((a, b) => b.p - a.p || (a.route < b.route ? -1 : a.route > b.route ? 1 : 0));
145
+ }
146
+ /** the model as a snapshot that fromJSON restores */
147
+ toJSON() {
148
+ return {
149
+ v: 1,
150
+ t: this.#tick,
151
+ one: [...this.#one.values()].map(entryOf),
152
+ two: [...this.#two.values()].map(entryOf)
153
+ };
154
+ }
155
+ /** restores a model from toJSON output; throws bad-nav on a malformed snapshot */
156
+ static fromJSON(snapshot, options) {
157
+ if (!isRecord(snapshot))
158
+ refuse('is not an object');
159
+ if (snapshot.v !== 1)
160
+ refuse('has an unknown version');
161
+ if (Object.keys(snapshot).some((key) => !SNAPSHOT_KEYS.includes(key))) {
162
+ refuse('has an unknown field');
163
+ }
164
+ const { t, one, two } = snapshot;
165
+ if (!isTick(t, Number.MAX_SAFE_INTEGER))
166
+ refuse('has a bad tick');
167
+ if (!Array.isArray(one) || !Array.isArray(two))
168
+ refuse('has a table that is not a list');
169
+ const model = new NavModel(options);
170
+ if (model.#order === 1 && two.length > 0)
171
+ refuse('has two-pattern contexts for order 1');
172
+ model.#tick = t;
173
+ restore(model.#one, one, 1, t);
174
+ restore(model.#two, two, 2, t);
175
+ return model;
176
+ }
177
+ #touch(table, ctx, route) {
178
+ const key = keyOf(ctx);
179
+ let row = table.get(key);
180
+ if (!row) {
181
+ if (table.size >= this.#maxContexts)
182
+ dropOldest(table);
183
+ row = { ctx, t: this.#tick, next: new Map() };
184
+ table.set(key, row);
185
+ }
186
+ row.t = this.#tick;
187
+ const prev = row.next.get(route);
188
+ row.next.set(route, { n: round3((prev ? this.#weigh(prev) : 0) + 1), t: this.#tick });
189
+ if (row.next.size > this.#maxNext)
190
+ this.#dropWeakest(row.next);
191
+ }
192
+ #dropWeakest(next) {
193
+ let weakest = '';
194
+ let weakestW = Infinity;
195
+ for (const [route, count] of next) {
196
+ const w = this.#weigh(count);
197
+ if (w < weakestW || (w === weakestW && route < weakest)) {
198
+ weakest = route;
199
+ weakestW = w;
200
+ }
201
+ }
202
+ next.delete(weakest);
203
+ }
204
+ #weigh(count) {
205
+ return count.n * 0.5 ** ((this.#tick - count.t) / this.#halfLife);
206
+ }
207
+ #rowWeight(row) {
208
+ let total = 0;
209
+ for (const count of row.next.values())
210
+ total += this.#weigh(count);
211
+ return total;
212
+ }
213
+ #distribution(row, prior) {
214
+ const out = new Map();
215
+ const denom = (row ? this.#rowWeight(row) : 0) + this.#alpha;
216
+ if (denom <= 0)
217
+ return out;
218
+ const priorTotal = prior ? Object.values(prior).reduce((sum, n) => sum + n, 0) : 0;
219
+ const routes = new Set([...(row?.next.keys() ?? []), ...Object.keys(prior ?? {})]);
220
+ for (const route of routes) {
221
+ const count = row?.next.get(route);
222
+ const shared = prior && Object.hasOwn(prior, route) ? (prior[route] ?? 0) : 0;
223
+ const share = priorTotal > 0 ? shared / priorTotal : 0;
224
+ out.set(route, ((count ? this.#weigh(count) : 0) + this.#alpha * share) / denom);
225
+ }
226
+ return out;
227
+ }
228
+ }
229
+ /** a Wilson score lower bound for a proportion `p` over `weight` effective observations */
230
+ export function lowerBound(p, weight, z = 1.28) {
231
+ if (!(p >= 0 && p <= 1) || !(weight > 0) || !Number.isFinite(weight))
232
+ return 0;
233
+ const z2 = z * z;
234
+ const centre = p + z2 / (2 * weight);
235
+ const margin = z * Math.sqrt((p * (1 - p)) / weight + z2 / (4 * weight * weight));
236
+ const bound = (centre - margin) / (1 + z2 / weight);
237
+ return Math.min(p, Math.max(0, bound));
238
+ }
239
+ /** expected joules of acting on a candidate, with its probability taken at the lower bound */
240
+ export function expectedNet(input, z) {
241
+ return (lowerBound(input.p, input.weight, z) * input.avoided -
242
+ input.provision -
243
+ (input.render ?? 0) -
244
+ (input.maintain ?? 0) -
245
+ (input.model ?? 0));
246
+ }
247
+ export function shouldAct(input, z) {
248
+ return expectedNet(input, z) > 0;
249
+ }
@@ -3,9 +3,10 @@ export type NormaliseOptions = {
3
3
  ignore?: readonly RegExp[];
4
4
  };
5
5
  /**
6
- * Reduces markup to what two renders of the same page must share: comments removed, runs of
7
- * whitespace collapsed to one space, whitespace between tags dropped, and every `ignore` match
8
- * blanked (a per-render nonce, say). It does not reorder attributes or fix tag soup.
6
+ * Reduces markup to what two renders of the same page must share: comments and the inline
7
+ * artifact element removed, runs of whitespace collapsed to one space, whitespace between tags
8
+ * dropped, and every `ignore` match blanked (a per-render nonce, say). It does not reorder
9
+ * attributes or fix tag soup.
9
10
  */
10
11
  export declare function normalise(html: string, options?: NormaliseOptions): string;
11
12
  /** the verdict of {@link equivalent}; a mismatch names where the two first differ */
@@ -1,11 +1,13 @@
1
+ import { stripInline } from './inline.js';
1
2
  const IGNORED = '\u0000';
2
3
  /**
3
- * Reduces markup to what two renders of the same page must share: comments removed, runs of
4
- * whitespace collapsed to one space, whitespace between tags dropped, and every `ignore` match
5
- * blanked (a per-render nonce, say). It does not reorder attributes or fix tag soup.
4
+ * Reduces markup to what two renders of the same page must share: comments and the inline
5
+ * artifact element removed, runs of whitespace collapsed to one space, whitespace between tags
6
+ * dropped, and every `ignore` match blanked (a per-render nonce, say). It does not reorder
7
+ * attributes or fix tag soup.
6
8
  */
7
9
  export function normalise(html, options = {}) {
8
- let out = html.replace(/<!--[\s\S]*?-->/g, '');
10
+ let out = stripInline(html).replace(/<!--[\s\S]*?-->/g, '');
9
11
  for (const pattern of options.ignore ?? []) {
10
12
  const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
11
13
  out = out.replace(new RegExp(pattern.source, flags), IGNORED);
@@ -78,6 +78,8 @@ export type EntryCandidate = {
78
78
  path: string;
79
79
  /** the predicted share of devices that will open the page, 0 to 1 */
80
80
  p: number;
81
+ /** the observations behind `p`; with a `z` it lowers `p` to a confidence bound, so a share seen once does not count as one seen a thousand times */
82
+ weight?: number;
81
83
  /** compressed bytes of the entry */
82
84
  entryBytes: number;
83
85
  /** bytes of the document the entry replaces */
@@ -87,10 +89,13 @@ export type EntryCandidate = {
87
89
  * The candidates worth shipping: those whose `p` is at least their break-even, best expected net
88
90
  * first, kept while their entry bytes fit under `capBytes`. A candidate that does not fit is
89
91
  * skipped and a smaller one may still go. A path is chosen once. A candidate with a `p` outside 0
90
- * to 1 or a negative or non-finite size is never chosen.
92
+ * to 1 or a negative or non-finite size is never chosen. With `z` above 0, a candidate that has a
93
+ * `weight` is judged on the lower confidence bound of its `p` (the Wilson bound at `z`), and the
94
+ * order follows the net at that bound; one with no `weight` keeps its `p`.
91
95
  */
92
96
  export declare function chooseEntries(candidates: readonly EntryCandidate[], options: {
93
97
  capBytes: number;
98
+ z?: number;
94
99
  }): EntryCandidate[];
95
100
  /**
96
101
  * P_reuse from aggregate telemetry: the share of a route's views that found a stored copy, pulled
@@ -1,3 +1,4 @@
1
+ import { lowerBound } from './navigation.js';
1
2
  /** the defaults a config without `provision` gets */
2
3
  export const DEFAULT_PRIOR = {
3
4
  reuse: 0.5,
@@ -65,24 +66,33 @@ export function entryBreakEven(entryBytes, documentBytes) {
65
66
  return (JOULES_PER_BYTE * entryBytes) / (JOULES_PER_BYTE * documentBytes + ORIGIN_JOULES);
66
67
  }
67
68
  const sound = (n) => Number.isFinite(n) && n >= 0;
69
+ /** the share the decision uses: `p`, or its lower confidence bound at `z` when the candidate says how many observations back it */
70
+ function shareOf(c, z) {
71
+ return c.weight !== undefined && z > 0 ? lowerBound(c.p, c.weight, z) : c.p;
72
+ }
68
73
  /** expected joules of shipping an entry: `p * (k*D + o) - k*E` */
69
- function expectedNet(c) {
70
- return (c.p * (JOULES_PER_BYTE * c.documentBytes + ORIGIN_JOULES) - JOULES_PER_BYTE * c.entryBytes);
74
+ function expectedNet(c, z) {
75
+ return (shareOf(c, z) * (JOULES_PER_BYTE * c.documentBytes + ORIGIN_JOULES) -
76
+ JOULES_PER_BYTE * c.entryBytes);
71
77
  }
72
78
  /**
73
79
  * The candidates worth shipping: those whose `p` is at least their break-even, best expected net
74
80
  * first, kept while their entry bytes fit under `capBytes`. A candidate that does not fit is
75
81
  * skipped and a smaller one may still go. A path is chosen once. A candidate with a `p` outside 0
76
- * to 1 or a negative or non-finite size is never chosen.
82
+ * to 1 or a negative or non-finite size is never chosen. With `z` above 0, a candidate that has a
83
+ * `weight` is judged on the lower confidence bound of its `p` (the Wilson bound at `z`), and the
84
+ * order follows the net at that bound; one with no `weight` keeps its `p`.
77
85
  */
78
86
  export function chooseEntries(candidates, options) {
87
+ const z = options.z ?? 0;
79
88
  const paying = candidates
80
89
  .filter((c) => sound(c.entryBytes) &&
81
90
  sound(c.documentBytes) &&
82
91
  c.p >= 0 &&
83
92
  c.p <= 1 &&
84
- c.p >= entryBreakEven(c.entryBytes, c.documentBytes))
85
- .sort((a, b) => expectedNet(b) - expectedNet(a) || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
93
+ shareOf(c, z) >= entryBreakEven(c.entryBytes, c.documentBytes))
94
+ .sort((a, b) => expectedNet(b, z) - expectedNet(a, z) ||
95
+ (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
86
96
  const out = [];
87
97
  const seen = new Set();
88
98
  let bytes = 0;
@@ -0,0 +1,80 @@
1
+ /** how a query parameter is read when it filters a field */
2
+ export type QueryFilterType = 'string' | 'number';
3
+ /**
4
+ * The query strings a public route answers from the collection it holds. `list` names the key of the
5
+ * loaded data that holds the whole collection, an array of flat objects. A parameter named in
6
+ * `filter` keeps the items whose field of the same name equals it, and a repeated one matches any of
7
+ * its values. `sort` lists the fields the `sort` parameter may name (`-name` sorts descending), and
8
+ * `pageSize` turns on the 1-based `page` parameter.
9
+ */
10
+ export type QuerySchema = {
11
+ /** key of the loaded data that holds the collection */
12
+ list: string;
13
+ /** parameters that filter items, by field name, with how each is read */
14
+ filter?: Record<string, QueryFilterType>;
15
+ /** fields the sort parameter may name; a leading minus reverses the order */
16
+ sort?: readonly string[];
17
+ /** items per page; turns on the page parameter */
18
+ pageSize?: number;
19
+ };
20
+ /** what a collection's `load` result carries so the worker can tell it holds every item the server sent */
21
+ export type DatasetProof = {
22
+ /** number of items in the collection */
23
+ count: number;
24
+ /** hash of the collection's canonical JSON */
25
+ digest: string;
26
+ };
27
+ /** the page of items a query selects, with the size of the filtered collection and the page count */
28
+ export type QueryResult = {
29
+ /** the items on this page */
30
+ items: Record<string, unknown>[];
31
+ /** items matching the filters, before paging */
32
+ total: number;
33
+ /** the 1-based page returned */
34
+ page: number;
35
+ /** number of pages, at least 1 */
36
+ pages: number;
37
+ };
38
+ /** what a template or renderer receives as `query` for a query URL */
39
+ export type QueryView = {
40
+ /** items matching the filters, before paging */
41
+ total: number;
42
+ /** the 1-based page returned */
43
+ page: number;
44
+ /** number of pages, at least 1 */
45
+ pages: number;
46
+ };
47
+ /** the refusal reason when the stored items no longer match their proof */
48
+ export declare const PROOF_MISMATCH = "dataset proof does not match its items";
49
+ /** a flat object of a collection or the data around it */
50
+ export type Plain = Record<string, unknown>;
51
+ /** JSON with object keys sorted and no whitespace, so equal values give equal text on any engine */
52
+ export declare function canonicalJson(value: unknown): string;
53
+ /** the proof a query route's `load` result carries for its collection */
54
+ export declare function datasetProof(items: readonly unknown[]): Promise<DatasetProof>;
55
+ /** whether `data` holds the collection at `schema.list` and a `proof` that matches it */
56
+ export declare function verifyProof(schema: QuerySchema, data: unknown): Promise<boolean>;
57
+ /**
58
+ * Applies a query string to the collection in `data`: filters by equality, sorts stably (ties keep
59
+ * the stored order), and pages. Returns `null` for anything the schema does not declare, so the
60
+ * caller goes to the network: an unknown parameter, a number filter that is not a finite number, a
61
+ * `sort` that is repeated or not a listed field, a `page` that is not a positive integer or lies
62
+ * past the last, or an item that is not an object. An empty query string selects everything.
63
+ */
64
+ export declare function evaluateQuery(schema: QuerySchema, data: unknown, search: string): QueryResult | null;
65
+ /**
66
+ * The data a template or renderer gets for a query URL: the stored data with `schema.list` replaced
67
+ * by the page's items and a `query` key added. Refuses when the proof fails or the query is not one
68
+ * the schema declares.
69
+ */
70
+ export declare function shapeQuery(schema: QuerySchema, data: unknown, search: string): Promise<{
71
+ /** true when the query was answered from the stored collection */
72
+ ok: true;
73
+ /** the stored data with the page's items and the query view */
74
+ data: Plain;
75
+ } | {
76
+ /** false when the proof or the query was refused */
77
+ ok: false;
78
+ /** why the query was refused */
79
+ reason: string;
80
+ }>;