async-storage-sync 1.0.0

package/dist/index.js

@@ -0,0 +1,575 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AsyncStorageSync: () => AsyncStorageSync,
+  getSyncQueue: () => getSyncQueue,
+  initSyncQueue: () => initSyncQueue,
+  setStorageDriver: () => setStorageDriver
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/drivers/AsyncStorageDriver.ts
+var _AsyncStorageDriver = class _AsyncStorageDriver {
+  static setStorageClient(storage) {
+    _AsyncStorageDriver.injectedStorage = storage;
+  }
+  constructor() {
+    if (_AsyncStorageDriver.injectedStorage) {
+      this.storage = _AsyncStorageDriver.injectedStorage;
+      return;
+    }
+    const injectedStorage = globalThis.__ASYNC_STORAGE__;
+    if (injectedStorage) {
+      this.storage = injectedStorage;
+      return;
+    }
+    try {
+      this.storage = require("@react-native-async-storage/async-storage").default;
+    } catch {
+      throw new Error(
+        "[async-storage-sync] AsyncStorageDriver requires @react-native-async-storage/async-storage."
+      );
+    }
+  }
+  async get(key) {
+    return this.storage.getItem(key);
+  }
+  async set(key, value) {
+    try {
+      await this.storage.setItem(key, value);
+    } catch (error) {
+      if (String(error).includes("quota") || String(error).includes("full")) {
+        throw new Error("STORAGE_FULL");
+      }
+      throw error;
+    }
+  }
+  async remove(key) {
+    await this.storage.removeItem(key);
+  }
+  async getAllKeys() {
+    const keys = await this.storage.getAllKeys();
+    return keys ? [...keys] : [];
+  }
+  async clear() {
+    await this.storage.clear();
+  }
+};
+_AsyncStorageDriver.injectedStorage = null;
+var AsyncStorageDriver = _AsyncStorageDriver;
+
+// src/core/queue.ts
+var QUEUE_KEY = "asyncstorage::__queue__";
+var MAX_RETRIES = 5;
+var Queue = class {
+  constructor(driver) {
+    this.driver = driver;
+    this.items = [];
+    this.loaded = false;
+  }
+  async load() {
+    try {
+      const raw = await this.driver.get(QUEUE_KEY);
+      this.items = raw ? JSON.parse(raw) : [];
+    } catch {
+      this.items = [];
+    }
+    this.loaded = true;
+  }
+  async enqueue(item) {
+    this.assertLoaded();
+    this.items.push(item);
+    await this.persist();
+  }
+  getPending() {
+    this.assertLoaded();
+    return this.items.filter((item) => !item.synced && item.retries < MAX_RETRIES);
+  }
+  getPendingForCollection(collectionName) {
+    return this.getPending().filter((item) => item.key === collectionName);
+  }
+  getPendingForRecord(recordId) {
+    return this.getPending().find((item) => item.recordId === recordId);
+  }
+  getAll() {
+    this.assertLoaded();
+    return [...this.items];
+  }
+  async markSynced(itemId) {
+    this.assertLoaded();
+    const item = this.items.find((entry) => entry.id === itemId);
+    if (item) {
+      item.synced = true;
+      item.retries = 0;
+    }
+    await this.persist();
+  }
+  async incrementRetry(itemId) {
+    this.assertLoaded();
+    const item = this.items.find((entry) => entry.id === itemId);
+    if (item) {
+      item.retries += 1;
+    }
+    await this.persist();
+  }
+  async remove(itemId) {
+    this.assertLoaded();
+    this.items = this.items.filter((entry) => entry.id !== itemId);
+    await this.persist();
+  }
+  async clear() {
+    this.items = [];
+    await this.persist();
+  }
+  async persist() {
+    await this.driver.set(QUEUE_KEY, JSON.stringify(this.items));
+  }
+  assertLoaded() {
+    if (!this.loaded) {
+      throw new Error(
+        "[Queue] Queue has not been loaded yet. Ensure AsyncStorageSync.init() has completed before use."
+      );
+    }
+  }
+};
+
+// src/core/sync-engine.ts
+var DEBOUNCE_MS = 500;
+var BACKOFF_BASE_MS = 1e3;
+var SyncEngine = class {
+  constructor(config, queue, driver) {
+    this.config = config;
+    this.queue = queue;
+    this.driver = driver;
+    this.isFlushing = false;
+  }
+  onSynced(cb) {
+    this.onSyncedCb = cb;
+  }
+  onAuthError(cb) {
+    this.onAuthErrorCb = cb;
+  }
+  onStorageFull(cb) {
+    this.onStorageFullCb = cb;
+  }
+  emitStorageFull() {
+    this.onStorageFullCb?.();
+  }
+  start() {
+    console.log("[SyncEngine] start() called");
+    try {
+      const NetInfo = require("@react-native-community/netinfo").default;
+      console.log("[SyncEngine] NetInfo loaded \u2705");
+      this.unsubscribeNetInfo = NetInfo.addEventListener((state) => {
+        console.log("[SyncEngine] NetInfo change \u2192 isConnected:", state.isConnected);
+        if (state.isConnected) {
+          this.scheduleFlush();
+        }
+      });
+      NetInfo.fetch().then((state) => {
+        console.log("[SyncEngine] NetInfo.fetch() \u2192 isConnected:", state.isConnected);
+        if (state.isConnected) {
+          this.scheduleFlush();
+        }
+      });
+    } catch (e) {
+      console.warn("[SyncEngine] \u26A0\uFE0F NetInfo not available \u2014 auto-sync disabled. Error:", e);
+      console.warn("[SyncEngine] Install @react-native-community/netinfo to enable auto-sync.");
+    }
+  }
+  stop() {
+    if (this.unsubscribeNetInfo) {
+      this.unsubscribeNetInfo();
+      this.unsubscribeNetInfo = void 0;
+    }
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = void 0;
+    }
+  }
+  scheduleFlush() {
+    console.log("[SyncEngine] scheduleFlush() \u2014 debounce", DEBOUNCE_MS, "ms");
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    this.debounceTimer = setTimeout(() => {
+      void this.flush();
+    }, DEBOUNCE_MS);
+  }
+  async flush() {
+    if (this.isFlushing) {
+      console.log("[SyncEngine] flush() skipped \u2014 already flushing");
+      return;
+    }
+    this.isFlushing = true;
+    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;
+      }
+      for (const item of pending) {
+        await this.syncItem(item);
+      }
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+  async flushCollection(collectionName) {
+    const pending = this.queue.getPendingForCollection(collectionName);
+    for (const item of pending) {
+      await this.syncItem(item);
+    }
+  }
+  async flushRecord(recordId) {
+    const item = this.queue.getPendingForRecord(recordId);
+    if (item) {
+      await this.syncItem(item);
+    }
+  }
+  async syncItem(item) {
+    if (item.retries > 0) {
+      const backoffMs = Math.pow(2, item.retries) * BACKOFF_BASE_MS;
+      const elapsed = Date.now() - item.ts;
+      if (elapsed < backoffMs) {
+        console.log(`[SyncEngine] syncItem backoff \u2014 retries: ${item.retries}, wait: ${backoffMs - elapsed}ms remaining`);
+        return;
+      }
+    }
+    try {
+      const url = `${this.config.serverUrl}${this.config.endpoint}`;
+      console.log(`[SyncEngine] \u{1F4E4} POST ${url} \u2014 key: ${item.key}, recordId: ${item.recordId}`);
+      const raw = JSON.parse(item.payload);
+      const body = this.config.payloadTransformer ? this.config.payloadTransformer(raw) : raw;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.credentials.apiKey}`
+        },
+        body: JSON.stringify(body)
+      });
+      console.log(`[SyncEngine] Response: ${response.status} ${response.statusText}`);
+      if (response.ok) {
+        await this.handleSuccess(item);
+      } else if (response.status >= 400 && response.status < 500) {
+        await this.handleClientError(item, response.status);
+      } else if (response.status >= 500) {
+        await this.handleServerError(item);
+      }
+    } catch (e) {
+      console.warn("[SyncEngine] \u{1F50C} Network error (offline?) \u2014 will retry on next flush:", e);
+    }
+  }
+  async handleSuccess(item) {
+    await this.queue.markSynced(item.id);
+    const strategy = this.config.onSyncSuccess ?? "keep";
+    if (strategy === "delete") {
+      await this.removeRecordFromCollection(item.key, item.recordId);
+    } else if (strategy === "ttl") {
+      this.scheduleRecordTTL(item.key, item.recordId);
+    } else {
+      await this.updateRecordSyncStatus(item.key, item.recordId, "synced");
+    }
+    this.onSyncedCb?.(item);
+  }
+  async handleClientError(item, status) {
+    await this.queue.remove(item.id);
+    await this.updateRecordSyncStatus(item.key, item.recordId, "failed");
+    if (status === 401 || status === 403) {
+      this.onAuthErrorCb?.(status, item);
+    }
+  }
+  async handleServerError(item) {
+    await this.queue.incrementRetry(item.id);
+  }
+  collectionKey(name) {
+    return `asyncstorage::${name}`;
+  }
+  async getCollection(name) {
+    const raw = await this.driver.get(this.collectionKey(name));
+    return raw ? JSON.parse(raw) : [];
+  }
+  async saveCollection(name, records) {
+    await this.driver.set(this.collectionKey(name), JSON.stringify(records));
+  }
+  async updateRecordSyncStatus(collectionName, recordId, status) {
+    const records = await this.getCollection(collectionName);
+    const index = records.findIndex((record) => record._id === recordId);
+    if (index !== -1) {
+      records[index]._synced = status;
+      await this.saveCollection(collectionName, records);
+    }
+  }
+  async removeRecordFromCollection(collectionName, recordId) {
+    const records = await this.getCollection(collectionName);
+    const filtered = records.filter((record) => record._id !== recordId);
+    await this.saveCollection(collectionName, filtered);
+  }
+  scheduleRecordTTL(collectionName, recordId) {
+    const ttl = this.config.ttl ?? 7 * 24 * 60 * 60 * 1e3;
+    setTimeout(() => {
+      void this.removeRecordFromCollection(collectionName, recordId);
+    }, ttl);
+  }
+};
+
+// src/core/singleton.ts
+function generateId() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
+    const random = Math.random() * 16 | 0;
+    const value = char === "x" ? random : random & 3 | 8;
+    return value.toString(16);
+  });
+}
+function collectionKey(name) {
+  return `asyncstorage::${name}`;
+}
+var DEFAULTS = {
+  autoSync: true,
+  endpoint: "/sync",
+  onSyncSuccess: "keep",
+  ttl: 7 * 24 * 60 * 60 * 1e3,
+  duplicateStrategy: "append"
+};
+var _AsyncStorageSync = class _AsyncStorageSync {
+  constructor(config, driver) {
+    this.config = config;
+    this.driver = driver;
+    this.queue = new Queue(driver);
+    this.engine = new SyncEngine(config, this.queue, driver);
+  }
+  static async init(config) {
+    if (_AsyncStorageSync.instance) {
+      return _AsyncStorageSync.instance;
+    }
+    let driver;
+    if (config.driver === "asyncstorage") {
+      driver = new AsyncStorageDriver();
+    } else {
+      throw new Error(
+        `[async-storage-sync] Unknown driver: "${config.driver}". Only "asyncstorage" is available in v1.`
+      );
+    }
+    const fullConfig = {
+      autoSync: DEFAULTS.autoSync,
+      endpoint: DEFAULTS.endpoint,
+      onSyncSuccess: DEFAULTS.onSyncSuccess,
+      ttl: DEFAULTS.ttl,
+      duplicateStrategy: DEFAULTS.duplicateStrategy,
+      ...config
+    };
+    const instance = new _AsyncStorageSync(fullConfig, driver);
+    await instance.queue.load();
+    await instance.requeueFailed();
+    if (fullConfig.autoSync) {
+      console.log("[AsyncStorageSync] autoSync enabled \u2014 starting sync engine");
+      instance.engine.start();
+    } else {
+      console.log("[AsyncStorageSync] autoSync disabled \u2014 call flush() manually");
+    }
+    _AsyncStorageSync.instance = instance;
+    return instance;
+  }
+  static getInstance() {
+    if (!_AsyncStorageSync.instance) {
+      throw new Error(
+        "[async-storage-sync] getInstance() called before init(). Call AsyncStorageSync.init(...) first."
+      );
+    }
+    return _AsyncStorageSync.instance;
+  }
+  async save(name, data, options = {}) {
+    const strategy = options.duplicateStrategy ?? this.config.duplicateStrategy ?? DEFAULTS.duplicateStrategy;
+    const type = options.type ?? name;
+    const records = await this.getCollection(name);
+    if (strategy === "overwrite") {
+      const existingIndex = records.findIndex((record2) => record2._type === type);
+      if (existingIndex !== -1) {
+        const existing = records[existingIndex];
+        const updated = {
+          ...existing,
+          ...data,
+          _ts: Date.now(),
+          _synced: "pending",
+          _type: type
+        };
+        records[existingIndex] = updated;
+        await this.saveCollection(name, records);
+        await this.enqueueRecord(name, updated, options);
+        return updated;
+      }
+    }
+    const record = {
+      ...data,
+      _id: generateId(),
+      _ts: Date.now(),
+      _synced: "pending",
+      _type: type,
+      _retries: 0
+    };
+    records.push(record);
+    try {
+      await this.saveCollection(name, records);
+    } catch (error) {
+      if (String(error).includes("STORAGE_FULL")) {
+        this.engine.emitStorageFull();
+        throw new Error("[async-storage-sync] Storage is full.");
+      }
+      throw error;
+    }
+    await this.enqueueRecord(name, record, options);
+    return record;
+  }
+  async enqueueRecord(name, record, _options) {
+    const queueItem = {
+      id: generateId(),
+      key: name,
+      recordId: record._id,
+      payload: JSON.stringify(record),
+      endpoint: this.config.endpoint,
+      ts: Date.now(),
+      retries: 0,
+      synced: false
+    };
+    await this.queue.enqueue(queueItem);
+  }
+  async getAll(name) {
+    return this.getCollection(name);
+  }
+  async getById(name, id) {
+    const records = await this.getCollection(name);
+    return records.find((record) => record._id === id) ?? null;
+  }
+  async deleteById(name, id) {
+    const records = await this.getCollection(name);
+    await this.saveCollection(
+      name,
+      records.filter((record) => record._id !== id)
+    );
+  }
+  async deleteCollection(name) {
+    await this.driver.remove(collectionKey(name));
+  }
+  async sync(name) {
+    await this.engine.flushCollection(name);
+  }
+  async syncById(_name, id) {
+    await this.engine.flushRecord(id);
+  }
+  async flush() {
+    await this.engine.flush();
+  }
+  /**
+   * 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.
+   */
+  async requeueFailed() {
+    const allKeys = await this.driver.getAllKeys();
+    const collectionKeys = allKeys.filter((k) => k.startsWith("asyncstorage::") && k !== "asyncstorage::sync_queue");
+    let total = 0;
+    for (const storageKey of collectionKeys) {
+      const collectionName = storageKey.replace("asyncstorage::", "");
+      const raw = await this.driver.get(storageKey);
+      if (!raw) continue;
+      const records = JSON.parse(raw);
+      const failed = records.filter((r) => r._synced === "failed");
+      for (const record of failed) {
+        const queueItem = {
+          id: generateId(),
+          key: collectionName,
+          recordId: record._id,
+          payload: JSON.stringify(record),
+          endpoint: this.config.endpoint,
+          ts: Date.now(),
+          retries: 0,
+          synced: false
+        };
+        await this.queue.enqueue(queueItem);
+        record._synced = "pending";
+        total++;
+      }
+      if (failed.length > 0) {
+        await this.driver.set(storageKey, JSON.stringify(records));
+      }
+    }
+    if (total > 0) {
+      console.log(`[AsyncStorageSync] \u267B\uFE0F Re-enqueued ${total} previously failed record(s) for retry`);
+    }
+  }
+  onSynced(cb) {
+    this.engine.onSynced(cb);
+  }
+  onAuthError(cb) {
+    this.engine.onAuthError(cb);
+  }
+  onStorageFull(cb) {
+    this.engine.onStorageFull(cb);
+  }
+  getQueue() {
+    return this.queue.getAll();
+  }
+  async destroy() {
+    this.engine.stop();
+    await this.queue.clear();
+    await this.driver.clear();
+    _AsyncStorageSync.instance = null;
+  }
+  async getCollection(name) {
+    const raw = await this.driver.get(collectionKey(name));
+    return raw ? JSON.parse(raw) : [];
+  }
+  async saveCollection(name, records) {
+    await this.driver.set(collectionKey(name), JSON.stringify(records));
+  }
+};
+_AsyncStorageSync.instance = null;
+var AsyncStorageSync = _AsyncStorageSync;
+
+// src/index.ts
+var initPromise = null;
+async function initSyncQueue(config) {
+  try {
+    return AsyncStorageSync.getInstance();
+  } catch {
+    if (!initPromise) {
+      initPromise = AsyncStorageSync.init(config).finally(() => {
+        initPromise = null;
+      });
+    }
+    return initPromise;
+  }
+}
+function getSyncQueue() {
+  return AsyncStorageSync.getInstance();
+}
+function setStorageDriver(storage) {
+  AsyncStorageDriver.setStorageClient(storage);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AsyncStorageSync,
+  getSyncQueue,
+  initSyncQueue,
+  setStorageDriver
+});