@powersync-bridge/react 0.0.1-alpha.0 → 0.0.1-alpha.1

package/README.md

@@ -1,24 +1,87 @@
 # powersync-bridge
 
-A client-side bridge between a [PowerSync](https://powersync.com) local SQLite database and a
-conventional HTTP API, for web and React Native.
-
-The right data source, local synced SQLite or the live API, is a runtime, per-screen decision.
-This package makes it automatic:
-
-- **`useRacedList`** — paint the first screen from whichever source is *correct* first. A
-  first-ever visit has an empty local table; a warm re-mount has yesterday's checkpoint. The
-  bridge fetches one API snapshot, merges by id with pending-write and freshness awareness,
-  and hands the list to local sync as soon as local is fresh in this session.
-- **`useInfiniteList`** — scroll past the synced window. Older data arrives either through
-  PowerSync sync streams (one equality partition at a time, bounded) or through your API's
-  pages. Row removals are classified as filtered-out, delete, or eviction, so the list never
-  resurrects deletes and never loses content mid-scroll.
-- **`useOnDemandStream`** — pull one record into the offline database by id.
-
-Status: **v0 alpha**. Core engine and invariant tests are complete (35 tests on a virtual-time
-fake driver); the PowerSync driver is written against `@powersync/common` 2.3 and needs a running
-integration before GA. Sizes (minified + gzip): core 8.2 kB, React 0.6 kB, driver 1.8 kB.
+Local SQLite and your HTTP API, behind one list interface for React and React Native.
+
+The application defines its SQL, API calls, filters and permissions. The bridge owns racing,
+pagination, pending-write protection, reconciliation, subscriptions, connectivity, retries and
+bounded memory. API results stay in memory; only PowerSync makes records durable offline.
+
+## Start with `useInfiniteQuery`
+
+```tsx
+import { useInfiniteQuery } from '@powersync-bridge/react';
+
+type Transaction = { id: string; date: string; amount: string };
+
+const transactions = useInfiniteQuery<Transaction>({
+  queryKey: ['transactions', organizationId, filters, permissionVersion],
+  orderBy: ['date', 'id'],
+  // Descending order, 25 rows per page and a 500-row memory window are defaults.
+  query: ({ cursor, limit }) =>
+    db.select().from(transaction)
+      .where(and(
+        eq(transaction.organizationId, organizationId),
+        cursor ? or(
+          lt(transaction.date, cursor.date),
+          and(eq(transaction.date, cursor.date), lt(transaction.id, cursor.id)),
+        ) : undefined,
+      ))
+      .orderBy(desc(transaction.date), desc(transaction.id))
+      .limit(limit),
+  fetchPage: async ({ cursor, limit, signal }) =>
+    api.transactions.list({ organizationId, filters,
+      cursor: cursor ? { date: cursor.date, id: cursor.id } : undefined,
+      limit, signal,
+    }),
+});
+
+// FlatList / virtualized list:
+// data={transactions.data}
+// onEndReached={() => transactions.hasNextPage && transactions.fetchNextPage()}
+// refreshing={transactions.isFetching}
+// onRefresh={transactions.refresh}
+```
+
+The local and API rows must have the same decoded shape and a strict, stable sort order.
+Honor the requested `limit`: the bridge requests one extra row to detect another page.
+`cursor` is the previous API row, never a cursor guessed from a sparse local feed. Local reads
+can fill a requested page while its API request is still pending. Every requested page races;
+API requests follow a single cursor chain, including when scrolling outpaces the network.
+
+`data` contains ordinary rows. `items` additionally exposes each row's source and local presence
+for edit guards. `error` reports an error preventing the requested range from being filled;
+`errors` retains independent local/API diagnostics even when usable rows are displayed.
+`retry()` retries the pending range. `refresh()` / `refetch()` starts again at the current window.
+At `maxRows`, `needsOlderWindow` becomes true when more history may exist; `continueOlder()`
+opens the next bounded window. Changing `queryKey` discards the previous scope.
+
+Include every organization, filter and permission predicate in `queryKey`; the bridge does not
+invent business authorization. It infers the business table for single-table queries. Supply `table`
+for joins or ambiguous queries, or `getRowIdentity(row) => ({ table, id })` for a heterogeneous feed whose display
+IDs differ from the underlying business IDs.
+
+`mapQuery(builder, decode)` preserves ORM metadata when decoding rows. `rawQuery(db,
+{ text, params }, tables, decode)` supports parameterized SQL feeds with explicit source tables.
+Both come from `@powersync-bridge/drizzle`; no application adapter or custom watch is needed.
+
+## Connectivity
+
+Browser connectivity is observed automatically. In React Native, pass the existing network
+hook's boolean once at the provider:
+
+```tsx
+<BridgeProvider bridge={bridge} online={online}>
+  <App />
+</BridgeProvider>
+```
+
+`online` is optional and may be `undefined`. The bridge also handles HTTP failures when a
+connectivity hint incorrectly says online. A disconnected sync socket does not by itself mean
+the API is unavailable. Downloaded rows continue to paginate offline; additional archive rows
+require a connection. Reconnection resumes the pending API range without clearing visible rows.
+
+The lower-level `useRacedList`, `useInfiniteList`, `useOnDemandStream` and `useAutoSync` APIs
+remain available for specialized workflows. Ordinary paginated lists need only `useInfiniteQuery`.
 
 ## What your backend must change
 
@@ -39,7 +102,7 @@ alignment, not a change: your list endpoint sorts rows the same way your local q
 pnpm add powersync-bridge @powersync-bridge/react @powersync-bridge/drizzle @powersync-bridge/powersync
 ```
 
-Peers: `@powersync/common ^2.3`, `@powersync/web ^2.4` or `@powersync/react-native ^2.3`,
+Peers: `@powersync/common ^1.57.3 || ^2.3`, with your compatible web or native SDK,
 `@powersync/drizzle-driver`, `drizzle-orm`, `react ^18.2 || ^19`. TanStack Query is optional.
 
 ## Setup (once, in a plain module)

package/dist/index.cjs

@@ -24,15 +24,39 @@ __export(src_exports, {
   useAutoSync: () => useAutoSync,
   useBridge: () => useBridge,
   useInfiniteList: () => useInfiniteList,
+  useInfiniteQuery: () => useInfiniteQuery,
   useOnDemandStream: () => useOnDemandStream,
   useRacedList: () => useRacedList
 });
 module.exports = __toCommonJS(src_exports);
 var import_react = require("react");
+var import_powersync_bridge = require("powersync-bridge");
 var BridgeContext = (0, import_react.createContext)(null);
-function BridgeProvider({ bridge, children }) {
+function BridgeProvider({ bridge, children, online }) {
+  (0, import_react.useEffect)(() => {
+    bridge.setOnline(online);
+  }, [bridge, online]);
   return (0, import_react.createElement)(BridgeContext.Provider, { value: bridge }, children);
 }
+var useInfiniteQuery = (options) => {
+  const bridge = useBridge();
+  const epoch = useEpoch(bridge);
+  const key = (0, import_powersync_bridge.infiniteQueryKey)(options);
+  const controller = (0, import_react.useMemo)(() => bridge.query(options), [bridge, epoch, key]);
+  (0, import_react.useEffect)(() => {
+    controller.retain();
+    return () => controller.release();
+  }, [controller]);
+  const result = (0, import_react.useSyncExternalStore)(controller.store.subscribe, controller.store.getSnapshot, controller.store.getSnapshot);
+  return (0, import_react.useMemo)(() => ({
+    ...result,
+    fetchNextPage: controller.fetchNextPage,
+    retry: controller.retry,
+    refresh: controller.refresh,
+    refetch: controller.refresh,
+    continueOlder: controller.continueOlder
+  }), [result, controller]);
+};
 function useBridge() {
   const b = (0, import_react.useContext)(BridgeContext);
   if (!b) throw new Error("powersync-bridge: no <BridgeProvider> above this component");
@@ -86,6 +110,7 @@ function useAutoSync(config, ids) {
   useAutoSync,
   useBridge,
   useInfiniteList,
+  useInfiniteQuery,
   useOnDemandStream,
   useRacedList
 });

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore, type ReactNode } from 'react';\nimport type {\n  Bridge,\n  FlaggerConfig,\n  FlagResult,\n  InfiniteListDefinition,\n  InfiniteListResult,\n  OnDemandOptions,\n  OnDemandResult,\n  OrderKey,\n  Params,\n  RacedListDefinition,\n  RacedListResult,\n  Store,\n} from 'powersync-bridge';\n\n// NOTE (R11, static assertion): this package never imports `useQuery` from TanStack.\n// It renders from the engine store via useSyncExternalStore only.\n\nconst BridgeContext = createContext<Bridge | null>(null);\n\nexport interface BridgeProviderProps {\n  bridge: Bridge;\n  children?: ReactNode;\n}\n\n/** Mount once at app root. Crud-delta observation started at createBridge(), not here (F6-001). */\nexport function BridgeProvider({ bridge, children }: BridgeProviderProps) {\n  return createElement(BridgeContext.Provider, { value: bridge }, children);\n}\n\nexport function useBridge(): Bridge {\n  const b = useContext(BridgeContext);\n  if (!b) throw new Error('powersync-bridge: no <BridgeProvider> above this component');\n  return b;\n}\n\nfunction useEpoch(bridge: Bridge): number {\n  return useSyncExternalStore(bridge.epochStore.subscribe, bridge.epochStore.getSnapshot, bridge.epochStore.getSnapshot);\n}\n\ninterface Retainable<S> {\n  readonly store: Store<S>;\n  retain(): void;\n  release(): void;\n}\n\n/**\n * Acquire a ref-counted store for the current epoch and subscribe to it. Retain/release run in\n * an effect so StrictMode's double-invoke is a no-op pair (R10); the store is shared across\n * components that ask for the same definition + scope.\n */\nfunction useRetained<S>(bridge: Bridge, key: string, acquire: () => Retainable<S>): S {\n  const epoch = useEpoch(bridge);\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  const holder = useMemo(() => acquire(), [bridge, epoch, key]);\n  useEffect(() => {\n    holder.retain();\n    return () => holder.release();\n  }, [holder]);\n  return useSyncExternalStore(holder.store.subscribe, holder.store.getSnapshot, holder.store.getSnapshot);\n}\n\nexport function useRacedList<TItem, TScope, TApi, K extends OrderKey<TItem>>(\n  def: RacedListDefinition<TItem, TScope, TApi, K>,\n  scope: TScope,\n): RacedListResult<TItem> {\n  const bridge = useBridge();\n  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;\n  return useRetained(bridge, key, () => bridge.raced(def, scope));\n}\n\nexport interface UseInfiniteListResult<TItem> extends InfiniteListResult<TItem> {\n  loadMore(): void;\n  /** Clears API backoff and loads (R16). */\n  retry(): void;\n}\n\nexport function useInfiniteList<TItem, TScope, K extends OrderKey<TItem>, TCursor, TPartition>(\n  def: InfiniteListDefinition<TItem, TScope, K, TCursor, TPartition>,\n  scope: TScope,\n): UseInfiniteListResult<TItem> {\n  const bridge = useBridge();\n  const epoch = useEpoch(bridge);\n  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  const store = useMemo(() => bridge.infinite(def, scope), [bridge, epoch, key]);\n  useEffect(() => {\n    store.retain();\n    return () => store.release();\n  }, [store]);\n  const result = useSyncExternalStore(store.store.subscribe, store.store.getSnapshot, store.store.getSnapshot);\n  return useMemo(\n    () => ({ ...result, loadMore: () => void store.loadMore(), retry: () => void store.retry() }),\n    [result, store],\n  );\n}\n\n/** The default \"pull one row into the offline DB\" primitive (§7). */\nexport function useOnDemandStream(name: string, params: Params | null, opts: OnDemandOptions = {}): OnDemandResult {\n  const bridge = useBridge();\n  const key = `${name}:${JSON.stringify(params)}:${JSON.stringify(opts)}`;\n  return useRetained(bridge, key, () => bridge.onDemand(name, params, opts));\n}\n\n/** OPTIONAL: server-side flagging (§7). Prefer useOnDemandStream. */\nexport function useAutoSync(config: FlaggerConfig, ids: readonly string[]): FlagResult {\n  const bridge = useBridge();\n  const key = `${config.stream}:${JSON.stringify([...ids].sort())}`;\n  return useRetained(bridge, key, () => bridge.autoSync(config, ids));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAmH;AAmBnH,IAAM,oBAAgB,4BAA6B,IAAI;AAQhD,SAAS,eAAe,EAAE,QAAQ,SAAS,GAAwB;AACxE,aAAO,4BAAc,cAAc,UAAU,EAAE,OAAO,OAAO,GAAG,QAAQ;AAC1E;AAEO,SAAS,YAAoB;AAClC,QAAM,QAAI,yBAAW,aAAa;AAClC,MAAI,CAAC,EAAG,OAAM,IAAI,MAAM,4DAA4D;AACpF,SAAO;AACT;AAEA,SAAS,SAAS,QAAwB;AACxC,aAAO,mCAAqB,OAAO,WAAW,WAAW,OAAO,WAAW,aAAa,OAAO,WAAW,WAAW;AACvH;AAaA,SAAS,YAAe,QAAgB,KAAa,SAAiC;AACpF,QAAM,QAAQ,SAAS,MAAM;AAE7B,QAAM,aAAS,sBAAQ,MAAM,QAAQ,GAAG,CAAC,QAAQ,OAAO,GAAG,CAAC;AAC5D,8BAAU,MAAM;AACd,WAAO,OAAO;AACd,WAAO,MAAM,OAAO,QAAQ;AAAA,EAC9B,GAAG,CAAC,MAAM,CAAC;AACX,aAAO,mCAAqB,OAAO,MAAM,WAAW,OAAO,MAAM,aAAa,OAAO,MAAM,WAAW;AACxG;AAEO,SAAS,aACd,KACA,OACwB;AACxB,QAAM,SAAS,UAAU;AACzB,QAAM,MAAM,GAAG,IAAI,EAAE,IAAI,KAAK,UAAU,SAAS,IAAI,CAAC;AACtD,SAAO,YAAY,QAAQ,KAAK,MAAM,OAAO,MAAM,KAAK,KAAK,CAAC;AAChE;AAQO,SAAS,gBACd,KACA,OAC8B;AAC9B,QAAM,SAAS,UAAU;AACzB,QAAM,QAAQ,SAAS,MAAM;AAC7B,QAAM,MAAM,GAAG,IAAI,EAAE,IAAI,KAAK,UAAU,SAAS,IAAI,CAAC;AAEtD,QAAM,YAAQ,sBAAQ,MAAM,OAAO,SAAS,KAAK,KAAK,GAAG,CAAC,QAAQ,OAAO,GAAG,CAAC;AAC7E,8BAAU,MAAM;AACd,UAAM,OAAO;AACb,WAAO,MAAM,MAAM,QAAQ;AAAA,EAC7B,GAAG,CAAC,KAAK,CAAC;AACV,QAAM,aAAS,mCAAqB,MAAM,MAAM,WAAW,MAAM,MAAM,aAAa,MAAM,MAAM,WAAW;AAC3G,aAAO;AAAA,IACL,OAAO,EAAE,GAAG,QAAQ,UAAU,MAAM,KAAK,MAAM,SAAS,GAAG,OAAO,MAAM,KAAK,MAAM,MAAM,EAAE;AAAA,IAC3F,CAAC,QAAQ,KAAK;AAAA,EAChB;AACF;AAGO,SAAS,kBAAkB,MAAc,QAAuB,OAAwB,CAAC,GAAmB;AACjH,QAAM,SAAS,UAAU;AACzB,QAAM,MAAM,GAAG,IAAI,IAAI,KAAK,UAAU,MAAM,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC;AACrE,SAAO,YAAY,QAAQ,KAAK,MAAM,OAAO,SAAS,MAAM,QAAQ,IAAI,CAAC;AAC3E;AAGO,SAAS,YAAY,QAAuB,KAAoC;AACrF,QAAM,SAAS,UAAU;AACzB,QAAM,MAAM,GAAG,OAAO,MAAM,IAAI,KAAK,UAAU,CAAC,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC;AAC/D,SAAO,YAAY,QAAQ,KAAK,MAAM,OAAO,SAAS,QAAQ,GAAG,CAAC;AACpE;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore, type ReactNode } from 'react';\nimport { infiniteQueryKey } from 'powersync-bridge';\nimport type {\n  Bridge,\n  FlaggerConfig,\n  FlagResult,\n  InfiniteListDefinition,\n  InfiniteListResult,\n  InfiniteQueryOptions,\n  InfiniteQueryResult,\n  OnDemandOptions,\n  OnDemandResult,\n  OrderKey,\n  Params,\n  RacedListDefinition,\n  RacedListResult,\n  Store,\n} from 'powersync-bridge';\n\n// NOTE (R11, static assertion): this package never imports `useQuery` from TanStack.\n// It renders from the engine store via useSyncExternalStore only.\n\nconst BridgeContext = createContext<Bridge | null>(null);\n\nexport interface BridgeProviderProps {\n  bridge: Bridge;\n  children?: ReactNode;\n  /** Native apps supply their network hook's result once, at the provider. */\n  online?: boolean | undefined;\n}\n\n/** Mount once at app root. Crud-delta observation started at createBridge(), not here (F6-001). */\nexport function BridgeProvider({ bridge, children, online }: BridgeProviderProps) {\n  useEffect(() => { bridge.setOnline(online); }, [bridge, online]);\n  return createElement(BridgeContext.Provider, { value: bridge }, children);\n}\n\nexport type UseInfiniteQueryResult<T> = InfiniteQueryResult<T> & {\n  fetchNextPage(): void;\n  retry(): void;\n  refresh(): void;\n  refetch(): void;\n  continueOlder(): void;\n};\n\n/** Define local SQL and an API page; the bridge owns all paging and reconciliation. */\nexport const useInfiniteQuery = <T extends { id: string }>(\n  options: InfiniteQueryOptions<T>,\n): UseInfiniteQueryResult<T> => {\n  const bridge = useBridge();\n  const epoch = useEpoch(bridge);\n  const key = infiniteQueryKey(options);\n  // Definitions are closures; every changing predicate belongs in queryKey.\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  const controller = useMemo(() => bridge.query(options), [bridge, epoch, key]);\n  useEffect(() => {\n    controller.retain();\n    return () => controller.release();\n  }, [controller]);\n  const result = useSyncExternalStore(controller.store.subscribe, controller.store.getSnapshot, controller.store.getSnapshot);\n  return useMemo(() => ({\n    ...result, fetchNextPage: controller.fetchNextPage, retry: controller.retry,\n    refresh: controller.refresh, refetch: controller.refresh, continueOlder: controller.continueOlder,\n  }), [result, controller]);\n};\n\nexport function useBridge(): Bridge {\n  const b = useContext(BridgeContext);\n  if (!b) throw new Error('powersync-bridge: no <BridgeProvider> above this component');\n  return b;\n}\n\nfunction useEpoch(bridge: Bridge): number {\n  return useSyncExternalStore(bridge.epochStore.subscribe, bridge.epochStore.getSnapshot, bridge.epochStore.getSnapshot);\n}\n\ninterface Retainable<S> {\n  readonly store: Store<S>;\n  retain(): void;\n  release(): void;\n}\n\n/**\n * Acquire a ref-counted store for the current epoch and subscribe to it. Retain/release run in\n * an effect so StrictMode's double-invoke is a no-op pair (R10); the store is shared across\n * components that ask for the same definition + scope.\n */\nfunction useRetained<S>(bridge: Bridge, key: string, acquire: () => Retainable<S>): S {\n  const epoch = useEpoch(bridge);\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  const holder = useMemo(() => acquire(), [bridge, epoch, key]);\n  useEffect(() => {\n    holder.retain();\n    return () => holder.release();\n  }, [holder]);\n  return useSyncExternalStore(holder.store.subscribe, holder.store.getSnapshot, holder.store.getSnapshot);\n}\n\nexport function useRacedList<TItem, TScope, TApi, K extends OrderKey<TItem>>(\n  def: RacedListDefinition<TItem, TScope, TApi, K>,\n  scope: TScope,\n): RacedListResult<TItem> {\n  const bridge = useBridge();\n  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;\n  return useRetained(bridge, key, () => bridge.raced(def, scope));\n}\n\nexport interface UseInfiniteListResult<TItem> extends InfiniteListResult<TItem> {\n  loadMore(): void;\n  /** Clears API backoff and loads (R16). */\n  retry(): void;\n}\n\nexport function useInfiniteList<TItem, TScope, K extends OrderKey<TItem>, TCursor, TPartition>(\n  def: InfiniteListDefinition<TItem, TScope, K, TCursor, TPartition>,\n  scope: TScope,\n): UseInfiniteListResult<TItem> {\n  const bridge = useBridge();\n  const epoch = useEpoch(bridge);\n  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  const store = useMemo(() => bridge.infinite(def, scope), [bridge, epoch, key]);\n  useEffect(() => {\n    store.retain();\n    return () => store.release();\n  }, [store]);\n  const result = useSyncExternalStore(store.store.subscribe, store.store.getSnapshot, store.store.getSnapshot);\n  return useMemo(\n    () => ({ ...result, loadMore: () => void store.loadMore(), retry: () => void store.retry() }),\n    [result, store],\n  );\n}\n\n/** The default \"pull one row into the offline DB\" primitive (§7). */\nexport function useOnDemandStream(name: string, params: Params | null, opts: OnDemandOptions = {}): OnDemandResult {\n  const bridge = useBridge();\n  const key = `${name}:${JSON.stringify(params)}:${JSON.stringify(opts)}`;\n  return useRetained(bridge, key, () => bridge.onDemand(name, params, opts));\n}\n\n/** OPTIONAL: server-side flagging (§7). Prefer useOnDemandStream. */\nexport function useAutoSync(config: FlaggerConfig, ids: readonly string[]): FlagResult {\n  const bridge = useBridge();\n  const key = `${config.stream}:${JSON.stringify([...ids].sort())}`;\n  return useRetained(bridge, key, () => bridge.autoSync(config, ids));\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -1,13 +1,26 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { Bridge, InfiniteListResult, FlaggerConfig, FlagResult, OrderKey, InfiniteListDefinition, Params, OnDemandOptions, OnDemandResult, RacedListDefinition, RacedListResult } from 'powersync-bridge';
+import { Bridge, InfiniteListResult, InfiniteQueryResult, FlaggerConfig, FlagResult, OrderKey, InfiniteListDefinition, InfiniteQueryOptions, Params, OnDemandOptions, OnDemandResult, RacedListDefinition, RacedListResult } from 'powersync-bridge';
 
 interface BridgeProviderProps {
     bridge: Bridge;
     children?: ReactNode;
+    /** Native apps supply their network hook's result once, at the provider. */
+    online?: boolean | undefined;
 }
 /** Mount once at app root. Crud-delta observation started at createBridge(), not here (F6-001). */
-declare function BridgeProvider({ bridge, children }: BridgeProviderProps): react.FunctionComponentElement<react.ProviderProps<Bridge | null>>;
+declare function BridgeProvider({ bridge, children, online }: BridgeProviderProps): react.FunctionComponentElement<react.ProviderProps<Bridge | null>>;
+type UseInfiniteQueryResult<T> = InfiniteQueryResult<T> & {
+    fetchNextPage(): void;
+    retry(): void;
+    refresh(): void;
+    refetch(): void;
+    continueOlder(): void;
+};
+/** Define local SQL and an API page; the bridge owns all paging and reconciliation. */
+declare const useInfiniteQuery: <T extends {
+    id: string;
+}>(options: InfiniteQueryOptions<T>) => UseInfiniteQueryResult<T>;
 declare function useBridge(): Bridge;
 declare function useRacedList<TItem, TScope, TApi, K extends OrderKey<TItem>>(def: RacedListDefinition<TItem, TScope, TApi, K>, scope: TScope): RacedListResult<TItem>;
 interface UseInfiniteListResult<TItem> extends InfiniteListResult<TItem> {
@@ -21,4 +34,4 @@ declare function useOnDemandStream(name: string, params: Params | null, opts?: O
 /** OPTIONAL: server-side flagging (§7). Prefer useOnDemandStream. */
 declare function useAutoSync(config: FlaggerConfig, ids: readonly string[]): FlagResult;
 
-export { BridgeProvider, type BridgeProviderProps, type UseInfiniteListResult, useAutoSync, useBridge, useInfiniteList, useOnDemandStream, useRacedList };
+export { BridgeProvider, type BridgeProviderProps, type UseInfiniteListResult, type UseInfiniteQueryResult, useAutoSync, useBridge, useInfiniteList, useInfiniteQuery, useOnDemandStream, useRacedList };

package/dist/index.d.ts

@@ -1,13 +1,26 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { Bridge, InfiniteListResult, FlaggerConfig, FlagResult, OrderKey, InfiniteListDefinition, Params, OnDemandOptions, OnDemandResult, RacedListDefinition, RacedListResult } from 'powersync-bridge';
+import { Bridge, InfiniteListResult, InfiniteQueryResult, FlaggerConfig, FlagResult, OrderKey, InfiniteListDefinition, InfiniteQueryOptions, Params, OnDemandOptions, OnDemandResult, RacedListDefinition, RacedListResult } from 'powersync-bridge';
 
 interface BridgeProviderProps {
     bridge: Bridge;
     children?: ReactNode;
+    /** Native apps supply their network hook's result once, at the provider. */
+    online?: boolean | undefined;
 }
 /** Mount once at app root. Crud-delta observation started at createBridge(), not here (F6-001). */
-declare function BridgeProvider({ bridge, children }: BridgeProviderProps): react.FunctionComponentElement<react.ProviderProps<Bridge | null>>;
+declare function BridgeProvider({ bridge, children, online }: BridgeProviderProps): react.FunctionComponentElement<react.ProviderProps<Bridge | null>>;
+type UseInfiniteQueryResult<T> = InfiniteQueryResult<T> & {
+    fetchNextPage(): void;
+    retry(): void;
+    refresh(): void;
+    refetch(): void;
+    continueOlder(): void;
+};
+/** Define local SQL and an API page; the bridge owns all paging and reconciliation. */
+declare const useInfiniteQuery: <T extends {
+    id: string;
+}>(options: InfiniteQueryOptions<T>) => UseInfiniteQueryResult<T>;
 declare function useBridge(): Bridge;
 declare function useRacedList<TItem, TScope, TApi, K extends OrderKey<TItem>>(def: RacedListDefinition<TItem, TScope, TApi, K>, scope: TScope): RacedListResult<TItem>;
 interface UseInfiniteListResult<TItem> extends InfiniteListResult<TItem> {
@@ -21,4 +34,4 @@ declare function useOnDemandStream(name: string, params: Params | null, opts?: O
 /** OPTIONAL: server-side flagging (§7). Prefer useOnDemandStream. */
 declare function useAutoSync(config: FlaggerConfig, ids: readonly string[]): FlagResult;
 
-export { BridgeProvider, type BridgeProviderProps, type UseInfiniteListResult, useAutoSync, useBridge, useInfiniteList, useOnDemandStream, useRacedList };
+export { BridgeProvider, type BridgeProviderProps, type UseInfiniteListResult, type UseInfiniteQueryResult, useAutoSync, useBridge, useInfiniteList, useInfiniteQuery, useOnDemandStream, useRacedList };

package/dist/index.js

@@ -1,9 +1,32 @@
 // src/index.ts
 import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
+import { infiniteQueryKey } from "powersync-bridge";
 var BridgeContext = createContext(null);
-function BridgeProvider({ bridge, children }) {
+function BridgeProvider({ bridge, children, online }) {
+  useEffect(() => {
+    bridge.setOnline(online);
+  }, [bridge, online]);
   return createElement(BridgeContext.Provider, { value: bridge }, children);
 }
+var useInfiniteQuery = (options) => {
+  const bridge = useBridge();
+  const epoch = useEpoch(bridge);
+  const key = infiniteQueryKey(options);
+  const controller = useMemo(() => bridge.query(options), [bridge, epoch, key]);
+  useEffect(() => {
+    controller.retain();
+    return () => controller.release();
+  }, [controller]);
+  const result = useSyncExternalStore(controller.store.subscribe, controller.store.getSnapshot, controller.store.getSnapshot);
+  return useMemo(() => ({
+    ...result,
+    fetchNextPage: controller.fetchNextPage,
+    retry: controller.retry,
+    refresh: controller.refresh,
+    refetch: controller.refresh,
+    continueOlder: controller.continueOlder
+  }), [result, controller]);
+};
 function useBridge() {
   const b = useContext(BridgeContext);
   if (!b) throw new Error("powersync-bridge: no <BridgeProvider> above this component");
@@ -56,6 +79,7 @@ export {
   useAutoSync,
   useBridge,
   useInfiniteList,
+  useInfiniteQuery,
   useOnDemandStream,
   useRacedList
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore, type ReactNode } from 'react';\nimport type {\n  Bridge,\n  FlaggerConfig,\n  FlagResult,\n  InfiniteListDefinition,\n  InfiniteListResult,\n  OnDemandOptions,\n  OnDemandResult,\n  OrderKey,\n  Params,\n  RacedListDefinition,\n  RacedListResult,\n  Store,\n} from 'powersync-bridge';\n\n// NOTE (R11, static assertion): this package never imports `useQuery` from TanStack.\n// It renders from the engine store via useSyncExternalStore only.\n\nconst BridgeContext = createContext<Bridge | null>(null);\n\nexport interface BridgeProviderProps {\n  bridge: Bridge;\n  children?: ReactNode;\n}\n\n/** Mount once at app root. Crud-delta observation started at createBridge(), not here (F6-001). */\nexport function BridgeProvider({ bridge, children }: BridgeProviderProps) {\n  return createElement(BridgeContext.Provider, { value: bridge }, children);\n}\n\nexport function useBridge(): Bridge {\n  const b = useContext(BridgeContext);\n  if (!b) throw new Error('powersync-bridge: no <BridgeProvider> above this component');\n  return b;\n}\n\nfunction useEpoch(bridge: Bridge): number {\n  return useSyncExternalStore(bridge.epochStore.subscribe, bridge.epochStore.getSnapshot, bridge.epochStore.getSnapshot);\n}\n\ninterface Retainable<S> {\n  readonly store: Store<S>;\n  retain(): void;\n  release(): void;\n}\n\n/**\n * Acquire a ref-counted store for the current epoch and subscribe to it. Retain/release run in\n * an effect so StrictMode's double-invoke is a no-op pair (R10); the store is shared across\n * components that ask for the same definition + scope.\n */\nfunction useRetained<S>(bridge: Bridge, key: string, acquire: () => Retainable<S>): S {\n  const epoch = useEpoch(bridge);\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  const holder = useMemo(() => acquire(), [bridge, epoch, key]);\n  useEffect(() => {\n    holder.retain();\n    return () => holder.release();\n  }, [holder]);\n  return useSyncExternalStore(holder.store.subscribe, holder.store.getSnapshot, holder.store.getSnapshot);\n}\n\nexport function useRacedList<TItem, TScope, TApi, K extends OrderKey<TItem>>(\n  def: RacedListDefinition<TItem, TScope, TApi, K>,\n  scope: TScope,\n): RacedListResult<TItem> {\n  const bridge = useBridge();\n  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;\n  return useRetained(bridge, key, () => bridge.raced(def, scope));\n}\n\nexport interface UseInfiniteListResult<TItem> extends InfiniteListResult<TItem> {\n  loadMore(): void;\n  /** Clears API backoff and loads (R16). */\n  retry(): void;\n}\n\nexport function useInfiniteList<TItem, TScope, K extends OrderKey<TItem>, TCursor, TPartition>(\n  def: InfiniteListDefinition<TItem, TScope, K, TCursor, TPartition>,\n  scope: TScope,\n): UseInfiniteListResult<TItem> {\n  const bridge = useBridge();\n  const epoch = useEpoch(bridge);\n  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  const store = useMemo(() => bridge.infinite(def, scope), [bridge, epoch, key]);\n  useEffect(() => {\n    store.retain();\n    return () => store.release();\n  }, [store]);\n  const result = useSyncExternalStore(store.store.subscribe, store.store.getSnapshot, store.store.getSnapshot);\n  return useMemo(\n    () => ({ ...result, loadMore: () => void store.loadMore(), retry: () => void store.retry() }),\n    [result, store],\n  );\n}\n\n/** The default \"pull one row into the offline DB\" primitive (§7). */\nexport function useOnDemandStream(name: string, params: Params | null, opts: OnDemandOptions = {}): OnDemandResult {\n  const bridge = useBridge();\n  const key = `${name}:${JSON.stringify(params)}:${JSON.stringify(opts)}`;\n  return useRetained(bridge, key, () => bridge.onDemand(name, params, opts));\n}\n\n/** OPTIONAL: server-side flagging (§7). Prefer useOnDemandStream. */\nexport function useAutoSync(config: FlaggerConfig, ids: readonly string[]): FlagResult {\n  const bridge = useBridge();\n  const key = `${config.stream}:${JSON.stringify([...ids].sort())}`;\n  return useRetained(bridge, key, () => bridge.autoSync(config, ids));\n}\n"],"mappings":";AAAA,SAAS,eAAe,eAAe,YAAY,WAAW,SAAS,4BAA4C;AAmBnH,IAAM,gBAAgB,cAA6B,IAAI;AAQhD,SAAS,eAAe,EAAE,QAAQ,SAAS,GAAwB;AACxE,SAAO,cAAc,cAAc,UAAU,EAAE,OAAO,OAAO,GAAG,QAAQ;AAC1E;AAEO,SAAS,YAAoB;AAClC,QAAM,IAAI,WAAW,aAAa;AAClC,MAAI,CAAC,EAAG,OAAM,IAAI,MAAM,4DAA4D;AACpF,SAAO;AACT;AAEA,SAAS,SAAS,QAAwB;AACxC,SAAO,qBAAqB,OAAO,WAAW,WAAW,OAAO,WAAW,aAAa,OAAO,WAAW,WAAW;AACvH;AAaA,SAAS,YAAe,QAAgB,KAAa,SAAiC;AACpF,QAAM,QAAQ,SAAS,MAAM;AAE7B,QAAM,SAAS,QAAQ,MAAM,QAAQ,GAAG,CAAC,QAAQ,OAAO,GAAG,CAAC;AAC5D,YAAU,MAAM;AACd,WAAO,OAAO;AACd,WAAO,MAAM,OAAO,QAAQ;AAAA,EAC9B,GAAG,CAAC,MAAM,CAAC;AACX,SAAO,qBAAqB,OAAO,MAAM,WAAW,OAAO,MAAM,aAAa,OAAO,MAAM,WAAW;AACxG;AAEO,SAAS,aACd,KACA,OACwB;AACxB,QAAM,SAAS,UAAU;AACzB,QAAM,MAAM,GAAG,IAAI,EAAE,IAAI,KAAK,UAAU,SAAS,IAAI,CAAC;AACtD,SAAO,YAAY,QAAQ,KAAK,MAAM,OAAO,MAAM,KAAK,KAAK,CAAC;AAChE;AAQO,SAAS,gBACd,KACA,OAC8B;AAC9B,QAAM,SAAS,UAAU;AACzB,QAAM,QAAQ,SAAS,MAAM;AAC7B,QAAM,MAAM,GAAG,IAAI,EAAE,IAAI,KAAK,UAAU,SAAS,IAAI,CAAC;AAEtD,QAAM,QAAQ,QAAQ,MAAM,OAAO,SAAS,KAAK,KAAK,GAAG,CAAC,QAAQ,OAAO,GAAG,CAAC;AAC7E,YAAU,MAAM;AACd,UAAM,OAAO;AACb,WAAO,MAAM,MAAM,QAAQ;AAAA,EAC7B,GAAG,CAAC,KAAK,CAAC;AACV,QAAM,SAAS,qBAAqB,MAAM,MAAM,WAAW,MAAM,MAAM,aAAa,MAAM,MAAM,WAAW;AAC3G,SAAO;AAAA,IACL,OAAO,EAAE,GAAG,QAAQ,UAAU,MAAM,KAAK,MAAM,SAAS,GAAG,OAAO,MAAM,KAAK,MAAM,MAAM,EAAE;AAAA,IAC3F,CAAC,QAAQ,KAAK;AAAA,EAChB;AACF;AAGO,SAAS,kBAAkB,MAAc,QAAuB,OAAwB,CAAC,GAAmB;AACjH,QAAM,SAAS,UAAU;AACzB,QAAM,MAAM,GAAG,IAAI,IAAI,KAAK,UAAU,MAAM,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC;AACrE,SAAO,YAAY,QAAQ,KAAK,MAAM,OAAO,SAAS,MAAM,QAAQ,IAAI,CAAC;AAC3E;AAGO,SAAS,YAAY,QAAuB,KAAoC;AACrF,QAAM,SAAS,UAAU;AACzB,QAAM,MAAM,GAAG,OAAO,MAAM,IAAI,KAAK,UAAU,CAAC,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC;AAC/D,SAAO,YAAY,QAAQ,KAAK,MAAM,OAAO,SAAS,QAAQ,GAAG,CAAC;AACpE;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore, type ReactNode } from 'react';\nimport { infiniteQueryKey } from 'powersync-bridge';\nimport type {\n  Bridge,\n  FlaggerConfig,\n  FlagResult,\n  InfiniteListDefinition,\n  InfiniteListResult,\n  InfiniteQueryOptions,\n  InfiniteQueryResult,\n  OnDemandOptions,\n  OnDemandResult,\n  OrderKey,\n  Params,\n  RacedListDefinition,\n  RacedListResult,\n  Store,\n} from 'powersync-bridge';\n\n// NOTE (R11, static assertion): this package never imports `useQuery` from TanStack.\n// It renders from the engine store via useSyncExternalStore only.\n\nconst BridgeContext = createContext<Bridge | null>(null);\n\nexport interface BridgeProviderProps {\n  bridge: Bridge;\n  children?: ReactNode;\n  /** Native apps supply their network hook's result once, at the provider. */\n  online?: boolean | undefined;\n}\n\n/** Mount once at app root. Crud-delta observation started at createBridge(), not here (F6-001). */\nexport function BridgeProvider({ bridge, children, online }: BridgeProviderProps) {\n  useEffect(() => { bridge.setOnline(online); }, [bridge, online]);\n  return createElement(BridgeContext.Provider, { value: bridge }, children);\n}\n\nexport type UseInfiniteQueryResult<T> = InfiniteQueryResult<T> & {\n  fetchNextPage(): void;\n  retry(): void;\n  refresh(): void;\n  refetch(): void;\n  continueOlder(): void;\n};\n\n/** Define local SQL and an API page; the bridge owns all paging and reconciliation. */\nexport const useInfiniteQuery = <T extends { id: string }>(\n  options: InfiniteQueryOptions<T>,\n): UseInfiniteQueryResult<T> => {\n  const bridge = useBridge();\n  const epoch = useEpoch(bridge);\n  const key = infiniteQueryKey(options);\n  // Definitions are closures; every changing predicate belongs in queryKey.\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  const controller = useMemo(() => bridge.query(options), [bridge, epoch, key]);\n  useEffect(() => {\n    controller.retain();\n    return () => controller.release();\n  }, [controller]);\n  const result = useSyncExternalStore(controller.store.subscribe, controller.store.getSnapshot, controller.store.getSnapshot);\n  return useMemo(() => ({\n    ...result, fetchNextPage: controller.fetchNextPage, retry: controller.retry,\n    refresh: controller.refresh, refetch: controller.refresh, continueOlder: controller.continueOlder,\n  }), [result, controller]);\n};\n\nexport function useBridge(): Bridge {\n  const b = useContext(BridgeContext);\n  if (!b) throw new Error('powersync-bridge: no <BridgeProvider> above this component');\n  return b;\n}\n\nfunction useEpoch(bridge: Bridge): number {\n  return useSyncExternalStore(bridge.epochStore.subscribe, bridge.epochStore.getSnapshot, bridge.epochStore.getSnapshot);\n}\n\ninterface Retainable<S> {\n  readonly store: Store<S>;\n  retain(): void;\n  release(): void;\n}\n\n/**\n * Acquire a ref-counted store for the current epoch and subscribe to it. Retain/release run in\n * an effect so StrictMode's double-invoke is a no-op pair (R10); the store is shared across\n * components that ask for the same definition + scope.\n */\nfunction useRetained<S>(bridge: Bridge, key: string, acquire: () => Retainable<S>): S {\n  const epoch = useEpoch(bridge);\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  const holder = useMemo(() => acquire(), [bridge, epoch, key]);\n  useEffect(() => {\n    holder.retain();\n    return () => holder.release();\n  }, [holder]);\n  return useSyncExternalStore(holder.store.subscribe, holder.store.getSnapshot, holder.store.getSnapshot);\n}\n\nexport function useRacedList<TItem, TScope, TApi, K extends OrderKey<TItem>>(\n  def: RacedListDefinition<TItem, TScope, TApi, K>,\n  scope: TScope,\n): RacedListResult<TItem> {\n  const bridge = useBridge();\n  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;\n  return useRetained(bridge, key, () => bridge.raced(def, scope));\n}\n\nexport interface UseInfiniteListResult<TItem> extends InfiniteListResult<TItem> {\n  loadMore(): void;\n  /** Clears API backoff and loads (R16). */\n  retry(): void;\n}\n\nexport function useInfiniteList<TItem, TScope, K extends OrderKey<TItem>, TCursor, TPartition>(\n  def: InfiniteListDefinition<TItem, TScope, K, TCursor, TPartition>,\n  scope: TScope,\n): UseInfiniteListResult<TItem> {\n  const bridge = useBridge();\n  const epoch = useEpoch(bridge);\n  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  const store = useMemo(() => bridge.infinite(def, scope), [bridge, epoch, key]);\n  useEffect(() => {\n    store.retain();\n    return () => store.release();\n  }, [store]);\n  const result = useSyncExternalStore(store.store.subscribe, store.store.getSnapshot, store.store.getSnapshot);\n  return useMemo(\n    () => ({ ...result, loadMore: () => void store.loadMore(), retry: () => void store.retry() }),\n    [result, store],\n  );\n}\n\n/** The default \"pull one row into the offline DB\" primitive (§7). */\nexport function useOnDemandStream(name: string, params: Params | null, opts: OnDemandOptions = {}): OnDemandResult {\n  const bridge = useBridge();\n  const key = `${name}:${JSON.stringify(params)}:${JSON.stringify(opts)}`;\n  return useRetained(bridge, key, () => bridge.onDemand(name, params, opts));\n}\n\n/** OPTIONAL: server-side flagging (§7). Prefer useOnDemandStream. */\nexport function useAutoSync(config: FlaggerConfig, ids: readonly string[]): FlagResult {\n  const bridge = useBridge();\n  const key = `${config.stream}:${JSON.stringify([...ids].sort())}`;\n  return useRetained(bridge, key, () => bridge.autoSync(config, ids));\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync-bridge/react",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.1",
   "description": "React bindings for powersync-bridge: BridgeProvider, useRacedList, useInfiniteList, useOnDemandStream, useAutoSync (useSyncExternalStore-based).",
   "license": "MIT",
   "type": "module",
@@ -41,14 +41,14 @@
   ],
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",
-    "powersync-bridge": "0.0.1-alpha.0"
+    "powersync-bridge": "0.0.1-alpha.1"
   },
   "devDependencies": {
     "@types/react": "^19.1.0",
     "react": "^19.1.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.0",
-    "powersync-bridge": "0.0.1-alpha.0"
+    "powersync-bridge": "0.0.1-alpha.1"
   },
   "scripts": {
     "build": "tsup",