jazz-tools 0.7.0-alpha.30 → 0.7.0-alpha.32

package/src/coValues/coList.ts

@@ -8,9 +8,10 @@ import type {
     SchemaFor,
     ID,
     RefEncoded,
-    SubclassedConstructor,
+    ClassOf,
     UnavailableError,
     IfCo,
+    UnCo,
 } from "../internal.js";
 import {
     Account,
@@ -27,11 +28,13 @@ import {
 } from "../internal.js";
 import { encodeSync, decodeSync } from "@effect/schema/Schema";
 
+/** @category CoValues */
 export class CoList<Item = any>
     extends Array<Item>
     implements CoValue<"CoList", RawCoList>
 {
     static Of<Item>(item: IfCo<Item, Item>): typeof CoList<Item> {
+        // TODO: cache superclass for item class
         return class CoListOf extends CoList<Item> {
             [co.items] = item;
         };
@@ -64,6 +67,7 @@ export class CoList<Item = any>
             : Group.fromRaw(this._raw.group);
     }
 
+    /** @category Content */
     get _refs(): {
         [idx: number]: NonNullable<Item> extends CoValue
             ? Ref<NonNullable<Item>>
@@ -107,21 +111,16 @@ export class CoList<Item = any>
         return Array;
     }
 
-    constructor(_init: undefined, options: { fromRaw: RawCoList });
-    constructor(init: Item[], options: { owner: Account | Group });
     constructor(
-        init: Item[] | undefined,
-        options?: { owner: Account | Group } | { fromRaw: RawCoList }
+        options:
+            | { init: Item[]; owner: Account | Group }
+            | { fromRaw: RawCoList }
     ) {
         super();
 
-        if (!options) {
-            throw new Error("Must provide options");
-        }
-
-        if (init && "owner" in options) {
+        if ("owner" in options) {
             this[InitValues] = {
-                init,
+                init: options.init,
                 owner: options.owner,
             };
         } else if ("fromRaw" in options) {
@@ -137,6 +136,14 @@ export class CoList<Item = any>
         return new Proxy(this, CoListProxyHandler as ProxyHandler<this>);
     }
 
+    static create<L extends CoList>(
+        this: ClassOf<L>,
+        items: UnCo<L[number]>[],
+        options: {owner: Account | Group}
+    ) {
+        return new this({ init: items, owner: options.owner });
+    }
+
     push(...items: Item[]): number;
     /** @private For exact type compatibility with Array superclass */
     push(...items: Item[]): number;
@@ -235,29 +242,29 @@ export class CoList<Item = any>
     }
 
     static fromRaw<V extends CoList>(
-        this: SubclassedConstructor<V> & typeof CoList,
+        this: ClassOf<V> & typeof CoList,
         raw: RawCoList
     ) {
-        return new this(undefined, { fromRaw: raw });
+        return new this({ fromRaw: raw });
     }
 
     static loadEf = CoValueBase.loadEf as unknown as <V extends CoValue>(
-        this: SubclassedConstructor<V>,
+        this: ClassOf<V>,
         id: ID<V>
     ) => Effect.Effect<V, UnavailableError, AccountCtx>;
     static load = CoValueBase.load as unknown as <V extends CoValue>(
-        this: SubclassedConstructor<V>,
+        this: ClassOf<V>,
         id: ID<V>,
         options: { as: Account | Group }
     ) => Promise<V | undefined>;
     static subscribeEf = CoValueBase.subscribeEf as unknown as <
         V extends CoValue,
     >(
-        this: SubclassedConstructor<V>,
+        this: ClassOf<V>,
         id: ID<V>
     ) => Stream.Stream<V, UnavailableError, AccountCtx>;
     static subscribe = CoValueBase.subscribe as unknown as <V extends CoValue>(
-        this: SubclassedConstructor<V>,
+        this: ClassOf<V>,
         id: ID<V>,
         options: { as: Account | Group },
         onUpdate: (value: V) => void

package/src/coValues/coMap.ts

@@ -9,6 +9,7 @@ import type {
     RefEncoded,
     IfCo,
     RefIfCoValue,
+    ClassOf,
 } from "../internal.js";
 import {
     Account,
@@ -23,11 +24,6 @@ import {
     isRefEncoded,
 } from "../internal.js";
 
-type DefaultFields = {
-    [key: string]: any;
-    [ItemsSym]?: any;
-};
-
 type CoMapEdit<V> = {
     value?: V;
     ref?: RefIfCoValue<V>;
@@ -40,24 +36,72 @@ type InitValuesFor<C extends CoMap> = {
     owner: Account | Group;
 };
 
-export class CoMap<Fields extends object = DefaultFields>
-    extends CoValueBase
-    implements CoValue<"CoMap", RawCoMap>
-{
+/**
+ * CoMaps are collaborative versions of plain objects, mapping string-like keys to values.
+ *
+ * @categoryDescription Declaration
+ * Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.
+ *
+ * ```ts
+ * import { co, CoMap } from "jazz-tools";
+ *
+ * class Person extends CoMap {
+ *   name = co.string;
+ *   age = co.number;
+ *   pet = co.ref(Animal);
+ * }
+ * ```
+ *
+ * @categoryDescription Content
+ * You can access properties you declare on a `CoMap` (using `co`) as if they were normal properties on a plain object, using dot notation, `Object.keys()`, etc.
+ *
+ * ```ts
+ * person.name;
+ * person["age"];
+ * person.age = 42;
+ * person.pet?.name;
+ * Object.keys(person);
+ * // => ["name", "age", "pet"]
+ * ```
+ *
+ * @category CoValues
+ *  */
+export class CoMap extends CoValueBase implements CoValue<"CoMap", RawCoMap> {
+    /**
+     * The ID of this `CoMap`
+     * @category Content */
     declare id: ID<this>;
+    /** @category Type Helpers */
     declare _type: "CoMap";
     static {
         this.prototype._type = "CoMap";
     }
+    /** @category Internals */
     declare _raw: RawCoMap;
 
+    /** @internal */
     static _schema: any;
+    /** @internal */
     get _schema() {
         return (this.constructor as typeof CoMap)._schema as {
             [key: string]: Schema;
         } & { [ItemsSym]?: Schema };
     }
 
+    /**
+     * If property `prop` is a `co.ref(...)`, you can use `coMaps._refs.prop` to access
+     * the `Ref` instead of the potentially loaded/null value.
+     * This allows you to always get the ID or load the value manually.
+     *
+     * @example
+     * ```ts
+     * person._refs.pet.id; // => ID<Animal>
+     * person._refs.pet.value;
+     * // => Animal | undefined
+     * const pet = await person._refs.pet.load();
+     * ```
+     *
+     * @category Content */
     get _refs(): {
         [Key in CoKeys<this>]: IfCo<this[Key], RefIfCoValue<this[Key]>>;
     } {
@@ -80,6 +124,7 @@ export class CoMap<Fields extends object = DefaultFields>
         ) as any;
     }
 
+    /** @category Collaboration */
     get _edits() {
         return new Proxy(this, {
             get(target, key) {
@@ -124,26 +169,23 @@ export class CoMap<Fields extends object = DefaultFields>
         };
     }
 
+    /** @internal */
     get _loadedAs() {
         return Account.fromNode(this._raw.core.node);
     }
 
+    /** @internal */
     [InitValues]?: any;
 
-    constructor(_init: undefined, options: { fromRaw: RawCoMap });
+    /** @internal */
     constructor(
-        init: Simplify<CoMapInit<Fields>>,
-        options: { owner: Account | Group }
-    );
-    constructor(
-        init: Simplify<CoMapInit<Fields>> | undefined,
-        options: { owner: Account | Group } | { fromRaw: RawCoMap }
+        options: { fromRaw: RawCoMap } | { init: any; owner: Account | Group }
     ) {
         super();
 
-        if (init && "owner" in options) {
+        if ("owner" in options) {
             this[InitValues] = {
-                init,
+                init: options.init,
                 owner: options.owner,
             } as InitValuesFor<this>;
         } else if ("fromRaw" in options) {
@@ -161,6 +203,15 @@ export class CoMap<Fields extends object = DefaultFields>
         return new Proxy(this, CoMapProxyHandler as ProxyHandler<this>);
     }
 
+    /** @category Creation */
+    static create<M extends CoMap>(
+        this: ClassOf<M>,
+        init: Simplify<CoMapInit<M>>,
+        options: { owner: Account | Group }
+    ) {
+        return new this({ init, owner: options.owner });
+    }
+
     toJSON() {
         const jsonedFields = this._raw.keys().map((key) => {
             const tKey = key as CoKeys<this>;
@@ -188,6 +239,7 @@ export class CoMap<Fields extends object = DefaultFields>
         return this.toJSON();
     }
 
+    /** @internal */
     rawFromInit<Fields extends object = Record<string, any>>(
         init: Simplify<CoMapInit<Fields>> | undefined,
         owner: Account | Group
@@ -222,9 +274,10 @@ export class CoMap<Fields extends object = DefaultFields>
         return rawOwner.createMap(rawInit);
     }
 
+    /** @category Declaration */
     static Record<Value>(value: IfCo<Value, Value>) {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
-        class RecordLikeCoMap extends CoMap<RecordLikeCoMap> {
+        class RecordLikeCoMap extends CoMap {
             [ItemsSym] = value;
         }
         // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
@@ -236,7 +289,7 @@ export class CoMap<Fields extends object = DefaultFields>
 
 export type CoKeys<Fields extends object> = Exclude<
     keyof Fields & string,
-    keyof CoMap<Record<string, never>>
+    keyof CoMap
 >;
 
 export type CoMapInit<Fields extends object> = {

package/src/coValues/coStream.ts

@@ -8,7 +8,7 @@ import type {
     RawCoStream,
     SessionID,
 } from "cojson";
-import { cojsonInternals } from "cojson";
+import { MAX_RECOMMENDED_TX_SIZE, cojsonInternals } from "cojson";
 import type {
     CoValue,
     Schema,
@@ -17,6 +17,8 @@ import type {
     ID,
     Me,
     IfCo,
+    ClassOf,
+    UnCo,
 } from "../internal.js";
 import {
     ItemsSym,
@@ -43,13 +45,12 @@ export type SingleCoStreamEntry<Item> = {
     tx: CojsonInternalTypes.TransactionID;
 };
 
+/** @category CoValues */
 export class CoStream<Item = any>
     extends CoValueBase
     implements CoValue<"CoStream", RawCoStream>
 {
-    static Of<Item>(
-        item: IfCo<Item, Item>
-    ): typeof CoStream<Item> {
+    static Of<Item>(item: IfCo<Item, Item>): typeof CoStream<Item> {
         return class CoStreamOf extends CoStream<Item> {
             [co.items] = item;
         };
@@ -85,11 +86,10 @@ export class CoStream<Item = any>
 
     [InitValues]?: any;
 
-    constructor(_init: undefined, options: { fromRaw: RawCoStream });
-    constructor(init: Item[], options: { owner: Account | Group });
     constructor(
-        init: Item[] | undefined,
-        options: { owner: Account | Group } | { fromRaw: RawCoStream }
+        options:
+            | { init: Item[]; owner: Account | Group }
+            | { fromRaw: RawCoStream }
     ) {
         super();
 
@@ -103,7 +103,7 @@ export class CoStream<Item = any>
             });
         } else {
             this[InitValues] = {
-                init,
+                init: options.init,
                 owner: options.owner,
             };
         }
@@ -111,6 +111,14 @@ export class CoStream<Item = any>
         return new Proxy(this, CoStreamProxyHandler as ProxyHandler<this>);
     }
 
+    static create<S extends CoStream>(
+        this: ClassOf<S>,
+        init: S extends CoStream<infer Item> ? UnCo<Item>[] : never,
+        options: { owner: Account | Group }
+    ) {
+        return new this({ init, owner: options.owner });
+    }
+
     push(...items: Item[]) {
         for (const item of items) {
             this.pushItem(item);
@@ -123,9 +131,7 @@ export class CoStream<Item = any>
         if (itemDescriptor === "json") {
             this._raw.push(item as JsonValue);
         } else if ("encoded" in itemDescriptor) {
-            this._raw.push(
-                encodeSync(itemDescriptor.encoded)(item)
-            );
+            this._raw.push(encodeSync(itemDescriptor.encoded)(item));
         } else if (isRefEncoded(itemDescriptor)) {
             this._raw.push((item as unknown as CoValue).id);
         }
@@ -192,9 +198,7 @@ function entryFromRawEntry<Item>(
                     ? (CoValue & Item) | null
                     : Item;
             } else if ("encoded" in itemField) {
-                return decodeSync(itemField.encoded)(
-                    rawEntry.value
-                );
+                return decodeSync(itemField.encoded)(rawEntry.value);
             } else if (isRefEncoded(itemField)) {
                 return this.ref?.accessFrom(
                     accessFrom
@@ -292,7 +296,10 @@ export const CoStreamProxyHandler: ProxyHandler<CoStream> = {
 
             return entry;
         } else if (key === "perSession") {
-            return new Proxy({}, CoStreamPerSessionProxyHandler(target, receiver));
+            return new Proxy(
+                {},
+                CoStreamPerSessionProxyHandler(target, receiver)
+            );
         } else {
             return Reflect.get(target, key, receiver);
         }
@@ -350,7 +357,10 @@ export const CoStreamProxyHandler: ProxyHandler<CoStream> = {
     },
 };
 
-const CoStreamPerSessionProxyHandler = (innerTarget: CoStream, accessFrom: CoStream): ProxyHandler<Record<string, never>> => ({
+const CoStreamPerSessionProxyHandler = (
+    innerTarget: CoStream,
+    accessFrom: CoStream
+): ProxyHandler<Record<string, never>> => ({
     get(_target, key, receiver) {
         if (typeof key === "string" && key.includes("session")) {
             const sessionID = key as SessionID;
@@ -411,6 +421,7 @@ const CoStreamPerSessionProxyHandler = (innerTarget: CoStream, accessFrom: CoStr
     },
 });
 
+/** @category CoValues */
 export class BinaryCoStream
     extends CoValueBase
     implements CoValue<"BinaryCoStream", RawBinaryCoStream>
@@ -420,7 +431,6 @@ export class BinaryCoStream
     declare _raw: RawBinaryCoStream;
 
     constructor(
-        _init: [] | undefined,
         options:
             | {
                   owner: Account | Group;
@@ -449,6 +459,13 @@ export class BinaryCoStream
         });
     }
 
+    static create<S extends BinaryCoStream>(
+        this: ClassOf<S>,
+        options: { owner: Account | Group }
+    ) {
+        return new this(options);
+    }
+
     getChunks(options?: {
         allowUnfinished?: boolean;
     }):
@@ -469,6 +486,81 @@ export class BinaryCoStream
         this._raw.endBinaryStream();
     }
 
+    toBlob(options?: { allowUnfinished?: boolean }): Blob | undefined {
+        const chunks = this.getChunks({
+            allowUnfinished: options?.allowUnfinished,
+        });
+
+        if (!chunks) {
+            return undefined;
+        }
+
+        return new Blob(chunks.chunks, { type: chunks.mimeType });
+    }
+
+    static async loadAsBlob(
+        id: ID<BinaryCoStream>,
+        options: {
+            as: Account & Me;
+            allowUnfinished?: boolean;
+            onProgress?: (progress: number) => void;
+        }
+    ): Promise<Blob | undefined> {
+        const stream = await this.load(id, {
+            as: options.as,
+            onProgress: options.onProgress,
+        });
+
+        return stream?.toBlob({
+            allowUnfinished: options.allowUnfinished,
+        });
+    }
+
+    static async createFromBlob(
+        blob: Blob | File,
+        options: {
+            owner: Group | Account;
+            onProgress?: (progress: number) => void;
+        }
+    ): Promise<BinaryCoStream> {
+        const stream = this.create({ owner: options.owner });
+
+        const start = Date.now();
+
+        const data = new Uint8Array(await blob.arrayBuffer());
+        stream.start({
+            mimeType: blob.type,
+            totalSizeBytes: blob.size,
+            fileName: blob instanceof File ? blob.name : undefined,
+        });
+        const chunkSize = MAX_RECOMMENDED_TX_SIZE;
+
+        let lastProgressUpdate = Date.now();
+
+        for (let idx = 0; idx < data.length; idx += chunkSize) {
+            stream.push(data.slice(idx, idx + chunkSize));
+
+            if (Date.now() - lastProgressUpdate > 100) {
+                options.onProgress?.(idx / data.length);
+                lastProgressUpdate = Date.now();
+            }
+
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+        stream.end();
+        const end = Date.now();
+
+        console.debug(
+            "Finished creating binary stream in",
+            (end - start) / 1000,
+            "s - Throughput in MB/s",
+            (1000 * (blob.size / (end - start))) / (1024 * 1024)
+        );
+        options.onProgress?.(1);
+
+        return stream;
+    }
+
     toJSON() {
         return {
             id: this.id,

package/src/coValues/extensions/imageDef.ts

@@ -5,7 +5,8 @@ import {
     subscriptionsScopes,
 } from "../../internal.js";
 
-export class ImageDefinition extends CoMap<ImageDefinition> {
+/** @category Media */
+export class ImageDefinition extends CoMap {
     originalSize = co.json<[number, number]>();
     placeholderDataURL? = co.string;
 

package/src/coValues/group.ts

@@ -2,9 +2,9 @@ import type { AccountID, Everyone, RawGroup, Role } from "cojson";
 import type {
     CoValue,
     ID,
-    JsonEncoded,
     RefEncoded,
     Schema,
+    ClassOf,
 } from "../internal.js";
 import {
     Account,
@@ -17,34 +17,13 @@ import {
     MembersSym,
 } from "../internal.js";
 
-export class Profile extends CoMap<{ name: co<string> }> {
+/** @category Identity & Permissions */
+export class Profile extends CoMap {
     name = co.string;
 }
 
-type GroupSchema<Def extends Group> = {
-    profile: NonNullable<Def["profile"]> extends CoValue
-        ? RefEncoded<NonNullable<Def["profile"]>>
-        : JsonEncoded;
-    root: NonNullable<Def["root"]> extends CoValue
-        ? RefEncoded<NonNullable<Def["root"]>>
-        : JsonEncoded;
-    [MembersSym]: RefEncoded<NonNullable<Def[MembersSym]>>;
-};
-
-export class Group<
-        Def extends {
-            profile: Profile | null;
-            root: CoMap | null;
-            [MembersSym]: Account | null;
-        } = {
-            profile: Profile | null;
-            root: CoMap | null;
-            [MembersSym]: Account | null;
-        },
-    >
-    extends CoValueBase
-    implements CoValue<"Group", RawGroup>
-{
+/** @category Identity & Permissions */
+export class Group extends CoValueBase implements CoValue<"Group", RawGroup> {
     declare id: ID<this>;
     declare _type: "Group";
     static {
@@ -53,7 +32,11 @@ export class Group<
     declare _raw: RawGroup;
 
     static _schema: any;
-    get _schema(): GroupSchema<this> {
+    get _schema(): {
+        profile: Schema;
+        root: Schema;
+        [MembersSym]: RefEncoded<Account>;
+    } {
         return (this.constructor as typeof Group)._schema;
     }
     static {
@@ -67,19 +50,16 @@ export class Group<
         });
     }
 
-    declare profile: Def["profile"] | null;
-    declare root: Def["root"] | null;
-    declare [MembersSym]: Def[MembersSym] | null;
+    declare profile: Profile | null;
+    declare root: CoMap | null;
+    declare [MembersSym]: Account | null;
 
-    get _refs(): {
-        profile: Def["profile"] extends Profile ? Ref<Def["profile"]> : never;
-        root: Def["root"] extends CoMap ? Ref<Def["root"]> : never;
-    } {
+    get _refs() {
         const profileID = this._raw.get("profile") as unknown as
-            | ID<NonNullable<Def["profile"]>>
+            | ID<NonNullable<this["profile"]>>
             | undefined;
         const rootID = this._raw.get("root") as unknown as
-            | ID<NonNullable<Def["root"]>>
+            | ID<NonNullable<this["root"]>>
             | undefined;
         return {
             profile:
@@ -88,33 +68,32 @@ export class Group<
                     profileID,
                     this._loadedAs,
                     this._schema.profile as RefEncoded<
-                        NonNullable<Def["profile"]>
+                        NonNullable<this["profile"]>
                     >
-                ) as any),
+                ) as any as this["profile"] extends Profile
+                    ? Ref<this["profile"]>
+                    : never),
             root:
                 rootID &&
                 (new Ref(
                     rootID,
                     this._loadedAs,
-                    this._schema.root as RefEncoded<NonNullable<Def["root"]>>
-                ) as any),
+                    this._schema.root as RefEncoded<NonNullable<this["root"]>>
+                ) as any as this["root"] extends CoMap
+                    ? Ref<this["root"]>
+                    : never),
         };
     }
 
-    constructor(options: { owner: Account | Group });
-    constructor(init: any, options: { fromRaw: RawGroup });
-    constructor(init: undefined, options: { owner: Account | Group });
-    constructor(
-        init: undefined | { owner: Account | Group },
-        options?: { fromRaw: RawGroup } | { owner: Account | Group }
-    ) {
+    /** @deprecated Don't use constructor directly, use .create */
+    constructor(options: { fromRaw: RawGroup } | { owner: Account | Group }) {
         super();
         let raw: RawGroup;
 
         if (options && "fromRaw" in options) {
             raw = options.fromRaw;
         } else {
-            const initOwner = options?.owner || init?.owner;
+            const initOwner = options.owner;
             if (!initOwner) throw new Error("No owner provided");
             if (
                 initOwner instanceof Account &&
@@ -143,6 +122,13 @@ export class Group<
         );
     }
 
+    static create<G extends Group>(
+        this: ClassOf<G>,
+        options: { owner: Account }
+    ) {
+        return new this(options);
+    }
+
     myRole(): Role | undefined {
         return this._raw.myRole();
     }