jazz-tools 0.16.2 → 0.16.4

package/src/react-core/hooks.ts

@@ -141,13 +141,102 @@ function useCoValueSubscription<
   return subscription.subscription;
 }
 
+/**
+ * React hook for subscribing to CoValues and handling loading states.
+ *
+ * This hook provides a convenient way to subscribe to CoValues and automatically
+ * handles the subscription lifecycle (subscribe on mount, unsubscribe on unmount).
+ * It also supports deep loading of nested CoValues through resolve queries.
+ *
+ * @returns The loaded CoValue, or `undefined` if loading, or `null` if not found/not accessible
+ *
+ * @example
+ * ```tsx
+ * // Deep loading with resolve queries
+ * const Project = co.map({
+ *   name: z.string(),
+ *   tasks: co.list(Task),
+ *   owner: TeamMember,
+ * });
+ *
+ * function ProjectView({ projectId }: { projectId: string }) {
+ *   const project = useCoState(Project, projectId, {
+ *     resolve: {
+ *       tasks: { $each: true },
+ *       owner: true,
+ *     },
+ *   });
+ *
+ *   if (!project) {
+ *     return project === null
+ *       ? "Project not found or not accessible"
+ *       : "Loading project...";
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <h1>{project.name}</h1>
+ *       <p>Owner: {project.owner.name}</p>
+ *       <ul>
+ *         {project.tasks.map((task) => (
+ *           <li key={task.id}>{task.title}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using with optional references and error handling
+ * const Task = co.map({
+ *   title: z.string(),
+ *   assignee: co.optional(TeamMember),
+ *   subtasks: co.list(Task),
+ * });
+ *
+ * function TaskDetail({ taskId }: { taskId: string }) {
+ *   const task = useCoState(Task, taskId, {
+ *     resolve: {
+ *       assignee: true,
+ *       subtasks: { $each: { $onError: null } },
+ *     },
+ *   });
+ *
+ *   if (!task) {
+ *     return task === null
+ *       ? "Task not found or not accessible"
+ *       : "Loading task...";
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <h2>{task.title}</h2>
+ *       {task.assignee && <p>Assigned to: {task.assignee.name}</p>}
+ *       <ul>
+ *         {task.subtasks.map((subtask, index) => (
+ *           subtask ? <li key={subtask.id}>{subtask.title}</li> : <li key={index}>Inaccessible subtask</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * For more examples, see the [subscription and deep loading](https://jazz.tools/docs/react/using-covalues/subscription-and-loading) documentation.
+ */
 export function useCoState<
   S extends CoValueClassOrSchema,
   const R extends ResolveQuery<S> = true,
 >(
+  /** The CoValue schema or class constructor */
   Schema: S,
+  /** The ID of the CoValue to subscribe to. If `undefined`, returns `null` */
   id: string | undefined,
+  /** Optional configuration for the subscription */
   options?: {
+    /** Resolve query to specify which nested CoValues to load */
     resolve?: ResolveQueryStrict<S, R>;
   },
 ): Loaded<S, R> | undefined | null {
@@ -229,12 +318,66 @@ function useAccountSubscription<
   return subscription.subscription;
 }
 
+/**
+ * React hook for accessing the current user's account and authentication state.
+ * 
+ * This hook provides access to the current user's account profile and root data,
+ * along with authentication utilities. It automatically handles subscription to
+ * the user's account data and provides a logout function.
+ * 
+ * @returns An object containing:
+ * - `me`: The loaded account data, or `undefined` if loading, or `null` if not authenticated
+ * - `agent`: The current agent (anonymous or authenticated user). Can be used as `loadAs` parameter for load and subscribe methods.
+ * - `logOut`: Function to log out the current user
+
+ * @example
+ * ```tsx
+ * // Deep loading with resolve queries
+ * function ProjectListWithDetails() {
+ *   const { me } = useAccount(MyAppAccount, {
+ *     resolve: {
+ *       profile: true,
+ *       root: {
+ *         myProjects: {
+ *           $each: {
+ *             tasks: true,
+ *           },
+ *         },
+ *       },
+ *     },
+ *   });
+ * 
+ *   if (!me) {
+ *     return me === null
+ *       ? <div>Failed to load your projects</div>
+ *       : <div>Loading...</div>;
+ *   }
+ * 
+ *   return (
+ *     <div>
+ *       <h1>{me.profile.name}'s projects</h1>
+ *       <ul>
+ *         {me.root.myProjects.map((project) => (
+ *           <li key={project.id}>
+ *             {project.name} ({project.tasks.length} tasks)
+ *           </li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ * 
+ */
 export function useAccount<
   A extends AccountClass<Account> | AnyAccountSchema,
   R extends ResolveQuery<A> = true,
 >(
+  /** The account schema to use. Defaults to the base Account schema */
   AccountSchema: A = Account as unknown as A,
+  /** Optional configuration for the subscription */
   options?: {
+    /** Resolve query to specify which nested CoValues to load from the account */
     resolve?: ResolveQueryStrict<A, R>;
   },
 ): {

package/src/tools/coValues/coFeed.ts

@@ -34,6 +34,7 @@ import {
   coField,
   ensureCoValueLoaded,
   inspect,
+  instantiateRefEncodedWithInit,
   isRefEncoded,
   loadCoValueWithoutMe,
   parseCoValueCreateOptions,
@@ -278,7 +279,16 @@ export class CoFeed<out Item = any> extends CoValueBase implements CoValue {
     } else if ("encoded" in itemDescriptor) {
       this._raw.push(itemDescriptor.encoded.encode(item));
     } else if (isRefEncoded(itemDescriptor)) {
-      this._raw.push((item as unknown as CoValue).id);
+      let refId = (item as unknown as CoValue).id;
+      if (!refId) {
+        const coValue = instantiateRefEncodedWithInit(
+          itemDescriptor,
+          item,
+          this._owner,
+        );
+        refId = coValue.id;
+      }
+      this._raw.push(refId);
     }
   }
 
@@ -418,9 +428,7 @@ export class CoFeed<out Item = any> extends CoValueBase implements CoValue {
    *
    * @category Subscription & Loading
    */
-  waitForSync(options?: {
-    timeout?: number;
-  }) {
+  waitForSync(options?: { timeout?: number }) {
     return this._raw.core.waitForSync(options);
   }
 }

package/src/tools/coValues/coList.ts

@@ -29,6 +29,7 @@ import {
   coValuesCache,
   ensureCoValueLoaded,
   inspect,
+  instantiateRefEncodedWithInit,
   isRefEncoded,
   loadCoValueWithoutMe,
   makeRefs,
@@ -240,7 +241,7 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
     const { owner } = parseCoValueCreateOptions(options);
     const instance = new this({ init: items, owner });
     const raw = owner._raw.createList(
-      toRawItems(items, instance._schema[ItemsSym]),
+      toRawItems(items, instance._schema[ItemsSym], owner),
     );
 
     Object.defineProperties(instance, {
@@ -256,7 +257,7 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
 
   push(...items: Item[]): number {
     this._raw.appendItems(
-      toRawItems(items, this._schema[ItemsSym]),
+      toRawItems(items, this._schema[ItemsSym], this._owner),
       undefined,
       "private",
     );
@@ -265,7 +266,11 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
   }
 
   unshift(...items: Item[]): number {
-    for (const item of toRawItems(items as Item[], this._schema[ItemsSym])) {
+    for (const item of toRawItems(
+      items as Item[],
+      this._schema[ItemsSym],
+      this._owner,
+    )) {
       this._raw.prepend(item);
     }
 
@@ -306,7 +311,11 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
       this._raw.delete(idxToDelete);
     }
 
-    const rawItems = toRawItems(items as Item[], this._schema[ItemsSym]);
+    const rawItems = toRawItems(
+      items as Item[],
+      this._schema[ItemsSym],
+      this._owner,
+    );
 
     // If there are no items to insert, return the deleted items
     if (rawItems.length === 0) {
@@ -551,23 +560,36 @@ export class CoList<out Item = any> extends Array<Item> implements CoValue {
  * Convert an array of items to a raw array of items.
  * @param items - The array of items to convert.
  * @param itemDescriptor - The descriptor of the items.
+ * @param owner - The owner of the CoList.
  * @returns The raw array of items.
  */
-function toRawItems<Item>(items: Item[], itemDescriptor: Schema) {
-  const rawItems =
-    itemDescriptor === "json"
-      ? (items as JsonValue[])
-      : "encoded" in itemDescriptor
-        ? items?.map((e) => itemDescriptor.encoded.encode(e))
-        : isRefEncoded(itemDescriptor)
-          ? items?.map((v) => {
-              if (!v) return null;
-
-              return (v as unknown as CoValue).id;
-            })
-          : (() => {
-              throw new Error("Invalid element descriptor");
-            })();
+function toRawItems<Item>(
+  items: Item[],
+  itemDescriptor: Schema,
+  owner: Account | Group,
+) {
+  let rawItems: JsonValue[] = [];
+  if (itemDescriptor === "json") {
+    rawItems = items as JsonValue[];
+  } else if ("encoded" in itemDescriptor) {
+    rawItems = items?.map((e) => itemDescriptor.encoded.encode(e));
+  } else if (isRefEncoded(itemDescriptor)) {
+    rawItems = items?.map((value) => {
+      if (value == null) return null;
+      let refId = (value as unknown as CoValue).id;
+      if (!refId) {
+        const coValue = instantiateRefEncodedWithInit(
+          itemDescriptor,
+          value,
+          owner,
+        );
+        refId = coValue.id;
+      }
+      return refId;
+    });
+  } else {
+    throw new Error("Invalid element descriptor");
+  }
   return rawItems;
 }
 

package/src/tools/coValues/coMap.ts

@@ -37,6 +37,7 @@ import {
   activeAccountContext,
   ensureCoValueLoaded,
   inspect,
+  instantiateRefEncodedWithInit,
   isRefEncoded,
   loadCoValueWithoutMe,
   makeRefs,
@@ -424,8 +425,17 @@ export class CoMap extends CoValueBase implements CoValue {
         if (descriptor === "json") {
           rawInit[key] = initValue as JsonValue;
         } else if (isRefEncoded(descriptor)) {
-          if (initValue) {
-            rawInit[key] = (initValue as unknown as CoValue).id;
+          if (initValue != null) {
+            let refId = (initValue as unknown as CoValue).id;
+            if (!refId) {
+              const coValue = instantiateRefEncodedWithInit(
+                descriptor,
+                initValue,
+                owner,
+              );
+              refId = coValue.id;
+            }
+            rawInit[key] = refId;
           }
         } else if ("encoded" in descriptor) {
           rawInit[key] = descriptor.encoded.encode(

package/src/tools/coValues/inbox.ts

@@ -145,7 +145,7 @@ export class Inbox {
 
       for (const [sessionID, items] of Object.entries(stream.items) as [
         SessionID,
-        CoStreamItem<CoID<InboxMessage<InstanceOfSchema<M>, O>>>[],
+        CoStreamItem<CoID<InboxMessage<NonNullable<InstanceOfSchema<M>>, O>>>[],
       ][]) {
         const accountID = getAccountIDfromSessionID(sessionID);
 

package/src/tools/coValues/interfaces.ts

@@ -2,7 +2,6 @@ import {
   type CoValueUniqueness,
   type CojsonInternalTypes,
   type RawCoValue,
-  emptyKnownState,
 } from "cojson";
 import { AvailableCoValueCore } from "cojson/dist/coValueCore/coValueCore.js";
 import {
@@ -546,9 +545,9 @@ function loadContentPiecesFromCoValue(
     }
   }
 
-  const pieces = core.verified.newContentSince(emptyKnownState(core.id));
+  const pieces = core.verified.newContentSince(undefined) ?? [];
 
-  for (const piece of pieces ?? []) {
+  for (const piece of pieces) {
     contentPieces.push(piece);
   }
 }

package/src/tools/coValues/schemaUnion.ts

@@ -1,12 +1,16 @@
+import { JsonValue, RawCoMap } from "cojson";
 import {
   Account,
   AnonymousJazzAgent,
+  CoMapInit,
   CoValue,
   CoValueBase,
   CoValueClass,
   CoValueFromRaw,
+  Group,
   ID,
   Resolved,
+  Simplify,
   SubscribeListenerOptions,
   SubscribeRestArgs,
   loadCoValueWithoutMe,
@@ -20,6 +24,10 @@ import {
 export type SchemaUnionConcreteSubclass<V extends CoValue> =
   typeof SchemaUnion & CoValueClass<V>;
 
+export type SchemaUnionDiscriminator<V extends CoValue> = (discriminable: {
+  get(key: string): JsonValue | undefined;
+}) => CoValueClass<V> & CoValueFromRaw<V>;
+
 /**
  * SchemaUnion allows you to create union types of CoValues that can be discriminated at runtime.
  *
@@ -89,28 +97,45 @@ export abstract class SchemaUnion extends CoValueBase implements CoValue {
    * @category Declaration
    **/
   static Of<V extends CoValue>(
-    discriminator: (raw: V["_raw"]) => CoValueClass<V> & CoValueFromRaw<V>,
+    discriminator: SchemaUnionDiscriminator<V>,
   ): SchemaUnionConcreteSubclass<V> {
     return class SchemaUnionClass extends SchemaUnion {
+      static override create<V extends CoValue>(
+        this: CoValueClass<V>,
+        init: Simplify<CoMapInit<V>>,
+        owner: Account | Group,
+      ): V {
+        const ResolvedClass = discriminator(new Map(Object.entries(init)));
+        // @ts-expect-error - create is a static method in the CoMap class
+        return ResolvedClass.create(init, owner);
+      }
+
       static override fromRaw<T extends CoValue>(
         this: CoValueClass<T> & CoValueFromRaw<T>,
         raw: T["_raw"],
       ): T {
         const ResolvedClass = discriminator(
-          raw as V["_raw"],
+          raw as RawCoMap,
         ) as unknown as CoValueClass<T> & CoValueFromRaw<T>;
         return ResolvedClass.fromRaw(raw);
       }
     } as unknown as SchemaUnionConcreteSubclass<V>;
   }
 
+  static create<V extends CoValue>(
+    this: CoValueClass<V>,
+    init: Simplify<CoMapInit<V>>,
+    owner: Account | Group,
+  ): V {
+    throw new Error("Not implemented");
+  }
+
   /**
    * Create an instance from raw data. This is called internally and should not be used directly.
    * Use {@link SchemaUnion.Of} to create a union type instead.
    *
    * @internal
    */
-  // @ts-ignore
   static fromRaw<V extends CoValue>(this: CoValueClass<V>, raw: V["_raw"]): V {
     throw new Error("Not implemented");
   }

package/src/tools/exports.ts

@@ -107,7 +107,6 @@ export {
   type CoreAccountSchema as AnyAccountSchema,
   type ResolveQuery,
   type ResolveQueryStrict,
-  type InitFor,
 } from "./internal.js";
 
 export {

package/src/tools/implementation/schema.ts

@@ -1,11 +1,12 @@
 import type { JsonValue, RawCoValue } from "cojson";
 import { CojsonInternalTypes } from "cojson";
 import {
+  Account,
   type CoValue,
   type CoValueClass,
   CoValueFromRaw,
+  Group,
   ItemsSym,
-  JazzToolsSymbol,
   SchemaInit,
   isCoValueClass,
 } from "../internal.js";
@@ -140,7 +141,7 @@ export function isRefEncoded<V extends CoValue>(
   );
 }
 
-export function instantiateRefEncoded<V extends CoValue>(
+export function instantiateRefEncodedFromRaw<V extends CoValue>(
   schema: RefEncoded<V>,
   raw: RawCoValue,
 ): V {
@@ -151,6 +152,31 @@ export function instantiateRefEncoded<V extends CoValue>(
       ).fromRaw(raw);
 }
 
+/**
+ * Creates a new CoValue of the given ref type, using the provided init values.
+ *
+ * @param schema - The schema of the CoValue to create.
+ * @param init - The init values to use to create the CoValue.
+ * @param parentOwner - The owner of the referencing CoValue. Will be used
+ * as the parent group of the created CoValue's group
+ * @returns The created CoValue.
+ */
+export function instantiateRefEncodedWithInit<V extends CoValue>(
+  schema: RefEncoded<V>,
+  init: any,
+  parentOwner: Account | Group,
+): V {
+  if (!isCoValueClass<V>(schema.ref)) {
+    throw Error(
+      `Cannot automatically create CoValue from value: ${JSON.stringify(init)}. Use the CoValue schema's create() method instead.`,
+    );
+  }
+  const owner = Group.create();
+  owner.addMember(parentOwner.castAs(Group));
+  // @ts-expect-error - create is a static method in all CoValue classes
+  return schema.ref.create(init, owner);
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type Schema = JsonEncoded | RefEncoded<CoValue> | EncodedAs<any>;
 

package/src/tools/implementation/zodSchema/schemaTypes/CoFeedSchema.ts

@@ -6,21 +6,16 @@ import {
   RefsToResolve,
   RefsToResolveStrict,
   Resolved,
-  Simplify,
   SubscribeListenerOptions,
   coOptionalDefiner,
 } from "../../../internal.js";
 import { AnonymousJazzAgent } from "../../anonymousJazzAgent.js";
-import { CoFieldInit } from "../typeConverters/CoFieldInit.js";
+import { CoFeedInit } from "../typeConverters/CoFieldInit.js";
 import { InstanceOrPrimitiveOfSchema } from "../typeConverters/InstanceOrPrimitiveOfSchema.js";
 import { InstanceOrPrimitiveOfSchemaCoValuesNullable } from "../typeConverters/InstanceOrPrimitiveOfSchemaCoValuesNullable.js";
 import { CoOptionalSchema } from "./CoOptionalSchema.js";
 import { CoreCoValueSchema } from "./CoValueSchema.js";
 
-type CoFeedInit<T extends AnyZodOrCoValueSchema> = Simplify<
-  Array<CoFieldInit<T>>
->;
-
 export class CoFeedSchema<T extends AnyZodOrCoValueSchema>
   implements CoreCoFeedSchema<T>
 {
@@ -36,7 +31,7 @@ export class CoFeedSchema<T extends AnyZodOrCoValueSchema>
     init: CoFeedInit<T>,
     options?: { owner: Account | Group } | Account | Group,
   ): CoFeedInstance<T> {
-    return this.coValueClass.create(init, options) as CoFeedInstance<T>;
+    return this.coValueClass.create(init as any, options) as CoFeedInstance<T>;
   }
 
   load<const R extends RefsToResolve<CoFeedInstanceCoValuesNullable<T>> = true>(

package/src/tools/implementation/zodSchema/schemaTypes/CoListSchema.ts

@@ -5,22 +5,17 @@ import {
   RefsToResolve,
   RefsToResolveStrict,
   Resolved,
-  Simplify,
   SubscribeListenerOptions,
   coOptionalDefiner,
 } from "../../../internal.js";
 import { AnonymousJazzAgent } from "../../anonymousJazzAgent.js";
-import { CoFieldInit } from "../typeConverters/CoFieldInit.js";
+import { CoListInit } from "../typeConverters/CoFieldInit.js";
 import { InstanceOrPrimitiveOfSchema } from "../typeConverters/InstanceOrPrimitiveOfSchema.js";
 import { InstanceOrPrimitiveOfSchemaCoValuesNullable } from "../typeConverters/InstanceOrPrimitiveOfSchemaCoValuesNullable.js";
 import { AnyZodOrCoValueSchema } from "../zodSchema.js";
 import { CoOptionalSchema } from "./CoOptionalSchema.js";
 import { CoreCoValueSchema } from "./CoValueSchema.js";
 
-type CoListInit<T extends AnyZodOrCoValueSchema> = Simplify<
-  Array<CoFieldInit<T>>
->;
-
 export class CoListSchema<T extends AnyZodOrCoValueSchema>
   implements CoreCoListSchema<T>
 {
@@ -36,7 +31,7 @@ export class CoListSchema<T extends AnyZodOrCoValueSchema>
     items: CoListInit<T>,
     options?: { owner: Account | Group } | Account | Group,
   ): CoListInstance<T> {
-    return this.coValueClass.create(items, options) as CoListInstance<T>;
+    return this.coValueClass.create(items as any, options) as CoListInstance<T>;
   }
 
   load<const R extends RefsToResolve<CoListInstanceCoValuesNullable<T>> = true>(