@nocentraldb/sdk 0.0.0-stage → 0.1.0-alpha.70

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 (58) hide show
  1. package/dist/account.d.ts +14 -0
  2. package/dist/account.js +34 -0
  3. package/dist/accountCalls.d.ts +34 -0
  4. package/dist/accountCalls.js +48 -0
  5. package/dist/adHoc.d.ts +49 -0
  6. package/dist/adHoc.js +52 -0
  7. package/dist/cbor.d.ts +8 -0
  8. package/dist/cbor.js +223 -0
  9. package/dist/connect.d.ts +14 -0
  10. package/dist/connect.js +527 -0
  11. package/dist/connectParts.d.ts +29 -0
  12. package/dist/connectParts.js +10 -0
  13. package/dist/db.d.ts +291 -0
  14. package/dist/db.js +17 -0
  15. package/dist/durability.d.ts +20 -0
  16. package/dist/durability.js +5 -0
  17. package/dist/durabilityReport.d.ts +29 -0
  18. package/dist/durabilityReport.js +128 -0
  19. package/dist/elements.d.ts +5 -0
  20. package/dist/elements.js +13 -0
  21. package/dist/error.d.ts +10 -0
  22. package/dist/error.js +23 -0
  23. package/dist/index.d.ts +19 -0
  24. package/dist/index.js +6 -0
  25. package/dist/lockCheck.d.ts +4 -0
  26. package/dist/lockCheck.js +63 -0
  27. package/dist/members.d.ts +55 -0
  28. package/dist/members.js +38 -0
  29. package/dist/membership.d.ts +5 -0
  30. package/dist/membership.js +29 -0
  31. package/dist/nc.d.ts +153 -0
  32. package/dist/nc.js +211 -0
  33. package/dist/query.d.ts +21 -0
  34. package/dist/query.js +45 -0
  35. package/dist/reports.d.ts +8 -0
  36. package/dist/reports.js +50 -0
  37. package/dist/spaceList.d.ts +14 -0
  38. package/dist/spaceList.js +45 -0
  39. package/dist/status.d.ts +51 -0
  40. package/dist/status.js +5 -0
  41. package/dist/sync.d.ts +15 -0
  42. package/dist/sync.js +4 -0
  43. package/dist/tabs.d.ts +30 -0
  44. package/dist/tabs.js +444 -0
  45. package/dist/texts.d.ts +52 -0
  46. package/dist/texts.js +58 -0
  47. package/dist/waitNotice.d.ts +7 -0
  48. package/dist/waitNotice.js +32 -0
  49. package/dist/wasm/nocentraldb_wasm.d.ts +91 -0
  50. package/dist/wasm/nocentraldb_wasm.js +1058 -0
  51. package/dist/wasm/nocentraldb_wasm_bg.wasm +0 -0
  52. package/dist/wasm/nocentraldb_wasm_bg.wasm.d.ts +36 -0
  53. package/dist/worker.d.ts +1 -0
  54. package/dist/worker.js +142 -0
  55. package/dist/workerHost.d.ts +3 -0
  56. package/dist/workerHost.js +55 -0
  57. package/package.json +21 -4
  58. package/README.md +0 -3
@@ -0,0 +1,527 @@
1
+ // The implementation behind `nc.open` (NOC-176 slices 1 and 2): the worker
2
+ // that runs the core, and the database the SDK builds on any core that
3
+ // answers the bridge's protocol (crates/nocentraldb/src/bridge/mod.rs).
4
+ // Subscriptions re-run their read after the core's `folded` events, which
5
+ // name the space and collections of each fold, never values. Internal:
6
+ // the package's entry does not reach it, so it is not in the API report;
7
+ // the vitest tests pass a fake core to `connect`.
8
+ import { accountOf } from "./accountCalls.js";
9
+ import { createAdHoc, lookupsOf, readObjects } from "./adHoc.js";
10
+ import { decode, encode } from "./cbor.js";
11
+ import { flatten, randomId, } from "./connectParts.js";
12
+ import { reportsOf } from "./durabilityReport.js";
13
+ import { SetElements } from "./elements.js";
14
+ import { NcError } from "./error.js";
15
+ import { lockOutOfDate } from "./lockCheck.js";
16
+ import { membersOf, ownInvitation } from "./membership.js";
17
+ import { Cursor, queryState } from "./query.js";
18
+ import { notify, spaceStatusOf, syncStatusOf } from "./reports.js";
19
+ import { spaceListOf } from "./spaceList.js";
20
+ import { browserPage, tabCore } from "./tabs.js";
21
+ import * as texts from "./texts.js";
22
+ import { startWorker } from "./workerHost.js";
23
+ /** The rule RFC 0006 sets for a browser database's name ("The browser"). */
24
+ const NAME = /^[a-z0-9_-]{1,64}$/;
25
+ const DESCRIBE = Symbol.for("nocentraldb.model.describe");
26
+ /** Opens the database in the worker the package ships, or, when another tab owns it, through that tab (NOC-177; RFC 0006, "The browser"). */
27
+ export const connectWorker = async (options) => {
28
+ checkName(options.name);
29
+ // Before the worker starts, so that no database opens with a model its
30
+ // lock was not built from (NOC-323; RFC 0009, "Open and close").
31
+ const outOfDate = lockOutOfDate(options.model, options.lock);
32
+ if (outOfDate !== undefined)
33
+ throw new NcError("lockOutOfDate", outOfDate);
34
+ const core = typeof navigator !== "undefined" &&
35
+ navigator.locks !== undefined &&
36
+ typeof BroadcastChannel !== "undefined"
37
+ ? await tabCore(options.name ?? "default", {
38
+ locks: navigator.locks,
39
+ channel: (name) => new BroadcastChannel(name),
40
+ startWorker,
41
+ page: browserPage(),
42
+ })
43
+ : startWorker();
44
+ return connect(core, options);
45
+ };
46
+ const checkName = (name) => {
47
+ if (name !== undefined && !NAME.test(name)) {
48
+ throw new NcError("invalidValue", texts.NOT_ADATABASE_NAME);
49
+ }
50
+ };
51
+ /** Opens the database through `core`. Internal: `open` passes the worker, a test a fake. */
52
+ export const connect = async (core, options) => {
53
+ try {
54
+ checkName(options.name);
55
+ }
56
+ catch (error) {
57
+ core.terminate();
58
+ throw error;
59
+ }
60
+ const names = new Map();
61
+ for (const [name, collection] of Object.entries(options.model)) {
62
+ names.set(collection, name);
63
+ }
64
+ const describe = options.model[DESCRIBE];
65
+ const described = describe ? describe().collections : {};
66
+ let next = 0;
67
+ let closed = false;
68
+ const ask = async (call, args) => {
69
+ if (closed)
70
+ throw new NcError("closed", texts.DATABASE_CLOSED);
71
+ next += 1;
72
+ const answer = decode(await core.call(encode({ id: next, call, args })));
73
+ if (answer.error) {
74
+ const { code, message, ids, fingerprint } = answer.error;
75
+ throw new NcError(code, message, ids ?? [], fingerprint);
76
+ }
77
+ return answer.ok ?? null;
78
+ };
79
+ let opened;
80
+ try {
81
+ opened = await ask("open", {
82
+ lock: JSON.stringify(options.lock),
83
+ name: options.name ?? "default",
84
+ relay: options.relay,
85
+ pairing: options.pairing === "request" ? true : undefined,
86
+ recover: options.recover,
87
+ });
88
+ }
89
+ catch (error) {
90
+ core.terminate();
91
+ throw error;
92
+ }
93
+ // The newest sync status the core sent: at open, then in its `sync`
94
+ // events, so that `db.sync.current()` answers at once.
95
+ // The relay that serves this database: this tab's option, or, when
96
+ // another tab owns the database, that tab's (NOC-177).
97
+ let relay = opened?.relay ?? options.relay;
98
+ let sync = syncStatusOf(opened?.sync, relay);
99
+ const reports = reportsOf(ask, (opened ?? {}), options.persistentStorage);
100
+ const syncListeners = new Set();
101
+ const spaceList = spaceListOf(ask);
102
+ // Who waits for the next sync status: `db.sync.confirmed`.
103
+ const syncWaiters = new Set();
104
+ const nextSync = () => {
105
+ let waiter;
106
+ const promise = new Promise((resolve, reject) => {
107
+ waiter = { resolve, reject };
108
+ });
109
+ syncWaiters.add(waiter);
110
+ return { promise, cancel: () => syncWaiters.delete(waiter) };
111
+ };
112
+ const synced = (raw) => {
113
+ sync = syncStatusOf(raw, relay);
114
+ notify(syncListeners, sync);
115
+ for (const waiter of [...syncWaiters]) {
116
+ syncWaiters.delete(waiter);
117
+ waiter.resolve();
118
+ }
119
+ };
120
+ const isConfirmed = async (change) => (await ask("sync.isConfirmed", { change })) === true;
121
+ // Each space's newest status and who follows it, shared by every handle
122
+ // of the space: the core answers `space.status` with it, and sends a
123
+ // `spaceStatus` event whenever it changes.
124
+ const statuses = new Map();
125
+ const statusChanged = (id, raw) => {
126
+ const entry = statuses.get(id);
127
+ if (entry === undefined)
128
+ return;
129
+ entry.status = spaceStatusOf(raw);
130
+ notify(entry.listeners, entry.status);
131
+ };
132
+ /** A handle of the space `id`, with its status, which the core follows from now on. */
133
+ const read = readObjects();
134
+ const handleOf = async (id) => {
135
+ const raw = await ask("space.status", { space: id });
136
+ const entry = statuses.get(id);
137
+ if (entry === undefined) {
138
+ statuses.set(id, { status: spaceStatusOf(raw), listeners: new Set() });
139
+ }
140
+ else {
141
+ entry.status = spaceStatusOf(raw);
142
+ }
143
+ return space(id);
144
+ };
145
+ // The identity of this database, which its cursors carry.
146
+ const identity = {};
147
+ const subscriptions = new Set();
148
+ const changeListeners = new Set();
149
+ let pending = [];
150
+ core.listen((bytes) => {
151
+ if (closed)
152
+ return;
153
+ const message = decode(bytes);
154
+ if (message.event === "sync") {
155
+ synced(message.status);
156
+ return;
157
+ }
158
+ if (message.event === "durability") {
159
+ reports.durabilityChanged(message.durability);
160
+ return;
161
+ }
162
+ if (message.event === "waitingForTab") {
163
+ reports.waitingChanged(message.waiting === true);
164
+ return;
165
+ }
166
+ if (message.event === "view") {
167
+ reports.viewChanged(message.view);
168
+ return;
169
+ }
170
+ if (message.event === "spaces") {
171
+ spaceList.changed(message.spaces);
172
+ return;
173
+ }
174
+ if (message.event === "spaceStatus") {
175
+ statusChanged(message.space, message.status);
176
+ return;
177
+ }
178
+ if (message.event === "reopened") {
179
+ // Another tab took the database over (NOC-177): its core follows no
180
+ // space yet and its reads may differ, so everything is read again.
181
+ relay = message.relay;
182
+ synced(message.sync);
183
+ for (const id of statuses.keys()) {
184
+ ask("space.status", { space: id }).then((raw) => statusChanged(id, raw), () => { });
185
+ }
186
+ spaceList.reopened();
187
+ reports.reopened();
188
+ for (const subscription of subscriptions)
189
+ rerun(subscription);
190
+ return;
191
+ }
192
+ if (message.event !== "folded" || !message.folds)
193
+ return;
194
+ for (const fold of message.folds) {
195
+ for (const changed of fold.changes ?? []) {
196
+ const change = {
197
+ space: fold.space,
198
+ collection: changed.collection,
199
+ ids: changed.ids,
200
+ origin: changed.origin,
201
+ };
202
+ for (const listener of [...changeListeners]) {
203
+ try {
204
+ listener(change);
205
+ }
206
+ catch {
207
+ // A listener that throws loses this change, and the others
208
+ // still get it.
209
+ }
210
+ }
211
+ }
212
+ }
213
+ if (pending.length === 0)
214
+ queueMicrotask(flush);
215
+ pending.push(...message.folds);
216
+ });
217
+ // Re-runs, once, every subscription a batch of folds may have changed.
218
+ const flush = () => {
219
+ const folds = pending;
220
+ pending = [];
221
+ for (const subscription of subscriptions) {
222
+ if (folds.some((fold) => fold.collections.includes(subscription.collection) &&
223
+ (subscription.space === undefined ||
224
+ subscription.space === fold.space))) {
225
+ rerun(subscription);
226
+ }
227
+ }
228
+ };
229
+ // Runs a subscription's read; one that is asked again while it runs runs
230
+ // once more after it, so a listener sees the newest state and never two
231
+ // reads at once.
232
+ const rerun = (subscription) => {
233
+ if (closed || !subscriptions.has(subscription))
234
+ return;
235
+ if (subscription.running) {
236
+ subscription.again = true;
237
+ return;
238
+ }
239
+ subscription.running = true;
240
+ subscription
241
+ .run()
242
+ .catch(() => { })
243
+ .finally(() => {
244
+ subscription.running = false;
245
+ if (subscription.again) {
246
+ subscription.again = false;
247
+ rerun(subscription);
248
+ }
249
+ });
250
+ };
251
+ const follow = (collection, spaceId, run) => {
252
+ const subscription = {
253
+ collection,
254
+ space: spaceId,
255
+ run,
256
+ running: false,
257
+ again: false,
258
+ };
259
+ subscriptions.add(subscription);
260
+ rerun(subscription);
261
+ return () => {
262
+ subscriptions.delete(subscription);
263
+ };
264
+ };
265
+ /** A page of `query`, in `spaceId` when it names one. */
266
+ const find = async (query, spaceId) => {
267
+ if (closed)
268
+ throw new NcError("closed", texts.DATABASE_CLOSED);
269
+ const state = queryState(query);
270
+ if (state === undefined) {
271
+ throw new NcError("invalidValue", texts.NOT_AQUERY_START_ONE);
272
+ }
273
+ const asked = {
274
+ collection: nameOf(state.collection),
275
+ index: state.index,
276
+ };
277
+ if (state.equal !== undefined) {
278
+ asked.equal = state.equal.map((v) => typeof v === "string" ? v.normalize("NFC") : v);
279
+ }
280
+ if (state.take !== undefined)
281
+ asked.take = state.take;
282
+ if (state.after !== undefined) {
283
+ const handle = state.after instanceof Cursor
284
+ ? state.after.handleIn(identity)
285
+ : undefined;
286
+ if (handle === undefined) {
287
+ throw new NcError("cursorOfAnotherModel", texts.CURSOR_OF_ANOTHER_DATABASE);
288
+ }
289
+ asked.after = handle;
290
+ }
291
+ const args = { query: asked };
292
+ if (spaceId !== undefined)
293
+ args.space = spaceId;
294
+ const answer = (await ask("find", args));
295
+ return {
296
+ items: answer.items.map((item) => read.remember(flatten(item), asked.collection)),
297
+ cursor: answer.cursor === null
298
+ ? undefined
299
+ : new Cursor(identity, answer.cursor),
300
+ hasMore: answer.hasMore,
301
+ };
302
+ };
303
+ /** The collection a query reads. */
304
+ const collectionOf = (query) => {
305
+ const state = queryState(query);
306
+ if (state === undefined) {
307
+ throw new NcError("invalidValue", texts.NOT_AQUERY);
308
+ }
309
+ return nameOf(state.collection);
310
+ };
311
+ const nameOf = (collection) => {
312
+ const name = names.get(collection);
313
+ if (name === undefined) {
314
+ throw new NcError("notFound", texts.NO_SUCH_COLLECTION);
315
+ }
316
+ return name;
317
+ };
318
+ const value = (collection, field, written) => {
319
+ if (written === null)
320
+ return null;
321
+ if (written instanceof SetElements) {
322
+ const elements = written.elements.map((e) => element(collection, field, e, true));
323
+ return written.add ? { $add: elements } : { $remove: elements };
324
+ }
325
+ return element(collection, field, written, false);
326
+ };
327
+ const element = (collection, field, written, inSet) => {
328
+ const type = described[collection]?.fields[field];
329
+ const kind = inSet ? (type?.of?.type ?? type?.type) : type?.type;
330
+ if (kind === "ncdb/int" &&
331
+ !(typeof written === "number" && Number.isSafeInteger(written))) {
332
+ throw new NcError("invalidValue", texts.notASafeInteger(collection, field));
333
+ }
334
+ if (typeof written === "string")
335
+ return written.normalize("NFC");
336
+ return written;
337
+ };
338
+ const values = (collection, written) => {
339
+ const out = {};
340
+ for (const [field, v] of Object.entries(written)) {
341
+ if (v !== undefined)
342
+ out[field] = value(collection, field, v);
343
+ }
344
+ return out;
345
+ };
346
+ const space = (id) => {
347
+ const write = async (record) => {
348
+ if (closed)
349
+ throw new NcError("closed", texts.DATABASE_CLOSED);
350
+ const ops = [];
351
+ const tx = {
352
+ create: (collection, written) => {
353
+ const name = nameOf(collection);
354
+ const created = randomId();
355
+ ops.push({
356
+ op: "create",
357
+ collection: name,
358
+ id: created,
359
+ values: values(name, written),
360
+ });
361
+ return created;
362
+ },
363
+ update: (collection, object, written) => {
364
+ const name = nameOf(collection);
365
+ ops.push({
366
+ op: "update",
367
+ collection: name,
368
+ id: object,
369
+ values: values(name, written),
370
+ });
371
+ },
372
+ delete: (collection, object) => {
373
+ ops.push({
374
+ op: "delete",
375
+ collection: nameOf(collection),
376
+ id: object,
377
+ });
378
+ },
379
+ restore: (collection, object) => {
380
+ ops.push({
381
+ op: "restore",
382
+ collection: nameOf(collection),
383
+ id: object,
384
+ });
385
+ },
386
+ };
387
+ record(tx);
388
+ return (await ask("write", { space: id, ops }));
389
+ };
390
+ return {
391
+ id,
392
+ write,
393
+ create: (collection, written) => write((tx) => void tx.create(collection, written)),
394
+ update: (collection, object, written) => write((tx) => tx.update(collection, object, written)),
395
+ delete: (collection, object) => write((tx) => tx.delete(collection, object)),
396
+ restore: (collection, object) => write((tx) => tx.restore(collection, object)),
397
+ members: membersOf(ask, id),
398
+ ...lookupsOf(ask, id),
399
+ leave: async () => (await ask("space.leave", { space: id })),
400
+ erasures: {
401
+ list: async () => (await ask("erasures.list", { space: id })),
402
+ },
403
+ status: {
404
+ current: () => statuses.get(id).status,
405
+ subscribe: (listener) => {
406
+ const entry = statuses.get(id);
407
+ if (entry === undefined || closed)
408
+ return () => { };
409
+ entry.listeners.add(listener);
410
+ listener(entry.status);
411
+ return () => {
412
+ entry.listeners.delete(listener);
413
+ };
414
+ },
415
+ },
416
+ get: (collection, object) => get(id, collection, object),
417
+ find: (query) => find(query, id),
418
+ subscribe: ((first, second, third) => {
419
+ if (queryState(first) !== undefined) {
420
+ const listener = second;
421
+ return follow(collectionOf(first), id, async () => listener(await find(first, id)));
422
+ }
423
+ const object = second;
424
+ const listener = third;
425
+ return follow(nameOf(first), id, async () => listener(await get(id, first, object)));
426
+ }),
427
+ };
428
+ };
429
+ const get = async (spaceId, collection, object) => {
430
+ if (closed)
431
+ throw new NcError("closed", texts.DATABASE_CLOSED);
432
+ const answer = (await ask("get", {
433
+ space: spaceId,
434
+ collection: nameOf(collection),
435
+ id: object,
436
+ }));
437
+ return answer === null
438
+ ? undefined
439
+ : read.remember(flatten(answer), nameOf(collection));
440
+ };
441
+ return {
442
+ spaces: {
443
+ create: async () => handleOf((await ask("spaces.create", {}))),
444
+ get: async (id) => handleOf((await ask("spaces.get", { space: id }))),
445
+ list: async () => (await ask("spaces.list", {})),
446
+ subscribe: (listener) => closed ? () => { } : spaceList.subscribe(listener),
447
+ createAdHoc: async (options) => {
448
+ const answer = await createAdHoc(ask, read, options);
449
+ return { ...answer, space: await handleOf(answer.space) };
450
+ },
451
+ },
452
+ find: (query) => find(query),
453
+ changes: {
454
+ subscribe: (listener) => {
455
+ changeListeners.add(listener);
456
+ return () => {
457
+ changeListeners.delete(listener);
458
+ };
459
+ },
460
+ },
461
+ subscribe: (query, listener) => follow(collectionOf(query), undefined, async () => listener(await find(query))),
462
+ invitation: async () => ownInvitation(await ask("invitation", {})),
463
+ sync: {
464
+ current: () => sync,
465
+ subscribe: (listener) => {
466
+ syncListeners.add(listener);
467
+ listener(sync);
468
+ return () => {
469
+ syncListeners.delete(listener);
470
+ };
471
+ },
472
+ pause: async () => {
473
+ await ask("sync.pause", {});
474
+ },
475
+ resume: async () => {
476
+ await ask("sync.resume", {});
477
+ },
478
+ isConfirmed,
479
+ // A confirmation lowers `unconfirmed`, so it arrives as a sync
480
+ // status: wait for the next one, registered before asking, so none
481
+ // slips between the answer and the wait.
482
+ confirmed: async (change) => {
483
+ for (;;) {
484
+ const next = nextSync();
485
+ let held;
486
+ try {
487
+ held = await isConfirmed(change);
488
+ }
489
+ catch (error) {
490
+ next.cancel();
491
+ throw error;
492
+ }
493
+ if (held) {
494
+ next.cancel();
495
+ return;
496
+ }
497
+ await next.promise;
498
+ }
499
+ },
500
+ },
501
+ account: accountOf(ask),
502
+ durability: reports.durability,
503
+ view: reports.view,
504
+ close: async () => {
505
+ if (closed)
506
+ return;
507
+ try {
508
+ await ask("close", {});
509
+ }
510
+ finally {
511
+ closed = true;
512
+ subscriptions.clear();
513
+ changeListeners.clear();
514
+ syncListeners.clear();
515
+ spaceList.clear();
516
+ reports.clear();
517
+ for (const entry of statuses.values())
518
+ entry.listeners.clear();
519
+ for (const waiter of syncWaiters) {
520
+ waiter.reject(new NcError("closed", texts.DATABASE_CLOSED));
521
+ }
522
+ syncWaiters.clear();
523
+ core.terminate();
524
+ }
525
+ },
526
+ };
527
+ };
@@ -0,0 +1,29 @@
1
+ import type { Db } from "./db.ts";
2
+ type Id = string;
3
+ /** One fold the core reports: its space, the collections whose reads it may have changed, and the ids it touched per collection with their origin. */
4
+ export type Fold = {
5
+ space: string;
6
+ collections: string[];
7
+ changes?: {
8
+ collection: string;
9
+ ids: string[];
10
+ origin: "local" | "remote";
11
+ }[];
12
+ };
13
+ /** What `db.changes.subscribe` gives a listener. */
14
+ export type Change = Parameters<Parameters<Db["changes"]["subscribe"]>[0]>[0];
15
+ /** A read a subscription re-runs, and what it follows. */
16
+ export type Subscription = {
17
+ collection: string;
18
+ space: string | undefined;
19
+ run: () => Promise<void>;
20
+ running: boolean;
21
+ again: boolean;
22
+ };
23
+ /** An object as the core answers it, with its fields beside `$id`, `$space` and `$deleted`. */
24
+ export declare const flatten: ({ fields, ...rest }: {
25
+ fields: Record<string, unknown>;
26
+ }) => Record<string, unknown>;
27
+ /** 128 random bits from the browser's secure generator, as 32 hex digits (RFC 0002, "Object ids"). */
28
+ export declare const randomId: () => Id;
29
+ export {};
@@ -0,0 +1,10 @@
1
+ // Types and helpers of connect.ts, in a module of their own to keep
2
+ // connect.ts under the file size limit (NOC-315). Internal: the package's
3
+ // entry does not reach it.
4
+ /** An object as the core answers it, with its fields beside `$id`, `$space` and `$deleted`. */
5
+ export const flatten = ({ fields, ...rest }) => ({ ...rest, ...fields });
6
+ /** 128 random bits from the browser's secure generator, as 32 hex digits (RFC 0002, "Object ids"). */
7
+ export const randomId = () => {
8
+ const bytes = crypto.getRandomValues(new Uint8Array(16));
9
+ return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
10
+ };