jazz-tools 0.7.0-alpha.37 → 0.7.0-alpha.39

package/src/coValues/deepLoading.ts

@@ -0,0 +1,215 @@
+import { SessionID } from "cojson";
+import {
+    Account,
+    CoList,
+    CoStream,
+    CoStreamEntry,
+    ItemsSym,
+    Ref,
+    UnCo,
+} from "../internal.js";
+import { CoKeys } from "./coMap.js";
+import { CoValue, ID } from "./interfaces.js";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function fulfillsDepth(depth: any, value: CoValue): boolean {
+    if (
+        value._type === "CoMap" ||
+        value._type === "Group" ||
+        value._type === "Account"
+    ) {
+        if (Array.isArray(depth) && depth.length === 1) {
+            return Object.entries(value).every(([key, item]) => {
+                return (
+                    value as unknown as {
+                        _refs: { [key: string]: Ref<CoValue> | undefined };
+                    }
+                )._refs[key]
+                    ? item && fulfillsDepth(depth[0], item)
+                    : true;
+            });
+        } else {
+            for (const key of Object.keys(depth)) {
+                const map = value as unknown as {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    [key: string]: any;
+                    _refs: { [key: string]: Ref<CoValue> | undefined };
+                };
+                if (!map._refs[key]) {
+                    continue;
+                }
+                if (!map[key]) {
+                    return false;
+                }
+                if (!fulfillsDepth(depth[key], map[key])) {
+                    return false;
+                }
+            }
+            return true;
+        }
+    } else if (value._type === "CoList") {
+        if (depth.length === 0) {
+            return true;
+        } else {
+            const itemDepth = depth[0];
+            return (value as CoList).every((item, i) =>
+                (value as CoList)._refs[i]
+                    ? item && fulfillsDepth(itemDepth, item)
+                    : true,
+            );
+        }
+    } else if (value._type === "CoStream") {
+        if (depth.length === 0) {
+            return true;
+        } else {
+            const itemDepth = depth[0];
+            return Object.values((value as CoStream).perSession).every(
+                (entry) => entry.value && fulfillsDepth(itemDepth, entry.value),
+            );
+        }
+    } else if (value._type === "BinaryCoStream") {
+        return true;
+    } else {
+        console.error(value);
+        throw new Error("Unexpected value type: " + value._type);
+    }
+}
+
+type UnCoNotNull<T> = UnCo<Exclude<T, null>>;
+type Clean<T> = UnCo<NonNullable<T>>;
+
+export type DepthsIn<
+    V,
+    DepthLimit extends number = 5,
+    CurrentDepth extends number[] = [],
+> =
+    | (DepthLimit extends CurrentDepth["length"]
+          ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            any
+          : // Basically V extends CoList - but if we used that we'd introduce circularity into the definition of CoList itself
+            V extends Array<infer Item>
+            ?
+                  | [
+                        DepthsIn<
+                            UnCoNotNull<Item>,
+                            DepthLimit,
+                            [0, ...CurrentDepth]
+                        >,
+                    ]
+                  | never[]
+            : // Basically V extends CoMap | Group | Account - but if we used that we'd introduce circularity into the definition of CoMap itself
+              V extends { _type: "CoMap" | "Group" | "Account" }
+              ?
+                    | {
+                          [Key in CoKeys<V> as Clean<V[Key]> extends CoValue
+                              ? Key
+                              : never]?: DepthsIn<
+                              Clean<V[Key]>,
+                              DepthLimit,
+                              [0, ...CurrentDepth]
+                          >;
+                      }
+                    | (ItemsSym extends keyof V
+                          ? [
+                                DepthsIn<
+                                    Clean<V[ItemsSym]>,
+                                    DepthLimit,
+                                    [0, ...CurrentDepth]
+                                >,
+                            ]
+                          : never)
+                    | never[]
+              : V extends {
+                      _type: "CoStream";
+                      byMe: CoStreamEntry<infer Item> | undefined;
+                  }
+                ?
+                      | [
+                            DepthsIn<
+                                UnCoNotNull<Item>,
+                                DepthLimit,
+                                [0, ...CurrentDepth]
+                            >,
+                        ]
+                      | never[]
+                : never[])
+    | never[];
+
+export type DeeplyLoaded<
+    V,
+    Depth,
+    DepthLimit extends number = 5,
+    CurrentDepth extends number[] = [],
+> = DepthLimit extends CurrentDepth["length"]
+    ? V
+    : // Basically V extends CoList - but if we used that we'd introduce circularity into the definition of CoList itself
+      [V] extends [Array<infer Item>]
+      ? Depth extends never[] // []
+          ? V
+          : UnCoNotNull<Item> extends CoValue
+            ? Depth extends Array<infer ItemDepth> // [item-depth]
+                ? (UnCoNotNull<Item> &
+                      DeeplyLoaded<
+                          UnCoNotNull<Item>,
+                          ItemDepth,
+                          DepthLimit,
+                          [0, ...CurrentDepth]
+                      >)[] &
+                      V
+                : never
+            : V
+      : // Basically V extends CoMap | Group | Account - but if we used that we'd introduce circularity into the definition of CoMap itself
+        [V] extends [{ _type: "CoMap" | "Group" | "Account" }]
+        ? Depth extends never[]
+            ? V
+            : Depth extends Array<infer ItemDepth>
+              ? ItemsSym extends keyof V
+                  ? V & {
+                        [key: string]: DeeplyLoaded<
+                            Clean<V[ItemsSym]>,
+                            ItemDepth,
+                            DepthLimit,
+                            [0, ...CurrentDepth]
+                        >;
+                    }
+                  : never
+              : keyof Depth extends never
+                ? V
+                : {
+                      [Key in keyof Depth]-?: Key extends CoKeys<V>
+                          ? Clean<V[Key]> extends CoValue
+                              ?
+                                    | DeeplyLoaded<
+                                          Clean<V[Key]>,
+                                          Depth[Key],
+                                          DepthLimit,
+                                          [0, ...CurrentDepth]
+                                      >
+                                    | (undefined extends V[Key]
+                                          ? undefined
+                                          : never)
+                              : never
+                          : never;
+                  } & V
+        : [V] extends [
+                {
+                    _type: "CoStream";
+                    byMe: CoStreamEntry<infer Item> | undefined;
+                },
+            ]
+          ? Depth extends never[]
+              ? V
+              : V & {
+                    byMe?: { value: UnCoNotNull<Item> };
+                    inCurrentSession?: { value: UnCoNotNull<Item> };
+                    perSession: {
+                        [key: SessionID]: { value: UnCoNotNull<Item> };
+                    };
+                } & { [key: ID<Account>]: { value: UnCoNotNull<Item> } }
+          : [V] extends [
+                  {
+                      _type: "BinaryCoStream";
+                  },
+              ]
+            ? V
+            : never;

package/src/coValues/extensions/imageDef.ts

@@ -18,15 +18,15 @@ export class ImageDefinition extends CoMap {
     }): { res: `${number}x${number}`; stream: BinaryCoStream } | undefined {
         if (!subscriptionsScopes.get(this)) {
             console.warn(
-                "highestResAvailable() only makes sense when used within a subscription."
+                "highestResAvailable() only makes sense when used within a subscription.",
             );
         }
 
         const resolutions = Object.keys(this).filter(
             (key) =>
                 key.match(/^\d+x\d+$/) &&
-                ((options?.maxWidth === undefined) ||
-                    Number(key.split("x")[0]) <= options.maxWidth)
+                (options?.maxWidth === undefined ||
+                    Number(key.split("x")[0]) <= options.maxWidth),
         ) as `${number}x${number}`[];
 
         resolutions.sort((a, b) => {

package/src/coValues/group.ts

@@ -1,11 +1,5 @@
 import type { AccountID, Everyone, RawGroup, Role } from "cojson";
-import type {
-    CoValue,
-    ID,
-    RefEncoded,
-    Schema,
-    ClassOf,
-} from "../internal.js";
+import type { CoValue, ID, RefEncoded, Schema, ClassOf } from "../internal.js";
 import {
     Account,
     CoMap,
@@ -31,6 +25,7 @@ export class Group extends CoValueBase implements CoValue<"Group", RawGroup> {
     }
     declare _raw: RawGroup;
 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     static _schema: any;
     get _schema(): {
         profile: Schema;
@@ -44,6 +39,7 @@ export class Group extends CoValueBase implements CoValue<"Group", RawGroup> {
             profile: "json" satisfies Schema,
             root: "json" satisfies Schema,
             [MembersSym]: () => Account satisfies Schema,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
         } as any;
         Object.defineProperty(this.prototype, "_schema", {
             get: () => this._schema,
@@ -69,7 +65,8 @@ export class Group extends CoValueBase implements CoValue<"Group", RawGroup> {
                     this._loadedAs,
                     this._schema.profile as RefEncoded<
                         NonNullable<this["profile"]>
-                    >
+                    >,
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 ) as any as this["profile"] extends Profile
                     ? Ref<this["profile"]>
                     : never),
@@ -78,7 +75,8 @@ export class Group extends CoValueBase implements CoValue<"Group", RawGroup> {
                 (new Ref(
                     rootID,
                     this._loadedAs,
-                    this._schema.root as RefEncoded<NonNullable<this["root"]>>
+                    this._schema.root as RefEncoded<NonNullable<this["root"]>>,
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 ) as any as this["root"] extends CoMap
                     ? Ref<this["root"]>
                     : never),
@@ -103,7 +101,7 @@ export class Group extends CoValueBase implements CoValue<"Group", RawGroup> {
                 raw = rawOwner.createGroup();
             } else {
                 throw new Error(
-                    "Can only construct group as a controlled account"
+                    "Can only construct group as a controlled account",
                 );
             }
         }
@@ -118,13 +116,13 @@ export class Group extends CoValueBase implements CoValue<"Group", RawGroup> {
 
         return new Proxy(
             this,
-            AccountAndGroupProxyHandler as ProxyHandler<this>
+            AccountAndGroupProxyHandler as ProxyHandler<this>,
         );
     }
 
     static create<G extends Group>(
         this: ClassOf<G>,
-        options: { owner: Account }
+        options: { owner: Account },
     ) {
         return new this(options);
     }
@@ -155,7 +153,7 @@ export class Group extends CoValueBase implements CoValue<"Group", RawGroup> {
                     new Ref<NonNullable<this[MembersSym]>>(
                         accountID,
                         this._loadedAs,
-                        this._schema[MembersSym]
+                        this._schema[MembersSym],
                     );
                 const accessRef = () => ref?.accessFrom(this, "members." + id);
 

package/src/coValues/interfaces.ts

@@ -1,7 +1,11 @@
-import { Effect, Sink, Stream } from "effect";
+import { Effect, Option, Sink, Stream } from "effect";
 import type { CojsonInternalTypes, RawCoValue } from "cojson";
 import { RawAccount } from "cojson";
-import type { Me, UnavailableError } from "../internal.js";
+import type {
+    DeeplyLoaded,
+    DepthsIn,
+    UnavailableError,
+} from "../internal.js";
 import {
     Account,
     AccountCtx,
@@ -11,52 +15,67 @@ import {
     inspect,
     subscriptionsScopes,
 } from "../internal.js";
+import { fulfillsDepth } from "./deepLoading.js";
 
 export type ClassOf<T> = {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     new (...args: any[]): T;
 };
 
 /** @category Abstract interfaces */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface CoValueClass<Value extends CoValue = CoValue, Init = any> {
-    /** @category Construction and loading */
     new (init: Init, options: { owner: Account | Group }): Value;
 
     /** @ignore */
     fromRaw(raw: Value["_raw"]): Value;
 
-    /** @category Construction and loading */
-    load<V extends Value>(
+    /** @category Subscription & Loading */
+    load<V extends Value, Depth>(
         this: ClassOf<V>,
         id: ID<V>,
-        options: {
-            as: Account & Me;
-            onProgress?: (progress: number) => void;
-        }
-    ): Promise<V | undefined>;
+        as: Account,
+        depth: Depth & DepthsIn<V>,
+    ): Promise<DeeplyLoaded<V, Depth> | undefined>;
+    /** @category Subscription & Loading */
+    load<V extends Value, Depth>(
+        this: ClassOf<V>,
+        existing: V,
+        depth: Depth & DepthsIn<V>,
+    ): Promise<DeeplyLoaded<V, Depth> | undefined>;
 
-    /** @category Construction and loading */
-    loadEf<V extends Value>(
+    /** @category Subscription & Loading */
+    loadEf<V extends Value, Depth>(
         this: ClassOf<V>,
-        id: ID<V>
-    ): Effect.Effect<V, UnavailableError, AccountCtx>;
+        id: ID<V>,
+        depth: Depth & DepthsIn<V>,
+    ): Effect.Effect<DeeplyLoaded<V, Depth>, UnavailableError, AccountCtx>;
 
-    /** @category Subscription */
-    subscribe<V extends Value, Acc extends Account>(
+    /** @category Subscription & Loading */
+    subscribe<V extends Value, Depth>(
         this: ClassOf<V>,
         id: ID<V>,
-        options: { as: Acc & Me, require?: (value: V) => boolean | undefined },
-        onUpdate: (value: V) => void
+        as: Account,
+        depth: Depth & DepthsIn<V>,
+        listener: (value: DeeplyLoaded<V, Depth>) => void,
+    ): () => void;
+    subscribe<V extends Value, Depth>(
+        this: ClassOf<V>,
+        existing: V,
+        depth: Depth & DepthsIn<V>,
+        listener: (value: DeeplyLoaded<V, Depth>) => void,
     ): () => void;
 
-    /** @category Subscription */
-    subscribeEf<V extends Value>(
+    /** @category Subscription & Loading */
+    subscribeEf<V extends Value, Depth>(
         this: ClassOf<V>,
         id: ID<V>,
-        options?: { require?: (value: V) => boolean | undefined }
-    ): Stream.Stream<V, UnavailableError, AccountCtx>;
+        depth: Depth & DepthsIn<V>,
+    ): Stream.Stream<DeeplyLoaded<V, Depth>, UnavailableError, AccountCtx>;
 }
 
 /** @category Abstract interfaces */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface CoValue<Type extends string = string, Raw = any> {
     /** @category Content */
     readonly id: ID<this>;
@@ -64,23 +83,24 @@ export interface CoValue<Type extends string = string, Raw = any> {
     _type: Type;
     /** @category Collaboration */
     _owner: Account | Group;
-    /** @category Subscription & Loading */
-    subscribe(listener: (update: this) => void, options?: RequireOptions<this>): () => void;
-    /** @category Subscription & Loading */
-    subscribeEf(): Stream.Stream<this, UnavailableError, never>;
     /** @category Internals */
     _raw: Raw;
     /** @internal */
-    readonly _loadedAs: Account & Me;
+    readonly _loadedAs: Account;
     /** @category Stringifying & Inspection */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     toJSON(): any[] | object;
     /** @category Stringifying & Inspection */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     [inspect](): any;
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function isCoValue(value: any): value is CoValue {
     return value && value._type !== undefined;
 }
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function isCoValueClass(value: any): value is CoValueClass {
     return typeof value === "function" && value.fromRaw !== undefined;
 }
@@ -117,6 +137,7 @@ export class CoValueBase implements CoValue {
         return Account.fromNode(this._raw.core.node);
     }
 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     constructor(..._args: any) {
         Object.defineProperty(this, "_instanceID", {
             value: `instance-${Math.random().toString(36).slice(2)}`,
@@ -130,108 +151,149 @@ export class CoValueBase implements CoValue {
     }
 
     /** @category Subscription & Loading */
-    static loadEf<V extends CoValue>(
+    static load<V extends CoValue, Depth>(
         this: ClassOf<V> & typeof CoValueBase,
-        id: ID<V>
-    ): Effect.Effect<V, UnavailableError, AccountCtx> {
-        return Effect.gen(this, function* (_) {
-            const account = yield* _(AccountCtx);
-            return yield* _(
-                new Ref(id as ID<V>, account, this as CoValueClass<V>).loadEf()
-            );
-        });
+        id: ID<V>,
+        as: Account,
+        depth: Depth & DepthsIn<V>,
+    ): Promise<DeeplyLoaded<V, Depth> | undefined>;
+    /** @category Subscription & Loading */
+    static load<V extends CoValue, Depth>(
+        this: ClassOf<V> & typeof CoValueBase,
+        existing: V,
+        depth: Depth & DepthsIn<V>,
+    ): Promise<DeeplyLoaded<V, Depth> | undefined>;
+    static load<V extends CoValue, Depth>(
+        this: ClassOf<V> & typeof CoValueBase,
+
+        ...args:
+            | [ID<V>, Account, Depth & DepthsIn<V>]
+            | [V, Depth & DepthsIn<V>]
+    ): Promise<DeeplyLoaded<V, Depth> | undefined> {
+        const { id, as, depth } =
+            args.length === 3
+                ? { id: args[0], as: args[1], depth: args[2] }
+                : { id: args[0].id, as: args[0]._loadedAs, depth: args[1] };
+        return Effect.runPromise(
+            this.loadEf(id, depth).pipe(
+                Effect.mapError(() => undefined),
+                Effect.merge,
+                Effect.provideService(AccountCtx, as),
+            ),
+        );
     }
 
     /** @category Subscription & Loading */
-    static load<V extends CoValue>(
+    static loadEf<V extends CoValue, Depth>(
         this: ClassOf<V> & typeof CoValueBase,
         id: ID<V>,
-        options: {
-            as: Account & Me;
-            onProgress?: (progress: number) => void;
-        }
-    ): Promise<V | undefined> {
-        return new Ref(id as ID<V>, options.as, this as CoValueClass<V>).load(
-            options?.onProgress && { onProgress: options.onProgress }
+        depth: Depth & DepthsIn<V>,
+    ): Effect.Effect<DeeplyLoaded<V, Depth>, UnavailableError, AccountCtx> {
+        return this.subscribeEf(id, depth).pipe(
+            Stream.runHead,
+            Effect.andThen(
+                Effect.mapError((_noSuchElem) => "unavailable" as const),
+            ),
         );
     }
 
     /** @category Subscription & Loading */
-    static subscribe<V extends CoValue, Acc extends Account>(
+    static subscribe<V extends CoValue, Depth>(
         this: ClassOf<V> & typeof CoValueBase,
         id: ID<V>,
-        options: { as: Acc & Me; require?: (value: V) => boolean | undefined },
-        onUpdate: (value: V) => void
+        as: Account,
+        depth: Depth & DepthsIn<V>,
+        listener: (value: DeeplyLoaded<V, Depth>) => void,
+    ): () => void;
+    static subscribe<V extends CoValue, Depth>(
+        this: ClassOf<V> & typeof CoValueBase,
+        existing: V,
+        depth: Depth & DepthsIn<V>,
+        listener: (value: DeeplyLoaded<V, Depth>) => void,
+    ): () => void;
+    static subscribe<V extends CoValue, Depth>(
+        this: ClassOf<V> & typeof CoValueBase,
+        ...args:
+            | [
+                  ID<V>,
+                  Account,
+                  Depth & DepthsIn<V>,
+                  (value: DeeplyLoaded<V, Depth>) => void,
+              ]
+            | [V, Depth & DepthsIn<V>, (value: DeeplyLoaded<V, Depth>) => void]
     ): () => void {
+        const { id, as, depth, listener } =
+            args.length === 4
+                ? {
+                      id: args[0],
+                      as: args[1],
+                      depth: args[2],
+                      listener: args[3],
+                  }
+                : {
+                      id: args[0].id,
+                      as: args[0]._loadedAs,
+                      depth: args[1],
+                      listener: args[2],
+                  };
         void Effect.runPromise(
             Effect.provideService(
-                this.subscribeEf(id, { require: options.require }).pipe(
+                this.subscribeEf(id, depth).pipe(
                     Stream.run(
                         Sink.forEach((update) =>
-                            Effect.sync(() => onUpdate(update))
-                        )
-                    )
+                            Effect.sync(() => listener(update)),
+                        ),
+                    ),
                 ),
                 AccountCtx,
-                options.as as Account & Me
-            )
+                as,
+            ),
         );
 
         return function unsubscribe() {};
     }
 
     /** @category Subscription & Loading */
-    static subscribeEf<V extends CoValue>(
+    static subscribeEf<V extends CoValue, Depth>(
         this: ClassOf<V> & typeof CoValueBase,
         id: ID<V>,
-        options?: { require?: (value: V) => boolean | undefined }
-    ): Stream.Stream<V, UnavailableError, AccountCtx> {
-        return Stream.fromEffect(this.loadEf(id)).pipe(
-            Stream.flatMap((value) =>
+        depth: Depth & DepthsIn<V>,
+    ): Stream.Stream<DeeplyLoaded<V, Depth>, UnavailableError, AccountCtx> {
+        return AccountCtx.pipe(
+            Effect.andThen((account) =>
+                new Ref(id, account, this as CoValueClass<V>).loadEf(),
+            ),
+            Stream.fromEffect,
+            Stream.flatMap((value: V) =>
                 Stream.asyncScoped<V, UnavailableError>((emit) =>
                     Effect.gen(this, function* (_) {
                         const subscription = new SubscriptionScope(
                             value,
                             this,
-                            (update) => {
-                                if (!options?.require || options.require(update)) {
-                                    void emit.single(update as V);
-                                }
-                            }
+                            (update) => void emit.single(update as V),
                         );
 
                         yield* _(
                             Effect.addFinalizer(() =>
-                                Effect.sync(() => subscription.unsubscribeAll())
-                            )
+                                Effect.sync(() =>
+                                    subscription.unsubscribeAll(),
+                                ),
+                            ),
                         );
-                    })
-                )
-            )
-        );
-    }
-
-    /** @category Subscription & Loading */
-    subscribe(listener: (update: this) => void, options?: RequireOptions<this>): () => void {
-        return (this.constructor as unknown as typeof CoValueBase).subscribe(
-            this.id as unknown as ID<CoValue>,
-            { as: this._loadedAs, require: options?.require as any },
-            listener as unknown as (update: CoValue) => void
-        );
-    }
-
-    /** @category Subscription & Loading */
-    subscribeEf(options?: RequireOptions<this>): Stream.Stream<this, UnavailableError, never> {
-        return Stream.provideService(
-            (this.constructor as unknown as typeof CoValueBase).subscribeEf(
-                this.id as unknown as ID<CoValue>,
-                options as any
+                    }),
+                ),
+            ),
+            Stream.filterMap((update: V) =>
+                Option.fromNullable(
+                    fulfillsDepth(depth, update)
+                        ? (update as DeeplyLoaded<V, Depth>)
+                        : undefined,
+                ),
             ),
-            AccountCtx,
-            this._loadedAs
-        ) as unknown as Stream.Stream<this, UnavailableError, never>;
+        );
     }
 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     toJSON(): object | any[] {
         return {
             id: this.id,
@@ -254,7 +316,3 @@ export class CoValueBase implements CoValue {
         return cast;
     }
 }
-
-export type RequireOptions<V extends CoValue> = {
-    require?: (value: V) => boolean | undefined
-};

package/src/implementation/devtoolsFormatters.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import { ItemsSym } from "./symbols.js";
 
 (globalThis as any).devtoolsFormatters = [