@powersync-bridge/react 0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 akpor-kofi
+
+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

@@ -0,0 +1,218 @@
+# 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.
+
+## What your backend must change
+
+**Nothing.** No new tables, no new columns, no change to existing sync streams. The one rule is an
+alignment, not a change: your list endpoint sorts rows the same way your local query does, with
+`id` as the last tiebreaker.
+
+| What you want | Streams you need | Routes you need |
+|---|---|---|
+| Fast, correct first paint of any list | none beyond what you have | your existing list endpoint |
+| Scroll past the synced window, older pages from the API | none | the same endpoint accepting `cursor` (or `offset`, degraded) |
+| Scroll past the synced window, older months into the offline DB | one stream with `subscription.parameter('month')`, partition computed with `substring()` on your existing timestamp | optional `GET …/floor` |
+| Open one old record by id, offline-capable | one stream with `id = subscription.parameter('id')` | none |
+
+## Install
+
+```bash
+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`,
+`@powersync/drizzle-driver`, `drizzle-orm`, `react ^18.2 || ^19`. TanStack Query is optional.
+
+## Setup (once, in a plain module)
+
+```ts
+// bridge.ts
+import { createBridge } from 'powersync-bridge';
+import { createPowerSyncDriver } from '@powersync-bridge/powersync';
+import { drizzleAdapter } from '@powersync-bridge/drizzle';
+import { db, drizzle } from './db/powersync';
+
+const adapter = drizzleAdapter(drizzle);
+export const bridge = createBridge({
+  driver: createPowerSyncDriver(db, { adapter, onlineHint: () => navigator.onLine }),
+  adapter,
+  platformGates: { native: 'local-first', web: 'race' },
+});
+```
+
+```ts
+// db/boot.ts — connect THROUGH the bridge: identity is derived from the JWT your connector
+// already returns. Never pass claims yourself.
+await db.init();
+await db.connect(bridge.wrapConnector(connector));
+```
+
+```tsx
+// App.tsx
+<BridgeProvider bridge={bridge}>
+  <Router />
+</BridgeProvider>
+```
+
+## A raced list (page 1, with joins)
+
+```ts
+import { z } from 'zod';
+import { desc, eq } from 'drizzle-orm';
+import { defineRacedList } from 'powersync-bridge';
+import { drizzle } from '../db/powersync';
+import { sales, customers, users } from '../db/schema';
+
+const SaleApi = z.object({
+  id: z.string(), sold_at: z.string(), total: z.string(),
+  status: z.enum(['OPEN', 'PAID', 'VOID']), item_count: z.number().int(),
+  customer_name: z.string(), seller_name: z.string(),
+});
+type SaleApi = z.infer<typeof SaleApi>;
+
+export const RecentSales = defineRacedList({
+  id: 'recent-sales',
+  table: 'sales',
+  // The row type is inferred from this query. Annotate the scope; close over your drizzle instance.
+  query: ({ orgId }: { orgId: string }) =>
+    drizzle
+      .select({
+        id: sales.id, soldAt: sales.soldAt, total: sales.total, status: sales.status,
+        itemCount: sales.itemCount, customerName: customers.name, sellerName: users.displayName,
+      })
+      .from(sales)
+      .innerJoin(customers, eq(customers.id, sales.customerId))
+      .innerJoin(users, eq(users.id, sales.sellerId))
+      .where(eq(sales.orgId, orgId))
+      .orderBy(desc(sales.soldAt), desc(sales.id))
+      .limit(50),
+  fetchSnapshot: async (_scope, signal) => {
+    const res = await api.get('/api/sales?limit=50', { signal });
+    return { rows: z.array(SaleApi).parse(res.items) };
+  },
+  mapApi: (o: SaleApi) => ({            // return type is checked against the query's row type
+    id: o.id, soldAt: o.sold_at, total: o.total, status: o.status,
+    itemCount: o.item_count, customerName: o.customer_name, sellerName: o.seller_name,
+  }),
+  orderKey: ['soldAt', 'id'] as const,  // `id` is always the implicit tiebreaker
+  direction: 'desc',
+  limit: 50,
+  stream: { name: 'sales_window', params: null },
+});
+```
+
+```tsx
+function RecentSalesScreen({ orgId }: { orgId: string }) {
+  const { items, state, errors } = useRacedList(RecentSales, { orgId });
+  if (state === 'pending') return <Skeleton />;
+  return (
+    <FlatList
+      data={items}
+      keyExtractor={(r) => r.row.id}
+      renderItem={({ item }) => (
+        <SaleRow
+          sale={item.row}
+          muted={item.stale === true || !item.presentLocally}
+          onVoid={item.presentLocally ? () => voidSale(item.row.id) : undefined}   // presence-gated writes
+        />
+      )}
+    />
+  );
+}
+```
+
+## An infinite list (older months via sync streams)
+
+```ts
+import { defineInfiniteList, type Cursor, type PageArgs } from 'powersync-bridge';
+
+type SaleCursor = Cursor<SaleRow, ['soldAt', 'id']>;   // [string, string] | undefined
+
+export const SalesHistory = defineInfiniteList({
+  id: 'sales-history',
+  table: 'sales',
+  pageSize: 50,
+  orderKey: ['soldAt', 'id'] as const,
+  direction: 'desc',
+  // Annotate the page argument with the Cursor type; the row type is inferred from the return.
+  query: ({ cursor, limit }: PageArgs<SaleCursor>, { orgId }: { orgId: string }) =>
+    drizzle.select(projection).from(sales) /* …joins… */
+      .where(and(eq(sales.orgId, orgId), cursor ? or(lt(sales.soldAt, cursor[0]), and(eq(sales.soldAt, cursor[0]), lt(sales.id, cursor[1]))) : undefined))
+      .orderBy(desc(sales.soldAt), desc(sales.id))
+      .limit(limit),
+  escalate: {
+    kind: 'partition',
+    stream: 'sales_month',
+    partitionOf: (c) => (c ? c[0].slice(0, 7) : currentMonth()),
+    nextPartition: prevMonth,
+    partitionParams: (m) => ({ month: m }),
+    floor: '2015-01',                                              // static floor, always required
+    serverFloor: async () => (await api.get('/api/sales/floor')).month,   // optional exact floor
+  },
+});
+```
+
+```yaml
+# sync_streams.yaml — no partition column; the month is computed from your existing timestamp
+sales_month:
+  query: >
+    SELECT * FROM sales
+    WHERE org_id = auth.parameter('org_id')
+      AND substring(sold_at::text, 1, 7) = subscription.parameter('month')
+```
+
+Or escalate through your API instead (`kind: 'api'` with a cursor, or `kind: 'api-offset'` for
+offset-only APIs, where duplicates are dropped and a shift is reported in `warnings`).
+
+## Rules that make it safe
+
+- **Pending writes always win** — the live upload queue, a seeded snapshot-lifetime window, and
+  recently-acked writes shield your edits from an older API snapshot.
+- **Freshness is session-scoped** — PowerSync's persisted `hasSynced` never counts as "fresh";
+  a checkpoint is stamped at its download start and the stamp is monotonic.
+- **Deletes never resurrect** — a pending delete tombstones its id for the snapshot's lifetime.
+- **Removals are classified** — a batched presence probe distinguishes filtered-out from
+  deleted; stream expiry distinguishes deleted from evicted; evicted rows stay visible but
+  are marked `presentLocally: false` and cannot be written.
+- **Identity is derived** — from the connector's JWT, deny-listing volatile claims; an org
+  switch swaps every store's root synchronously, so no frame renders the outgoing tenant.
+
+Sorting constraints: the sort column must compare identically on Postgres and SQLite.
+ISO-8601 UTC strings, integers and uuidv7 are safe. For text use `ORDER BY col COLLATE "C"` on
+the API; for decimals declare the column as `column.real` in the client schema.
+
+## Testing your own lists
+
+`powersync-bridge/testing` ships a `FakeDriver` with virtual time: script sync status,
+checkpoints, uploads, stream first-syncs and API responses, then assert on interleavings. See
+`packages/core/test` for the invariant suite (T1–T44 in ARCHITECTURE.md §12.2).
+
+## Layout
+
+```
+packages/core              powersync-bridge            engine, definitions, testing driver
+packages/react             @powersync-bridge/react     BridgeProvider + hooks
+packages/adapters/drizzle  @powersync-bridge/drizzle   builder → PreparedQuery (decoded rows)
+packages/powersync         @powersync-bridge/powersync BridgeDriver over @powersync/common
+```
+
+Design: `ARCHITECTURE.md`. Build brief and worked example: `BUILD-READINESS.md`.

package/dist/index.cjs

@@ -0,0 +1,92 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  BridgeProvider: () => BridgeProvider,
+  useAutoSync: () => useAutoSync,
+  useBridge: () => useBridge,
+  useInfiniteList: () => useInfiniteList,
+  useOnDemandStream: () => useOnDemandStream,
+  useRacedList: () => useRacedList
+});
+module.exports = __toCommonJS(src_exports);
+var import_react = require("react");
+var BridgeContext = (0, import_react.createContext)(null);
+function BridgeProvider({ bridge, children }) {
+  return (0, import_react.createElement)(BridgeContext.Provider, { value: bridge }, children);
+}
+function useBridge() {
+  const b = (0, import_react.useContext)(BridgeContext);
+  if (!b) throw new Error("powersync-bridge: no <BridgeProvider> above this component");
+  return b;
+}
+function useEpoch(bridge) {
+  return (0, import_react.useSyncExternalStore)(bridge.epochStore.subscribe, bridge.epochStore.getSnapshot, bridge.epochStore.getSnapshot);
+}
+function useRetained(bridge, key, acquire) {
+  const epoch = useEpoch(bridge);
+  const holder = (0, import_react.useMemo)(() => acquire(), [bridge, epoch, key]);
+  (0, import_react.useEffect)(() => {
+    holder.retain();
+    return () => holder.release();
+  }, [holder]);
+  return (0, import_react.useSyncExternalStore)(holder.store.subscribe, holder.store.getSnapshot, holder.store.getSnapshot);
+}
+function useRacedList(def, scope) {
+  const bridge = useBridge();
+  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;
+  return useRetained(bridge, key, () => bridge.raced(def, scope));
+}
+function useInfiniteList(def, scope) {
+  const bridge = useBridge();
+  const epoch = useEpoch(bridge);
+  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;
+  const store = (0, import_react.useMemo)(() => bridge.infinite(def, scope), [bridge, epoch, key]);
+  (0, import_react.useEffect)(() => {
+    store.retain();
+    return () => store.release();
+  }, [store]);
+  const result = (0, import_react.useSyncExternalStore)(store.store.subscribe, store.store.getSnapshot, store.store.getSnapshot);
+  return (0, import_react.useMemo)(
+    () => ({ ...result, loadMore: () => void store.loadMore(), retry: () => void store.retry() }),
+    [result, store]
+  );
+}
+function useOnDemandStream(name, params, opts = {}) {
+  const bridge = useBridge();
+  const key = `${name}:${JSON.stringify(params)}:${JSON.stringify(opts)}`;
+  return useRetained(bridge, key, () => bridge.onDemand(name, params, opts));
+}
+function useAutoSync(config, ids) {
+  const bridge = useBridge();
+  const key = `${config.stream}:${JSON.stringify([...ids].sort())}`;
+  return useRetained(bridge, key, () => bridge.autoSync(config, ids));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BridgeProvider,
+  useAutoSync,
+  useBridge,
+  useInfiniteList,
+  useOnDemandStream,
+  useRacedList
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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":[]}

package/dist/index.d.cts

@@ -0,0 +1,24 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Bridge, InfiniteListResult, FlaggerConfig, FlagResult, OrderKey, InfiniteListDefinition, Params, OnDemandOptions, OnDemandResult, RacedListDefinition, RacedListResult } from 'powersync-bridge';
+
+interface BridgeProviderProps {
+    bridge: Bridge;
+    children?: ReactNode;
+}
+/** 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 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> {
+    loadMore(): void;
+    /** Clears API backoff and loads (R16). */
+    retry(): void;
+}
+declare function useInfiniteList<TItem, TScope, K extends OrderKey<TItem>, TCursor, TPartition>(def: InfiniteListDefinition<TItem, TScope, K, TCursor, TPartition>, scope: TScope): UseInfiniteListResult<TItem>;
+/** The default "pull one row into the offline DB" primitive (§7). */
+declare function useOnDemandStream(name: string, params: Params | null, opts?: OnDemandOptions): OnDemandResult;
+/** 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 };

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Bridge, InfiniteListResult, FlaggerConfig, FlagResult, OrderKey, InfiniteListDefinition, Params, OnDemandOptions, OnDemandResult, RacedListDefinition, RacedListResult } from 'powersync-bridge';
+
+interface BridgeProviderProps {
+    bridge: Bridge;
+    children?: ReactNode;
+}
+/** 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 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> {
+    loadMore(): void;
+    /** Clears API backoff and loads (R16). */
+    retry(): void;
+}
+declare function useInfiniteList<TItem, TScope, K extends OrderKey<TItem>, TCursor, TPartition>(def: InfiniteListDefinition<TItem, TScope, K, TCursor, TPartition>, scope: TScope): UseInfiniteListResult<TItem>;
+/** The default "pull one row into the offline DB" primitive (§7). */
+declare function useOnDemandStream(name: string, params: Params | null, opts?: OnDemandOptions): OnDemandResult;
+/** 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 };

package/dist/index.js

@@ -0,0 +1,62 @@
+// src/index.ts
+import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
+var BridgeContext = createContext(null);
+function BridgeProvider({ bridge, children }) {
+  return createElement(BridgeContext.Provider, { value: bridge }, children);
+}
+function useBridge() {
+  const b = useContext(BridgeContext);
+  if (!b) throw new Error("powersync-bridge: no <BridgeProvider> above this component");
+  return b;
+}
+function useEpoch(bridge) {
+  return useSyncExternalStore(bridge.epochStore.subscribe, bridge.epochStore.getSnapshot, bridge.epochStore.getSnapshot);
+}
+function useRetained(bridge, key, acquire) {
+  const epoch = useEpoch(bridge);
+  const holder = useMemo(() => acquire(), [bridge, epoch, key]);
+  useEffect(() => {
+    holder.retain();
+    return () => holder.release();
+  }, [holder]);
+  return useSyncExternalStore(holder.store.subscribe, holder.store.getSnapshot, holder.store.getSnapshot);
+}
+function useRacedList(def, scope) {
+  const bridge = useBridge();
+  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;
+  return useRetained(bridge, key, () => bridge.raced(def, scope));
+}
+function useInfiniteList(def, scope) {
+  const bridge = useBridge();
+  const epoch = useEpoch(bridge);
+  const key = `${def.id}:${JSON.stringify(scope ?? null)}`;
+  const store = useMemo(() => bridge.infinite(def, scope), [bridge, epoch, key]);
+  useEffect(() => {
+    store.retain();
+    return () => store.release();
+  }, [store]);
+  const result = useSyncExternalStore(store.store.subscribe, store.store.getSnapshot, store.store.getSnapshot);
+  return useMemo(
+    () => ({ ...result, loadMore: () => void store.loadMore(), retry: () => void store.retry() }),
+    [result, store]
+  );
+}
+function useOnDemandStream(name, params, opts = {}) {
+  const bridge = useBridge();
+  const key = `${name}:${JSON.stringify(params)}:${JSON.stringify(opts)}`;
+  return useRetained(bridge, key, () => bridge.onDemand(name, params, opts));
+}
+function useAutoSync(config, ids) {
+  const bridge = useBridge();
+  const key = `${config.stream}:${JSON.stringify([...ids].sort())}`;
+  return useRetained(bridge, key, () => bridge.autoSync(config, ids));
+}
+export {
+  BridgeProvider,
+  useAutoSync,
+  useBridge,
+  useInfiniteList,
+  useOnDemandStream,
+  useRacedList
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@powersync-bridge/react",
+  "version": "0.0.1-alpha.0",
+  "description": "React bindings for powersync-bridge: BridgeProvider, useRacedList, useInfiniteList, useOnDemandStream, useAutoSync (useSyncExternalStore-based).",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akpor-kofi/powersync-bridge.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/akpor-kofi/powersync-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/akpor-kofi/powersync-bridge/issues"
+  },
+  "keywords": [
+    "powersync",
+    "offline-first",
+    "local-first",
+    "sqlite",
+    "sync",
+    "react",
+    "hooks"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "powersync-bridge": "0.0.1-alpha.0"
+  },
+  "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"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}