react-native-outbox-mutation-queue 0.1.0

package/lib/queue.js

@@ -0,0 +1,299 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineQueue = void 0;
+exports.createQueue = createQueue;
+const backoff_1 = require("./backoff");
+const memory_1 = require("./storage/memory");
+const id_1 = require("./utils/id");
+class OfflineQueue {
+    constructor(config) {
+        this.tasks = [];
+        this.warnedAboutDedupe = false;
+        this.online = true;
+        this.running = false;
+        this.draining = false;
+        this.inFlight = 0;
+        this.timer = null;
+        this.listeners = {
+            enqueued: new Set(),
+            deduped: new Set(),
+            started: new Set(),
+            succeeded: new Set(),
+            failed: new Set(),
+            discarded: new Set(),
+            drained: new Set(),
+            changed: new Set(),
+        };
+        this.config = config;
+        this.storage = config.storage ?? (0, memory_1.createMemoryStorage)();
+        this.storageKey = config.storageKey ?? 'rn-offline-queue/v1';
+        this.retry = { ...backoff_1.DEFAULT_RETRY, ...config.retry };
+        this.dedupeStrategy = config.dedupeStrategy ?? 'replace';
+        this.concurrency = Math.max(1, config.concurrency ?? 1);
+        this.silenceDedupeWarning = config.silenceDedupeWarning ?? false;
+        this.running = config.autoStart ?? true;
+        this.hydrated = this.hydrate();
+    }
+    // ---------------------------------------------------------------- lifecycle
+    /** Resolves once persisted tasks have been loaded from storage. */
+    ready() {
+        return this.hydrated;
+    }
+    /** Resume processing. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        void this.drain();
+    }
+    /** Pause processing. In-flight tasks are allowed to finish. */
+    pause() {
+        this.running = false;
+        this.clearTimer();
+    }
+    /**
+     * Report connectivity. Wire this to NetInfo — the queue holds tasks while
+     * offline rather than burning retry attempts against a dead network.
+     */
+    setOnline(online) {
+        const wasOffline = !this.online;
+        this.online = online;
+        if (online && wasOffline)
+            void this.drain();
+    }
+    isOnline() {
+        return this.online;
+    }
+    // ------------------------------------------------------------------- public
+    /** Add a mutation to the queue. Safe to call while offline. */
+    async enqueue(type, payload, options = {}) {
+        await this.hydrated;
+        const now = Date.now();
+        const task = {
+            id: (0, id_1.createId)(),
+            type,
+            payload,
+            createdAt: now,
+            updatedAt: now,
+            attempts: 0,
+            status: 'pending',
+            dedupeKey: options.dedupeKey,
+        };
+        const strategy = options.dedupeStrategy ?? this.dedupeStrategy;
+        if (task.dedupeKey && strategy !== 'keep') {
+            // Only collapse against tasks not yet in flight — replacing a running
+            // task would leave its side effect half-applied.
+            const existingIndex = this.tasks.findIndex((t) => t.dedupeKey === task.dedupeKey && t.status === 'pending');
+            if (existingIndex !== -1) {
+                const existing = this.tasks[existingIndex];
+                if (strategy === 'drop') {
+                    this.noteDedupe();
+                    this.emit('deduped', existing, task, strategy);
+                    return existing;
+                }
+                // 'replace' — keep queue position, take the newer payload.
+                const merged = {
+                    ...existing,
+                    payload: task.payload,
+                    type: task.type,
+                    updatedAt: now,
+                };
+                this.tasks[existingIndex] = merged;
+                await this.persist();
+                this.noteDedupe();
+                // `existing` carried the payload that is now gone.
+                this.emit('deduped', merged, existing, strategy);
+                this.emit('enqueued', merged);
+                void this.drain();
+                return merged;
+            }
+        }
+        this.tasks.push(task);
+        await this.persist();
+        this.emit('enqueued', task);
+        void this.drain();
+        return task;
+    }
+    /** Snapshot of queued tasks, in execution order. */
+    list() {
+        return [...this.tasks];
+    }
+    size() {
+        return this.tasks.length;
+    }
+    /** Remove a single task without executing it. */
+    async remove(id) {
+        const before = this.tasks.length;
+        this.tasks = this.tasks.filter((t) => t.id !== id);
+        if (this.tasks.length === before)
+            return false;
+        await this.persist();
+        return true;
+    }
+    /** Drop every queued task. */
+    async clear() {
+        this.tasks = [];
+        await this.persist();
+    }
+    on(event, handler) {
+        const set = this.listeners[event];
+        set.add(handler);
+        return () => {
+            set.delete(handler);
+        };
+    }
+    // ------------------------------------------------------------------ internal
+    /**
+     * Deduplication discards work by design, but a silent discard is how the
+     * "my chat messages disappeared" bug happens. Warn once per queue in dev so
+     * the behaviour is discovered during development rather than in production.
+     */
+    noteDedupe() {
+        if (this.warnedAboutDedupe || this.silenceDedupeWarning)
+            return;
+        this.warnedAboutDedupe = true;
+        const dev = globalThis.__DEV__;
+        if (dev === false)
+            return;
+        // eslint-disable-next-line no-console
+        console.warn('[outbox] A queued task was collapsed because it shared a dedupeKey ' +
+            'with another. This is intentional for drafts and form saves, but it ' +
+            'DISCARDS the other payload — do not use dedupeKey for items that ' +
+            'must each be delivered, such as chat messages. Listen to the ' +
+            '"deduped" event to observe this, or pass silenceDedupeWarning: true.');
+    }
+    async hydrate() {
+        try {
+            const raw = await this.storage.getItem(this.storageKey);
+            if (raw) {
+                const parsed = JSON.parse(raw);
+                // Anything left mid-flight from a previous session is retried; the
+                // process died before we learned the outcome.
+                this.tasks = parsed.map((t) => t.status === 'running' ? { ...t, status: 'pending' } : t);
+            }
+        }
+        catch {
+            // Corrupt payload should not brick the app — start clean.
+            this.tasks = [];
+        }
+        this.emit('changed', this.list());
+        void this.drain();
+    }
+    async persist() {
+        this.emit('changed', this.list());
+        try {
+            await this.storage.setItem(this.storageKey, JSON.stringify(this.tasks));
+        }
+        catch {
+            // Storage failure must not lose the in-memory queue.
+        }
+    }
+    nextRunnable(now) {
+        return this.tasks.find((t) => t.status === 'pending' && (!t.nextAttemptAt || t.nextAttemptAt <= now));
+    }
+    async drain() {
+        if (this.draining)
+            return;
+        if (!this.running || !this.online)
+            return;
+        this.draining = true;
+        try {
+            while (this.running && this.online && this.inFlight < this.concurrency) {
+                const now = Date.now();
+                const task = this.nextRunnable(now);
+                if (!task)
+                    break;
+                void this.run(task);
+            }
+        }
+        finally {
+            this.draining = false;
+        }
+        this.scheduleNext();
+    }
+    /** Wake up when the earliest backed-off task becomes eligible. */
+    scheduleNext() {
+        this.clearTimer();
+        if (!this.running || !this.online)
+            return;
+        const waiting = this.tasks
+            .filter((t) => t.status === 'pending' && t.nextAttemptAt)
+            .map((t) => t.nextAttemptAt);
+        if (waiting.length === 0) {
+            if (this.tasks.length === 0 && this.inFlight === 0)
+                this.emit('drained');
+            return;
+        }
+        const delay = Math.max(0, Math.min(...waiting) - Date.now());
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.drain();
+        }, delay);
+    }
+    clearTimer() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    async run(task) {
+        task.status = 'running';
+        task.attempts += 1;
+        task.updatedAt = Date.now();
+        this.inFlight += 1;
+        this.emit('started', task);
+        await this.persist();
+        try {
+            await this.config.execute(task);
+            this.tasks = this.tasks.filter((t) => t.id !== task.id);
+            await this.persist();
+            this.emit('succeeded', task);
+        }
+        catch (error) {
+            await this.handleFailure(task, error);
+        }
+        finally {
+            this.inFlight -= 1;
+            void this.drain();
+        }
+    }
+    async handleFailure(task, error) {
+        const kind = this.config.classifyError?.(error, task) ?? 'transient';
+        const exhausted = task.attempts >= this.retry.maxAttempts;
+        const willRetry = kind === 'transient' && !exhausted;
+        task.lastError = error instanceof Error ? error.message : String(error);
+        task.updatedAt = Date.now();
+        if (willRetry) {
+            task.status = 'pending';
+            task.nextAttemptAt = Date.now() + (0, backoff_1.computeBackoff)(task.attempts, this.retry);
+            await this.persist();
+            this.emit('failed', task, error, true);
+            return;
+        }
+        task.status = 'discarded';
+        this.tasks = this.tasks.filter((t) => t.id !== task.id);
+        await this.persist();
+        this.emit('failed', task, error, false);
+        this.emit('discarded', task, error);
+        try {
+            await this.config.onDiscard?.(task, error);
+        }
+        catch {
+            // A throwing conflict handler must not stall the queue.
+        }
+    }
+    emit(event, ...args) {
+        for (const handler of this.listeners[event]) {
+            try {
+                handler(...args);
+            }
+            catch {
+                // Listener errors are contained.
+            }
+        }
+    }
+}
+exports.OfflineQueue = OfflineQueue;
+function createQueue(config) {
+    return new OfflineQueue(config);
+}

package/lib/react.d.ts

@@ -0,0 +1,16 @@
+import type { OfflineQueue } from './queue';
+import type { Task } from './types';
+export interface QueueState<P = unknown> {
+    tasks: Task<P>[];
+    pending: number;
+    isOnline: boolean;
+}
+/**
+ * Subscribe a component to queue contents.
+ *
+ * ```tsx
+ * const { pending, isOnline } = useOfflineQueue(queue);
+ * if (pending > 0) return <Text>{pending} change(s) waiting to sync</Text>;
+ * ```
+ */
+export declare function useOfflineQueue<P = unknown>(queue: OfflineQueue<P>): QueueState<P>;

package/lib/react.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useOfflineQueue = useOfflineQueue;
+const react_1 = require("react");
+/**
+ * Subscribe a component to queue contents.
+ *
+ * ```tsx
+ * const { pending, isOnline } = useOfflineQueue(queue);
+ * if (pending > 0) return <Text>{pending} change(s) waiting to sync</Text>;
+ * ```
+ */
+function useOfflineQueue(queue) {
+    const [tasks, setTasks] = (0, react_1.useState)(() => queue.list());
+    const [isOnline, setIsOnline] = (0, react_1.useState)(() => queue.isOnline());
+    (0, react_1.useEffect)(() => {
+        setTasks(queue.list());
+        setIsOnline(queue.isOnline());
+        const unsubscribe = queue.on('changed', (next) => {
+            setTasks(next);
+            setIsOnline(queue.isOnline());
+        });
+        return unsubscribe;
+    }, [queue]);
+    return {
+        tasks,
+        pending: tasks.filter((t) => t.status !== 'discarded').length,
+        isOnline,
+    };
+}

package/lib/storage/memory.d.ts

@@ -0,0 +1,6 @@
+import type { StorageAdapter } from './types';
+/**
+ * In-memory adapter. Used as the default so the queue works without
+ * configuration, and useful in tests. Nothing survives a restart.
+ */
+export declare function createMemoryStorage(): StorageAdapter;

package/lib/storage/memory.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMemoryStorage = createMemoryStorage;
+/**
+ * In-memory adapter. Used as the default so the queue works without
+ * configuration, and useful in tests. Nothing survives a restart.
+ */
+function createMemoryStorage() {
+    const map = new Map();
+    return {
+        async getItem(key) {
+            return map.has(key) ? map.get(key) : null;
+        },
+        async setItem(key, value) {
+            map.set(key, value);
+        },
+        async removeItem(key) {
+            map.delete(key);
+        },
+    };
+}

package/lib/storage/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal persistence contract.
+ *
+ * Deliberately shaped like AsyncStorage so `@react-native-async-storage/
+ * async-storage` can be passed straight in, while MMKV, SQLite or a test
+ * double can be adapted in a few lines.
+ */
+export interface StorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}

package/lib/storage/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Core types for the offline mutation queue.
+ */
+export type TaskStatus = 'pending' | 'running' | 'failed' | 'discarded';
+export interface Task<P = unknown> {
+    /** Stable unique id, generated on enqueue. */
+    id: string;
+    /** Caller-defined operation name, e.g. `updateProfile`. */
+    type: string;
+    payload: P;
+    createdAt: number;
+    updatedAt: number;
+    /** Number of execution attempts made so far. */
+    attempts: number;
+    status: TaskStatus;
+    /** Tasks sharing a key collapse according to the dedupe strategy. */
+    dedupeKey?: string;
+    /** Message from the most recent failure, kept for debugging. */
+    lastError?: string;
+    /** Epoch ms before which the task must not be retried. */
+    nextAttemptAt?: number;
+}
+/**
+ * What to do when a newly enqueued task shares a `dedupeKey` with one
+ * already waiting.
+ *
+ * - `replace` keeps the newest payload (last write wins) — the right default
+ *   for "save this form" style mutations.
+ * - `drop`    keeps the task already queued and ignores the new one.
+ * - `keep`    disables collapsing and queues both.
+ */
+export type DedupeStrategy = 'replace' | 'drop' | 'keep';
+export interface RetryPolicy {
+    /** Attempts before a task is handed to `onDiscard`. Default 5. */
+    maxAttempts: number;
+    /** First backoff delay in ms. Default 1000. */
+    baseDelayMs: number;
+    /** Upper bound for a single backoff delay in ms. Default 60_000. */
+    maxDelayMs: number;
+    /** Randomisation applied to each delay, 0–1. Default 0.3. */
+    jitter: number;
+}
+/**
+ * Thrown-error classification. Returning `permanent` skips remaining
+ * retries — use it for 4xx responses that will never succeed.
+ */
+export type FailureKind = 'transient' | 'permanent';
+export interface QueueEvents<P = unknown> {
+    enqueued: (task: Task<P>) => void;
+    /**
+     * A task was collapsed into another because they shared a `dedupeKey`.
+     * `kept` remains queued; `dropped` was discarded.
+     *
+     * Deduplication is intentional, but it does throw work away. Listen here to
+     * log or reconcile — and to catch the classic mistake of giving a dedupeKey
+     * to things that must each be delivered, such as chat messages.
+     */
+    deduped: (kept: Task<P>, dropped: Task<P>, strategy: DedupeStrategy) => void;
+    started: (task: Task<P>) => void;
+    succeeded: (task: Task<P>) => void;
+    failed: (task: Task<P>, error: unknown, willRetry: boolean) => void;
+    discarded: (task: Task<P>, error: unknown) => void;
+    drained: () => void;
+    /** Fired whenever the persisted task list changes. */
+    changed: (tasks: Task<P>[]) => void;
+}
+export type QueueEventName = keyof QueueEvents;
+export type Unsubscribe = () => void;

package/lib/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Core types for the offline mutation queue.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/utils/id.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Collision-resistant id without pulling in a uuid dependency.
+ * Time-prefixed so ids sort roughly in creation order.
+ */
+export declare function createId(): string;

package/lib/utils/id.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createId = createId;
+let counter = 0;
+/**
+ * Collision-resistant id without pulling in a uuid dependency.
+ * Time-prefixed so ids sort roughly in creation order.
+ */
+function createId() {
+    counter = (counter + 1) % 0xffff;
+    const time = Date.now().toString(36);
+    const seq = counter.toString(36).padStart(3, '0');
+    const rand = Math.floor(Math.random() * 0xffffff)
+        .toString(36)
+        .padStart(4, '0');
+    return `${time}-${seq}-${rand}`;
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "react-native-outbox-mutation-queue",
+  "version": "0.1.0",
+  "description": "A focused offline mutation queue for React Native \u2014 queue API writes while offline, retry with exponential backoff, deduplicate, persist across restarts.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./react": {
+      "types": "./lib/react.d.ts",
+      "default": "./lib/react.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build",
+    "demo": "node example/node-demo.cjs"
+  },
+  "keywords": [
+    "react-native",
+    "offline",
+    "offline-first",
+    "queue",
+    "mutation",
+    "retry",
+    "backoff",
+    "sync",
+    "async-storage"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.18",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ARBAB1/react-native-outbox-mutation-queue.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ARBAB1/react-native-outbox-mutation-queue/issues"
+  },
+  "homepage": "https://github.com/ARBAB1/react-native-outbox-mutation-queue#readme",
+  "author": "Syed Arbab Ali Shah <syedarbabalishah@gmail.com>"
+}

package/src/backoff.ts

@@ -0,0 +1,34 @@
+import type { RetryPolicy } from './types';
+
+export const DEFAULT_RETRY: RetryPolicy = {
+  maxAttempts: 5,
+  baseDelayMs: 1000,
+  maxDelayMs: 60_000,
+  jitter: 0.3,
+};
+
+/**
+ * Exponential backoff with full-width jitter.
+ *
+ * Delay grows as base * 2^(attempt-1), clamped to maxDelayMs, then has a
+ * random factor applied so a fleet of devices coming back online together
+ * does not retry in lockstep and stampede the API.
+ *
+ * @param attempt 1-based attempt number that just failed.
+ */
+export function computeBackoff(
+  attempt: number,
+  policy: RetryPolicy = DEFAULT_RETRY,
+  random: () => number = Math.random,
+): number {
+  const exponent = Math.max(0, attempt - 1);
+  const raw = policy.baseDelayMs * 2 ** exponent;
+  const clamped = Math.min(raw, policy.maxDelayMs);
+
+  if (policy.jitter <= 0) return Math.round(clamped);
+
+  // Spread within ±jitter of the clamped delay, never below zero.
+  const spread = clamped * policy.jitter;
+  const offset = (random() * 2 - 1) * spread;
+  return Math.max(0, Math.round(clamped + offset));
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { OfflineQueue, createQueue } from './queue';
+export type { QueueConfig, EnqueueOptions } from './queue';
+
+export { computeBackoff, DEFAULT_RETRY } from './backoff';
+export { createMemoryStorage } from './storage/memory';
+
+export type { StorageAdapter } from './storage/types';
+export type {
+  DedupeStrategy,
+  FailureKind,
+  QueueEventName,
+  QueueEvents,
+  RetryPolicy,
+  Task,
+  TaskStatus,
+  Unsubscribe,
+} from './types';