jazz-tools 0.19.8 → 0.19.10

package/src/react-core/hooks.ts

@@ -23,11 +23,11 @@ import {
   Loaded,
   MaybeLoaded,
   NotLoaded,
+  RefsToResolve,
   ResolveQuery,
   ResolveQueryStrict,
   SchemaResolveQuery,
   SubscriptionScope,
-  coValueClassFromCoValueClassOrSchema,
   importContentPieces,
   captureStack,
   getUnloadedCoValueWithoutId,
@@ -36,6 +36,7 @@ import {
 import { JazzContext, JazzContextManagerContext } from "./provider.js";
 import { getCurrentAccountFromContextManager } from "./utils.js";
 import { CoValueSubscription } from "./types.js";
+import { use } from "./use.js";
 
 export function useJazzContext<Acc extends Account>() {
   const value = useContext(JazzContext) as JazzContextType<Acc>;
@@ -134,20 +135,22 @@ export function useCoValueSubscription<
     const resolve = getResolveQuery(Schema, options?.resolve);
 
     const node = contextManager.getCurrentValue()!.node;
-    const subscription = new SubscriptionScope<any>(
+    const cache = contextManager.getSubscriptionScopeCache();
+    const subscription = cache.getOrCreate(
       node,
-      resolve,
+      Schema,
       id,
-      {
-        ref: coValueClassFromCoValueClassOrSchema(Schema),
-        optional: true,
-      },
+      resolve,
       false,
       false,
       options?.unstable_branch,
-      callerStack.current,
     );
 
+    // Set callerStack on returned subscription after retrieval
+    if (callerStack.current) {
+      subscription.callerStack = callerStack.current;
+    }
+
     return {
       value: subscription,
       contextManager,
@@ -182,7 +185,6 @@ export function useCoValueSubscription<
     subscription.branchOwnerId !== branchOwnerId ||
     subscription.agent !== agent
   ) {
-    subscription.value?.destroy();
     subscriptionRef.current = createSubscription();
     subscription = subscriptionRef.current;
   }
@@ -442,6 +444,79 @@ export function useCoState<
   return value;
 }
 
+export function useSuspenseCoState<
+  S extends CoValueClassOrSchema,
+  // @ts-expect-error we can't statically enforce the schema's resolve query is a valid resolve query, but in practice it is
+  const R extends ResolveQuery<S> = SchemaResolveQuery<S>,
+  TSelectorReturn = Loaded<S, R>,
+>(
+  /** The CoValue schema or class constructor */
+  Schema: S,
+  /** The ID of the CoValue to subscribe to */
+  id: string,
+  /** Optional configuration for the subscription */
+  options?: {
+    /** Resolve query to specify which nested CoValues to load */
+    resolve?: ResolveQueryStrict<S, R>;
+    /** Select which value to return */
+    select?: (value: Loaded<S, R>) => TSelectorReturn;
+    /** Equality function to determine if the selected value has changed, defaults to `Object.is` */
+    equalityFn?: (a: TSelectorReturn, b: TSelectorReturn) => boolean;
+    /**
+     * Create or load a branch for isolated editing.
+     *
+     * Branching lets you take a snapshot of the current state and start modifying it without affecting the canonical/shared version.
+     * It's a fork of your data graph: the same schema, but with diverging values.
+     *
+     * The checkout of the branch is applied on all the resolved values.
+     *
+     * @param name - A unique name for the branch. This identifies the branch
+     *   and can be used to switch between different branches of the same CoValue.
+     * @param owner - The owner of the branch. Determines who can access and modify
+     *   the branch. If not provided, the branch is owned by the current user.
+     *
+     * For more info see the [branching](https://jazz.tools/docs/react/using-covalues/version-control) documentation.
+     */
+    unstable_branch?: BranchDefinition;
+    preloaded?: ExportedCoValue<Loaded<S, R>>;
+  },
+): TSelectorReturn {
+  useImportCoValueContent(id, options?.preloaded);
+
+  const subscription = useCoValueSubscription(Schema, id, options);
+
+  if (!subscription) {
+    throw new Error("Subscription not found");
+  }
+
+  use(subscription.getPromise());
+
+  const getCurrentValue = () => {
+    const value = subscription.getCurrentValue();
+
+    if (!value.$isLoaded) {
+      throw new Error("CoValue must be loaded in a suspense context");
+    }
+
+    return value;
+  };
+
+  const value = useSyncExternalStoreWithSelector<Loaded<S, R>, TSelectorReturn>(
+    React.useCallback(
+      (callback) => {
+        return subscription.subscribe(callback);
+      },
+      [subscription],
+    ),
+    getCurrentValue,
+    getCurrentValue,
+    options?.select ?? ((value) => value as TSelectorReturn),
+    options?.equalityFn ?? Object.is,
+  );
+
+  return value;
+}
+
 export function useSubscriptionSelector<
   S extends CoValueClassOrSchema,
   // @ts-expect-error we can't statically enforce the schema's resolve query is a valid resolve query, but in practice it is
@@ -510,20 +585,22 @@ export function useAccountSubscription<
     const resolve = getResolveQuery(Schema, options?.resolve);
 
     const node = contextManager.getCurrentValue()!.node;
-    const subscription = new SubscriptionScope<any>(
+    const cache = contextManager.getSubscriptionScopeCache();
+    const subscription = cache.getOrCreate(
       node,
-      resolve,
+      Schema,
       agent.$jazz.id,
-      {
-        ref: coValueClassFromCoValueClassOrSchema(Schema),
-        optional: true,
-      },
+      resolve,
       false,
       false,
       options?.unstable_branch,
-      callerStack.current,
     );
 
+    // Set callerStack on returned subscription after retrieval
+    if (callerStack.current) {
+      subscription.callerStack = callerStack.current;
+    }
+
     return {
       subscription,
       contextManager,
@@ -545,12 +622,12 @@ export function useAccountSubscription<
       subscription.branchName !== options?.unstable_branch?.name ||
       subscription.branchOwnerId !== options?.unstable_branch?.owner?.$jazz.id
     ) {
-      subscription.subscription?.destroy();
+      // No need to manually destroy - cache handles cleanup via SubscriptionScope lifecycle
       setSubscription(createSubscription());
     }
 
     return contextManager.subscribe(() => {
-      subscription.subscription?.destroy();
+      // No need to manually destroy - cache handles cleanup via SubscriptionScope lifecycle
       setSubscription(createSubscription());
     });
   }, [Schema, contextManager, branchName, branchOwnerId]);
@@ -705,6 +782,78 @@ export function useAccount<
   );
 }
 
+export function useSuspenseAccount<
+  A extends AccountClass<Account> | AnyAccountSchema,
+  // @ts-expect-error we can't statically enforce the schema's resolve query is a valid resolve query, but in practice it is
+  const R extends ResolveQuery<A> = SchemaResolveQuery<A>,
+  TSelectorReturn = Loaded<A, R>,
+>(
+  /** 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>;
+    /** Select which value to return from the account data */
+    select?: (account: Loaded<A, R>) => TSelectorReturn;
+    /** Equality function to determine if the selected value has changed, defaults to `Object.is` */
+    equalityFn?: (a: TSelectorReturn, b: TSelectorReturn) => boolean;
+    /**
+     * Create or load a branch for isolated editing.
+     *
+     * Branching lets you take a snapshot of the current state and start modifying it without affecting the canonical/shared version.
+     * It's a fork of your data graph: the same schema, but with diverging values.
+     *
+     * The checkout of the branch is applied on all the resolved values.
+     *
+     * @param name - A unique name for the branch. This identifies the branch
+     *   and can be used to switch between different branches of the same CoValue.
+     * @param owner - The owner of the branch. Determines who can access and modify
+     *   the branch. If not provided, the branch is owned by the current user.
+     *
+     * For more info see the [branching](https://jazz.tools/docs/react/using-covalues/version-control) documentation.
+     */
+    unstable_branch?: BranchDefinition;
+  },
+): TSelectorReturn {
+  const subscription = useAccountSubscription(AccountSchema, options);
+
+  if (!subscription) {
+    throw new Error(
+      "Subscription not found, are you using useSuspenseAccount in guest mode?",
+    );
+  }
+
+  use(subscription.getPromise());
+
+  const getCurrentValue = () => {
+    const value = subscription.getCurrentValue();
+
+    if (!value.$isLoaded) {
+      throw new Error("Account must be loaded in a suspense context");
+    }
+
+    return value;
+  };
+
+  return useSyncExternalStoreWithSelector<Loaded<A, R>, TSelectorReturn>(
+    React.useCallback(
+      (callback) => {
+        if (!subscription) {
+          return () => {};
+        }
+
+        return subscription.subscribe(callback);
+      },
+      [subscription],
+    ),
+    getCurrentValue,
+    getCurrentValue,
+    options?.select ?? ((value) => value as TSelectorReturn),
+    options?.equalityFn ?? Object.is,
+  );
+}
+
 /**
  * Returns a function for logging out of the current account.
  */

package/src/react-core/tests/createCoValueSubscriptionContext.test.tsx

@@ -164,15 +164,31 @@ describe("createCoValueSubscriptionContext", () => {
   });
 
   it("the provider shows a loading fallback when loading the coValue", async () => {
+    await setupJazzTestSync({
+      asyncPeers: true,
+    });
+
     const TestMap = co.map({
       value: z.string(),
     });
 
+    const map = TestMap.create({
+      value: "123",
+    });
+
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
     const { Provider } = createCoValueSubscriptionContext(TestMap);
 
     const { container } = render(
       <JazzTestProvider>
-        <Provider id="co_test123" loadingFallback={<div>Loading...</div>}>
+        <Provider
+          id={map.$jazz.id}
+          loadingFallback={<div>Loading...</div>}
+          unavailableFallback={<div>Unavailable</div>}
+        >
           <div>Children should not render</div>
         </Provider>
       </JazzTestProvider>,
@@ -203,13 +219,7 @@ describe("createCoValueSubscriptionContext", () => {
       </JazzTestProvider>,
     );
 
-    // Initially shows loading fallback
-    expect(container.textContent).toContain("Loading...");
-
-    // Should show unavailable fallback after CoValue load timeout
-    await waitFor(() => {
-      expect(container.textContent).toContain("Unavailable");
-    });
+    expect(container.textContent).toContain("Unavailable");
 
     // Children should never be rendered
     expect(container.textContent).not.toContain("Children should not render");

package/src/react-core/tests/testUtils.tsx

@@ -4,9 +4,12 @@ import {
   render,
   renderHook,
 } from "@testing-library/react";
-import { Account, AnonymousJazzAgent, AuthSecretStorage } from "jazz-tools";
+import { Account, AnonymousJazzAgent } from "jazz-tools";
 import React from "react";
 import { JazzTestProvider } from "../testing.js";
+import { getSqliteStorageAsync, SQLiteDatabaseDriverAsync } from "cojson";
+import Database, { type Database as DatabaseT } from "libsql";
+import { onTestFinished } from "vitest";
 
 type JazzExtendedOptions = {
   account?: Account | { guest: AnonymousJazzAgent };
@@ -23,12 +26,16 @@ const customRender = (
         account={options.account}
         isAuthenticated={options.isAuthenticated}
       >
-        {children}
+        {options.wrapper ? (
+          <options.wrapper>{children}</options.wrapper>
+        ) : (
+          children
+        )}
       </JazzTestProvider>
     );
   };
 
-  return render(ui, { wrapper: AllTheProviders, ...options });
+  return render(ui, { ...options, wrapper: AllTheProviders });
 };
 
 const customRenderHook = <TProps, TResult>(
@@ -41,12 +48,16 @@ const customRenderHook = <TProps, TResult>(
         account={options.account}
         isAuthenticated={options.isAuthenticated}
       >
-        {children}
+        {options.wrapper ? (
+          <options.wrapper>{children}</options.wrapper>
+        ) : (
+          children
+        )}
       </JazzTestProvider>
     );
   };
 
-  return renderHook(callback, { wrapper: AllTheProviders, ...options });
+  return renderHook(callback, { ...options, wrapper: AllTheProviders });
 };
 
 // re-export everything
@@ -55,3 +66,54 @@ export * from "@testing-library/react";
 // override render method
 export { customRender as render };
 export { customRenderHook as renderHook };
+
+class LibSQLSqliteAsyncDriver implements SQLiteDatabaseDriverAsync {
+  private readonly db: DatabaseT;
+
+  constructor(filename: string) {
+    this.db = new Database(filename, {});
+  }
+
+  async initialize() {
+    await this.db.pragma("journal_mode = WAL");
+  }
+
+  async run(sql: string, params: unknown[]) {
+    this.db.prepare(sql).run(params);
+  }
+
+  async query<T>(sql: string, params: unknown[]): Promise<T[]> {
+    return this.db.prepare(sql).all(params) as T[];
+  }
+
+  async get<T>(sql: string, params: unknown[]): Promise<T | undefined> {
+    return this.db.prepare(sql).get(params) as T | undefined;
+  }
+
+  async transaction(callback: () => unknown) {
+    await this.run("BEGIN TRANSACTION", []);
+
+    try {
+      await callback();
+      await this.run("COMMIT", []);
+    } catch (error) {
+      await this.run("ROLLBACK", []);
+    }
+  }
+
+  async closeDb() {
+    this.db.close();
+  }
+}
+
+export async function createAsyncStorage() {
+  const storage = await getSqliteStorageAsync(
+    new LibSQLSqliteAsyncDriver(":memory:"),
+  );
+
+  onTestFinished(() => {
+    storage.close();
+  });
+
+  return storage;
+}

package/src/react-core/tests/useCoState.test.ts

@@ -64,13 +64,9 @@ describe("useCoState", () => {
       account,
     });
 
-    expect(result.current.$jazz.loadingState).toBe(CoValueLoadingState.LOADING);
-
-    await waitFor(() => {
-      expect(result.current.$jazz.loadingState).toBe(
-        CoValueLoadingState.UNAVAILABLE,
-      );
-    });
+    expect(result.current.$jazz.loadingState).toBe(
+      CoValueLoadingState.UNAVAILABLE,
+    );
   });
 
   it("should update the value when the coValue changes", async () => {

package/src/react-core/tests/useSubscriptionSelector.test.ts

@@ -89,13 +89,9 @@ describe("useSubscriptionSelector", () => {
       return useSubscriptionSelector(subscription);
     });
 
-    expect(result.current.$jazz.loadingState).toBe(CoValueLoadingState.LOADING);
-
-    await waitFor(() => {
-      expect(result.current.$jazz.loadingState).toBe(
-        CoValueLoadingState.UNAVAILABLE,
-      );
-    });
+    expect(result.current.$jazz.loadingState).toBe(
+      CoValueLoadingState.UNAVAILABLE,
+    );
   });
 
   it("should return coAccount", async () => {