jazz-tools 0.7.1 → 0.7.6

package/src/coValues/coList.ts

@@ -6,31 +6,69 @@ import type {
     SchemaFor,
     ID,
     RefEncoded,
-    ClassOf,
     UnCo,
     CoValueClass,
+    DepthsIn,
+    DeeplyLoaded,
+    UnavailableError,
+    AccountCtx,
+    CoValueFromRaw,
 } from "../internal.js";
 import {
     Account,
-    CoValueBase,
     Group,
     InitValues,
     ItemsSym,
     Ref,
     SchemaInit,
     co,
+    ensureCoValueLoaded,
     inspect,
     isRefEncoded,
+    loadCoValue,
+    loadCoValueEf,
     makeRefs,
+    subscribeToCoValue,
+    subscribeToCoValueEf,
+    subscribeToExistingCoValue,
 } from "../internal.js";
 import { encodeSync, decodeSync } from "@effect/schema/Schema";
-
-/** @category CoValues */
+import { Effect, Stream } from "effect";
+
+/**
+ * CoLists are collaborative versions of plain arrays.
+ *
+ *  * @categoryDescription Content
+ * You can access items on a `CoList` as if they were normal items on a plain array, using `[]` notation, etc.
+ *
+ * Since `CoList` is a subclass of `Array`, you can use all the normal array methods like `push`, `pop`, `splice`, etc.
+ *
+ * ```ts
+ * colorList[0];
+ * colorList[3] = "yellow";
+ * colorList.push("Kawazaki Green");
+ * colorList.splice(1, 1);
+ * ```
+ *
+ * @category CoValues
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export class CoList<Item = any>
-    extends Array<Item>
-    implements CoValue<"CoList", RawCoList>
-{
+export class CoList<Item = any> extends Array<Item> implements CoValue {
+    /**
+     * Declare a `CoList` by subclassing `CoList.Of(...)` and passing the item schema using `co`.
+     *
+     * @example
+     * ```ts
+     * class ColorList extends CoList.Of(
+     *   co.string
+     * ) {}
+     * class AnimalList extends CoList.Of(
+     *   co.ref(Animal)
+     * ) {}
+     * ```
+     *
+     * @category Declaration
+     */
     static Of<Item>(item: Item): typeof CoList<Item> {
         // TODO: cache superclass for item class
         return class CoListOf extends CoList<Item> {
@@ -38,36 +76,62 @@ export class CoList<Item = any>
         };
     }
 
-    /** @deprecated Use UPPERCASE `CoList.Of` instead! */
+    /**
+     * @ignore
+     * @deprecated Use UPPERCASE `CoList.Of` instead! */
     static of(..._args: never): never {
         throw new Error("Can't use Array.of with CoLists");
     }
 
+    /**
+     * The ID of this `CoList`
+     * @category Content */
     id!: ID<this>;
+    /** @category Type Helpers */
     _type!: "CoList";
     static {
         this.prototype._type = "CoList";
     }
+    /** @category Internals */
     _raw!: RawCoList;
+    /** @category Internals */
     _instanceID!: string;
 
     /** @internal This is only a marker type and doesn't exist at runtime */
     [ItemsSym]!: Item;
+    /** @internal */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     static _schema: any;
+    /** @internal */
     get _schema(): {
         [ItemsSym]: SchemaFor<Item>;
     } {
         return (this.constructor as typeof CoList)._schema;
     }
 
+    /** @category Collaboration */
     get _owner(): Account | Group {
         return this._raw.group instanceof RawAccount
             ? Account.fromRaw(this._raw.group)
             : Group.fromRaw(this._raw.group);
     }
 
-    /** @category Content */
+    /**
+     * If a `CoList`'s items are a `co.ref(...)`, you can use `coList._refs[i]` 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
+     * animals._refs[0].id; // => ID<Animal>
+     * animals._refs[0].value;
+     * // => Animal | null
+     * const animal = await animals._refs[0].load();
+     * ```
+     *
+     * @category Content
+     **/
     get _refs(): {
         [idx: number]: Exclude<Item, null> extends CoValue
             ? Ref<UnCo<Exclude<Item, null>>>
@@ -145,17 +209,35 @@ export class CoList<Item = any>
         return new Proxy(this, CoListProxyHandler as ProxyHandler<this>);
     }
 
+    /**
+     * Create a new CoList with the given initial values and owner.
+     *
+     * The owner (a Group or Account) determines access rights to the CoMap.
+     *
+     * The CoList will immediately be persisted and synced to connected peers.
+     *
+     * @example
+     * ```ts
+     * const colours = ColorList.create(
+     *   ["red", "green", "blue"],
+     *   { owner: me }
+     * );
+     * const animals = AnimalList.create(
+     *   [cat, dog, fish],
+     *   { owner: me }
+     * );
+     * ```
+     *
+     * @category Creation
+     **/
     static create<L extends CoList>(
-        this: ClassOf<L>,
+        this: CoValueClass<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;
     push(...items: Item[]): number {
         for (const item of toRawItems(
             items as Item[],
@@ -167,9 +249,6 @@ export class CoList<Item = any>
         return this._raw.entries().length;
     }
 
-    unshift(...items: Item[]): number;
-    /** @private For exact type compatibility with Array superclass */
-    unshift(...items: Item[]): number;
     unshift(...items: Item[]): number {
         for (const item of toRawItems(
             items as Item[],
@@ -240,18 +319,15 @@ export class CoList<Item = any>
         return this.toJSON();
     }
 
+    /** @category Internals */
     static fromRaw<V extends CoList>(
-        this: ClassOf<V> & typeof CoList,
+        this: CoValueClass<V> & typeof CoList,
         raw: RawCoList,
     ) {
         return new this({ fromRaw: raw });
     }
 
-    static load = CoValueBase.load as CoValueClass["load"];
-    static loadEf = CoValueBase.loadEf as CoValueClass["loadEf"];
-    static subscribe = CoValueBase.subscribe as CoValueClass["subscribe"];
-    static subscribeEf = CoValueBase.subscribeEf as CoValueClass["subscribeEf"];
-
+    /** @internal */
     static schema<V extends CoList>(
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this: { new (...args: any): V } & typeof CoList,
@@ -260,6 +336,143 @@ export class CoList<Item = any>
         this._schema ||= {};
         Object.assign(this._schema, def);
     }
+
+    /**
+     * Load a `CoList` with a given ID, as a given account.
+     *
+     * `depth` specifies if item CoValue references should be loaded as well before resolving.
+     * The `DeeplyLoaded` return type guarantees that corresponding referenced CoValues are loaded to the specified depth.
+     *
+     * You can pass `[]` or for shallowly loading only this CoList, or `[itemDepth]` for recursively loading referenced CoValues.
+     *
+     * Check out the `load` methods on `CoMap`/`CoList`/`CoStream`/`Group`/`Account` to see which depth structures are valid to nest.
+     *
+     * @example
+     * ```ts
+     * const animalsWithVets =
+     *   await ListOfAnimals.load(
+     *     "co_zdsMhHtfG6VNKt7RqPUPvUtN2Ax",
+     *     me,
+     *     [{ vet: {} }]
+     *   );
+     * ```
+     *
+     * @category Subscription & Loading
+     */
+    static load<L extends CoList, Depth>(
+        this: CoValueClass<L>,
+        id: ID<L>,
+        as: Account,
+        depth: Depth & DepthsIn<L>,
+    ): Promise<DeeplyLoaded<L, Depth> | undefined> {
+        return loadCoValue(this, id, as, depth);
+    }
+
+    /**
+     * Effectful version of `CoList.load()`.
+     *
+     * Needs to be run inside an `AccountCtx` context.
+     *
+     * @category Subscription & Loading
+     */
+    static loadEf<L extends CoList, Depth>(
+        this: CoValueClass<L>,
+        id: ID<L>,
+        depth: Depth & DepthsIn<L>,
+    ): Effect.Effect<DeeplyLoaded<L, Depth>, UnavailableError, AccountCtx> {
+        return loadCoValueEf<L, Depth>(this, id, depth);
+    }
+
+    /**
+     * Load and subscribe to a `CoList` with a given ID, as a given account.
+     *
+     * Automatically also subscribes to updates to all referenced/nested CoValues as soon as they are accessed in the listener.
+     *
+     * `depth` specifies if item CoValue references should be loaded as well before calling `listener` for the first time.
+     * The `DeeplyLoaded` return type guarantees that corresponding referenced CoValues are loaded to the specified depth.
+     *
+     * You can pass `[]` or for shallowly loading only this CoList, or `[itemDepth]` for recursively loading referenced CoValues.
+     *
+     * Check out the `load` methods on `CoMap`/`CoList`/`CoStream`/`Group`/`Account` to see which depth structures are valid to nest.
+     *
+     * Returns an unsubscribe function that you should call when you no longer need updates.
+     *
+     * Also see the `useCoState` hook to reactively subscribe to a CoValue in a React component.
+     *
+     * @example
+     * ```ts
+     * const unsub = ListOfAnimals.subscribe(
+     *   "co_zdsMhHtfG6VNKt7RqPUPvUtN2Ax",
+     *   me,
+     *   { vet: {} },
+     *   (animalsWithVets) => console.log(animalsWithVets)
+     * );
+     * ```
+     *
+     * @category Subscription & Loading
+     */
+    static subscribe<L extends CoList, Depth>(
+        this: CoValueClass<L>,
+        id: ID<L>,
+        as: Account,
+        depth: Depth & DepthsIn<L>,
+        listener: (value: DeeplyLoaded<L, Depth>) => void,
+    ): () => void {
+        return subscribeToCoValue<L, Depth>(this, id, as, depth, listener);
+    }
+
+    /**
+     * Effectful version of `CoList.subscribe()` that returns a stream of updates.
+     *
+     * Needs to be run inside an `AccountCtx` context.
+     *
+     * @category Subscription & Loading
+     */
+    static subscribeEf<L extends CoList, Depth>(
+        this: CoValueClass<L>,
+        id: ID<L>,
+        depth: Depth & DepthsIn<L>,
+    ): Stream.Stream<DeeplyLoaded<L, Depth>, UnavailableError, AccountCtx> {
+        return subscribeToCoValueEf<L, Depth>(this, id, depth);
+    }
+
+    /**
+     * Given an already loaded `CoList`, ensure that items are loaded to the specified depth.
+     *
+     * Works like `CoList.load()`, but you don't need to pass the ID or the account to load as again.
+     *
+     * @category Subscription & Loading
+     */
+    ensureLoaded<L extends CoList, Depth>(
+        this: L,
+        depth: Depth & DepthsIn<L>,
+    ): Promise<DeeplyLoaded<L, Depth> | undefined> {
+        return ensureCoValueLoaded(this, depth);
+    }
+
+    /**
+     * Given an already loaded `CoList`, subscribe to updates to the `CoList` and ensure that items are loaded to the specified depth.
+     *
+     * Works like `CoList.subscribe()`, but you don't need to pass the ID or the account to load as again.
+     *
+     * Returns an unsubscribe function that you should call when you no longer need updates.
+     *
+     * @category Subscription & Loading
+     **/
+    subscribe<L extends CoList, Depth>(
+        this: L,
+        depth: Depth & DepthsIn<L>,
+        listener: (value: DeeplyLoaded<L, Depth>) => void,
+    ): () => void {
+        return subscribeToExistingCoValue(this, depth, listener);
+    }
+
+    /** @category Type Helpers */
+    castAs<Cl extends CoValueClass & CoValueFromRaw<CoValue>>(
+        cl: Cl,
+    ): InstanceType<Cl> {
+        return cl.fromRaw(this._raw) as InstanceType<Cl>;
+    }
 }
 
 function toRawItems<Item>(items: Item[], itemDescriptor: Schema) {

package/src/coValues/coMap.ts

@@ -9,7 +9,11 @@ import type {
     RefEncoded,
     IfCo,
     RefIfCoValue,
-    ClassOf,
+    DepthsIn,
+    DeeplyLoaded,
+    UnavailableError,
+    AccountCtx,
+    CoValueClass,
 } from "../internal.js";
 import {
     Account,
@@ -22,7 +26,14 @@ import {
     ItemsSym,
     InitValues,
     isRefEncoded,
+    loadCoValue,
+    loadCoValueEf,
+    subscribeToCoValue,
+    subscribeToCoValueEf,
+    ensureCoValueLoaded,
+    subscribeToExistingCoValue,
 } from "../internal.js";
+import { Effect, Stream } from "effect";
 
 type CoMapEdit<V> = {
     value?: V;
@@ -42,6 +53,8 @@ type InitValuesFor<C extends CoMap> = {
  * @categoryDescription Declaration
  * Declare your own CoMap schemas by subclassing `CoMap` and assigning field schemas with `co`.
  *
+ * Optional `co.ref(...)` fields must be marked with `{ optional: true }`.
+ *
  * ```ts
  * import { co, CoMap } from "jazz-tools";
  *
@@ -49,6 +62,7 @@ type InitValuesFor<C extends CoMap> = {
  *   name = co.string;
  *   age = co.number;
  *   pet = co.ref(Animal);
+ *   car = co.ref(Car, { optional: true });
  * }
  * ```
  *
@@ -66,7 +80,7 @@ type InitValuesFor<C extends CoMap> = {
  *
  * @category CoValues
  *  */
-export class CoMap extends CoValueBase implements CoValue<"CoMap", RawCoMap> {
+export class CoMap extends CoValueBase implements CoValue {
     /**
      * The ID of this `CoMap`
      * @category Content */
@@ -92,17 +106,19 @@ export class CoMap extends CoValueBase implements CoValue<"CoMap", RawCoMap> {
     /**
      * 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
+     * // => Animal | null
      * const pet = await person._refs.pet.load();
      * ```
      *
-     * @category Content */
+     * @category Content
+     **/
     get _refs(): {
         [Key in CoKeys<this>]: IfCo<this[Key], RefIfCoValue<this[Key]>>;
     } {
@@ -161,10 +177,14 @@ export class CoMap extends CoValueBase implements CoValue<"CoMap", RawCoMap> {
                             : undefined,
                     by:
                         rawEdit.by &&
-                        new Ref(rawEdit.by as ID<Account>, target._loadedAs, {
-                            ref: Account,
-                            optional: false,
-                        }).accessFrom(
+                        new Ref<Account>(
+                            rawEdit.by as ID<Account>,
+                            target._loadedAs,
+                            {
+                                ref: Account,
+                                optional: false,
+                            },
+                        ).accessFrom(
                             target,
                             "_edits." + key.toString() + ".by",
                         ),
@@ -212,9 +232,26 @@ export class CoMap extends CoValueBase implements CoValue<"CoMap", RawCoMap> {
         return new Proxy(this, CoMapProxyHandler as ProxyHandler<this>);
     }
 
-    /** @category Creation */
+    /**
+     * Create a new CoMap with the given initial values and owner.
+     *
+     * The owner (a Group or Account) determines access rights to the CoMap.
+     *
+     * The CoMap will immediately be persisted and synced to connected peers.
+     *
+     * @example
+     * ```ts
+     * const person = Person.create({
+     *   name: "Alice",
+     *   age: 42,
+     *   pet: cat,
+     * }, { owner: friendGroup });
+     * ```
+     *
+     * @category Creation
+     **/
     static create<M extends CoMap>(
-        this: ClassOf<M>,
+        this: CoValueClass<M>,
         init: Simplify<CoMapInit<M>>,
         options: { owner: Account | Group },
     ) {
@@ -286,7 +323,24 @@ export class CoMap extends CoValueBase implements CoValue<"CoMap", RawCoMap> {
         return rawOwner.createMap(rawInit);
     }
 
-    /** @category Declaration */
+    /**
+     * Declare a Record-like CoMap schema, by extending `CoMap.Record(...)` and passing the value schema using `co`. Keys are always `string`.
+     *
+     * @example
+     * ```ts
+     * import { co, CoMap } from "jazz-tools";
+     *
+     * class ColorToFruitMap extends CoMap.Record(
+     *  co.ref(Fruit)
+     * ) {}
+     *
+     * // assume we have map: ColorToFruitMap
+     * // and strawberry: Fruit
+     * map["red"] = strawberry;
+     * ```
+     *
+     * @category Declaration
+     */
     static Record<Value>(value: IfCo<Value, Value>) {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
         class RecordLikeCoMap extends CoMap {
@@ -297,6 +351,135 @@ export class CoMap extends CoValueBase implements CoValue<"CoMap", RawCoMap> {
 
         return RecordLikeCoMap;
     }
+
+    /**
+     * Load a `CoMap` with a given ID, as a given account.
+     *
+     * `depth` specifies which (if any) fields that reference other CoValues to load as well before resolving.
+     * The `DeeplyLoaded` return type guarantees that corresponding referenced CoValues are loaded to the specified depth.
+     *
+     * You can pass `[]` or `{}` for shallowly loading only this CoMap, or `{ fieldA: depthA, fieldB: depthB }` for recursively loading referenced CoValues.
+     *
+     * Check out the `load` methods on `CoMap`/`CoList`/`CoStream`/`Group`/`Account` to see which depth structures are valid to nest.
+     *
+     * @example
+     * ```ts
+     * const person = await Person.load(
+     *   "co_zdsMhHtfG6VNKt7RqPUPvUtN2Ax",
+     *   me,
+     *   { pet: {} }
+     * );
+     * ```
+     *
+     * @category Subscription & Loading
+     */
+    static load<M extends CoMap, Depth>(
+        this: CoValueClass<M>,
+        id: ID<M>,
+        as: Account,
+        depth: Depth & DepthsIn<M>,
+    ): Promise<DeeplyLoaded<M, Depth> | undefined> {
+        return loadCoValue(this, id, as, depth);
+    }
+
+    /**
+     * Effectful version of `CoMap.load()`.
+     *
+     * Needs to be run inside an `AccountCtx` context.
+     *
+     * @category Subscription & Loading
+     */
+    static loadEf<M extends CoMap, Depth>(
+        this: CoValueClass<M>,
+        id: ID<M>,
+        depth: Depth & DepthsIn<M>,
+    ): Effect.Effect<DeeplyLoaded<M, Depth>, UnavailableError, AccountCtx> {
+        return loadCoValueEf<M, Depth>(this, id, depth);
+    }
+
+    /**
+     * Load and subscribe to a `CoMap` with a given ID, as a given account.
+     *
+     * Automatically also subscribes to updates to all referenced/nested CoValues as soon as they are accessed in the listener.
+     *
+     * `depth` specifies which (if any) fields that reference other CoValues to load as well before calling `listener` for the first time.
+     * The `DeeplyLoaded` return type guarantees that corresponding referenced CoValues are loaded to the specified depth.
+     *
+     * You can pass `[]` or `{}` for shallowly loading only this CoMap, or `{ fieldA: depthA, fieldB: depthB }` for recursively loading referenced CoValues.
+     *
+     * Check out the `load` methods on `CoMap`/`CoList`/`CoStream`/`Group`/`Account` to see which depth structures are valid to nest.
+     *
+     * Returns an unsubscribe function that you should call when you no longer need updates.
+     *
+     * Also see the `useCoState` hook to reactively subscribe to a CoValue in a React component.
+     *
+     * @example
+     * ```ts
+     * const unsub = Person.subscribe(
+     *   "co_zdsMhHtfG6VNKt7RqPUPvUtN2Ax",
+     *   me,
+     *   { pet: {} },
+     *   (person) => console.log(person)
+     * );
+     * ```
+     *
+     * @category Subscription & Loading
+     */
+    static subscribe<M extends CoMap, Depth>(
+        this: CoValueClass<M>,
+        id: ID<M>,
+        as: Account,
+        depth: Depth & DepthsIn<M>,
+        listener: (value: DeeplyLoaded<M, Depth>) => void,
+    ): () => void {
+        return subscribeToCoValue<M, Depth>(this, id, as, depth, listener);
+    }
+
+    /**
+     * Effectful version of `CoMap.subscribe()` that returns a stream of updates.
+     *
+     * Needs to be run inside an `AccountCtx` context.
+     *
+     * @category Subscription & Loading
+     */
+    static subscribeEf<M extends CoMap, Depth>(
+        this: CoValueClass<M>,
+        id: ID<M>,
+        depth: Depth & DepthsIn<M>,
+    ): Stream.Stream<DeeplyLoaded<M, Depth>, UnavailableError, AccountCtx> {
+        return subscribeToCoValueEf<M, Depth>(this, id, depth);
+    }
+
+    /**
+     * Given an already loaded `CoMap`, ensure that the specified fields are loaded to the specified depth.
+     *
+     * Works like `CoMap.load()`, but you don't need to pass the ID or the account to load as again.
+     *
+     * @category Subscription & Loading
+     */
+    ensureLoaded<M extends CoMap, Depth>(
+        this: M,
+        depth: Depth & DepthsIn<M>,
+    ): Promise<DeeplyLoaded<M, Depth> | undefined> {
+        return ensureCoValueLoaded(this, depth);
+    }
+
+    /**
+     * Given an already loaded `CoMap`, subscribe to updates to the `CoMap` and ensure that the specified fields are loaded to the specified depth.
+     *
+     * Works like `CoMap.subscribe()`, but you don't need to pass the ID or the account to load as again.
+     *
+     * Returns an unsubscribe function that you should call when you no longer need updates.
+     *
+     * @category Subscription & Loading
+     **/
+    subscribe<M extends CoMap, Depth>(
+        this: M,
+        depth: Depth & DepthsIn<M>,
+        listener: (value: DeeplyLoaded<M, Depth>) => void,
+    ): () => void {
+        return subscribeToExistingCoValue(this, depth, listener);
+    }
 }
 
 export type CoKeys<Map extends object> = Exclude<