cojson 0.2.3 → 0.3.0

package/src/group.ts

@@ -1,4 +1,4 @@
-import { CoID, CoValue, AnyCoValue } from "./coValue.js";
+import { CoID, CoValue, AnyCoValue, AnyCoMap, AnyCoList } from "./coValue.js";
 import { CoMap } from "./coValues/coMap.js";
 import { JsonObject, JsonValue } from "./jsonValue.js";
 import {
@@ -15,12 +15,11 @@ import {
     agentSecretFromSecretSeed,
     getAgentID,
 } from "./crypto.js";
-import { LocalNode } from "./node.js";
+import { LocalNode } from "./localNode.js";
 import { AgentID, SessionID, isAgentID } from "./ids.js";
 import { AccountID, GeneralizedControlledAccount, Profile } from "./account.js";
 import { Role } from "./permissions.js";
 import { base58 } from "@scure/base";
-import { CoList } from "./coValues/coList.js";
 import {
     BinaryCoStream,
     BinaryCoStreamMeta,
@@ -28,9 +27,9 @@ import {
 } from "./coValues/coStream.js";
 
 export type GroupContent = {
-    profile: CoID<Profile> | null;
+    profile?: CoID<Profile> | null;
     [key: AccountID | AgentID]: Role;
-    readKey: KeyID;
+    readKey?: KeyID;
     [revelationFor: `${KeyID}_for_${AccountID | AgentID}`]: Sealed<KeySecret>;
     [oldKeyForNewKey: `${KeyID}_for_${KeyID}`]: Encrypted<
         KeySecret,
@@ -70,6 +69,7 @@ export function expectGroupContent(
  *  ```
  * */
 export class Group {
+    /** @category 4. Underlying CoMap */
     underlyingMap: CoMap<GroupContent, JsonObject | null>;
     /** @internal */
     node: LocalNode;
@@ -83,12 +83,20 @@ export class Group {
         this.node = node;
     }
 
-    /** Returns the `CoID` of the `Group`. */
+    /**
+     * Returns the `CoID` of the `Group`.
+     *
+     * @category 4. Underlying CoMap
+     */
     get id(): CoID<CoMap<GroupContent, JsonObject | null>> {
         return this.underlyingMap.id;
     }
 
-    /** Returns the current role of a given account. */
+    /**
+     * Returns the current role of a given account.
+     *
+     * @category 1. Role reading
+     */
     roleOf(accountID: AccountID): Role | undefined {
         return this.roleOfInternal(accountID);
     }
@@ -98,20 +106,28 @@ export class Group {
         return this.underlyingMap.get(accountID);
     }
 
-    /** Returns the role of the current account in the group. */
+    /**
+     * Returns the role of the current account in the group.
+     *
+     * @category 1. Role reading
+     */
     myRole(): Role | undefined {
         return this.roleOfInternal(this.node.account.id);
     }
 
-    /** Directly grants a new member a role in the group. The current account must be an
-     * admin to be able to do so. Throws otherwise. */
+    /**
+     * Directly grants a new member a role in the group. The current account must be an
+     * admin to be able to do so. Throws otherwise.
+     *
+     * @category 2. Role changing
+     */
     addMember(accountID: AccountID, role: Role) {
         this.addMemberInternal(accountID, role);
     }
 
     /** @internal */
     addMemberInternal(accountID: AccountID | AgentID, role: Role) {
-        this.underlyingMap = this.underlyingMap.edit((map) => {
+        this.underlyingMap = this.underlyingMap.mutate((map) => {
             const currentReadKey = this.underlyingMap.core.getCurrentReadKey();
 
             if (!currentReadKey.secret) {
@@ -131,15 +147,15 @@ export class Group {
 
             map.set(
                 `${currentReadKey.id}_for_${accountID}`,
-                seal(
-                    currentReadKey.secret,
-                    this.underlyingMap.core.node.account.currentSealerSecret(),
-                    getAgentSealerID(agent),
-                    {
+                seal({
+                    message: currentReadKey.secret,
+                    from: this.underlyingMap.core.node.account.currentSealerSecret(),
+                    to: getAgentSealerID(agent),
+                    nOnceMaterial: {
                         in: this.underlyingMap.core.id,
                         tx: this.underlyingMap.core.nextTransactionID(),
-                    }
-                ),
+                    },
+                }),
                 "trusting"
             );
         });
@@ -177,7 +193,7 @@ export class Group {
 
         const newReadKey = newRandomKeySecret();
 
-        this.underlyingMap = this.underlyingMap.edit((map) => {
+        this.underlyingMap = this.underlyingMap.mutate((map) => {
             for (const readerID of currentlyPermittedReaders) {
                 const reader = this.node.resolveAccountAgent(
                     readerID,
@@ -186,15 +202,15 @@ export class Group {
 
                 map.set(
                     `${newReadKey.id}_for_${readerID}`,
-                    seal(
-                        newReadKey.secret,
-                        this.underlyingMap.core.node.account.currentSealerSecret(),
-                        getAgentSealerID(reader),
-                        {
+                    seal({
+                        message: newReadKey.secret,
+                        from: this.underlyingMap.core.node.account.currentSealerSecret(),
+                        to: getAgentSealerID(reader),
+                        nOnceMaterial: {
                             in: this.underlyingMap.core.id,
                             tx: this.underlyingMap.core.nextTransactionID(),
-                        }
-                    ),
+                        },
+                    }),
                     "trusting"
                 );
             }
@@ -212,23 +228,33 @@ export class Group {
         });
     }
 
-    /** Strips the specified member of all roles (preventing future writes in
+    /**
+     * Strips the specified member of all roles (preventing future writes in
      *  the group and owned values) and rotates the read encryption key for that group
-     * (preventing reads of new content in the group and owned values) */
+     * (preventing reads of new content in the group and owned values)
+     *
+     * @category 2. Role changing
+     */
     removeMember(accountID: AccountID) {
         this.removeMemberInternal(accountID);
     }
 
     /** @internal */
     removeMemberInternal(accountID: AccountID | AgentID) {
-        this.underlyingMap = this.underlyingMap.edit((map) => {
+        this.underlyingMap = this.underlyingMap.mutate((map) => {
             map.set(accountID, "revoked", "trusting");
         });
 
         this.rotateReadKey();
     }
 
-    /** Creates an invite for new members to indirectly join the group, allowing them to grant themselves the specified role with the InviteSecret (a string starting with "inviteSecret_") - use `LocalNode.acceptInvite()` for this purpose. */
+    /**
+     * Creates an invite for new members to indirectly join the group,
+     * allowing them to grant themselves the specified role with the InviteSecret
+     * (a string starting with "inviteSecret_") - use `LocalNode.acceptInvite()` for this purpose.
+     *
+     * @category 2. Role changing
+     */
     createInvite(role: "reader" | "writer" | "admin"): InviteSecret {
         const secretSeed = newRandomSecretSeed();
 
@@ -240,22 +266,20 @@ export class Group {
         return inviteSecretFromSecretSeed(secretSeed);
     }
 
-    /** Creates a new `CoMap` within this group, with the specified specialized
-     *  `CoMap` type `M` and optional static metadata. */
-    createMap<
-        M extends CoMap<
-            { [key: string]: JsonValue | AnyCoValue | undefined },
-            JsonObject | null
-        >
-    >(
-        init?: M extends CoMap<infer M, infer _Meta>
-            ? {
-                  [K in keyof M]: M[K] extends AnyCoValue
-                      ? M[K] | CoID<M[K]>
-                      : M[K];
-              }
-            : never,
-        meta?: M["meta"]
+    /**
+     * Creates a new `CoMap` within this group, with the specified specialized
+     * `CoMap` type `M` and optional static metadata.
+     *
+     * @category 3. Value creation
+     */
+    createMap<M extends AnyCoMap>(
+        init?: {
+            [K in keyof M["_shape"]]: M["_shape"][K] extends AnyCoValue
+                ? M["_shape"][K] | CoID<M["_shape"][K]>
+                : M["_shape"][K];
+        },
+        meta?: M["meta"],
+        initPrivacy: "trusting" | "private" = "trusting"
     ): M {
         let map = this.node
             .createCoValue({
@@ -270,23 +294,26 @@ export class Group {
             .getCurrentContent() as M;
 
         if (init) {
-            map = map.edit((editable) => {
-                for (const [key, value] of Object.entries(init)) {
-                    editable.set(key, value);
-                }
-            });
+            for (const [key, value] of Object.entries(init)) {
+                map = map.set(key, value, initPrivacy);
+            }
         }
 
         return map;
     }
 
-    /** Creates a new `CoList` within this group, with the specified specialized
-     * `CoList` type `L` and optional static metadata. */
-    createList<L extends CoList<JsonValue | CoValue, JsonObject | null>>(
-        init?: L extends CoList<infer I, infer _Meta>
-            ? (I extends CoValue ? CoID<I> | I : I)[]
-            : never,
-        meta?: L["meta"]
+    /**
+     * Creates a new `CoList` within this group, with the specified specialized
+     * `CoList` type `L` and optional static metadata.
+     *
+     * @category 3. Value creation
+     */
+    createList<L extends AnyCoList>(
+        init?: (L["_item"] extends CoValue
+            ? CoID<L["_item"]> | L["_item"]
+            : L["_item"])[],
+        meta?: L["meta"],
+        initPrivacy: "trusting" | "private" = "trusting"
     ): L {
         let list = this.node
             .createCoValue({
@@ -301,16 +328,15 @@ export class Group {
             .getCurrentContent() as L;
 
         if (init) {
-            list = list.edit((editable) => {
-                for (const item of init) {
-                    editable.push(item);
-                }
-            });
+            for (const item of init) {
+                list = list.append(item, undefined, initPrivacy);
+            }
         }
 
         return list;
     }
 
+    /** @category 3. Value creation */
     createStream<C extends CoStream<JsonValue | CoValue, JsonObject | null>>(
         meta?: C["meta"]
     ): C {
@@ -327,6 +353,7 @@ export class Group {
             .getCurrentContent() as C;
     }
 
+    /** @category 3. Value creation */
     createBinaryStream<C extends BinaryCoStream<BinaryCoStreamMeta>>(
         meta: C["meta"] = { type: "binary" }
     ): C {

package/src/index.ts

@@ -1,13 +1,17 @@
-import { CoValueCore, newRandomSessionID, MAX_RECOMMENDED_TX_SIZE } from "./coValueCore.js";
-import { LocalNode } from "./node.js";
+import {
+    CoValueCore,
+    newRandomSessionID,
+    MAX_RECOMMENDED_TX_SIZE,
+} from "./coValueCore.js";
+import { LocalNode } from "./localNode.js";
 import type { CoValue } from "./coValue.js";
-import { CoMap, WriteableCoMap } from "./coValues/coMap.js";
-import { CoList, WriteableCoList } from "./coValues/coList.js";
+import { CoMap, MutableCoMap } from "./coValues/coMap.js";
+import { CoList, MutableCoList } from "./coValues/coList.js";
 import {
     CoStream,
-    WriteableCoStream,
+    MutableCoStream,
     BinaryCoStream,
-    WriteableBinaryCoStream,
+    MutableBinaryCoStream,
 } from "./coValues/coStream.js";
 import {
     agentSecretFromBytes,
@@ -18,7 +22,7 @@ import {
     agentSecretFromSecretSeed,
     secretSeedLength,
     shortHashLength,
-    cryptoReady
+    cryptoReady,
 } from "./crypto.js";
 import { connectedPeers } from "./streamUtils.js";
 import { AnonymousControlledAccount, ControlledAccount } from "./account.js";
@@ -30,7 +34,13 @@ import { parseJSON } from "./jsonStringify.js";
 import type { SessionID, AgentID } from "./ids.js";
 import type { CoID, AnyCoValue } from "./coValue.js";
 import type { Queried } from "./queries.js";
-import type { BinaryStreamInfo, BinaryCoStreamMeta } from "./coValues/coStream.js";
+import type { QueriedCoStream } from "./queriedCoValues/queriedCoStream.js";
+import type { QueriedCoList } from "./queriedCoValues/queriedCoList.js";
+import type { QueriedCoMap } from "./queriedCoValues/queriedCoMap.js";
+import type {
+    BinaryStreamInfo,
+    BinaryCoStreamMeta,
+} from "./coValues/coStream.js";
 import type { JsonValue } from "./jsonValue.js";
 import type { SyncMessage, Peer } from "./sync.js";
 import type { AgentSecret } from "./crypto.js";
@@ -57,38 +67,39 @@ export const cojsonInternals = {
     expectGroupContent,
     base64URLtoBytes,
     bytesToBase64url,
-    parseJSON
+    parseJSON,
 };
 
 export {
     LocalNode,
     Group,
     CoMap,
-    WriteableCoMap,
+    MutableCoMap,
     CoList,
-    WriteableCoList,
+    MutableCoList,
     CoStream,
-    WriteableCoStream,
+    MutableCoStream,
     BinaryCoStream,
-    WriteableBinaryCoStream,
-    CoValueCore,
-    AnonymousControlledAccount,
-    ControlledAccount,
-    cryptoReady as cojsonReady,
-    MAX_RECOMMENDED_TX_SIZE
-};
-
-export type {
-    Value,
-    JsonValue,
+    MutableBinaryCoStream,
     CoValue,
-    AnyCoValue,
     CoID,
+    AnyCoValue,
     Queried,
+    QueriedCoMap,
+    QueriedCoList,
+    QueriedCoStream,
     AccountID,
     Account,
     Profile,
     SessionID,
+    Media,
+    CoValueCore,
+    AnonymousControlledAccount,
+    ControlledAccount,
+    cryptoReady as cojsonReady,
+    MAX_RECOMMENDED_TX_SIZE,
+    Value,
+    JsonValue,
     Peer,
     BinaryStreamInfo,
     BinaryCoStreamMeta,
@@ -96,7 +107,6 @@ export type {
     AgentSecret,
     InviteSecret,
     SyncMessage,
-    Media
 };
 
 // eslint-disable-next-line @typescript-eslint/no-namespace

package/src/{node.ts → localNode.ts}

@@ -35,7 +35,6 @@ import {
     AccountID,
     Profile,
     AccountContent,
-    Account,
 } from "./account.js";
 import { CoMap } from "./coValues/coMap.js";
 import { CoValue } from "./index.js";
@@ -54,11 +53,14 @@ const { localNode } = useJazz();
 export class LocalNode {
     /** @internal */
     coValues: { [key: RawCoID]: CoValueState } = {};
-    /** @internal */
+    /** @category 3. Low-level */
     account: GeneralizedControlledAccount;
+    /** @category 3. Low-level */
     currentSessionID: SessionID;
-    sync = new SyncManager(this);
+    /** @category 3. Low-level */
+    syncManager = new SyncManager(this);
 
+    /** @category 3. Low-level */
     constructor(
         account: GeneralizedControlledAccount,
         currentSessionID: SessionID
@@ -67,6 +69,7 @@ export class LocalNode {
         this.currentSessionID = currentSessionID;
     }
 
+    /** @category 2. Node Creation */
     static withNewlyCreatedAccount(
         name: string,
         initialAgentSecret = newRandomAgentSecret()
@@ -97,6 +100,7 @@ export class LocalNode {
         };
     }
 
+    /** @category 2. Node Creation */
     static async withLoadedAccount(
         accountID: AccountID,
         accountSecret: AgentSecret,
@@ -111,7 +115,7 @@ export class LocalNode {
         const accountPromise = loadingNode.load(accountID);
 
         for (const peer of peersToLoadFrom) {
-            loadingNode.sync.addPeer(peer);
+            loadingNode.syncManager.addPeer(peer);
         }
 
         const account = await accountPromise;
@@ -121,8 +125,8 @@ export class LocalNode {
             new ControlledAccount(accountSecret, account, loadingNode),
             sessionID
         );
-        node.sync = loadingNode.sync;
-        node.sync.local = node;
+        node.syncManager = loadingNode.syncManager;
+        node.syncManager.local = node;
 
         return node;
     }
@@ -132,7 +136,7 @@ export class LocalNode {
         const coValue = new CoValueCore(header, this);
         this.coValues[coValue.id] = { state: "loaded", coValue: coValue };
 
-        void this.sync.syncCoValue(coValue);
+        void this.syncManager.syncCoValue(coValue);
 
         return coValue;
     }
@@ -145,7 +149,7 @@ export class LocalNode {
 
             this.coValues[id] = entry;
 
-            this.sync.loadFromPeers(id);
+            this.syncManager.loadFromPeers(id);
         }
         if (entry.state === "loaded") {
             return Promise.resolve(entry.coValue);
@@ -157,33 +161,42 @@ export class LocalNode {
      * Loads a CoValue's content, syncing from peers as necessary and resolving the returned
      * promise once a first version has been loaded. See `coValue.subscribe()` and `node.useTelepathicData()`
      * for listening to subsequent updates to the CoValue.
+     *
+     * @category 3. Low-level
      */
     async load<T extends CoValue>(id: CoID<T>): Promise<T> {
         return (await this.loadCoValue(id)).getCurrentContent() as T;
     }
 
-    subscribe<T extends CoValue>(id: CoID<T>, callback: (update: T) => void): () => void {
+    /** @category 3. Low-level */
+    subscribe<T extends CoValue>(
+        id: CoID<T>,
+        callback: (update: T) => void
+    ): () => void {
         let stopped = false;
         let unsubscribe!: () => void;
 
         console.log("Subscribing to " + id);
 
-        this.load(id).then((coValue) => {
-            if (stopped) {
-                return;
-            }
-            unsubscribe = coValue.subscribe(callback);
-        }).catch((e) => {
-            console.error("Error subscribing to ", id, e);
-        });
+        this.load(id)
+            .then((coValue) => {
+                if (stopped) {
+                    return;
+                }
+                unsubscribe = coValue.subscribe(callback);
+            })
+            .catch((e) => {
+                console.error("Error subscribing to ", id, e);
+            });
 
         return () => {
             console.log("Unsubscribing from " + id);
             stopped = true;
             unsubscribe?.();
-        }
+        };
     }
 
+    /** @category 1. High-level */
     query<T extends CoValue>(
         id: CoID<T>,
         callback: (update: Queried<T> | undefined) => void
@@ -191,22 +204,7 @@ export class LocalNode {
         return query(id, this, callback);
     }
 
-    /**
-     * Loads a profile associated with an account. `Profile` is at least a `CoMap<{string: name}>`,
-     * but might contain other, app-specific properties.
-     */
-    async loadProfile(id: AccountID): Promise<Profile> {
-        const account = await this.load<Account>(id);
-        const profileID = account.get("profile");
-
-        if (!profileID) {
-            throw new Error(`Account ${id} has no profile`);
-        }
-        return (
-            await this.loadCoValue(profileID)
-        ).getCurrentContent() as Profile;
-    }
-
+    /** @category 1. High-level */
     async acceptInvite<T extends CoValue>(
         groupOrOwnedValueID: CoID<T>,
         inviteSecret: InviteSecret
@@ -327,11 +325,12 @@ export class LocalNode {
         name: string,
         agentSecret = newRandomAgentSecret()
     ): ControlledAccount {
+        const accountAgentID = getAgentID(agentSecret);
         const account = this.createCoValue(
             accountHeaderForInitialAgentSecret(agentSecret)
         ).testWithDifferentAccount(
             new AnonymousControlledAccount(agentSecret),
-            newRandomSessionID(getAgentID(agentSecret))
+            newRandomSessionID(accountAgentID)
         );
 
         const accountAsGroup = new Group(
@@ -339,22 +338,22 @@ export class LocalNode {
             account.node
         );
 
-        accountAsGroup.underlyingMap.edit((editable) => {
-            editable.set(getAgentID(agentSecret), "admin", "trusting");
+        accountAsGroup.underlyingMap.mutate((editable) => {
+            editable.set(accountAgentID, "admin", "trusting");
 
             const readKey = newRandomKeySecret();
 
             editable.set(
-                `${readKey.id}_for_${getAgentID(agentSecret)}`,
-                seal(
-                    readKey.secret,
-                    getAgentSealerSecret(agentSecret),
-                    getAgentSealerID(getAgentID(agentSecret)),
-                    {
+                `${readKey.id}_for_${accountAgentID}`,
+                seal({
+                    message: readKey.secret,
+                    from: getAgentSealerSecret(agentSecret),
+                    to: getAgentSealerID(accountAgentID),
+                    nOnceMaterial: {
                         in: account.id,
                         tx: account.nextTransactionID(),
-                    }
-                ),
+                    },
+                }),
                 "trusting"
             );
 
@@ -367,17 +366,15 @@ export class LocalNode {
             account.node
         );
 
-        let profile = accountAsGroup.createMap<Profile>(undefined, {
-            type: "profile",
-        });
-
-        profile = profile.edit((editable) => {
-            editable.set("name", name, "trusting");
-        });
+        const profile = accountAsGroup.createMap<Profile>(
+            { name },
+            {
+                type: "profile",
+            },
+            "trusting"
+        );
 
-        accountAsGroup.underlyingMap.edit((editable) => {
-            editable.set("profile", profile.id, "trusting");
-        });
+        accountAsGroup.underlyingMap.set("profile", profile.id, "trusting");
 
         const accountOnThisNode = this.expectCoValueLoaded(account.id);
 
@@ -427,7 +424,10 @@ export class LocalNode {
         ).getCurrentAgentID();
     }
 
-    /** Creates a new group (with the current account as the group's first admin). */
+    /**
+     * Creates a new group (with the current account as the group's first admin).
+     * @category 1. High-level
+     */
     createGroup(): Group {
         const groupCoValue = this.createCoValue({
             type: "comap",
@@ -438,22 +438,22 @@ export class LocalNode {
 
         let groupContent = expectGroupContent(groupCoValue.getCurrentContent());
 
-        groupContent = groupContent.edit((editable) => {
+        groupContent = groupContent.mutate((editable) => {
             editable.set(this.account.id, "admin", "trusting");
 
             const readKey = newRandomKeySecret();
 
             editable.set(
                 `${readKey.id}_for_${this.account.id}`,
-                seal(
-                    readKey.secret,
-                    this.account.currentSealerSecret(),
-                    this.account.currentSealerID(),
-                    {
+                seal({
+                    message: readKey.secret,
+                    from: this.account.currentSealerSecret(),
+                    to: this.account.currentSealerID(),
+                    nOnceMaterial: {
                         in: groupCoValue.id,
                         tx: groupCoValue.nextTransactionID(),
-                    }
-                ),
+                    },
+                }),
                 "trusting"
             );