@nocentraldb/sdk 0.0.0 → 0.1.0-alpha.71

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 (57) 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 +14 -2
@@ -0,0 +1,14 @@
1
+ /** The account's recovery code, held until the person stored it (RFC 0010, "The recovery code"). Its string, JSON and inspect forms are `"RecoveryCode(redacted)"`. */
2
+ export interface RecoveryCode {
3
+ /** The twelve words, for the person to write down or keep in a password manager. */
4
+ words(): readonly string[];
5
+ /** The person stored the code: the database forgets it, and `recoveryCode()` answers `null` from then on. */
6
+ confirm(): Promise<void>;
7
+ }
8
+ /** A pairing answer (RFC 0010, "The pairing answer"): public data with a text form, as an invitation is. It carries the account key sealed to the one device that asked, which only that device opens. */
9
+ export interface PairingAnswer {
10
+ /** Its text, `ncdb-pair-1:` and unpadded base64url, to show the new device as a QR code or text. */
11
+ toString(): string;
12
+ }
13
+ /** Reads a pairing answer's text, as the new device received it (NOC-321 point 3). It checks only the prefix and the encoding, and fails with `invalidValue` otherwise; `completePairing` checks the rest. */
14
+ export declare const pairingAnswer: (text: string) => PairingAnswer;
@@ -0,0 +1,34 @@
1
+ // The types of accounts in the TypeScript SDK (NOC-316; RFC 0009,
2
+ // "Accounts and devices"; the shapes the owner decided on NOC-321,
3
+ // Carsten, 2026-11-15). What makes them is in accountCalls.ts, but for
4
+ // `nc.pairingAnswer`, which reads an answer's text as `nc.invitation` reads
5
+ // an invitation's.
6
+ import { NcError } from "./error.js";
7
+ import * as texts from "./texts.js";
8
+ const PREFIX = "ncdb-pair-1:";
9
+ /** Unpadded base64url: its alphabet, and a length no group of 4 leaves 1 character over. */
10
+ const BASE64URL = /^[A-Za-z0-9_-]+$/;
11
+ /** A pairing answer the SDK holds as its text. */
12
+ class PairingAnswerText {
13
+ #text;
14
+ constructor(text) {
15
+ this.#text = text;
16
+ }
17
+ toString() {
18
+ return this.#text;
19
+ }
20
+ toJSON() {
21
+ return this.#text;
22
+ }
23
+ }
24
+ /** Reads a pairing answer's text, as the new device received it (NOC-321 point 3). It checks only the prefix and the encoding, and fails with `invalidValue` otherwise; `completePairing` checks the rest. */
25
+ export const pairingAnswer = (text) => {
26
+ const trimmed = text.trim();
27
+ const body = trimmed.startsWith(PREFIX)
28
+ ? trimmed.slice(PREFIX.length)
29
+ : undefined;
30
+ if (body === undefined || !BASE64URL.test(body) || body.length % 4 === 1) {
31
+ throw new NcError("invalidValue", texts.NOT_APAIRING_ANSWER);
32
+ }
33
+ return new PairingAnswerText(trimmed);
34
+ };
@@ -0,0 +1,34 @@
1
+ import { type PairingAnswer, type RecoveryCode } from "./account.ts";
2
+ import type { Cbor } from "./cbor.ts";
3
+ import type { Invitation, Notice } from "./members.ts";
4
+ type Ask = (call: string, args: Record<string, unknown>) => Promise<Cbor>;
5
+ /** `db.account` for the core `ask` speaks to. */
6
+ export declare const accountOf: (ask: Ask) => {
7
+ recoveryCode: () => Promise<RecoveryCode | null>;
8
+ recovered: () => Promise<Notice | null>;
9
+ pair: ({ kind, invitation, }: {
10
+ kind: "device" | "agent";
11
+ invitation: Invitation;
12
+ }) => Promise<{
13
+ answer: PairingAnswer;
14
+ added: {
15
+ space: string;
16
+ notice: Notice;
17
+ }[];
18
+ askAdmins: string[];
19
+ }>;
20
+ completePairing: (answer: PairingAnswer) => Promise<{
21
+ readonly notices: readonly Notice[];
22
+ }>;
23
+ removeMember: (member: string, { recover }: {
24
+ recover: string;
25
+ }) => Promise<{
26
+ readonly removed: readonly {
27
+ readonly space: string;
28
+ readonly notice: Notice;
29
+ }[];
30
+ readonly askAdmins: readonly string[];
31
+ readonly notice: Notice;
32
+ }>;
33
+ };
34
+ export {};
@@ -0,0 +1,48 @@
1
+ // The account calls of the TypeScript SDK (NOC-316; RFC 0009, "Accounts and
2
+ // devices"; the shapes the owner decided on NOC-321, Carsten, 2026-11-15).
3
+ // Internal: the package's entry does not reach it.
4
+ import { pairingAnswer, } from "./account.js";
5
+ const REDACTED = "RecoveryCode(redacted)";
6
+ /** A recovery code whose words only `words()` gives: its string, JSON and Node's inspect forms are redacted (RFC 0009). */
7
+ const recoveryCodeOf = (words, ask) => {
8
+ const kept = Object.freeze([...words]);
9
+ const code = {
10
+ words: () => kept,
11
+ confirm: async () => {
12
+ await ask("account.confirmRecoveryCode", {});
13
+ },
14
+ toString: () => REDACTED,
15
+ toJSON: () => REDACTED,
16
+ [Symbol.toPrimitive]: () => REDACTED,
17
+ [Symbol.for("nodejs.util.inspect.custom")]: () => REDACTED,
18
+ };
19
+ return Object.freeze(code);
20
+ };
21
+ /** `db.account` for the core `ask` speaks to. */
22
+ export const accountOf = (ask) => ({
23
+ recoveryCode: async () => {
24
+ const answer = (await ask("account.recoveryCode", {}));
25
+ return Array.isArray(answer?.words)
26
+ ? recoveryCodeOf(answer.words, ask)
27
+ : null;
28
+ },
29
+ recovered: async () => (await ask("account.recovered", {})) ?? null,
30
+ pair: async ({ kind, invitation, }) => {
31
+ const paired = (await ask("account.pair", {
32
+ kind,
33
+ invitation: String(invitation),
34
+ }));
35
+ return {
36
+ answer: pairingAnswer(paired.answer),
37
+ added: paired.added ?? [],
38
+ askAdmins: paired.askAdmins ?? [],
39
+ };
40
+ },
41
+ completePairing: async (answer) => (await ask("account.completePairing", {
42
+ answer: String(answer),
43
+ })),
44
+ removeMember: async (member, { recover }) => (await ask("account.removeMember", {
45
+ member,
46
+ recover,
47
+ })),
48
+ });
@@ -0,0 +1,49 @@
1
+ import type { Notice } from "./members.ts";
2
+ type Id = string;
3
+ type Ask = (call: string, args: Record<string, unknown>) => Promise<unknown>;
4
+ /** Where an object the SDK read came from: what the core reads it by. */
5
+ interface Source {
6
+ readonly space: Id;
7
+ readonly collection: string;
8
+ readonly id: Id;
9
+ }
10
+ /**
11
+ * The objects one database's SDK read, each with its collection, which a
12
+ * read object does not carry. Weakly held, so that a forgotten object is
13
+ * not kept; a spread of one, or an object another database read, is not
14
+ * among them.
15
+ */
16
+ export declare const readObjects: () => {
17
+ /** Remembers `object`, read from `collection`, and gives it back. */
18
+ remember<T extends object>(object: T, collection: string): T;
19
+ /** Where `object` came from; `invalidValue` when the SDK did not read it. */
20
+ sourceOf(object: object): Source;
21
+ };
22
+ /** The options of `db.spaces.createAdHoc`. */
23
+ export interface AdHocOptions {
24
+ readonly copy: readonly object[];
25
+ readonly personal?: boolean;
26
+ readonly local?: boolean;
27
+ }
28
+ /** What the core's `spaces.createAdHoc` answers, the space still as its id. */
29
+ export interface AdHocAnswer {
30
+ readonly space: Id;
31
+ readonly notice: Notice;
32
+ readonly copies: readonly {
33
+ readonly source: Id;
34
+ readonly copy: Id;
35
+ }[];
36
+ readonly clearedLinks: number;
37
+ readonly pluginFieldsNotCopied: number;
38
+ }
39
+ /** Asks the core for an ad-hoc space; refuses before it any object the SDK did not read. */
40
+ export declare const createAdHoc: (ask: Ask, read: ReturnType<typeof readObjects>, options: AdHocOptions) => Promise<AdHocAnswer>;
41
+ /** The lookups of the ad-hoc space `space`. */
42
+ export declare const lookupsOf: (ask: Ask, space: Id) => {
43
+ sourceOf: (copy: Id) => Promise<{
44
+ readonly space: Id;
45
+ readonly id: Id;
46
+ } | undefined>;
47
+ copyOf: (sourceSpace: Id, source: Id) => Promise<string | undefined>;
48
+ };
49
+ export {};
package/dist/adHoc.js ADDED
@@ -0,0 +1,52 @@
1
+ // Ad-hoc spaces for sub-agents over the bridge (NOC-318 S4; RFC 0009,
2
+ // "Sub-agents and ad-hoc spaces"; crates/nocentraldb/src/bridge/ad_hoc.rs).
3
+ // The owner decided the shapes on NOC-351 (Carsten, 2026-11-16): `copy`
4
+ // takes the objects the SDK read, the call answers each source with its
5
+ // copy and the counts, and `space.sourceOf` and `space.copyOf` find them
6
+ // later. Internal: the package's entry does not reach it.
7
+ import { NcError } from "./error.js";
8
+ import * as texts from "./texts.js";
9
+ /**
10
+ * The objects one database's SDK read, each with its collection, which a
11
+ * read object does not carry. Weakly held, so that a forgotten object is
12
+ * not kept; a spread of one, or an object another database read, is not
13
+ * among them.
14
+ */
15
+ export const readObjects = () => {
16
+ const read = new WeakMap();
17
+ return {
18
+ /** Remembers `object`, read from `collection`, and gives it back. */
19
+ remember(object, collection) {
20
+ const { $space, $id } = object;
21
+ if ($space !== undefined && $id !== undefined) {
22
+ read.set(object, { space: $space, collection, id: $id });
23
+ }
24
+ return object;
25
+ },
26
+ /** Where `object` came from; `invalidValue` when the SDK did not read it. */
27
+ sourceOf(object) {
28
+ const source = read.get(object);
29
+ if (source === undefined) {
30
+ throw new NcError("invalidValue", texts.AD_HOC_COPY_NOT_READ);
31
+ }
32
+ return source;
33
+ },
34
+ };
35
+ };
36
+ /** Asks the core for an ad-hoc space; refuses before it any object the SDK did not read. */
37
+ export const createAdHoc = async (ask, read, options) => {
38
+ const args = {
39
+ copy: options.copy.map((object) => read.sourceOf(object)),
40
+ };
41
+ if (options.personal !== undefined)
42
+ args.personal = options.personal;
43
+ if (options.local !== undefined)
44
+ args.local = options.local;
45
+ return (await ask("spaces.createAdHoc", args));
46
+ };
47
+ /** The lookups of the ad-hoc space `space`. */
48
+ export const lookupsOf = (ask, space) => ({
49
+ sourceOf: async (copy) => ((await ask("space.sourceOf", { space, copy })) ?? undefined),
50
+ copyOf: async (sourceSpace, source) => ((await ask("space.copyOf", { space, sourceSpace, source })) ??
51
+ undefined),
52
+ });
package/dist/cbor.d.ts ADDED
@@ -0,0 +1,8 @@
1
+ /** A value the bridge carries. */
2
+ export type Cbor = null | boolean | number | string | Uint8Array | Cbor[] | {
3
+ [key: string]: Cbor | undefined;
4
+ };
5
+ /** The canonical bytes of `value`. A key whose value is `undefined` is left out. */
6
+ export declare const encode: (value: unknown) => Uint8Array;
7
+ /** The value of `bytes`, which the core wrote. A map with integer keys reads as an object with those keys as text. */
8
+ export declare const decode: (bytes: Uint8Array) => Cbor;
package/dist/cbor.js ADDED
@@ -0,0 +1,223 @@
1
+ // The canonical CBOR of RFC 0002 ("The canonical encoding";
2
+ // crates/ncdb-plugin/src/cbor.rs), as the worker bridge speaks it: definite
3
+ // and minimal lengths and integers, map keys sorted by the bytes of their
4
+ // encoding, floats in their shortest exact form with every NaN as 0xf97e00,
5
+ // and no tags or simple values but false, true and null. The core decodes
6
+ // only canonical bytes, so the SDK writes nothing else. Internal: not part
7
+ // of the package's public names.
8
+ const text = new TextEncoder();
9
+ const utf8 = new TextDecoder("utf-8", { fatal: true });
10
+ /** The canonical bytes of `value`. A key whose value is `undefined` is left out. */
11
+ export const encode = (value) => {
12
+ const out = [];
13
+ write(out, value);
14
+ return Uint8Array.from(out);
15
+ };
16
+ const head = (out, major, n) => {
17
+ const m = major << 5;
18
+ const v = BigInt(n);
19
+ if (v < 24n)
20
+ out.push(m | Number(v));
21
+ else if (v < 0x100n)
22
+ out.push(m | 24, Number(v));
23
+ else if (v < 0x10000n)
24
+ out.push(m | 25, Number(v >> 8n), Number(v & 0xffn));
25
+ else if (v < 0x100000000n) {
26
+ out.push(m | 26);
27
+ for (let shift = 24n; shift >= 0n; shift -= 8n)
28
+ out.push(Number((v >> shift) & 0xffn));
29
+ }
30
+ else {
31
+ out.push(m | 27);
32
+ for (let shift = 56n; shift >= 0n; shift -= 8n)
33
+ out.push(Number((v >> shift) & 0xffn));
34
+ }
35
+ };
36
+ const write = (out, value) => {
37
+ if (value === null) {
38
+ out.push(0xf6);
39
+ }
40
+ else if (value === true || value === false) {
41
+ out.push(value ? 0xf5 : 0xf4);
42
+ }
43
+ else if (typeof value === "number") {
44
+ number(out, value);
45
+ }
46
+ else if (typeof value === "string") {
47
+ const bytes = text.encode(value);
48
+ head(out, 3, bytes.length);
49
+ out.push(...bytes);
50
+ }
51
+ else if (value instanceof Uint8Array) {
52
+ head(out, 2, value.length);
53
+ out.push(...value);
54
+ }
55
+ else if (Array.isArray(value)) {
56
+ head(out, 4, value.length);
57
+ for (const item of value)
58
+ write(out, item);
59
+ }
60
+ else if (typeof value === "object" &&
61
+ Object.getPrototypeOf(value) === Object.prototype) {
62
+ const entries = Object.entries(value)
63
+ .filter(([, v]) => v !== undefined)
64
+ .map(([k, v]) => [encode(k), v])
65
+ .sort(([a], [b]) => compare(a, b));
66
+ head(out, 5, entries.length);
67
+ for (const [key, v] of entries) {
68
+ out.push(...key);
69
+ write(out, v);
70
+ }
71
+ }
72
+ else {
73
+ throw new TypeError(`the bridge cannot carry a ${typeof value}`);
74
+ }
75
+ };
76
+ const compare = (a, b) => {
77
+ for (let i = 0; i < Math.min(a.length, b.length); i++) {
78
+ const x = a[i];
79
+ const y = b[i];
80
+ if (x !== y)
81
+ return x - y;
82
+ }
83
+ return a.length - b.length;
84
+ };
85
+ const number = (out, n) => {
86
+ if (Number.isSafeInteger(n) && !Object.is(n, -0)) {
87
+ if (n >= 0)
88
+ head(out, 0, n);
89
+ else
90
+ head(out, 1, -1n - BigInt(n));
91
+ return;
92
+ }
93
+ if (Number.isNaN(n)) {
94
+ out.push(0xf9, 0x7e, 0x00);
95
+ return;
96
+ }
97
+ const half = toHalf(n);
98
+ if (half !== undefined) {
99
+ out.push(0xf9, half >> 8, half & 0xff);
100
+ return;
101
+ }
102
+ const view = new DataView(new ArrayBuffer(8));
103
+ view.setFloat32(0, n);
104
+ if (view.getFloat32(0) === n) {
105
+ out.push(0xfa, ...new Uint8Array(view.buffer, 0, 4));
106
+ return;
107
+ }
108
+ view.setFloat64(0, n);
109
+ out.push(0xfb, ...new Uint8Array(view.buffer));
110
+ };
111
+ /** The 16-bit form of `n`, when it keeps `n` exactly. */
112
+ const toHalf = (n) => {
113
+ const sign = n < 0 || Object.is(n, -0) ? 0x8000 : 0;
114
+ const a = Math.abs(n);
115
+ if (a === Number.POSITIVE_INFINITY)
116
+ return sign | 0x7c00;
117
+ if (a === 0)
118
+ return sign;
119
+ const exponent = Math.floor(Math.log2(a));
120
+ if (exponent > 15 || exponent < -24)
121
+ return undefined;
122
+ if (exponent >= -14) {
123
+ const mantissa = a / 2 ** exponent - 1;
124
+ const scaled = mantissa * 1024;
125
+ if (!Number.isInteger(scaled) ||
126
+ fromHalf(sign | ((exponent + 15) << 10) | scaled) !== n)
127
+ return undefined;
128
+ return sign | ((exponent + 15) << 10) | scaled;
129
+ }
130
+ const scaled = a / 2 ** -24;
131
+ if (!Number.isInteger(scaled) || scaled >= 1024)
132
+ return undefined;
133
+ return sign | scaled;
134
+ };
135
+ const fromHalf = (bits) => {
136
+ const sign = bits & 0x8000 ? -1 : 1;
137
+ const exponent = (bits >> 10) & 0x1f;
138
+ const mantissa = bits & 0x3ff;
139
+ if (exponent === 0)
140
+ return sign * mantissa * 2 ** -24;
141
+ if (exponent === 0x1f)
142
+ return mantissa ? Number.NaN : sign * Number.POSITIVE_INFINITY;
143
+ return sign * (1 + mantissa / 1024) * 2 ** (exponent - 15);
144
+ };
145
+ /** The value of `bytes`, which the core wrote. A map with integer keys reads as an object with those keys as text. */
146
+ export const decode = (bytes) => {
147
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
148
+ let at = 0;
149
+ const take = (n) => {
150
+ if (at + n > bytes.length)
151
+ throw new RangeError("the message is truncated");
152
+ const start = at;
153
+ at += n;
154
+ return start;
155
+ };
156
+ const length = (info) => {
157
+ if (info < 24)
158
+ return info;
159
+ if (info === 24)
160
+ return view.getUint8(take(1));
161
+ if (info === 25)
162
+ return view.getUint16(take(2));
163
+ if (info === 26)
164
+ return view.getUint32(take(4));
165
+ // The core writes no integer beyond 2^53 - 1 to the SDK; one would
166
+ // read rounded, as JavaScript's numbers do.
167
+ if (info === 27)
168
+ return Number(view.getBigUint64(take(8)));
169
+ throw new RangeError("an indefinite length is not canonical");
170
+ };
171
+ const item = () => {
172
+ const initial = view.getUint8(take(1));
173
+ const major = initial >> 5;
174
+ const info = initial & 0x1f;
175
+ switch (major) {
176
+ case 0:
177
+ return length(info);
178
+ case 1:
179
+ return -1 - length(info);
180
+ case 2: {
181
+ const n = length(info);
182
+ return bytes.slice(take(n), at);
183
+ }
184
+ case 3: {
185
+ const n = length(info);
186
+ return utf8.decode(bytes.subarray(take(n), at));
187
+ }
188
+ case 4: {
189
+ const n = length(info);
190
+ return Array.from({ length: n }, item);
191
+ }
192
+ case 5: {
193
+ const n = length(info);
194
+ const map = {};
195
+ for (let i = 0; i < n; i++) {
196
+ const key = item();
197
+ map[String(key)] = item();
198
+ }
199
+ return map;
200
+ }
201
+ case 7:
202
+ if (info === 20)
203
+ return false;
204
+ if (info === 21)
205
+ return true;
206
+ if (info === 22)
207
+ return null;
208
+ if (info === 25)
209
+ return fromHalf(view.getUint16(take(2)));
210
+ if (info === 26)
211
+ return view.getFloat32(take(4));
212
+ if (info === 27)
213
+ return view.getFloat64(take(8));
214
+ throw new RangeError("a simple value the bridge does not carry");
215
+ default:
216
+ throw new RangeError("a tag the bridge does not carry");
217
+ }
218
+ };
219
+ const value = item();
220
+ if (at !== bytes.length)
221
+ throw new RangeError("bytes after the message");
222
+ return value;
223
+ };
@@ -0,0 +1,14 @@
1
+ import type { Db, open } from "./db.ts";
2
+ /** The core, as the SDK reaches it: one CBOR request, one CBOR answer, and the events it sends unasked. Internal; a test passes a fake. */
3
+ export interface Core {
4
+ call(request: Uint8Array): Promise<Uint8Array>;
5
+ terminate(): void;
6
+ /** Gives the core's events, such as `{event: "folded", folds}`, to `listener`. */
7
+ listen(listener: (event: Uint8Array) => void): void;
8
+ }
9
+ type OpenOptions = Parameters<typeof open>[0];
10
+ /** Opens the database in the worker the package ships, or, when another tab owns it, through that tab (NOC-177; RFC 0006, "The browser"). */
11
+ export declare const connectWorker: (options: OpenOptions) => Promise<Db>;
12
+ /** Opens the database through `core`. Internal: `open` passes the worker, a test a fake. */
13
+ export declare const connect: (core: Core, options: OpenOptions) => Promise<Db>;
14
+ export {};