@bridgebrew/storage 0.0.0-stage → 0.0.2

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.
package/objects.ts ADDED
@@ -0,0 +1,1185 @@
1
+ // Object domains (AD-24): `{ id, node, value }` objects on nodes of the worker's tree, written by the declaring plugin
2
+ // only, or by any plugin of the workspace once it opens the domain (`writers`, research-052 D3), one write after
3
+ // another, each through the domain's `rules` (research-052 D1), run in that same queue. Reads
4
+ // are async, served by the storage backend, and return copies. Facets of an object are assembled into its envelope on
5
+ // read. Deleting archives (soft delete); `purge` removes for good, refused while referenced. Each durable write emits
6
+ // `<domain id>/<action>` through `nodes.emit` (AD-25), in write order, with the object's view; a private domain's
7
+ // events carry `{ id, node }` (and `from` on a move), never the value. Each write carries its audit meta (research-011
8
+ // D3): the op, the names of the fields it changed, the writing plugin, and the actor read when the write was accepted.
9
+ import { AsyncLocalStorage } from 'node:async_hooks';
10
+ import { createHash, randomUUID } from 'node:crypto';
11
+ import { isDeepStrictEqual } from 'node:util';
12
+ import type { Context } from 'cordis';
13
+ import type { z } from 'zod';
14
+ import {
15
+ checkPath,
16
+ checkOrderBy,
17
+ checkTake,
18
+ checkWhere,
19
+ pick,
20
+ tokens,
21
+ type AuditMeta,
22
+ type Filter,
23
+ type Group,
24
+ type Hub,
25
+ type Mode,
26
+ type Order,
27
+ type OrderBy,
28
+ type SearchMode,
29
+ type Store,
30
+ type Where,
31
+ } from '@bridge/storage';
32
+ import type { References } from './references.ts';
33
+
34
+ /** The worker runtime's plugin key symbol (`@bridge/worker-runtime/router`), shared through the registry. */
35
+ export const pluginKey = Symbol.for('bridge.pluginKey');
36
+ /** The worker runtime's symbol for the domain versions a plugin's manifest declares (`bridge.dataVersions`), absent when it
37
+ * declares none. */
38
+ export const pluginDataVersions = Symbol.for('bridge.pluginDataVersions');
39
+
40
+ /** An object of an object domain (AD-24): `id` a UUID the domain generated, `node` the node it belongs to; `archived`
41
+ * once deleted (stored only when true; reads always carry it). */
42
+ export interface StoredObject<T> {
43
+ id: string;
44
+ node: string;
45
+ value: T;
46
+ archived?: boolean;
47
+ /** Its revision (research-021 D4): 1 at its creation, one more at each write; 0 for one stored before revisions. */
48
+ rev?: number;
49
+ }
50
+ /** What the store keeps beyond a read's view: the last writes' `mutationId`s (research-021 B12), never read out. */
51
+ type Receipted<T> = StoredObject<T> & { receipts?: string[] };
52
+ /** How many writes' `mutationId`s an object remembers: a retry after more writes than this is a conflict. */
53
+ const receiptsKept = 8;
54
+
55
+ /** An object with the value of every declared facet domain over its domain that has one, keyed by facet domain id. */
56
+ export interface Envelope<T> extends StoredObject<T> {
57
+ facets: Record<string, unknown>;
58
+ }
59
+
60
+ export interface ObjectsSpec<T> {
61
+ name: string;
62
+ /** Validates each object's `value`. */
63
+ schema: z.ZodType<T>;
64
+ version: number;
65
+ /** Turns one object's `value`, stored at `fromVersion`, into a value for `version`; ids and nodes are kept. */
66
+ migrate?: (value: unknown, fromVersion: number) => unknown;
67
+ /** Top-level fields of `value` holding a reference `{ domain, id }` (or an array of them) to the domain named. */
68
+ references?: References;
69
+ /** Paths of `value` (as in `where`) that `orderBy` uses often: the backend indexes them for ordering, raw and
70
+ * insensitive (SQLite; JSON ignores them). Speed only: every query works without. Object domains only. */
71
+ indexes?: string[];
72
+ /** Paths of `value` (as in `indexes`) whose text a query's `search` reads: strings and numbers, each element of an
73
+ * array of scalars, through an array of objects each element (`emails.value`). Object domains only. Without an
74
+ * index, a SQLite `contains` search scans the search text of every searchable domain of the workspace. `{ paths,
75
+ * index: 'trigram' }`: SQLite also keeps a trigram index, so `contains` words of 3 or more characters skip that
76
+ * scan (a query of only 1-2 character words still scans); about three times the text on disk, and slower writes.
77
+ * Speed only: every search works without. */
78
+ search?: string[] | { paths: string[]; index?: 'trigram' };
79
+ /** Only its owner reads it (research-011 D6): another plugin's `ctx.storage.read` of it is refused `private_domain`
80
+ * (403), relations into it are not followed from another plugin's domains, `resolve` and `envelope` give its objects'
81
+ * state without their value, and its events carry no value. Its references stay valid. What others may see of it, its
82
+ * owner provides as a service. A guard between trusted plugins, not security (AD-20): any plugin runs with the rights
83
+ * of the Bridge process and could open the storage files. Not a schema change: no version bump. */
84
+ private?: boolean;
85
+ /** The domain's rules (research-052 D1): what only its plugin knows of a sound value (a status along its transitions,
86
+ * a slug frozen once published, a unique slug). Storage runs them on every write, whoever writes, inside the
87
+ * domain's write queue, after the schema and the write's own checks (node, rev), before the backend write. `create`
88
+ * and `update` return the value to store, parsed again by the schema (`invalid_value` otherwise): the audit and the
89
+ * events see it. Any rule refuses by throwing (`refuse`). A rule reads any domain (its own sees every earlier write:
90
+ * a check and its write are one step); it never writes, any domain (refused `rule_write`, as the write could wait for a
91
+ * rule forever): what follows a write is the plugin's, after it, on its event. Migrations and storage's JSON import run no
92
+ * rule, nor does `purge`. A write storage makes without writing (an archived object deleted, a move to its own node,
93
+ * a create key or a `mutationId` already applied) runs none either. */
94
+ rules?: Rules<T>;
95
+ /** Who writes it (research-052 D3): `owner` (default), its plugin only, others refused `not_owner`; `workspace`, any
96
+ * plugin of the workspace (this worker) too, through `ctx.storage.write(id)` or this handle: `create`, `update`,
97
+ * `delete`, `restore`, `move`, each through the rules (`write.owner` false), never `purge`, declaration nor
98
+ * migration. The owner opens a domain whose rules hold whoever writes. Refused with `private` (a writer that cannot
99
+ * read). Not a schema change: no version bump; a reload changing it holds from the next write. */
100
+ writers?: 'owner' | 'workspace';
101
+ }
102
+
103
+ /** What a rule is told of the write it judges (research-052 D1). */
104
+ export interface RuleWrite {
105
+ /** The writing plugin's key. */
106
+ plugin: string;
107
+ /** The actor, as the audit names it (`plugin` outside any request). */
108
+ actor: string;
109
+ /** Whether the writer is the domain's own plugin. */
110
+ owner: boolean;
111
+ /** The object's id; on a create, the id it gets. */
112
+ id: string;
113
+ /** The object's node: a create's target, a move's origin. */
114
+ node: string;
115
+ /** The caller's word for the write, given in its options (`{ intent: 'status' }`): a rule may allow a change only
116
+ * through one path. Trusted, as the caller is (AD-20). */
117
+ intent?: string;
118
+ }
119
+
120
+ /** An object domain's rules (`ObjectsSpec.rules`); each may be async. `before` is the stored object as a read gives
121
+ * it, `after` (and a create's `value`) the new value parsed by the schema. */
122
+ export interface Rules<T> {
123
+ create?: (value: T, write: RuleWrite) => T | Promise<T>;
124
+ update?: (before: StoredObject<T>, after: T, write: RuleWrite) => T | Promise<T>;
125
+ /** Archiving. */
126
+ delete?: (before: StoredObject<T>, write: RuleWrite) => void | Promise<void>;
127
+ restore?: (before: StoredObject<T>, write: RuleWrite) => void | Promise<void>;
128
+ move?: (before: StoredObject<T>, node: string, write: RuleWrite) => void | Promise<void>;
129
+ }
130
+ export const ruleNames = ['create', 'update', 'delete', 'restore', 'move'] as const;
131
+
132
+ /** The options every write that runs rules takes. */
133
+ export interface WriteOptions {
134
+ /** Passed to the domain's rules as `write.intent`. */
135
+ intent?: string;
136
+ }
137
+
138
+ /** `self`: on the node; `inherited` (default): on the node and its ancestors; `subtree`: on the node and its descendants. */
139
+ export type Include = 'self' | 'inherited' | 'subtree';
140
+
141
+ export type { Group, OrderBy, Where };
142
+
143
+ /** What a read loads with its objects (or facets), each term in one backend call per page:
144
+ * - `<field>: true`, a reference field (or a facet's `target`): `related[field]`, the live object it names (`null`
145
+ * when missing, archived, or its plugin not loaded), or for an array of references the live ones;
146
+ * - `facets: [<facet domain id>…]` (object domains): `facets`, those facets only, as in an envelope;
147
+ * - `_count: { '<domain id>.<field>': true }`, a declared reference field of that domain to this one:
148
+ * `counts['<domain id>.<field>']`, how many live entries reference the object (a facet is live when its target is). */
149
+ export interface With {
150
+ facets?: string[];
151
+ _count?: Record<string, boolean>;
152
+ [field: string]: boolean | string[] | Record<string, boolean> | undefined;
153
+ }
154
+ /** What `with` adds. */
155
+ export interface Related {
156
+ related?: Record<string, unknown>;
157
+ counts?: Record<string, number>;
158
+ facets?: Record<string, unknown>;
159
+ }
160
+ export type WithResult<T> = StoredObject<T> & Related;
161
+
162
+ /** Visible: neither archived nor on a node of which an ancestor (or itself) is archived. */
163
+ export interface CountOptions {
164
+ node: string;
165
+ include?: Include;
166
+ /** Also the objects that are not visible, each with its `archived` flag. */
167
+ archived?: boolean;
168
+ /** Only objects whose `value` passes it (`@bridge/storage` `Where`): paths of one or two field names inside `value`
169
+ * (`lastName`, `address.city`, `emails.value`; through an array of objects, some element), each a bare value
170
+ * (`equals`), `null` (absent or null), or operators `equals`, `not`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`,
171
+ * `startsWith`, `endsWith`, `contains`, `has`, `hasSome`, `hasEvery`, `isEmpty`, with `mode: 'insensitive'`;
172
+ * `AND`, `OR`, `NOT` combine them. Equality is type-strict.
173
+ * Through a declared reference field `f` (and a facet's `target`), to its live (not archived) objects: `{ f: { is:
174
+ * Where } }`, `isNot` (single reference), `some`, `every`, `none` (array of references), `{ f: null }` (no live
175
+ * object); the inner `Where` is on the target's value; a target domain not declared in this worker is refused with
176
+ * `owner_missing` (404). `{ usedBy: { '<domain id>.<field>': { some: Where } | { none: Where } } }`: some (no) live
177
+ * entry of that domain references it through that declared field, or through `target` for a facet domain on this
178
+ * one. Live: not archived, on a node with no archived ancestor (a facet: its target is live). `usedBy`, and
179
+ * `target` on facet domains, are reserved: no reference field may take those names. */
180
+ where?: Where;
181
+ /** Only objects whose searchable text (the domain's declared `search` paths) has, for every word of it, a word
182
+ * starting with it: words are runs of letters and digits, compared without case nor accents (`zoe lef` finds Zoé
183
+ * Lefèvre, `412` finds +46 8 412 88 00, `wind` does not find Northwind). `{ text, mode: 'contains' }`: a word
184
+ * holding it anywhere (`wind` finds Northwind; never across words: `8412` does not find 8 412); `mode: 'prefix'` is
185
+ * the bare string. No word: every object. No ranking: the order stays `orderBy`'s. Refused (`invalid_query`) on a
186
+ * domain that declares no `search`, and on facet domains. */
187
+ search?: string | { text: string; mode: SearchMode };
188
+ }
189
+ export interface QueryOptions extends CountOptions {
190
+ /** `[{ <path>: 'asc' | 'desc' | { direction, mode: 'insensitive' } }, …]`, then the object id. Mixed types order as
191
+ * absent/null < booleans (0/1) and numbers < strings (by code point) < arrays and objects. Without `orderBy` nor
192
+ * `take`, no order is promised. */
193
+ orderBy?: OrderBy;
194
+ /** At most this many objects. */
195
+ take?: number;
196
+ with?: With;
197
+ }
198
+ export interface GroupByOptions extends CountOptions {
199
+ /** The path grouped, as in `where` (one or two field names; through an array of objects, each element). */
200
+ by: string;
201
+ /** `insensitive`: strings group without case nor accents, each group shown as its smallest spelling by code point. */
202
+ mode?: Mode;
203
+ /** At most this many groups. */
204
+ take?: number;
205
+ }
206
+ export interface PageOptions extends QueryOptions {
207
+ /** A page's `next`: continues strictly after its last object, with the same `orderBy` (else `invalid_cursor`). */
208
+ cursor?: string;
209
+ }
210
+ export interface Page<O> {
211
+ items: O[];
212
+ /** Absent on the last page. */
213
+ next?: string;
214
+ }
215
+
216
+ /** Writes take the caller's context and refuse one of another plugin (`not_owner`) unless the domain is open
217
+ * (`writers: 'workspace'`; `purge` stays the owner's); a rule's refusal is its own
218
+ * (`refuse`: its code, message and status), an `intent` that is not a string `invalid_intent` (status 400), a write
219
+ * from inside any rule `rule_write` (no status: the plugin's bug, a route answers 500); a node the worker's tree
220
+ * lacks is refused with `node_unknown` (status 400), an archived one (or one under an archived node) as a create or
221
+ * move target with `node_archived` (status 400), one where the owning plugin is not active as a create or move target
222
+ * with `plugin_inactive` (status 403, AD-25, whoever writes: the writer's own activity is not read; update, delete,
223
+ * restore, purge, and reads stay allowed), an unknown id with `not_found` (status 404), a value failing its
224
+ * schema with `invalid_value` (status 400), a reference to a
225
+ * missing object of a declared domain (or an unknown node) with `reference_unknown` (status 400), a purge of a
226
+ * referenced object with `in_use` (status 409). A read with a bad `where`, `orderBy` or `take` is refused with
227
+ * `invalid_query` (status 400), a cursor that is not a `next` of the same `orderBy` with `invalid_cursor` (status
228
+ * 400), before anything is read. */
229
+ export interface ObjectDomain<T> {
230
+ /** `key`: the caller's own key for this create (a draft's id): the same key again answers the object it created,
231
+ * without a second one, so a create resent after a lost answer or a closed tab is harmless. Its id comes from the
232
+ * key and the writing plugin's key, still the server's: two writers of an open domain never share a key. */
233
+ create(
234
+ caller: Context,
235
+ value: T,
236
+ options: { node: string; key?: string } & WriteOptions,
237
+ ): Promise<StoredObject<T>>;
238
+ /** Replaces the value; the node is kept. */
239
+ /** `rev`: refused with `409 conflict` (its `details.current` the stored object) unless the object is still at that
240
+ * revision. `mutationId`: a write already applied with it (one of the object's last 8) answers the object without
241
+ * writing again, so a retry after a lost answer is harmless. */
242
+ update(
243
+ caller: Context,
244
+ id: string,
245
+ value: T,
246
+ options?: { rev?: number; mutationId?: string } & WriteOptions,
247
+ ): Promise<StoredObject<T>>;
248
+ /** A move to the object's own node writes and emits nothing. */
249
+ move(caller: Context, id: string, node: string, options?: WriteOptions): Promise<StoredObject<T>>;
250
+ /** Archives it (soft delete); an archived one is accepted with no write. Facets and referrers are kept. */
251
+ delete(caller: Context, id: string, options?: WriteOptions): Promise<void>;
252
+ /** Un-archives it; a live one is accepted with no write. */
253
+ restore(caller: Context, id: string, options?: WriteOptions): Promise<void>;
254
+ /** Removes it for good with its facets in declared facet domains; refused (`in_use`) while anything references it.
255
+ * Runs no rule. */
256
+ purge(caller: Context, id: string): Promise<void>;
257
+ /** Archived or not. */
258
+ get(id: string, options: { with: With; facets?: boolean }): Promise<WithResult<T> | undefined>;
259
+ get(id: string, options: { facets: true }): Promise<Envelope<T> | undefined>;
260
+ get(id: string): Promise<StoredObject<T> | undefined>;
261
+ /** Visible objects only, unless `archived`. */
262
+ query(options: QueryOptions & { with: With }): Promise<WithResult<T>[]>;
263
+ query(options: QueryOptions & { facets: true }): Promise<Envelope<T>[]>;
264
+ query(options: QueryOptions): Promise<StoredObject<T>[]>;
265
+ /** `query` a page at a time: `take` objects (all without it), and `next` when more follow. */
266
+ page(options: PageOptions & { with: With }): Promise<Page<WithResult<T>>>;
267
+ page(options: PageOptions & { facets: true }): Promise<Page<Envelope<T>>>;
268
+ page(options: PageOptions): Promise<Page<StoredObject<T>>>;
269
+ /** How many objects `query` would give, without `take`. */
270
+ count(options: CountOptions): Promise<number>;
271
+ /** Per string or number held at `by` by the objects `count` would count, how many hold it (each object once; a list
272
+ * counts each of its values): `[{ value, count }]`, count descending, then value (numbers before strings, strings by
273
+ * code point). Null, absent, booleans, lists and objects are skipped. */
274
+ groupBy(options: GroupByOptions): Promise<Group[]>;
275
+ /** `fn` runs after each durable change with a copy of the object (an archived one after `delete`); `object` is
276
+ * `undefined` only after `purge`. */
277
+ subscribe(fn: (id: string, object: StoredObject<T> | undefined) => void): () => void;
278
+ /** The changes a read with the same `node`, `include` and `archived` would see (research-021 D3): `{ ready: true }`
279
+ * once watching, then per 50 ms window the ids whose object was or is visible to it, `{ ids: [{ id, action }] }`
280
+ * (`changed` or `purged`), or `{ all: true }` (past 100 ids, or the node tree changed): read again. A route returns
281
+ * it as its event stream; it ends with `signal` or the stream. */
282
+ watch(filter: WatchFilter, signal?: AbortSignal): AsyncIterable<WatchMessage>;
283
+ release(): void;
284
+ }
285
+
286
+ /** A watch's windows and thresholds (research-021 D3, B13); tests lower them. */
287
+ export const watchLimits = { windowMs: 50, ids: 100, slowAfterMs: 5000, slowWindowMs: 1000 };
288
+
289
+ /** What `watch` follows: the visibility arguments of a read. */
290
+ export interface WatchFilter {
291
+ node: string;
292
+ include?: Include;
293
+ archived?: boolean;
294
+ }
295
+ export type WatchMessage =
296
+ | { ready: true }
297
+ | { ids: { id: string; action: 'changed' | 'purged' }[] }
298
+ | { all: true };
299
+
300
+ /** The part of the worker's built-in `nodes` service (`@bridge/worker-runtime`) storage reads. */
301
+ export interface Nodes {
302
+ list(): { id: string }[];
303
+ has(id: string): boolean;
304
+ ancestors(id: string): { id: string; archived: boolean }[] | undefined;
305
+ isActive(pluginKey: string, id: string): boolean;
306
+ /** Delivers object event `event` to listeners active on `payload.node` (AD-25). */
307
+ emit<P extends { node: string }>(event: string, payload: P): void;
308
+ /** The node tree's revision: a watch reads it again when the tree changes visibility (AD-23). */
309
+ readonly revision?: number;
310
+ /** Plugin `key`'s settings resolved at node `id` (the audit's retention reads them). */
311
+ settings?(
312
+ key: string,
313
+ id: string,
314
+ ): { values: Record<string, { value?: unknown } | undefined> } | undefined;
315
+ }
316
+
317
+ /** Refuses a write of plugin `key` on node `node` where it is not active (AD-25). */
318
+ export const checkActive = (nodes: Nodes, key: string, node: string) => {
319
+ if (!nodes.isActive(key, node))
320
+ throw coded(`plugin ${key} is not active on node ${node}`, 'plugin_inactive', 403);
321
+ };
322
+
323
+ /** What an object domain asks the rest of storage: reference checks, its objects' facets and referrers. */
324
+ export interface Links {
325
+ /** Rejects with `reference_unknown` for a reference `value` holds to a missing object or node. */
326
+ check(value: unknown): Promise<void>;
327
+ /** Object `id`'s facets, less those of plugins not active on `node` (its node). */
328
+ facets(id: string, node: string): Promise<Record<string, unknown>>;
329
+ /** Who references object `id`, as `<domain> <id>` lines, less its own references (and its facets') to itself. */
330
+ usedBy(id: string): string[];
331
+ /** The declared facet domains holding a facet on object `id`. */
332
+ facetsOn(id: string): Promise<string[]>;
333
+ /** The declared facet domains over this domain, held now. */
334
+ facetDomains(): string[];
335
+ /** One batch over this domain and facet domains (the hub's `write`). */
336
+ write: Hub['write'];
337
+ /** Declared `private`: events carry no value. */
338
+ private?: boolean;
339
+ /** The actor of the running code (`plugin` without). */
340
+ actor?: () => string;
341
+ /** A value parsed by the domain's schema (with its references): what a rule gets, and what it returns, checked. */
342
+ parse?: (value: unknown) => unknown;
343
+ }
344
+
345
+ /** What a domain's reads ask the rest of storage, which knows every declared domain and reference. */
346
+ export interface Queries {
347
+ /** `where` with relation keys resolved and paths at entry level (`value.<path>`); throws `invalid_query`. */
348
+ where(where: unknown): Where;
349
+ /** `with` checked (throws `invalid_query`): what loads it for a page of stored entries. */
350
+ with(spec: unknown): (entries: { key: string; value: unknown }[]) => Promise<Related[]>;
351
+ /** Whether the domain declares `search` paths. */
352
+ searchable?: boolean;
353
+ /** Its declared reference fields. */
354
+ references?: string[];
355
+ }
356
+
357
+ /** Whether `object` is hidden: archived, or on a node of which an ancestor (or itself) is archived. */
358
+ export const hidden = (nodes: Nodes, object: StoredObject<unknown>) =>
359
+ object.archived === true || inArchivedNode(nodes, object.node);
360
+ export const inArchivedNode = (nodes: Nodes, node: string) =>
361
+ nodes.ancestors(node)?.some((each) => each.archived) === true;
362
+ /** A copy with `archived` always set. */
363
+ export const view = <T>(object: StoredObject<T>): StoredObject<T> => {
364
+ const { receipts: _, ...shown } = object as Receipted<T>;
365
+ return structuredClone({ ...shown, archived: object.archived === true, rev: object.rev ?? 0 });
366
+ };
367
+
368
+ /** Brands an error a route answers with its own 4xx (`@bridge/worker-runtime/router`). */
369
+ const clientError = Symbol.for('bridge.clientError');
370
+ export const coded = (message: string, code: string, status?: number) =>
371
+ Object.assign(new Error(message), { code, ...(status && { status, [clientError]: true }) });
372
+ /** A rule's refusal (research-052 D1), thrown: a route answers it as its own `status` (a 4xx), `{ error: { code,
373
+ * message } }`. */
374
+ export const refuse = (code: string, message: string, status = 409) => coded(message, code, status);
375
+
376
+ /** The domains whose rule runs in this async chain: no write starts in it. */
377
+ const ruling = new AsyncLocalStorage<readonly string[]>();
378
+
379
+ /** Stores through `set`; a value failing its schema is refused with `invalid_value` (status 400), its issues in short. */
380
+ export const validated = async (id: string, set: () => Promise<void>) => {
381
+ try {
382
+ await set();
383
+ } catch (cause) {
384
+ const issues = (cause as { issues?: { path: PropertyKey[]; message: string }[] } | null)
385
+ ?.issues;
386
+ if (!Array.isArray(issues)) throw cause;
387
+ throw Object.assign(
388
+ coded(
389
+ `${id}: invalid value: ${issues.map(({ path, message }) => `${path.map(String).join('.')}: ${message}`).join('; ')}`,
390
+ 'invalid_value',
391
+ 400,
392
+ ),
393
+ { cause },
394
+ );
395
+ }
396
+ };
397
+
398
+ /** Who a write's audit row names: the writing plugin's key, and the actor. */
399
+ export type Author = Pick<AuditMeta, 'plugin' | 'actor'>;
400
+
401
+ /** Runs one domain's writes one after another, each reading the state the previous one left (a move is never undone
402
+ * by a concurrent update that read the old node), each refused unless `caller` has plugin key `key`, or `opens(fn)`
403
+ * (an open domain, research-052 D3). `run` gets the write's author: the caller's key and `actor()` (the actor,
404
+ * default `plugin`), read when the write is accepted, before the queue, so a write queued behind another keeps its
405
+ * own cause. */
406
+ export const serialWrites = (
407
+ key: string,
408
+ id: string,
409
+ actor: () => string = () => 'plugin',
410
+ opens: (fn: string) => boolean = () => false,
411
+ ) => {
412
+ let tail: Promise<unknown> = Promise.resolve();
413
+ return <R>(fn: string, caller: Context, run: (author: Author) => R | Promise<R>): Promise<R> => {
414
+ // oxlint-disable-next-line bridge/no-new-unchecked-cast -- typing: the kernel sets the plugin key symbol on every plugin context
415
+ const plugin = (caller as unknown as Record<symbol, unknown> | null)?.[pluginKey];
416
+ const author = { plugin: String(plugin), actor: actor() };
417
+ const next = tail.then(() => {
418
+ if (plugin !== key && !opens(fn))
419
+ throw coded(`${id}.${fn}: only plugin ${key} writes this domain`, 'not_owner');
420
+ return run(author);
421
+ });
422
+ tail = next.catch(() => {});
423
+ return next;
424
+ };
425
+ };
426
+
427
+ export const isRecord = (value: unknown): value is Record<string, unknown> =>
428
+ typeof value === 'object' && value !== null && !Array.isArray(value);
429
+ /** The top-level field names of `value`; `null` for a value that is not an object (it has no fields). */
430
+ export const fieldsOf = (value: unknown) => (isRecord(value) ? Object.keys(value) : null);
431
+ /** The top-level field names whose value differs (deeply, key order aside) between `before` and `after` (present in either); every field of
432
+ * `after` when there was nothing before; `null` unless both are objects. Names only, never a value. */
433
+ export const changedFields = (before: unknown, after: unknown) => {
434
+ if (before === undefined) return fieldsOf(after);
435
+ if (!isRecord(before) || !isRecord(after)) return null;
436
+ return [...new Set([...Object.keys(before), ...Object.keys(after)])].filter(
437
+ (name) => !isDeepStrictEqual(before[name], after[name]),
438
+ );
439
+ };
440
+
441
+ const knownNode = (nodes: Nodes, node: unknown) => {
442
+ if (typeof node !== 'string' || !nodes.has(node))
443
+ throw coded(`node ${String(node)} is not in this workspace's tree`, 'node_unknown', 400);
444
+ return node;
445
+ };
446
+
447
+ /** `query`, `page` and `count` over a hub store of records keyed by `keyOf`: options checked before anything is read,
448
+ * node visibility from the worker's `nodes` service only (AD-23), the nodes a query may read handed to `scope`,
449
+ * which turns them into the backend filter (`archived`: hidden ones too). */
450
+ export function queries<R>(
451
+ nodes: Nodes,
452
+ id: string,
453
+ store: Store<R>,
454
+ keyOf: (record: R) => string,
455
+ scope: (nodes: string[], archived: boolean) => Filter,
456
+ links: Queries,
457
+ ) {
458
+ /** `invalid_query`, but an `owner_missing` (a relation to an undeclared domain) or a `private_domain` (into another
459
+ * plugin's private domain) stands. */
460
+ const invalid = (fn: string, cause: unknown) =>
461
+ ['owner_missing', 'private_domain'].includes((cause as { code?: string } | null)?.code ?? '')
462
+ ? cause
463
+ : Object.assign(coded(`${id}.${fn}: ${(cause as Error).message}`, 'invalid_query', 400), {
464
+ cause,
465
+ });
466
+ /** `with` checked, as a loader; `undefined` without. */
467
+ const loader = (fn: string, spec: unknown) => {
468
+ try {
469
+ return spec === undefined ? undefined : links.with(spec);
470
+ } catch (cause) {
471
+ throw invalid(fn, cause);
472
+ }
473
+ };
474
+ /** The ids of the nodes `include` reaches from `node`. */
475
+ const reached = (node: string, include: Include) => {
476
+ if (include === 'self') return [node];
477
+ if (include === 'inherited') return nodes.ancestors(node)!.map((each) => each.id);
478
+ // ponytail: every node's ancestors are read per subtree query; a descendants index if trees grow large.
479
+ if (include === 'subtree')
480
+ return nodes
481
+ .list()
482
+ .filter((each) => nodes.ancestors(each.id)?.some((above) => above.id === node))
483
+ .map((each) => each.id);
484
+ throw new Error(
485
+ `${id}.query: include must be self, inherited, or subtree, got ${JSON.stringify(include)}`,
486
+ );
487
+ };
488
+ /** The backend filter and page of `options`, checked; `where` resolved, `orderBy` paths gain the `value.` prefix. */
489
+ const prepare = (
490
+ fn: string,
491
+ {
492
+ node,
493
+ include = 'inherited',
494
+ archived,
495
+ where,
496
+ search,
497
+ orderBy,
498
+ take,
499
+ cursor,
500
+ with: spec,
501
+ }: PageOptions,
502
+ ) => {
503
+ let checked: Where | undefined;
504
+ let order: Order[] | undefined;
505
+ let words: string[] = [];
506
+ let mode: SearchMode = 'prefix';
507
+ try {
508
+ if (search !== undefined) {
509
+ const given = (typeof search === 'string' ? { text: search, mode } : search) as {
510
+ text?: unknown;
511
+ mode?: unknown;
512
+ } | null;
513
+ if (
514
+ typeof given?.text !== 'string' ||
515
+ (given.mode !== 'prefix' && given.mode !== 'contains') ||
516
+ Object.keys(given).length !== 2
517
+ ) {
518
+ throw new Error(
519
+ `search must be a string or { text, mode: 'prefix' | 'contains' }, got ${JSON.stringify(search)}`,
520
+ );
521
+ }
522
+ if (!links.searchable) throw new Error('this domain declares no search paths');
523
+ words = tokens(given.text);
524
+ mode = given.mode;
525
+ }
526
+ if (where !== undefined) checked = checkWhere(links.where(where));
527
+ if (orderBy !== undefined) order = checkOrderBy(orderBy, 2, 'value.');
528
+ checkTake(take);
529
+ } catch (cause) {
530
+ throw invalid(fn, cause);
531
+ }
532
+ const load = loader(fn, spec);
533
+ const after = cursor === undefined ? undefined : decode(cursor, order ?? []);
534
+ knownNode(nodes, node);
535
+ const set = reached(node, include);
536
+ // Visible: on a node with no archived ancestor, and not archived itself.
537
+ const scoped = scope(
538
+ archived === true ? set : set.filter((each) => !inArchivedNode(nodes, each)),
539
+ archived === true,
540
+ );
541
+ const both =
542
+ scoped.where && checked ? { AND: [scoped.where, checked] } : (scoped.where ?? checked);
543
+ const filter: Filter = {
544
+ ...scoped,
545
+ ...(both && { where: checkWhere(both) }),
546
+ ...(words.length > 0 && { search: words, ...(mode === 'contains' && { searchMode: mode }) }),
547
+ };
548
+ return { filter, order: order ?? [], take, after, load };
549
+ };
550
+ /** A cursor: the order it was made for, and the values at each order path of the last object, then its id. Values
551
+ * are scalars or null: an array or object travels as its JSON text, its index listed in `composite`. */
552
+ const encode = (order: Order[], values: unknown[]) => {
553
+ const composite = values.flatMap((each, i) =>
554
+ typeof each === 'object' && each !== null ? [i] : [],
555
+ );
556
+ const after = values.map((each, i) => (composite.includes(i) ? JSON.stringify(each) : each));
557
+ return Buffer.from(
558
+ JSON.stringify({ order, after, ...(composite.length > 0 && { composite }) }),
559
+ ).toString('base64url');
560
+ };
561
+ const decode = (cursor: unknown, order: Order[]) => {
562
+ const refused = () =>
563
+ coded(
564
+ `${id}: this cursor is not a next of a page with the same orderBy`,
565
+ 'invalid_cursor',
566
+ 400,
567
+ );
568
+ let decoded: unknown;
569
+ try {
570
+ decoded = JSON.parse(Buffer.from(String(cursor), 'base64url').toString());
571
+ } catch {}
572
+ // A cursor that is not an object has no fields, so the checks below refuse it.
573
+ const fields = isRecord(decoded) ? decoded : {};
574
+ const after: unknown = fields.after;
575
+ const composite: unknown = fields.composite ?? [];
576
+ const scalar = (value: unknown) =>
577
+ value === null ||
578
+ typeof value === 'string' ||
579
+ typeof value === 'boolean' ||
580
+ (typeof value === 'number' && Number.isFinite(value));
581
+ /** `given` is a cursor's values: one scalar per order term, then the last object's key. */
582
+ const values = (given: unknown): given is unknown[] =>
583
+ Array.isArray(given) &&
584
+ given.length === order.length + 1 &&
585
+ typeof given.at(-1) === 'string' &&
586
+ given.every(scalar);
587
+ if (
588
+ typeof cursor !== 'string' ||
589
+ JSON.stringify(fields.order) !== JSON.stringify(order) ||
590
+ !values(after) ||
591
+ !Array.isArray(composite)
592
+ )
593
+ throw refused();
594
+ return after.map((value, i) => {
595
+ if (!composite.includes(i)) return value;
596
+ let parsed: unknown;
597
+ try {
598
+ parsed = JSON.parse(value as string);
599
+ } catch {}
600
+ if (i === order.length || typeof parsed !== 'object' || parsed === null) throw refused();
601
+ return parsed;
602
+ });
603
+ };
604
+ /** Records, and what `with` loaded for each (absent without). */
605
+ const page = async (fn: string, options: PageOptions) => {
606
+ const { filter, order, take, after, load } = prepare(fn, options);
607
+ // A page of 0 could not say whether objects follow.
608
+ if (fn === 'page' && take !== undefined && take < 1)
609
+ throw coded(`${id}.page: take must be at least 1, got ${take}`, 'invalid_query', 400);
610
+ const ordered = order.length > 0 || take !== undefined || after !== undefined;
611
+ // One more than asked: whether a next page exists.
612
+ const listed = await store.list(
613
+ filter,
614
+ ordered
615
+ ? { orderBy: order, ...(take !== undefined && { take: take + 1 }), ...(after && { after }) }
616
+ : undefined,
617
+ );
618
+ const more = take !== undefined && listed.length > take;
619
+ const items = (more ? listed.slice(0, take) : listed).map(({ value }) => value);
620
+ const last = items.at(-1);
621
+ const extras = load && (await load(items.map((value) => ({ key: keyOf(value), value }))));
622
+ return {
623
+ items,
624
+ extras,
625
+ ...(more &&
626
+ last && {
627
+ next: encode(order, [...order.map(({ path }) => pick(last, path) ?? null), keyOf(last)]),
628
+ }),
629
+ };
630
+ };
631
+ return {
632
+ page,
633
+ count: async (options: CountOptions) => {
634
+ const { orderBy: _, take: __, cursor: ___, with: ____, ...rest } = options as PageOptions;
635
+ return store.count(prepare('count', rest).filter);
636
+ },
637
+ groupBy: async (options: GroupByOptions) => {
638
+ let path: string;
639
+ try {
640
+ if (typeof options !== 'object' || options === null)
641
+ throw new Error(`options must be an object, got ${JSON.stringify(options)}`);
642
+ } catch (cause) {
643
+ throw invalid('groupBy', cause);
644
+ }
645
+ const {
646
+ by,
647
+ mode,
648
+ orderBy,
649
+ cursor,
650
+ with: spec,
651
+ take,
652
+ ...rest
653
+ } = options as GroupByOptions & PageOptions;
654
+ try {
655
+ for (const [name, given] of Object.entries({ orderBy, cursor, with: spec }))
656
+ if (given !== undefined) throw new Error(`groupBy takes no ${name}`);
657
+ if (typeof by !== 'string') throw new Error(`by must be a path, got ${JSON.stringify(by)}`);
658
+ const names = checkPath(by, 2);
659
+ if (names.length === 1 && links.references?.includes(by))
660
+ throw new Error(`${by} is a reference field: group by '${by}.id' instead`);
661
+ path = `value.${names.join('.')}`;
662
+ if (mode !== undefined && mode !== 'default' && mode !== 'insensitive')
663
+ throw new Error(`mode must be 'default' or 'insensitive', got ${JSON.stringify(mode)}`);
664
+ } catch (cause) {
665
+ throw invalid('groupBy', cause);
666
+ }
667
+ const { filter } = prepare('groupBy', { ...rest, ...(take !== undefined && { take }) });
668
+ return store.groupBy(path, filter, {
669
+ insensitive: mode === 'insensitive',
670
+ ...(take !== undefined && { take }),
671
+ });
672
+ },
673
+ loader,
674
+ /** The ids of the nodes `include` reaches from `node`, as reads judge them (a watch's filter too). */
675
+ reached,
676
+ };
677
+ }
678
+
679
+ /** The id a create with key `createKey` by plugin `plugin` (the writer, research-052 D3) gets in domain `domain`: a
680
+ * UUID (version 8, a hash of them), the same for the same key (audit L18-02). */
681
+ const idOfKey = (plugin: string, domain: string, createKey: string) => {
682
+ const hex = createHash('sha256').update(`${plugin}\0${domain}\0${createKey}`).digest('hex');
683
+ const variant = ((parseInt(hex[16]!, 16) & 0x3) | 0x8).toString(16);
684
+ return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-8${hex.slice(13, 16)}-${variant}${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
685
+ };
686
+
687
+ /** The object facade over a hub store of `{ id, node, value }` records. */
688
+ export function objectDomain<T>(
689
+ nodes: Nodes,
690
+ store: Store<StoredObject<T>>,
691
+ key: string,
692
+ id: string,
693
+ links: Links & Queries,
694
+ release: () => void,
695
+ rules: Rules<T> = {},
696
+ /** Open to other plugins' writes but `purge` (`writers: 'workspace'`). */
697
+ open = false,
698
+ ): ObjectDomain<T> {
699
+ const known = (node: unknown) => knownNode(nodes, node);
700
+ const found = async (objectId: unknown) => {
701
+ const object = typeof objectId === 'string' ? await store.get(objectId) : undefined;
702
+ if (!object) throw coded(`${id}: no object ${String(objectId)}`, 'not_found', 404);
703
+ return object;
704
+ };
705
+ /** A node a create or move may target: known, neither it nor an ancestor archived (as `bridgeNodes` refuses), and
706
+ * the owning plugin active there. */
707
+ const target = (node: unknown) => {
708
+ known(node);
709
+ if (nodes.ancestors(node as string)!.some((each) => each.archived))
710
+ throw coded(
711
+ `node ${String(node)} is archived or under an archived node`,
712
+ 'node_archived',
713
+ 400,
714
+ );
715
+ checkActive(nodes, key, node as string);
716
+ return node as string;
717
+ };
718
+ const queued = serialWrites(key, id, links.actor, (fn) => open && fn !== 'purge');
719
+ /** `queued`, refused at once from inside any rule: a write of the rule's own domain would wait for the rule, and
720
+ * one of another domain could wait for a rule of that domain writing back (two queues waiting on each other). */
721
+ const write = <R>(fn: string, caller: Context, run: (author: Author) => R | Promise<R>) => {
722
+ const running = ruling.getStore();
723
+ return running?.length
724
+ ? Promise.reject(
725
+ coded(
726
+ `${id}.${fn}: a rule (of ${running.join(', ')}) cannot write, as the write could wait for a rule forever; write after it, on its event`,
727
+ 'rule_write',
728
+ ),
729
+ )
730
+ : queued(fn, caller, run);
731
+ };
732
+ /** What a rule is told of a write by `author`, after checking its `intent`. */
733
+ const told = (fn: string, author: Author, objectId: string, node: string, intent: unknown) => {
734
+ if (intent !== undefined && typeof intent !== 'string')
735
+ throw coded(
736
+ `${id}.${fn}: intent must be a string, got ${JSON.stringify(intent)}`,
737
+ 'invalid_intent',
738
+ 400,
739
+ );
740
+ return {
741
+ ...author,
742
+ owner: author.plugin === key,
743
+ id: objectId,
744
+ node,
745
+ ...(intent !== undefined && { intent }),
746
+ } satisfies RuleWrite;
747
+ };
748
+ /** Runs `fn`, a rule of this domain, marked in its async chain. */
749
+ const ruled = <R>(fn: () => R) => ruling.run([...(ruling.getStore() ?? []), id], fn);
750
+ /** `value` parsed by the schema, refused `invalid_value` as a write is (`what` names who gave it). */
751
+ const parsed = async (what: string, value: unknown) => {
752
+ let out: unknown;
753
+ await validated(what, async () => {
754
+ out = links.parse ? links.parse(value) : value;
755
+ });
756
+ return out as T;
757
+ };
758
+ /** The value a create or update stores: `value` through `rule` (the new value parsed, then what it returns). */
759
+ const transformed = async (
760
+ fn: 'create' | 'update',
761
+ value: T,
762
+ rule: ((after: T) => T | Promise<T>) | undefined,
763
+ ) => {
764
+ if (!rule) return value;
765
+ const out = await ruled(async () => rule(await parsed(id, value)));
766
+ if (out === undefined)
767
+ throw new Error(`${id}: its ${fn} rule returned nothing: it returns the value to store`);
768
+ return parsed(`${id} (from its ${fn} rule)`, out);
769
+ };
770
+ /** What an event carries of `object`: its view, or only `{ id, node }` for a private domain. */
771
+ const payload = (object: StoredObject<T>) =>
772
+ links.private ? { id: object.id, node: object.node } : view(object);
773
+ /** Stores `object` with its audit meta, then emits `<id>/<action>` with its view (and `extra`). */
774
+ const put = async (
775
+ action: string,
776
+ object: StoredObject<T>,
777
+ audit: AuditMeta,
778
+ extra?: { from: string },
779
+ receipt?: string,
780
+ ) => {
781
+ // One more revision, in the same write; a `mutationId` joins the object's last ones.
782
+ const { receipts } = object as Receipted<T>;
783
+ const next: Receipted<T> = {
784
+ ...object,
785
+ rev: (object.rev ?? 0) + 1,
786
+ ...(receipt !== undefined && {
787
+ receipts: [...(receipts ?? []), receipt].slice(-receiptsKept),
788
+ }),
789
+ };
790
+ await validated(id, () => store.set(object.id, next, audit));
791
+ const stored = view((await store.get(object.id))!);
792
+ nodes.emit(`${id}/${action}`, { ...payload(stored), ...extra });
793
+ return stored;
794
+ };
795
+ /** Stores `object` archived or not; `archived` is stored only when true. */
796
+ const archive = async (
797
+ { archived: _, ...object }: StoredObject<T>,
798
+ archived: boolean,
799
+ author: Author,
800
+ ) => {
801
+ await put(archived ? 'deleted' : 'restored', archived ? { ...object, archived } : object, {
802
+ op: archived ? 'archive' : 'restore',
803
+ fields: null,
804
+ ...author,
805
+ });
806
+ };
807
+ const envelope = async (object: StoredObject<T>): Promise<Envelope<T>> => ({
808
+ ...view(object),
809
+ facets: await links.facets(object.id, object.node),
810
+ });
811
+ const { page, count, groupBy, loader, reached } = queries(
812
+ nodes,
813
+ id,
814
+ store,
815
+ (object) => object.id,
816
+ (visible, archived) => ({ nodes: visible, ...(!archived && { archived: false }) }),
817
+ links,
818
+ );
819
+ /** Views (envelopes with `facets`), each with what `with` loaded. */
820
+ const shown = (
821
+ objects: StoredObject<T>[],
822
+ extras: Related[] | undefined,
823
+ facets: boolean | undefined,
824
+ ) =>
825
+ Promise.all(
826
+ objects.map(async (object, i) => ({
827
+ ...(facets ? await envelope(object) : view(object)),
828
+ ...extras?.[i],
829
+ })),
830
+ );
831
+ // Watches (research-021 D3, B2, B13): one hub per domain, made on the first watch, gone with the last. It keeps each
832
+ // object's last known node and archived flag, so a window's change is judged on both sides: an archive or a move out
833
+ // reaches a watcher that saw the object before, a move in one that sees it after.
834
+ type Seen = { node: string; archived: boolean };
835
+ type Watcher = { filter: Required<WatchFilter>; push: (message: WatchMessage) => void };
836
+ let hub:
837
+ | {
838
+ watchers: Set<Watcher>;
839
+ known: Map<string, Seen>;
840
+ /** This window's changes: the state before the first and after the last (`purged` for a deletion). */
841
+ window: Map<string, { before: Seen | undefined; after: Seen | 'purged' }>;
842
+ ready: Promise<void>;
843
+ stop: () => void;
844
+ timer: ReturnType<typeof setTimeout> | undefined;
845
+ windowMs: number;
846
+ /** Since when every window sent `{ all }` to some watcher; `slowed` once logged. */
847
+ allSince: number | undefined;
848
+ slowed: boolean;
849
+ }
850
+ | undefined;
851
+ const visibleTo = ({ node, include, archived }: Required<WatchFilter>, seen: Seen) =>
852
+ reached(node, include).includes(seen.node) &&
853
+ (archived || (!seen.archived && !inArchivedNode(nodes, seen.node)));
854
+ const flush = () => {
855
+ const held = hub;
856
+ if (!held) return;
857
+ held.timer = undefined;
858
+ const changes = [...held.window];
859
+ held.window.clear();
860
+ let all = false;
861
+ for (const watcher of held.watchers) {
862
+ const ids = changes.flatMap(([objectId, { before, after }]) =>
863
+ (before && visibleTo(watcher.filter, before)) ||
864
+ (after !== 'purged' && visibleTo(watcher.filter, after))
865
+ ? [
866
+ {
867
+ id: objectId,
868
+ action: after === 'purged' ? ('purged' as const) : ('changed' as const),
869
+ },
870
+ ]
871
+ : [],
872
+ );
873
+ if (ids.length > watchLimits.ids) {
874
+ all = true;
875
+ watcher.push({ all: true });
876
+ } else if (ids.length) watcher.push({ ids });
877
+ }
878
+ // A domain written past 100 ids a window for 5 s: windows of 1 s, said once.
879
+ const now = Date.now();
880
+ held.allSince = all ? (held.allSince ?? now) : undefined;
881
+ if (
882
+ held.allSince !== undefined &&
883
+ now - held.allSince >= watchLimits.slowAfterMs &&
884
+ held.windowMs !== watchLimits.slowWindowMs
885
+ ) {
886
+ held.windowMs = watchLimits.slowWindowMs;
887
+ if (!held.slowed) {
888
+ held.slowed = true;
889
+ console.warn(
890
+ `storage: ${id} written past ${watchLimits.ids} objects a window, watch notifications slowed`,
891
+ );
892
+ }
893
+ } else if (held.allSince === undefined) held.windowMs = watchLimits.windowMs;
894
+ };
895
+ const startHub = () => {
896
+ const known = new Map<string, Seen>();
897
+ const window = new Map<string, { before: Seen | undefined; after: Seen | 'purged' }>();
898
+ let revision = nodes.revision;
899
+ const unsubscribe = store.subscribe((objectId, object) => {
900
+ const held = hub;
901
+ if (!held) return;
902
+ const after: Seen | 'purged' = object
903
+ ? { node: object.node, archived: object.archived === true }
904
+ : 'purged';
905
+ const change = window.get(objectId) ?? { before: known.get(objectId), after };
906
+ change.after = after;
907
+ window.set(objectId, change);
908
+ if (after === 'purged') known.delete(objectId);
909
+ else known.set(objectId, after);
910
+ held.timer ??= setTimeout(flush, held.windowMs);
911
+ });
912
+ // The tree's own changes (a node archived, moved, restored) write no object: every watcher reads again.
913
+ const tree = setInterval(() => {
914
+ if (nodes.revision === revision) return;
915
+ revision = nodes.revision;
916
+ for (const watcher of hub?.watchers ?? []) watcher.push({ all: true });
917
+ }, 1000);
918
+ const started = {
919
+ watchers: new Set<Watcher>(),
920
+ known,
921
+ window,
922
+ // What each object was when watching began: a change seen during the listing keeps its own state.
923
+ ready: store.list().then((entries) => {
924
+ for (const { key: objectId, value } of entries)
925
+ if (!known.has(objectId))
926
+ known.set(objectId, { node: value.node, archived: value.archived === true });
927
+ }),
928
+ stop: () => {
929
+ unsubscribe();
930
+ clearInterval(tree);
931
+ clearTimeout(started.timer);
932
+ },
933
+ timer: undefined as ReturnType<typeof setTimeout> | undefined,
934
+ windowMs: watchLimits.windowMs,
935
+ allSince: undefined as number | undefined,
936
+ slowed: false,
937
+ };
938
+ return started;
939
+ };
940
+ function watch(
941
+ { node, include = 'inherited', archived = false }: WatchFilter,
942
+ signal?: AbortSignal,
943
+ ): AsyncIterable<WatchMessage> {
944
+ if (typeof node !== 'string' || !nodes.has(node))
945
+ throw coded(`${id}.watch: no node ${JSON.stringify(node)}`, 'invalid_query', 400);
946
+ reached(node, include); // throws on a bad include
947
+ const filter = { node, include, archived: archived === true };
948
+ return {
949
+ [Symbol.asyncIterator]: () => {
950
+ const queue: WatchMessage[] = [];
951
+ let wake: (() => void) | undefined;
952
+ let done = false;
953
+ const watcher: Watcher = {
954
+ filter,
955
+ push: (message) => {
956
+ queue.push(message);
957
+ wake?.();
958
+ },
959
+ };
960
+ const held = (hub ??= startHub());
961
+ // A watcher joins at a window's edge: the changes before it go to those already watching, judged on what they
962
+ // saw; its own view starts from its read after `ready`.
963
+ if (held.window.size > 0) {
964
+ clearTimeout(held.timer);
965
+ flush();
966
+ }
967
+ held.watchers.add(watcher);
968
+ const end = () => {
969
+ if (done) return;
970
+ done = true;
971
+ held.watchers.delete(watcher);
972
+ if (held.watchers.size === 0 && hub === held) {
973
+ held.stop();
974
+ hub = undefined;
975
+ }
976
+ wake?.();
977
+ };
978
+ signal?.addEventListener('abort', end, { once: true });
979
+ let readied = false;
980
+ return {
981
+ next: async (): Promise<IteratorResult<WatchMessage>> => {
982
+ if (!readied) {
983
+ readied = true;
984
+ await held.ready;
985
+ if (!done) return { value: { ready: true }, done: false };
986
+ }
987
+ while (!done && queue.length === 0)
988
+ await new Promise<void>((resolve) => {
989
+ wake = resolve;
990
+ });
991
+ wake = undefined;
992
+ const message = queue.shift();
993
+ return message && !done
994
+ ? { value: message, done: false }
995
+ : { value: undefined, done: true };
996
+ },
997
+ return: async () => {
998
+ end();
999
+ return { value: undefined, done: true };
1000
+ },
1001
+ };
1002
+ },
1003
+ };
1004
+ }
1005
+
1006
+ return {
1007
+ create: (caller, value, options) =>
1008
+ write('create', caller, async (author) => {
1009
+ if (typeof options?.node !== 'string' || !options.node)
1010
+ throw new Error(`${id}.create: a node is required`);
1011
+ const { key: createKey } = options;
1012
+ if (
1013
+ createKey !== undefined &&
1014
+ (typeof createKey !== 'string' || !/^[\w-]{1,128}$/.test(createKey))
1015
+ )
1016
+ throw coded(
1017
+ `${id}.create: key must be 1 to 128 letters, digits, - or _`,
1018
+ 'invalid_key',
1019
+ 400,
1020
+ );
1021
+ // The same key, the same id: an object already there is that create's, answered as it is (archived too, not
1022
+ // restored). ponytail: a purge forgets the key, and the same key creates again; a key log kept apart from the
1023
+ // objects would remember it past a purge.
1024
+ const objectId =
1025
+ createKey === undefined ? randomUUID() : idOfKey(author.plugin, id, createKey);
1026
+ if (createKey !== undefined) {
1027
+ const made = await store.get(objectId);
1028
+ if (made) return view(made);
1029
+ }
1030
+ const node = target(options.node);
1031
+ const ruleWrite = told('create', author, objectId, node, options.intent);
1032
+ const stored = await transformed(
1033
+ 'create',
1034
+ value,
1035
+ rules.create && ((each) => rules.create!(each, ruleWrite)),
1036
+ );
1037
+ await links.check(stored);
1038
+ return put(
1039
+ 'created',
1040
+ { id: objectId, node, value: stored },
1041
+ { op: 'create', fields: fieldsOf(stored), ...author },
1042
+ );
1043
+ }),
1044
+ update: (caller, objectId, value, options) =>
1045
+ write('update', caller, async (author) => {
1046
+ const { rev, mutationId, intent } = options ?? {};
1047
+ if (rev !== undefined && (!Number.isInteger(rev) || rev < 0))
1048
+ throw coded(
1049
+ `${id}.update: rev must be a whole number, got ${JSON.stringify(rev)}`,
1050
+ 'invalid_rev',
1051
+ 400,
1052
+ );
1053
+ if (
1054
+ mutationId !== undefined &&
1055
+ (typeof mutationId !== 'string' || !/^[\w-]{1,128}$/.test(mutationId))
1056
+ )
1057
+ throw coded(
1058
+ `${id}.update: mutationId must be 1 to 128 letters, digits, - or _`,
1059
+ 'invalid_mutation',
1060
+ 400,
1061
+ );
1062
+ const object = await found(objectId);
1063
+ // Already applied (a retry after a lost answer): the object as it is, no second write.
1064
+ if (mutationId !== undefined && (object as Receipted<T>).receipts?.includes(mutationId))
1065
+ return view(object);
1066
+ if (rev !== undefined && rev !== (object.rev ?? 0))
1067
+ throw Object.assign(
1068
+ coded(
1069
+ `${id}.update: ${objectId} changed since revision ${rev} (now ${object.rev ?? 0})`,
1070
+ 'conflict',
1071
+ 409,
1072
+ ),
1073
+ { details: { current: view(object) } },
1074
+ );
1075
+ const ruleWrite = told('update', author, object.id, object.node, intent);
1076
+ const stored = await transformed(
1077
+ 'update',
1078
+ value,
1079
+ rules.update && ((after) => rules.update!(view(object), after, ruleWrite)),
1080
+ );
1081
+ await links.check(stored);
1082
+ return put(
1083
+ 'updated',
1084
+ { ...object, value: stored },
1085
+ { op: 'update', fields: changedFields(object.value, stored), ...author },
1086
+ undefined,
1087
+ mutationId,
1088
+ );
1089
+ }),
1090
+ move: (caller, objectId, node, options) =>
1091
+ write('move', caller, async (author) => {
1092
+ const object = await found(objectId);
1093
+ const ruleWrite = told('move', author, object.id, object.node, options?.intent);
1094
+ if (object.node === node) return view(object); // already there: no write, no event
1095
+ target(node);
1096
+ if (rules.move) await ruled(() => rules.move!(view(object), node, ruleWrite));
1097
+ return put(
1098
+ 'moved',
1099
+ { ...object, node },
1100
+ { op: 'move', fields: ['node'], ...author },
1101
+ { from: object.node },
1102
+ );
1103
+ }),
1104
+ delete: (caller, objectId, options) =>
1105
+ write('delete', caller, async (author) => {
1106
+ const object = await found(objectId);
1107
+ const ruleWrite = told('delete', author, object.id, object.node, options?.intent);
1108
+ if (object.archived === true) return;
1109
+ if (rules.delete) await ruled(() => rules.delete!(view(object), ruleWrite));
1110
+ await archive(object, true, author);
1111
+ }),
1112
+ restore: (caller, objectId, options) =>
1113
+ write('restore', caller, async (author) => {
1114
+ const object = await found(objectId);
1115
+ const ruleWrite = told('restore', author, object.id, object.node, options?.intent);
1116
+ if (object.archived !== true) return;
1117
+ if (rules.restore) await ruled(() => rules.restore!(view(object), ruleWrite));
1118
+ await archive(object, false, author);
1119
+ }),
1120
+ purge: (caller, objectId) =>
1121
+ write('purge', caller, async (author) => {
1122
+ const object = await found(objectId);
1123
+ // ponytail: a referrer written in another domain while this purge runs is not seen; a cross-domain lock if it matters.
1124
+ // ponytail: loaded plugins only: references held by a disabled plugin's domains are not indexed, so they do not
1125
+ // refuse the purge (they then resolve `missing`); a persisted index if that matters.
1126
+ const users = links.usedBy(objectId);
1127
+ if (users.length > 0)
1128
+ throw coded(`${id}: ${objectId} is used by ${users.join(', ')}`, 'in_use', 409);
1129
+ // Its facets in declared facet domains and the object, one batch. A backend writing domain after domain
1130
+ // (JSON) writes the facets first: a failure leaves the object, never orphan facets.
1131
+ // Present ones get a `deleted` event; the batch, built when written, deletes in every facet domain held then (a
1132
+ // facet set since the read goes too; one released since is not reached).
1133
+ // Audited: the object's `purge` (its plugin), and a `delete` per facet present (plugin `storage`, the mechanism's
1134
+ // owner, whoever's facet it is); a facet domain holding none gets an unaudited deletion of an absent key.
1135
+ // ponytail: a facet set between `facetsOn` and the batch is deleted without its row; read them in the batch's turn if it matters.
1136
+ const facets = await links.facetsOn(objectId);
1137
+ const facetAudit: AuditMeta = {
1138
+ op: 'delete',
1139
+ fields: null,
1140
+ plugin: 'storage',
1141
+ actor: author.actor,
1142
+ };
1143
+ await links.write([
1144
+ ...links.facetDomains().map((facetId) => ({
1145
+ id: facetId,
1146
+ key: objectId,
1147
+ ...(facets.includes(facetId) && { audit: facetAudit }),
1148
+ })),
1149
+ { id, key: objectId, audit: { op: 'purge', fields: null, ...author } },
1150
+ ]);
1151
+ for (const facetId of facets)
1152
+ nodes.emit(`${facetId}/deleted`, { target: objectId, node: object.node });
1153
+ nodes.emit(`${id}/purged`, payload(object));
1154
+ }),
1155
+ get: (async (objectId: string, options?: { facets?: boolean; with?: With }) => {
1156
+ const load = loader('get', options?.with);
1157
+ const object = await store.get(objectId);
1158
+ if (!object) return undefined;
1159
+ return (
1160
+ await shown(
1161
+ [object],
1162
+ load && (await load([{ key: object.id, value: object }])),
1163
+ options?.facets,
1164
+ )
1165
+ )[0];
1166
+ }) as ObjectDomain<T>['get'],
1167
+ query: (async (options: QueryOptions & { facets?: boolean }) => {
1168
+ const { cursor: _, ...rest } = options as PageOptions;
1169
+ const { items, extras } = await page('query', rest);
1170
+ return shown(items, extras, options.facets);
1171
+ }) as ObjectDomain<T>['query'],
1172
+ page: (async (options: PageOptions & { facets?: boolean }) => {
1173
+ const { items, extras, next } = await page('page', options);
1174
+ return {
1175
+ items: await shown(items, extras, options.facets),
1176
+ ...(next !== undefined && { next }),
1177
+ };
1178
+ }) as ObjectDomain<T>['page'],
1179
+ count,
1180
+ groupBy,
1181
+ subscribe: (fn) => store.subscribe((objectId, object) => fn(objectId, object && view(object))),
1182
+ watch,
1183
+ release,
1184
+ };
1185
+ }