cojson 0.1.8 → 0.1.10

package/src/{contentTypes → coValues}/coList.ts

@@ -1,9 +1,9 @@
 import { JsonObject, JsonValue } from "../jsonValue.js";
-import { CoID } from "../contentType.js";
-import { CoValue, accountOrAgentIDfromSessionID } from "../coValue.js";
+import { CoID, ReadableCoValue, WriteableCoValue } from "../coValue.js";
+import { CoValueCore, accountOrAgentIDfromSessionID } from "../coValueCore.js";
 import { SessionID, TransactionID } from "../ids.js";
-import { AccountID, Group } from "../index.js";
-import { isAccountID } from "../account.js";
+import { Group } from "../group.js";
+import { AccountID, isAccountID } from "../account.js";
 
 type OpID = TransactionID & { changeIdx: number };
 
@@ -39,15 +39,17 @@ type DeletionEntry = {
     deletionID: OpID;
 } & DeletionOpPayload;
 
-export class CoList<
-    T extends JsonValue,
-    Meta extends JsonObject | null = null
-> {
+export class CoList<T extends JsonValue, Meta extends JsonObject | null = null>
+    implements ReadableCoValue
+{
     id: CoID<CoList<T, Meta>>;
     type = "colist" as const;
-    coValue: CoValue;
+    core: CoValueCore;
+    /** @internal */
     afterStart: OpID[];
+    /** @internal */
     beforeEnd: OpID[];
+    /** @internal */
     insertions: {
         [sessionID: SessionID]: {
             [txIdx: number]: {
@@ -55,6 +57,7 @@ export class CoList<
             };
         };
     };
+    /** @internal */
     deletionsByInsertion: {
         [deletedSessionID: SessionID]: {
             [deletedTxIdx: number]: {
@@ -63,9 +66,10 @@ export class CoList<
         };
     };
 
-    constructor(coValue: CoValue) {
-        this.id = coValue.id as CoID<CoList<T, Meta>>;
-        this.coValue = coValue;
+    /** @internal */
+    constructor(core: CoValueCore) {
+        this.id = core.id as CoID<CoList<T, Meta>>;
+        this.core = core;
         this.afterStart = [];
         this.beforeEnd = [];
         this.insertions = {};
@@ -74,15 +78,15 @@ export class CoList<
         this.fillOpsFromCoValue();
     }
 
-
     get meta(): Meta {
-        return this.coValue.header.meta as Meta;
+        return this.core.header.meta as Meta;
     }
 
     get group(): Group {
-        return this.coValue.getGroup();
+        return this.core.getGroup();
     }
 
+    /** @internal */
     protected fillOpsFromCoValue() {
         this.insertions = {};
         this.deletionsByInsertion = {};
@@ -93,7 +97,7 @@ export class CoList<
             txID,
             changes,
             madeAt,
-        } of this.coValue.getValidSortedTransactions()) {
+        } of this.core.getValidSortedTransactions()) {
             for (const [changeIdx, changeUntyped] of changes.entries()) {
                 const change = changeUntyped as ListOpPayload<T>;
 
@@ -195,6 +199,20 @@ export class CoList<
         }
     }
 
+    /** Get the item currently at `idx`. */
+    get(idx: number): T | undefined {
+        const entry = this.entries()[idx];
+        if (!entry) {
+            return undefined;
+        }
+        return entry.value;
+    }
+
+    /** Returns the current items in the CoList as an array. */
+    asArray(): T[] {
+        return this.entries().map((entry) => entry.value);
+    }
+
     entries(): { value: T; madeAt: number; opID: OpID }[] {
         const arr: { value: T; madeAt: number; opID: OpID }[] = [];
         for (const opID of this.afterStart) {
@@ -206,6 +224,7 @@ export class CoList<
         return arr;
     }
 
+    /** @internal */
     private fillArrayFromOpID(
         opID: OpID,
         arr: { value: T; madeAt: number; opID: OpID }[]
@@ -234,6 +253,7 @@ export class CoList<
         }
     }
 
+    /** Returns the accountID of the account that inserted value at the given index. */
     whoInserted(idx: number): AccountID | undefined {
         const entry = this.entries()[idx];
         if (!entry) {
@@ -247,19 +267,16 @@ export class CoList<
         }
     }
 
+    /** Returns the current items in the CoList as an array. (alias of `asArray`) */
     toJSON(): T[] {
         return this.asArray();
     }
 
-    asArray(): T[] {
-        return this.entries().map((entry) => entry.value);
-    }
-
     map<U>(mapper: (value: T, idx: number) => U): U[] {
         return this.entries().map((entry, idx) => mapper(entry.value, idx));
     }
 
-    filter<U extends T>(predicate: (value: T, idx: number) => value is U): U[]
+    filter<U extends T>(predicate: (value: T, idx: number) => value is U): U[];
     filter(predicate: (value: T, idx: number) => boolean): T[] {
         return this.entries()
             .filter((entry, idx) => predicate(entry.value, idx))
@@ -271,31 +288,45 @@ export class CoList<
         initialValue: U
     ): U {
         return this.entries().reduce(
-            (accumulator, entry, idx) =>
-                reducer(accumulator, entry.value, idx),
+            (accumulator, entry, idx) => reducer(accumulator, entry.value, idx),
             initialValue
         );
     }
 
+    subscribe(listener: (coMap: CoList<T, Meta>) => void): () => void {
+        return this.core.subscribe((content) => {
+            listener(content as CoList<T, Meta>);
+        });
+    }
+
     edit(
         changer: (editable: WriteableCoList<T, Meta>) => void
     ): CoList<T, Meta> {
-        const editable = new WriteableCoList<T, Meta>(this.coValue);
+        const editable = new WriteableCoList<T, Meta>(this.core);
         changer(editable);
-        return new CoList(this.coValue);
-    }
-
-    subscribe(listener: (coMap: CoList<T, Meta>) => void): () => void {
-        return this.coValue.subscribe((content) => {
-            listener(content as CoList<T, Meta>);
-        });
+        return new CoList(this.core);
     }
 }
 
 export class WriteableCoList<
-    T extends JsonValue,
-    Meta extends JsonObject | null = null
-> extends CoList<T, Meta> {
+        T extends JsonValue,
+        Meta extends JsonObject | null = null
+    >
+    extends CoList<T, Meta>
+    implements WriteableCoValue
+{
+    /** @internal */
+    edit(
+        _changer: (editable: WriteableCoList<T, Meta>) => void
+    ): CoList<T, Meta> {
+        throw new Error("Already editing.");
+    }
+
+    /** Appends a new item after index `after`.
+     *
+     * If `privacy` is `"private"` **(default)**, both `value` is encrypted in the transaction, only readable by other members of the group this `CoList` belongs to. Not even sync servers can see the content in plaintext.
+     *
+     * If `privacy` is `"trusting"`, both `value` is stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers. */
     append(
         after: number,
         value: T,
@@ -315,7 +346,7 @@ export class WriteableCoList<
             }
             opIDBefore = "start";
         }
-        this.coValue.makeTransaction(
+        this.core.makeTransaction(
             [
                 {
                     op: "app",
@@ -329,12 +360,28 @@ export class WriteableCoList<
         this.fillOpsFromCoValue();
     }
 
+    /** Pushes a new item to the end of the list.
+     *
+     * If `privacy` is `"private"` **(default)**, both `value` is encrypted in the transaction, only readable by other members of the group this `CoList` belongs to. Not even sync servers can see the content in plaintext.
+     *
+     * If `privacy` is `"trusting"`, both `value` is stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers. */
     push(value: T, privacy: "private" | "trusting" = "private"): void {
         // TODO: optimize
         const entries = this.entries();
-        this.append(entries.length > 0 ? entries.length - 1 : 0, value, privacy);
+        this.append(
+            entries.length > 0 ? entries.length - 1 : 0,
+            value,
+            privacy
+        );
     }
 
+    /**
+     * Prepends a new item before index `before`.
+     *
+     * If `privacy` is `"private"` **(default)**, both `value` is encrypted in the transaction, only readable by other members of the group this `CoList` belongs to. Not even sync servers can see the content in plaintext.
+     *
+     * If `privacy` is `"trusting"`, both `value` is stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers.
+     */
     prepend(
         before: number,
         value: T,
@@ -358,7 +405,7 @@ export class WriteableCoList<
             }
             opIDAfter = "end";
         }
-        this.coValue.makeTransaction(
+        this.core.makeTransaction(
             [
                 {
                     op: "pre",
@@ -372,16 +419,18 @@ export class WriteableCoList<
         this.fillOpsFromCoValue();
     }
 
-    delete(
-        at: number,
-        privacy: "private" | "trusting" = "private"
-    ): void {
+    /** Deletes the item at index `at` from the list.
+     *
+     * If `privacy` is `"private"` **(default)**, the fact of this deletion is encrypted in the transaction, only readable by other members of the group this `CoList` belongs to. Not even sync servers can see the content in plaintext.
+     *
+     * If `privacy` is `"trusting"`, the fact of this deletion is stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers. */
+    delete(at: number, privacy: "private" | "trusting" = "private"): void {
         const entries = this.entries();
         const entry = entries[at];
         if (!entry) {
             throw new Error("Invalid index " + at);
         }
-        this.coValue.makeTransaction(
+        this.core.makeTransaction(
             [
                 {
                     op: "del",

package/src/{contentTypes → coValues}/coMap.ts

@@ -1,7 +1,7 @@
 import { JsonObject, JsonValue } from '../jsonValue.js';
 import { TransactionID } from '../ids.js';
-import { CoID } from '../contentType.js';
-import { CoValue, accountOrAgentIDfromSessionID } from '../coValue.js';
+import { CoID, ReadableCoValue, WriteableCoValue } from '../coValue.js';
+import { CoValueCore, accountOrAgentIDfromSessionID } from '../coValueCore.js';
 import { AccountID, isAccountID } from '../account.js';
 import { Group } from '../group.js';
 
@@ -28,37 +28,41 @@ export type MapM<M extends { [key: string]: JsonValue; }> = {
     [KK in MapK<M>]: M[KK];
 }
 
+/** A collaborative map with precise shape `M` and optional static metadata `Meta` */
 export class CoMap<
     M extends { [key: string]: JsonValue; },
     Meta extends JsonObject | null = null,
-> {
+> implements ReadableCoValue {
     id: CoID<CoMap<MapM<M>, Meta>>;
-    coValue: CoValue;
     type = "comap" as const;
+    core: CoValueCore;
+    /** @internal */
     ops: {
         [KK in MapK<M>]?: MapOp<KK, M[KK]>[];
     };
 
-    constructor(coValue: CoValue) {
-        this.id = coValue.id as CoID<CoMap<MapM<M>, Meta>>;
-        this.coValue = coValue;
+    /** @internal */
+    constructor(core: CoValueCore) {
+        this.id = core.id as CoID<CoMap<MapM<M>, Meta>>;
+        this.core = core;
         this.ops = {};
 
         this.fillOpsFromCoValue();
     }
 
     get meta(): Meta {
-        return this.coValue.header.meta as Meta;
+        return this.core.header.meta as Meta;
     }
 
     get group(): Group {
-        return this.coValue.getGroup();
+        return this.core.getGroup();
     }
 
+    /** @internal */
     protected fillOpsFromCoValue() {
         this.ops = {};
 
-        for (const { txID, changes, madeAt } of this.coValue.getValidSortedTransactions()) {
+        for (const { txID, changes, madeAt } of this.core.getValidSortedTransactions()) {
             for (const [changeIdx, changeUntyped] of (
                 changes
             ).entries()) {
@@ -82,6 +86,7 @@ export class CoMap<
         return Object.keys(this.ops) as MapK<M>[];
     }
 
+    /** Returns the current value for the given key. */
     get<K extends MapK<M>>(key: K): M[K] | undefined {
         const ops = this.ops[key];
         if (!ops) {
@@ -116,6 +121,7 @@ export class CoMap<
         }
     }
 
+    /** Returns the accountID of the last account to modify the value for the given key. */
     whoEdited<K extends MapK<M>>(key: K): AccountID | undefined {
         const tx  = this.getLastTxID(key);
         if (!tx) {
@@ -187,26 +193,35 @@ export class CoMap<
         return json;
     }
 
-    edit(changer: (editable: WriteableCoMap<M, Meta>) => void): CoMap<M, Meta> {
-        const editable = new WriteableCoMap<M, Meta>(this.coValue);
-        changer(editable);
-        return new CoMap(this.coValue);
-    }
-
     subscribe(listener: (coMap: CoMap<M, Meta>) => void): () => void {
-        return this.coValue.subscribe((content) => {
+        return this.core.subscribe((content) => {
             listener(content as CoMap<M, Meta>);
         });
     }
+
+    edit(changer: (editable: WriteableCoMap<M, Meta>) => void): CoMap<M, Meta> {
+        const editable = new WriteableCoMap<M, Meta>(this.core);
+        changer(editable);
+        return new CoMap(this.core);
+    }
 }
 
 export class WriteableCoMap<
     M extends { [key: string]: JsonValue; },
     Meta extends JsonObject | null = null,
+> extends CoMap<M, Meta> implements WriteableCoValue {
+    /** @internal */
+    edit(_changer: (editable: WriteableCoMap<M, Meta>) => void): CoMap<M, Meta> {
+        throw new Error("Already editing.");
+    }
 
-> extends CoMap<M, Meta> {
+    /** Sets a new value for the given key.
+     *
+     * If `privacy` is `"private"` **(default)**, both `key` and `value` are encrypted in the transaction, only readable by other members of the group this `CoMap` belongs to. Not even sync servers can see the content in plaintext.
+     *
+     * If `privacy` is `"trusting"`, both `key` and `value` are stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers. */
     set<K extends MapK<M>>(key: K, value: M[K], privacy: "private" | "trusting" = "private"): void {
-        this.coValue.makeTransaction([
+        this.core.makeTransaction([
             {
                 op: "set",
                 key,
@@ -217,8 +232,13 @@ export class WriteableCoMap<
         this.fillOpsFromCoValue();
     }
 
+    /** Deletes the value for the given key (setting it to undefined).
+     *
+     * If `privacy` is `"private"` **(default)**, `key` is encrypted in the transaction, only readable by other members of the group this `CoMap` belongs to. Not even sync servers can see the content in plaintext.
+     *
+     * If `privacy` is `"trusting"`, `key` is stored in plaintext in the transaction, visible to everyone who gets a hold of it, including sync servers. */
     delete(key: MapK<M>, privacy: "private" | "trusting" = "private"): void {
-        this.coValue.makeTransaction([
+        this.core.makeTransaction([
             {
                 op: "del",
                 key,

package/src/coValues/coStream.ts

@@ -0,0 +1,249 @@
+import { JsonObject, JsonValue } from "../jsonValue.js";
+import { CoID, ReadableCoValue, WriteableCoValue } from "../coValue.js";
+import { CoValueCore } from "../coValueCore.js";
+import { Group } from "../group.js";
+import { SessionID } from "../ids.js";
+import { base64url } from "@scure/base";
+
+export type BinaryChunkInfo = {
+    mimeType: string;
+    fileName?: string;
+    totalSizeBytes?: number;
+};
+
+export type BinaryStreamStart = {
+    type: "start";
+} & BinaryChunkInfo;
+
+export type BinaryStreamChunk = {
+    type: "chunk";
+    chunk: `U${string}`;
+};
+
+export type BinaryStreamEnd = {
+    type: "end";
+};
+
+export type BinaryCoStreamMeta = JsonObject & { type: "binary" };
+
+export type BinaryStreamItem =
+    | BinaryStreamStart
+    | BinaryStreamChunk
+    | BinaryStreamEnd;
+
+export class CoStream<
+    T extends JsonValue,
+    Meta extends JsonObject | null = null
+> implements ReadableCoValue
+{
+    id: CoID<CoStream<T, Meta>>;
+    type = "costream" as const;
+    core: CoValueCore;
+    items: {
+        [key: SessionID]: T[];
+    };
+
+    constructor(core: CoValueCore) {
+        this.id = core.id as CoID<CoStream<T, Meta>>;
+        this.core = core;
+        this.items = {};
+    }
+
+    get meta(): Meta {
+        return this.core.header.meta as Meta;
+    }
+
+    get group(): Group {
+        return this.core.getGroup();
+    }
+
+    /** @internal */
+    protected fillFromCoValue() {
+        this.items = {};
+
+        for (const {
+            txID,
+            changes,
+        } of this.core.getValidSortedTransactions()) {
+            for (const changeUntyped of changes) {
+                const change = changeUntyped as T;
+                let entries = this.items[txID.sessionID];
+                if (!entries) {
+                    entries = [];
+                    this.items[txID.sessionID] = entries;
+                }
+                entries.push(change);
+            }
+        }
+    }
+
+    getSingleStream(): T[] | undefined {
+        if (Object.keys(this.items).length === 0) {
+            return undefined;
+        } else if (Object.keys(this.items).length !== 1) {
+            throw new Error(
+                "CoStream.getSingleStream() can only be called when there is exactly one stream"
+            );
+        }
+
+        return Object.values(this.items)[0];
+    }
+
+    toJSON(): {
+        [key: SessionID]: T[];
+    } {
+        return this.items;
+    }
+
+    subscribe(listener: (coMap: CoStream<T, Meta>) => void): () => void {
+        return this.core.subscribe((content) => {
+            listener(content as CoStream<T, Meta>);
+        });
+    }
+
+    edit(
+        changer: (editable: WriteableCoStream<T, Meta>) => void
+    ): CoStream<T, Meta> {
+        const editable = new WriteableCoStream<T, Meta>(this.core);
+        changer(editable);
+        return new CoStream(this.core);
+    }
+}
+
+export class BinaryCoStream<
+        Meta extends BinaryCoStreamMeta = { type: "binary" }
+    >
+    extends CoStream<BinaryStreamItem, Meta>
+    implements ReadableCoValue
+{
+    id!: CoID<BinaryCoStream<Meta>>;
+
+    getBinaryChunks():
+        | (BinaryChunkInfo & { chunks: Uint8Array[]; finished: boolean })
+        | undefined {
+        const items = this.getSingleStream();
+
+        if (!items) return;
+
+        const start = items[0];
+
+        if (start?.type !== "start") {
+            console.error("Invalid binary stream start", start);
+            return;
+        }
+
+        const chunks: Uint8Array[] = [];
+
+        for (const item of items.slice(1)) {
+            if (item.type === "end") {
+                return {
+                    mimeType: start.mimeType,
+                    fileName: start.fileName,
+                    totalSizeBytes: start.totalSizeBytes,
+                    chunks,
+                    finished: true,
+                };
+            }
+
+            if (item.type !== "chunk") {
+                console.error("Invalid binary stream chunk", item);
+                return undefined;
+            }
+
+            chunks.push(base64url.decode(item.chunk.slice(1)));
+        }
+
+        return {
+            mimeType: start.mimeType,
+            fileName: start.fileName,
+            totalSizeBytes: start.totalSizeBytes,
+            chunks,
+            finished: false,
+        };
+    }
+
+    edit(
+        changer: (editable: WriteableBinaryCoStream<Meta>) => void
+    ): BinaryCoStream<Meta> {
+        const editable = new WriteableBinaryCoStream<Meta>(this.core);
+        changer(editable);
+        return new BinaryCoStream(this.core);
+    }
+}
+
+export class WriteableCoStream<
+        T extends JsonValue,
+        Meta extends JsonObject | null = null
+    >
+    extends CoStream<T, Meta>
+    implements WriteableCoValue
+{
+    /** @internal */
+    edit(
+        _changer: (editable: WriteableCoStream<T, Meta>) => void
+    ): CoStream<T, Meta> {
+        throw new Error("Already editing.");
+    }
+
+    push(item: T, privacy: "private" | "trusting" = "private") {
+        this.core.makeTransaction([item], privacy);
+        this.fillFromCoValue();
+    }
+}
+
+export class WriteableBinaryCoStream<
+        Meta extends BinaryCoStreamMeta = { type: "binary" }
+    >
+    extends BinaryCoStream<Meta>
+    implements WriteableCoValue
+{
+    /** @internal */
+    edit(
+        _changer: (editable: WriteableBinaryCoStream<Meta>) => void
+    ): BinaryCoStream<Meta> {
+        throw new Error("Already editing.");
+    }
+
+    /** @internal */
+    push(
+        item: BinaryStreamItem,
+        privacy: "private" | "trusting" = "private"
+    ) {
+        WriteableCoStream.prototype.push.call(this, item, privacy);
+    }
+
+    startBinaryStream(
+        settings: BinaryChunkInfo,
+        privacy: "private" | "trusting" = "private"
+    ) {
+        this.push(
+            {
+                type: "start",
+                ...settings,
+            } satisfies BinaryStreamStart,
+            privacy
+        );
+    }
+
+    pushBinaryStreamChunk(
+        chunk: Uint8Array,
+        privacy: "private" | "trusting" = "private"
+    ) {
+        this.push(
+            {
+                type: "chunk",
+                chunk: `U${base64url.encode(chunk)}`,
+            } satisfies BinaryStreamChunk,
+            privacy
+        );
+    }
+
+    endBinaryStream(privacy: "private" | "trusting" = "private") {
+        this.push(
+            {
+                type: "end",
+            } satisfies BinaryStreamEnd,
+            privacy
+        );
+    }
+}

package/src/coValues/static.ts

@@ -0,0 +1,31 @@
+import { JsonObject } from '../jsonValue.js';
+import { CoID, ReadableCoValue } from '../coValue.js';
+import { CoValueCore } from '../coValueCore.js';
+import { Group } from '../index.js';
+
+export class Static<T extends JsonObject> implements ReadableCoValue{
+    id: CoID<Static<T>>;
+    type = "static" as const;
+    core: CoValueCore;
+
+    constructor(core: CoValueCore) {
+        this.id = core.id as CoID<Static<T>>;
+        this.core = core;
+    }
+
+    get meta(): T {
+        return this.core.header.meta as T;
+    }
+
+    get group(): Group {
+        return this.core.getGroup();
+    }
+
+    toJSON(): JsonObject {
+        throw new Error("Method not implemented.");
+    }
+
+    subscribe(_listener: (coMap: Static<T>) => void): () => void {
+        throw new Error("Method not implemented.");
+    }
+}