@apislash/storage-sync

Local-first durable outbox + background sync adapter for the @apislash/storage core.

Persist mutations (file uploads, form drafts) locally and encrypted, then deliver them to a REST backend in the background with ACK, jittered retry and last-write-wins. The user is freed immediately; delivery resumes on reconnect, tab focus, or app restart.

Install

npm install @apislash/storage-sync @apislash/storage-core

What it gives you

• SyncOutbox — a durable queue on a storage-core StructuredDbStore. Each entry's payload is encrypted at rest via a CryptoProvider (from @apislash/cryptobox); the metadata stays queryable.
• SyncEngine — drains due entries to a pluggable Transport, records the backend ACK (canonical id), retries retryable failures with exponential backoff + jitter, and marks terminal failures. Conflicts resolve last-write-wins by a clock-independent revision counter.
• installWebTriggers — flush the queue the moment connectivity returns or the tab becomes visible. subscribe() surfaces SyncStatus (pending / inflight / acked / failed) for UI badges.

One library serves both file uploads and form drafts.

Usage

import { createSyncOutbox, PayloadCipher, SyncEngine, installWebTriggers } from "@apislash/storage-sync";

const store  = dbDriver.collection("outbox");
const cipher = new PayloadCipher(cryptoProvider, key);            // always encrypt
const outbox = createSyncOutbox(store, cipher, { idGen: uuidV7 });
const engine = new SyncEngine(outbox, transport);                // you supply transport
engine.start();
installWebTriggers(engine);                                      // flush on online/visible

await outbox.enqueue("form", listingDraft);                      // local-first; returns at once
engine.subscribe((status) => render(status));

License

MIT © Apislash