fsqu

library1.1.3jsnpmunverified

FSqu implements job queues on top of a regular filesystem, where a queue is a directory and each element is a file. Version 1.1.3 is the latest stable release, with no frequent updates. It supports delays/scheduling, at-most-once and at-least-once delivery models, and direct file addition via mv. It is designed for single-machine pipelines that handle large files, and uses the `debug` module for logging. Key differentiators: constant-time operations regardless of queue size, no external dependencies beyond Node.js core modules, and survives process restarts.

storage

npm install fsqu

package ↗homepage ↗

INSTALL

IMPORT

SIG · FSQU

fsqu

storagejavascriptv1.1.3

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.

FSqu

✓ const FSqu = require('fsqu');

✗ import FSqu from 'fsqu'; // CommonJS only, no ESM exports

FSqu is exported as a CommonJS module. There is no default export; the main export is the constructor function `fsqu`. To instantiate: `new FSqu.fsqu(opts)`.

fsqu constructor

✓ const q = new FSqu.fsqu({ name: 'myqueue', path: '/tmp/queues' });

✗ const q = new FSqu({ name: 'myqueue' }); // FSqu is the module, not the constructor. Use FSqu.fsqu

The constructor is `FSqu.fsqu`. The module exports an object with an `fsqu` property.

q.pushData

✓ q.pushData('data', { delay: 1000 }, callback);

✗ q.pushData('data', callback); // Missing opts object – will error if second arg is not an object or function

pushData signature: (data, opts, cb). opts can be omitted but must be null/undefined or an object; if you pass a function as second argument it will be treated as opts.

Demonstrates queue initialization, pushing data, popping entries, and reading the landing location.

Debug

Known issues

gotchaNo FIFO guarantees: insertion order is mostly kept but not guaranteed.

fix

Do not rely on strict ordering. Use if order is critical.

affects: all

gotchaThe `pop()` operation moves the file to the landing directory, not copies. Ensure the landing directory is on the same filesystem.

fix

Set `landing` to a directory on the same filesystem as the queue to avoid cross-device moves.

affects: all

deprecatedThe `pushData` callback signature: `cb` is mandatory and must be a function. Omitting it causes an error.

fix

Always pass a callback function to pushData, pushStream, pushFile.

affects: >=1.0.0

gotchaThe `id` option for push operations must match regex `^([0-9a-z]+)$`. Failing to do so results in an error.

fix

Ensure id contains only lowercase alphanumeric characters.

affects: all

gotchaQueue initialization (`init`) must be called before any push/pop operations.

fix

Always call `q.init(callback)` before using the queue.

affects: all

Errors

Common errors & fixes

TypeError: FSqu is not a constructor

Using `new FSqu(opts)` incorrectly; FSqu is an object, not the constructor itself.

fix

Use `new FSqu.fsqu(opts)` instead.

TypeError: cb is not a function

Omitting the callback or passing a non-function to pushData.

fix

Always pass a function as the last argument to pushData/pushStream/pushFile.

Error: invalid id

The `id` option does not match the required regex.

fix

Use only lowercase letters and digits (0-9, a-z) for id.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

debugoptionalUsed for debugging output (DEBUG=fsqu:*)

asyncoptionalUsed in quickstart example for flow control, not a runtime dependency

Agent activity

28 hits · last 30 days

node

Amazon

Resources

packagefsqu ↗

homepagehttps://codeberg.org/pepmartinez/fsqu ↗