@instantdb/react-common 0.22.164 → 0.22.165

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instantdb/react-common",
-  "version": "0.22.164",
+  "version": "0.22.165",
   "description": "Instant DB shared components for React and React Native",
   "homepage": "https://github.com/instantdb/instant/tree/main/client/packages/react-common",
   "repository": {
@@ -53,8 +53,8 @@
     "react": ">=16"
   },
   "dependencies": {
-    "@instantdb/core": "0.22.164",
-    "@instantdb/version": "0.22.164"
+    "@instantdb/core": "0.22.165",
+    "@instantdb/version": "0.22.165"
   },
   "scripts": {
     "test": "vitest",

package/src/InstantReactAbstractDatabase.tsx

@@ -32,6 +32,10 @@ import {
   useSyncExternalStore,
 } from 'react';
 import { useQueryInternal } from './useQuery.ts';
+import {
+  type InfiniteQueryResult,
+  useInfiniteQuerySubscription,
+} from './useInfiniteQuerySubscription.ts';
 import { InstantReactRoom, rooms } from './InstantReactRoom.ts';
 
 const defaultAuthState = {
@@ -390,6 +394,41 @@ export default abstract class InstantReactAbstractDatabase<
     return this.core.queryOnce(query, opts);
   };
 
+  /**
+   * Subscribe to a query and incrementally load more items
+   *
+   * Only one top level namespace in the query is allowed.
+   *
+   * Changing the query or options while the subscription is active will
+   * reset the subscription and start over with new data.
+   * @example
+   * const {
+   *   data,
+   *   loadNextPage,
+   *   canLoadNextPage,
+   * } = db.useInfiniteQuery({
+   *   posts: {
+   *     $: {
+   *       limit: 20,   // Load 20 posts at a time
+   *       order: {
+   *         createdAt: 'desc',
+   *       },
+   *     },
+   *   },
+   * });
+   */
+  useInfiniteQuery = <Q extends ValidQuery<Q, Schema>>(
+    query: Q,
+    opts?: InstaQLOptions,
+  ): InfiniteQueryResult<Schema, Q, UseDates> => {
+    const result = useInfiniteQuerySubscription<Schema, Q, UseDates>({
+      core: this.core,
+      query: query,
+      opts,
+    });
+    return result;
+  };
+
   /**
    * Only render children if the user is signed in.
    * @see https://instantdb.com/docs/auth

package/src/useInfiniteQuerySubscription.ts

@@ -0,0 +1,127 @@
+import {
+  type InfiniteQuerySubscription,
+  type InstantCoreDatabase,
+  type InstantSchemaDef,
+  type InstaQLOptions,
+  InstaQLResponse,
+  ValidQuery,
+  weakHash,
+  getInfiniteQueryInitialSnapshot,
+} from '@instantdb/core';
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+
+export type InfiniteQueryResult<
+  Schema extends InstantSchemaDef<any, any, any>,
+  Q extends ValidQuery<Q, Schema>,
+  UseDates extends boolean,
+> =
+  | {
+      error: { message: string };
+      data: undefined;
+      isLoading: false;
+      canLoadNextPage: boolean;
+      loadNextPage: () => void;
+    }
+  | {
+      error: undefined;
+      data: undefined;
+      isLoading: true;
+      canLoadNextPage: boolean;
+      loadNextPage: () => void;
+    }
+  | {
+      error: undefined;
+      data: InstaQLResponse<Schema, Q, UseDates>;
+      isLoading: false;
+      canLoadNextPage: boolean;
+      loadNextPage: () => void;
+    };
+
+const defaultState = {
+  error: undefined,
+  data: undefined,
+  isLoading: true,
+  canLoadNextPage: false,
+};
+
+export function useInfiniteQuerySubscription<
+  Schema extends InstantSchemaDef<any, any, any>,
+  Q extends ValidQuery<Q, Schema>,
+  UseDates extends boolean,
+>({
+  core,
+  query,
+  opts,
+}: {
+  core: InstantCoreDatabase<Schema, UseDates>;
+  query: Q | null;
+  opts?: InstaQLOptions;
+}): InfiniteQueryResult<Schema, Q, UseDates> {
+  const subRef = useRef<InfiniteQuerySubscription | null>(null);
+
+  const queryHash = weakHash(query);
+  const optsHash = weakHash(opts);
+  const snapshot = getInfiniteQueryInitialSnapshot(core, query, opts);
+
+  const stateCacheRef = useRef<
+    Omit<InfiniteQueryResult<Schema, Q, UseDates>, 'loadNextPage'>
+  >({
+    ...snapshot,
+    isLoading: !snapshot.data && !snapshot.error,
+  });
+
+  const subscribe = useCallback(
+    (cb: () => void) => {
+      subRef.current = null;
+      stateCacheRef.current = {
+        error: undefined,
+        data: undefined,
+        isLoading: true,
+        canLoadNextPage: false,
+      };
+      cb();
+
+      if (!query) {
+        return () => {};
+      }
+
+      const sub = core.subscribeInfiniteQuery(
+        query,
+        (resp) => {
+          stateCacheRef.current = {
+            ...resp,
+            isLoading: false,
+          };
+          cb();
+        },
+        opts,
+      );
+
+      subRef.current = sub;
+
+      return () => {
+        sub.unsubscribe();
+        if (subRef.current === sub) {
+          subRef.current = null;
+        }
+      };
+    },
+    [queryHash, optsHash],
+  );
+
+  const state = useSyncExternalStore(
+    subscribe,
+    () => stateCacheRef.current,
+    () => defaultState,
+  );
+
+  const loadNextPage = () => {
+    subRef.current?.loadNextPage();
+  };
+
+  // @ts-expect-error union type
+  return {
+    ...state,
+    loadNextPage,
+  };
+}