async-storage-sync 1.0.4 → 1.0.6

package/README.md

@@ -48,8 +48,9 @@ await store.save('forms', {
   timestamp: new Date().toISOString() 
 });
 
-// Sync all pending records to server
-await store.flush();
+// Sync and get summary result
+const result = await store.flushWithResult();
+console.log(`Synced: ${result.synced}, Failed: ${result.failed}, Remaining: ${result.remainingPending}`);
 
 // List pending records
 const pending = await store.getAll('forms');
@@ -62,8 +63,8 @@ console.log(`${pending.length} forms waiting to sync`);
 - `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.flushWithResult()` → sync all pending and return summary counts
+  - `store.syncWithResult(collection)` → sync one collection and return summary counts
   - `store.syncById(collection, id)` → sync one record
 - Sync destination is controlled by your config: `serverUrl + endpoint`.
 
@@ -86,8 +87,8 @@ console.log(`${pending.length} forms waiting to sync`);
 | `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.flushWithResult()` | Sync all pending and return detailed summary (`attempted`, `synced`, `failed`, `retried`, `remainingPending`, `items`) |
+| `store.syncWithResult(collection)` | Sync collection and return detailed summary (same format as `flushWithResult()`) |
 | `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 |
@@ -105,7 +106,7 @@ import { getSyncQueue } from 'async-storage-sync';
 
 NetInfo.addEventListener(state => {
   if (state.isConnected) {
-    void getSyncQueue().flush();
+    void getSyncQueue().flushWithResult();
   }
 });
 ```
@@ -190,7 +191,7 @@ Notes:
 
 1. **Save** — Records written to AsyncStorage immediately
 2. **Queue** — Each save queued for syncing
-3. **Sync** — `flush()` POSTs all pending to your server
+3. **Sync** — `flushWithResult()` POSTs all pending to your server and returns summary output
 4. **Status** — Records marked synced, then kept or deleted
 5. **Retry** — Failed syncs retry automatically (max 5x)
 6. **Persist** — Everything survives app restart

package/dist/index.d.mts

@@ -42,6 +42,25 @@ interface SaveOptions {
     onSyncSuccess?: OnSyncSuccess;
     duplicateStrategy?: DuplicateStrategy;
 }
+type FlushItemStatus = 'synced' | 'failed' | 'retried' | 'deferred-backoff' | 'network-error';
+interface FlushItemResult {
+    itemId: string;
+    collection: string;
+    recordId: string;
+    status: FlushItemStatus;
+    httpStatus?: number;
+}
+interface FlushResult {
+    attempted: number;
+    synced: number;
+    failed: number;
+    retried: number;
+    deferred: number;
+    networkErrors: number;
+    remainingPending: number;
+    skippedAlreadyFlushing: boolean;
+    items: FlushItemResult[];
+}
 type SyncedCallback = (item: QueueItem) => void;
 type AuthErrorCallback = (statusCode: number, item: QueueItem) => void;
 type StorageFullCallback = () => void;
@@ -61,9 +80,9 @@ declare class AsyncStorageSync {
     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>;
+    syncWithResult(name: string): Promise<FlushResult>;
     syncById(_name: string, id: string): Promise<void>;
-    flush(): Promise<void>;
+    flushWithResult(): Promise<FlushResult>;
     /**
      * 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.
@@ -99,4 +118,4 @@ declare function getSyncQueue(): AsyncStorageSync;
  */
 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 };
+export { AsyncStorageSync, type AuthErrorCallback, type DriverName, type DuplicateStrategy, type FlushItemResult, type FlushItemStatus, type FlushResult, 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

@@ -42,6 +42,25 @@ interface SaveOptions {
     onSyncSuccess?: OnSyncSuccess;
     duplicateStrategy?: DuplicateStrategy;
 }
+type FlushItemStatus = 'synced' | 'failed' | 'retried' | 'deferred-backoff' | 'network-error';
+interface FlushItemResult {
+    itemId: string;
+    collection: string;
+    recordId: string;
+    status: FlushItemStatus;
+    httpStatus?: number;
+}
+interface FlushResult {
+    attempted: number;
+    synced: number;
+    failed: number;
+    retried: number;
+    deferred: number;
+    networkErrors: number;
+    remainingPending: number;
+    skippedAlreadyFlushing: boolean;
+    items: FlushItemResult[];
+}
 type SyncedCallback = (item: QueueItem) => void;
 type AuthErrorCallback = (statusCode: number, item: QueueItem) => void;
 type StorageFullCallback = () => void;
@@ -61,9 +80,9 @@ declare class AsyncStorageSync {
     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>;
+    syncWithResult(name: string): Promise<FlushResult>;
     syncById(_name: string, id: string): Promise<void>;
-    flush(): Promise<void>;
+    flushWithResult(): Promise<FlushResult>;
     /**
      * 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.
@@ -99,4 +118,4 @@ declare function getSyncQueue(): AsyncStorageSync;
  */
 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 };
+export { AsyncStorageSync, type AuthErrorCallback, type DriverName, type DuplicateStrategy, type FlushItemResult, type FlushItemStatus, type FlushResult, type InitConfig, type OnSyncSuccess, type QueueItem, type RecordMeta, type SaveOptions, type StorageFullCallback, type StoredRecord, type SyncStatus, type SyncedCallback, getSyncQueue, initSyncQueue, setStorageDriver };

package/dist/index.js

@@ -221,34 +221,101 @@ var SyncEngine = class {
       clearTimeout(this.debounceTimer);
     }
     this.debounceTimer = setTimeout(() => {
-      void this.flush();
+      void this.flushWithResult();
     }, DEBOUNCE_MS);
   }
-  async flush() {
+  async flushWithResult() {
     if (this.isFlushing) {
       console.log("[SyncEngine] flush() skipped \u2014 already flushing");
-      return;
+      return {
+        attempted: 0,
+        synced: 0,
+        failed: 0,
+        retried: 0,
+        deferred: 0,
+        networkErrors: 0,
+        remainingPending: this.queue.getPending().length,
+        skippedAlreadyFlushing: true,
+        items: []
+      };
     }
     this.isFlushing = true;
+    const result = {
+      attempted: 0,
+      synced: 0,
+      failed: 0,
+      retried: 0,
+      deferred: 0,
+      networkErrors: 0,
+      remainingPending: 0,
+      skippedAlreadyFlushing: false,
+      items: []
+    };
     try {
       const pending = this.queue.getPending();
       console.log("[SyncEngine] flush() \u2014 pending items:", pending.length);
       if (pending.length === 0) {
         console.log("[SyncEngine] Nothing to sync.");
-        return;
+        result.remainingPending = 0;
+        return result;
       }
       for (const item of pending) {
-        await this.syncItem(item);
+        result.attempted += 1;
+        const itemResult = await this.syncItem(item);
+        result.items.push(itemResult);
+        if (itemResult.status === "synced") {
+          result.synced += 1;
+        } else if (itemResult.status === "failed") {
+          result.failed += 1;
+        } else if (itemResult.status === "retried") {
+          result.retried += 1;
+        } else if (itemResult.status === "deferred-backoff") {
+          result.deferred += 1;
+        } else if (itemResult.status === "network-error") {
+          result.networkErrors += 1;
+        }
       }
+      result.remainingPending = this.queue.getPending().length;
+      return result;
     } finally {
       this.isFlushing = false;
     }
   }
-  async flushCollection(collectionName) {
+  async flushCollectionWithResult(collectionName) {
+    const result = {
+      attempted: 0,
+      synced: 0,
+      failed: 0,
+      retried: 0,
+      deferred: 0,
+      networkErrors: 0,
+      remainingPending: 0,
+      skippedAlreadyFlushing: false,
+      items: []
+    };
     const pending = this.queue.getPendingForCollection(collectionName);
+    if (pending.length === 0) {
+      result.remainingPending = this.queue.getPendingForCollection(collectionName).length;
+      return result;
+    }
     for (const item of pending) {
-      await this.syncItem(item);
+      result.attempted += 1;
+      const itemResult = await this.syncItem(item);
+      result.items.push(itemResult);
+      if (itemResult.status === "synced") {
+        result.synced += 1;
+      } else if (itemResult.status === "failed") {
+        result.failed += 1;
+      } else if (itemResult.status === "retried") {
+        result.retried += 1;
+      } else if (itemResult.status === "deferred-backoff") {
+        result.deferred += 1;
+      } else if (itemResult.status === "network-error") {
+        result.networkErrors += 1;
+      }
     }
+    result.remainingPending = this.queue.getPendingForCollection(collectionName).length;
+    return result;
   }
   async flushRecord(recordId) {
     const item = this.queue.getPendingForRecord(recordId);
@@ -262,7 +329,12 @@ var SyncEngine = class {
       const elapsed = Date.now() - item.ts;
       if (elapsed < backoffMs) {
         console.log(`[SyncEngine] syncItem backoff \u2014 retries: ${item.retries}, wait: ${backoffMs - elapsed}ms remaining`);
-        return;
+        return {
+          itemId: item.id,
+          collection: item.key,
+          recordId: item.recordId,
+          status: "deferred-backoff"
+        };
       }
     }
     try {
@@ -281,13 +353,47 @@ var SyncEngine = class {
       console.log(`[SyncEngine] Response: ${response.status} ${response.statusText}`);
       if (response.ok) {
         await this.handleSuccess(item);
+        return {
+          itemId: item.id,
+          collection: item.key,
+          recordId: item.recordId,
+          status: "synced",
+          httpStatus: response.status
+        };
       } else if (response.status >= 400 && response.status < 500) {
         await this.handleClientError(item, response.status);
+        return {
+          itemId: item.id,
+          collection: item.key,
+          recordId: item.recordId,
+          status: "failed",
+          httpStatus: response.status
+        };
       } else if (response.status >= 500) {
         await this.handleServerError(item);
+        return {
+          itemId: item.id,
+          collection: item.key,
+          recordId: item.recordId,
+          status: "retried",
+          httpStatus: response.status
+        };
       }
+      return {
+        itemId: item.id,
+        collection: item.key,
+        recordId: item.recordId,
+        status: "failed",
+        httpStatus: response.status
+      };
     } catch (e) {
       console.warn("[SyncEngine] \u{1F50C} Network error (offline?) \u2014 will retry on next flush:", e);
+      return {
+        itemId: item.id,
+        collection: item.key,
+        recordId: item.recordId,
+        status: "network-error"
+      };
     }
   }
   async handleSuccess(item) {
@@ -480,14 +586,14 @@ var _AsyncStorageSync = class _AsyncStorageSync {
   async deleteCollection(name) {
     await this.driver.remove(collectionKey(name));
   }
-  async sync(name) {
-    await this.engine.flushCollection(name);
+  async syncWithResult(name) {
+    return this.engine.flushCollectionWithResult(name);
   }
   async syncById(_name, id) {
     await this.engine.flushRecord(id);
   }
-  async flush() {
-    await this.engine.flush();
+  async flushWithResult() {
+    return this.engine.flushWithResult();
   }
   /**
    * Re-enqueue any records marked as 'failed' so they are retried on next flush.

package/dist/index.mjs

@@ -199,34 +199,101 @@ var SyncEngine = class {
       clearTimeout(this.debounceTimer);
     }
     this.debounceTimer = setTimeout(() => {
-      void this.flush();
+      void this.flushWithResult();
     }, DEBOUNCE_MS);
   }
-  async flush() {
+  async flushWithResult() {
     if (this.isFlushing) {
       console.log("[SyncEngine] flush() skipped \u2014 already flushing");
-      return;
+      return {
+        attempted: 0,
+        synced: 0,
+        failed: 0,
+        retried: 0,
+        deferred: 0,
+        networkErrors: 0,
+        remainingPending: this.queue.getPending().length,
+        skippedAlreadyFlushing: true,
+        items: []
+      };
     }
     this.isFlushing = true;
+    const result = {
+      attempted: 0,
+      synced: 0,
+      failed: 0,
+      retried: 0,
+      deferred: 0,
+      networkErrors: 0,
+      remainingPending: 0,
+      skippedAlreadyFlushing: false,
+      items: []
+    };
     try {
       const pending = this.queue.getPending();
       console.log("[SyncEngine] flush() \u2014 pending items:", pending.length);
       if (pending.length === 0) {
         console.log("[SyncEngine] Nothing to sync.");
-        return;
+        result.remainingPending = 0;
+        return result;
       }
       for (const item of pending) {
-        await this.syncItem(item);
+        result.attempted += 1;
+        const itemResult = await this.syncItem(item);
+        result.items.push(itemResult);
+        if (itemResult.status === "synced") {
+          result.synced += 1;
+        } else if (itemResult.status === "failed") {
+          result.failed += 1;
+        } else if (itemResult.status === "retried") {
+          result.retried += 1;
+        } else if (itemResult.status === "deferred-backoff") {
+          result.deferred += 1;
+        } else if (itemResult.status === "network-error") {
+          result.networkErrors += 1;
+        }
       }
+      result.remainingPending = this.queue.getPending().length;
+      return result;
     } finally {
       this.isFlushing = false;
     }
   }
-  async flushCollection(collectionName) {
+  async flushCollectionWithResult(collectionName) {
+    const result = {
+      attempted: 0,
+      synced: 0,
+      failed: 0,
+      retried: 0,
+      deferred: 0,
+      networkErrors: 0,
+      remainingPending: 0,
+      skippedAlreadyFlushing: false,
+      items: []
+    };
     const pending = this.queue.getPendingForCollection(collectionName);
+    if (pending.length === 0) {
+      result.remainingPending = this.queue.getPendingForCollection(collectionName).length;
+      return result;
+    }
     for (const item of pending) {
-      await this.syncItem(item);
+      result.attempted += 1;
+      const itemResult = await this.syncItem(item);
+      result.items.push(itemResult);
+      if (itemResult.status === "synced") {
+        result.synced += 1;
+      } else if (itemResult.status === "failed") {
+        result.failed += 1;
+      } else if (itemResult.status === "retried") {
+        result.retried += 1;
+      } else if (itemResult.status === "deferred-backoff") {
+        result.deferred += 1;
+      } else if (itemResult.status === "network-error") {
+        result.networkErrors += 1;
+      }
     }
+    result.remainingPending = this.queue.getPendingForCollection(collectionName).length;
+    return result;
   }
   async flushRecord(recordId) {
     const item = this.queue.getPendingForRecord(recordId);
@@ -240,7 +307,12 @@ var SyncEngine = class {
       const elapsed = Date.now() - item.ts;
       if (elapsed < backoffMs) {
         console.log(`[SyncEngine] syncItem backoff \u2014 retries: ${item.retries}, wait: ${backoffMs - elapsed}ms remaining`);
-        return;
+        return {
+          itemId: item.id,
+          collection: item.key,
+          recordId: item.recordId,
+          status: "deferred-backoff"
+        };
       }
     }
     try {
@@ -259,13 +331,47 @@ var SyncEngine = class {
       console.log(`[SyncEngine] Response: ${response.status} ${response.statusText}`);
       if (response.ok) {
         await this.handleSuccess(item);
+        return {
+          itemId: item.id,
+          collection: item.key,
+          recordId: item.recordId,
+          status: "synced",
+          httpStatus: response.status
+        };
       } else if (response.status >= 400 && response.status < 500) {
         await this.handleClientError(item, response.status);
+        return {
+          itemId: item.id,
+          collection: item.key,
+          recordId: item.recordId,
+          status: "failed",
+          httpStatus: response.status
+        };
       } else if (response.status >= 500) {
         await this.handleServerError(item);
+        return {
+          itemId: item.id,
+          collection: item.key,
+          recordId: item.recordId,
+          status: "retried",
+          httpStatus: response.status
+        };
       }
+      return {
+        itemId: item.id,
+        collection: item.key,
+        recordId: item.recordId,
+        status: "failed",
+        httpStatus: response.status
+      };
     } catch (e) {
       console.warn("[SyncEngine] \u{1F50C} Network error (offline?) \u2014 will retry on next flush:", e);
+      return {
+        itemId: item.id,
+        collection: item.key,
+        recordId: item.recordId,
+        status: "network-error"
+      };
     }
   }
   async handleSuccess(item) {
@@ -458,14 +564,14 @@ var _AsyncStorageSync = class _AsyncStorageSync {
   async deleteCollection(name) {
     await this.driver.remove(collectionKey(name));
   }
-  async sync(name) {
-    await this.engine.flushCollection(name);
+  async syncWithResult(name) {
+    return this.engine.flushCollectionWithResult(name);
   }
   async syncById(_name, id) {
     await this.engine.flushRecord(id);
   }
-  async flush() {
-    await this.engine.flush();
+  async flushWithResult() {
+    return this.engine.flushWithResult();
   }
   /**
    * Re-enqueue any records marked as 'failed' so they are retried on next flush.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "async-storage-sync",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Offline-first data layer for React Native with local-first storage and automatic sync",
   "main": "dist/index.js",
   "module": "dist/index.mjs",