useWatch usage tracking and optimization

.changeset/itchy-pianos-wink.md

@@ -0,0 +1,5 @@
+---
+'@verdant-web/cli': patch
+---
+
+Adds typings for new useWatch option to disable usage tracking

.changeset/popular-games-promise.md

@@ -0,0 +1,5 @@
+---
+'@verdant-web/react': minor
+---
+
+Observe accessed keys of watched entities and only re-render the component when accessed keys change

package.json

@@ -31,7 +31,8 @@
 		"typescript": "^5.4.2"
 	},
 	"dependencies": {
-		"fake-indexeddb": "^5.0.1"
+		"fake-indexeddb": "^5.0.1",
+		"prettier": "^3.0.3"
 	},
 	"volta": {
 		"node": "18.17.0"

packages/cli/src/react.ts

@@ -93,7 +93,12 @@ export interface GeneratedHooks<Presence, Profile> {
   useSyncStatus: () => boolean;
 	useWatch<T extends AnyEntity<any, any, any> | null>(
     entity: T,
-		options?: { deep?: boolean },
+		options?: {
+			/** Observes changes to all sub-objects */
+			deep?: boolean,
+			/** Disables performance enhancements that prevent re-renders if the changed keys aren't used in the component */
+			untracked?: boolean,
+		},
   ): EntityDestructured<T>;
 	useWatch<T extends EntityFile | null>(
 		file: T

packages/cli/test/__snapshots__/generated.test.ts.snap

@@ -721,7 +721,12 @@ export interface GeneratedHooks<Presence, Profile> {
   useSyncStatus: () => boolean;
   useWatch<T extends AnyEntity<any, any, any> | null>(
     entity: T,
-    options?: { deep?: boolean },
+    options?: {
+      /** Observes changes to all sub-objects */
+      deep?: boolean;
+      /** Disables performance enhancements that prevent re-renders if the changed keys aren't used in the component */
+      untracked?: boolean;
+    },
   ): EntityDestructured<T>;
   useWatch<T extends EntityFile | null>(file: T): string | null;
   useOnChange<T extends AnyEntity<any, any, any> | null>(

packages/react/package.json

@@ -37,17 +37,19 @@
 	},
 	"dependencies": {
 		"@verdant-web/common": "workspace:*",
-		"suspend-react": "^0.0.8",
 		"use-sync-external-store": "^1.2.0"
 	},
 	"devDependencies": {
 		"@types/react": "^19.0.1",
 		"@types/use-sync-external-store": "^0.0.6",
 		"@verdant-web/store": "workspace:*",
+		"@vitest/browser": "^2.1.8",
 		"fake-indexeddb": "^5.0.1",
-		"jsdom": "^20.0.0",
+		"playwright": "^1.49.1",
+		"prettier": "^3.0.3",
 		"react": "^19.0.0",
 		"typescript": "^5.4.2",
-		"vitest": "^2.0.5"
+		"vitest": "^2.1.8",
+		"vitest-browser-react": "^0.0.4"
 	}
 }

packages/react/src/hooks.tsx

@@ -4,22 +4,22 @@ import {
 	StorageSchema,
 } from '@verdant-web/common';
 import {
-	Query,
-	SyncTransportMode,
-	StorageDescriptor,
-	UserInfo,
-	Entity,
+	Client,
 	ClientWithCollections,
+	Entity,
 	EntityFile,
-	Client,
+	Query,
 	QueryStatus,
+	StorageDescriptor,
+	SyncTransportMode,
+	UserInfo,
 } from '@verdant-web/store';
 import {
 	ChangeEvent,
 	createContext,
-	HTMLAttributes,
 	HTMLProps,
 	ReactNode,
+	use,
 	useCallback,
 	useContext,
 	useEffect,
@@ -28,16 +28,16 @@ import {
 	useState,
 	useSyncExternalStore,
 } from 'react';
-import { suspend } from 'suspend-react';
 import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/with-selector.js';
+import { useWatch } from './watch.js';
 
 function isQueryCurrentValid(query: Query<any>) {
 	return !(query.status === 'initial' || query.status === 'initializing');
 }
 function useLiveQuery(liveQuery: Query<any> | null, disableSuspense = false) {
 	// suspend if the query doesn't have a valid result set yet.
 	if (!disableSuspense && liveQuery && !isQueryCurrentValid(liveQuery)) {
-		suspend(() => liveQuery.resolved, [liveQuery]);
+		use(liveQuery.resolved);
 	}
 	return useSyncExternalStore(
 		(callback) => {
@@ -98,40 +98,7 @@ export function createHooks<Presence = any, Profile = any>(
 		if (!ctx) {
 			throw new Error('No verdant provider was found');
 		}
-		return suspend(() => ctx.readyPromise, ['lofi_' + ctx.namespace]) as any;
-	}
-
-	function useWatch(
-		liveObject: Entity | EntityFile | null,
-		options?: { deep?: boolean },
-	) {
-		return useSyncExternalStore(
-			(handler) => {
-				if (liveObject) {
-					if ('isFile' in liveObject) {
-						return liveObject.subscribe('change', handler);
-					} else {
-						if (options?.deep) {
-							return liveObject.subscribe('change', handler);
-						} else {
-							return liveObject.subscribe('change', handler);
-						}
-					}
-				}
-				return () => {};
-			},
-			() => {
-				if (liveObject) {
-					if (liveObject instanceof EntityFile) {
-						return liveObject.url;
-					} else {
-						return liveObject.getAll();
-					}
-				}
-
-				return undefined;
-			},
-		);
+		return use(ctx.readyPromise) as ClientWithCollections;
 	}
 
 	function useOnChange(
@@ -203,7 +170,7 @@ export function createHooks<Presence = any, Profile = any>(
 					unsubs.forEach((unsub) => unsub());
 				};
 			},
-			() => (peerId ? storage.sync.presence.peers[peerId] ?? null : null),
+			() => (peerId ? (storage.sync.presence.peers[peerId] ?? null) : null),
 		);
 	}
 
@@ -418,8 +385,8 @@ export function createHooks<Presence = any, Profile = any>(
 				fieldSchema.type === 'boolean'
 					? key
 					: value === null || value === undefined
-					? ''
-					: `${value}`;
+						? ''
+						: `${value}`;
 			const props: HTMLProps<HTMLInputElement> = {
 				onChange: (e: ChangeEvent<HTMLInputElement>) => {
 					if (fieldSchema.type === 'number') {
@@ -598,11 +565,13 @@ export function createHooks<Presence = any, Profile = any>(
 			value,
 			children,
 			sync,
+			fallback,
 			...rest
 		}: {
 			children?: ReactNode;
 			value: StorageDescriptor;
 			sync?: boolean;
+			fallback?: ReactNode;
 		}) => {
 			// auto-open storage when used in provider
 			useMemo(() => {
@@ -756,7 +725,7 @@ export function createHooks<Presence = any, Profile = any>(
 								pageSize,
 								page: 0,
 								key: key || getAllPaginatedHookName,
-						  }),
+							}),
 				[index, skip, pageSize],
 			);
 			const data = useLiveQuery(liveQuery, suspend === false);
@@ -809,7 +778,7 @@ export function createHooks<Presence = any, Profile = any>(
 								index,
 								pageSize,
 								key: key || getAllInfiniteHookName,
-						  }),
+							}),
 				[index, skip, pageSize],
 			);
 			const data = useLiveQuery(liveQuery, suspend === false);