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

package/dist/esm/useLiveQuery.d.ts

@@ -1,4 +1,4 @@
-import { UnhashableQueryIRError, Collection, CollectionImpl, CollectionStatus, Context, DbClient, GetResult, InferResultType, InitialQueryBuilder, LiveQueryCollectionConfig, LiveQueryPersistedStatus, NonSingleResult, QueryBuilder, SingleResult } from '@tanstack/db';
+import { Collection, CollectionImpl, CollectionStatus, Context, DbClient, GetResult, InferResultType, InitialQueryBuilder, LiveQueryCollectionConfig, LiveQueryIdentityScope, LiveQueryKey, LiveQuerySourceIdClaims, LiveQueryStatusFlags, NonSingleResult, PooledLiveQueries, QueryBuilder, SingleResult } from '@tanstack/db';
 export type DerivedIdentityProfiler = {
     renderCount: number;
     totalMs: number;
@@ -6,7 +6,7 @@ export type DerivedIdentityProfiler = {
     warned: boolean;
 };
 export type UseLiveQueryStatus = CollectionStatus | `disabled`;
-export type LiveQueryKey = ReadonlyArray<unknown>;
+export type { LiveQueryKey };
 type UseLiveQueryConfigOptions<TContext extends Context> = Omit<LiveQueryCollectionConfig<TContext>, `query`> & {
     /**
      * Explicit identity for queries that contain opaque functional variants or
@@ -16,29 +16,34 @@ type UseLiveQueryConfigOptions<TContext extends Context> = Omit<LiveQueryCollect
     queryKey?: LiveQueryKey;
     /** Override the nearest DbProvider for this query. */
     client?: DbClient;
+    /**
+     * Pass `pooledLiveQueries` to share one partition among equality-filtered
+     * queries of one shape. Suspense and DbClient queries never pool.
+     */
+    pool?: PooledLiveQueries;
 };
 type ConfiguredQueryBuilder<TContext extends Context> = Extract<LiveQueryCollectionConfig<TContext>[`query`], QueryBuilder<TContext>>;
 export type UseLiveQueryConfig<TContext extends Context> = UseLiveQueryConfigOptions<TContext> & Pick<LiveQueryCollectionConfig<TContext>, `query`>;
 export type ConditionalUseLiveQueryConfig<TContext extends Context> = UseLiveQueryConfigOptions<TContext> & {
     query: ConfiguredQueryBuilder<TContext> | ((q: InitialQueryBuilder) => ConfiguredQueryBuilder<TContext> | undefined | null);
 };
-export declare function warnDeprecatedDepsArray(hookName?: `useLiveQuery` | `useLiveInfiniteQuery`): void;
 export declare function prepareQueryValue(value: unknown, dbClient: DbClient | undefined, deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>): unknown;
 type DerivedQueryPreparation = {
-    status: `hashable`;
     value: unknown;
     identityDeps: Array<unknown>;
-} | {
-    status: `unhashable`;
-    value: unknown;
-    error: UnhashableQueryIRError;
 };
-export declare function prepareDerivedQuery(value: unknown, dbClient: DbClient | undefined, profiler: DerivedIdentityProfiler, deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>): DerivedQueryPreparation;
-export declare function warnUnhashableDerivedIdentity(error: UnhashableQueryIRError): void;
+/** How a hook checks a prepared query whose identity it compares. */
+export declare function getIdentityScope(claims: LiveQuerySourceIdClaims, dbClient: DbClient | undefined, hookName: string): LiveQueryIdentityScope;
+/**
+ * Prepare a query without `queryKey`, derive its identity, and claim its
+ * source Collection IDs. A query whose IR has no stable identity throws
+ * `UnhashableQueryIRError`. The hook's render boundary releases the sync
+ * starts a rejected render deferred.
+ */
+export declare function prepareDerivedQuery(value: unknown, profiler: DerivedIdentityProfiler, scope: LiveQueryIdentityScope, deferredCollections: Set<CollectionImpl<any, string | number, any, any, any>>): DerivedQueryPreparation;
 /**
  * Create a live query using a query function.
  * @param queryFn - Query function that defines what data to fetch
- * @param deps - Deprecated array of dependencies that trigger query re-execution when changed
  * @returns Object with reactive data, state, and status information
  * @example
  * // Prefer config object syntax
@@ -91,12 +96,12 @@ export declare function warnUnhashableDerivedIdentity(error: UnhashableQueryIREr
  *
  * @example
  * // Handle loading and error states
- * const { data, isLoading, isError, status } = useLiveQuery({
+ * const { data, isLoading, isLoadingError, status } = useLiveQuery({
  *   query: (q) => q.from({ todos: todoCollection })
  * })
  *
  * if (isLoading) return <div>Loading...</div>
- * if (isError) return <div>Error: {status}</div>
+ * if (isLoadingError) return <div>Error: {status}</div>
  *
  * return (
  *   <ul>
@@ -104,85 +109,44 @@ export declare function warnUnhashableDerivedIdentity(error: UnhashableQueryIREr
  *   </ul>
  * )
  */
-export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>, deps?: Array<unknown>): {
+export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>): {
     state: Map<string | number, GetResult<TContext>>;
     data: InferResultType<TContext>;
     collection: Collection<GetResult<TContext>, string | number, {}>;
     status: CollectionStatus;
-    isLoading: boolean;
-    isReady: boolean;
-    persistedStatus: LiveQueryPersistedStatus;
-    isPersistedReady: boolean;
-    persistedError: unknown | undefined;
-    isIdle: boolean;
-    isError: boolean;
-    isCleanedUp: boolean;
     isEnabled: true;
-};
-export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext> | undefined | null, deps?: Array<unknown>): {
+} & LiveQueryStatusFlags;
+export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext> | undefined | null): {
     state: Map<string | number, GetResult<TContext>> | undefined;
     data: InferResultType<TContext> | undefined;
     collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
     status: UseLiveQueryStatus;
-    isLoading: boolean;
-    isReady: boolean;
-    persistedStatus: LiveQueryPersistedStatus;
-    isPersistedReady: boolean;
-    persistedError: unknown | undefined;
-    isIdle: boolean;
-    isError: boolean;
-    isCleanedUp: boolean;
     isEnabled: boolean;
-};
-export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => LiveQueryCollectionConfig<TContext> | undefined | null, deps?: Array<unknown>): {
+} & LiveQueryStatusFlags;
+export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => LiveQueryCollectionConfig<TContext> | undefined | null): {
     state: Map<string | number, GetResult<TContext>> | undefined;
     data: InferResultType<TContext> | undefined;
     collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
     status: UseLiveQueryStatus;
-    isLoading: boolean;
-    isReady: boolean;
-    persistedStatus: LiveQueryPersistedStatus;
-    isPersistedReady: boolean;
-    persistedError: unknown | undefined;
-    isIdle: boolean;
-    isError: boolean;
-    isCleanedUp: boolean;
     isEnabled: boolean;
-};
-export declare function useLiveQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(queryFn: (q: InitialQueryBuilder) => Collection<TResult, TKey, TUtils> | undefined | null, deps?: Array<unknown>): {
+} & LiveQueryStatusFlags;
+export declare function useLiveQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(queryFn: (q: InitialQueryBuilder) => Collection<TResult, TKey, TUtils> | undefined | null): {
     state: Map<TKey, TResult> | undefined;
     data: Array<TResult> | undefined;
     collection: Collection<TResult, TKey, TUtils> | undefined;
     status: UseLiveQueryStatus;
-    isLoading: boolean;
-    isReady: boolean;
-    persistedStatus: LiveQueryPersistedStatus;
-    isPersistedReady: boolean;
-    persistedError: unknown | undefined;
-    isIdle: boolean;
-    isError: boolean;
-    isCleanedUp: boolean;
     isEnabled: boolean;
-};
-export declare function useLiveQuery<TContext extends Context, TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext> | LiveQueryCollectionConfig<TContext> | Collection<TResult, TKey, TUtils> | undefined | null, deps?: Array<unknown>): {
+} & LiveQueryStatusFlags;
+export declare function useLiveQuery<TContext extends Context, TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext> | LiveQueryCollectionConfig<TContext> | Collection<TResult, TKey, TUtils> | undefined | null): {
     state: Map<string | number, GetResult<TContext>> | Map<TKey, TResult> | undefined;
     data: InferResultType<TContext> | Array<TResult> | undefined;
     collection: Collection<GetResult<TContext>, string | number, {}> | Collection<TResult, TKey, TUtils> | undefined;
     status: UseLiveQueryStatus;
-    isLoading: boolean;
-    isReady: boolean;
-    persistedStatus: LiveQueryPersistedStatus;
-    isPersistedReady: boolean;
-    persistedError: unknown | undefined;
-    isIdle: boolean;
-    isError: boolean;
-    isCleanedUp: boolean;
     isEnabled: boolean;
-};
+} & LiveQueryStatusFlags;
 /**
  * Create a live query using configuration object
  * @param config - Configuration object with query and options
- * @param deps - Deprecated array of dependencies that trigger query re-execution when changed
  * @returns Object with reactive data, state, and status information
  * @example
  * // Basic config object usage
@@ -204,12 +168,12 @@ export declare function useLiveQuery<TContext extends Context, TResult extends o
  *
  * @example
  * // Handle all states uniformly
- * const { data, isLoading, isReady, isError } = useLiveQuery({
+ * const { data, isLoading, isReady, isLoadingError } = useLiveQuery({
  *   query: (q) => q.from({ items: itemCollection })
  * })
  *
  * if (isLoading) return <div>Loading...</div>
- * if (isError) return <div>Something went wrong</div>
+ * if (isLoadingError) return <div>Something went wrong</div>
  * if (!isReady) return <div>Preparing...</div>
  *
  * return <div>{data.length} items loaded</div>
@@ -219,61 +183,15 @@ export declare function useLiveQuery<TContext extends Context>(config: UseLiveQu
     data: InferResultType<TContext>;
     collection: Collection<GetResult<TContext>, string | number, {}>;
     status: CollectionStatus;
-    isLoading: boolean;
-    isReady: boolean;
-    persistedStatus: LiveQueryPersistedStatus;
-    isPersistedReady: boolean;
-    persistedError: unknown | undefined;
-    isIdle: boolean;
-    isError: boolean;
-    isCleanedUp: boolean;
     isEnabled: true;
-};
+} & LiveQueryStatusFlags;
 export declare function useLiveQuery<TContext extends Context>(config: ConditionalUseLiveQueryConfig<TContext>): {
     state: Map<string | number, GetResult<TContext>> | undefined;
     data: InferResultType<TContext> | undefined;
     collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
     status: UseLiveQueryStatus;
-    isLoading: boolean;
-    isReady: boolean;
-    persistedStatus: LiveQueryPersistedStatus;
-    isPersistedReady: boolean;
-    persistedError: unknown | undefined;
-    isIdle: boolean;
-    isError: boolean;
-    isCleanedUp: boolean;
-    isEnabled: boolean;
-};
-export declare function useLiveQuery<TContext extends Context>(config: LiveQueryCollectionConfig<TContext>, deps?: Array<unknown>): {
-    state: Map<string | number, GetResult<TContext>>;
-    data: InferResultType<TContext>;
-    collection: Collection<GetResult<TContext>, string | number, {}>;
-    status: CollectionStatus;
-    isLoading: boolean;
-    isReady: boolean;
-    persistedStatus: LiveQueryPersistedStatus;
-    isPersistedReady: boolean;
-    persistedError: unknown | undefined;
-    isIdle: boolean;
-    isError: boolean;
-    isCleanedUp: boolean;
-    isEnabled: true;
-};
-export declare function useLiveQuery<TContext extends Context>(config: ConditionalUseLiveQueryConfig<TContext>, deps: Array<unknown>): {
-    state: Map<string | number, GetResult<TContext>> | undefined;
-    data: InferResultType<TContext> | undefined;
-    collection: Collection<GetResult<TContext>, string | number, {}> | undefined;
-    status: UseLiveQueryStatus;
-    isLoading: boolean;
-    isReady: boolean;
-    persistedStatus: LiveQueryPersistedStatus;
-    isPersistedReady: boolean;
-    persistedError: unknown | undefined;
-    isIdle: boolean;
-    isError: boolean;
-    isCleanedUp: boolean;
     isEnabled: boolean;
-};
+} & LiveQueryStatusFlags;
 /**
  * Subscribe to an existing live query collection
  * @param liveQueryCollection - Pre-created live query collection to subscribe to
@@ -296,10 +214,10 @@ export declare function useLiveQuery<TContext extends Context>(config: Condition
  *
  * @example
  * // Handle states consistently
- * const { data, isLoading, isError } = useLiveQuery(sharedCollection)
+ * const { data, isLoading, isLoadingError } = useLiveQuery(sharedCollection)
  *
  * if (isLoading) return <div>Loading...</div>
- * if (isError) return <div>Error loading data</div>
+ * if (isLoadingError) return <div>Error loading data</div>
  *
  * return <div>{data.map(item => <Item key={item.id} {...item} />)}</div>
  */
@@ -308,31 +226,14 @@ export declare function useLiveQuery<TResult extends object, TKey extends string
     data: Array<TResult>;
     collection: Collection<TResult, TKey, TUtils>;
     status: CollectionStatus;
-    isLoading: boolean;
-    isReady: boolean;
-    persistedStatus: LiveQueryPersistedStatus;
-    isPersistedReady: boolean;
-    persistedError: unknown | undefined;
-    isIdle: boolean;
-    isError: boolean;
-    isCleanedUp: boolean;
     isEnabled: true;
-};
+} & LiveQueryStatusFlags;
 export declare function useLiveQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult): {
     state: Map<TKey, TResult>;
     data: TResult | undefined;
     collection: Collection<TResult, TKey, TUtils> & SingleResult;
     status: CollectionStatus;
-    isLoading: boolean;
-    isReady: boolean;
-    persistedStatus: LiveQueryPersistedStatus;
-    isPersistedReady: boolean;
-    persistedError: unknown | undefined;
-    isIdle: boolean;
-    isError: boolean;
-    isCleanedUp: boolean;
     isEnabled: true;
-};
+} & LiveQueryStatusFlags;
 /** @internal Shared implementation for the Suspense wrapper. */
-export declare function useLiveQueryForSuspense(configOrQueryOrCollection: any, deps: Array<unknown> | undefined): any;
-export {};
+export declare function useLiveQueryForSuspense(configOrQueryOrCollection: any): any;