jazz-tools 0.7.0-alpha.9 → 0.7.3

package/src/coValues/coMap.ts

@@ -1,15 +1,19 @@
 import type { JsonValue, RawCoMap } from "cojson";
 import type { Simplify } from "effect/Types";
-import { Schema } from "@effect/schema";
+import { encodeSync, decodeSync } from "@effect/schema/Schema";
 import type {
     CoValue,
-    Encoding,
-    EncodingFor,
+    Schema,
     Group,
     ID,
     RefEncoded,
-    EnsureCoValueNullable,
-    IsVal,
+    IfCo,
+    RefIfCoValue,
+    DepthsIn,
+    DeeplyLoaded,
+    UnavailableError,
+    AccountCtx,
+    CoValueClass,
 } from "../internal.js";
 import {
     Account,
@@ -21,161 +25,193 @@ import {
     subscriptionsScopes,
     ItemsSym,
     InitValues,
+    isRefEncoded,
+    loadCoValue,
+    loadCoValueEf,
+    subscribeToCoValue,
+    subscribeToCoValueEf,
+    ensureCoValueLoaded,
+    subscribeToExistingCoValue,
 } from "../internal.js";
-
-type ValidFields<Fields extends { [key: string]: any; [ItemsSym]?: any }> = {
-    [Key in keyof Fields & string as IsVal<
-        Fields[Key],
-        IfOptionalKey<Key, Fields>
-    >]?: EnsureCoValueNullable<Fields[Key], Key>;
-} & {
-    [Key in keyof Fields & string as IsVal<
-        Fields[Key],
-        IfRequiredKey<Key, Fields>
-    >]: EnsureCoValueNullable<Fields[Key], Key>;
-} & {
-    [Key in ItemsSym]?: EnsureCoValueNullable<Fields[ItemsSym], Key>;
-};
-
-type IfOptionalKey<Key extends keyof Obj, Obj> = Pick<
-    Partial<Obj>,
-    Key
-> extends Pick<Obj, Key>
-    ? Key
-    : never;
-type IfRequiredKey<Key extends keyof Obj, Obj> = Pick<
-    Partial<Obj>,
-    Key
-> extends Pick<Obj, Key>
-    ? never
-    : Key;
-
-type DefaultFields = {
-    [key: string]: any;
-    [ItemsSym]?: any;
-};
-
-type CoMapEncoding<Fields extends object> = {
-    [Key in OwnKeys<Fields> as IsVal<Fields[Key], Key>]: EncodingFor<
-        Fields[Key]
-    >;
-} &
-     {
-          [ItemsSym]: ItemsSym extends keyof Fields ? EncodingFor<Fields[ItemsSym]> : never;
-      }
+import { Effect, Stream } from "effect";
 
 type CoMapEdit<V> = {
     value?: V;
-    ref?: V extends CoValue ? Ref<V> : never;
+    ref?: RefIfCoValue<V>;
     by?: Account;
     madeAt: Date;
-}
+};
 
 type InitValuesFor<C extends CoMap> = {
     init: Simplify<CoMapInit<C>>;
     owner: Account | Group;
-}
+};
 
-export class CoMap<Fields extends ValidFields<Fields> = DefaultFields>
-    extends CoValueBase
-    implements CoValue<"CoMap", RawCoMap>
-{
-    id!: ID<this>;
-    _type!: "CoMap";
+/**
+ * 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 {
+    /**
+     * The ID of this `CoMap`
+     * @category Content */
+    declare id: ID<this>;
+    /** @category Type Helpers */
+    declare _type: "CoMap";
     static {
         this.prototype._type = "CoMap";
     }
-    _raw!: RawCoMap;
-
-    static _encoding: any;
-    get _encoding() {
-        return (this.constructor as typeof CoMap)._encoding as CoMapEncoding<this>
+    /** @category Internals */
+    declare _raw: RawCoMap;
+
+    /** @internal */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    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 OwnKeys<this> as NonNullable<this[Key]> extends CoValue
-            ? Key
-            : never]: NonNullable<this[Key]> extends CoValue
-            ? Ref<NonNullable<this[Key]>>
-            : never;
+        [Key in CoKeys<this>]: IfCo<this[Key], RefIfCoValue<this[Key]>>;
     } {
-        return makeRefs<OwnKeys<Fields>>(
+        return makeRefs<CoKeys<this>>(
             (key) => this._raw.get(key as string) as unknown as ID<CoValue>,
-            () =>
-                Object.keys(this._encoding).filter((key) => {
-                    const schema = this._encoding[
-                        key as keyof typeof this._encoding
-                    ] as Encoding;
-                    schema !== "json" && "ref" in schema;
-                }) as OwnKeys<Fields>[],
+            () => {
+                const keys = this._raw.keys().filter((key) => {
+                    const schema =
+                        this._schema[key as keyof typeof this._schema] ||
+                        (this._schema[ItemsSym] as Schema | undefined);
+                    return schema && schema !== "json" && isRefEncoded(schema);
+                }) as CoKeys<this>[];
+
+                return keys;
+            },
             this._loadedAs,
-            (key) => this._encoding[key] as RefEncoded<CoValue>
+            (key) =>
+                (this._schema[key] ||
+                    this._schema[ItemsSym]) as RefEncoded<CoValue>,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
         ) as any;
     }
 
+    /** @category Collaboration */
     get _edits() {
         return new Proxy(this, {
             get(target, key) {
                 const rawEdit = target._raw.lastEditAt(key as string);
                 if (!rawEdit) return undefined;
 
-                const descriptor = target._encoding[
-                    key as keyof typeof target._encoding
-                ] as Encoding;
+                const descriptor = target._schema[
+                    key as keyof typeof target._schema
+                ] as Schema;
 
                 return {
                     value:
                         descriptor === "json"
                             ? rawEdit.value
                             : "encoded" in descriptor
-                              ? Schema.decodeSync(descriptor.encoded)(
-                                    rawEdit.value
-                                )
+                              ? decodeSync(descriptor.encoded)(rawEdit.value)
                               : new Ref(
                                     rawEdit.value as ID<CoValue>,
                                     target._loadedAs,
-                                    descriptor
-                                ).accessFrom(target),
+                                    descriptor,
+                                ).accessFrom(
+                                    target,
+                                    "_edits." + key.toString() + ".value",
+                                ),
                     ref:
-                        descriptor !== "json" && "ref" in descriptor
+                        descriptor !== "json" && isRefEncoded(descriptor)
                             ? new Ref(
                                   rawEdit.value as ID<CoValue>,
                                   target._loadedAs,
-                                  descriptor
+                                  descriptor,
                               )
                             : undefined,
                     by:
                         rawEdit.by &&
-                        new Ref(rawEdit.by as ID<Account>, target._loadedAs, {
-                            ref: () => Account,
-                        }).accessFrom(target),
+                        new Ref<Account>(
+                            rawEdit.by as ID<Account>,
+                            target._loadedAs,
+                            {
+                                ref: Account,
+                                optional: false,
+                            },
+                        ).accessFrom(
+                            target,
+                            "_edits." + key.toString() + ".by",
+                        ),
                     madeAt: rawEdit.at,
                 };
             },
         }) as {
-            [Key in OwnKeys<this> as IsVal<this[Key], Key>]: CoMapEdit<this[Key]>
+            [Key in CoKeys<this>]: IfCo<this[Key], CoMapEdit<this[Key]>>;
         };
     }
 
+    /** @internal */
     get _loadedAs() {
         return Account.fromNode(this._raw.core.node);
     }
 
-    [InitValues]?: InitValuesFor<this>;
+    /** @internal */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [InitValues]?: any;
 
-    constructor(_init: undefined, options: { fromRaw: RawCoMap });
-    constructor(
-        init: Simplify<CoMapInit<Fields>>,
-        options: { owner: Account | Group }
-    );
+    /** @internal */
     constructor(
-        init: Simplify<CoMapInit<Fields>> | undefined,
-        options: { owner: Account | Group } | { fromRaw: RawCoMap }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        options: { fromRaw: RawCoMap } | { init: any; owner: Account | Group },
     ) {
         super();
 
-        if (init && "owner" in options) {
-            this[InitValues] = { init, owner: options.owner } as InitValuesFor<this>;
+        if ("owner" in options) {
+            this[InitValues] = {
+                init: options.init,
+                owner: options.owner,
+            } as InitValuesFor<this>;
         } else if ("fromRaw" in options) {
             Object.defineProperties(this, {
                 id: {
@@ -191,14 +227,25 @@ export class CoMap<Fields extends ValidFields<Fields> = DefaultFields>
         return new Proxy(this, CoMapProxyHandler as ProxyHandler<this>);
     }
 
+    /** @category Creation */
+    static create<M extends CoMap>(
+        this: CoValueClass<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 OwnKeys<Fields>;
-            const descriptor = this._encoding[tKey] as Encoding;
+            const tKey = key as CoKeys<this>;
+            const descriptor = (this._schema[tKey] ||
+                this._schema[ItemsSym]) as Schema;
 
             if (descriptor == "json" || "encode" in descriptor) {
                 return [key, this._raw.get(key)];
-            } else if ("ref" in descriptor) {
+            } else if (isRefEncoded(descriptor)) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 const jsonedRef = (this as any)[tKey]?.toJSON();
                 return [key, jsonedRef];
             } else {
@@ -217,9 +264,11 @@ export class CoMap<Fields extends ValidFields<Fields> = DefaultFields>
         return this.toJSON();
     }
 
+    /** @internal */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     rawFromInit<Fields extends object = Record<string, any>>(
         init: Simplify<CoMapInit<Fields>> | undefined,
-        owner: Account | Group
+        owner: Account | Group,
     ) {
         const rawOwner = owner._raw;
 
@@ -231,51 +280,119 @@ export class CoMap<Fields extends ValidFields<Fields> = DefaultFields>
             for (const key of Object.keys(init) as (keyof Fields)[]) {
                 const initValue = init[key as keyof typeof init];
 
-                const descriptor = (this._encoding[
-                    key as keyof typeof this._encoding
-                ] || this._encoding[ItemsSym]) as Encoding;
+                const descriptor = (this._schema[
+                    key as keyof typeof this._schema
+                ] || this._schema[ItemsSym]) as Schema;
 
                 if (descriptor === "json") {
                     rawInit[key] = initValue as JsonValue;
-                } else if ("ref" in descriptor) {
+                } else if (isRefEncoded(descriptor)) {
                     if (initValue) {
                         rawInit[key] = (initValue as unknown as CoValue).id;
                     }
                 } else if ("encoded" in descriptor) {
-                    rawInit[key] = Schema.encodeSync(descriptor.encoded)(
-                        initValue as any
+                    rawInit[key] = encodeSync(descriptor.encoded)(
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        initValue as any,
                     );
                 }
             }
 
         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 {
+            [ItemsSym] = value;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+        interface RecordLikeCoMap extends Record<string, Value> {}
+
+        return RecordLikeCoMap;
+    }
+
+    /** @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);
+    }
+
+    /** @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);
+    }
+
+    /** @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);
+    }
+
+    /** @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);
+    }
+
+    /** @category Subscription & Loading */
+    ensureLoaded<M extends CoMap, Depth>(
+        this: M,
+        depth: Depth & DepthsIn<M>,
+    ): Promise<DeeplyLoaded<M, Depth> | undefined> {
+        return ensureCoValueLoaded(this, depth);
+    }
+
+    /** @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 OwnKeys<Fields extends object> = Exclude<
-    keyof Fields & string,
-    keyof CoMap<Record<string, never>>
+export type CoKeys<Map extends object> = Exclude<
+    keyof Map & string,
+    keyof CoMap
 >;
 
-export type CoMapInit<Fields extends object> = {
-    [Key in OwnKeys<Fields> as undefined extends Fields[Key]
+export type CoMapInit<Map extends object> = {
+    [Key in CoKeys<Map> as undefined extends Map[Key]
         ? never
-        : null extends Fields[Key]
-          ? never
-          : IsVal<Fields[Key], Key>]: Fields[Key];
-} & { [Key in OwnKeys<Fields> as IsVal<Fields[Key], Key>]?: Fields[Key] };
+        : IfCo<Map[Key], Key>]: Map[Key];
+} & { [Key in CoKeys<Map> as IfCo<Map[Key], Key>]?: Map[Key] };
 
 function tryInit(map: CoMap) {
     if (
         map[InitValues] &&
-        (map._encoding[ItemsSym] ||
+        (map._schema[ItemsSym] ||
             Object.keys(map[InitValues].init).every(
-                (key) => (map._encoding as any)[key]
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                (key) => (map._schema as any)[key],
             ))
     ) {
         const raw = map.rawFromInit(
             map[InitValues].init,
-            map[InitValues].owner
+            map[InitValues].owner,
         );
         Object.defineProperties(map, {
             id: {
@@ -291,14 +408,13 @@ function tryInit(map: CoMap) {
 // TODO: cache handlers per descriptor for performance?
 const CoMapProxyHandler: ProxyHandler<CoMap> = {
     get(target, key, receiver) {
-        if (key === "_encoding") {
+        if (key === "_schema") {
             return Reflect.get(target, key);
         } else if (key in target) {
             return Reflect.get(target, key, receiver);
         } else {
-            const descriptor = (target._encoding[
-                key as keyof CoMap["_encoding"]
-            ] || target._encoding[ItemsSym]) as Encoding;
+            const descriptor = (target._schema[key as keyof CoMap["_schema"]] ||
+                target._schema[ItemsSym]) as Schema;
             if (descriptor && typeof key === "string") {
                 const raw = target._raw.get(key);
 
@@ -307,15 +423,15 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
                 } else if ("encoded" in descriptor) {
                     return raw === undefined
                         ? undefined
-                        : Schema.decodeSync(descriptor.encoded)(raw);
-                } else if ("ref" in descriptor) {
+                        : decodeSync(descriptor.encoded)(raw);
+                } else if (isRefEncoded(descriptor)) {
                     return raw === undefined
                         ? undefined
                         : new Ref(
                               raw as unknown as ID<CoValue>,
                               target._loadedAs,
-                              descriptor
-                          ).accessFrom(receiver);
+                              descriptor,
+                          ).accessFrom(receiver, key);
                 }
             } else {
                 return undefined;
@@ -328,26 +444,25 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
             typeof value === "object" &&
             SchemaInit in value
         ) {
-            (target.constructor as typeof CoMap)._encoding ||= {};
-            (target.constructor as typeof CoMap)._encoding[key] =
+            (target.constructor as typeof CoMap)._schema ||= {};
+            (target.constructor as typeof CoMap)._schema[key] =
                 value[SchemaInit];
             tryInit(target);
             return true;
         }
 
-        const descriptor = (target._encoding[key as keyof CoMap["_encoding"]] ||
-            target._encoding[ItemsSym]) as Encoding;
+        const descriptor = (target._schema[key as keyof CoMap["_schema"]] ||
+            target._schema[ItemsSym]) as Schema;
         if (descriptor && typeof key === "string") {
             if (descriptor === "json") {
                 target._raw.set(key, value);
             } else if ("encoded" in descriptor) {
-                target._raw.set(
-                    key,
-                    Schema.encodeSync(descriptor.encoded)(value)
-                );
-            } else if ("ref" in descriptor) {
+                target._raw.set(key, encodeSync(descriptor.encoded)(value));
+            } else if (isRefEncoded(descriptor)) {
                 target._raw.set(key, value.id);
-                subscriptionsScopes.get(target)?.onRefAccessedOrSet(value.id);
+                subscriptionsScopes
+                    .get(target)
+                    ?.onRefAccessedOrSet(target.id, value.id);
             }
             return true;
         } else {
@@ -360,8 +475,8 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
             typeof attributes.value === "object" &&
             SchemaInit in attributes.value
         ) {
-            (target.constructor as typeof CoMap)._encoding ||= {};
-            (target.constructor as typeof CoMap)._encoding[key as string] =
+            (target.constructor as typeof CoMap)._schema ||= {};
+            (target.constructor as typeof CoMap)._schema[key as string] =
                 attributes.value[SchemaInit];
             tryInit(target);
             return true;
@@ -371,11 +486,11 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
     },
     ownKeys(target) {
         const keys = Reflect.ownKeys(target).filter((k) => k !== ItemsSym);
-        for (const key of Reflect.ownKeys(target._encoding)) {
-            if (key !== ItemsSym && !keys.includes(key)) {
-                keys.push(key);
-            }
-        }
+        // for (const key of Reflect.ownKeys(target._schema)) {
+        //     if (key !== ItemsSym && !keys.includes(key)) {
+        //         keys.push(key);
+        //     }
+        // }
         for (const key of target._raw.keys()) {
             if (!keys.includes(key)) {
                 keys.push(key);
@@ -388,9 +503,8 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
         if (key in target) {
             return Reflect.getOwnPropertyDescriptor(target, key);
         } else {
-            const descriptor = (target._encoding[
-                key as keyof CoMap["_encoding"]
-            ] || target._encoding[ItemsSym]) as Encoding;
+            const descriptor = (target._schema[key as keyof CoMap["_schema"]] ||
+                target._schema[ItemsSym]) as Schema;
             if (descriptor || key in target._raw.ops) {
                 return {
                     enumerable: true,
@@ -400,4 +514,14 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
             }
         }
     },
+    deleteProperty(target, key) {
+        const descriptor = (target._schema[key as keyof CoMap["_schema"]] ||
+            target._schema[ItemsSym]) as Schema;
+        if (typeof key === "string" && descriptor) {
+            target._raw.delete(key);
+            return true;
+        } else {
+            return Reflect.deleteProperty(target, key);
+        }
+    },
 };