https://github.com/techiev2/deferq
A tiny, zero-dependency JavaScript library for queuing async actions when offline and automatically retrying them when connectivity returns.
https://github.com/techiev2/deferq
Last synced: 5 months ago
JSON representation
A tiny, zero-dependency JavaScript library for queuing async actions when offline and automatically retrying them when connectivity returns.
- Host: GitHub
- URL: https://github.com/techiev2/deferq
- Owner: techiev2
- License: mit
- Created: 2025-12-21T19:41:56.000Z (6 months ago)
- Default Branch: master
- Last Pushed: 2025-12-23T18:53:19.000Z (6 months ago)
- Last Synced: 2025-12-25T02:34:39.034Z (6 months ago)
- Language: JavaScript
- Size: 24.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# deferq
A tiny, zero-dependency JavaScript library for queuing async actions when offline and automatically retrying them when connectivity returns.
- **Lightweight**: ~30 lines of code
- **Zero dependencies**
- **Concurrent retries**: All queued actions run in parallel when back online
- **Flexible**: Queue any async function by name
Ideal for simple offline support without the complexity of service workers.
## Installation
### Via npm
Install with: `npm install deferq`
### Via CDN
```html
```
## Usage
### 1. Initialize the library (once)
```JavaScript
import { addToQueue, register } from 'https://cdn.jsdelivr.net/npm/deferq@1.1.3/index.js'; // Automatically registers the "online" listener
```
### 2. Queue actions when offline
```JavaScript
async function createPost({ post }) {
if (!navigator.onLine) {
addToQueue('networkQueue', 'createPost' { post });
showToast("Offline — we'll retry when you're back online.", 5);
return;
}
const res = await fetch('/api/post', {
method: 'POST',
body: JSON.stringify({ post }),
headers: { 'Content-Type': 'application/json' }
});
// handle response...
}
// Call your function as usual
createPost({ post: "Hello world!" });
```
### 3. Automatic retry
When the browser fires the "online" event, deferq:
- Loads the queue from internal storage.
- Executes all queued functions serially to avoid a thundering herd.
- Removes successful actions.
- Keeps persistent failures for the next online event.
No additional setup required.
## API
```JavaScript
addToQueue(key: string, fnName: string, payload: any)
````
Queues an action.
- key: key for the queue (e.g., 'networkQueue', 'fetchQueue', 'transferQueue')
- fnName: Name of the function as it was registered to deferq.
- payload: Data to pass to the function when replayed
Example: addToQueue('networkQueue', 'createPost', { post: 'data' })
## How It Works
- When offline, use addToQueue instead of calling the function directly.
- Actions are cached in internal storage under the given key.
- On "online", deferq replays all actions serially.
- Successful actions are removed; failed ones remain for future retries.
## Notes
- In v1.1.3, actions are no longer stored in localStorage to avoid pollution and XSS attacks.
- Functions to queue must be pure functions and not use global state, for safety and proper application.
- No built-in queue size limit (add your own in production if needed).
- Works in all modern browsers.
### Function Naming Requirement
For automatic retry to work, the calling function must have a name that appears in the stack trace.
Works:
- Named function declarations: `function createPost() {}`
- Named function expressions: `const post = function createPost() {}`
Does not work:
- Arrow functions: `const createPost = async () => {}`
- Anonymous functions
*Recommendation*: Use named functions for actions that may be queued offline.
## License
MIT