Registry / testing / storage-based-queue

storage-based-queue

library1.2.6jsnpmunverified

A persistent queue system for browser environments that stores tasks in localStorage, IndexedDB, in-memory, or custom storage drivers. Version 1.2.6 is the latest stable release. Tasks are processed asynchronously via worker classes (or native Web Workers). Supports multiple independent channels, configurable retries, priority sorting, and React Native with minor configuration. Designed for offline-capable web apps that need reliable job processing with error handling. Release cadence is low; library is stable but rarely updated as of 2024. Differentiates from backend queues by being entirely client-side.

testing

npm install storage-based-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · STORAGE-BASED-QUEU

storage-based-queue

testingjavascriptv1.2.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Queue

✓ import { Queue } from 'storage-based-queue'

✗ import Queue from 'storage-based-queue'

Queue is a named export, not a default export. TypeScript types included.

QueueOptions

✓ import type { QueueOptions } from 'storage-based-queue'

For TypeScript users to type options object. Available as a type export.

WorkerResult

✓ import type { WorkerResult } from 'storage-based-queue'

Type for return value of worker functions. Can be used as type assertion.

Queue class instance creation

✓ const queue = new Queue({ channel: 'myChannel', storage: 'localStorage' })

✗ const queue = new Queue()

Constructor requires an options object with at least 'channel' property. Omitting channel will throw.

Creates a queue with localStorage storage, adds a task, defines a worker, starts processing, and listens for events.

import { Queue } from 'storage-based-queue'; const queue = new Queue({ channel: 'myChannel', storage: 'localStorage', priority: 1, // 1 = low, 10 = high retry: 3, retryDelay: 1000, removeOnComplete: false }); // Add a task queue.add('task-1', { data: 'value' }); // Define a worker (must return Promise<boolean> or reject) const worker = async (task) => { try { console.log('Processing:', task.data); return true; // success, move to next } catch (err) { return false; // retry } }; // Start processing queue.run(worker); // Listen for events queue.on('error', (err) => console.error('Queue error:', err)); queue.on('complete', (task) => console.log('Task completed:', task)); queue.on('empty', () => console.log('Queue finished')); // Stop processing // queue.stop();

Debug

Known issues

gotchaMultiple Queue instances with different channels share singleton dependencies. Changes to one instance (e.g., setting retry delay) affect all other instances.

fix

Be aware that channel options are global. Do not rely on per-instance configuration for different channels.

affects: >=1.0.0

gotchaWorker function must return a Promise that resolves to boolean true for success, false for retry, or reject to skip. Returning non-boolean or not returning a promise will cause unpredictable behavior.

fix

Ensure worker returns Promise<boolean> (true) on success, Promise.reject (any) to skip, or resolves to false to trigger retry.

affects: >=1.0.0

gotchaStorage-based queue does not handle storage limits (e.g., localStorage ~5-10MB). Large queues may silently fail or lose data.

fix

Monitor storage usage or use an alternative storage adapter (e.g., IndexedDB via custom driver) for larger queues.

affects: >=1.0.0

gotchaUsing 'priority' option: works only if 'sort' is set to 'priority' (default is 'fifo'). Setting priority without changing sort mode has no effect.

fix

Set sort: 'priority' in options if you want tasks to be ordered by priority field.

affects: >=1.0.0

deprecatedThe pseudo-worker polyfill is added globally for supporting native Web Workers in older browsers. This may conflict with other libraries expecting Worker.

fix

Instead of relying on the polyfill, consider using a dedicated polyfill or bundling a Worker polyfill manually.

affects: >=1.0.0

Errors

Common errors & fixes

Uncaught TypeError: Cannot destructure property 'channel' of 'undefined' as it is undefined.

Constructing Queue without any options object.

fix

const queue = new Queue({ channel: 'myChannel' });

worker is not a function

Calling queue.run() without a worker argument or passing a non-function.

fix

queue.run(worker); where worker is a function returning a Promise.

Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'data')

Worker function assumes task object has a 'data' property but payload might be undefined.

fix

Check task exists: if (task?.data) { ... }

Failed to read the 'localStorage' property from 'Window': Access is denied for this document.

localStorage is blocked (e.g., in private browsing with strict settings, or sandboxed iframe).

fix

Use 'memory' storage driver or catch errors and switch to memory: new Queue({ channel: 'ch', storage: 'memory' });

Upgrade

Version history

1.2.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/atayahmet/storage-based-queue ↗

packagestorage-based-queue ↗

homepagehttps://github.com/atayahmet/storage-based-queue ↗