supastash 0.1.4 → 0.1.6

package/README.md

@@ -1,27 +1,25 @@
 # Supastash
 
-**Offline-First Sync Engine for Supabase + React Native.**
+**Offline-First Sync Engine for Supabase + React Native**
 
-> Reliable offline-first syncing for Supabase + React Native using local SQLite. Plug in your adapter and get syncing — no boilerplate.
+> Sync local SQLite data with Supabase in real-time — even when your app is offline. Built for React Native, no boilerplate required.
 
-Supastash makes it effortless to build offline-capable mobile apps using **SQLite for local-first storage** and **Supabase for cloud sync**. Designed for React Native, Supastash handles syncing, conflict resolution, realtime updates, and local querying so you can focus on features, not infrastructure.
+Supastash gives your app **instant offline access**, **two-way syncing**, and **real-time updates** — all while letting you work with local data as the source of truth.
 
 ---
 
-### 📚 Documentation
-
-Read the [Docs](https://0xzekea.github.io/supastash/)
+## 📚 **[Read the Full Docs »](https://0xzekea.github.io/supastash/)**
 
 ---
 
-## 🚀 Features
+## ✨ Features
 
-- 🔁 **Two-way sync** with Supabase
-- 💾 **Local-first querying** with React Native SQLite
-- ⚡ **Realtime updates** using Supabase channels
-- 🔌 **Pluggable SQLite adapters** (`expo-sqlite`, `react-native-nitro-sqlite`, `react-native-sqlite-storage`)
-- ✅ **Built-in deduplication**, conflict resolution, and background retries
-- 🧠 Designed to support **event batching**, **job staging**, and fine-grained sync control
+- 🔁 Two-way sync with Supabase
+- 💾 Local-first querying via SQLite
+- ⚡ Realtime updates (INSERT, UPDATE, DELETE)
+- 🔌 Works with any SQLite adapter (`expo-sqlite`, `rn-nitro`, `sqlite-storage`)
+- 🧠 Handles conflict resolution, batching, retries
+- 🧩 Supports filtering, job staging, and advanced sync control
 
 ---
 
@@ -29,31 +27,34 @@ Read the [Docs](https://0xzekea.github.io/supastash/)
 
 ```bash
 npm install supastash
-# or
-yarn add supastash
 ```
 
-### 📎 Peer Dependencies (You MUST install these)
+### Required Peer Dependencies
 
 ```bash
-npm install @supabase/supabase-js
-             @react-native-community/netinfo
-             react
-             react-native
+npm install @supabase/supabase-js \
+             @react-native-community/netinfo \
+             react react-native
+```
+
+### Choose one SQLite adapter:
 
-# Choose one SQLite adapter:
+```bash
+# Expo
 npm install expo-sqlite
-# OR React Native Nitro
+
+# React Native Nitro (faster)
 npm install react-native-nitro-sqlite
-# OR React Native SQLite Storage
+
+# Or classic storage
 npm install react-native-sqlite-storage
 ```
 
-> `sqliteClientType` must match your adapter: "expo", "rn-nitro", or "rn-storage"
+> Match with: `"sqliteClientType": "expo"`, `"rn-nitro"`, or `"rn-storage"`
 
 ---
 
-## ⚙️ Setup
+## ⚙️ Quick Setup
 
 ```ts
 // lib/supastash.ts
@@ -66,6 +67,7 @@ configureSupastash({
   dbName: "supastash_db",
   sqliteClient: { openDatabaseAsync },
   sqliteClientType: "expo",
+
   onSchemaInit: () => {
     defineLocalSchema(
       "users",
@@ -73,60 +75,48 @@ configureSupastash({
         id: "TEXT PRIMARY KEY",
         name: "TEXT",
         email: "TEXT",
-        created_at: "TIMESTAMP DEFAULT CURRENT_TIMESTAMP",
-        updated_at: "TIMESTAMP DEFAULT CURRENT_TIMESTAMP",
+        created_at: "TIMESTAMP",
+        updated_at: "TIMESTAMP",
       },
       true
     );
   },
+
   debugMode: true,
   syncEngine: {
     push: true,
-    pull: false, // ⚠️ Pull sync is disabled by default.
+    pull: false, // enable if using RLS
   },
 });
 ```
 
-Then initialize early:
+Then in your root layout:
 
 ```ts
-// _layout.tsx or App.tsx
+// App.tsx or _layout.tsx
 import "@/lib/supastash";
 
-export default function RootLayout() {
+export default function App() {
   return <Stack />;
 }
 ```
 
 ---
 
-## 🚨 Key Notes
-
-> ⚠️ **Important:** All timestamp fields (`created_at`, `updated_at`) used for syncing **must be `timestamptz`** in Supabase. This avoids timezone mismatch issues and ensures reliable sync.
+## 🚨 Important Notes
 
-- Supabase tables **must** include:
-
-  - `id`, `created_at`, `updated_at`, `deleted_at`
-  - Avoid null primary keys
-
-- To enable schema reflection, create this Supabase RPC:
+- Timestamp fields (`created_at`, `updated_at`, `deleted_at`) **must be `timestamptz`** in Supabase
+- Every synced table must have a valid `id`
+- Create this SQL function in Supabase to allow schema reflection:
 
 ```sql
 create or replace function get_table_schema(table_name text)
-returns table(
-  column_name text,
-  data_type text,
-  is_nullable text
-)
+returns table(column_name text, data_type text, is_nullable text)
 security definer
 as $$
-  select
-    column_name,
-    data_type,
-    is_nullable
+  select column_name, data_type, is_nullable
   from information_schema.columns
-  where table_schema = 'public'
-    and table_name = $1;
+  where table_schema = 'public' and table_name = $1;
 $$ language sql;
 
 grant execute on function get_table_schema(text) to anon, authenticated;
@@ -134,130 +124,99 @@ grant execute on function get_table_schema(text) to anon, authenticated;
 
 ---
 
-## 🧪 Basic Usage
-
-### `useSupatashData` hook
+## 🧪 Example: `useSupatashData`
 
-```ts
+```tsx
 import { useSupatashData } from "supastash";
 
-type Order = {
-  id: string;
-  user_id: string;
-  deleted_at: string | null;
-  updated_at: string;
-  created_at: string;
-};
+const { data, dataMap } = useSupatashData("orders");
+```
 
-const { data: orders, dataMap: ordersMap } = useSupatashData<Order>("orders");
+Filtered by user:
 
-// Filtered
+```tsx
 const { userId } = useAuth();
-const { data: userOrders } = useSupatashData<Order>("orders", {
+const { data: userOrders } = useSupatashData("orders", {
   filter: { column: "user_id", operator: "eq", value: userId },
   shouldFetch: !!userId,
 });
 ```
 
-### `useSupatash`
+Ensure sync engine is ready:
 
-```ts
+```tsx
 import { useSupatash } from "supastash";
 
 const { dbReady } = useSupatash();
 if (!dbReady) return null;
-return <Stack />;
 ```
 
 ---
 
-## 📘 API Overview
-
-### `configureSupastash(config)`
-
-Initialize sync system.
-
-### `useSupatashData(table, options)`
+## 🔧 API Overview
 
-Access data with local cache, syncing, filtering, etc.
-
-Returns:
-
-```ts
-{
-  data: R[];
-  dataMap: Map<string, R>;
-  trigger: () => void;
-  cancel: () => void;
-}
-```
-
-### `refreshTable(table: string)` / `refreshAllTables()`
-
-Force-refresh any or all table data.
+- [`configureSupastash()`](https://0xzekea.github.io/supastash/docs/configuration)) – setup + schema
+- [`useSupatashData()`](https://0xzekea.github.io/supastash/docs/data-access)) – read/write synced local data
 
 ---
 
-## 🔄 Sync Internals
+## 🔄 How Sync Works
 
-- Safe writes with `created_at`, `updated_at`, `deleted_at`
-- Retries with **exponential backoff**
-- Batched inserts, updates, deletes
-- Real-time changes are applied directly to local cache
+- Tracks changes with `created_at`, `updated_at`, `deleted_at`
+- Retries failed syncs with exponential backoff
+- Batches realtime + manual changes efficiently
+- Keeps local cache as the main source of truth
 
 ---
 
-### Sync Modes (per-query control)
-
-You can control how each query syncs:
-
-- `localOnly`: Use only local data
-- `remoteOnly`: Fetch directly from Supabase
-- `localFirst` _(default)_: Read/write locally, then sync to Supabase
-- `remoteFirst`: Write to Supabase first, then update local
+## 🧩 Sync Modes (via query builder)
 
-Use `.syncMode("...")` or `{ viewRemoteResult: true }` in `.run()` to control behavior.
+```ts
+supastash
+  .from("orders")
+  .select("*")
+  .syncMode("remoteOnly") // or localOnly, localFirst, remoteFirst
+  .run();
+```
 
 ---
 
-## 📁 Project Structure
+## 🗂 Example Project Structure
 
 ```
 src/
-  ├─ core/         # Supabase + sync logic
-  ├─ hooks/        # Main React hooks
+  ├─ core/         # Config
+  ├─ hooks/        # Custom hooks
   ├─ types/        # Type definitions
-  ├─ utils/        # Helper utilities
+  ├─ utils/        # Helpers
 ```
 
 ---
 
-## 🔧 Testing
+## 🧪 Testing & Dev
 
 ```bash
+# Run tests
 yarn test
-```
 
-Uses `vitest` for unit testing.
+# Start local dev build
+yarn dev
+```
 
 ---
 
 ## 🤝 Contributing
 
-```bash
-yarn dev
-```
-
-Open a PR with tests and typed signatures. PRs welcome.
+PRs welcome! Please include tests and type signatures.
 
 ---
 
 ## 📜 License
 
-MIT License © Ezekiel Akpan
+MIT © Ezekiel Akpan
 
 ---
 
 ## 💬 Questions?
 
-Open an issue or reach out on [X @0xZekeA](https://x.com/0xZekeA)
+Open an issue or reach out on [X (Twitter) @0xZekeA](https://x.com/0xZekeA)

package/dist/hooks/supastashData/addPayloadToUI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"addPayloadToUI.d.ts","sourceRoot":"","sources":["../../../src/hooks/supastashData/addPayloadToUI.ts"],"names":[],"mappings":"AAoBA,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,GAAG,GAAG,GAAG,EAAE,EACpB,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAC9D,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EACxD,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,QAoBrD"}
+{"version":3,"file":"addPayloadToUI.d.ts","sourceRoot":"","sources":["../../../src/hooks/supastashData/addPayloadToUI.ts"],"names":[],"mappings":"AAsBA,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,GAAG,GAAG,GAAG,EAAE,EACpB,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAC9D,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EACxD,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,QAoBrD"}

package/dist/hooks/supastashData/addPayloadToUI.js

@@ -1,3 +1,4 @@
+// Deprecated
 const versionMap = new Map();
 function getNewVersion(table, setter) {
     if (versionMap.get(table)) {

package/dist/hooks/supastashData/dataState.d.ts

@@ -1,8 +1,7 @@
-declare function useDataState<R = any>(table: string): {
+declare function useDataState<R, T>(table: string): {
     dataMap: Map<string, R>;
-    setDataMap: import("react").Dispatch<import("react").SetStateAction<Map<string, R>>>;
-    version: string;
-    setVersion: import("react").Dispatch<import("react").SetStateAction<string>>;
+    data: Array<R>;
+    groupedBy?: { [K in keyof T]: Map<T[K], Array<R>>; };
 };
 export default useDataState;
 //# sourceMappingURL=dataState.d.ts.map

package/dist/hooks/supastashData/dataState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataState.d.ts","sourceRoot":"","sources":["../../../src/hooks/supastashData/dataState.ts"],"names":[],"mappings":"AAEA,iBAAS,YAAY,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM;;;;;EAI3C;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"dataState.d.ts","sourceRoot":"","sources":["../../../src/hooks/supastashData/dataState.ts"],"names":[],"mappings":"AAGA,iBAAS,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAQ4B;IACjE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACxB,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACf,SAAS,CAAC,EAAE,GACT,CAAC,IAAI,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,GACpC,CAAC;CACH,CACF;AAED,eAAe,YAAY,CAAC"}

package/dist/hooks/supastashData/dataState.js

@@ -1,7 +1,8 @@
-import { useState } from "react";
+import { useCallback, useSyncExternalStore } from "react";
+import { getSnapshot, subscribe } from "../../utils/fetchData/snapShot";
 function useDataState(table) {
-    const [version, setVersion] = useState(`${table}-${Date.now()}`);
-    const [dataMap, setDataMap] = useState(new Map());
-    return { dataMap, setDataMap, version, setVersion };
+    const stableSubscribe = useCallback((cb) => subscribe(table, cb), [table]);
+    const getStableSnapshot = useCallback(() => getSnapshot(table), [table]);
+    return useSyncExternalStore(stableSubscribe, getStableSnapshot);
 }
 export default useDataState;

package/dist/hooks/supastashData/eventQueues.d.ts

@@ -1,5 +1,5 @@
 import { PayloadData } from "../../types/query.types";
 import { RealtimeOptions } from "../../types/realtimeData.types";
-declare function useEventQueues(table: string, setDataMap: React.Dispatch<React.SetStateAction<Map<string, any>>>, setVersion: React.Dispatch<React.SetStateAction<string>>, options: RealtimeOptions, flushIntervalMs: number): (eventType: string, data: PayloadData) => void;
+declare function useEventQueues<R>(table: string, options: RealtimeOptions<R>, flushIntervalMs: number): (eventType: string, data: PayloadData) => void;
 export default useEventQueues;
 //# sourceMappingURL=eventQueues.d.ts.map

package/dist/hooks/supastashData/eventQueues.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eventQueues.d.ts","sourceRoot":"","sources":["../../../src/hooks/supastashData/eventQueues.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAKjE,iBAAS,cAAc,CACrB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAClE,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EACxD,OAAO,EAAE,eAAe,EACxB,eAAe,EAAE,MAAM,eA6CU,MAAM,QAAQ,WAAW,UAgB3D;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"eventQueues.d.ts","sourceRoot":"","sources":["../../../src/hooks/supastashData/eventQueues.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAKjE,iBAAS,cAAc,CAAC,CAAC,EACvB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAC3B,eAAe,EAAE,MAAM,eA8CU,MAAM,QAAQ,WAAW,UAgB3D;AAED,eAAe,cAAc,CAAC"}

package/dist/hooks/supastashData/eventQueues.js

@@ -2,7 +2,7 @@ import { useRef } from "react";
 import { deleteData } from "../../utils/fetchData/deleteData";
 import { receiveData } from "../../utils/fetchData/receiveData";
 import useDataState from "./dataState";
-function useEventQueues(table, setDataMap, setVersion, options, flushIntervalMs) {
+function useEventQueues(table, options, flushIntervalMs) {
     const { dataMap } = useDataState(table);
     const insertQueue = useRef([]);
     const updateQueue = useRef([]);
@@ -11,15 +11,13 @@ function useEventQueues(table, setDataMap, setVersion, options, flushIntervalMs)
     const flush = () => {
         if (options.shouldFetch) {
             insertQueue.current.forEach((item) => {
-                receiveData(item, table, setDataMap, setVersion, options.shouldFetch);
-                options.onInsertAndUpdate?.(item) || options.onInsert?.(item);
+                receiveData(item, table, options.shouldFetch, options.onInsertAndUpdate || options.onInsert);
             });
             updateQueue.current.forEach((item) => {
-                receiveData(item, table, setDataMap, setVersion, options.shouldFetch);
-                options.onInsertAndUpdate?.(item) || options.onUpdate?.(item);
+                receiveData(item, table, options.shouldFetch, options.onInsertAndUpdate || options.onInsert);
             });
             deleteQueue.current.forEach((item) => {
-                deleteData(item, table, setDataMap, setVersion, dataMap, options.shouldFetch);
+                deleteData(item, table, options.shouldFetch);
                 options.onDelete?.(item);
             });
             insertQueue.current = [];

package/dist/hooks/supastashData/fetchCalls.d.ts

@@ -1,9 +1,8 @@
 import { RealtimeOptions } from "../../types/realtimeData.types";
-export declare function fetchCalls(table: string, setDataMap: React.Dispatch<React.SetStateAction<Map<string, any>>>, setVersion: React.Dispatch<React.SetStateAction<string>>, options: RealtimeOptions, initialized: React.RefObject<boolean>): {
+export declare function fetchCalls<R>(table: string, options: RealtimeOptions<R>, initialized: React.RefObject<boolean>): {
     triggerRefresh: () => Promise<void>;
     trigger: () => void;
     cancel: () => void;
     initialFetchAndSync: () => Promise<void>;
-    pushToUI: (payload: any | any[], operation: "insert" | "update" | "delete" | "upsert") => Promise<void>;
 };
 //# sourceMappingURL=fetchCalls.d.ts.map

package/dist/hooks/supastashData/fetchCalls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetchCalls.d.ts","sourceRoot":"","sources":["../../../src/hooks/supastashData/fetchCalls.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AASjE,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAClE,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EACxD,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC;;;;;wBA2E1B,GAAG,GAAG,GAAG,EAAE,aACT,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ;EAYvD"}
+{"version":3,"file":"fetchCalls.d.ts","sourceRoot":"","sources":["../../../src/hooks/supastashData/fetchCalls.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAQjE,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAC3B,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC;;;;;EAkFtC"}

package/dist/hooks/supastashData/fetchCalls.js

@@ -4,11 +4,10 @@ import { tableFilters } from "../../store/tableFilters";
 import { fetchLocalData } from "../../utils/fetchData/fetchLocalData";
 import { initialFetch } from "../../utils/fetchData/initialFetch";
 import log from "../../utils/logs";
-import { addPayloadToUI } from "./addPayloadToUI";
 const timesFetched = new Map();
 let lastFetched = new Map();
-export function fetchCalls(table, setDataMap, setVersion, options, initialized) {
-    const { shouldFetch = true, limit, filter, onPushToRemote, onInsertAndUpdate, useFilterWhileSyncing = true, } = options;
+export function fetchCalls(table, options, initialized) {
+    const { shouldFetch = true, limit, filter, onPushToRemote, onInsertAndUpdate, useFilterWhileSyncing = true, extraMapKeys, daylength, } = options;
     const cancelled = useRef(false);
     useEffect(() => {
         if (filter && useFilterWhileSyncing && !tableFilters.get(table)) {
@@ -29,7 +28,7 @@ export function fetchCalls(table, setDataMap, setVersion, options, initialized)
     }, []);
     const fetch = async () => {
         if (!cancelled.current) {
-            await fetchLocalData(table, setDataMap, setVersion, shouldFetch, limit);
+            await fetchLocalData(table, shouldFetch, limit, extraMapKeys, daylength);
         }
     };
     const trigger = () => {
@@ -63,14 +62,10 @@ export function fetchCalls(table, setDataMap, setVersion, options, initialized)
             console.error(`[Supastash] Error on initial fetch for ${table}`, error);
         }
     };
-    const pushToUI = async (payload, operation) => {
-        addPayloadToUI(table, payload, setDataMap, setVersion, operation);
-    };
     return {
         triggerRefresh,
         trigger,
         cancel,
         initialFetchAndSync,
-        pushToUI,
     };
 }

package/dist/hooks/supastashData/index.d.ts

@@ -1,53 +1,56 @@
 import { RealtimeOptions, SupastashDataResult } from "../../types/realtimeData.types";
 /**
  * @description
- * React hook to sync and subscribe to local-first data from a Supabase table.
+ * React hook to sync and subscribe to local-first data from a Supabase table using Supastash.
  *
- * - Fetches initial data from a local SQLite table using Supastash.
- * - Subscribes to Supabase `postgres_changes` for INSERT, UPDATE, DELETE events.
- * - Batches updates and applies them to local state at controlled intervals.
- * - Supports optional callbacks for reacting to specific event types.
- * - Lazy loading and manual triggers are supported for better control in UI flows.
+ * This hook:
+ * - Fetches initial data from local SQLite (offline-first).
+ * - Optionally subscribes to Supabase `postgres_changes` for realtime updates.
+ * - Batches and flushes changes into state at a controlled interval.
+ * - Supports lazy loading, manual triggers, and event callbacks.
  *
  * @example
  * const authenticated = !!session?.user;
- *
  * const { data, dataMap, trigger, cancel } = useSupastashData("users", {
- *   filter: {
- *     column: "user_id",
- *     operator: "eq",
- *     value: 1,
- *   },
- *   shouldFetch: authenticated, // Only fetch if allowed
+ *   shouldFetch: authenticated,
+ *   filter: { column: "user_id", operator: "eq", value: 1 },
  *   flushIntervalMs: 200,
  *   onInsert: (user) => console.log("User added:", user),
- *   lazy: true, // Don't fetch or subscribe until trigger() is called
+ *   lazy: true,
  * });
  *
  * useEffect(() => {
- *   trigger(); // Manually start loading
+ *   trigger(); // manually start sync
  * }, []);
  *
- * @param table - The name of the table to subscribe to (must match the local table name).
- * @param options.shouldFetch - If true, loads data from the local DB on mount. Defaults to true.
- * @param options.filter - Optional structured filter for realtime subscription.
- * @param options.flushIntervalMs - Interval in ms to flush batched changes into state. Defaults to 100ms.
- * @param options.lazy - If true, disables auto-fetch. Use `trigger()` to manually start.
- * @param options.onInsert - Optional callback triggered on INSERT events.
- * @param options.onUpdate - Optional callback triggered on UPDATE events.
- * @param options.onDelete - Optional callback triggered on DELETE events.
- * @param options.realtime - If true, subscribes to realtime changes. Defaults to true.
- * @param options.onInsertAndUpdate - Optional callback triggered on INSERT and UPDATE events.
- * @param options.onPushToRemote - Optional callback triggered on INSERT and UPDATE events.
- * @param options.onDelete - Optional callback triggered on DELETE events.
- * @param options.limit - Optional limit for the number of records to fetch initially. Defaults to 200.
- * @param options.useFilterWhileSyncing - If true, uses the filter while syncing. Defaults to true.
- *
- * @returns
- * - `data`: Array of local data, memoized by version.
- * - `dataMap`: Map of data keyed by ID.
- * - `trigger`: Starts fetch and subscription (used with `lazy: true`).
- * - `cancel`: Cancels a pending fetch or blocks lazy init.
+ * @param table - The table name (must match local SQLite table).
+ * @param options - Configuration object:
+ *
+ * ### Fetch Options:
+ * @param options.shouldFetch - If `false`, prevents initial fetch. Defaults to `true`.
+ * @param options.lazy - If `true`, disables auto-fetch. Call `trigger()` manually.
+ * @param options.limit - Max number of records to load from local DB. Defaults to `200`.
+ * @param options.useFilterWhileSyncing - If `true`, applies filter while syncing. Defaults to `true`.
+ * @param options.extraMapKey - Field to additionally group data by (`groupedBy`).
+ *
+ * ### Realtime Options:
+ * @param options.realtime - If `true`, subscribes to Supabase realtime. Defaults to `true`.
+ * @param options.filter - Structured filter (column, operator, value) for realtime subscription.
+ * @param options.flushIntervalMs - How often (ms) to apply batched changes to UI. Defaults to `100`.
+ *
+ * ### Event Callbacks:
+ * @param options.onInsert - Triggered on INSERT event.
+ * @param options.onUpdate - Triggered on UPDATE event.
+ * @param options.onDelete - Triggered on DELETE event.
+ * @param options.onInsertAndUpdate - Triggered on both INSERT and UPDATE.
+ * @param options.onPushToRemote - Called when a record is pushed to Supabase.
+ *
+ * @returns Object with:
+ * - `data`: Array of records.
+ * - `dataMap`: Map of records keyed by ID.
+ * - `groupedBy`: Optional maps grouped by fields (like `chat_id`).
+ * - `trigger()`: Manually start sync (used with lazy).
+ * - `cancel()`: Cancel a pending or lazy fetch.
  */
 export declare function useSupastashData<R = any>(table: string, options?: RealtimeOptions): SupastashDataResult<R>;
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/supastashData/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/supastashData/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,eAAe,EACf,mBAAmB,EACpB,MAAM,gCAAgC,CAAC;AAWxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EACtC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,GAC5B,mBAAmB,CAAC,CAAC,CAAC,CAwDxB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/supastashData/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,eAAe,EACf,mBAAmB,EACpB,MAAM,gCAAgC,CAAC;AAWxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EACtC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAoB,GAC5B,mBAAmB,CAAC,CAAC,CAAC,CA2ExB"}