async-storage-sync 1.0.3 → 1.0.5

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,7 +63,7 @@ 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.flushWithResult()` → sync all pending and return summary counts
   - `store.sync(collection)` → sync one collection
   - `store.syncById(collection, id)` → sync one record
 - Sync destination is controlled by your config: `serverUrl + endpoint`.
@@ -86,7 +87,7 @@ 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.flushWithResult()` | Sync all pending and return detailed summary (`attempted`, `synced`, `failed`, `retried`, `remainingPending`, `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 |
@@ -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

@@ -4,9 +4,7 @@ type DuplicateStrategy = 'append' | 'overwrite';
 interface InitConfig {
     driver: DriverName;
     serverUrl: string;
-    credentials: {
-        apiKey: string;
-    };
+    credentials: Record<string, 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
@@ -44,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;
@@ -65,7 +82,7 @@ declare class AsyncStorageSync {
     deleteCollection(name: string): Promise<void>;
     sync(name: string): Promise<void>;
     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.
@@ -101,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

@@ -4,9 +4,7 @@ type DuplicateStrategy = 'append' | 'overwrite';
 interface InitConfig {
     driver: DriverName;
     serverUrl: string;
-    credentials: {
-        apiKey: string;
-    };
+    credentials: Record<string, 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
@@ -44,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;
@@ -65,7 +82,7 @@ declare class AsyncStorageSync {
     deleteCollection(name: string): Promise<void>;
     sync(name: string): Promise<void>;
     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.
@@ -101,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

@@ -155,6 +155,15 @@ var Queue = class {
 // src/core/sync-engine.ts
 var DEBOUNCE_MS = 500;
 var BACKOFF_BASE_MS = 1e3;
+function buildAuthHeaders(credentials) {
+  const headers = { ...credentials };
+  const apiKey = headers.apiKey;
+  if (apiKey && !headers.Authorization && !headers.authorization) {
+    headers.Authorization = `Bearer ${apiKey}`;
+  }
+  delete headers.apiKey;
+  return headers;
+}
 var SyncEngine = class {
   constructor(config, queue, driver) {
     this.config = config;
@@ -212,25 +221,62 @@ 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;
     }
@@ -253,7 +299,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 {
@@ -265,20 +316,54 @@ var SyncEngine = class {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${this.config.credentials.apiKey}`
+          ...buildAuthHeaders(this.config.credentials)
         },
         body: JSON.stringify(body)
       });
       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) {
@@ -477,8 +562,8 @@ var _AsyncStorageSync = class _AsyncStorageSync {
   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

@@ -133,6 +133,15 @@ var Queue = class {
 // src/core/sync-engine.ts
 var DEBOUNCE_MS = 500;
 var BACKOFF_BASE_MS = 1e3;
+function buildAuthHeaders(credentials) {
+  const headers = { ...credentials };
+  const apiKey = headers.apiKey;
+  if (apiKey && !headers.Authorization && !headers.authorization) {
+    headers.Authorization = `Bearer ${apiKey}`;
+  }
+  delete headers.apiKey;
+  return headers;
+}
 var SyncEngine = class {
   constructor(config, queue, driver) {
     this.config = config;
@@ -190,25 +199,62 @@ 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;
     }
@@ -231,7 +277,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 {
@@ -243,20 +294,54 @@ var SyncEngine = class {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${this.config.credentials.apiKey}`
+          ...buildAuthHeaders(this.config.credentials)
         },
         body: JSON.stringify(body)
       });
       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) {
@@ -455,8 +540,8 @@ var _AsyncStorageSync = class _AsyncStorageSync {
   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.3",
+  "version": "1.0.5",
   "description": "Offline-first data layer for React Native with local-first storage and automatic sync",
   "main": "dist/index.js",
   "module": "dist/index.mjs",