@tanstack/preact-db 0.0.0-stage → 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kyle Mathews
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @tanstack/preact-db
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Preact hooks for TanStack DB. See [TanStack/db](https://github.com/TanStack/db) for more details.
+
+## Installation
+
+```sh
+npm install @tanstack/preact-db
+```
+
+`@tanstack/preact-db` supports Preact 10 and later and ships as ES modules.
+
+Queries read concrete source Collections. Preact has no `DbProvider` yet, so it does not bind collection descriptors or read from a `DbClient`; a query over a descriptor throws when it is consumed. Use `@tanstack/react-db` or `@tanstack/svelte-db` for `DbClient`-based SSR and hydration.
+
+## Usage
+
+```tsx
+import { eq, useLiveQuery } from '@tanstack/preact-db'
+
+function TodoList({ userId }: { userId?: string }) {
+  const { data, isLoading } = useLiveQuery((q) =>
+    userId
+      ? q
+          .from({ todos: todosCollection })
+          .where(({ todos }) => eq(todos.userId, userId))
+      : undefined,
+  )
+
+  if (isLoading) return <div>Loading...</div>
+  return (
+    <ul>
+      {data?.map((todo) => (
+        <li key={todo.id}>{todo.text}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+`useLiveQuery` accepts a query callback, a `{ query }` config object, or an
+existing live-query Collection. Return `undefined` or `null` from the callback
+to disable the query. `useLiveInfiniteQuery` pages an ordered live query.
+
+The hooks derive each query's identity from its structured IR, so values the
+callback captures recompile the query when they change. A query that uses
+functional variants such as `fn.where` has no stable IR hash and throws
+`UnhashableQueryIRError` unless a config object names it with `queryKey`:
+
+```ts
+const { data } = useLiveQuery({
+  queryKey: [`todos-by-text`, search],
+  query: (q) =>
+    q
+      .from({ todos: todosCollection })
+      .fn.where(({ todos }) => todos.text.includes(search)),
+})
+```
+
+See the [Preact adapter documentation](https://tanstack.com/db/latest/docs/framework/preact/overview) for more.

package/dist/esm/index.d.ts

@@ -0,0 +1,7 @@
+export { useLiveQuery } from './useLiveQuery.js';
+export type { ConditionalUseLiveQueryConfig, UseConditionalLiveQueryResult, UseLiveQueryConfig, UseLiveQueryResult, UseLiveQueryStatus, } from './useLiveQuery.js';
+export { useLiveInfiniteQuery } from './useLiveInfiniteQuery.js';
+export type { UseLiveInfiniteQueryConfig, UseLiveInfiniteQueryReturn, UseLiveInfiniteQueryReturnWithCollection, } from './useLiveInfiniteQuery.js';
+export * from '@tanstack/db';
+export type { Collection } from '@tanstack/db';
+export { createTransaction } from '@tanstack/db';

package/dist/esm/index.js

@@ -0,0 +1,10 @@
+import { useLiveQuery } from "./useLiveQuery.js";
+import { useLiveInfiniteQuery } from "./useLiveInfiniteQuery.js";
+export * from "@tanstack/db";
+import { createTransaction } from "@tanstack/db";
+export {
+  createTransaction,
+  useLiveInfiniteQuery,
+  useLiveQuery
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}

package/dist/esm/useLiveInfiniteQuery.d.ts

@@ -0,0 +1,42 @@
+import { Collection, Context, InferResultType, InitialQueryBuilder, LiveQueryKey, NonSingleResult, QueryBuilder } from '@tanstack/db';
+import { UseLiveQueryResult } from './useLiveQuery.js';
+export type UseLiveInfiniteQueryConfig<_TContext extends Context> = {
+    /**
+     * Explicit identity for a query whose IR cannot derive one, such as a query
+     * with functional variants. Structured queries should omit it.
+     */
+    queryKey?: LiveQueryKey;
+    pageSize?: number;
+    /** First result-page label, not a server cursor or remote offset. */
+    initialPageParam?: number;
+};
+interface InfiniteQueryPagination<TRow> {
+    pages: Array<Array<TRow>>;
+    pageParams: Array<number>;
+    fetchNextPage: () => Promise<void>;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+}
+export type UseLiveInfiniteQueryReturn<TContext extends Context> = UseLiveQueryResult<InferResultType<TContext>[number], string | number, InferResultType<TContext>, Collection<InferResultType<TContext>[number], string | number, {}>> & InfiniteQueryPagination<InferResultType<TContext>[number]>;
+export type UseLiveInfiniteQueryReturnWithCollection<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>> = UseLiveQueryResult<TResult, TKey, Array<TResult>, Collection<TResult, TKey, TUtils> & NonSingleResult> & InfiniteQueryPagination<TResult>;
+/** What one hook instance renders until its input or page shape changes. */
+/**
+ * Page through an ordered live query, growing one live-query Collection's
+ * window with `utils.setWindow()` instead of recreating it per page.
+ *
+ * The query must include `.orderBy()`. Its identity follows `useLiveQuery`:
+ * derived from the query IR, or named by `queryKey`. A query whose IR cannot be
+ * hashed throws `UnhashableQueryIRError` unless `queryKey` is supplied.
+ *
+ * @example
+ * const { pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
+ *   (q) =>
+ *     q
+ *       .from({ posts: postsCollection })
+ *       .orderBy(({ posts }) => posts.createdAt, `desc`),
+ *   { pageSize: 20 },
+ * )
+ */
+export declare function useLiveInfiniteQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult, config: UseLiveInfiniteQueryConfig<any>): UseLiveInfiniteQueryReturnWithCollection<TResult, TKey, TUtils>;
+export declare function useLiveInfiniteQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>, config: UseLiveInfiniteQueryConfig<TContext>): UseLiveInfiniteQueryReturn<TContext>;
+export {};

package/dist/esm/useLiveInfiniteQuery.js

@@ -0,0 +1,76 @@
+import { useRef, useState, useLayoutEffect, useCallback } from "preact/hooks";
+import { readLiveQueryWindowPageShape, getLiveQueryKey, getLiveQueryHash, prepareLiveQueryValue, identifyLiveQuery, createLiveQuerySourceIdClaims, bindLiveQueryWindow, fetchNextLiveQueryWindowPage } from "@tanstack/db";
+function useLiveInfiniteQuery(queryFnOrCollection, config) {
+  const pageShape = readLiveQueryWindowPageShape(config);
+  const claimsRef = useRef(null);
+  const bindingRef = useRef(null);
+  let preparedValue;
+  let identity;
+  if (typeof queryFnOrCollection === `function`) {
+    const queryKey = getLiveQueryKey(config);
+    if (queryKey) {
+      identity = getLiveQueryHash(void 0, queryKey);
+    } else {
+      preparedValue = prepareLiveQueryValue(queryFnOrCollection, void 0);
+      identity = identifyLiveQuery(
+        preparedValue,
+        {
+          claims: claimsRef.current ??= createLiveQuerySourceIdClaims(),
+          client: void 0,
+          bindingName: `useLiveInfiniteQuery`
+        },
+        getLiveQueryHash
+      );
+    }
+  }
+  const binding = bindingRef.current = bindLiveQueryWindow(
+    bindingRef.current,
+    {
+      ...pageShape,
+      // Compile what this render prepared, so the callback runs once.
+      input: preparedValue === void 0 ? queryFnOrCollection : () => preparedValue,
+      dependencies: identity === void 0 ? void 0 : [identity],
+      recompile: `identity`
+    }
+  );
+  const { controller } = binding;
+  const snapshot = controller.getSnapshot();
+  const [, setRevision] = useState(0);
+  useLayoutEffect(() => {
+    const rerender = () => setRevision((revision) => revision + 1);
+    controller.subscribe(rerender);
+    if (controller.getSnapshot() !== snapshot) rerender();
+    if (binding.warning) console.warn(binding.warning);
+    return () => controller.dispose();
+  }, [controller]);
+  const fetchNextPage = useCallback(
+    () => fetchNextLiveQueryWindowPage(controller),
+    [controller]
+  );
+  return {
+    data: snapshot.data,
+    get state() {
+      return snapshot.state;
+    },
+    status: snapshot.status,
+    isLoading: snapshot.isLoading,
+    isReady: snapshot.isReady,
+    isIdle: snapshot.isIdle,
+    isLoadingError: snapshot.isLoadingError,
+    isCrashed: snapshot.isCrashed,
+    isCleanedUp: snapshot.isCleanedUp,
+    isSyncError: snapshot.isSyncError,
+    collection: snapshot.collection,
+    isEnabled: true,
+    pages: snapshot.pages,
+    pageParams: snapshot.pageParams,
+    fetchNextPage,
+    hasNextPage: snapshot.hasNextPage,
+    isFetchingNextPage: snapshot.isFetchingNextPage,
+    health: snapshot.health
+  };
+}
+export {
+  useLiveInfiniteQuery
+};
+//# sourceMappingURL=useLiveInfiniteQuery.js.map

package/dist/esm/useLiveInfiniteQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveInfiniteQuery.js","sources":["../../src/useLiveInfiniteQuery.ts"],"sourcesContent":["import { useCallback, useLayoutEffect, useRef, useState } from 'preact/hooks'\nimport {\n  bindLiveQueryWindow,\n  createLiveQuerySourceIdClaims,\n  fetchNextLiveQueryWindowPage,\n  getLiveQueryHash,\n  getLiveQueryKey,\n  identifyLiveQuery,\n  prepareLiveQueryValue,\n  readLiveQueryWindowPageShape,\n} from '@tanstack/db'\nimport type {\n  Collection,\n  CollectionStatus,\n  Context,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryKey,\n  LiveQuerySourceIdClaims,\n  LiveQueryWindowBinding,\n  NonSingleResult,\n  QueryBuilder,\n} from '@tanstack/db'\nimport type { UseLiveQueryResult } from './useLiveQuery'\n\n// Keep the generic parameter for typed config wrappers.\nexport type UseLiveInfiniteQueryConfig<_TContext extends Context> = {\n  /**\n   * Explicit identity for a query whose IR cannot derive one, such as a query\n   * with functional variants. Structured queries should omit it.\n   */\n  queryKey?: LiveQueryKey\n  pageSize?: number\n  /** First result-page label, not a server cursor or remote offset. */\n  initialPageParam?: number\n}\n\ninterface InfiniteQueryPagination<TRow> {\n  pages: Array<Array<TRow>>\n  pageParams: Array<number>\n  fetchNextPage: () => Promise<void>\n  hasNextPage: boolean\n  isFetchingNextPage: boolean\n}\n\nexport type UseLiveInfiniteQueryReturn<TContext extends Context> =\n  UseLiveQueryResult<\n    InferResultType<TContext>[number],\n    string | number,\n    InferResultType<TContext>,\n    Collection<InferResultType<TContext>[number], string | number, {}>\n  > &\n    InfiniteQueryPagination<InferResultType<TContext>[number]>\n\nexport type UseLiveInfiniteQueryReturnWithCollection<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n> = UseLiveQueryResult<\n  TResult,\n  TKey,\n  Array<TResult>,\n  Collection<TResult, TKey, TUtils> & NonSingleResult\n> &\n  InfiniteQueryPagination<TResult>\n\n/** What one hook instance renders until its input or page shape changes. */\n/**\n * Page through an ordered live query, growing one live-query Collection's\n * window with `utils.setWindow()` instead of recreating it per page.\n *\n * The query must include `.orderBy()`. Its identity follows `useLiveQuery`:\n * derived from the query IR, or named by `queryKey`. A query whose IR cannot be\n * hashed throws `UnhashableQueryIRError` unless `queryKey` is supplied.\n *\n * @example\n * const { pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(\n *   (q) =>\n *     q\n *       .from({ posts: postsCollection })\n *       .orderBy(({ posts }) => posts.createdAt, `desc`),\n *   { pageSize: 20 },\n * )\n */\nexport function useLiveInfiniteQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n  config: UseLiveInfiniteQueryConfig<any>,\n): UseLiveInfiniteQueryReturnWithCollection<TResult, TKey, TUtils>\n\nexport function useLiveInfiniteQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  config: UseLiveInfiniteQueryConfig<TContext>,\n): UseLiveInfiniteQueryReturn<TContext>\n\nexport function useLiveInfiniteQuery(\n  queryFnOrCollection: unknown,\n  config: UseLiveInfiniteQueryConfig<any>,\n): UseLiveInfiniteQueryReturn<any> {\n  const pageShape = readLiveQueryWindowPageShape(config)\n  const claimsRef = useRef<LiveQuerySourceIdClaims | null>(null)\n  const bindingRef = useRef<LiveQueryWindowBinding | null>(null)\n\n  // A query input's identity is a hash, so a structurally equal query keeps\n  // its loaded pages and a changed one compiles again.\n  let preparedValue: unknown\n  let identity: string | undefined\n  if (typeof queryFnOrCollection === `function`) {\n    const queryKey = getLiveQueryKey(config)\n    if (queryKey) {\n      identity = getLiveQueryHash(undefined, queryKey)\n    } else {\n      preparedValue = prepareLiveQueryValue(queryFnOrCollection, undefined)\n      identity = identifyLiveQuery(\n        preparedValue,\n        {\n          claims: (claimsRef.current ??= createLiveQuerySourceIdClaims()),\n          client: undefined,\n          bindingName: `useLiveInfiniteQuery`,\n        },\n        getLiveQueryHash,\n      )\n    }\n  }\n\n  const binding = (bindingRef.current = bindLiveQueryWindow(\n    bindingRef.current,\n    {\n      ...pageShape,\n      // Compile what this render prepared, so the callback runs once.\n      input:\n        preparedValue === undefined ? queryFnOrCollection : () => preparedValue,\n      dependencies: identity === undefined ? undefined : [identity],\n      recompile: `identity`,\n    },\n  ))\n\n  const { controller } = binding\n  const snapshot = controller.getSnapshot()\n  const [, setRevision] = useState(0)\n\n  useLayoutEffect(() => {\n    const rerender = () => setRevision((revision) => revision + 1)\n    controller.subscribe(rerender)\n    // The query can publish between this render and its subscription.\n    if (controller.getSnapshot() !== snapshot) rerender()\n    if (binding.warning) console.warn(binding.warning)\n    // Each binding owns its controller, so disposal also detaches this\n    // subscription and releases its window lease.\n    return () => controller.dispose()\n  }, [controller])\n\n  const fetchNextPage = useCallback(\n    () => fetchNextLiveQueryWindowPage(controller),\n    [controller],\n  )\n\n  return {\n    data: snapshot.data,\n    get state() {\n      return snapshot.state\n    },\n    status: snapshot.status as CollectionStatus,\n    isLoading: snapshot.isLoading,\n    isReady: snapshot.isReady,\n    isIdle: snapshot.isIdle,\n    isLoadingError: snapshot.isLoadingError,\n    isCrashed: snapshot.isCrashed,\n    isCleanedUp: snapshot.isCleanedUp,\n    isSyncError: snapshot.isSyncError,\n    collection: snapshot.collection,\n    isEnabled: true,\n    pages: snapshot.pages,\n    pageParams: snapshot.pageParams,\n    fetchNextPage,\n    hasNextPage: snapshot.hasNextPage,\n    isFetchingNextPage: snapshot.isFetchingNextPage,\n    health: snapshot.health,\n  } as UseLiveInfiniteQueryReturn<any>\n}\n"],"names":[],"mappings":";;AAkGO,SAAS,qBACd,qBACA,QACiC;AACjC,QAAM,YAAY,6BAA6B,MAAM;AACrD,QAAM,YAAY,OAAuC,IAAI;AAC7D,QAAM,aAAa,OAAsC,IAAI;AAI7D,MAAI;AACJ,MAAI;AACJ,MAAI,OAAO,wBAAwB,YAAY;AAC7C,UAAM,WAAW,gBAAgB,MAAM;AACvC,QAAI,UAAU;AACZ,iBAAW,iBAAiB,QAAW,QAAQ;AAAA,IACjD,OAAO;AACL,sBAAgB,sBAAsB,qBAAqB,MAAS;AACpE,iBAAW;AAAA,QACT;AAAA,QACA;AAAA,UACE,QAAS,UAAU,YAAY,8BAAA;AAAA,UAC/B,QAAQ;AAAA,UACR,aAAa;AAAA,QAAA;AAAA,QAEf;AAAA,MAAA;AAAA,IAEJ;AAAA,EACF;AAEA,QAAM,UAAW,WAAW,UAAU;AAAA,IACpC,WAAW;AAAA,IACX;AAAA,MACE,GAAG;AAAA;AAAA,MAEH,OACE,kBAAkB,SAAY,sBAAsB,MAAM;AAAA,MAC5D,cAAc,aAAa,SAAY,SAAY,CAAC,QAAQ;AAAA,MAC5D,WAAW;AAAA,IAAA;AAAA,EACb;AAGF,QAAM,EAAE,eAAe;AACvB,QAAM,WAAW,WAAW,YAAA;AAC5B,QAAM,GAAG,WAAW,IAAI,SAAS,CAAC;AAElC,kBAAgB,MAAM;AACpB,UAAM,WAAW,MAAM,YAAY,CAAC,aAAa,WAAW,CAAC;AAC7D,eAAW,UAAU,QAAQ;AAE7B,QAAI,WAAW,kBAAkB,SAAU,UAAA;AAC3C,QAAI,QAAQ,QAAS,SAAQ,KAAK,QAAQ,OAAO;AAGjD,WAAO,MAAM,WAAW,QAAA;AAAA,EAC1B,GAAG,CAAC,UAAU,CAAC;AAEf,QAAM,gBAAgB;AAAA,IACpB,MAAM,6BAA6B,UAAU;AAAA,IAC7C,CAAC,UAAU;AAAA,EAAA;AAGb,SAAO;AAAA,IACL,MAAM,SAAS;AAAA,IACf,IAAI,QAAQ;AACV,aAAO,SAAS;AAAA,IAClB;AAAA,IACA,QAAQ,SAAS;AAAA,IACjB,WAAW,SAAS;AAAA,IACpB,SAAS,SAAS;AAAA,IAClB,QAAQ,SAAS;AAAA,IACjB,gBAAgB,SAAS;AAAA,IACzB,WAAW,SAAS;AAAA,IACpB,aAAa,SAAS;AAAA,IACtB,aAAa,SAAS;AAAA,IACtB,YAAY,SAAS;AAAA,IACrB,WAAW;AAAA,IACX,OAAO,SAAS;AAAA,IAChB,YAAY,SAAS;AAAA,IACrB;AAAA,IACA,aAAa,SAAS;AAAA,IACtB,oBAAoB,SAAS;AAAA,IAC7B,QAAQ,SAAS;AAAA,EAAA;AAErB;"}

package/dist/esm/useLiveQuery.d.ts

@@ -0,0 +1,93 @@
+import { Collection, CollectionStatus, Context, GetResult, InferResultType, InitialQueryBuilder, LiveQueryCollectionConfig, LiveQueryKey, LiveQueryStatusFlags, NonSingleResult, PooledLiveQueries, QueryBuilder, SingleResult } from '@tanstack/db';
+export type UseLiveQueryStatus = CollectionStatus | `disabled`;
+type ConfiguredQueryBuilder<TContext extends Context> = Extract<LiveQueryCollectionConfig<TContext>[`query`], QueryBuilder<TContext>>;
+type UseLiveQueryConfigOptions<TContext extends Context> = Omit<LiveQueryCollectionConfig<TContext>, `query`> & {
+    /**
+     * Explicit identity for a query whose IR cannot derive one, such as a query
+     * with functional variants. Structured queries should omit it.
+     */
+    queryKey?: LiveQueryKey;
+    /**
+     * Pass `pooledLiveQueries` to share one partition among equality-filtered
+     * queries of one shape.
+     */
+    pool?: PooledLiveQueries;
+};
+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);
+};
+/** The result of a live query that is always enabled. */
+export interface UseLiveQueryResult<TResult extends object, TKey extends string | number, TData, TCollection> extends LiveQueryStatusFlags {
+    state: ReadonlyMap<TKey, TResult>;
+    data: TData;
+    collection: TCollection;
+    status: CollectionStatus;
+    isEnabled: true;
+}
+/** The result of a live query whose callback can disable it. */
+export interface UseConditionalLiveQueryResult<TResult extends object, TKey extends string | number, TData, TCollection> extends LiveQueryStatusFlags {
+    state: ReadonlyMap<TKey, TResult> | undefined;
+    data: TData | undefined;
+    collection: TCollection | undefined;
+    status: UseLiveQueryStatus;
+    isEnabled: boolean;
+}
+type QueryResult<TContext extends Context> = UseLiveQueryResult<GetResult<TContext>, string | number, InferResultType<TContext>, Collection<GetResult<TContext>, string | number, {}>>;
+type ConditionalQueryResult<TContext extends Context> = UseConditionalLiveQueryResult<GetResult<TContext>, string | number, InferResultType<TContext>, Collection<GetResult<TContext>, string | number, {}>>;
+/**
+ * Subscribe a Preact component to a live query.
+ *
+ * The hook derives the query's identity from its structured IR on each render,
+ * so values captured by the callback recompile the query when they change. A
+ * query whose IR cannot be hashed, such as one using `fn.where`, throws
+ * `UnhashableQueryIRError` unless its config supplies `queryKey`. While the
+ * hook is mounted, each Collection ID its queries read must keep naming one
+ * source object, or it throws `SourceCollectionIdReuseError`.
+ * Return `undefined` or `null` from the callback to disable the query.
+ *
+ * @example
+ * const { data, isLoading } = useLiveQuery((q) =>
+ *   q
+ *     .from({ todos: todosCollection })
+ *     .where(({ todos }) => eq(todos.completed, false)),
+ * )
+ *
+ * @example
+ * // Disable the query until its input exists
+ * const { data, isEnabled } = useLiveQuery((q) =>
+ *   userId
+ *     ? q
+ *         .from({ todos: todosCollection })
+ *         .where(({ todos }) => eq(todos.userId, userId))
+ *     : undefined,
+ * )
+ */
+export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>): QueryResult<TContext>;
+export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext> | undefined | null): ConditionalQueryResult<TContext>;
+export declare function useLiveQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => LiveQueryCollectionConfig<TContext> | undefined | null): ConditionalQueryResult<TContext>;
+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): UseConditionalLiveQueryResult<TResult, TKey, Array<TResult>, Collection<TResult, TKey, TUtils>>;
+/**
+ * Subscribe to a live query described by a config object.
+ *
+ * @example
+ * const { data } = useLiveQuery({
+ *   query: (q) => q.from({ todos: todosCollection }),
+ *   gcTime: 60_000,
+ * })
+ */
+export declare function useLiveQuery<TContext extends Context>(config: UseLiveQueryConfig<TContext>): QueryResult<TContext>;
+export declare function useLiveQuery<TContext extends Context>(config: ConditionalUseLiveQueryConfig<TContext>): ConditionalQueryResult<TContext>;
+/**
+ * Subscribe to an existing live-query Collection. The hook starts its sync and
+ * leaves its retention policy to the caller.
+ *
+ * @example
+ * const activeTodos = createLiveQueryCollection((q) =>
+ *   q.from({ todos: todosCollection }).where(({ todos }) => todos.active),
+ * )
+ * const { data, collection } = useLiveQuery(activeTodos)
+ */
+export declare function useLiveQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult): UseLiveQueryResult<TResult, TKey, Array<TResult>, Collection<TResult, TKey, TUtils>>;
+export declare function useLiveQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult): UseLiveQueryResult<TResult, TKey, TResult | undefined, Collection<TResult, TKey, TUtils> & SingleResult>;
+export {};

package/dist/esm/useLiveQuery.js

@@ -0,0 +1,44 @@
+import { useRef, useState, useLayoutEffect } from "preact/hooks";
+import { prepareLiveQueryValue, getLiveQueryKey, isCollection, getLiveQueryHash, identifyLiveQuery, createLiveQuerySourceIdClaims, createLiveQueryObserver, resolveLiveQueryValue } from "@tanstack/db";
+const DEFAULT_GC_TIME_MS = 1;
+function useLiveQuery(input) {
+  const claimsRef = useRef(null);
+  const preparedValue = prepareLiveQueryValue(input, void 0);
+  const queryKey = getLiveQueryKey(input);
+  const identity = isCollection(input) ? input : queryKey ? getLiveQueryHash(preparedValue, queryKey) : identifyLiveQuery(
+    preparedValue,
+    {
+      claims: claimsRef.current ??= createLiveQuerySourceIdClaims(),
+      client: void 0,
+      bindingName: `useLiveQuery`
+    },
+    getLiveQueryHash
+  );
+  const bindingRef = useRef(null);
+  let binding = bindingRef.current;
+  if (binding?.identity !== identity) {
+    binding = bindingRef.current = {
+      identity,
+      // Wholesale mode publishes nothing during subscribe; the hook re-reads
+      // the observer's snapshot on each notification.
+      observer: createLiveQueryObserver(
+        resolveLiveQueryValue(preparedValue, { gcTime: DEFAULT_GC_TIME_MS }),
+        { mode: `wholesale` }
+      )
+    };
+  }
+  const { observer } = binding;
+  const snapshot = observer.getSnapshot();
+  const [, setRevision] = useState(0);
+  useLayoutEffect(() => {
+    const rerender = () => setRevision((revision) => revision + 1);
+    observer.subscribe(rerender);
+    if (observer.getSnapshot() !== snapshot) rerender();
+    return () => observer.dispose();
+  }, [observer]);
+  return snapshot;
+}
+export {
+  useLiveQuery
+};
+//# sourceMappingURL=useLiveQuery.js.map

package/dist/esm/useLiveQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveQuery.js","sources":["../../src/useLiveQuery.ts"],"sourcesContent":["import { useLayoutEffect, useRef, useState } from 'preact/hooks'\nimport {\n  createLiveQueryObserver,\n  createLiveQuerySourceIdClaims,\n  getLiveQueryHash,\n  getLiveQueryKey,\n  identifyLiveQuery,\n  isCollection,\n  prepareLiveQueryValue,\n  resolveLiveQueryValue,\n} from '@tanstack/db'\nimport type {\n  Collection,\n  CollectionStatus,\n  Context,\n  GetResult,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  LiveQueryKey,\n  LiveQueryObserver,\n  LiveQuerySourceIdClaims,\n  LiveQueryStatusFlags,\n  NonSingleResult,\n  PooledLiveQueries,\n  QueryBuilder,\n  SingleResult,\n} from '@tanstack/db'\n\n// A live query this hook creates from a callback or config retires 1 ms after\n// its last subscriber leaves. A supplied Collection, or a config with an\n// explicit `gcTime`, keeps the caller's retention policy.\nconst DEFAULT_GC_TIME_MS = 1\n\nexport type UseLiveQueryStatus = CollectionStatus | `disabled`\n\ntype ConfiguredQueryBuilder<TContext extends Context> = Extract<\n  LiveQueryCollectionConfig<TContext>[`query`],\n  QueryBuilder<TContext>\n>\n\ntype UseLiveQueryConfigOptions<TContext extends Context> = Omit<\n  LiveQueryCollectionConfig<TContext>,\n  `query`\n> & {\n  /**\n   * Explicit identity for a query whose IR cannot derive one, such as a query\n   * with functional variants. Structured queries should omit it.\n   */\n  queryKey?: LiveQueryKey\n  /**\n   * Pass `pooledLiveQueries` to share one partition among equality-filtered\n   * queries of one shape.\n   */\n  pool?: PooledLiveQueries\n}\n\nexport type UseLiveQueryConfig<TContext extends Context> =\n  UseLiveQueryConfigOptions<TContext> &\n    Pick<LiveQueryCollectionConfig<TContext>, `query`>\n\nexport type ConditionalUseLiveQueryConfig<TContext extends Context> =\n  UseLiveQueryConfigOptions<TContext> & {\n    query:\n      | ConfiguredQueryBuilder<TContext>\n      | ((\n          q: InitialQueryBuilder,\n        ) => ConfiguredQueryBuilder<TContext> | undefined | null)\n  }\n\n/** The result of a live query that is always enabled. */\nexport interface UseLiveQueryResult<\n  TResult extends object,\n  TKey extends string | number,\n  TData,\n  TCollection,\n> extends LiveQueryStatusFlags {\n  state: ReadonlyMap<TKey, TResult>\n  data: TData\n  collection: TCollection\n  status: CollectionStatus\n  isEnabled: true\n}\n\n/** The result of a live query whose callback can disable it. */\nexport interface UseConditionalLiveQueryResult<\n  TResult extends object,\n  TKey extends string | number,\n  TData,\n  TCollection,\n> extends LiveQueryStatusFlags {\n  state: ReadonlyMap<TKey, TResult> | undefined\n  data: TData | undefined\n  collection: TCollection | undefined\n  status: UseLiveQueryStatus\n  isEnabled: boolean\n}\n\ntype QueryResult<TContext extends Context> = UseLiveQueryResult<\n  GetResult<TContext>,\n  string | number,\n  InferResultType<TContext>,\n  Collection<GetResult<TContext>, string | number, {}>\n>\n\ntype ConditionalQueryResult<TContext extends Context> =\n  UseConditionalLiveQueryResult<\n    GetResult<TContext>,\n    string | number,\n    InferResultType<TContext>,\n    Collection<GetResult<TContext>, string | number, {}>\n  >\n\n/**\n * Subscribe a Preact component to a live query.\n *\n * The hook derives the query's identity from its structured IR on each render,\n * so values captured by the callback recompile the query when they change. A\n * query whose IR cannot be hashed, such as one using `fn.where`, throws\n * `UnhashableQueryIRError` unless its config supplies `queryKey`. While the\n * hook is mounted, each Collection ID its queries read must keep naming one\n * source object, or it throws `SourceCollectionIdReuseError`.\n * Return `undefined` or `null` from the callback to disable the query.\n *\n * @example\n * const { data, isLoading } = useLiveQuery((q) =>\n *   q\n *     .from({ todos: todosCollection })\n *     .where(({ todos }) => eq(todos.completed, false)),\n * )\n *\n * @example\n * // Disable the query until its input exists\n * const { data, isEnabled } = useLiveQuery((q) =>\n *   userId\n *     ? q\n *         .from({ todos: todosCollection })\n *         .where(({ todos }) => eq(todos.userId, userId))\n *     : undefined,\n * )\n */\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n): QueryResult<TContext>\n\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => QueryBuilder<TContext> | undefined | null,\n): ConditionalQueryResult<TContext>\n\nexport function useLiveQuery<TContext extends Context>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => LiveQueryCollectionConfig<TContext> | undefined | null,\n): ConditionalQueryResult<TContext>\n\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  queryFn: (\n    q: InitialQueryBuilder,\n  ) => Collection<TResult, TKey, TUtils> | undefined | null,\n): UseConditionalLiveQueryResult<\n  TResult,\n  TKey,\n  Array<TResult>,\n  Collection<TResult, TKey, TUtils>\n>\n\n/**\n * Subscribe to a live query described by a config object.\n *\n * @example\n * const { data } = useLiveQuery({\n *   query: (q) => q.from({ todos: todosCollection }),\n *   gcTime: 60_000,\n * })\n */\nexport function useLiveQuery<TContext extends Context>(\n  config: UseLiveQueryConfig<TContext>,\n): QueryResult<TContext>\n\nexport function useLiveQuery<TContext extends Context>(\n  config: ConditionalUseLiveQueryConfig<TContext>,\n): ConditionalQueryResult<TContext>\n\n/**\n * Subscribe to an existing live-query Collection. The hook starts its sync and\n * leaves its retention policy to the caller.\n *\n * @example\n * const activeTodos = createLiveQueryCollection((q) =>\n *   q.from({ todos: todosCollection }).where(({ todos }) => todos.active),\n * )\n * const { data, collection } = useLiveQuery(activeTodos)\n */\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n): UseLiveQueryResult<\n  TResult,\n  TKey,\n  Array<TResult>,\n  Collection<TResult, TKey, TUtils>\n>\n\nexport function useLiveQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult,\n): UseLiveQueryResult<\n  TResult,\n  TKey,\n  TResult | undefined,\n  Collection<TResult, TKey, TUtils> & SingleResult\n>\n\nexport function useLiveQuery(\n  input: unknown,\n): UseConditionalLiveQueryResult<\n  object,\n  string | number,\n  unknown,\n  Collection<object, string | number, any>\n> {\n  const claimsRef = useRef<LiveQuerySourceIdClaims | null>(null)\n  const preparedValue = prepareLiveQueryValue(input, undefined)\n  const queryKey = getLiveQueryKey(input)\n  // A supplied Collection is not compiled, so its object is its identity.\n  const identity = isCollection(input)\n    ? input\n    : queryKey\n      ? getLiveQueryHash(preparedValue, queryKey)\n      : identifyLiveQuery(\n          preparedValue,\n          {\n            claims: (claimsRef.current ??= createLiveQuerySourceIdClaims()),\n            client: undefined,\n            bindingName: `useLiveQuery`,\n          },\n          getLiveQueryHash,\n        )\n\n  const bindingRef = useRef<LiveQueryBinding | null>(null)\n  let binding = bindingRef.current\n  if (binding?.identity !== identity) {\n    binding = bindingRef.current = {\n      identity,\n      // Wholesale mode publishes nothing during subscribe; the hook re-reads\n      // the observer's snapshot on each notification.\n      observer: createLiveQueryObserver(\n        resolveLiveQueryValue(preparedValue, { gcTime: DEFAULT_GC_TIME_MS }),\n        { mode: `wholesale` },\n      ),\n    }\n  }\n\n  const { observer } = binding\n  const snapshot = observer.getSnapshot()\n  const [, setRevision] = useState(0)\n\n  useLayoutEffect(() => {\n    const rerender = () => setRevision((revision) => revision + 1)\n    observer.subscribe(rerender)\n    // The query can publish between this render and its subscription.\n    if (observer.getSnapshot() !== snapshot) rerender()\n    // Each binding owns its observer, so disposal also detaches this\n    // subscription and releases the live-query Collection.\n    return () => observer.dispose()\n  }, [observer])\n\n  return snapshot\n}\n\n/** The live query one hook instance reads until its identity changes. */\ninterface LiveQueryBinding {\n  identity: unknown\n  observer: LiveQueryObserver<object, string | number>\n}\n"],"names":[],"mappings":";;AAgCA,MAAM,qBAAqB;AAiMpB,SAAS,aACd,OAMA;AACA,QAAM,YAAY,OAAuC,IAAI;AAC7D,QAAM,gBAAgB,sBAAsB,OAAO,MAAS;AAC5D,QAAM,WAAW,gBAAgB,KAAK;AAEtC,QAAM,WAAW,aAAa,KAAK,IAC/B,QACA,WACE,iBAAiB,eAAe,QAAQ,IACxC;AAAA,IACE;AAAA,IACA;AAAA,MACE,QAAS,UAAU,YAAY,8BAAA;AAAA,MAC/B,QAAQ;AAAA,MACR,aAAa;AAAA,IAAA;AAAA,IAEf;AAAA,EAAA;AAGR,QAAM,aAAa,OAAgC,IAAI;AACvD,MAAI,UAAU,WAAW;AACzB,MAAI,SAAS,aAAa,UAAU;AAClC,cAAU,WAAW,UAAU;AAAA,MAC7B;AAAA;AAAA;AAAA,MAGA,UAAU;AAAA,QACR,sBAAsB,eAAe,EAAE,QAAQ,oBAAoB;AAAA,QACnE,EAAE,MAAM,YAAA;AAAA,MAAY;AAAA,IACtB;AAAA,EAEJ;AAEA,QAAM,EAAE,aAAa;AACrB,QAAM,WAAW,SAAS,YAAA;AAC1B,QAAM,GAAG,WAAW,IAAI,SAAS,CAAC;AAElC,kBAAgB,MAAM;AACpB,UAAM,WAAW,MAAM,YAAY,CAAC,aAAa,WAAW,CAAC;AAC7D,aAAS,UAAU,QAAQ;AAE3B,QAAI,SAAS,kBAAkB,SAAU,UAAA;AAGzC,WAAO,MAAM,SAAS,QAAA;AAAA,EACxB,GAAG,CAAC,QAAQ,CAAC;AAEb,SAAO;AACT;"}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@tanstack/preact-db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.1",
+  "description": "Preact integration for @tanstack/db",
+  "author": "Kyle Mathews",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/db.git",
+    "directory": "packages/preact-db"
+  },
+  "homepage": "https://tanstack.com/db",
+  "keywords": [
+    "optimistic",
+    "preact",
+    "typescript",
+    "tanstack-intent"
+  ],
+  "type": "module",
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "skills"
+  ],
+  "dependencies": {
+    "@tanstack/db": "1.0.0-rc.1"
+  },
+  "peerDependencies": {
+    "preact": ">=10.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-istanbul": "^4.1.12",
+    "preact": "^11.0.1"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "test": "vitest --run",
+    "lint": "eslint . --fix"
+  }
 }

package/skills/preact-db/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: preact-db
+description: >
+  Preact bindings for TanStack DB. useLiveQuery hook with query callbacks,
+  { query, queryKey } config objects, or pre-created collections; identity is
+  derived from query IR, with no dependency arrays. Conditional queries via
+  returning undefined/null. useLiveInfiniteQuery for paging an ordered live
+  query. Functional variants (fn.where) require queryKey. Import from
+  @tanstack/preact-db (re-exports all of @tanstack/db).
+type: framework
+library: db
+framework: preact
+library_version: '0.6.17'
+requires:
+  - db-core
+sources:
+  - 'TanStack/db:docs/framework/preact/overview.md'
+  - 'TanStack/db:packages/preact-db/src/useLiveQuery.ts'
+  - 'TanStack/db:packages/preact-db/src/useLiveInfiniteQuery.ts'
+---
+
+This skill builds on db-core. Read it first for collection setup, query builder, and mutation patterns.
+
+Queries read concrete source Collections. Preact has no `DbProvider` yet, so it does not bind collection descriptors or read from a `DbClient`; a query over a descriptor throws when it is consumed. Use `@tanstack/react-db` or `@tanstack/svelte-db` for `DbClient`-based SSR and hydration.
+
+# TanStack DB — Preact
+
+## Setup
+
+```tsx
+import { eq, not, useLiveQuery } from '@tanstack/preact-db'
+
+function TodoList() {
+  const { data, isLoading } = useLiveQuery((q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => not(todo.completed))
+      .orderBy(({ todo }) => todo.created_at, 'asc'),
+  )
+
+  if (isLoading) return <div>Loading...</div>
+  return (
+    <ul>
+      {data.map((todo) => (
+        <li key={todo.id}>{todo.text}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+`@tanstack/preact-db` re-exports everything from `@tanstack/db`. It supports Preact 10+ and ships ES modules only.
+
+## Hooks
+
+### useLiveQuery
+
+```tsx
+// Query callback
+const { data, state, status, isReady, isEnabled } = useLiveQuery((q) =>
+  q.from({ todo: todoCollection }),
+)
+
+// Config object (required for queryKey)
+const { data } = useLiveQuery({
+  query: (q) => q.from({ todo: todoCollection }),
+  gcTime: 60_000,
+})
+
+// Pre-created live query collection
+const { data } = useLiveQuery(activeTodosCollection)
+
+// Disabled until an input exists: data and state are undefined
+const { data, isEnabled } = useLiveQuery((q) =>
+  userId
+    ? q
+        .from({ todo: todoCollection })
+        .where(({ todo }) => eq(todo.userId, userId))
+    : undefined,
+)
+```
+
+`isLoadingError` means the first load failed and there is nothing to show; offer `collection.reload()`. `isCrashed` means local storage broke; only `cleanup({ dependents: true })` and a fresh start recover. After the query is ready, sync problems never change `status`: read `isSyncError` or the `health` tree to show stale-data warnings. There is no `isError`.
+
+### useLiveInfiniteQuery
+
+```tsx
+const { data, pages, fetchNextPage, hasNextPage, isFetchingNextPage } =
+  useLiveInfiniteQuery(
+    (q) =>
+      q
+        .from({ post: postsCollection })
+        .orderBy(({ post }) => post.createdAt, 'desc'),
+    { pageSize: 20 },
+  )
+```
+
+The query must include `.orderBy()`. `fetchNextPage()` resolves when the page request settles; a failed page load does not reject or change `status`; it appears as a request error in the returned `health` tree. `getNextPageParam` is rejected.
+
+## Preact-Specific Patterns
+
+### Query identity
+
+The hook derives identity from the query IR on every render. Captured values in structured expressions recompile the query when they change, so there is no dependency array:
+
+```tsx
+function Filtered({ minPriority }: { minPriority: number }) {
+  const { data } = useLiveQuery((q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => gt(todo.priority, minPriority)),
+  )
+  return <div>{data.length}</div>
+}
+```
+
+While a hook is mounted, a source Collection ID must keep naming the same Collection object. A different object under a previously read ID throws `SourceCollectionIdReuseError`.
+
+## Common Mistakes
+
+### CRITICAL Using opaque query logic without queryKey
+
+Wrong:
+
+```tsx
+const { data } = useLiveQuery((q) =>
+  q
+    .from({ todo: todoCollection })
+    .fn.where(({ todo }) => todo.text.includes(search)),
+)
+```
+
+Correct:
+
+```tsx
+const { data } = useLiveQuery({
+  queryKey: [todoCollection.id, 'search', search],
+  query: (q) =>
+    q
+      .from({ todo: todoCollection })
+      .fn.where(({ todo }) => todo.text.includes(search)),
+})
+```
+
+Functional variants (`fn.where`, `fn.select`, `fn.having`) have no stable IR identity, so without `queryKey` the hook throws `UnhashableQueryIRError`. Put every value the function captures into the key.
+
+### HIGH Using === instead of eq() in .where()
+
+`.where(({ todo }) => todo.completed === false)` compares a query reference, not a value. Use `eq(todo.completed, false)` or `not(todo.completed)`.
+
+### HIGH Reading data of a disabled query without narrowing
+
+A callback that can return `undefined` makes `data` possibly `undefined`. Check `isEnabled` or use `data?.`.

package/src/index.ts

@@ -0,0 +1,22 @@
+// Re-export all public APIs
+export { useLiveQuery } from './useLiveQuery'
+export type {
+  ConditionalUseLiveQueryConfig,
+  UseConditionalLiveQueryResult,
+  UseLiveQueryConfig,
+  UseLiveQueryResult,
+  UseLiveQueryStatus,
+} from './useLiveQuery'
+export { useLiveInfiniteQuery } from './useLiveInfiniteQuery'
+export type {
+  UseLiveInfiniteQueryConfig,
+  UseLiveInfiniteQueryReturn,
+  UseLiveInfiniteQueryReturnWithCollection,
+} from './useLiveInfiniteQuery'
+
+// Re-export everything from @tanstack/db
+export * from '@tanstack/db'
+
+// Re-export some stuff explicitly to ensure the type & value is exported
+export type { Collection } from '@tanstack/db'
+export { createTransaction } from '@tanstack/db'

package/src/useLiveInfiniteQuery.ts

@@ -0,0 +1,183 @@
+import { useCallback, useLayoutEffect, useRef, useState } from 'preact/hooks'
+import {
+  bindLiveQueryWindow,
+  createLiveQuerySourceIdClaims,
+  fetchNextLiveQueryWindowPage,
+  getLiveQueryHash,
+  getLiveQueryKey,
+  identifyLiveQuery,
+  prepareLiveQueryValue,
+  readLiveQueryWindowPageShape,
+} from '@tanstack/db'
+import type {
+  Collection,
+  CollectionStatus,
+  Context,
+  InferResultType,
+  InitialQueryBuilder,
+  LiveQueryKey,
+  LiveQuerySourceIdClaims,
+  LiveQueryWindowBinding,
+  NonSingleResult,
+  QueryBuilder,
+} from '@tanstack/db'
+import type { UseLiveQueryResult } from './useLiveQuery'
+
+// Keep the generic parameter for typed config wrappers.
+export type UseLiveInfiniteQueryConfig<_TContext extends Context> = {
+  /**
+   * Explicit identity for a query whose IR cannot derive one, such as a query
+   * with functional variants. Structured queries should omit it.
+   */
+  queryKey?: LiveQueryKey
+  pageSize?: number
+  /** First result-page label, not a server cursor or remote offset. */
+  initialPageParam?: number
+}
+
+interface InfiniteQueryPagination<TRow> {
+  pages: Array<Array<TRow>>
+  pageParams: Array<number>
+  fetchNextPage: () => Promise<void>
+  hasNextPage: boolean
+  isFetchingNextPage: boolean
+}
+
+export type UseLiveInfiniteQueryReturn<TContext extends Context> =
+  UseLiveQueryResult<
+    InferResultType<TContext>[number],
+    string | number,
+    InferResultType<TContext>,
+    Collection<InferResultType<TContext>[number], string | number, {}>
+  > &
+    InfiniteQueryPagination<InferResultType<TContext>[number]>
+
+export type UseLiveInfiniteQueryReturnWithCollection<
+  TResult extends object,
+  TKey extends string | number,
+  TUtils extends Record<string, any>,
+> = UseLiveQueryResult<
+  TResult,
+  TKey,
+  Array<TResult>,
+  Collection<TResult, TKey, TUtils> & NonSingleResult
+> &
+  InfiniteQueryPagination<TResult>
+
+/** What one hook instance renders until its input or page shape changes. */
+/**
+ * Page through an ordered live query, growing one live-query Collection's
+ * window with `utils.setWindow()` instead of recreating it per page.
+ *
+ * The query must include `.orderBy()`. Its identity follows `useLiveQuery`:
+ * derived from the query IR, or named by `queryKey`. A query whose IR cannot be
+ * hashed throws `UnhashableQueryIRError` unless `queryKey` is supplied.
+ *
+ * @example
+ * const { pages, fetchNextPage, hasNextPage } = useLiveInfiniteQuery(
+ *   (q) =>
+ *     q
+ *       .from({ posts: postsCollection })
+ *       .orderBy(({ posts }) => posts.createdAt, `desc`),
+ *   { pageSize: 20 },
+ * )
+ */
+export function useLiveInfiniteQuery<
+  TResult extends object,
+  TKey extends string | number,
+  TUtils extends Record<string, any>,
+>(
+  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,
+  config: UseLiveInfiniteQueryConfig<any>,
+): UseLiveInfiniteQueryReturnWithCollection<TResult, TKey, TUtils>
+
+export function useLiveInfiniteQuery<TContext extends Context>(
+  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
+  config: UseLiveInfiniteQueryConfig<TContext>,
+): UseLiveInfiniteQueryReturn<TContext>
+
+export function useLiveInfiniteQuery(
+  queryFnOrCollection: unknown,
+  config: UseLiveInfiniteQueryConfig<any>,
+): UseLiveInfiniteQueryReturn<any> {
+  const pageShape = readLiveQueryWindowPageShape(config)
+  const claimsRef = useRef<LiveQuerySourceIdClaims | null>(null)
+  const bindingRef = useRef<LiveQueryWindowBinding | null>(null)
+
+  // A query input's identity is a hash, so a structurally equal query keeps
+  // its loaded pages and a changed one compiles again.
+  let preparedValue: unknown
+  let identity: string | undefined
+  if (typeof queryFnOrCollection === `function`) {
+    const queryKey = getLiveQueryKey(config)
+    if (queryKey) {
+      identity = getLiveQueryHash(undefined, queryKey)
+    } else {
+      preparedValue = prepareLiveQueryValue(queryFnOrCollection, undefined)
+      identity = identifyLiveQuery(
+        preparedValue,
+        {
+          claims: (claimsRef.current ??= createLiveQuerySourceIdClaims()),
+          client: undefined,
+          bindingName: `useLiveInfiniteQuery`,
+        },
+        getLiveQueryHash,
+      )
+    }
+  }
+
+  const binding = (bindingRef.current = bindLiveQueryWindow(
+    bindingRef.current,
+    {
+      ...pageShape,
+      // Compile what this render prepared, so the callback runs once.
+      input:
+        preparedValue === undefined ? queryFnOrCollection : () => preparedValue,
+      dependencies: identity === undefined ? undefined : [identity],
+      recompile: `identity`,
+    },
+  ))
+
+  const { controller } = binding
+  const snapshot = controller.getSnapshot()
+  const [, setRevision] = useState(0)
+
+  useLayoutEffect(() => {
+    const rerender = () => setRevision((revision) => revision + 1)
+    controller.subscribe(rerender)
+    // The query can publish between this render and its subscription.
+    if (controller.getSnapshot() !== snapshot) rerender()
+    if (binding.warning) console.warn(binding.warning)
+    // Each binding owns its controller, so disposal also detaches this
+    // subscription and releases its window lease.
+    return () => controller.dispose()
+  }, [controller])
+
+  const fetchNextPage = useCallback(
+    () => fetchNextLiveQueryWindowPage(controller),
+    [controller],
+  )
+
+  return {
+    data: snapshot.data,
+    get state() {
+      return snapshot.state
+    },
+    status: snapshot.status as CollectionStatus,
+    isLoading: snapshot.isLoading,
+    isReady: snapshot.isReady,
+    isIdle: snapshot.isIdle,
+    isLoadingError: snapshot.isLoadingError,
+    isCrashed: snapshot.isCrashed,
+    isCleanedUp: snapshot.isCleanedUp,
+    isSyncError: snapshot.isSyncError,
+    collection: snapshot.collection,
+    isEnabled: true,
+    pages: snapshot.pages,
+    pageParams: snapshot.pageParams,
+    fetchNextPage,
+    hasNextPage: snapshot.hasNextPage,
+    isFetchingNextPage: snapshot.isFetchingNextPage,
+    health: snapshot.health,
+  } as UseLiveInfiniteQueryReturn<any>
+}

package/src/useLiveQuery.ts

@@ -0,0 +1,287 @@
+import { useLayoutEffect, useRef, useState } from 'preact/hooks'
+import {
+  createLiveQueryObserver,
+  createLiveQuerySourceIdClaims,
+  getLiveQueryHash,
+  getLiveQueryKey,
+  identifyLiveQuery,
+  isCollection,
+  prepareLiveQueryValue,
+  resolveLiveQueryValue,
+} from '@tanstack/db'
+import type {
+  Collection,
+  CollectionStatus,
+  Context,
+  GetResult,
+  InferResultType,
+  InitialQueryBuilder,
+  LiveQueryCollectionConfig,
+  LiveQueryKey,
+  LiveQueryObserver,
+  LiveQuerySourceIdClaims,
+  LiveQueryStatusFlags,
+  NonSingleResult,
+  PooledLiveQueries,
+  QueryBuilder,
+  SingleResult,
+} from '@tanstack/db'
+
+// A live query this hook creates from a callback or config retires 1 ms after
+// its last subscriber leaves. A supplied Collection, or a config with an
+// explicit `gcTime`, keeps the caller's retention policy.
+const DEFAULT_GC_TIME_MS = 1
+
+export type UseLiveQueryStatus = CollectionStatus | `disabled`
+
+type ConfiguredQueryBuilder<TContext extends Context> = Extract<
+  LiveQueryCollectionConfig<TContext>[`query`],
+  QueryBuilder<TContext>
+>
+
+type UseLiveQueryConfigOptions<TContext extends Context> = Omit<
+  LiveQueryCollectionConfig<TContext>,
+  `query`
+> & {
+  /**
+   * Explicit identity for a query whose IR cannot derive one, such as a query
+   * with functional variants. Structured queries should omit it.
+   */
+  queryKey?: LiveQueryKey
+  /**
+   * Pass `pooledLiveQueries` to share one partition among equality-filtered
+   * queries of one shape.
+   */
+  pool?: PooledLiveQueries
+}
+
+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)
+  }
+
+/** The result of a live query that is always enabled. */
+export interface UseLiveQueryResult<
+  TResult extends object,
+  TKey extends string | number,
+  TData,
+  TCollection,
+> extends LiveQueryStatusFlags {
+  state: ReadonlyMap<TKey, TResult>
+  data: TData
+  collection: TCollection
+  status: CollectionStatus
+  isEnabled: true
+}
+
+/** The result of a live query whose callback can disable it. */
+export interface UseConditionalLiveQueryResult<
+  TResult extends object,
+  TKey extends string | number,
+  TData,
+  TCollection,
+> extends LiveQueryStatusFlags {
+  state: ReadonlyMap<TKey, TResult> | undefined
+  data: TData | undefined
+  collection: TCollection | undefined
+  status: UseLiveQueryStatus
+  isEnabled: boolean
+}
+
+type QueryResult<TContext extends Context> = UseLiveQueryResult<
+  GetResult<TContext>,
+  string | number,
+  InferResultType<TContext>,
+  Collection<GetResult<TContext>, string | number, {}>
+>
+
+type ConditionalQueryResult<TContext extends Context> =
+  UseConditionalLiveQueryResult<
+    GetResult<TContext>,
+    string | number,
+    InferResultType<TContext>,
+    Collection<GetResult<TContext>, string | number, {}>
+  >
+
+/**
+ * Subscribe a Preact component to a live query.
+ *
+ * The hook derives the query's identity from its structured IR on each render,
+ * so values captured by the callback recompile the query when they change. A
+ * query whose IR cannot be hashed, such as one using `fn.where`, throws
+ * `UnhashableQueryIRError` unless its config supplies `queryKey`. While the
+ * hook is mounted, each Collection ID its queries read must keep naming one
+ * source object, or it throws `SourceCollectionIdReuseError`.
+ * Return `undefined` or `null` from the callback to disable the query.
+ *
+ * @example
+ * const { data, isLoading } = useLiveQuery((q) =>
+ *   q
+ *     .from({ todos: todosCollection })
+ *     .where(({ todos }) => eq(todos.completed, false)),
+ * )
+ *
+ * @example
+ * // Disable the query until its input exists
+ * const { data, isEnabled } = useLiveQuery((q) =>
+ *   userId
+ *     ? q
+ *         .from({ todos: todosCollection })
+ *         .where(({ todos }) => eq(todos.userId, userId))
+ *     : undefined,
+ * )
+ */
+export function useLiveQuery<TContext extends Context>(
+  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
+): QueryResult<TContext>
+
+export function useLiveQuery<TContext extends Context>(
+  queryFn: (
+    q: InitialQueryBuilder,
+  ) => QueryBuilder<TContext> | undefined | null,
+): ConditionalQueryResult<TContext>
+
+export function useLiveQuery<TContext extends Context>(
+  queryFn: (
+    q: InitialQueryBuilder,
+  ) => LiveQueryCollectionConfig<TContext> | undefined | null,
+): ConditionalQueryResult<TContext>
+
+export function useLiveQuery<
+  TResult extends object,
+  TKey extends string | number,
+  TUtils extends Record<string, any>,
+>(
+  queryFn: (
+    q: InitialQueryBuilder,
+  ) => Collection<TResult, TKey, TUtils> | undefined | null,
+): UseConditionalLiveQueryResult<
+  TResult,
+  TKey,
+  Array<TResult>,
+  Collection<TResult, TKey, TUtils>
+>
+
+/**
+ * Subscribe to a live query described by a config object.
+ *
+ * @example
+ * const { data } = useLiveQuery({
+ *   query: (q) => q.from({ todos: todosCollection }),
+ *   gcTime: 60_000,
+ * })
+ */
+export function useLiveQuery<TContext extends Context>(
+  config: UseLiveQueryConfig<TContext>,
+): QueryResult<TContext>
+
+export function useLiveQuery<TContext extends Context>(
+  config: ConditionalUseLiveQueryConfig<TContext>,
+): ConditionalQueryResult<TContext>
+
+/**
+ * Subscribe to an existing live-query Collection. The hook starts its sync and
+ * leaves its retention policy to the caller.
+ *
+ * @example
+ * const activeTodos = createLiveQueryCollection((q) =>
+ *   q.from({ todos: todosCollection }).where(({ todos }) => todos.active),
+ * )
+ * const { data, collection } = useLiveQuery(activeTodos)
+ */
+export function useLiveQuery<
+  TResult extends object,
+  TKey extends string | number,
+  TUtils extends Record<string, any>,
+>(
+  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,
+): UseLiveQueryResult<
+  TResult,
+  TKey,
+  Array<TResult>,
+  Collection<TResult, TKey, TUtils>
+>
+
+export function useLiveQuery<
+  TResult extends object,
+  TKey extends string | number,
+  TUtils extends Record<string, any>,
+>(
+  liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult,
+): UseLiveQueryResult<
+  TResult,
+  TKey,
+  TResult | undefined,
+  Collection<TResult, TKey, TUtils> & SingleResult
+>
+
+export function useLiveQuery(
+  input: unknown,
+): UseConditionalLiveQueryResult<
+  object,
+  string | number,
+  unknown,
+  Collection<object, string | number, any>
+> {
+  const claimsRef = useRef<LiveQuerySourceIdClaims | null>(null)
+  const preparedValue = prepareLiveQueryValue(input, undefined)
+  const queryKey = getLiveQueryKey(input)
+  // A supplied Collection is not compiled, so its object is its identity.
+  const identity = isCollection(input)
+    ? input
+    : queryKey
+      ? getLiveQueryHash(preparedValue, queryKey)
+      : identifyLiveQuery(
+          preparedValue,
+          {
+            claims: (claimsRef.current ??= createLiveQuerySourceIdClaims()),
+            client: undefined,
+            bindingName: `useLiveQuery`,
+          },
+          getLiveQueryHash,
+        )
+
+  const bindingRef = useRef<LiveQueryBinding | null>(null)
+  let binding = bindingRef.current
+  if (binding?.identity !== identity) {
+    binding = bindingRef.current = {
+      identity,
+      // Wholesale mode publishes nothing during subscribe; the hook re-reads
+      // the observer's snapshot on each notification.
+      observer: createLiveQueryObserver(
+        resolveLiveQueryValue(preparedValue, { gcTime: DEFAULT_GC_TIME_MS }),
+        { mode: `wholesale` },
+      ),
+    }
+  }
+
+  const { observer } = binding
+  const snapshot = observer.getSnapshot()
+  const [, setRevision] = useState(0)
+
+  useLayoutEffect(() => {
+    const rerender = () => setRevision((revision) => revision + 1)
+    observer.subscribe(rerender)
+    // The query can publish between this render and its subscription.
+    if (observer.getSnapshot() !== snapshot) rerender()
+    // Each binding owns its observer, so disposal also detaches this
+    // subscription and releases the live-query Collection.
+    return () => observer.dispose()
+  }, [observer])
+
+  return snapshot
+}
+
+/** The live query one hook instance reads until its identity changes. */
+interface LiveQueryBinding {
+  identity: unknown
+  observer: LiveQueryObserver<object, string | number>
+}