@zacaw99/relayq

A lightweight, persistent action queue for PWAs and local-first web apps.

Queue actions, store them locally, retry on failure, and automatically sync when the network returns.

✨ Features

• 📦 Persistent Queue – Store actions locally using IndexedDB
• 🔁 Retry Logic – Automatic retry with configurable backoff
• 🌐 Offline Safe – Works seamlessly without network
• ⚡ Auto Flush – Retries automatically when connection returns
• 🎯 Simple API – Register handlers and enqueue jobs
• 🧱 Framework Agnostic – Works with React, Next.js, or vanilla JS
• 🪶 Lightweight – Minimal footprint, no dependencies
• 🧠 Deterministic – Explicit control, no hidden magic

📦 Installation

npm install @zacaw99/relayq

🚀 Quick Start

1. Create a queue

import { createQueue, indexedDbStorage } from "@zacaw99/relayq";

export const queue = createQueue({
	storage: indexedDbStorage(),
	autoFlushOnOnline: true,
});

2. Register handlers

await queue.register("profile:update", async (job) => {
	const res = await fetch("/api/profile", {
		method: "POST",
		headers: { "Content-Type": "application/json" },
		body: JSON.stringify(job.payload),
	});

	if (!res.ok) {
		throw new Error(`Request failed: ${res.status}`);
	}
});

3. Enqueue actions

await queue.enqueue({
	type: "profile:update",
	payload: {
		name: "Zac",
		role: "Admin",
	},
});

That’s it

• Online → executes immediately
• Offline → stored and retried later
• Reconnect → automatically flushed

📱 PWA Setup (Recommended)

relayq pairs naturally with PWAs.

Minimal setup

if ("serviceWorker" in navigator) {
	navigator.serviceWorker.register("/sw.js");
}

// public/sw.js
self.addEventListener("install", (event) => {
	event.waitUntil(
		caches.open("app-shell").then((cache) => {
			return cache.addAll(["/", "/index.html"]);
		}),
	);
});

🧠 Summary

Never lose user actions.

Queue it.
Persist it.
Retry it.
Deliver it.

📝 License

MIT

👤 Author

Created by zacaw99