file-queue

library0.3.0jsnpmunverified

A file system-based FIFO queue implemented using the maildir format, providing lockfree operations for durability and simplicity. Version 0.3.0 is the latest release (last updated in 2014). The library supports push, pop (with blocking on empty queues), transactional pop (tpop) with commit/rollback, length, and clear operations. Objects are serialized as JSON. It is designed for environments where a lightweight, filesystem-backed queue is needed. Alternatives like better-queue or bull use databases or Redis; file-queue is purely filesystem-based with no external dependencies. The package is in maintenance mode but still functional for Node.js projects.

storage

npm install file-queue

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FILE-QUEUE

file-queue

storagejavascriptv0.3.0

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.

default

✓ import Queue from 'file-queue'

✗ const Queue = require('file-queue')

This package does not export a default; use named import for Queue.

Queue

✓ import { Queue } from 'file-queue'

✗ const { Queue } = require('file-queue').Queue

CommonJS users should use `const Queue = require('file-queue').Queue`.

Queue (with fs option)

✓ import { Queue } from 'file-queue'; new Queue({ path: 'queue', fs: require('graceful-fs') }, callback)

Pass an options object with path and fs to configure the queue.

Shows how to create a queue, push, pop, transactional pop with commit, get length, and clear.

import { Queue } from 'file-queue'; const queue = new Queue('./my-queue', (err) => { if (err) { console.error('Failed to create queue:', err); process.exit(1); } // Push a message queue.push('Hello World', (err) => { if (err) console.error('Push error:', err); else console.log('Pushed message'); }); // Pop a message (blocks until available) queue.pop((err, message) => { if (err) console.error('Pop error:', err); else console.log('Received:', message); }); // Transactional pop queue.tpop((err, message, commit, rollback) => { if (err) console.error('TPop error:', err); else { console.log('Processing:', message); commit((err) => { if (err) console.error('Commit error:', err); else console.log('Committed'); }); } }); // Get queue length queue.length((err, length) => { if (err) console.error('Length error:', err); else console.log('Queue length:', length); }); // Clear the queue queue.clear((err) => { if (err) console.error('Clear error:', err); else console.log('Queue cleared'); }); });

Debug

Known issues

gotchapop() blocks indefinitely if queue is empty.

fix

Wrap pop in a timeout or setInterval with length check if non-blocking needed.

affects: >=0.0.0

gotchaTransactional pops (tpop) do not guarantee FIFO ordering — inner transactions may process out of order.

fix

Avoid using nested tpop if strict ordering is required.

affects: >=0.0.0

gotchaFile system errors (e.g., EMFILE) can occur with many files; Node's default fs may fail.

fix

Use graceful-fs by passing `fs: require('graceful-fs')` in options.

affects: >=0.0.0

deprecatedPackage has not been updated since 2014; may not work with modern Node.js (10+).

fix

Consider migrating to an active library like better-queue or bull.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'file-queue'

Package not installed or import path incorrect.

fix

Run `npm install file-queue` and use `require('file-queue').Queue` for CommonJS.

TypeError: Queue is not a constructor

Using `new Queue()` with incorrect import (default instead of named).

fix

Use `import { Queue }` or `const Queue = require('file-queue').Queue`.

Error: EMFILE: too many open files, open '...'

File descriptor limit reached with many files in queue.

fix

Use graceful-fs: `new Queue({ path: '.', fs: require('graceful-fs') })`.

TypeError: queue.pop is not a function

Wrong import or queue variable not initialized correctly.

fix

Ensure Queue is properly constructed: `const queue = new Queue('path', callback)`.

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/threez/file-queue ↗

packagefile-queue ↗

homepagehttps://github.com/threez/file-queue#readme ↗