Request Queue (Offline & PWA Support) The RequestQueue manages persistent offline mutations, FIFO flushing, and dead-letter error handling. It allows PWA applications to operate seamlessly offline and process enqueued mutations sequentially or manually when online.
Enqueue Mutation Flush All (FIFO) Enqueue 500 Failure Clear Queue
Operations waiting to be flushed to the server in FIFO order.
No pending queue operations. Click "Enqueue Mutation" to add item.
Operations that encountered permanent server errors (4xx/5xx). Kept isolated until manually retried or discarded.
import { RequestQueue, EQueueStorage } from '@katlux/providers'
// 1. Initialize queue with storage backend (IndexedDB, LocalStorage, Memory)
RequestQueue.setStorageBackend(EQueueStorage.IndexedDB)
await RequestQueue.init()
// 2. Configure lifecycle hooks (set once in app setup)
RequestQueue.onDeadLetter((item, err) => {
console.error(`Permanent failure (4xx/5xx): ${item.label}`, err)
})
RequestQueue.onNetworkError((item) => {
console.warn(`Device offline — mutation queued for retry: ${item.label}`)
})
RequestQueue.onError((fatalErr) => {
console.error('Queue capacity or persistence error:', fatalErr)
})
RequestQueue.onFlushComplete((succeededTags) => {
console.log('Successfully synced tags:', succeededTags)
})
// 3. Enqueue mutation
const id = await RequestQueue.enqueue({
url: '/api/v1/invoices',
method: 'POST',
options: { method: 'POST', body: { customerId: 42, amount: 150.00 } },
tags: ['invoices'],
label: 'Create Invoice 1004'
})
// 4. Flush queued operations (FIFO order, stops on first failure)
await RequestQueue.flushAll()
// 5. Single-item controls
await RequestQueue.flushOne(id) // Flush single item
await RequestQueue.retryOne(id) // Move dead-letter back to pending (front)
await RequestQueue.discard(id) // Permanently delete item
RequestQueue.reorder([id]) // Reorder pending queue
Property Type Description RequestQueue.queue Ref(IQueuedOperation[]) Reactive array of pending queued mutations waiting for flush. RequestQueue.deadLetterQueue Ref(IDeadLetterItem[]) Reactive array of permanently failed (4xx/5xx) operations. RequestQueue.isFlushing Ref(boolean) Reactive boolean indicator of active flush state.
Method Parameters Description init () => Promise Initializes the chosen storage backend and loads persisted queue state. setStorageBackend (type: EQueueStorage) Sets storage engine (IndexedDB, LocalStorage, Memory). enqueue (item: IQueuedOperationInput) Enqueues a mutation operation. Returns generated item ID. flushAll (options?: { tag?: string }) Flushes queued operations in FIFO order. Stops on first error. Catches capacity errors safely. flushOne (id: string) Immediately dispatches a specific queued item by ID. retryOne (id: string) Moves a dead-letter item to the FRONT of the pending queue. discard (id: string) Permanently removes an item from pending or dead-letter queue. reorder (ids: string[]) Reorders pending queue operations according to the provided ID array. setMaxQueueSize (limit: number) Sets maximum pending queue capacity (default: 500). setMaxDeadLetterSize (limit: number) Sets maximum dead-letter queue capacity before halting to prevent data loss (default: 200). setMaxPayloadSize (bytes: number) Sets maximum allowed mutation payload size in bytes (default: 5MB). onError (cb: (err: Error) => void) Event listener fired when a fatal queue capacity or storage error occurs. onQueueFatalError (cb: (err: Error) => void) Alias for onError. onDeadLetter (cb: (item: IDeadLetterItem, err: Error) => void) Event listener fired when an operation permanently fails and moves to dead-letter. onFlushComplete (cb: (tags: string[]) => void) Event listener fired when a flush successfully processes mutations. onNetworkError (cb: (item: IQueuedOperation) => void) Event listener fired when a flush halts due to device going offline.