@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.
- 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 +14 -2
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A member's invitation: its public identity, which an admin passes to
|
|
3
|
+
* `space.members.add` (RFC 0009, "Invitations and members"). Nothing in it
|
|
4
|
+
* is secret. `toString()` gives its text form, `ncdb-invite-1:…`.
|
|
5
|
+
*/
|
|
6
|
+
export interface Invitation {
|
|
7
|
+
/** The fingerprint of its account, as twelve blocks of five digits: known for this member's own invitation, from `db.invitation()`; unset for one read with `nc.invitation`, whose fingerprint `members.add` gives with `unknownAccount`. */
|
|
8
|
+
readonly fingerprint?: string;
|
|
9
|
+
/** The invitation's text, `ncdb-invite-1:` and base64url. */
|
|
10
|
+
toString(): string;
|
|
11
|
+
}
|
|
12
|
+
/** What a call that changes who can read or write does not do: its `code`, named by the call, and a plain English `text` for the developer (RFC 0009, "Notices"). */
|
|
13
|
+
export interface Notice {
|
|
14
|
+
readonly code: string;
|
|
15
|
+
readonly text: string;
|
|
16
|
+
}
|
|
17
|
+
/** A role in a space (RFC 0008, "Roles and rights"). */
|
|
18
|
+
type Role = "reader" | "writer" | "admin";
|
|
19
|
+
/** A member of a space, as `space.members.list()` gives it. */
|
|
20
|
+
interface Member {
|
|
21
|
+
/** Its id, 64 lowercase hex digits, which `setRole` and `remove` take. */
|
|
22
|
+
readonly id: string;
|
|
23
|
+
/** The fingerprint of the account its certificate names. */
|
|
24
|
+
readonly account: string;
|
|
25
|
+
/** The fingerprint of the account `account` is linked into, when this database knows the link; `null` otherwise (RFC 0010, "Linking accounts drawn per database"). */
|
|
26
|
+
readonly linkedTo: string | null;
|
|
27
|
+
readonly kind: "device" | "agent" | "subAgent";
|
|
28
|
+
/** Its role; `null` while no membership of it is folded. */
|
|
29
|
+
readonly role: Role | null;
|
|
30
|
+
/** Whether it is this member. */
|
|
31
|
+
readonly self: boolean;
|
|
32
|
+
}
|
|
33
|
+
/** The members of a space (RFC 0009, "Invitations and members"). */
|
|
34
|
+
export interface Members {
|
|
35
|
+
/** Adds the member of each invitation; `role` may be left out for an agent. An account new to this device fails with `unknownAccount`, carrying its fingerprint, until `fingerprint` passes the one a person compared. With several invitations it adds them in turn and stops at the first that fails, with that one's error: the members added before it stay, and an invitation is checked only when its turn comes. On success it answers the last invitation's notice (Carsten, 2026-11-14, NOC-313). */
|
|
36
|
+
add(invitations: Invitation | readonly Invitation[], options?: {
|
|
37
|
+
role?: Role;
|
|
38
|
+
fingerprint?: string;
|
|
39
|
+
}): Promise<{
|
|
40
|
+
readonly notice: Notice;
|
|
41
|
+
}>;
|
|
42
|
+
/** The current members. */
|
|
43
|
+
list(): Promise<Member[]>;
|
|
44
|
+
/** Raises or lowers a member's role. */
|
|
45
|
+
setRole(member: string, role: Role): Promise<{
|
|
46
|
+
readonly notice: Notice;
|
|
47
|
+
}>;
|
|
48
|
+
/** Removes a member and rotates the space key. */
|
|
49
|
+
remove(member: string): Promise<{
|
|
50
|
+
readonly notice: Notice;
|
|
51
|
+
}>;
|
|
52
|
+
}
|
|
53
|
+
/** Reads an invitation from its text. It checks the form, `ncdb-invite-1:` and unpadded base64url, and fails with `invalidValue` otherwise; the core checks the rest when `members.add` reads it. */
|
|
54
|
+
export declare const invitation: (text: string) => Invitation;
|
|
55
|
+
export {};
|
package/dist/members.js
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
// Invitations and members (RFC 0009, "Invitations and members"; NOC-176
|
|
2
|
+
// slice 4b): the types an app sees and `nc.invitation`. membership.ts
|
|
3
|
+
// implements a space's `members` over the bridge's `invitation` and
|
|
4
|
+
// `members.*` calls (crates/nocentraldb/src/bridge/members.rs). A member id is its 64
|
|
5
|
+
// lowercase hex digits (Carsten, 2026-11-13, NOC-298). What RFC 0009 leaves
|
|
6
|
+
// open follows NOC-305 A and A (Carsten, 2026-11-13).
|
|
7
|
+
import { NcError } from "./error.js";
|
|
8
|
+
import * as texts from "./texts.js";
|
|
9
|
+
const PREFIX = "ncdb-invite-1:";
|
|
10
|
+
/** Unpadded base64url: its alphabet, and a length no group of 4 leaves 1 character over. */
|
|
11
|
+
const BASE64URL = /^[A-Za-z0-9_-]+$/;
|
|
12
|
+
/** An invitation the SDK holds as its text. */
|
|
13
|
+
class InvitationText {
|
|
14
|
+
fingerprint;
|
|
15
|
+
#text;
|
|
16
|
+
constructor(text, fingerprint) {
|
|
17
|
+
this.#text = text;
|
|
18
|
+
if (fingerprint !== undefined)
|
|
19
|
+
this.fingerprint = fingerprint;
|
|
20
|
+
}
|
|
21
|
+
toString() {
|
|
22
|
+
return this.#text;
|
|
23
|
+
}
|
|
24
|
+
toJSON() {
|
|
25
|
+
return this.#text;
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
/** Reads an invitation from its text. It checks the form, `ncdb-invite-1:` and unpadded base64url, and fails with `invalidValue` otherwise; the core checks the rest when `members.add` reads it. */
|
|
29
|
+
export const invitation = (text) => {
|
|
30
|
+
const trimmed = text.trim();
|
|
31
|
+
const body = trimmed.startsWith(PREFIX)
|
|
32
|
+
? trimmed.slice(PREFIX.length)
|
|
33
|
+
: undefined;
|
|
34
|
+
if (body === undefined || !BASE64URL.test(body) || body.length % 4 === 1) {
|
|
35
|
+
throw new NcError("invalidValue", texts.NOT_AN_INVITATION);
|
|
36
|
+
}
|
|
37
|
+
return new InvitationText(trimmed);
|
|
38
|
+
};
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { Invitation, Members } from "./members.ts";
|
|
2
|
+
/** This member's invitation, as the core's `invitation` call answers it. */
|
|
3
|
+
export declare const ownInvitation: (answer: unknown) => Invitation;
|
|
4
|
+
/** The members of the space `space`, through `ask`. */
|
|
5
|
+
export declare const membersOf: (ask: (call: string, args: Record<string, unknown>) => Promise<unknown>, space: string) => Members;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// A space's members and this member's invitation over the bridge (NOC-176
|
|
2
|
+
// slice 4b; crates/nocentraldb/src/bridge/members.rs). Internal: the
|
|
3
|
+
// package's entry does not reach it, so it is not in the API report.
|
|
4
|
+
/** This member's invitation, as the core's `invitation` call answers it. */
|
|
5
|
+
export const ownInvitation = (answer) => {
|
|
6
|
+
const { text, fingerprint } = answer;
|
|
7
|
+
return {
|
|
8
|
+
fingerprint,
|
|
9
|
+
toString: () => text,
|
|
10
|
+
toJSON: () => text,
|
|
11
|
+
};
|
|
12
|
+
};
|
|
13
|
+
/** The members of the space `space`, through `ask`. */
|
|
14
|
+
export const membersOf = (ask, space) => ({
|
|
15
|
+
add: async (invitations, options = {}) => {
|
|
16
|
+
const list = Array.isArray(invitations) ? invitations : [invitations];
|
|
17
|
+
return (await ask("members.add", {
|
|
18
|
+
space,
|
|
19
|
+
invitations: list.map(String),
|
|
20
|
+
...(options.role === undefined ? {} : { role: options.role }),
|
|
21
|
+
...(options.fingerprint === undefined
|
|
22
|
+
? {}
|
|
23
|
+
: { fingerprint: options.fingerprint }),
|
|
24
|
+
}));
|
|
25
|
+
},
|
|
26
|
+
list: async () => (await ask("members.list", { space })),
|
|
27
|
+
setRole: async (member, role) => (await ask("members.setRole", { space, member, role })),
|
|
28
|
+
remove: async (member) => (await ask("members.remove", { space, member })),
|
|
29
|
+
});
|
package/dist/nc.d.ts
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
import type { Query } from "./db.ts";
|
|
2
|
+
/** What every field of the model carries: what it reads as (`T`), and whether it is deprecated (`D`). */
|
|
3
|
+
interface Value<T = unknown, D extends boolean = false> {
|
|
4
|
+
readonly "nc.reads": T;
|
|
5
|
+
readonly "nc.deprecated": D;
|
|
6
|
+
}
|
|
7
|
+
/** A field of the model that reads as `T`, deprecated when `D` is true: its type, and the modifiers chained after it. */
|
|
8
|
+
interface Field<T = unknown, D extends boolean = false> extends Value<T, D> {
|
|
9
|
+
/** Marks the field as personal, about `person`: `"self"` or a link field of the same collection. */
|
|
10
|
+
personal(options: {
|
|
11
|
+
person: string;
|
|
12
|
+
}): Field<T, D>;
|
|
13
|
+
/** Adds a description, which is copied into the lock. */
|
|
14
|
+
describe(text: string): Field<T, D>;
|
|
15
|
+
/** Hides the field from the app, and keeps it in the model and the data. */
|
|
16
|
+
deprecated(reason: string): Field<T, true>;
|
|
17
|
+
}
|
|
18
|
+
/** A reference field, deprecated when `D` is true: it takes `describe` and `deprecated`, and cannot be personal (RFC 0005, "References into another space"). */
|
|
19
|
+
interface Ref<D extends boolean = false> extends Value<Target, D> {
|
|
20
|
+
/** Adds a description, which is copied into the lock. */
|
|
21
|
+
describe(text: string): Ref<D>;
|
|
22
|
+
/** Hides the field from the app, and keeps it in the model and the data. */
|
|
23
|
+
deprecated(reason: string): Ref<true>;
|
|
24
|
+
}
|
|
25
|
+
/** The fields of a collection, by name. */
|
|
26
|
+
type Fields = Record<string, Value<unknown, boolean>>;
|
|
27
|
+
/** A collection of the model with the fields `F` and the indexes `I`, deprecated when `D` is true: its fields, and the places for computed fields, views and indexes. */
|
|
28
|
+
interface Collection<F extends Fields = Fields, D extends boolean = false, I extends Indexes = Indexes> {
|
|
29
|
+
readonly "nc.collection": F;
|
|
30
|
+
readonly "nc.deprecated": D;
|
|
31
|
+
/** A query of every declared index, by name (RFC 0009, "Queries and indexes"). */
|
|
32
|
+
readonly indexes: {
|
|
33
|
+
readonly [K in keyof I]: Query<Item<F>, EqualOf<F, I[K]>>;
|
|
34
|
+
};
|
|
35
|
+
/** Hides the collection from the app, and keeps it in the model and the data. */
|
|
36
|
+
deprecated(reason: string): Collection<F, true, I>;
|
|
37
|
+
}
|
|
38
|
+
/** The declared indexes of a collection, by name. */
|
|
39
|
+
type Indexes = Record<string, Index>;
|
|
40
|
+
/** The fields of `F` that are not deprecated, each optional, as the app reads them. */
|
|
41
|
+
type Readable<F extends Fields> = {
|
|
42
|
+
[K in keyof F as F[K] extends Value<unknown, true> ? never : K]?: F[K]["nc.reads"];
|
|
43
|
+
};
|
|
44
|
+
/** An object of a collection with the fields `F`, as a read gives it: its fields and its ids (RFC 0009, "Get by id"). */
|
|
45
|
+
type Item<F extends Fields> = Readable<F> & {
|
|
46
|
+
readonly $id: ObjectId;
|
|
47
|
+
readonly $space: SpaceId;
|
|
48
|
+
readonly $deleted: boolean;
|
|
49
|
+
};
|
|
50
|
+
/** The values `.equal` takes for the first `N` fields `K` of a collection with the fields `F`: one per field, of that field's type. */
|
|
51
|
+
type EqualValues<F extends Fields, K extends readonly string[], N extends number, Taken extends readonly unknown[] = []> = Taken["length"] extends N ? Taken : K extends readonly [
|
|
52
|
+
infer H extends string,
|
|
53
|
+
...infer R extends readonly string[]
|
|
54
|
+
] ? EqualValues<F, R, N, [
|
|
55
|
+
...Taken,
|
|
56
|
+
Exclude<F[H & keyof F]["nc.reads"], undefined>
|
|
57
|
+
]> : Taken;
|
|
58
|
+
/** The values `.equal` takes for the index `X` of a collection with the fields `F`. */
|
|
59
|
+
type EqualOf<F extends Fields, X> = X extends Index<infer K, infer N> ? EqualValues<F, K, N> : readonly [];
|
|
60
|
+
/** The collections of a model without the deprecated ones, which the app does not see. */
|
|
61
|
+
type Visible<C> = {
|
|
62
|
+
[K in keyof C as C[K] extends Collection<Fields, true> ? never : K]: C[K];
|
|
63
|
+
};
|
|
64
|
+
/** A choice option the lock does not list yet, kept as written (RFC 0009, "Get by id"). */
|
|
65
|
+
export type Unknown = {
|
|
66
|
+
unknown: string;
|
|
67
|
+
};
|
|
68
|
+
/**
|
|
69
|
+
* An object of the collection `C` as the app reads it (RFC 0005, "Types for
|
|
70
|
+
* the app"): every field optional, without the deprecated ones. A choice
|
|
71
|
+
* reads as its options or `Unknown`, an `nc.int` as a `number`, a set as
|
|
72
|
+
* an array, a link as an object id, a reference as `{ space, id }`
|
|
73
|
+
* (RFC 0009, "Get by id").
|
|
74
|
+
*/
|
|
75
|
+
export type Infer<C extends Collection<Fields, boolean>> = C extends Collection<infer F, false> ? {
|
|
76
|
+
[K in keyof F as F[K] extends Value<unknown, true> ? never : K]?: F[K]["nc.reads"];
|
|
77
|
+
} : never;
|
|
78
|
+
/** A computed field or a view: named now, designed by a later RFC. */
|
|
79
|
+
interface Named {
|
|
80
|
+
readonly "nc.named": true;
|
|
81
|
+
}
|
|
82
|
+
/** A declared index on the fields `K`, whose first `N` a query fixes with equality. */
|
|
83
|
+
interface Index<K extends readonly string[] = readonly string[], N extends number = number> {
|
|
84
|
+
readonly "nc.index": true;
|
|
85
|
+
readonly "nc.fields": K;
|
|
86
|
+
readonly "nc.equal": N;
|
|
87
|
+
}
|
|
88
|
+
/** The field names of an index's entries, in order. */
|
|
89
|
+
type Names<E extends readonly (string | {
|
|
90
|
+
field: string;
|
|
91
|
+
})[]> = {
|
|
92
|
+
[P in keyof E]: E[P] extends string ? E[P] : E[P] extends {
|
|
93
|
+
field: infer N extends string;
|
|
94
|
+
} ? N : never;
|
|
95
|
+
};
|
|
96
|
+
/** An object id, as a link reads: its 16 bytes as 32 lowercase hex digits (RFC 0009, "Get by id"). */
|
|
97
|
+
type ObjectId = string;
|
|
98
|
+
/** A space id, in the form `$space` carries it. */
|
|
99
|
+
type SpaceId = string;
|
|
100
|
+
/** A reference as the app reads it: the target's space id and object id, without its state (RFC 0009, "Get by id"). */
|
|
101
|
+
type Target = {
|
|
102
|
+
space: SpaceId;
|
|
103
|
+
id: ObjectId;
|
|
104
|
+
};
|
|
105
|
+
/** Declares the model: the collections, by name. */
|
|
106
|
+
export declare function model<C extends Record<string, Collection<Fields, boolean>>>(collections: C): Visible<C>;
|
|
107
|
+
/** Declares a collection: its fields by name, and its computed fields, views and indexes. */
|
|
108
|
+
export declare function collection<F extends Fields, const I extends Indexes = Record<never, never>>(fields: F, options?: {
|
|
109
|
+
computed?: Record<string, Named>;
|
|
110
|
+
views?: Record<string, Named>;
|
|
111
|
+
indexes?: I;
|
|
112
|
+
}): Collection<F, false, I>;
|
|
113
|
+
/** A string, basic value. */
|
|
114
|
+
export declare const string: () => Field<string>;
|
|
115
|
+
/** A signed 64-bit integer, basic value. The app reads and writes it as a `number`, a safe integer (RFC 0005, "Types for the app"). */
|
|
116
|
+
export declare const int: () => Field<number>;
|
|
117
|
+
/** A binary64 number, basic value. */
|
|
118
|
+
export declare const float: () => Field<number>;
|
|
119
|
+
/** A boolean, basic value. */
|
|
120
|
+
export declare const boolean: () => Field<boolean>;
|
|
121
|
+
/** A choice from a fixed list of options, basic value. */
|
|
122
|
+
export declare const oneOf: <const O extends readonly string[]>(options: O) => Field<O[number] | Unknown>;
|
|
123
|
+
/** A set of basic values. */
|
|
124
|
+
export declare const set: <T>(element: Field<T>) => Field<T[]>;
|
|
125
|
+
/** A link to one object, in one collection or in one of several. */
|
|
126
|
+
export declare const link: (target: string | readonly string[]) => Field<ObjectId>;
|
|
127
|
+
/** Links to many objects, in one collection or in several. */
|
|
128
|
+
export declare const links: (target: string | readonly string[]) => Field<ObjectId[]>;
|
|
129
|
+
/** A reference to one object, which may live in another space, in one collection or in one of several (RFC 0005, "References into another space"). */
|
|
130
|
+
export declare const ref: (target: string | readonly string[]) => Ref;
|
|
131
|
+
/** Rich text: reserved, its field type belongs to a later RFC. */
|
|
132
|
+
export declare const richText: () => Field<never>;
|
|
133
|
+
/** A stream: reserved, its field type belongs to a later RFC. */
|
|
134
|
+
export declare const stream: () => Field<never>;
|
|
135
|
+
/** A computed function: named now, its arguments belong to the computed-fields RFC. */
|
|
136
|
+
export declare const reach: (..._args: unknown[]) => Named;
|
|
137
|
+
/** A view: named now, its arguments belong to the computed-fields RFC. */
|
|
138
|
+
export declare const view: (..._args: unknown[]) => Named;
|
|
139
|
+
/** Declares an index: fields in index order, each ascending unless it says otherwise, how many leading fields a query fixes with equality (`equal`, 0 by default), and with `scope: "space"` an index that runs in one space at a time instead of across every space of the member. */
|
|
140
|
+
export declare const index: <const K extends readonly (string | {
|
|
141
|
+
field: string;
|
|
142
|
+
direction: "asc" | "desc";
|
|
143
|
+
})[], const N extends number = 0>(fields: K, options?: {
|
|
144
|
+
equal?: N;
|
|
145
|
+
scope?: "space";
|
|
146
|
+
}) => Index<Names<K>, N>;
|
|
147
|
+
export { pairingAnswer } from "./account.ts";
|
|
148
|
+
/** Opens this member's database (RFC 0009, "Open and close"). */
|
|
149
|
+
/** Field operations on sets and many links (RFC 0009, "Field operations per field type"). */
|
|
150
|
+
export { add, open, remove } from "./db.ts";
|
|
151
|
+
/** The one error class the SDK throws (RFC 0009, "Errors"). */
|
|
152
|
+
export { NcError as Error } from "./error.ts";
|
|
153
|
+
export { invitation } from "./members.ts";
|
package/dist/nc.js
ADDED
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
// The schema functions of RFC 0005 (docs/rfc/0005-schema-and-model-lock.md),
|
|
2
|
+
// as far as `ncdb model build` needs them: a developer declares the model
|
|
3
|
+
// with them, and `ncdb model build` reads the description that `model`
|
|
4
|
+
// keeps under a hidden key and turns it into model.lock.json. The rules of
|
|
5
|
+
// the model (names, personal fields, indexes, the additive-change rule) are
|
|
6
|
+
// checked by the core when it builds the lock, not here, so that the build
|
|
7
|
+
// and the device check apply the same rules.
|
|
8
|
+
//
|
|
9
|
+
// Only `nc` and its members are public names; the interfaces below are not
|
|
10
|
+
// exported, so an app cannot name them. Each type carries a brand (a key it
|
|
11
|
+
// is never given at run time), so a collection, a name and an index cannot be
|
|
12
|
+
// passed for one another. A field's brands also carry what it reads as and
|
|
13
|
+
// whether it is deprecated, and a collection's carry its fields, which is
|
|
14
|
+
// what `Infer` reads.
|
|
15
|
+
import { makeQuery } from "./query.js";
|
|
16
|
+
import * as texts from "./texts.js";
|
|
17
|
+
/** The key under which `model` keeps the function that describes the model for `ncdb model build`. */
|
|
18
|
+
const DESCRIBE = Symbol.for("nocentraldb.model.describe");
|
|
19
|
+
const fieldStates = new WeakMap();
|
|
20
|
+
const collectionStates = new WeakMap();
|
|
21
|
+
const indexStates = new WeakMap();
|
|
22
|
+
const names = new WeakSet();
|
|
23
|
+
/** The field with this state; each modifier returns a new field. */
|
|
24
|
+
const field = (state) => {
|
|
25
|
+
const made = {
|
|
26
|
+
personal: ({ person }) => field({ ...state, person }),
|
|
27
|
+
describe: (text) => field({ ...state, description: text }),
|
|
28
|
+
deprecated: (reason) => field({ ...state, deprecated: reason }),
|
|
29
|
+
};
|
|
30
|
+
fieldStates.set(made, state);
|
|
31
|
+
return made;
|
|
32
|
+
};
|
|
33
|
+
/** The reference with this state: a field without `personal` (RFC 0005, "References into another space"). */
|
|
34
|
+
const reference = (state) => {
|
|
35
|
+
const made = {
|
|
36
|
+
describe: (text) => reference({ ...state, description: text }),
|
|
37
|
+
deprecated: (reason) => reference({ ...state, deprecated: reason }),
|
|
38
|
+
};
|
|
39
|
+
fieldStates.set(made, state);
|
|
40
|
+
return made;
|
|
41
|
+
};
|
|
42
|
+
const basic = (type, options) => field({
|
|
43
|
+
spec: options === undefined
|
|
44
|
+
? { kind: "basic", type }
|
|
45
|
+
: { kind: "basic", type, options: [...options] },
|
|
46
|
+
});
|
|
47
|
+
const targets = (target) => typeof target === "string" ? [target] : [...target];
|
|
48
|
+
/** Declares the model: the collections, by name. */
|
|
49
|
+
export function model(collections) {
|
|
50
|
+
const declared = { ...collections };
|
|
51
|
+
Object.defineProperty(declared, DESCRIBE, {
|
|
52
|
+
value: () => describeModel(declared),
|
|
53
|
+
enumerable: false,
|
|
54
|
+
});
|
|
55
|
+
return declared;
|
|
56
|
+
}
|
|
57
|
+
/** Declares a collection: its fields by name, and its computed fields, views and indexes. */
|
|
58
|
+
export function collection(fields, options = {}) {
|
|
59
|
+
return makeCollection({
|
|
60
|
+
fields: { ...fields },
|
|
61
|
+
computed: { ...options.computed },
|
|
62
|
+
views: { ...options.views },
|
|
63
|
+
indexes: { ...options.indexes },
|
|
64
|
+
});
|
|
65
|
+
}
|
|
66
|
+
/** The collection with this state; `deprecated` returns a new collection. */
|
|
67
|
+
const makeCollection = (state) => {
|
|
68
|
+
const made = {
|
|
69
|
+
deprecated: (reason) => makeCollection({ ...state, deprecated: reason }),
|
|
70
|
+
};
|
|
71
|
+
made.indexes = Object.fromEntries(Object.keys(state.indexes).map((name) => [name, makeQuery(made, name)]));
|
|
72
|
+
collectionStates.set(made, state);
|
|
73
|
+
return made;
|
|
74
|
+
};
|
|
75
|
+
/** A string, basic value. */
|
|
76
|
+
export const string = () => basic("ncdb/string");
|
|
77
|
+
/** A signed 64-bit integer, basic value. The app reads and writes it as a `number`, a safe integer (RFC 0005, "Types for the app"). */
|
|
78
|
+
export const int = () => basic("ncdb/int");
|
|
79
|
+
/** A binary64 number, basic value. */
|
|
80
|
+
export const float = () => basic("ncdb/float");
|
|
81
|
+
/** A boolean, basic value. */
|
|
82
|
+
export const boolean = () => basic("ncdb/boolean");
|
|
83
|
+
/** A choice from a fixed list of options, basic value. */
|
|
84
|
+
export const oneOf = (options) => basic("ncdb/choice", options);
|
|
85
|
+
/** A set of basic values. */
|
|
86
|
+
export const set = (element) => field({ spec: { kind: "set", of: element } });
|
|
87
|
+
/** A link to one object, in one collection or in one of several. */
|
|
88
|
+
export const link = (target) => field({
|
|
89
|
+
spec: { kind: "link", type: "ncdb/link", targets: targets(target) },
|
|
90
|
+
});
|
|
91
|
+
/** Links to many objects, in one collection or in several. */
|
|
92
|
+
export const links = (target) => field({
|
|
93
|
+
spec: { kind: "link", type: "ncdb/links", targets: targets(target) },
|
|
94
|
+
});
|
|
95
|
+
/** A reference to one object, which may live in another space, in one collection or in one of several (RFC 0005, "References into another space"). */
|
|
96
|
+
export const ref = (target) => reference({
|
|
97
|
+
spec: { kind: "link", type: "ncdb/ref", targets: targets(target) },
|
|
98
|
+
});
|
|
99
|
+
/** Rich text: reserved, its field type belongs to a later RFC. */
|
|
100
|
+
export const richText = () => field({ spec: { kind: "reserved", name: "nc.richText" } });
|
|
101
|
+
/** A stream: reserved, its field type belongs to a later RFC. */
|
|
102
|
+
export const stream = () => field({ spec: { kind: "reserved", name: "nc.stream" } });
|
|
103
|
+
const name = () => {
|
|
104
|
+
const made = {};
|
|
105
|
+
names.add(made);
|
|
106
|
+
return made;
|
|
107
|
+
};
|
|
108
|
+
/** A computed function: named now, its arguments belong to the computed-fields RFC. */
|
|
109
|
+
export const reach = (..._args) => name();
|
|
110
|
+
/** A view: named now, its arguments belong to the computed-fields RFC. */
|
|
111
|
+
export const view = (..._args) => name();
|
|
112
|
+
/** Declares an index: fields in index order, each ascending unless it says otherwise, how many leading fields a query fixes with equality (`equal`, 0 by default), and with `scope: "space"` an index that runs in one space at a time instead of across every space of the member. */
|
|
113
|
+
export const index = (fields, options = {}) => {
|
|
114
|
+
const made = {};
|
|
115
|
+
indexStates.set(made, {
|
|
116
|
+
fields: fields.map((entry) => typeof entry === "string"
|
|
117
|
+
? { field: entry, direction: "asc" }
|
|
118
|
+
: { field: entry.field, direction: entry.direction }),
|
|
119
|
+
equal: options.equal ?? 0,
|
|
120
|
+
...(options.scope === undefined ? {} : { scope: options.scope }),
|
|
121
|
+
});
|
|
122
|
+
return made;
|
|
123
|
+
};
|
|
124
|
+
/** The model as `ncdb model build` reads it (the core's `Draft`). */
|
|
125
|
+
const describeModel = (collections) => {
|
|
126
|
+
const described = {};
|
|
127
|
+
for (const [name, declared] of Object.entries(collections)) {
|
|
128
|
+
const state = collectionStates.get(declared);
|
|
129
|
+
if (state === undefined) {
|
|
130
|
+
throw new Error(texts.notACollection(name));
|
|
131
|
+
}
|
|
132
|
+
described[name] = describeCollection(name, state);
|
|
133
|
+
}
|
|
134
|
+
return { collections: described, plugins: {} };
|
|
135
|
+
};
|
|
136
|
+
const describeCollection = (name, state) => {
|
|
137
|
+
const fields = {};
|
|
138
|
+
for (const [fieldName, declared] of Object.entries(state.fields)) {
|
|
139
|
+
fields[fieldName] = describeField(`${name}.${fieldName}`, declared);
|
|
140
|
+
}
|
|
141
|
+
const named = (place, notOne) => Object.entries(place).map(([key, value]) => {
|
|
142
|
+
if (!names.has(value)) {
|
|
143
|
+
throw new Error(notOne(name, key));
|
|
144
|
+
}
|
|
145
|
+
return key;
|
|
146
|
+
});
|
|
147
|
+
const indexes = {};
|
|
148
|
+
for (const [key, value] of Object.entries(state.indexes)) {
|
|
149
|
+
const declared = indexStates.get(value);
|
|
150
|
+
if (declared === undefined) {
|
|
151
|
+
throw new Error(texts.notAnIndex(name, key));
|
|
152
|
+
}
|
|
153
|
+
indexes[key] = declared;
|
|
154
|
+
}
|
|
155
|
+
return {
|
|
156
|
+
...(state.deprecated === undefined ? {} : { deprecated: state.deprecated }),
|
|
157
|
+
fields,
|
|
158
|
+
computed: named(state.computed, (collection, key) => texts.notAComputedField(collection, key)),
|
|
159
|
+
views: named(state.views, (collection, key) => texts.notAView(collection, key)),
|
|
160
|
+
indexes,
|
|
161
|
+
};
|
|
162
|
+
};
|
|
163
|
+
const describeField = (path, declared) => {
|
|
164
|
+
const state = fieldStates.get(declared);
|
|
165
|
+
if (state === undefined) {
|
|
166
|
+
throw new Error(texts.notAField(path));
|
|
167
|
+
}
|
|
168
|
+
const { spec } = state;
|
|
169
|
+
const described = {
|
|
170
|
+
...describeType(path, spec),
|
|
171
|
+
rule: 1,
|
|
172
|
+
};
|
|
173
|
+
if (state.person !== undefined)
|
|
174
|
+
described.personal = { person: state.person };
|
|
175
|
+
if (state.description !== undefined)
|
|
176
|
+
described.description = state.description;
|
|
177
|
+
if (state.deprecated !== undefined)
|
|
178
|
+
described.deprecated = state.deprecated;
|
|
179
|
+
return described;
|
|
180
|
+
};
|
|
181
|
+
const describeType = (path, spec) => {
|
|
182
|
+
switch (spec.kind) {
|
|
183
|
+
case "basic":
|
|
184
|
+
return spec.options === undefined
|
|
185
|
+
? { type: spec.type }
|
|
186
|
+
: { type: spec.type, options: spec.options };
|
|
187
|
+
case "link":
|
|
188
|
+
return { type: spec.type, targets: spec.targets };
|
|
189
|
+
case "reserved":
|
|
190
|
+
throw new Error(texts.reservedFieldType(path, spec.name));
|
|
191
|
+
case "set": {
|
|
192
|
+
const element = fieldStates.get(spec.of);
|
|
193
|
+
if (element === undefined || element.spec.kind !== "basic") {
|
|
194
|
+
throw new Error(texts.setElementNotBasic(path));
|
|
195
|
+
}
|
|
196
|
+
if (element.person !== undefined ||
|
|
197
|
+
element.description !== undefined ||
|
|
198
|
+
element.deprecated !== undefined) {
|
|
199
|
+
throw new Error(texts.setElementModified(path));
|
|
200
|
+
}
|
|
201
|
+
return { type: "ncdb/set", of: describeType(path, element.spec) };
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
};
|
|
205
|
+
export { pairingAnswer } from "./account.js";
|
|
206
|
+
/** Opens this member's database (RFC 0009, "Open and close"). */
|
|
207
|
+
/** Field operations on sets and many links (RFC 0009, "Field operations per field type"). */
|
|
208
|
+
export { add, open, remove } from "./db.js";
|
|
209
|
+
/** The one error class the SDK throws (RFC 0009, "Errors"). */
|
|
210
|
+
export { NcError as Error } from "./error.js";
|
|
211
|
+
export { invitation } from "./members.js";
|
package/dist/query.d.ts
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/** What a query asks: the collection handle, the index, and the page. */
|
|
2
|
+
export type QueryState = {
|
|
3
|
+
collection: object;
|
|
4
|
+
index: string;
|
|
5
|
+
equal?: unknown[];
|
|
6
|
+
take?: number;
|
|
7
|
+
after?: Cursor;
|
|
8
|
+
};
|
|
9
|
+
/** The query of the first page of the index `index` of `collection`. */
|
|
10
|
+
export declare const makeQuery: (collection: object, index: string) => object;
|
|
11
|
+
/** What `query` asks; `undefined` for an object that is no query. */
|
|
12
|
+
export declare const queryState: (made: object) => QueryState | undefined;
|
|
13
|
+
/** Where the page after another starts: a handle the core holds, of the database `db`. It prints as `[redacted]`. */
|
|
14
|
+
export declare class Cursor {
|
|
15
|
+
#private;
|
|
16
|
+
constructor(db: object, handle: number);
|
|
17
|
+
/** The core's handle, when the cursor belongs to `db`. */
|
|
18
|
+
handleIn(db: object): number | undefined;
|
|
19
|
+
toString(): string;
|
|
20
|
+
toJSON(): string;
|
|
21
|
+
}
|
package/dist/query.js
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
// The runtime of queries and cursors (RFC 0009, "Queries and indexes";
|
|
2
|
+
// NOC-176 slice 2). A query is an immutable builder on a collection handle
|
|
3
|
+
// and an index name; a cursor is an opaque handle of the position the core
|
|
4
|
+
// keeps in the worker, tied to the database that made it, because a
|
|
5
|
+
// cursor holds plaintext field values and never leaves the device (RFC
|
|
6
|
+
// 0006, "Ordered pages"). Internal: the package's entry does not reach
|
|
7
|
+
// this module, and the app sees only the types `Query` and `Page`.
|
|
8
|
+
const queries = new WeakMap();
|
|
9
|
+
/** A query of the index `index` of `collection`, from `state` on. */
|
|
10
|
+
const query = (state) => {
|
|
11
|
+
const made = {
|
|
12
|
+
equal: (...values) => query({ ...state, equal: values }),
|
|
13
|
+
take: (n) => query({ ...state, take: n }),
|
|
14
|
+
after: (cursor) => query({ ...state, after: cursor }),
|
|
15
|
+
};
|
|
16
|
+
queries.set(made, state);
|
|
17
|
+
return made;
|
|
18
|
+
};
|
|
19
|
+
/** The query of the first page of the index `index` of `collection`. */
|
|
20
|
+
export const makeQuery = (collection, index) => query({ collection, index });
|
|
21
|
+
/** What `query` asks; `undefined` for an object that is no query. */
|
|
22
|
+
export const queryState = (made) => queries.get(made);
|
|
23
|
+
const REDACTED = "[redacted]";
|
|
24
|
+
/** Where the page after another starts: a handle the core holds, of the database `db`. It prints as `[redacted]`. */
|
|
25
|
+
export class Cursor {
|
|
26
|
+
#db;
|
|
27
|
+
#handle;
|
|
28
|
+
constructor(db, handle) {
|
|
29
|
+
this.#db = db;
|
|
30
|
+
this.#handle = handle;
|
|
31
|
+
}
|
|
32
|
+
/** The core's handle, when the cursor belongs to `db`. */
|
|
33
|
+
handleIn(db) {
|
|
34
|
+
return this.#db === db ? this.#handle : undefined;
|
|
35
|
+
}
|
|
36
|
+
toString() {
|
|
37
|
+
return REDACTED;
|
|
38
|
+
}
|
|
39
|
+
toJSON() {
|
|
40
|
+
return REDACTED;
|
|
41
|
+
}
|
|
42
|
+
[Symbol.for("nodejs.util.inspect.custom")]() {
|
|
43
|
+
return `Cursor(${REDACTED})`;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { SpaceStatus } from "./status.ts";
|
|
2
|
+
import type { SyncStatus } from "./sync.ts";
|
|
3
|
+
/** The sync status the core sent, with the relay that serves the database. */
|
|
4
|
+
export declare const syncStatusOf: (raw: unknown, relay: string | undefined) => SyncStatus;
|
|
5
|
+
/** A space's status the core sent. */
|
|
6
|
+
export declare const spaceStatusOf: (raw: unknown) => SpaceStatus;
|
|
7
|
+
/** Gives `value` to each listener; one that throws loses it, and the others still get it. */
|
|
8
|
+
export declare const notify: <T>(listeners: Set<(value: T) => void>, value: T) => void;
|
package/dist/reports.js
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
// The sync status and a space's status as the core sends them (NOC-176
|
|
2
|
+
// slice 4; RFC 0009, "Sync and status"), read into the SDK's types, and the
|
|
3
|
+
// listeners that follow them. connect.ts keeps the newest of each.
|
|
4
|
+
/** The sync status the core sent, with the relay that serves the database. */
|
|
5
|
+
export const syncStatusOf = (raw, relay) => {
|
|
6
|
+
const given = (raw ?? {});
|
|
7
|
+
return {
|
|
8
|
+
connection: (given.connection ?? "none"),
|
|
9
|
+
...(relay === undefined ? {} : { relay }),
|
|
10
|
+
unconfirmed: Number(given.unconfirmed ?? 0),
|
|
11
|
+
refused: Number(given.refused ?? 0),
|
|
12
|
+
epochChanged: given.epochChanged === true,
|
|
13
|
+
...(typeof given.error === "string" ? { error: given.error } : {}),
|
|
14
|
+
};
|
|
15
|
+
};
|
|
16
|
+
/** A space's status the core sent. */
|
|
17
|
+
export const spaceStatusOf = (raw) => {
|
|
18
|
+
const given = (raw ?? {});
|
|
19
|
+
const list = (value) => (Array.isArray(value) ? value : []);
|
|
20
|
+
const counts = (value) => Object.fromEntries(Object.entries((value ?? {})).map(([reason, count]) => [reason, Number(count)]));
|
|
21
|
+
return {
|
|
22
|
+
role: (given.role ?? "removed"),
|
|
23
|
+
initialSyncComplete: given.initialSyncComplete === true,
|
|
24
|
+
behind: Number(given.behind ?? 0),
|
|
25
|
+
gaps: list(given.gaps),
|
|
26
|
+
parked: counts(given.parked),
|
|
27
|
+
...(typeof given.newestModel === "number"
|
|
28
|
+
? { newestModel: given.newestModel }
|
|
29
|
+
: {}),
|
|
30
|
+
rejected: counts(given.rejected),
|
|
31
|
+
refused: list(given.refused),
|
|
32
|
+
lostGrants: list(given.lostGrants),
|
|
33
|
+
equivocations: list(given.equivocations),
|
|
34
|
+
exposed: given.exposed === true,
|
|
35
|
+
waitingForKey: given.waitingForKey === true,
|
|
36
|
+
badPersonKeyRecords: list(given.badPersonKeyRecords),
|
|
37
|
+
provisionalErasures: list(given.provisionalErasures).map((erasure) => ({ ...erasure, age: Number(erasure.age) })),
|
|
38
|
+
};
|
|
39
|
+
};
|
|
40
|
+
/** Gives `value` to each listener; one that throws loses it, and the others still get it. */
|
|
41
|
+
export const notify = (listeners, value) => {
|
|
42
|
+
for (const listener of [...listeners]) {
|
|
43
|
+
try {
|
|
44
|
+
listener(value);
|
|
45
|
+
}
|
|
46
|
+
catch {
|
|
47
|
+
// The app's bug; it does not stop the other listeners.
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
};
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { Cbor } from "./cbor.ts";
|
|
2
|
+
type Ask = (call: string, args: Record<string, unknown>) => Promise<Cbor>;
|
|
3
|
+
/** The follower of the space list of one database. */
|
|
4
|
+
export declare const spaceListOf: <E>(ask: Ask) => {
|
|
5
|
+
/** Calls `listener` with the list at once, or once the core answered the first follow, and with each new list. */
|
|
6
|
+
subscribe(listener: (spaces: E[]) => void): () => void;
|
|
7
|
+
/** A `spaces` event of the core. */
|
|
8
|
+
changed: (raw: unknown) => void;
|
|
9
|
+
/** Another tab took the database over (NOC-177): its core follows no list yet. */
|
|
10
|
+
reopened(): void;
|
|
11
|
+
/** The database closed: no listener hears anything more. */
|
|
12
|
+
clear(): void;
|
|
13
|
+
};
|
|
14
|
+
export {};
|