Merge pull request #3237 from garden-co/feat/suspense

feat: suspense hooks

Author: gdorsi

.changeset/real-pants-wait.md

@@ -0,0 +1,5 @@
+---
+"jazz-tools": patch
+---
+
+Added Suspense hooks for React and implemented subscription deduplication for React hooks

examples/music-player/src/3_HomePage.tsx

@@ -1,4 +1,3 @@
-import { useCoState } from "jazz-tools/react";
 import { useParams } from "react-router";
 import { PlaylistWithTracks } from "./1_schema";
 import { uploadMusicTracks } from "./4_actions";
@@ -15,6 +14,7 @@ import { SidebarInset, SidebarTrigger } from "./components/ui/sidebar";
 import { usePlayState } from "./lib/audio/usePlayState";
 import { useState } from "react";
 import { useAccountSelector } from "@/components/AccountProvider.tsx";
+import { useSuspenseCoState } from "jazz-tools/react-core";
 
 export function HomePage({ mediaPlayer }: { mediaPlayer: MediaPlayer }) {
   const playState = usePlayState();
@@ -32,16 +32,12 @@ export function HomePage({ mediaPlayer }: { mediaPlayer: MediaPlayer }) {
 
   const params = useParams<{ playlistId: string }>();
   const playlistId = useAccountSelector({
-    select: (me) =>
-      params.playlistId ??
-      (me.$isLoaded ? me.root.$jazz.refs.rootPlaylist.id : undefined),
+    select: (me) => params.playlistId ?? me.root.$jazz.refs.rootPlaylist.id,
   });
 
-  const playlist = useCoState(PlaylistWithTracks, playlistId, {
-    select: (playlist) => (playlist.$isLoaded ? playlist : undefined),
-  });
+  const playlist = useSuspenseCoState(PlaylistWithTracks, playlistId);
 
-  const membersIds = playlist?.$jazz.owner.members.map((member) => member.id);
+  const membersIds = playlist.$jazz.owner.members.map((member) => member.id);
   const isRootPlaylist = !params.playlistId;
   const canEdit = useAccountSelector({
     select: (me) => Boolean(playlist && me.canWrite(playlist)),

examples/music-player/src/5_useMediaPlayer.ts

@@ -15,8 +15,7 @@ export function useMediaPlayer() {
   const [loading, setLoading] = useState<string | null>(null);
 
   const activeTrackId = useAccountSelector({
-    select: (me) =>
-      me.$isLoaded ? me.root.$jazz.refs.activeTrack?.id : undefined,
+    select: (me) => me.root.$jazz.refs.activeTrack?.id,
   });
   // Reference used to avoid out-of-order track loads
   const lastLoadedTrackId = useRef<string | null>(null);

examples/music-player/src/components/AuthModal.tsx

@@ -19,7 +19,7 @@ export function AuthModal({ open, onOpenChange }: AuthModalProps) {
   const [isSignUp, setIsSignUp] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const profileName = useAccountSelector({
-    select: (me) => (me.$isLoaded ? me.profile.name : undefined),
+    select: (me) => me.profile.name,
   });
 
   const auth = usePasskeyAuth({
@@ -59,7 +59,6 @@ export function AuthModal({ open, onOpenChange }: AuthModalProps) {
   const shouldShowTransferRootPlaylist = useAccountSelector({
     select: (me) =>
       !isSignUp &&
-      me.$isLoaded &&
       me.root.rootPlaylist.tracks.some((track) => !track.isExampleTrack),
   });
 

examples/music-player/src/components/MusicTrackRow.tsx

@@ -16,13 +16,13 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { cn } from "@/lib/utils";
-import { useAccount, useCoState } from "jazz-tools/react";
 import { MoreHorizontal, Pause, Play } from "lucide-react";
-import { Fragment, useCallback, useState } from "react";
+import { Fragment, Suspense, useCallback, useState } from "react";
 import { EditTrackDialog } from "./RenameTrackDialog";
 import { Waveform } from "./Waveform";
 import { Button } from "./ui/button";
 import { useAccountSelector } from "@/components/AccountProvider.tsx";
+import { useSuspenseCoState, useSuspenseAccount } from "jazz-tools/react";
 
 function isPartOfThePlaylist(trackId: string, playlist: PlaylistWithTracks) {
   return Array.from(playlist.tracks.$jazz.refs).some((t) => t.id === trackId);
@@ -39,43 +39,32 @@ export function MusicTrackRow({
   onClick: (track: MusicTrack) => void;
   index: number;
 }) {
-  const track = useCoState(MusicTrack, trackId);
+  const track = useSuspenseCoState(MusicTrack, trackId);
   const [isEditDialogOpen, setIsEditDialogOpen] = useState(false);
   const [isDropdownOpen, setIsDropdownOpen] = useState(false);
   const [isHovered, setIsHovered] = useState(false);
 
-  const playlists = useAccount(MusicaAccountWithPlaylists, {
-    select: (account) =>
-      account.$isLoaded && account.root.playlists.$isLoaded
-        ? account.root.playlists
-        : undefined,
-  });
-
   const isActiveTrack = useAccountSelector({
-    select: (me) => me.$isLoaded && me.root.activeTrack?.$jazz.id === trackId,
+    select: (me) => me.root.activeTrack?.$jazz.id === trackId,
   });
 
   const canEditTrack = useAccountSelector({
-    select: (me) => me.$isLoaded && track.$isLoaded && me.canWrite(track),
+    select: (me) => me.canWrite(track),
   });
 
   function handleTrackClick() {
-    if (!track.$isLoaded) return;
     onClick(track);
   }
 
   function handleAddToPlaylist(playlist: Playlist) {
-    if (!track.$isLoaded) return;
     addTrackToPlaylist(playlist, track);
   }
 
   function handleRemoveFromPlaylist(playlist: Playlist) {
-    if (!track.$isLoaded) return;
     removeTrackFromPlaylist(playlist, track);
   }
 
   function deleteTrack() {
-    if (!track.$isLoaded) return;
     removeTrackFromAllPlaylists(track);
   }
 
@@ -89,7 +78,6 @@ export function MusicTrackRow({
   }, []);
 
   const showWaveform = isHovered || isActiveTrack;
-  const trackTitle = track.$isLoaded ? track.title : "";
 
   return (
     <li
@@ -112,7 +100,7 @@ export function MusicTrackRow({
           isActiveTrack && "md:opacity-100 opacity-100",
         )}
         onClick={handleTrackClick}
-        aria-label={`${isPlaying ? "Pause" : "Play"} ${trackTitle}`}
+        aria-label={`${isPlaying ? "Pause" : "Play"} ${track.title}`}
       >
         {isPlaying ? (
           <Pause height={16} width={16} fill="currentColor" />
@@ -133,11 +121,11 @@ export function MusicTrackRow({
         onClick={handleTrackClick}
         className="flex items-center overflow-hidden text-ellipsis whitespace-nowrap cursor-pointer flex-1 min-w-0"
       >
-        {trackTitle}
+        {track.title}
       </button>
 
       {/* Waveform that appears on hover */}
-      {track.$isLoaded && showWaveform && (
+      {showWaveform && (
         <div className="flex-1 min-w-0 px-2 items-center hidden md:flex">
           <Waveform
             track={track}
@@ -155,40 +143,28 @@ export function MusicTrackRow({
               <Button
                 variant="ghost"
                 className="h-8 w-8 p-0"
-                aria-label={`Open ${trackTitle} menu`}
+                aria-label={`Open ${track.title} menu`}
               >
                 <span className="sr-only">Open menu</span>
                 <MoreHorizontal className="h-4 w-4" />
               </Button>
             </DropdownMenuTrigger>
-            <DropdownMenuContent align="end">
-              <DropdownMenuItem onSelect={handleEdit}>Edit</DropdownMenuItem>
-              {playlists
-                ?.filter((playlist) => playlist.$isLoaded)
-                .map((playlist, playlistIndex) => (
-                  <Fragment key={playlistIndex}>
-                    {isPartOfThePlaylist(trackId, playlist) ? (
-                      <DropdownMenuItem
-                        key={`remove-${playlistIndex}`}
-                        onSelect={() => handleRemoveFromPlaylist(playlist)}
-                      >
-                        Remove from {playlist.title}
-                      </DropdownMenuItem>
-                    ) : (
-                      <DropdownMenuItem
-                        key={`add-${playlistIndex}`}
-                        onSelect={() => handleAddToPlaylist(playlist)}
-                      >
-                        Add to {playlist.title}
-                      </DropdownMenuItem>
-                    )}
-                  </Fragment>
-                ))}
-            </DropdownMenuContent>
+            <Suspense>
+              <DropdownMenuContent align="end">
+                <DropdownMenuItem onSelect={handleEdit}>Edit</DropdownMenuItem>
+                <PlaylistItems
+                  onRemove={handleRemoveFromPlaylist}
+                  onAdd={handleAddToPlaylist}
+                  isPartOfThePlaylist={(playlist) =>
+                    isPartOfThePlaylist(trackId, playlist)
+                  }
+                />
+              </DropdownMenuContent>
+            </Suspense>
           </DropdownMenu>
         </div>
       )}
-      {track.$isLoaded && isEditDialogOpen && (
+      {isEditDialogOpen && (
         <EditTrackDialog
           track={track}
           isOpen={isEditDialogOpen}
@@ -199,3 +175,33 @@ export function MusicTrackRow({
     </li>
   );
 }
+
+function PlaylistItems(props: {
+  onRemove: (playlist: PlaylistWithTracks) => void;
+  onAdd: (playlist: PlaylistWithTracks) => void;
+  isPartOfThePlaylist: (playlist: PlaylistWithTracks) => boolean;
+}) {
+  const playlists = useSuspenseAccount(MusicaAccountWithPlaylists, {
+    select: (account) => account.root.playlists,
+  });
+
+  const loadedPlaylists = playlists.filter((playlist) => playlist.$isLoaded);
+
+  return (
+    <>
+      {loadedPlaylists.map((playlist, playlistIndex) => (
+        <Fragment key={playlistIndex}>
+          {props.isPartOfThePlaylist(playlist) ? (
+            <DropdownMenuItem onSelect={() => props.onRemove(playlist)}>
+              Remove from {playlist.title}
+            </DropdownMenuItem>
+          ) : (
+            <DropdownMenuItem onSelect={() => props.onAdd(playlist)}>
+              Add to {playlist.title}
+            </DropdownMenuItem>
+          )}
+        </Fragment>
+      ))}
+    </>
+  );
+}

examples/music-player/src/components/PlayerControls.tsx

@@ -15,7 +15,7 @@ export function PlayerControls({ mediaPlayer }: { mediaPlayer: MediaPlayer }) {
 
   const activePlaylistTitle = useAccountSelector({
     select: (me) =>
-      me.$isLoaded && me.root.activePlaylist?.$isLoaded
+      me.root.activePlaylist?.$isLoaded
         ? (me.root.activePlaylist.title ?? "All tracks")
         : "All tracks",
   });

examples/music-player/src/components/ProfileForm.tsx

@@ -34,7 +34,7 @@ export function ProfileForm({
   className = "",
 }: ProfileFormProps) {
   const profile = useAccountSelector({
-    select: (me) => (me.$isLoaded ? me.profile : undefined),
+    select: (me) => me.profile,
   });
 
   const [username, setUsername] = useState(

examples/music-player/src/components/WelcomeScreen.tsx

@@ -9,20 +9,17 @@ export function WelcomeScreen() {
   });
 
   const { handleCompleteSetup } = useAccountSelector({
-    select: (me) =>
-      me.$isLoaded
-        ? {
-            id: me.root.$jazz.id,
-            handleCompleteSetup: () => {
-              me.root.$jazz.set("accountSetupCompleted", true);
-            },
-          }
-        : { id: null, handleCompleteSetup: null },
+    select: (me) => ({
+      id: me.root.$jazz.id,
+      handleCompleteSetup: () => {
+        me.root.$jazz.set("accountSetupCompleted", true);
+      },
+    }),
     equalityFn: (a, b) => a.id === b.id,
   });
 
   const initialUsername = useAccountSelector({
-    select: (me) => (me.$isLoaded ? me.profile.name : undefined),
+    select: (me) => me.profile.name,
   });
 
   if (!handleCompleteSetup) return null;

packages/cojson/src/exports.ts

@@ -6,7 +6,10 @@ import {
   enablePermissionErrors,
   type AvailableCoValueCore,
 } from "./coValueCore/coValueCore.js";
-import { CoValueUniqueness } from "./coValueCore/verifiedState.js";
+import {
+  CoValueHeader,
+  CoValueUniqueness,
+} from "./coValueCore/verifiedState.js";
 import {
   ControlledAccount,
   ControlledAgent,
@@ -78,7 +81,9 @@ import { getDependedOnCoValuesFromRawData } from "./coValueCore/utils.js";
 import {
   CO_VALUE_LOADING_CONFIG,
   TRANSACTION_CONFIG,
+  setCoValueLoadingMaxRetries,
   setCoValueLoadingRetryDelay,
+  setCoValueLoadingTimeout,
   setIncomingMessagesTimeBudget,
   setMaxRecommendedTxSize,
 } from "./config.js";
@@ -118,6 +123,8 @@ export const cojsonInternals = {
   CO_VALUE_PRIORITY,
   setIncomingMessagesTimeBudget,
   setCoValueLoadingRetryDelay,
+  setCoValueLoadingMaxRetries,
+  setCoValueLoadingTimeout,
   ConnectedPeerChannel,
   textEncoder,
   textDecoder,
@@ -186,6 +193,7 @@ export type {
   AccountRole,
   AvailableCoValueCore,
   PeerState,
+  CoValueHeader,
 };
 
 export * from "./storage/index.js";

packages/cojson/src/localNode.ts

@@ -31,7 +31,7 @@ import {
 } from "./coValues/group.js";
 import { CO_VALUE_LOADING_CONFIG } from "./config.js";
 import { AgentSecret, CryptoProvider } from "./crypto/crypto.js";
-import { AgentID, RawCoID, SessionID, isAgentID } from "./ids.js";
+import { AgentID, RawCoID, SessionID, isAgentID, isRawCoID } from "./ids.js";
 import { logger } from "./logger.js";
 import { StorageAPI } from "./storage/index.js";
 import { Peer, PeerID, SyncManager } from "./sync.js";
@@ -387,13 +387,17 @@ export class LocalNode {
     return coValue;
   }
 
+  hasLoadingSources(id: RawCoID) {
+    return this.storage || this.syncManager.getServerPeers(id).length > 0;
+  }
+
   /** @internal */
   async loadCoValueCore(
     id: RawCoID,
     skipLoadingFromPeer?: PeerID,
     skipRetry?: boolean,
   ): Promise<CoValueCore> {
-    if (typeof id !== "string" || !id.startsWith("co_z")) {
+    if (!isRawCoID(id)) {
       throw new TypeError(
         `Trying to load CoValue with invalid id ${Array.isArray(id) ? JSON.stringify(id) : id}`,
       );
@@ -421,6 +425,8 @@ export class LocalNode {
         const peers = this.syncManager.getServerPeers(id, skipLoadingFromPeer);
 
         if (!this.storage && peers.length === 0) {
+          // Flags the coValue as unavailable
+          coValue.markNotFoundInPeer("storage");
           return coValue;
         }