jazz-tools 0.7.3 → 0.7.8

package/src/coValues/coMap.ts

@@ -24,7 +24,6 @@ import {
     makeRefs,
     subscriptionsScopes,
     ItemsSym,
-    InitValues,
     isRefEncoded,
     loadCoValue,
     loadCoValueEf,
@@ -42,17 +41,14 @@ type CoMapEdit<V> = {
     madeAt: Date;
 };
 
-type InitValuesFor<C extends CoMap> = {
-    init: Simplify<CoMapInit<C>>;
-    owner: Account | Group;
-};
-
 /**
  * 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`.
  *
+ * Optional `co.ref(...)` fields must be marked with `{ optional: true }`.
+ *
  * ```ts
  * import { co, CoMap } from "jazz-tools";
  *
@@ -60,6 +56,7 @@ type InitValuesFor<C extends CoMap> = {
  *   name = co.string;
  *   age = co.number;
  *   pet = co.ref(Animal);
+ *   car = co.ref(Car, { optional: true });
  * }
  * ```
  *
@@ -103,17 +100,19 @@ export class CoMap extends CoValueBase implements CoValue {
     /**
      * 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]>>;
     } {
@@ -196,44 +195,66 @@ export class CoMap extends CoValueBase implements CoValue {
         return Account.fromNode(this._raw.core.node);
     }
 
-    /** @internal */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [InitValues]?: any;
-
     /** @internal */
     constructor(
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        options: { fromRaw: RawCoMap } | { init: any; owner: Account | Group },
+        options: { fromRaw: RawCoMap } | undefined
     ) {
         super();
 
-        if ("owner" in options) {
-            this[InitValues] = {
-                init: options.init,
-                owner: options.owner,
-            } as InitValuesFor<this>;
-        } else if ("fromRaw" in options) {
-            Object.defineProperties(this, {
-                id: {
-                    value: options.fromRaw.id as unknown as ID<this>,
-                    enumerable: false,
-                },
-                _raw: { value: options.fromRaw, enumerable: false },
-            });
-        } else {
-            throw new Error("Invalid CoMap constructor arguments");
+        if (options) {
+            if ("fromRaw" in options) {
+                Object.defineProperties(this, {
+                    id: {
+                        value: options.fromRaw.id as unknown as ID<this>,
+                        enumerable: false,
+                    },
+                    _raw: { value: options.fromRaw, enumerable: false },
+                });
+            } else {
+                throw new Error("Invalid CoMap constructor arguments");
+            }
         }
 
         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: CoValueClass<M>,
         init: Simplify<CoMapInit<M>>,
         options: { owner: Account | Group },
     ) {
-        return new this({ init, owner: options.owner });
+        const instance = new this();
+        const raw = instance.rawFromInit(
+            init,
+            options.owner,
+        );
+        Object.defineProperties(instance, {
+            id: {
+                value: raw.id,
+                enumerable: false,
+            },
+            _raw: { value: raw, enumerable: false },
+        });
+        return instance;
     }
 
     toJSON() {
@@ -284,6 +305,10 @@ export class CoMap extends CoValueBase implements CoValue {
                     key as keyof typeof this._schema
                 ] || this._schema[ItemsSym]) as Schema;
 
+                if (!descriptor) {
+                    continue;
+                }
+
                 if (descriptor === "json") {
                     rawInit[key] = initValue as JsonValue;
                 } else if (isRefEncoded(descriptor)) {
@@ -301,7 +326,24 @@ export class CoMap extends CoValueBase implements CoValue {
         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 {
@@ -313,7 +355,27 @@ export class CoMap extends CoValueBase implements CoValue {
         return RecordLikeCoMap;
     }
 
-    /** @category Subscription & Loading */
+    /**
+     * 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>,
@@ -323,7 +385,13 @@ export class CoMap extends CoValueBase implements CoValue {
         return loadCoValue(this, id, as, depth);
     }
 
-    /** @category Subscription & Loading */
+    /**
+     * 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>,
@@ -332,7 +400,34 @@ export class CoMap extends CoValueBase implements CoValue {
         return loadCoValueEf<M, Depth>(this, id, depth);
     }
 
-    /** @category Subscription & Loading */
+    /**
+     * 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>,
@@ -343,7 +438,13 @@ export class CoMap extends CoValueBase implements CoValue {
         return subscribeToCoValue<M, Depth>(this, id, as, depth, listener);
     }
 
-    /** @category Subscription & Loading */
+    /**
+     * 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>,
@@ -352,7 +453,13 @@ export class CoMap extends CoValueBase implements CoValue {
         return subscribeToCoValueEf<M, Depth>(this, id, depth);
     }
 
-    /** @category Subscription & Loading */
+    /**
+     * 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>,
@@ -360,7 +467,15 @@ export class CoMap extends CoValueBase implements CoValue {
         return ensureCoValueLoaded(this, depth);
     }
 
-    /** @category Subscription & Loading */
+    /**
+     * 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>,
@@ -381,30 +496,6 @@ export type CoMapInit<Map extends object> = {
         : 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._schema[ItemsSym] ||
-            Object.keys(map[InitValues].init).every(
-                // 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,
-        );
-        Object.defineProperties(map, {
-            id: {
-                value: raw.id,
-                enumerable: false,
-            },
-            _raw: { value: raw, enumerable: false },
-        });
-        delete map[InitValues];
-    }
-}
-
 // TODO: cache handlers per descriptor for performance?
 const CoMapProxyHandler: ProxyHandler<CoMap> = {
     get(target, key, receiver) {
@@ -447,7 +538,6 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
             (target.constructor as typeof CoMap)._schema ||= {};
             (target.constructor as typeof CoMap)._schema[key] =
                 value[SchemaInit];
-            tryInit(target);
             return true;
         }
 
@@ -478,7 +568,6 @@ const CoMapProxyHandler: ProxyHandler<CoMap> = {
             (target.constructor as typeof CoMap)._schema ||= {};
             (target.constructor as typeof CoMap)._schema[key as string] =
                 attributes.value[SchemaInit];
-            tryInit(target);
             return true;
         } else {
             return Reflect.defineProperty(target, key, attributes);

package/src/coValues/coStream.ts

@@ -30,7 +30,6 @@ import {
     Ref,
     inspect,
     co,
-    InitValues,
     SchemaInit,
     isRefEncoded,
     loadCoValue,
@@ -93,9 +92,6 @@ export class CoStream<Item = any> extends CoValueBase implements CoValue {
         return this.perSession[this._loadedAs.sessionID!];
     }
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    [InitValues]?: any;
-
     constructor(
         options:
             | { init: Item[]; owner: Account | Group }
@@ -103,7 +99,7 @@ export class CoStream<Item = any> extends CoValueBase implements CoValue {
     ) {
         super();
 
-        if ("fromRaw" in options) {
+        if (options && "fromRaw" in options) {
             Object.defineProperties(this, {
                 id: {
                     value: options.fromRaw.id,
@@ -111,11 +107,6 @@ export class CoStream<Item = any> extends CoValueBase implements CoValue {
                 },
                 _raw: { value: options.fromRaw, enumerable: false },
             });
-        } else {
-            this[InitValues] = {
-                init: options.init,
-                owner: options.owner,
-            };
         }
 
         return new Proxy(this, CoStreamProxyHandler as ProxyHandler<this>);
@@ -126,7 +117,21 @@ export class CoStream<Item = any> extends CoValueBase implements CoValue {
         init: S extends CoStream<infer Item> ? UnCo<Item>[] : never,
         options: { owner: Account | Group },
     ) {
-        return new this({ init, owner: options.owner });
+        const instance = new this({ init, owner: options.owner });
+        const raw = options.owner._raw.createStream();
+
+        Object.defineProperties(instance, {
+            id: {
+                value: raw.id,
+                enumerable: false,
+            },
+            _raw: { value: raw, enumerable: false },
+        });
+
+        if (init) {
+            instance.push(...init);
+        }
+        return instance;
     }
 
     push(...items: Item[]) {
@@ -317,27 +322,6 @@ function entryFromRawEntry<Item>(
     };
 }
 
-function init(stream: CoStream) {
-    const init = stream[InitValues];
-    if (!init) return;
-
-    const raw = init.owner._raw.createStream();
-
-    Object.defineProperties(stream, {
-        id: {
-            value: raw.id,
-            enumerable: false,
-        },
-        _raw: { value: raw, enumerable: false },
-    });
-
-    if (init.init) {
-        stream.push(...init.init);
-    }
-
-    delete stream[InitValues];
-}
-
 export const CoStreamProxyHandler: ProxyHandler<CoStream> = {
     get(target, key, receiver) {
         if (typeof key === "string" && key.startsWith("co_")) {
@@ -391,7 +375,6 @@ export const CoStreamProxyHandler: ProxyHandler<CoStream> = {
             (target.constructor as typeof CoStream)._schema ||= {};
             (target.constructor as typeof CoStream)._schema[ItemsSym] =
                 value[SchemaInit];
-            init(target);
             return true;
         } else {
             return Reflect.set(target, key, value, receiver);
@@ -407,7 +390,6 @@ export const CoStreamProxyHandler: ProxyHandler<CoStream> = {
             (target.constructor as typeof CoStream)._schema ||= {};
             (target.constructor as typeof CoStream)._schema[ItemsSym] =
                 descriptor.value[SchemaInit];
-            init(target);
             return true;
         } else {
             return Reflect.defineProperty(target, key, descriptor);

package/src/coValues/group.ts

@@ -114,7 +114,7 @@ export class Group extends CoValueBase implements CoValue {
             const initOwner = options.owner;
             if (!initOwner) throw new Error("No owner provided");
             if (
-                initOwner instanceof Account &&
+                initOwner._type === "Account" &&
                 isControlledAccount(initOwner)
             ) {
                 const rawOwner = initOwner._raw;

package/src/coValues/interfaces.ts

@@ -68,6 +68,7 @@ export class CoValueBase implements CoValue {
     id!: ID<this>;
     _type!: string;
     _raw!: RawCoValue;
+    /** @category Internals */
     _instanceID!: string;
 
     get _owner(): Account | Group {

package/src/implementation/symbols.ts

@@ -1,9 +1,6 @@
 export const SchemaInit = Symbol.for("SchemaInit");
 export type SchemaInit = typeof SchemaInit;
 
-export const InitValues = Symbol.for("InitValues");
-export type InitValues = typeof InitValues;
-
 export const ItemsSym = Symbol.for("items");
 export type ItemsSym = typeof ItemsSym;
 

package/src/index.ts

@@ -17,7 +17,7 @@ export type { ID, CoValue } from "./internal.js";
 
 export { Encoders, co } from "./internal.js";
 
-export { CoMap } from "./internal.js";
+export { CoMap, type CoMapInit } from "./internal.js";
 export { CoList } from "./internal.js";
 export { CoStream, BinaryCoStream } from "./internal.js";
 export { Group, Profile } from "./internal.js";

package/src/tests/coMap.test.ts

@@ -52,6 +52,22 @@ describe("Simple CoMap operations", async () => {
         expect(Object.keys(map)).toEqual(["color", "_height", "birthday"]);
     });
 
+    test("Construction with too many things provided", () => {
+        const mapWithExtra = TestMap.create(
+            {
+                color: "red",
+                _height: 10,
+                birthday: birthday,
+                name: "Hermes",
+                extra: "extra",
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            } as any,
+            { owner: me },
+        );
+
+        expect(mapWithExtra.color).toEqual("red");
+    })
+
     describe("Mutation", () => {
         test("assignment & deletion", () => {
             map.color = "blue";