@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.
- package/dist/account.d.ts +14 -0
- package/dist/account.js +34 -0
- package/dist/accountCalls.d.ts +34 -0
- package/dist/accountCalls.js +48 -0
- package/dist/adHoc.d.ts +49 -0
- package/dist/adHoc.js +52 -0
- package/dist/cbor.d.ts +8 -0
- package/dist/cbor.js +223 -0
- package/dist/connect.d.ts +14 -0
- package/dist/connect.js +527 -0
- package/dist/connectParts.d.ts +29 -0
- package/dist/connectParts.js +10 -0
- package/dist/db.d.ts +291 -0
- package/dist/db.js +17 -0
- package/dist/durability.d.ts +20 -0
- package/dist/durability.js +5 -0
- package/dist/durabilityReport.d.ts +29 -0
- package/dist/durabilityReport.js +128 -0
- package/dist/elements.d.ts +5 -0
- package/dist/elements.js +13 -0
- package/dist/error.d.ts +10 -0
- package/dist/error.js +23 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +6 -0
- package/dist/lockCheck.d.ts +4 -0
- package/dist/lockCheck.js +63 -0
- package/dist/members.d.ts +55 -0
- package/dist/members.js +38 -0
- package/dist/membership.d.ts +5 -0
- package/dist/membership.js +29 -0
- package/dist/nc.d.ts +153 -0
- package/dist/nc.js +211 -0
- package/dist/query.d.ts +21 -0
- package/dist/query.js +45 -0
- package/dist/reports.d.ts +8 -0
- package/dist/reports.js +50 -0
- package/dist/spaceList.d.ts +14 -0
- package/dist/spaceList.js +45 -0
- package/dist/status.d.ts +51 -0
- package/dist/status.js +5 -0
- package/dist/sync.d.ts +15 -0
- package/dist/sync.js +4 -0
- package/dist/tabs.d.ts +30 -0
- package/dist/tabs.js +444 -0
- package/dist/texts.d.ts +52 -0
- package/dist/texts.js +58 -0
- package/dist/waitNotice.d.ts +7 -0
- package/dist/waitNotice.js +32 -0
- package/dist/wasm/nocentraldb_wasm.d.ts +91 -0
- package/dist/wasm/nocentraldb_wasm.js +1058 -0
- package/dist/wasm/nocentraldb_wasm_bg.wasm +0 -0
- package/dist/wasm/nocentraldb_wasm_bg.wasm.d.ts +36 -0
- package/dist/worker.d.ts +1 -0
- package/dist/worker.js +142 -0
- package/dist/workerHost.d.ts +3 -0
- package/dist/workerHost.js +55 -0
- package/package.json +21 -4
- package/README.md +0 -3
package/dist/db.d.ts
ADDED
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
import type { RecoveryCode } from "./account.ts";
|
|
2
|
+
import type { Durability, ViewStatus } from "./durability.ts";
|
|
3
|
+
import type { Invitation, Members } from "./members.ts";
|
|
4
|
+
import type { Infer, model } from "./nc.ts";
|
|
5
|
+
import type { SpaceStatus } from "./status.ts";
|
|
6
|
+
import type { SyncStatus } from "./sync.ts";
|
|
7
|
+
/** A collection handle of the model, such as `model.tasks`. */
|
|
8
|
+
type AnyCollection = Parameters<typeof model>[0][string];
|
|
9
|
+
/** An object id or a space id: 16 bytes as 32 lowercase hex digits (RFC 0009, "Get by id"). */
|
|
10
|
+
type Id = string;
|
|
11
|
+
/** Elements to add to, or remove from, a set or many links: what `nc.add` and `nc.remove` give. */
|
|
12
|
+
interface Elements<E> {
|
|
13
|
+
readonly "nc.elements": E;
|
|
14
|
+
}
|
|
15
|
+
/** What a write takes for a field that reads as `T`: the value, `null` to clear it, or for a set or many links `nc.add` / `nc.remove`. */
|
|
16
|
+
type Write<T> = [T] extends [readonly (infer E)[] | undefined] ? Elements<E> : Exclude<T, undefined> | null;
|
|
17
|
+
/** The values a create or an update writes, by field name; `undefined` writes nothing. */
|
|
18
|
+
type Values<C> = C extends AnyCollection ? {
|
|
19
|
+
[K in keyof Infer<C>]?: Write<Infer<C>[K]> | undefined;
|
|
20
|
+
} : never;
|
|
21
|
+
/** An object as `space.get` reads it (RFC 0009, "Get by id"). */
|
|
22
|
+
type Read<C> = C extends AnyCollection ? Infer<C> & {
|
|
23
|
+
readonly $id: Id;
|
|
24
|
+
readonly $space: Id;
|
|
25
|
+
readonly $deleted: boolean;
|
|
26
|
+
} : never;
|
|
27
|
+
/** Where the page after another starts. It holds the page's last position on this device and prints as `[redacted]`; another database refuses it with `cursorOfAnotherModel` (RFC 0009, "Queries and indexes"). */
|
|
28
|
+
interface Cursor {
|
|
29
|
+
toString(): string;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* A query of a declared index, whose objects are `T`: the handle
|
|
33
|
+
* `model.<collection>.indexes.<index>`, with `.equal` fixing its equality
|
|
34
|
+
* prefix (`E`, its values in index order), `.take` the page size (50 by
|
|
35
|
+
* default, at most 1000) and `.after` where the page starts (RFC 0009,
|
|
36
|
+
* "Queries and indexes"). Each returns a new query.
|
|
37
|
+
*/
|
|
38
|
+
export interface Query<T, E extends readonly unknown[] = readonly []> {
|
|
39
|
+
/** Fixes the index's leading fields, as many as its `equal` declares. */
|
|
40
|
+
equal(...values: E): Query<T>;
|
|
41
|
+
/** Sets the page size: 50 by default, at most 1000. */
|
|
42
|
+
take(n: number): Query<T, E>;
|
|
43
|
+
/** Starts after the cursor of an earlier page. */
|
|
44
|
+
after(cursor: Cursor): Query<T, E>;
|
|
45
|
+
/** Brands the query with its objects' type. */
|
|
46
|
+
readonly "nc.query"?: T;
|
|
47
|
+
}
|
|
48
|
+
/** One page of a query: its objects in index order, the cursor after the last one when more may follow, and whether more do. */
|
|
49
|
+
export interface Page<T> {
|
|
50
|
+
readonly items: T[];
|
|
51
|
+
readonly cursor: Cursor | undefined;
|
|
52
|
+
readonly hasMore: boolean;
|
|
53
|
+
}
|
|
54
|
+
/** Stops a subscription. */
|
|
55
|
+
type Stop = () => void;
|
|
56
|
+
/** What one fold touched in one collection (RFC 0009, "Subscribe"): ids, never values, and whether the change was this member's own write. */
|
|
57
|
+
interface Change {
|
|
58
|
+
readonly space: Id;
|
|
59
|
+
readonly collection: string;
|
|
60
|
+
readonly ids: readonly Id[];
|
|
61
|
+
readonly origin: "local" | "remote";
|
|
62
|
+
}
|
|
63
|
+
/** What a write answers: its change id and the ids of the objects it created, in order. */
|
|
64
|
+
interface Written {
|
|
65
|
+
readonly change: string;
|
|
66
|
+
readonly ids: readonly Id[];
|
|
67
|
+
}
|
|
68
|
+
/** A transaction: the writes one `space.write` records and turns into one change (RFC 0009, "One write, one change"). */
|
|
69
|
+
export interface Tx {
|
|
70
|
+
/** Records the creation of an object and returns its new id, drawn on the device. */
|
|
71
|
+
create<C extends AnyCollection>(collection: C, values: Values<C>): Id;
|
|
72
|
+
/** Records a write of `values` to the object `id`. */
|
|
73
|
+
update<C extends AnyCollection>(collection: C, id: Id, values: Values<C>): void;
|
|
74
|
+
/** Records the deletion of the object `id`. */
|
|
75
|
+
delete(collection: AnyCollection, id: Id): void;
|
|
76
|
+
/** Records the restore of the deleted object `id`. */
|
|
77
|
+
restore(collection: AnyCollection, id: Id): void;
|
|
78
|
+
}
|
|
79
|
+
/** A space: its objects are read and written through it (RFC 0009, "Spaces"). */
|
|
80
|
+
export interface Space {
|
|
81
|
+
/** The space id, 32 lowercase hex digits. */
|
|
82
|
+
readonly id: Id;
|
|
83
|
+
/** The members of this space: add, list, re-role and remove (RFC 0009, "Invitations and members"). */
|
|
84
|
+
readonly members: Members;
|
|
85
|
+
/** In an ad-hoc space this database created: the space and id of the object `copy` was copied from, or `undefined` on any other database; the mapping never syncs (RFC 0009, "Sub-agents and ad-hoc spaces"; Carsten, 2026-11-16, NOC-351). */
|
|
86
|
+
sourceOf(copy: Id): Promise<{
|
|
87
|
+
readonly space: Id;
|
|
88
|
+
readonly id: Id;
|
|
89
|
+
} | undefined>;
|
|
90
|
+
/** In an ad-hoc space this database created: the copy of the object `source` of `sourceSpace`, or `undefined` when this database copied no such object into it. */
|
|
91
|
+
copyOf(sourceSpace: Id, source: Id): Promise<Id | undefined>;
|
|
92
|
+
/** Leaves the space: this member writes its own removal and keeps its copy; the last admin is refused with `lastAdmin` (RFC 0009, "Spaces"). */
|
|
93
|
+
leave(): Promise<{
|
|
94
|
+
readonly notice: import("./members.ts").Notice;
|
|
95
|
+
}>;
|
|
96
|
+
/** The audit of this space's erasures; every member may read it, a reader too (RFC 0009, "Erasures"). */
|
|
97
|
+
readonly erasures: {
|
|
98
|
+
/** Each erasure, with who deleted the person key, who only saw it and who never answered. */
|
|
99
|
+
list(): Promise<ErasureEntry[]>;
|
|
100
|
+
};
|
|
101
|
+
/** What this space holds that a read does not show, as a report (RFC 0009, "Sync and status"). */
|
|
102
|
+
readonly status: {
|
|
103
|
+
/** The report as it is now. */
|
|
104
|
+
current(): SpaceStatus;
|
|
105
|
+
/** Calls `listener` with the report at once, and again whenever it changes. */
|
|
106
|
+
subscribe(listener: (status: SpaceStatus) => void): Stop;
|
|
107
|
+
};
|
|
108
|
+
/** Records the writes of `record` and turns them into one change of this space. */
|
|
109
|
+
write(record: (tx: Tx) => void): Promise<Written>;
|
|
110
|
+
/** A write with one create. */
|
|
111
|
+
create<C extends AnyCollection>(collection: C, values: Values<C>): Promise<Written>;
|
|
112
|
+
/** A write with one update. */
|
|
113
|
+
update<C extends AnyCollection>(collection: C, id: Id, values: Values<C>): Promise<Written>;
|
|
114
|
+
/** A write with one delete. */
|
|
115
|
+
delete(collection: AnyCollection, id: Id): Promise<Written>;
|
|
116
|
+
/** A write with one restore. */
|
|
117
|
+
restore(collection: AnyCollection, id: Id): Promise<Written>;
|
|
118
|
+
/** The object `id` of `collection`, deleted or not, or `undefined` when the copy holds none. */
|
|
119
|
+
get<C extends AnyCollection>(collection: C, id: Id): Promise<Read<C> | undefined>;
|
|
120
|
+
/** A page of a query of an index with `scope: "space"`, in this space. */
|
|
121
|
+
find<T>(query: Query<T, readonly unknown[]>): Promise<Page<T>>;
|
|
122
|
+
/** Follows a query in this space: its page at once, and again after every fold in this space that touched its collection. */
|
|
123
|
+
subscribe<T>(query: Query<T, readonly unknown[]>, listener: (page: Page<T>) => void): Stop;
|
|
124
|
+
/** Follows the object `id` of `collection`: as `get` reads it, at once and after every fold in this space that touched the collection. */
|
|
125
|
+
subscribe<C extends AnyCollection>(collection: C, id: Id, listener: (object: Read<C> | undefined) => void): Stop;
|
|
126
|
+
}
|
|
127
|
+
/** One erasure of a space, as `space.erasures.list()` gives it (RFC 0009, "Erasures"; Carsten, 2026-11-12, NOC-246). */
|
|
128
|
+
interface ErasureEntry {
|
|
129
|
+
/** The change id of the erasure's shred entry. */
|
|
130
|
+
readonly shred: string;
|
|
131
|
+
/** `"final"` for a shred, or a provisional one a decision finalized; `"provisional"` while it waits; `"takenBack"` when its account took it back. */
|
|
132
|
+
readonly state: "final" | "provisional" | "takenBack";
|
|
133
|
+
/** The member that performed it, and its account's fingerprint. */
|
|
134
|
+
readonly performer: {
|
|
135
|
+
readonly id: string;
|
|
136
|
+
readonly account: string;
|
|
137
|
+
};
|
|
138
|
+
/** The fingerprint of the account that signed it off. */
|
|
139
|
+
readonly signOff: string;
|
|
140
|
+
/** Every member that could have held the person key. */
|
|
141
|
+
readonly members: readonly {
|
|
142
|
+
readonly id: string;
|
|
143
|
+
readonly account: string;
|
|
144
|
+
/** Whether it is still a member. */
|
|
145
|
+
readonly current: boolean;
|
|
146
|
+
/** Whether it confirmed it deleted the key, only saw the shred, or never answered. */
|
|
147
|
+
readonly acknowledged: "deleted" | "seen" | "missing";
|
|
148
|
+
}[];
|
|
149
|
+
}
|
|
150
|
+
/** A space as `db.spaces.list` gives it. */
|
|
151
|
+
interface SpaceEntry {
|
|
152
|
+
readonly id: Id;
|
|
153
|
+
readonly role: string | null;
|
|
154
|
+
/** Whether the space is of this database's model, or of another (RFC 0009, "Spaces of another model"). */
|
|
155
|
+
readonly model: "ours" | "another";
|
|
156
|
+
}
|
|
157
|
+
/** This member's database (RFC 0009, "Open and close"). */
|
|
158
|
+
export interface Db {
|
|
159
|
+
readonly spaces: {
|
|
160
|
+
/** Creates a space, offline if need be; this member is its first admin. */
|
|
161
|
+
create(): Promise<Space>;
|
|
162
|
+
/** The space `id`; `notFound` when the copy holds none. */
|
|
163
|
+
get(id: Id): Promise<Space>;
|
|
164
|
+
/** Every space of this member, with its role. */
|
|
165
|
+
list(): Promise<SpaceEntry[]>;
|
|
166
|
+
/** Calls `listener` with the list, then with each new list when a space is added, left or removed, or its role changes (RFC 0009, "Spaces"). */
|
|
167
|
+
subscribe(listener: (spaces: SpaceEntry[]) => void): Stop;
|
|
168
|
+
/**
|
|
169
|
+
* Creates an ad-hoc space for a sub-agent: a space with a fresh key, which syncs as any other, holding a copy of each object of `copy` as a new object with a fresh id (RFC 0009, "Sub-agents and ad-hoc spaces"; Carsten, 2026-11-16, NOC-351).
|
|
170
|
+
* `copy` takes objects this database read, as `space.get`, `find` and `subscribe` give them; any other object, a spread of one too, is refused with `invalidValue`.
|
|
171
|
+
* A copied link points to the copy of its target, or is cleared; personal and plugin fields are not copied. `personal` and `local` are refused with `notAllowed` for now.
|
|
172
|
+
* Gives the space, its `adHocSpaceCreated` notice, each source with its copy in the order of `copy`, and how many links were cleared and plugin fields not copied.
|
|
173
|
+
*/
|
|
174
|
+
createAdHoc(options: {
|
|
175
|
+
copy: readonly object[];
|
|
176
|
+
personal?: boolean;
|
|
177
|
+
local?: boolean;
|
|
178
|
+
}): Promise<{
|
|
179
|
+
readonly space: Space;
|
|
180
|
+
readonly notice: import("./members.ts").Notice;
|
|
181
|
+
readonly copies: readonly {
|
|
182
|
+
readonly source: Id;
|
|
183
|
+
readonly copy: Id;
|
|
184
|
+
}[];
|
|
185
|
+
readonly clearedLinks: number;
|
|
186
|
+
readonly pluginFieldsNotCopied: number;
|
|
187
|
+
}>;
|
|
188
|
+
};
|
|
189
|
+
/** A page of a query of an index across every space of the member. */
|
|
190
|
+
find<T>(query: Query<T, readonly unknown[]>): Promise<Page<T>>;
|
|
191
|
+
/** Follows a query: its page at once, and again after every fold that touched its collection, whole pages, never diffs (RFC 0009, "Subscribe"). */
|
|
192
|
+
subscribe<T>(query: Query<T, readonly unknown[]>, listener: (page: Page<T>) => void): Stop;
|
|
193
|
+
/** The change event: after each fold, its space, collection and the ids it touched, and its origin (RFC 0009, "Subscribe"). */
|
|
194
|
+
readonly changes: {
|
|
195
|
+
/** Calls `listener` after each fold, once per collection it touched. */
|
|
196
|
+
subscribe(listener: (change: Change) => void): Stop;
|
|
197
|
+
};
|
|
198
|
+
/** This member's invitation, with its account's fingerprint, for an admin to add it to a space (RFC 0009, "Invitations and members"). */
|
|
199
|
+
invitation(): Promise<Invitation>;
|
|
200
|
+
/** The relay connection, as a report (RFC 0009, "Sync and status"). */
|
|
201
|
+
readonly sync: {
|
|
202
|
+
/** The report as it is now. */
|
|
203
|
+
current(): SyncStatus;
|
|
204
|
+
/** Calls `listener` with the report at once, and again whenever it changes. */
|
|
205
|
+
subscribe(listener: (status: SyncStatus) => void): Stop;
|
|
206
|
+
/** Stops syncing, for an app that wants to stay offline; the connection reads `"paused"` until `resume`. */
|
|
207
|
+
pause(): Promise<void>;
|
|
208
|
+
/** Syncs again after `pause`. */
|
|
209
|
+
resume(): Promise<void>;
|
|
210
|
+
/** Whether the relay holds the change `change`, as `write` answered its id. */
|
|
211
|
+
isConfirmed(change: string): Promise<boolean>;
|
|
212
|
+
/** Resolves when the relay holds the change `change`. It may never resolve: the relay can refuse the change, or never be reached. */
|
|
213
|
+
confirmed(change: string): Promise<void>;
|
|
214
|
+
};
|
|
215
|
+
/** What this copy would lose if the browser deleted it now, as a report (RFC 0006, "What the SDK reports"). */
|
|
216
|
+
readonly durability: {
|
|
217
|
+
/** The report as it is now. */
|
|
218
|
+
current(): Durability;
|
|
219
|
+
/** Calls `listener` with the report at once, and again whenever it changes. */
|
|
220
|
+
subscribe(listener: (durability: Durability) => void): Stop;
|
|
221
|
+
/** Asks the browser for persistent storage and answers its answer; the new storage is also reported through `subscribe`. */
|
|
222
|
+
requestPersistent(): Promise<boolean>;
|
|
223
|
+
};
|
|
224
|
+
/** The view's report: whether a rebuild runs, and how far it is (RFC 0009, "Sync and status"). */
|
|
225
|
+
readonly view: {
|
|
226
|
+
/** The report as it is now. */
|
|
227
|
+
current(): ViewStatus;
|
|
228
|
+
/** Calls `listener` with the report at once, and again whenever it changes. */
|
|
229
|
+
subscribe(listener: (view: ViewStatus) => void): Stop;
|
|
230
|
+
};
|
|
231
|
+
/** This member's account: its recovery code, and whether this open recovered it (RFC 0009, "Accounts and devices"). */
|
|
232
|
+
readonly account: {
|
|
233
|
+
/** The recovery code while the person has not confirmed they stored it, else `null`; shown again on every open until then. */
|
|
234
|
+
recoveryCode(): Promise<RecoveryCode | null>;
|
|
235
|
+
/** `accountRecovered` on the open that recovered the account with `recover`, else `null`. */
|
|
236
|
+
recovered(): Promise<import("./members.ts").Notice | null>;
|
|
237
|
+
/** On a device of the account, after a person confirmed the new device: the answer to show it, the spaces the new device was added to, each with its notice, and the spaces whose admins the app asks (RFC 0010). `kind` is `"device"` or `"agent"`. */
|
|
238
|
+
pair(request: {
|
|
239
|
+
kind: "device" | "agent";
|
|
240
|
+
invitation: Invitation;
|
|
241
|
+
}): Promise<{
|
|
242
|
+
readonly answer: import("./account.ts").PairingAnswer;
|
|
243
|
+
readonly added: readonly {
|
|
244
|
+
readonly space: Id;
|
|
245
|
+
readonly notice: import("./members.ts").Notice;
|
|
246
|
+
}[];
|
|
247
|
+
readonly askAdmins: readonly Id[];
|
|
248
|
+
}>;
|
|
249
|
+
/** On the new database, opened with `pairing: "request"`: takes the answer and makes it a device or an agent of the account; gives the notices of the pairing. */
|
|
250
|
+
completePairing(answer: import("./account.ts").PairingAnswer): Promise<{
|
|
251
|
+
readonly notices: readonly import("./members.ts").Notice[];
|
|
252
|
+
}>;
|
|
253
|
+
/** On a device of the account, with the recovery code the person typed: removes a lost device or an agent of the account from every space this device administers, and renews the account key so that the lost one's is no longer accepted (RFC 0010, "Losing a device"). Gives the spaces it was removed from, each with its notice, the spaces whose admins the app asks, and `accountKeyRenewed`. The words are never logged. */
|
|
254
|
+
removeMember(member: string, options: {
|
|
255
|
+
recover: string;
|
|
256
|
+
}): Promise<{
|
|
257
|
+
readonly removed: readonly {
|
|
258
|
+
readonly space: Id;
|
|
259
|
+
readonly notice: import("./members.ts").Notice;
|
|
260
|
+
}[];
|
|
261
|
+
readonly askAdmins: readonly Id[];
|
|
262
|
+
readonly notice: import("./members.ts").Notice;
|
|
263
|
+
}>;
|
|
264
|
+
};
|
|
265
|
+
/** Closes the database; every later call fails with `closed`, and every subscription stops. */
|
|
266
|
+
close(): Promise<void>;
|
|
267
|
+
}
|
|
268
|
+
/** The options of `nc.open` in a browser (RFC 0009, "Open and close"). */
|
|
269
|
+
interface OpenOptions {
|
|
270
|
+
/** The TypeScript model, `nc.model(...)`: types and handles. */
|
|
271
|
+
model: Record<string, any>;
|
|
272
|
+
/** `model.lock.json`: the rules the core folds by. */
|
|
273
|
+
lock: unknown;
|
|
274
|
+
/** The relay's URL; without it, the database stays local. */
|
|
275
|
+
relay?: string;
|
|
276
|
+
/** Which database: 1 to 64 of a–z, 0–9, `-` and `_`; `"default"` when left out. */
|
|
277
|
+
name?: string;
|
|
278
|
+
/** `"on-open"`, the default: ask the browser for persistent storage on open, without waiting; `"on-request"`: only when the app calls `db.durability.requestPersistent()` (RFC 0006). */
|
|
279
|
+
persistentStorage?: "on-open" | "on-request";
|
|
280
|
+
/** `"request"`: open a new database to be paired to an account; its invitation carries no certificate yet (RFC 0010). */
|
|
281
|
+
pairing?: "request";
|
|
282
|
+
/** The twelve words of a recovery code, as the person typed them: recovers the account on a new database (RFC 0010). Never logged. */
|
|
283
|
+
recover?: string;
|
|
284
|
+
}
|
|
285
|
+
/** Opens this member's database in the browser. */
|
|
286
|
+
export declare const open: (options: OpenOptions) => Promise<Db>;
|
|
287
|
+
/** Adds `elements` to a set or to many links (RFC 0009, "Field operations per field type"). */
|
|
288
|
+
export declare const add: <E>(...elements: E[]) => Elements<E>;
|
|
289
|
+
/** Removes `elements` from a set or from many links: the additions of each that the copy holds. */
|
|
290
|
+
export declare const remove: <E>(...elements: E[]) => Elements<E>;
|
|
291
|
+
export {};
|
package/dist/db.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
// The database an app opens in the browser (RFC 0009, "Open and close",
|
|
2
|
+
// "Write", "Get by id", "Queries and indexes", "Subscribe", "Spaces";
|
|
3
|
+
// NOC-176 slices 1 and 2). The SDK runs the core,
|
|
4
|
+
// the Rust SDK compiled to WebAssembly, in a dedicated worker it starts
|
|
5
|
+
// itself, and speaks to it in the bridge's messages
|
|
6
|
+
// (crates/nocentraldb/src/bridge/mod.rs): canonical CBOR, one request and
|
|
7
|
+
// one answer at a time. `@nocentraldb/sdk` ships the worker script and the
|
|
8
|
+
// wasm module and finds them with `new URL(..., import.meta.url)` (Carsten,
|
|
9
|
+
// 2026-11-12, NOC-274).
|
|
10
|
+
import { connectWorker } from "./connect.js";
|
|
11
|
+
import { SetElements } from "./elements.js";
|
|
12
|
+
/** Opens this member's database in the browser. */
|
|
13
|
+
export const open = (options) => connectWorker(options);
|
|
14
|
+
/** Adds `elements` to a set or to many links (RFC 0009, "Field operations per field type"). */
|
|
15
|
+
export const add = (...elements) => new SetElements(true, elements);
|
|
16
|
+
/** Removes `elements` from a set or from many links: the additions of each that the copy holds. */
|
|
17
|
+
export const remove = (...elements) => new SetElements(false, elements);
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/** What this copy would lose if the browser deleted it now (RFC 0006, "What the SDK reports"). */
|
|
2
|
+
export interface Durability {
|
|
3
|
+
/** `"persistent"`: native, or the browser keeps the copy; `"best-effort"`: the browser may delete it; `"temporary"`: in memory, as Node.js's `inMemory` opens it; a browser never reports it. */
|
|
4
|
+
readonly storage: "persistent" | "best-effort" | "temporary";
|
|
5
|
+
/** This member's changes the relay has not confirmed: they exist only on this device. */
|
|
6
|
+
readonly unconfirmed: number;
|
|
7
|
+
/** When the oldest of them was written, in milliseconds since the epoch, or `null`. */
|
|
8
|
+
readonly oldestUnconfirmedAt: number | null;
|
|
9
|
+
/** Whether some changes are unconfirmed while the copy is not persistent. */
|
|
10
|
+
readonly atRisk: boolean;
|
|
11
|
+
/** Whether this browser tab waits for the database's storage, which another tab of the app still holds, as a frozen tab in Safari does: this tab's calls, writes included, wait until that tab runs again, and none fails. Always `false` outside a browser (NOC-355). */
|
|
12
|
+
readonly waitingForTab: boolean;
|
|
13
|
+
}
|
|
14
|
+
/** The view's report: whether a rebuild runs, and how far it is, in frames of the log. */
|
|
15
|
+
export interface ViewStatus {
|
|
16
|
+
readonly rebuild: {
|
|
17
|
+
readonly folded: number;
|
|
18
|
+
readonly total: number;
|
|
19
|
+
} | null;
|
|
20
|
+
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
// The types of the durability of the copy and of the view's report
|
|
2
|
+
// (NOC-315, slice 3; RFC 0006, "What the SDK reports"; RFC 0009, "Sync and
|
|
3
|
+
// status"; the shapes the owner decided on NOC-317, Carsten, 2026-11-14).
|
|
4
|
+
// What follows them is in durabilityReport.ts.
|
|
5
|
+
export {};
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { Cbor } from "./cbor.ts";
|
|
2
|
+
import type { Durability, ViewStatus } from "./durability.ts";
|
|
3
|
+
type Ask = (call: string, args: Record<string, unknown>) => Promise<Cbor>;
|
|
4
|
+
/** The durability and view reports of one database. */
|
|
5
|
+
export declare const reportsOf: (ask: Ask, opened: {
|
|
6
|
+
durability?: unknown;
|
|
7
|
+
view?: unknown;
|
|
8
|
+
}, persistentStorage?: "on-open" | "on-request") => {
|
|
9
|
+
durability: {
|
|
10
|
+
current: () => Durability;
|
|
11
|
+
subscribe: (listener: (durability: Durability) => void) => () => void;
|
|
12
|
+
requestPersistent: () => Promise<boolean>;
|
|
13
|
+
};
|
|
14
|
+
view: {
|
|
15
|
+
current: () => ViewStatus;
|
|
16
|
+
subscribe: (listener: (view: ViewStatus) => void) => () => void;
|
|
17
|
+
};
|
|
18
|
+
/** A `durability` event of the core. */
|
|
19
|
+
durabilityChanged: (raw: unknown) => void;
|
|
20
|
+
/** A `waitingForTab` event of this tab's worker (NOC-355, worker.ts). */
|
|
21
|
+
waitingChanged: (waitingForTab: boolean) => void;
|
|
22
|
+
/** A `view` event of the core. */
|
|
23
|
+
viewChanged: (raw: unknown) => void;
|
|
24
|
+
/** Another tab took the database over (NOC-177): read both again. */
|
|
25
|
+
reopened(): void;
|
|
26
|
+
/** The database closed. */
|
|
27
|
+
clear(): void;
|
|
28
|
+
};
|
|
29
|
+
export {};
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
// The durability of the copy and the view's report as reports (NOC-315,
|
|
2
|
+
// slice 3; RFC 0006, "What the SDK reports"). `open` answers both, the
|
|
3
|
+
// core's `durability` and `view` events keep them current, and the page
|
|
4
|
+
// asks the browser for persistent storage: a worker can read `persisted()`
|
|
5
|
+
// but not call `persist()`, so the page asks and the core reads again.
|
|
6
|
+
// Internal: the package's entry does not reach it.
|
|
7
|
+
import { notify } from "./reports.js";
|
|
8
|
+
/** A durability the core sent; the core knows nothing of tabs, so whether this tab waits for another is the page's (NOC-355). */
|
|
9
|
+
const durabilityOf = (raw, waitingForTab = false) => {
|
|
10
|
+
const given = (raw ?? {});
|
|
11
|
+
return {
|
|
12
|
+
storage: (given.storage ?? "temporary"),
|
|
13
|
+
unconfirmed: Number(given.unconfirmed ?? 0),
|
|
14
|
+
oldestUnconfirmedAt: given.oldestUnconfirmedAt === null ||
|
|
15
|
+
given.oldestUnconfirmedAt === undefined
|
|
16
|
+
? null
|
|
17
|
+
: Number(given.oldestUnconfirmedAt),
|
|
18
|
+
atRisk: given.atRisk === true,
|
|
19
|
+
waitingForTab,
|
|
20
|
+
};
|
|
21
|
+
};
|
|
22
|
+
/** A view's report the core sent. */
|
|
23
|
+
const viewOf = (raw) => {
|
|
24
|
+
const rebuild = (raw ?? {}).rebuild;
|
|
25
|
+
return {
|
|
26
|
+
rebuild: rebuild === null || rebuild === undefined
|
|
27
|
+
? null
|
|
28
|
+
: { folded: Number(rebuild.folded), total: Number(rebuild.total) },
|
|
29
|
+
};
|
|
30
|
+
};
|
|
31
|
+
/** The browser's `navigator.storage.persist()`, where it has one. */
|
|
32
|
+
const persist = () => {
|
|
33
|
+
const storage = globalThis.navigator?.storage;
|
|
34
|
+
return typeof storage?.persist === "function"
|
|
35
|
+
? () => storage.persist.call(storage)
|
|
36
|
+
: undefined;
|
|
37
|
+
};
|
|
38
|
+
/** The durability and view reports of one database. */
|
|
39
|
+
export const reportsOf = (ask, opened, persistentStorage = "on-open") => {
|
|
40
|
+
let durability = durabilityOf(opened.durability);
|
|
41
|
+
let view = viewOf(opened.view);
|
|
42
|
+
const durabilityListeners = new Set();
|
|
43
|
+
const viewListeners = new Set();
|
|
44
|
+
const durabilityChanged = (raw) => {
|
|
45
|
+
durability = durabilityOf(raw, durability.waitingForTab);
|
|
46
|
+
notify(durabilityListeners, durability);
|
|
47
|
+
};
|
|
48
|
+
const waitingChanged = (waitingForTab) => {
|
|
49
|
+
if (waitingForTab === durability.waitingForTab)
|
|
50
|
+
return;
|
|
51
|
+
durability = { ...durability, waitingForTab };
|
|
52
|
+
notify(durabilityListeners, durability);
|
|
53
|
+
};
|
|
54
|
+
const viewChanged = (raw) => {
|
|
55
|
+
view = viewOf(raw);
|
|
56
|
+
notify(viewListeners, view);
|
|
57
|
+
};
|
|
58
|
+
/** Asks the core to read again whether the browser keeps the copy. */
|
|
59
|
+
const refresh = () => ask("durability", {}).then(durabilityChanged, () => {
|
|
60
|
+
// A closed database answers nothing more.
|
|
61
|
+
});
|
|
62
|
+
const requestPersistent = async () => {
|
|
63
|
+
const asking = persist();
|
|
64
|
+
let answer = false;
|
|
65
|
+
if (asking !== undefined) {
|
|
66
|
+
try {
|
|
67
|
+
answer = (await asking()) === true;
|
|
68
|
+
}
|
|
69
|
+
catch {
|
|
70
|
+
answer = false;
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
await refresh();
|
|
74
|
+
return answer;
|
|
75
|
+
};
|
|
76
|
+
// RFC 0006: on open, without waiting; `subscribe` reports the answer.
|
|
77
|
+
// Where the browser has no `persist()`, there is nothing to ask.
|
|
78
|
+
if (persistentStorage === "on-open" && persist() !== undefined) {
|
|
79
|
+
void requestPersistent();
|
|
80
|
+
}
|
|
81
|
+
// RFC 0006: a user can grant or revoke it in the browser's settings.
|
|
82
|
+
const page = globalThis.document;
|
|
83
|
+
const visible = () => {
|
|
84
|
+
if (page?.visibilityState === "visible")
|
|
85
|
+
void refresh();
|
|
86
|
+
};
|
|
87
|
+
page?.addEventListener?.("visibilitychange", visible);
|
|
88
|
+
return {
|
|
89
|
+
durability: {
|
|
90
|
+
current: () => durability,
|
|
91
|
+
subscribe: (listener) => {
|
|
92
|
+
durabilityListeners.add(listener);
|
|
93
|
+
notify(new Set([listener]), durability);
|
|
94
|
+
return () => {
|
|
95
|
+
durabilityListeners.delete(listener);
|
|
96
|
+
};
|
|
97
|
+
},
|
|
98
|
+
requestPersistent,
|
|
99
|
+
},
|
|
100
|
+
view: {
|
|
101
|
+
current: () => view,
|
|
102
|
+
subscribe: (listener) => {
|
|
103
|
+
viewListeners.add(listener);
|
|
104
|
+
notify(new Set([listener]), view);
|
|
105
|
+
return () => {
|
|
106
|
+
viewListeners.delete(listener);
|
|
107
|
+
};
|
|
108
|
+
},
|
|
109
|
+
},
|
|
110
|
+
/** A `durability` event of the core. */
|
|
111
|
+
durabilityChanged,
|
|
112
|
+
/** A `waitingForTab` event of this tab's worker (NOC-355, worker.ts). */
|
|
113
|
+
waitingChanged,
|
|
114
|
+
/** A `view` event of the core. */
|
|
115
|
+
viewChanged,
|
|
116
|
+
/** Another tab took the database over (NOC-177): read both again. */
|
|
117
|
+
reopened() {
|
|
118
|
+
void refresh();
|
|
119
|
+
void ask("view", {}).then(viewChanged, () => { });
|
|
120
|
+
},
|
|
121
|
+
/** The database closed. */
|
|
122
|
+
clear() {
|
|
123
|
+
durabilityListeners.clear();
|
|
124
|
+
viewListeners.clear();
|
|
125
|
+
page?.removeEventListener?.("visibilitychange", visible);
|
|
126
|
+
},
|
|
127
|
+
};
|
|
128
|
+
};
|
package/dist/elements.js
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// What `nc.add` and `nc.remove` give: elements to add to, or remove from,
|
|
2
|
+
// a set or many links (RFC 0009, "Field operations per field type").
|
|
3
|
+
// Internal: the app sees only the type `Elements`. Plain fields, not
|
|
4
|
+
// parameter properties: `ncdb model build` runs the SDK's source under
|
|
5
|
+
// Node's type stripping, which supports only erasable syntax.
|
|
6
|
+
export class SetElements {
|
|
7
|
+
add;
|
|
8
|
+
elements;
|
|
9
|
+
constructor(add, elements) {
|
|
10
|
+
this.add = add;
|
|
11
|
+
this.elements = elements;
|
|
12
|
+
}
|
|
13
|
+
}
|
package/dist/error.d.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/** The one error class the SDK throws; match on `code`. */
|
|
2
|
+
export declare class NcError extends Error {
|
|
3
|
+
/** RFC 0009's error code, such as `notFound` or `invalidValue`. */
|
|
4
|
+
readonly code: string;
|
|
5
|
+
/** The ids the error concerns, each as text. */
|
|
6
|
+
readonly ids: readonly string[];
|
|
7
|
+
/** For `unknownAccount`: the account's fingerprint, twelve blocks. */
|
|
8
|
+
readonly fingerprint?: string;
|
|
9
|
+
constructor(code: string, message: string, ids?: readonly string[], fingerprint?: string);
|
|
10
|
+
}
|
package/dist/error.js
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// `nc.Error`, the one error class of the SDK (RFC 0009, "Errors"; Carsten,
|
|
2
|
+
// 2026-11-12, NOC-274): a string `code` that maps one to one to the Rust
|
|
3
|
+
// SDK's `ErrorCode`, the ids the error concerns as text, and, for
|
|
4
|
+
// `unknownAccount`, the account's fingerprint as a plain string of twelve
|
|
5
|
+
// blocks. An error never carries content, a key or a personal field (RFC
|
|
6
|
+
// 0003, "Keys never reach logs, errors or telemetry").
|
|
7
|
+
/** The one error class the SDK throws; match on `code`. */
|
|
8
|
+
export class NcError extends Error {
|
|
9
|
+
/** RFC 0009's error code, such as `notFound` or `invalidValue`. */
|
|
10
|
+
code;
|
|
11
|
+
/** The ids the error concerns, each as text. */
|
|
12
|
+
ids;
|
|
13
|
+
/** For `unknownAccount`: the account's fingerprint, twelve blocks. */
|
|
14
|
+
fingerprint;
|
|
15
|
+
constructor(code, message, ids = [], fingerprint) {
|
|
16
|
+
super(message);
|
|
17
|
+
this.name = "nc.Error";
|
|
18
|
+
this.code = code;
|
|
19
|
+
this.ids = [...ids];
|
|
20
|
+
if (fingerprint !== undefined)
|
|
21
|
+
this.fingerprint = fingerprint;
|
|
22
|
+
}
|
|
23
|
+
}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/** Returns the package name; exists so the gates have real code to check. */
|
|
2
|
+
export declare function name(): string;
|
|
3
|
+
/** The account's recovery code (RFC 0009, "Accounts and devices"; NOC-316). */
|
|
4
|
+
export type { RecoveryCode } from "./account.ts";
|
|
5
|
+
/** The TypeScript types of a database, a space and a transaction (RFC 0009, "Public names"; Carsten, 2026-11-12, NOC-274). */
|
|
6
|
+
/** The TypeScript types of a query and its page (RFC 0009, "Public names"; NOC-176 slice 2). */
|
|
7
|
+
export type { Db, Page, Query, Space, Tx } from "./db.ts";
|
|
8
|
+
/** The durability of the copy (RFC 0006, "What the SDK reports"; RFC 0009, "Public names"; NOC-315). */
|
|
9
|
+
export type { Durability } from "./durability.ts";
|
|
10
|
+
/** An invitation, and the notice a membership call returns (RFC 0009, "Invitations and members"; NOC-176 slice 4b). */
|
|
11
|
+
export type { Invitation, Notice } from "./members.ts";
|
|
12
|
+
/** The schema functions of RFC 0005: `nc.model`, `nc.collection`, the field types and `nc.index`, and the types `nc.Infer` and `nc.Unknown`. */
|
|
13
|
+
export * as nc from "./nc.ts";
|
|
14
|
+
/** A space's status (RFC 0009, "Sync and status"; NOC-176 slice 4). */
|
|
15
|
+
export type { SpaceStatus } from "./status.ts";
|
|
16
|
+
/** The sync report (RFC 0009, "Sync and status"; NOC-176 slice 4). */
|
|
17
|
+
export type { SyncStatus } from "./sync.ts";
|
|
18
|
+
/** A pairing answer, which a device of the account hands a new one (RFC 0009, "Accounts and devices"; NOC-316). Its own line, so that the export of `RecoveryCode` above stays as it was. */
|
|
19
|
+
export type PairingAnswer = import("./account.ts").PairingAnswer;
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/** Returns the package name; exists so the gates have real code to check. */
|
|
2
|
+
export function name() {
|
|
3
|
+
return "@nocentraldb/sdk";
|
|
4
|
+
}
|
|
5
|
+
/** The schema functions of RFC 0005: `nc.model`, `nc.collection`, the field types and `nc.index`, and the types `nc.Infer` and `nc.Unknown`. */
|
|
6
|
+
export * as nc from "./nc.js";
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
type Json = unknown;
|
|
2
|
+
/** Why `lock` is out of date for `model`, or `undefined` when every collection, field and index the model names is in the lock as the model names it. */
|
|
3
|
+
export declare const lockOutOfDate: (model: object, lock: Json) => string | undefined;
|
|
4
|
+
export {};
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
// nc.open checks the model against its lock (NOC-323; RFC 0009, "Open and
|
|
2
|
+
// close", 2. "Checks the model against the lock"): every collection,
|
|
3
|
+
// field and index the model names is in the lock with the same type and
|
|
4
|
+
// options. The core folds by the lock alone, so a model changed without
|
|
5
|
+
// `ncdb model build` would write fields no lock knows. The model may name
|
|
6
|
+
// less than the lock: an app need not declare every collection. A field's
|
|
7
|
+
// description and deprecation are no type or option, and are not
|
|
8
|
+
// compared. Internal: the package's entry does not reach it.
|
|
9
|
+
import * as texts from "./texts.js";
|
|
10
|
+
/** The key under which `nc.model` keeps the function that describes the model, as `ncdb model build` reads it. */
|
|
11
|
+
const DESCRIBE = Symbol.for("nocentraldb.model.describe");
|
|
12
|
+
/** What a field's type is in the lock and in the model's description: the type, with its options, targets, element and person. */
|
|
13
|
+
const shape = (field) => ({
|
|
14
|
+
type: field.type,
|
|
15
|
+
options: field.options,
|
|
16
|
+
targets: field.targets,
|
|
17
|
+
of: field.of,
|
|
18
|
+
personal: field.personal,
|
|
19
|
+
});
|
|
20
|
+
/** What an index is: its fields with their directions, its equality prefix and its scope. */
|
|
21
|
+
const indexShape = (index) => ({
|
|
22
|
+
fields: index.fields,
|
|
23
|
+
equal: index.equal ?? 0,
|
|
24
|
+
scope: index.scope ?? "member",
|
|
25
|
+
});
|
|
26
|
+
/** A JSON value's text with every object's keys sorted, as the lock writes them, so that key order does not count. */
|
|
27
|
+
const canonical = (value) => JSON.stringify(value, (_key, inner) => inner !== null && typeof inner === "object" && !Array.isArray(inner)
|
|
28
|
+
? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))
|
|
29
|
+
: inner);
|
|
30
|
+
/** Whether two JSON values are equal, whatever the order of their keys. */
|
|
31
|
+
const same = (a, b) => canonical(a) === canonical(b);
|
|
32
|
+
/** Why `lock` is out of date for `model`, or `undefined` when every collection, field and index the model names is in the lock as the model names it. */
|
|
33
|
+
export const lockOutOfDate = (model, lock) => {
|
|
34
|
+
const describe = model[DESCRIBE];
|
|
35
|
+
if (describe === undefined)
|
|
36
|
+
return undefined;
|
|
37
|
+
const locked = (lock?.collections ??
|
|
38
|
+
{});
|
|
39
|
+
for (const [name, collection] of Object.entries(describe().collections)) {
|
|
40
|
+
const inLock = locked[name];
|
|
41
|
+
if (inLock === undefined)
|
|
42
|
+
return texts.lockHasNoCollection(name);
|
|
43
|
+
const fields = (collection?.fields ?? {});
|
|
44
|
+
const lockFields = (inLock.fields ?? {});
|
|
45
|
+
for (const [field, described] of Object.entries(fields)) {
|
|
46
|
+
const kept = lockFields[field];
|
|
47
|
+
if (kept === undefined)
|
|
48
|
+
return texts.lockHasNoField(name, field);
|
|
49
|
+
if (!same(shape(described ?? {}), shape(kept)))
|
|
50
|
+
return texts.lockFieldDiffers(name, field);
|
|
51
|
+
}
|
|
52
|
+
const indexes = (collection?.indexes ?? {});
|
|
53
|
+
const lockIndexes = (inLock.indexes ?? {});
|
|
54
|
+
for (const [index, described] of Object.entries(indexes)) {
|
|
55
|
+
const kept = lockIndexes[index];
|
|
56
|
+
if (kept === undefined)
|
|
57
|
+
return texts.lockHasNoIndex(name, index);
|
|
58
|
+
if (!same(indexShape(described ?? {}), indexShape(kept)))
|
|
59
|
+
return texts.lockIndexDiffers(name, index);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
return undefined;
|
|
63
|
+
};
|