async-storage-sync 1.0.0

package/README.md

@@ -0,0 +1,198 @@
+# async-storage-sync
+
+**Offline-first data layer for React Native** — Save locally, sync when connected.
+
+## Install
+
+```bash
+npm install async-storage-sync @react-native-async-storage/async-storage @react-native-community/netinfo
+```
+
+`@react-native-async-storage/async-storage` and `@react-native-community/netinfo` are required peer dependencies used by this package.
+
+## 30-Second Start
+
+Initialize once in your app (no separate files required):
+
+```ts
+// App.tsx
+import React, { useEffect } from 'react';
+import { initSyncQueue } from 'async-storage-sync';
+
+export default function App() {
+  useEffect(() => {
+    void initSyncQueue({
+      driver: 'asyncstorage',
+      serverUrl: 'https://api.example.com',
+      credentials: { apiKey: 'YOUR_API_KEY' },
+      endpoint: '/submit',
+      autoSync: false,
+    });
+  }, []);
+
+  return <YourApp />;
+}
+```
+
+Now use it anywhere in your app:
+
+```ts
+import { getSyncQueue } from 'async-storage-sync';
+
+const store = getSyncQueue();
+
+// Save record (saved locally immediately)
+await store.save('forms', { 
+  formId: '123', 
+  name: 'John', 
+  timestamp: new Date().toISOString() 
+});
+
+// Sync all pending records to server
+await store.flush();
+
+// List pending records
+const pending = await store.getAll('forms');
+console.log(`${pending.length} forms waiting to sync`);
+```
+
+## Sync Behavior (Auto vs Manual)
+
+- `autoSync: true` (default): when the app starts, the package checks connectivity and attempts sync if online.
+- `autoSync: true` also listens for reconnect events and retries pending items automatically.
+- `autoSync: false`: no automatic syncing; call sync methods manually when you choose.
+- Manual methods:
+  - `store.flush()` → sync all pending items
+  - `store.sync(collection)` → sync one collection
+  - `store.syncById(collection, id)` → sync one record
+- Sync destination is controlled by your config: `serverUrl + endpoint`.
+
+## API Reference
+
+### Setup
+
+| Function | Purpose |
+|--------|---------|
+| `initSyncQueue(config)` | Initialize singleton once at app startup (safe to call repeatedly) |
+| `getSyncQueue()` | Get initialized singleton instance |
+| `setStorageDriver(storage)` | Inject storage client explicitly (useful for symlink/local package setups) |
+
+### Store Methods (`const store = getSyncQueue()`)
+
+| Method | Purpose |
+|--------|---------|
+| `store.save(collection, data, options?)` | Save one record locally and enqueue for sync |
+| `store.getAll(collection)` | Get all records from one collection |
+| `store.getById(collection, id)` | Get one record by internal `_id` |
+| `store.deleteById(collection, id)` | Delete one record by internal `_id` |
+| `store.deleteCollection(collection)` | Delete all records in one collection |
+| `store.flush()` | Sync all pending queue items |
+| `store.sync(collection)` | Sync pending items for one collection only |
+| `store.syncById(collection, id)` | Sync one specific record by internal `_id` |
+| `store.requeueFailed()` | Move `failed` records back to pending queue for retry |
+| `store.onSynced(callback)` | Event callback for successful sync of each item |
+| `store.onAuthError(callback)` | Event callback when sync returns `401` or `403` |
+| `store.onStorageFull(callback)` | Event callback when local storage is full on save |
+| `store.getQueue()` | Inspect in-memory queue items (debug/metrics) |
+| `store.destroy()` | Stop engine, clear queue/storage, and reset singleton |
+
+## Quick Examples
+
+**Auto-sync when internet reconnects:**
+```ts
+import NetInfo from '@react-native-community/netinfo';
+import { getSyncQueue } from 'async-storage-sync';
+
+NetInfo.addEventListener(state => {
+  if (state.isConnected) {
+    void getSyncQueue().flush();
+  }
+});
+```
+
+**Handle authentication errors:**
+```ts
+const store = getSyncQueue();
+
+store.onAuthError((statusCode, item) => {
+  if (statusCode === 401 || statusCode === 403) {
+    console.log('Session expired, re-login needed');
+  }
+});
+```
+
+**Transform data before sending to server:**
+```ts
+initSyncQueue({
+  driver: 'asyncstorage',
+  serverUrl: 'https://api.example.com',
+  credentials: { apiKey: 'KEY' },
+  endpoint: '/submit',
+  payloadTransformer: (record) => {
+    const { _id, _ts, _synced, _retries, ...payload } = record;
+    return payload;
+  },
+});
+```
+
+**Handle duplicates:**
+```ts
+// Keep all (default)
+await store.save('logs', { event: 'tap' });
+
+// Replace existing type
+await store.save('profile', { userId: 1, name: 'Bob' }, {
+  type: 'currentUser',
+  duplicateStrategy: 'overwrite',
+});
+```
+
+**Logout cleanup:**
+```ts
+const store = getSyncQueue();
+await store.deleteCollection('submissions');
+```
+
+## Configuration
+
+```ts
+initSyncQueue({
+  driver: 'asyncstorage',           // (required) only driver type
+  serverUrl: string,                // (required) API base URL
+  credentials: { apiKey: string },  // (required) auth
+  endpoint?: '/submit',             // route to POST data
+  autoSync?: false,                 // auto-sync on reconnect
+  onSyncSuccess?: 'keep',           // after sync: keep|delete|ttl
+  ttl?: 7 * 24 * 60 * 60 * 1000,   // if ttl mode, keep duration
+  duplicateStrategy?: 'append',     // append or overwrite
+  payloadTransformer?: (r) => r,    // optional: shape before send
+});
+```
+
+## How It Works
+
+1. **Save** — Records written to AsyncStorage immediately
+2. **Queue** — Each save queued for syncing
+3. **Sync** — `flush()` POSTs all pending to your server
+4. **Status** — Records marked synced, then kept or deleted
+5. **Retry** — Failed syncs retry automatically (max 5x)
+6. **Persist** — Everything survives app restart
+
+## Storage
+
+- `asyncstorage::<collectionName>` — Your records + metadata (`_id`, `_ts`, `_synced`, `_retries`)
+- `asyncstorage::__queue__` — Sync queue
+
+## Limits
+
+✅ Works: 100s-1000s of records, multiple collections, TypeScript support, app crashes  
+❌ Limits: Max 5 retries, not a full database, config locks after init
+
+## Production Checklist
+
+- [ ] Use `payloadTransformer` to remove `_` fields before server
+- [ ] Handle `onAuthError` for 401/403
+- [ ] Set `autoSync: false` if you control sync timing
+- [ ] Test with `NetInfo` reconnect listener
+- [ ] Call `deleteCollection()` on logout
+- [ ] Monitor queue with `getQueue()` for ops metrics

package/dist/index.d.mts

@@ -0,0 +1,104 @@
+type DriverName = 'asyncstorage';
+type OnSyncSuccess = 'keep' | 'delete' | 'ttl';
+type DuplicateStrategy = 'append' | 'overwrite';
+interface InitConfig {
+    driver: DriverName;
+    serverUrl: string;
+    credentials: {
+        apiKey: string;
+    };
+    /**
+     * Optional transform applied to the stored record before it is sent to the server.
+     * Use this to strip internal meta fields, rename keys, or reshape the payload
+     * to match your backend's expected schema.
+     * If omitted, the full stored record is sent as-is.
+     */
+    payloadTransformer?: (record: Record<string, unknown>) => Record<string, unknown>;
+    autoSync?: boolean;
+    endpoint?: string;
+    onSyncSuccess?: OnSyncSuccess;
+    ttl?: number;
+    duplicateStrategy?: DuplicateStrategy;
+}
+type SyncStatus = 'pending' | 'synced' | 'failed';
+interface RecordMeta {
+    _id: string;
+    _ts: number;
+    _synced: SyncStatus;
+    _type: string;
+    _retries: number;
+}
+type StoredRecord<T = Record<string, unknown>> = RecordMeta & T;
+interface QueueItem {
+    id: string;
+    key: string;
+    recordId: string;
+    payload: string;
+    endpoint: string;
+    ts: number;
+    retries: number;
+    synced: boolean;
+}
+interface SaveOptions {
+    type?: string;
+    onSyncSuccess?: OnSyncSuccess;
+    duplicateStrategy?: DuplicateStrategy;
+}
+type SyncedCallback = (item: QueueItem) => void;
+type AuthErrorCallback = (statusCode: number, item: QueueItem) => void;
+type StorageFullCallback = () => void;
+
+declare class AsyncStorageSync {
+    private readonly config;
+    private readonly driver;
+    private static instance;
+    private readonly queue;
+    private readonly engine;
+    private constructor();
+    static init(config: InitConfig): Promise<AsyncStorageSync>;
+    static getInstance(): AsyncStorageSync;
+    save<T extends Record<string, unknown>>(name: string, data: T, options?: SaveOptions): Promise<StoredRecord<T>>;
+    private enqueueRecord;
+    getAll<T extends Record<string, unknown>>(name: string): Promise<StoredRecord<T>[]>;
+    getById<T extends Record<string, unknown>>(name: string, id: string): Promise<StoredRecord<T> | null>;
+    deleteById(name: string, id: string): Promise<void>;
+    deleteCollection(name: string): Promise<void>;
+    sync(name: string): Promise<void>;
+    syncById(_name: string, id: string): Promise<void>;
+    flush(): Promise<void>;
+    /**
+     * Re-enqueue any records marked as 'failed' so they are retried on next flush.
+     * Called automatically on init to recover from previous 4xx/500 failures.
+     */
+    requeueFailed(): Promise<void>;
+    onSynced(cb: SyncedCallback): void;
+    onAuthError(cb: AuthErrorCallback): void;
+    onStorageFull(cb: StorageFullCallback): void;
+    getQueue(): QueueItem[];
+    destroy(): Promise<void>;
+    private getCollection;
+    private saveCollection;
+}
+
+type AsyncStorageClient = {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<readonly string[] | null>;
+    clear(): Promise<void>;
+};
+
+/**
+ * Initialize once at app startup (safe to call repeatedly).
+ */
+declare function initSyncQueue(config: InitConfig): Promise<AsyncStorageSync>;
+/**
+ * Get initialized singleton instance.
+ */
+declare function getSyncQueue(): AsyncStorageSync;
+/**
+ * Inject storage implementation explicitly (recommended for symlink/local package usage).
+ */
+declare function setStorageDriver(storage: AsyncStorageClient): void;
+
+export { AsyncStorageSync, type AuthErrorCallback, type DriverName, type DuplicateStrategy, type InitConfig, type OnSyncSuccess, type QueueItem, type RecordMeta, type SaveOptions, type StorageFullCallback, type StoredRecord, type SyncStatus, type SyncedCallback, getSyncQueue, initSyncQueue, setStorageDriver };

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+type DriverName = 'asyncstorage';
+type OnSyncSuccess = 'keep' | 'delete' | 'ttl';
+type DuplicateStrategy = 'append' | 'overwrite';
+interface InitConfig {
+    driver: DriverName;
+    serverUrl: string;
+    credentials: {
+        apiKey: string;
+    };
+    /**
+     * Optional transform applied to the stored record before it is sent to the server.
+     * Use this to strip internal meta fields, rename keys, or reshape the payload
+     * to match your backend's expected schema.
+     * If omitted, the full stored record is sent as-is.
+     */
+    payloadTransformer?: (record: Record<string, unknown>) => Record<string, unknown>;
+    autoSync?: boolean;
+    endpoint?: string;
+    onSyncSuccess?: OnSyncSuccess;
+    ttl?: number;
+    duplicateStrategy?: DuplicateStrategy;
+}
+type SyncStatus = 'pending' | 'synced' | 'failed';
+interface RecordMeta {
+    _id: string;
+    _ts: number;
+    _synced: SyncStatus;
+    _type: string;
+    _retries: number;
+}
+type StoredRecord<T = Record<string, unknown>> = RecordMeta & T;
+interface QueueItem {
+    id: string;
+    key: string;
+    recordId: string;
+    payload: string;
+    endpoint: string;
+    ts: number;
+    retries: number;
+    synced: boolean;
+}
+interface SaveOptions {
+    type?: string;
+    onSyncSuccess?: OnSyncSuccess;
+    duplicateStrategy?: DuplicateStrategy;
+}
+type SyncedCallback = (item: QueueItem) => void;
+type AuthErrorCallback = (statusCode: number, item: QueueItem) => void;
+type StorageFullCallback = () => void;
+
+declare class AsyncStorageSync {
+    private readonly config;
+    private readonly driver;
+    private static instance;
+    private readonly queue;
+    private readonly engine;
+    private constructor();
+    static init(config: InitConfig): Promise<AsyncStorageSync>;
+    static getInstance(): AsyncStorageSync;
+    save<T extends Record<string, unknown>>(name: string, data: T, options?: SaveOptions): Promise<StoredRecord<T>>;
+    private enqueueRecord;
+    getAll<T extends Record<string, unknown>>(name: string): Promise<StoredRecord<T>[]>;
+    getById<T extends Record<string, unknown>>(name: string, id: string): Promise<StoredRecord<T> | null>;
+    deleteById(name: string, id: string): Promise<void>;
+    deleteCollection(name: string): Promise<void>;
+    sync(name: string): Promise<void>;
+    syncById(_name: string, id: string): Promise<void>;
+    flush(): Promise<void>;
+    /**
+     * Re-enqueue any records marked as 'failed' so they are retried on next flush.
+     * Called automatically on init to recover from previous 4xx/500 failures.
+     */
+    requeueFailed(): Promise<void>;
+    onSynced(cb: SyncedCallback): void;
+    onAuthError(cb: AuthErrorCallback): void;
+    onStorageFull(cb: StorageFullCallback): void;
+    getQueue(): QueueItem[];
+    destroy(): Promise<void>;
+    private getCollection;
+    private saveCollection;
+}
+
+type AsyncStorageClient = {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<readonly string[] | null>;
+    clear(): Promise<void>;
+};
+
+/**
+ * Initialize once at app startup (safe to call repeatedly).
+ */
+declare function initSyncQueue(config: InitConfig): Promise<AsyncStorageSync>;
+/**
+ * Get initialized singleton instance.
+ */
+declare function getSyncQueue(): AsyncStorageSync;
+/**
+ * Inject storage implementation explicitly (recommended for symlink/local package usage).
+ */
+declare function setStorageDriver(storage: AsyncStorageClient): void;
+
+export { AsyncStorageSync, type AuthErrorCallback, type DriverName, type DuplicateStrategy, type InitConfig, type OnSyncSuccess, type QueueItem, type RecordMeta, type SaveOptions, type StorageFullCallback, type StoredRecord, type SyncStatus, type SyncedCallback, getSyncQueue, initSyncQueue, setStorageDriver };