feat: useSuspendingLiveQuery

addons/y-dexie/package.json

@@ -8,7 +8,7 @@
   "exports": {
     ".": {
       "import": "./dist/y-dexie.js",
-      "require": false
+      "require": null
     }
   },
   "types": "dist/y-dexie.d.ts",

libs/dexie-react-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexie-react-hooks",
-  "version": "4.2.0",
+  "version": "4.2.1-alpha.1",
   "description": "React hooks for reactive data fetching using Dexie.js",
   "main": "dist/dexie-react-hooks.js",
   "typings": "dist/dexie-react-hooks.d.ts",
@@ -63,12 +63,13 @@
     "@rollup/plugin-node-resolve": "^11.1.1",
     "@rollup/plugin-typescript": "^8.1.1",
     "@types/qunit": "^2.9.6",
-    "@types/react": "^17.0.0",
-    "@types/react-dom": "^17.0.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.1",
+    "dexie": "workspace:>=4.2.0-alpha.1 <5.0.0",
     "just-build": "^0.9.24",
     "qunit": "^2.12.0",
-    "react": "^17.0.1",
-    "react-dom": "^17.0.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "rollup": "^2.40.0",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-commonjs": "^10.1.0",
@@ -78,7 +79,6 @@
     "typescript": "^5.3.3",
     "webpack": "^5.74.0",
     "webpack-cli": "^4.5.0",
-    "dexie": "workspace:>=4.2.0-alpha.1 <5.0.0",
     "y-dexie": "workspace:>=4.2.0-alpha.1 <5.0.0",
     "yjs": "^13.6.27"
   }

libs/dexie-react-hooks/src/dexie-react-hooks.ts

@@ -1,4 +1,6 @@
 export * from './useLiveQuery';
 export * from './useObservable';
 export * from './usePermissions';
-export * from './useDocument';
+export * from './useDocument';
+export * from './useSuspendingLiveQuery';
+export * from './useSuspendingObservable';

libs/dexie-react-hooks/src/types/y-dexie.d.ts

@@ -0,0 +1,28 @@
+// Minimal ambient declarations for 'y-dexie' to satisfy type imports
+// This is a local quickfix for TypeScript ESM/CJS resolution issues.
+declare module 'y-dexie' {
+  // Inline minimal Y.Doc type to avoid depending on 'yjs' ambient declaration
+  export type YDoc = {
+    // minimal shape used by dexie-react-hooks
+    toJSON?: () => any;
+  };
+
+  export type DexieYProvider = {
+    doc?: YDoc | null;
+    // Partial API surface used by dexie-react-hooks
+    release?: (doc?: YDoc) => void;
+  };
+
+  export const DexieYProvider: {
+    load(doc: YDoc, options?: any): DexieYProvider;
+    for(doc: YDoc): DexieYProvider | undefined;
+    release(doc: YDoc): void;
+  };
+
+  export type YUpdateRow = any;
+  export type YSyncState = any;
+
+  export function compressYDocs(docs: unknown): unknown;
+
+  export default function yDexie(dbOrOptions?: any): any;
+}

libs/dexie-react-hooks/src/types/yjs.d.ts

@@ -0,0 +1,7 @@
+// Minimal ambient declaration for 'yjs' used for type Doc
+declare module 'yjs' {
+  export type Doc = {
+    // Minimal Doc shape used by dexie-react-hooks; real API is larger
+    toJSON?: () => any;
+  };
+}

libs/dexie-react-hooks/src/useObservable.ts

@@ -3,11 +3,13 @@ export interface InteropableObservable<T> {
   subscribe(
     onNext: (x: T) => any,
     onError?: (error: any) => any
-  ): (() => any) | { unsubscribe(): any };
+  ): AnySubscription;
   getValue?(): T; // For BehaviorSubject
   hasValue?(): boolean; // For liveQuery observable returning false until a value is available
 }
 
+export type AnySubscription = { unsubscribe(): any } | (() => any);
+
 export function useObservable<T, TDefault>(
   observable: InteropableObservable<T>
 ): T | undefined;

libs/dexie-react-hooks/src/usePromise.ts

@@ -0,0 +1,37 @@
+import * as React from 'react';
+
+/** {@link React.use} if supported, else fallback */
+export const usePromise: <T>(promise: PromiseLike<T>) => T =
+  React.use ?? fallbackUsePromise;
+
+/** Fallback for `React.use` with promise */
+function fallbackUsePromise<T>(promise: PromiseLike<T>): T {
+  const state = PROMISE_STATE_MAP.get(promise);
+
+  if (!state) {
+    PROMISE_STATE_MAP.set(promise, { status: 'pending' });
+    promise.then(
+      (value) => {
+        PROMISE_STATE_MAP.set(promise, { status: 'fulfilled', value });
+      },
+      (reason) => {
+        PROMISE_STATE_MAP.set(promise, { status: 'rejected', reason });
+      }
+    );
+    throw promise;
+  }
+
+  switch (state.status) {
+    case 'pending':
+      throw promise;
+    case 'rejected':
+      throw state.reason;
+    case 'fulfilled':
+      return state.value;
+  }
+}
+
+const PROMISE_STATE_MAP = new WeakMap<
+  PromiseLike<any>,
+  PromiseSettledResult<any> | { status: 'pending' }
+>();

libs/dexie-react-hooks/src/useSuspendingLiveQuery.ts

@@ -0,0 +1,17 @@
+import { Dexie } from 'dexie';
+import { useSuspendingObservable } from './useSuspendingObservable';
+
+/**
+ * Observe IndexedDB data in your React component. Make the component re-render when the observed data changes.
+ *
+ * Suspends until first value is available.
+ */
+export function useSuspendingLiveQuery<T>(
+  querier: () => Promise<T> | T,
+  cacheKey: React.DependencyList
+): T {
+  return useSuspendingObservable(
+    () => Dexie.liveQuery(querier),
+    ['dexie', ...cacheKey]
+  );
+}

libs/dexie-react-hooks/src/useSuspendingObservable.ts

@@ -0,0 +1,149 @@
+import * as React from 'react';
+import { AnySubscription, InteropableObservable } from './useObservable';
+import { usePromise } from './usePromise';
+
+/**
+ * Subscribes to an observable and returns the latest value.
+ * Suspends until the first value is received.
+ *
+ * Calls with the same cacheKey will use the same observable.
+ * cacheKey must be globally unique.
+ */
+export function useSuspendingObservable<T>(
+  getObservable: (() => InteropableObservable<T>) | InteropableObservable<T>,
+  cacheKey: React.DependencyList
+): T {
+  let observable: InteropableObservable<T>;
+  for (const [key, val] of OBSERVABLES.entries()) {
+    if (
+      key.length === cacheKey.length &&
+      key.every((k, i) => Object.is(k, cacheKey[i]))
+    ) {
+      observable = val;
+      break;
+    }
+  }
+  //@ts-ignore (because observable might be undefined here)
+  if (!observable) {
+    observable = typeof getObservable === 'function'
+      ? getObservable()
+      : getObservable;
+    OBSERVABLES.set(cacheKey, observable);
+  }
+  // At this point, observable is always set.
+
+  const incrementRef = () => {
+    const timeout = TIMEOUTS.get(observable);
+    if (timeout != null) clearTimeout(timeout);
+
+    let refCount = REF_COUNTS.get(observable) ?? 0;
+    refCount += 1;
+    REF_COUNTS.set(observable, refCount);
+  };
+
+  const decrementRef = () => {
+    let refCount = REF_COUNTS.get(observable)!;
+    refCount -= 1;
+    REF_COUNTS.set(observable, refCount);
+
+    if (refCount > 0) return;
+
+    const timeout = setTimeout(() => {
+      for (const [key, val] of OBSERVABLES.entries()) {
+        if (val === observable) {
+          OBSERVABLES.delete(key);
+          break;
+        }
+      }
+      PROMISES.delete(observable);
+      VALUES.delete(observable);
+      TIMEOUTS.delete(observable);
+      REF_COUNTS.delete(observable);
+    }, 1000);
+    TIMEOUTS.set(observable, timeout);
+  };
+
+  let promise: Promise<T> | undefined = PROMISES.get(observable);
+  if (!promise) {
+    promise = new Promise<T>((resolve, reject) => {
+      if (VALUES.has(observable)) {
+        resolve(VALUES.get(observable)!);
+        return;
+      }
+
+      incrementRef();
+
+      let calledSynchronously = false;
+      let sub: AnySubscription;
+      sub = observable.subscribe(
+        (val) => {
+          resolve(val);
+          VALUES.set(observable, val);
+          if (!sub) calledSynchronously = true;
+          else unsub(sub);
+          decrementRef();
+        },
+        (err) => {
+          reject(err);
+          if (!sub) calledSynchronously = true;
+          else unsub(sub);
+          decrementRef();
+        }
+      );
+      if (calledSynchronously) unsub(sub);
+    });
+
+    PROMISES.set(observable, promise);
+  }
+
+  if (!VALUES.has(observable)) {
+    usePromise(promise);
+  }
+
+  const [value, setValue] = React.useState<T>(VALUES.get(observable));
+  const [error, setError] = React.useState<any>(null);
+
+  React.useEffect(() => {
+    incrementRef();
+
+    const sub = observable.subscribe(
+      (val) => {
+        VALUES.set(observable, val);
+        setValue(val);
+      },
+      (err) => {
+        setError(err);
+      }
+    );
+
+    return () => {
+      unsub(sub);
+      decrementRef();
+    };
+  }, [observable]);
+
+  if (error) throw error;
+  return value;
+}
+
+const OBSERVABLES = new Map<React.DependencyList, InteropableObservable<any>>();
+
+const PROMISES = new WeakMap<InteropableObservable<any>, Promise<any>>();
+
+const VALUES = new WeakMap<InteropableObservable<any>, any>();
+
+const TIMEOUTS = new WeakMap<
+  InteropableObservable<any>,
+  ReturnType<typeof setTimeout>
+>();
+
+const REF_COUNTS = new WeakMap<InteropableObservable<any>, number>();
+
+/** Unsubscribes from an observable */
+function unsub(sub: AnySubscription) {
+  if (typeof sub === 'function') {
+    sub();
+  } else {
+    sub.unsubscribe();
+  }
+}

libs/dexie-react-hooks/test/components/ErrorBoundrary.tsx

@@ -1,7 +1,7 @@
 import React, { Component } from "react";
 
-export class ErrorBoundary extends Component<{}, { error: any }> {
-  constructor(props) {
+export class ErrorBoundary extends Component<React.PropsWithChildren<{}>, { error: any }> {
+  constructor(props: React.PropsWithChildren<{}>) {
     super(props);
     this.state = { error: null };
   }
@@ -11,7 +11,7 @@ export class ErrorBoundary extends Component<{}, { error: any }> {
     return { error };
   }
 
-  componentDidCatch(error, errorInfo) {
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
     //console.error(error, errorInfo);
   }
 

libs/dexie-react-hooks/test/components/ItemLoaderComponent.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { useLiveQuery } from "../../src";
+import { useSuspendingLiveQuery } from "../../src";
 import { Item } from "../models/Item";
 import { ItemComponent } from "./ItemComponent";
 
@@ -9,8 +9,7 @@ export interface Props {
 }
 
 export function ItemLoaderComponent({ id, loadItem }: Props) {
-  const item = useLiveQuery(() => loadItem(id), [id], "loading");
-  if (item === "loading") return <p>Loading...</p>;
+  const item = useSuspendingLiveQuery(() => loadItem(id), ["item", id]);
   if (!item)
     return (
       <p className="not-found-item">