Adopt Suspense for useLiveQuery

[FuJuntao]

Hi, I see there is no property like isLoading for useLiveQuery result.

I wonder if it is possible to adopt Suspense for useLiveQuery.

[dfahlander]

isLoading: The third argument to useLiveQuery() is a default value returned while loading. With IndexedDB, loading time is normally too short to make it feasible with fallback rendering. I normally just return null from the component while loading.

Examples:

export function FriendListComponent() {
  // When returning array, we can rely on the default and do not need to specify 3rd arg:
  const friends = useLiveQuery(() => db.friends.toArray());

  // A falsy result means we're still loading
  if (!friends) return null; // Initial render (is loading)

  return <ul>{
    friends.map(friend => <li key={friend.id}>{friend.name}</li>)
  }</ul>;
}

export function FriendDetailsComponent(friendId) {
   const friend = useLiveQuery(
     () => db.friends.get(friendId), // This query may return undefined!
     [friendId], // Deps
     null // Specify fallback distinguished from not-found result.
   );

   if (friend === null) return null; // Initial render (is loading)

   if (friend === undefined) return <p>Friend not found</p>; // Not found.

   return <div>
     <p>Name: {friend.name}</p>
     <p>Age: {friend.age}</p>
   </div>;
}

Suspense support: We might support a suspense based useLiveQuery in future. That would require a DBCore caching middleware that is capable of caching all responses including IDBCoreCursors - which in turn would require a virtual cursor ("CachedCursor" or how to name it) to be implemented that will behave just like the original cursor. So, it's doable but not super straightforward to implement.

[FuJuntao]

Sounds like a lot of thoughts and works, but I still think it's a nice to have feature. Hopefully there will be time for implementing this.

[bioshazard]

The default return worked well for me. I used a Symbol tho in case there are an cases where Dexie would legitimately return null. eg,

import { useLiveQuery } from 'dexie-react-hooks';
import db from 'lib/db';

// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol
const dexieLoading = Symbol()

export default function useSettingDexie({ name, defaultValue }) {
  const liveQuery = useLiveQuery(
    () => db.settings.get({ name }),
    [name],
    dexieLoading // default to unique "loading" symbol
  )
  const loading = liveQuery === dexieLoading
  const value = loading ? undefined // return `undefined` if still loading...
    : liveQuery === undefined // after loading, if query is undefined... it means 404 from Dexie
      ? defaultValue // relay the default value
      : liveQuery.value // otherwise, relay the query value itself

  const save = async (value) => await db.settings.put({ name, value });

  return {
    liveQuery,
    loading,
    value,
    save
  }
}

[mutewinter]

Here's my approach for adding Suspense support to liveQuery using Jotai. I also added a cache to ensure the minimal amount of observables are created.

// utils/useSuspenseLiveQuery.ts
import { liveQuery } from 'dexie';
import { type Atom, useAtomValue } from 'jotai';
import { atomWithObservable } from 'jotai/utils';
import { useRef } from 'react';

// Must use a global cache because Suspense breaks the rules of hooks like
// useMemo and useRef
// https://github.com/facebook/react/issues/15137
// eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-redundant-type-constituents
const CACHE = new Map<string, Atom<any | Promise<any>> | undefined>();

// Cache for 5 minutes, which was inspired by TanStack Query
const CACHE_ITEM_LIFESPAN_MS = 1000 * 60 * 5;

type CacheKey = string | number;
// Force at least one cache key past the `use` prefixed key to ensure that
// using useSuspenseLiveQuery is necessary vs a global atom.
type CacheKeys<T = CacheKey> = [`use${string}`, T, ...T[]];

type InitialValue<Data> = Data | (() => Data);

// A suspense-enabled version of useLiveQuery from Dexie
export default function useSuspenseLiveQuery<T>(
  querier: () => Promise<T> | T,
  cacheKeys: CacheKeys,
): T | undefined;
export default function useSuspenseLiveQuery<T, U extends InitialValue<T>>(
  querier: () => Promise<T> | T,
  cacheKeys: CacheKeys,
  initialValue: U,
): T | U;
export default function useSuspenseLiveQuery<T, U extends InitialValue<T>>(
  querier: () => Promise<T> | T,
  cacheKeys: CacheKeys,
  initialValue?: U,
): T | U {
  const cacheKey = cacheKeys.join(':');
  const atomRef = useRef<[string, Atom<T | Promise<T>> | undefined]>([
    cacheKey,
    CACHE.get(cacheKey),
  ]);

  // Look for atom in cache
  if (atomRef.current[0] !== cacheKey) {
    atomRef.current = [cacheKey, CACHE.get(cacheKey)];
  }

  // Atom not in cache
  if (!atomRef.current[1]) {
    const newAtom = atomWithObservable<T>(
      () => liveQuery(querier),
      initialValue ? { initialValue } : undefined,
    );
    if (process.env.NODE_ENV === 'development') {
      newAtom.debugLabel = cacheKey;
    }
    atomRef.current = [cacheKey, newAtom];
    CACHE.set(cacheKey, newAtom);

    // Remove from cache after a timeout to allow for garbage collection
    setTimeout(() => {
      CACHE.delete(cacheKey);
    }, CACHE_ITEM_LIFESPAN_MS);
  }

  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
  return useAtomValue(atomRef.current[1]!);
}

Example Use

// store/sessions.ts
export function useSession(sessionId: SessionId) {
  return useSuspenseLiveQuery(
    () => db.sessions.get(sessionId),
    ['useSession', sessionId],
  );
}

[mutewinter]

You can also use Jotai for atoms that don't need any params like so:

import { liveQuery } from 'dexie';
import { useAtomValue } from 'jotai';
import { atomFamily, atomWithObservable } from 'jotai/utils';

const sessionsByUpdatedAtAtom = atomWithObservable(() =>
  liveQuery(() => db.sessions.orderBy('updatedAt').reverse().toArray()),
);

export function useSessionsByUpdatedAt() {
  return useAtomValue(sessionsByUpdatedAtAtom);
}