@sync-subscribe/client-react 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 fromkeith
+
+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,197 @@
+# @sync-subscribe/client-react
+
+React bindings for `@sync-subscribe/client`. Provides a context provider and hooks for subscribing to synced data, making mutations, and automatically replaying changes when the device comes back online.
+
+## Installation
+
+```bash
+npm install @sync-subscribe/client-react @sync-subscribe/client @sync-subscribe/core
+```
+
+React ≥ 18 is a peer dependency.
+
+## Quick start
+
+```tsx
+import { SyncClient, IdbLocalStore, createFetchTransport } from "@sync-subscribe/client";
+import { SyncProvider, useRecords, useMutate } from "@sync-subscribe/client-react";
+
+// Create the client once at module level (outside components)
+const client = new SyncClient(
+  createFetchTransport({ baseUrl: "/api" }),
+  new IdbLocalStore("my-app-db"), // persists across reloads; omit for in-memory
+);
+
+function App() {
+  return (
+    <SyncProvider client={client}>
+      <NotesList />
+    </SyncProvider>
+  );
+}
+
+function NotesList() {
+  const notes = useRecords<NoteRecord>({ filter: { isDeleted: false } });
+  const mutate = useMutate<NoteRecord>();
+
+  async function handleDelete(note: NoteRecord) {
+    await mutate({
+      ...note,
+      isDeleted: true,
+      updatedAt: Date.now(),
+      revisionCount: note.revisionCount + 1,
+    });
+  }
+
+  return (
+    <ul>
+      {notes.map((n) => (
+        <li key={n.recordId}>
+          {n.title}
+          <button onClick={() => handleDelete(n)}>Delete</button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## API
+
+### `<SyncProvider client={client}>`
+
+Provides the `SyncClient` to all child hooks. Place it once near the root of your app.
+
+The provider also manages the **offline mutation queue**. Mutations made while the device is offline are written to the local store immediately (read-your-own-writes) and pushed to the server automatically when connectivity is restored.
+
+```tsx
+<SyncProvider client={client}>
+  <App />
+</SyncProvider>
+```
+
+---
+
+### `useRecords<T>(options)`
+
+Subscribes to a filtered view of records and returns them as a live array.
+
+```ts
+const notes = useRecords<NoteRecord>({
+  filter: { isDeleted: false },
+  name: "active-notes", // optional — persists subscription state across sessions
+});
+```
+
+**What it does:**
+- On mount: registers a subscription locally for `filter`, pulls the initial batch, and opens an SSE stream
+- Re-renders on every incoming patch (from pull, stream, or conflict resolution)
+- When `filter` changes: registers a new subscription, replacing the old one. Gap analysis runs locally to determine whether any records matching the new filter are not yet cached — if so they are fetched before joining the stream. Records that only the old filter needed are evicted.
+- Filters the local store client-side with `matchesFilter`, so multiple overlapping `useRecords` calls with different filters work correctly
+
+**Filter operators:**
+
+```ts
+// Equality
+useRecords({ filter: { color: "blue" } });
+
+// Comparison operators
+useRecords({ filter: { createdAt: { $gte: Date.now() - 30 * 24 * 60 * 60 * 1000 } } });
+
+// Multiple conditions (all must match)
+useRecords({ filter: { isDeleted: false, category: "work" } });
+
+// $or
+useRecords({ filter: { $or: [{ color: "blue" }, { color: "red" }] } });
+```
+
+**Stable filter references:**
+
+`useRecords` serialises the filter to detect changes, so passing an inline object literal is safe — it won't trigger unnecessary re-subscriptions:
+
+```tsx
+// Fine — does NOT re-subscribe on every render
+const notes = useRecords({ filter: { isDeleted: false } });
+```
+
+---
+
+### `useMutate<T>()`
+
+Returns a `mutate` function scoped to the nearest `SyncProvider`.
+
+```ts
+const mutate = useMutate<NoteRecord>();
+```
+
+**`mutate(record): Promise<boolean>`**
+- Writes the record to the local store immediately (read-your-own-writes)
+- If **online**: pushes to the server; returns `true` on success, `false` on conflict (server record wins and is applied locally)
+- If **offline**: queues the push and returns `true` optimistically; the push is retried when the device comes back online
+
+Always increment `revisionCount` on every change:
+
+```ts
+// Create
+await mutate({
+  recordId: crypto.randomUUID(),
+  createdAt: Date.now(),
+  updatedAt: Date.now(),
+  revisionCount: 1,
+  title: "New note",
+  isDeleted: false,
+});
+
+// Update
+await mutate({
+  ...existing,
+  title: "Edited title",
+  updatedAt: Date.now(),
+  revisionCount: existing.revisionCount + 1,
+});
+
+// Soft-delete
+await mutate({
+  ...existing,
+  isDeleted: true,
+  updatedAt: Date.now(),
+  revisionCount: existing.revisionCount + 1,
+});
+```
+
+---
+
+### `useSyncClient<T>()`
+
+Escape hatch to access the raw `SyncClient` from context.
+
+```ts
+const client = useSyncClient<NoteRecord>();
+await client.reset(); // e.g. on logout
+```
+
+---
+
+## Offline behaviour
+
+`SyncProvider` listens to the browser's `online` event. When the device reconnects, it drains the pending queue in the order mutations were made, deduplicating by `recordId` (only the latest mutation per record is sent).
+
+```
+offline  →  mutate(noteA v1)  →  mutate(noteA v2)  →  online
+                                                          ↓
+                                               push(noteA v2)   ← only latest sent
+```
+
+If a push fails after reconnecting (e.g. the server is still unreachable), the record is re-queued and retried on the next `online` event.
+
+---
+
+## Multiple subscriptions
+
+Multiple `useRecords` calls create independent subscriptions. The local store deduplicates records by `recordId`, so records matching more than one filter are stored only once. Each hook filters client-side to return its own view.
+
+```tsx
+// Two subscriptions, no duplicates in the local store
+const recentNotes = useRecords({ filter: { createdAt: { $gte: thirtyDaysAgo } } });
+const blueNotes   = useRecords({ filter: { color: "blue" } });
+```

package/dist/context.d.ts

@@ -0,0 +1,34 @@
+import type { ReactNode } from "react";
+import type { SyncRecord } from "@sync-subscribe/core";
+import type { SyncClient } from "@sync-subscribe/client";
+export interface SyncContextValue {
+    client: SyncClient<any>;
+    /**
+     * Enqueue a mutation. If the device is online the record is pushed to the
+     * server immediately via client.mutate(). If offline, the record is written
+     * to the local store for read-your-own-writes and queued; it will be pushed
+     * automatically when connectivity is restored.
+     */
+    enqueue: (record: SyncRecord) => Promise<boolean>;
+}
+export declare const SyncContext: import("react").Context<SyncContextValue | null>;
+export interface SyncProviderProps {
+    client: SyncClient<any>;
+    children: ReactNode;
+}
+/**
+ * Provides a SyncClient to all child hooks.
+ * Place this once near the root of your app.
+ *
+ * The provider also manages the offline mutation queue:
+ * mutations made while the device is offline are held in memory and
+ * automatically replayed (in order, deduplicated by recordId) when
+ * connectivity resumes.
+ */
+export declare function SyncProvider({ client, children }: SyncProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Returns the SyncClient from the nearest SyncProvider.
+ * The generic parameter lets you recover the typed client at the call site.
+ */
+export declare function useSyncClient<T extends SyncRecord = SyncRecord>(): SyncClient<T>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAE/B,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IACxB;;;;;OAKG;IACH,OAAO,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACnD;AAED,eAAO,MAAM,WAAW,kDAA+C,CAAC;AAExE,MAAM,WAAW,iBAAiB;IAEhC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IACxB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,iBAAiB,2CA4CnE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,CAAC,SAAS,UAAU,GAAG,UAAU,KAC9B,UAAU,CAAC,CAAC,CAAC,CAIjB"}

package/dist/context.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, } from "react";
+export const SyncContext = createContext(null);
+/**
+ * Provides a SyncClient to all child hooks.
+ * Place this once near the root of your app.
+ *
+ * The provider also manages the offline mutation queue:
+ * mutations made while the device is offline are held in memory and
+ * automatically replayed (in order, deduplicated by recordId) when
+ * connectivity resumes.
+ */
+export function SyncProvider({ client, children }) {
+    // Map<recordId, record> — only the latest mutation per record is kept.
+    const queue = useRef(new Map());
+    // Drain pending mutations when connectivity is restored.
+    useEffect(() => {
+        async function drain() {
+            if (queue.current.size === 0)
+                return;
+            const pending = [...queue.current.values()];
+            queue.current.clear();
+            for (const record of pending) {
+                await client.mutate(record).catch(() => {
+                    // Push still failing — re-queue so we retry on the next online event.
+                    queue.current.set(record.recordId, record);
+                });
+            }
+        }
+        const isWindow = typeof window !== "undefined";
+        if (isWindow)
+            window.addEventListener("online", drain);
+        return () => {
+            if (isWindow)
+                window.removeEventListener("online", drain);
+        };
+    }, [client]);
+    const enqueue = useCallback(async (record) => {
+        const online = typeof navigator === "undefined" ? true : navigator.onLine;
+        if (online) {
+            return client.mutate(record);
+        }
+        // Offline path: queue the raw record. mutate() will stamp on drain.
+        queue.current.set(record.recordId, record);
+        return true; // optimistic — push will happen when back online
+    }, [client]);
+    const value = useMemo(() => ({ client, enqueue }), [client, enqueue]);
+    return _jsx(SyncContext.Provider, { value: value, children: children });
+}
+/**
+ * Returns the SyncClient from the nearest SyncProvider.
+ * The generic parameter lets you recover the typed client at the call site.
+ */
+export function useSyncClient() {
+    const ctx = useContext(SyncContext);
+    if (!ctx)
+        throw new Error("useSyncClient must be used inside <SyncProvider>");
+    return ctx.client;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":";AAAA,OAAO,EACL,aAAa,EACb,WAAW,EACX,UAAU,EACV,SAAS,EACT,OAAO,EACP,MAAM,GACP,MAAM,OAAO,CAAC;AAiBf,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAA0B,IAAI,CAAC,CAAC;AAQxE;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAqB;IAClE,uEAAuE;IACvE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,GAAG,EAAsB,CAAC,CAAC;IAEpD,yDAAyD;IACzD,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,UAAU,KAAK;YAClB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;gBAAE,OAAO;YACrC,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YAC5C,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACtB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;oBACrC,sEAAsE;oBACtE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;gBAC7C,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC;QAC/C,IAAI,QAAQ;YAAE,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACvD,OAAO,GAAG,EAAE;YACV,IAAI,QAAQ;gBAAE,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC5D,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,MAAM,OAAO,GAAG,WAAW,CACzB,KAAK,EAAE,MAAkB,EAAoB,EAAE;QAC7C,MAAM,MAAM,GACV,OAAO,SAAS,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC;QAE7D,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC;QAED,oEAAoE;QACpE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC,CAAC,iDAAiD;IAChE,CAAC,EACD,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEtE,OAAO,KAAC,WAAW,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAwB,CAAC;AAC/E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAG3B,MAAM,GAAG,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IAC9E,OAAO,GAAG,CAAC,MAAuB,CAAC;AACrC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { SyncProvider, useSyncClient } from "./context.js";
+export type { SyncProviderProps, SyncContextValue } from "./context.js";
+export { useRecords } from "./useRecords.js";
+export type { UseRecordsOptions } from "./useRecords.js";
+export { useQuery } from "./useQuery.js";
+export { useMutate } from "./useMutate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAExE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { SyncProvider, useSyncClient } from "./context.js";
+export { useRecords } from "./useRecords.js";
+export { useQuery } from "./useQuery.js";
+export { useMutate } from "./useMutate.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG3D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/useMutate.d.ts

@@ -0,0 +1,21 @@
+import type { SyncRecord } from "@sync-subscribe/core";
+/**
+ * Returns a `mutate` function that writes a record to the local store and
+ * pushes it to the server.
+ *
+ * `mutate` automatically stamps `updatedAt` and increments `revisionCount` —
+ * callers should not set those fields.
+ *
+ * When the device is **offline** the mutation is queued and replayed
+ * automatically by `SyncProvider` when connectivity is restored.
+ *
+ * Returns `true` on success (or when queued offline), `false` when the
+ * server rejected the push due to a conflict (server record wins).
+ *
+ * @example
+ * const mutate = useMutate<NoteRecord>();
+ *
+ * await mutate({ ...note, title: "Updated title" });
+ */
+export declare function useMutate<T extends SyncRecord>(): (record: T) => Promise<boolean>;
+//# sourceMappingURL=useMutate.d.ts.map

package/dist/useMutate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMutate.d.ts","sourceRoot":"","sources":["../src/useMutate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGvD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,UAAU,KAAK,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CASjF"}

package/dist/useMutate.js

@@ -0,0 +1,28 @@
+import { useCallback, useContext } from "react";
+import { SyncContext } from "./context.js";
+/**
+ * Returns a `mutate` function that writes a record to the local store and
+ * pushes it to the server.
+ *
+ * `mutate` automatically stamps `updatedAt` and increments `revisionCount` —
+ * callers should not set those fields.
+ *
+ * When the device is **offline** the mutation is queued and replayed
+ * automatically by `SyncProvider` when connectivity is restored.
+ *
+ * Returns `true` on success (or when queued offline), `false` when the
+ * server rejected the push due to a conflict (server record wins).
+ *
+ * @example
+ * const mutate = useMutate<NoteRecord>();
+ *
+ * await mutate({ ...note, title: "Updated title" });
+ */
+export function useMutate() {
+    const ctx = useContext(SyncContext);
+    if (!ctx)
+        throw new Error("useMutate must be used inside <SyncProvider>");
+    const { enqueue } = ctx;
+    return useCallback((record) => enqueue(record), [enqueue]);
+}
+//# sourceMappingURL=useMutate.js.map

package/dist/useMutate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMutate.js","sourceRoot":"","sources":["../src/useMutate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,GAAG,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAC1E,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC;IAExB,OAAO,WAAW,CAChB,CAAC,MAAS,EAAE,EAAE,CAAC,OAAO,CAAC,MAAoB,CAAC,EAC5C,CAAC,OAAO,CAAC,CACV,CAAC;AACJ,CAAC"}

package/dist/useQuery.d.ts

@@ -0,0 +1,26 @@
+import type { SyncRecord } from "@sync-subscribe/core";
+import type { SyncQuery } from "@sync-subscribe/client";
+/**
+ * Subscribes to a `SyncQuery` and returns its current `{ data, loading }` state.
+ *
+ * The `syncQuery` reference must be stable across renders — create it with
+ * `useMemo` or at module level, otherwise it will re-subscribe on every render.
+ *
+ * Works with both `client.query()` (local-store only) and `client.liveQuery()`
+ * (sync + query combined).
+ *
+ * @example
+ * // Local-only query (data already synced elsewhere)
+ * const q = useMemo(() => client.query({ filter: { isDeleted: false } }), [client]);
+ * const { data, loading } = useQuery(q);
+ *
+ * @example
+ * // Live query — manages its own sync subscription
+ * const q = useMemo(() => client.liveQuery({ filter: { isDeleted: false } }), [client]);
+ * const { data, loading } = useQuery(q);
+ */
+export declare function useQuery<T extends SyncRecord>(syncQuery: SyncQuery<T>): {
+    data: T[];
+    loading: boolean;
+};
+//# sourceMappingURL=useQuery.d.ts.map

package/dist/useQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQuery.d.ts","sourceRoot":"","sources":["../src/useQuery.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,UAAU,EAC3C,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GACtB;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAWjC"}

package/dist/useQuery.js

@@ -0,0 +1,31 @@
+import { useEffect, useState } from "react";
+/**
+ * Subscribes to a `SyncQuery` and returns its current `{ data, loading }` state.
+ *
+ * The `syncQuery` reference must be stable across renders — create it with
+ * `useMemo` or at module level, otherwise it will re-subscribe on every render.
+ *
+ * Works with both `client.query()` (local-store only) and `client.liveQuery()`
+ * (sync + query combined).
+ *
+ * @example
+ * // Local-only query (data already synced elsewhere)
+ * const q = useMemo(() => client.query({ filter: { isDeleted: false } }), [client]);
+ * const { data, loading } = useQuery(q);
+ *
+ * @example
+ * // Live query — manages its own sync subscription
+ * const q = useMemo(() => client.liveQuery({ filter: { isDeleted: false } }), [client]);
+ * const { data, loading } = useQuery(q);
+ */
+export function useQuery(syncQuery) {
+    const [state, setState] = useState({
+        data: [],
+        loading: true,
+    });
+    useEffect(() => {
+        return syncQuery.subscribe((value) => setState(value));
+    }, [syncQuery]);
+    return state;
+}
+//# sourceMappingURL=useQuery.js.map

package/dist/useQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQuery.js","sourceRoot":"","sources":["../src/useQuery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAI5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,QAAQ,CACtB,SAAuB;IAEvB,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAkC;QAClE,IAAI,EAAE,EAAE;QACR,OAAO,EAAE,IAAI;KACd,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,SAAS,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IACzD,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;IAEhB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/useRecords.d.ts

@@ -0,0 +1,32 @@
+import type { SyncRecord, SubscriptionFilter } from "@sync-subscribe/core";
+export interface UseRecordsOptions<T extends SyncRecord = SyncRecord> {
+    filter: SubscriptionFilter<T>;
+    /**
+     * Stable name for this subscription. When provided, the subscription state
+     * is persisted to the local store and automatically restored on next startup,
+     * enabling incremental sync instead of a full re-fetch.
+     */
+    name?: string;
+}
+/**
+ * Sync-and-query shorthand. Registers a live sync subscription for `filter`
+ * and returns its records as `{ data, loading }`.
+ *
+ * `loading` is `true` until the first pull completes.
+ * The sync subscription is automatically removed when the component unmounts.
+ *
+ * For a narrower in-memory view over a broader background sync (e.g. showing
+ * 1 day of data while syncing 30 days), use `useQuery` with `client.query()`
+ * instead — it reads from the local store without registering a new subscription.
+ *
+ * @example
+ * const { data: notes, loading } = useRecords<NoteRecord>({
+ *   filter: { isDeleted: false },
+ *   name: "active-notes",
+ * });
+ */
+export declare function useRecords<T extends SyncRecord>(options: UseRecordsOptions<T>): {
+    data: T[];
+    loading: boolean;
+};
+//# sourceMappingURL=useRecords.d.ts.map

package/dist/useRecords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRecords.d.ts","sourceRoot":"","sources":["../src/useRecords.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAI3E,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IAClE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC9B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,UAAU,EAC7C,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAejC"}

package/dist/useRecords.js

@@ -0,0 +1,33 @@
+import { useMemo } from "react";
+import { useSyncClient } from "./context.js";
+import { useQuery } from "./useQuery.js";
+/**
+ * Sync-and-query shorthand. Registers a live sync subscription for `filter`
+ * and returns its records as `{ data, loading }`.
+ *
+ * `loading` is `true` until the first pull completes.
+ * The sync subscription is automatically removed when the component unmounts.
+ *
+ * For a narrower in-memory view over a broader background sync (e.g. showing
+ * 1 day of data while syncing 30 days), use `useQuery` with `client.query()`
+ * instead — it reads from the local store without registering a new subscription.
+ *
+ * @example
+ * const { data: notes, loading } = useRecords<NoteRecord>({
+ *   filter: { isDeleted: false },
+ *   name: "active-notes",
+ * });
+ */
+export function useRecords(options) {
+    const client = useSyncClient();
+    // Stringify the filter so object literals don't cause a new liveQuery on every render.
+    const filterKey = JSON.stringify(options.filter);
+    const liveQuery = useMemo(() => client.liveQuery({
+        filter: options.filter,
+        ...(options.name !== undefined && { name: options.name }),
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [client, filterKey, options.name]);
+    return useQuery(liveQuery);
+}
+//# sourceMappingURL=useRecords.js.map

package/dist/useRecords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRecords.js","sourceRoot":"","sources":["../src/useRecords.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAEhC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAYzC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU,CACxB,OAA6B;IAE7B,MAAM,MAAM,GAAG,aAAa,EAAK,CAAC;IAClC,uFAAuF;IACvF,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjD,MAAM,SAAS,GAAG,OAAO,CACvB,GAAG,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC;QACrB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;KAC1D,CAAC;IACF,uDAAuD;IACvD,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAClC,CAAC;IAEF,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAC;AAC7B,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@sync-subscribe/client-react",
+  "version": "0.3.2",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@sync-subscribe/client": "0.3.2",
+    "@sync-subscribe/core": "0.3.2"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^19.1.0",
+    "jsdom": "^26.0.0",
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --build --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}