@tanstack/react-db 0.5.12 → 1.0.0-rc.1

package/dist/esm/useLiveQuery.js

@@ -1,18 +1,16 @@
 "use client";
 import { useRef, useSyncExternalStore } from "react";
-import { getPreparedLiveQueryIdentity, UnhashableQueryIRError, prepareLiveQueryValue, isCollection, getStableValueHash, deepEquals, resolveLiveQueryValue, createLiveQueryObserver, resumeDeferredLiveQueryCollections } from "@tanstack/db";
+import { identifyLiveQuery, prepareLiveQueryValue, isCollection, getLiveQueryKey, getStableValueHash, UnhashableQueryIRError, deepEquals, resolveLiveQueryValue, releaseDeferredOnReclaim, createLiveQueryObserver, rejectLiveQueryInput, createLiveQuerySourceIdClaims, getSourceObjectToken, resumeDeferredLiveQueryCollections } from "@tanstack/db";
 import { useOptionalDbClient } from "./DbProvider.js";
 import { setLiveQueryResultInfo } from "./live-query-internals.js";
 import { shouldWarnInDevelopment } from "./development.js";
-import { claimSourceIds, getPreparedSources, createSourceIdBindings, getSourceObjectToken } from "./source-id-bindings.js";
+import { getPreparedSources, getUnboundDescriptorReporter } from "./source-id-bindings.js";
 const DEFAULT_GC_TIME_MS = 1;
 const DEFAULT_SUSPENSE_GC_TIME_MS = 5e3;
 const DERIVED_IDENTITY_SINGLE_RENDER_WARN_MS = 16;
 const DERIVED_IDENTITY_RENDER_COUNT_WARN_THRESHOLD = 10;
 const DERIVED_IDENTITY_TOTAL_WARN_MS = 50;
-const warnedDepsCallsites = /* @__PURE__ */ new Set();
 const warnedDerivedIdentityCallsites = /* @__PURE__ */ new Set();
-const warnedUnhashableIdentityCallsites = /* @__PURE__ */ new Set();
 const unpreparedQueryValue = /* @__PURE__ */ Symbol(`unpreparedQueryValue`);
 const unscopedSuspenseCollections = /* @__PURE__ */ new Map();
 const suspenseCollectionsByClient = /* @__PURE__ */ new WeakMap();
@@ -40,20 +38,6 @@ function releaseSuspenseCollection(collections, queryHash, collection) {
   collections.delete(queryHash);
   entry.removeStatusListeners();
 }
-function warnDeprecatedDepsArray(hookName = `useLiveQuery`) {
-  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_DEPRECATION_WARNINGS`)) {
-    return;
-  }
-  const callsite = getWarningCallsite(4);
-  if (warnedDepsCallsites.has(callsite)) {
-    return;
-  }
-  warnedDepsCallsites.add(callsite);
-  const replacement = hookName === `useLiveQuery` ? `useLiveQuery({ query })` : `useLiveInfiniteQuery(query, { queryKey })`;
-  console.warn(
-    `[${hookName}] The dependency-array form is deprecated and will be removed in 1.0. Use ${replacement} instead. Provide queryKey only for functional/opaque queries or to avoid deriving identity from structured query IR on render.`
-  );
-}
 function getCurrentTime() {
   return typeof performance !== `undefined` && typeof performance.now === `function` ? performance.now() : Date.now();
 }
@@ -67,7 +51,7 @@ function getWarningCallsite(stackIndex) {
   return userFrame?.trim() ?? lines[stackIndex]?.trim() ?? stack;
 }
 function warnDerivedIdentityHotPath(profiler, durationMs) {
-  if (profiler.warned || !shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)) {
+  if (profiler.warned || !(shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`) && process.env.NODE_ENV !== `production`)) {
     return;
   }
   const isSlowSingleRender = durationMs >= DERIVED_IDENTITY_SINGLE_RENDER_WARN_MS;
@@ -87,33 +71,33 @@ function warnDerivedIdentityHotPath(profiler, durationMs) {
     `[useLiveQuery] Deriving live query identity from structured query IR is running on a hot render path (${reason}, max ${profiler.maxMs.toFixed(1)}ms). Provide an explicit queryKey to skip rebuilding and hashing the IR on every render: useLiveQuery({ queryKey: [...], query }).`
   );
 }
-function getExplicitQueryKey(value) {
-  return value && typeof value === `object` && Array.isArray(value.queryKey) ? value.queryKey : void 0;
-}
 function getExplicitDbClient(value) {
   return value && typeof value === `object` && `client` in value && value.client !== void 0 ? value.client : void 0;
 }
 function prepareQueryValue(value, dbClient, deferredCollections) {
   return prepareLiveQueryValue(value, dbClient, deferredCollections);
 }
-function prepareDerivedQuery(value, dbClient, profiler, deferredCollections) {
-  const shouldProfile = shouldWarnInDevelopment(
-    `TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`
-  );
+function getIdentityScope(claims, dbClient, hookName) {
+  return {
+    claims,
+    client: dbClient,
+    bindingName: hookName,
+    onUnboundDescriptor: getUnboundDescriptorReporter(dbClient, hookName)
+  };
+}
+function prepareDerivedQuery(value, profiler, scope, deferredCollections) {
+  const shouldProfile = shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`) && process.env.NODE_ENV !== `production`;
   const start = shouldProfile ? getCurrentTime() : 0;
-  const preparedValue = prepareQueryValue(value, dbClient, deferredCollections);
+  const preparedValue = prepareQueryValue(
+    value,
+    scope.client,
+    deferredCollections
+  );
   try {
-    const identity = getPreparedLiveQueryIdentity(preparedValue);
     return {
-      status: `hashable`,
       value: preparedValue,
-      identityDeps: [`derived`, identity]
+      identityDeps: [`derived`, identifyLiveQuery(preparedValue, scope)]
     };
-  } catch (error) {
-    if (error instanceof UnhashableQueryIRError) {
-      return { status: `unhashable`, value: preparedValue, error };
-    }
-    throw error;
   } finally {
     if (shouldProfile) {
       const durationMs = getCurrentTime() - start;
@@ -124,32 +108,18 @@ function prepareDerivedQuery(value, dbClient, profiler, deferredCollections) {
     }
   }
 }
-function warnUnhashableDerivedIdentity(error) {
-  if (!shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)) {
-    return;
-  }
-  const callsite = getWarningCallsite(4);
-  if (warnedUnhashableIdentityCallsites.has(callsite)) {
-    return;
-  }
-  warnedUnhashableIdentityCallsites.add(callsite);
-  console.warn(
-    `[useLiveQuery] This query cannot derive a stable identity because ${error.reason} at ${error.path}. It will keep the legacy mount-stable behavior for now. Add queryKey: [...] to make captured values reactive. Unhashable queries without queryKey will throw in 1.0.`
-  );
-}
-function useLiveQuery(configOrQueryOrCollection, deps) {
-  return useLiveQueryImpl(configOrQueryOrCollection, deps);
+function useLiveQuery(configOrQueryOrCollection) {
+  return useLiveQueryImpl(configOrQueryOrCollection);
 }
-function useLiveQueryForSuspense(configOrQueryOrCollection, deps) {
-  return useLiveQueryImpl(configOrQueryOrCollection, deps, true);
+function useLiveQueryForSuspense(configOrQueryOrCollection) {
+  return useLiveQueryImpl(configOrQueryOrCollection, true);
 }
 function createHookInstance(dbClient) {
   return {
     collection: null,
-    deps: null,
+    identityDeps: null,
     config: null,
     client: dbClient,
-    legacyUnhashableIdentity: [`legacy-unhashable`],
     derivedIdentityProfiler: {
       renderCount: 0,
       totalMs: 0,
@@ -157,7 +127,8 @@ function createHookInstance(dbClient) {
       warned: false
     },
     deferredCollections: /* @__PURE__ */ new Set(),
-    sourceIds: createSourceIdBindings(),
+    sourceIds: createLiveQuerySourceIdClaims(),
+    cancelReclaimRelease: void 0,
     observer: null,
     queryHash: void 0,
     suspenseKey: void 0,
@@ -165,119 +136,89 @@ function createHookInstance(dbClient) {
     subscribe: null
   };
 }
-function useLiveQueryImpl(configOrQueryOrCollection, deps, forSuspense = false) {
+function useLiveQueryImpl(configOrQueryOrCollection, forSuspense = false) {
   const contextDbClient = useOptionalDbClient();
   const inputIsCollection = isCollection(configOrQueryOrCollection);
   const dbClient = inputIsCollection ? contextDbClient : getExplicitDbClient(configOrQueryOrCollection) ?? contextDbClient;
-  const resolvedDeps = deps ?? [];
   const instanceRef = useRef(null);
   const instance = instanceRef.current ??= createHookInstance(dbClient);
-  const resumeDeferredCollections = () => resumeDeferredLiveQueryCollections(instance.deferredCollections);
-  const queryKey = !inputIsCollection ? getExplicitQueryKey(configOrQueryOrCollection) : void 0;
-  let preparedQueryValue = unpreparedQueryValue;
-  let identityDeps;
-  let streamIdentity = void 0;
-  let identityError;
-  if (queryKey) {
-    identityDeps = queryKey;
-    streamIdentity = [`queryKey`, queryKey];
-  } else if (deps !== void 0) {
-    identityDeps = resolvedDeps;
-    if (dbClient || forSuspense || shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`))
-      try {
-        preparedQueryValue = prepareQueryValue(
-          configOrQueryOrCollection,
-          dbClient,
-          instance.deferredCollections
-        );
-        streamIdentity = [
-          `deps`,
-          resolvedDeps,
-          getPreparedLiveQueryIdentity(preparedQueryValue)
-        ];
-      } catch (error) {
-        if (!(error instanceof UnhashableQueryIRError)) throw error;
-        warnUnhashableDerivedIdentity(error);
-        identityError = error;
-      }
-  } else if (inputIsCollection) {
-    identityDeps = [];
-    streamIdentity = [`collection`, configOrQueryOrCollection.id];
-  } else {
-    const preparation = prepareDerivedQuery(
-      configOrQueryOrCollection,
-      dbClient,
-      instance.derivedIdentityProfiler,
-      instance.deferredCollections
-    );
-    preparedQueryValue = preparation.value;
-    if (preparation.status === `hashable`) {
+  const resumeDeferredCollections = () => {
+    instance.cancelReclaimRelease?.();
+    instance.cancelReclaimRelease = void 0;
+    resumeDeferredLiveQueryCollections(instance.deferredCollections);
+  };
+  try {
+    const queryKey = !inputIsCollection ? getLiveQueryKey(configOrQueryOrCollection) : void 0;
+    let preparedQueryValue = unpreparedQueryValue;
+    let identityDeps;
+    let streamIdentity = void 0;
+    let identityError;
+    if (queryKey) {
+      identityDeps = queryKey;
+      streamIdentity = [`queryKey`, queryKey];
+    } else if (inputIsCollection) {
+      identityDeps = [];
+      streamIdentity = [`collection`, configOrQueryOrCollection.id];
+    } else {
+      const preparation = prepareDerivedQuery(
+        configOrQueryOrCollection,
+        instance.derivedIdentityProfiler,
+        getIdentityScope(instance.sourceIds, dbClient, `useLiveQuery`),
+        instance.deferredCollections
+      );
+      preparedQueryValue = preparation.value;
       identityDeps = preparation.identityDeps;
       streamIdentity = preparation.identityDeps;
-    } else {
-      warnUnhashableDerivedIdentity(preparation.error);
-      identityDeps = instance.legacyUnhashableIdentity;
-      identityError = preparation.error;
     }
-  }
-  let queryHash;
-  if (streamIdentity !== void 0) {
-    try {
-      queryHash = getStableValueHash(streamIdentity, `queryKey`);
-    } catch (error) {
-      if (error instanceof UnhashableQueryIRError) {
-        if (queryKey !== void 0) throw error;
-        identityError = error;
-      } else {
-        throw error;
+    let queryHash;
+    if (streamIdentity !== void 0) {
+      try {
+        queryHash = getStableValueHash(streamIdentity, `queryKey`);
+      } catch (error) {
+        if (error instanceof UnhashableQueryIRError) {
+          if (queryKey !== void 0) throw error;
+          identityError = error;
+        } else {
+          throw error;
+        }
       }
     }
-  }
-  if (deps !== void 0) {
-    warnDeprecatedDepsArray();
-  }
-  if (queryKey === void 0 && deps === void 0 && preparedQueryValue !== unpreparedQueryValue) {
-    claimSourceIds(
-      instance.sourceIds,
+    const canReuseSuspenseKey = forSuspense && !inputIsCollection && queryHash !== void 0 && instance.collection !== null && instance.client === dbClient && instance.queryHash === queryHash && instance.suspenseKey !== void 0;
+    if (forSuspense && !inputIsCollection && queryHash && !canReuseSuspenseKey && preparedQueryValue === unpreparedQueryValue) {
+      preparedQueryValue = prepareQueryValue(
+        configOrQueryOrCollection,
+        dbClient,
+        instance.deferredCollections
+      );
+    }
+    const suspenseKey = queryHash && forSuspense && !inputIsCollection ? canReuseSuspenseKey ? instance.suspenseKey : getSourceQualifiedSuspenseKey(
       preparedQueryValue,
-      dbClient,
-      `useLiveQuery`,
-      resumeDeferredCollections
-    );
-  }
-  const canReuseSuspenseKey = forSuspense && !inputIsCollection && queryHash !== void 0 && instance.collection !== null && instance.client === dbClient && instance.queryHash === queryHash && instance.suspenseKey !== void 0;
-  if (forSuspense && !inputIsCollection && queryHash && !canReuseSuspenseKey && preparedQueryValue === unpreparedQueryValue) {
-    preparedQueryValue = prepareQueryValue(
-      configOrQueryOrCollection,
-      dbClient,
-      instance.deferredCollections
-    );
-  }
-  const suspenseKey = queryHash && forSuspense && !inputIsCollection ? canReuseSuspenseKey ? instance.suspenseKey : getSourceQualifiedSuspenseKey(preparedQueryValue, queryHash, dbClient) : queryHash;
-  const suspenseCollections = forSuspense && !inputIsCollection && suspenseKey ? getSuspenseCollections(dbClient) : void 0;
-  const suspenseEntry = suspenseKey ? suspenseCollections?.get(suspenseKey) : void 0;
-  const suspenseCollection = suspenseEntry?.collection;
-  const identityChanged = instance.deps === null || (deps !== void 0 ? instance.deps.length !== identityDeps.length || instance.deps.some((dep, index) => dep !== identityDeps[index]) : !deepEquals(instance.deps, identityDeps));
-  const needsNewCollection = !instance.collection || inputIsCollection && instance.config !== configOrQueryOrCollection || !inputIsCollection && (instance.client !== dbClient || identityChanged);
-  if (needsNewCollection) {
-    if (inputIsCollection) {
-      const syncMode = configOrQueryOrCollection.config?.syncMode;
-      if (syncMode === `on-demand` && shouldWarnInDevelopment(`TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`)) {
-        console.warn(
-          `[useLiveQuery] Warning: Passing a collection with syncMode "on-demand" directly to useLiveQuery will not load any data. In on-demand mode, data is only loaded when queries with predicates request it.
+      queryHash,
+      dbClient
+    ) : queryHash;
+    const suspenseCollections = forSuspense && !inputIsCollection && suspenseKey ? getSuspenseCollections(dbClient) : void 0;
+    const suspenseEntry = suspenseKey ? suspenseCollections?.get(suspenseKey) : void 0;
+    const suspenseCollection = suspenseEntry?.collection;
+    const identityChanged = instance.identityDeps === null || !deepEquals(instance.identityDeps, identityDeps);
+    const needsNewCollection = !instance.collection || inputIsCollection && instance.config !== configOrQueryOrCollection || !inputIsCollection && (instance.client !== dbClient || identityChanged);
+    if (needsNewCollection) {
+      if (inputIsCollection) {
+        const syncMode = configOrQueryOrCollection.config?.syncMode;
+        if (syncMode === `on-demand` && shouldWarnInDevelopment(
+          `TANSTACK_DB_DISABLE_QUERY_IDENTITY_WARNINGS`
+        ) && process.env.NODE_ENV !== `production`) {
+          console.warn(
+            `[useLiveQuery] Warning: Passing a collection with syncMode "on-demand" directly to useLiveQuery will not load any data. In on-demand mode, data is only loaded when queries with predicates request it.
 
 Instead, use a query builder function:
   const { data } = useLiveQuery({ query: (q) => q.from({ c: myCollection }).select(({ c }) => c) })
 
 Or switch to syncMode "eager" if you want all data to sync automatically.`
-        );
-      }
-      configOrQueryOrCollection.startSyncImmediate();
-      instance.collection = configOrQueryOrCollection;
-      instance.config = configOrQueryOrCollection;
-    } else {
-      if (suspenseCollection) {
-        instance.collection = suspenseCollection;
+          );
+        }
+        configOrQueryOrCollection.startSyncImmediate();
+        instance.collection = configOrQueryOrCollection;
+        instance.config = configOrQueryOrCollection;
       } else {
         if (preparedQueryValue === unpreparedQueryValue) {
           preparedQueryValue = prepareQueryValue(
@@ -286,28 +227,38 @@ Or switch to syncMode "eager" if you want all data to sync automatically.`
             instance.deferredCollections
           );
         }
-        if (!dbClient) {
-          getPreparedSources(preparedQueryValue, dbClient, `useLiveQuery`);
-        }
-        instance.collection = resolveLiveQueryValue(preparedQueryValue, {
-          gcTime: forSuspense ? DEFAULT_SUSPENSE_GC_TIME_MS : DEFAULT_GC_TIME_MS,
-          // Hydration and Suspense key the live-query Collection by identity.
-          pool: !forSuspense && !dbClient,
-          // Without a DbClient, Suspense starts it through a preload below.
-          startSync: !forSuspense || dbClient !== void 0
-        });
-        if (suspenseCollections && suspenseKey && instance.collection) {
-          const collection = instance.collection;
-          const removeCleanupListener = collection.on(
-            `status:cleaned-up`,
-            () => releaseSuspenseCollection(
-              suspenseCollections,
-              suspenseKey,
-              collection
-            )
-          );
-          const removeErrorListener = collection.on(`status:error`, () => {
-            setTimeout(
+        if (suspenseCollection) {
+          instance.collection = suspenseCollection;
+        } else {
+          if (!dbClient && queryKey !== void 0) {
+            getPreparedSources(preparedQueryValue, dbClient, `useLiveQuery`);
+          }
+          instance.collection = resolveLiveQueryValue(preparedQueryValue, {
+            gcTime: forSuspense ? DEFAULT_SUSPENSE_GC_TIME_MS : DEFAULT_GC_TIME_MS,
+            // Hydration and Suspense key the live-query Collection by identity,
+            // so they never pool, even when the config passes a pool.
+            pool: forSuspense || dbClient ? false : void 0,
+            // Without a DbClient, Suspense starts it through a preload below.
+            startSync: !forSuspense || dbClient !== void 0
+          });
+          if (instance.collection && !isCollection(preparedQueryValue)) {
+            instance.cancelReclaimRelease?.();
+            instance.cancelReclaimRelease = releaseDeferredOnReclaim(
+              instance.collection,
+              instance.deferredCollections
+            );
+          }
+          if (suspenseCollections && suspenseKey && instance.collection) {
+            const collection = instance.collection;
+            const removeCleanupListener = collection.on(
+              `status:cleaned-up`,
+              () => releaseSuspenseCollection(
+                suspenseCollections,
+                suspenseKey,
+                collection
+              )
+            );
+            const retireAfterRetry = () => setTimeout(
               () => releaseSuspenseCollection(
                 suspenseCollections,
                 suspenseKey,
@@ -315,66 +266,78 @@ Or switch to syncMode "eager" if you want all data to sync automatically.`
               ),
               0
             );
-          });
-          const entry = {
-            collection,
-            removeStatusListeners: () => {
-              removeCleanupListener();
-              removeErrorListener();
-            }
-          };
-          suspenseCollections.set(suspenseKey, entry);
+            const removeErrorListener = collection.on(
+              `status:error`,
+              retireAfterRetry
+            );
+            const removeCrashListener = collection.on(
+              `status:crashed`,
+              retireAfterRetry
+            );
+            const entry = {
+              collection,
+              removeStatusListeners: () => {
+                removeCleanupListener();
+                removeErrorListener();
+                removeCrashListener();
+              }
+            };
+            suspenseCollections.set(suspenseKey, entry);
+          }
         }
+        instance.config = configOrQueryOrCollection;
+        instance.identityDeps = [...identityDeps];
       }
-      instance.config = configOrQueryOrCollection;
-      instance.deps = [...identityDeps];
+      instance.client = dbClient;
+      instance.queryHash = queryHash;
+      instance.suspenseKey = suspenseKey;
+      instance.identityError = identityError;
     }
-    instance.client = dbClient;
-    instance.queryHash = queryHash;
-    instance.suspenseKey = suspenseKey;
-    instance.identityError = identityError;
-  }
-  if (needsNewCollection) {
-    instance.observer = createLiveQueryObserver(instance.collection, {
-      mode: `wholesale`,
-      client: dbClient,
-      queryHash: instance.queryHash,
-      onPreload: resumeDeferredCollections
-    });
-  }
-  const observer = instance.observer;
-  if (forSuspense && !dbClient && (instance.collection?.status === `idle` || instance.collection?.status === `cleaned-up`)) {
-    observer.preloadForInitialRender().catch(() => {
-    });
-  }
-  if (!instance.subscribe || needsNewCollection) {
-    instance.subscribe = (onStoreChange) => {
-      const unsubscribe = observer.subscribe(onStoreChange);
-      resumeDeferredCollections();
-      return unsubscribe;
-    };
-  }
-  const returned = useSyncExternalStore(
-    instance.subscribe,
-    () => observer.getSnapshot(),
-    () => observer.getServerSnapshot()
-  );
-  if (forSuspense) {
-    setLiveQueryResultInfo(returned, {
-      client: dbClient,
-      queryHash: instance.queryHash,
-      identityError: instance.identityError,
-      observer
-    });
+    if (needsNewCollection) {
+      instance.observer = createLiveQueryObserver(instance.collection, {
+        mode: `wholesale`,
+        client: dbClient,
+        queryHash: instance.queryHash,
+        onPreload: resumeDeferredCollections,
+        suspendUntilReady: forSuspense
+      });
+    }
+    const observer = instance.observer;
+    if (forSuspense && !dbClient && (instance.collection?.status === `idle` || instance.collection?.status === `cleaned-up`)) {
+      observer.preload().catch(() => {
+      });
+    }
+    if (!instance.subscribe || needsNewCollection) {
+      instance.subscribe = (onStoreChange) => {
+        const unsubscribe = observer.subscribe(onStoreChange);
+        resumeDeferredCollections();
+        return unsubscribe;
+      };
+    }
+    const returned = useSyncExternalStore(
+      instance.subscribe,
+      () => observer.getSnapshot(),
+      () => observer.getServerSnapshot(forSuspense)
+    );
+    if (forSuspense) {
+      setLiveQueryResultInfo(returned, {
+        client: dbClient,
+        queryHash: instance.queryHash,
+        identityError: instance.identityError,
+        observer,
+        deferredCollections: instance.deferredCollections
+      });
+    }
+    return returned;
+  } catch (error) {
+    return rejectLiveQueryInput(instance.deferredCollections, error);
   }
-  return returned;
 }
 export {
+  getIdentityScope,
   prepareDerivedQuery,
   prepareQueryValue,
   useLiveQuery,
-  useLiveQueryForSuspense,
-  warnDeprecatedDepsArray,
-  warnUnhashableDerivedIdentity
+  useLiveQueryForSuspense
 };
 //# sourceMappingURL=useLiveQuery.js.map