qlobber-fsq

library14.0.0jsnpmunverified

A shared file system queue for Node.js that supports pub-sub and work queues with AMQP-like topic wildcards. Version 14.0.0 (stable, maintained as of 2025) targets Node 16+. It leverages the local file system for multi-core use and tested distributed file systems (BeeGFS, CephFS) for multi-host setups. Key differentiators vs. Redis pub-sub or RabbitMQ are zero external dependencies beyond Node.js, optional direct producer-to-subscriber streaming (since v12.1.0), and optional shared-memory Disruptor acceleration (since v9). Limitations: no guaranteed message ordering unless using order_by_expiry; best-effort delivery under crashes.

messaging

npm install qlobber-fsq

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · QLOBBER-FSQ

qlobber-fsq

messagingjavascriptv14.0.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.

QlobberFSQ

✓ import { QlobberFSQ } from 'qlobber-fsq'

✗ const QlobberFSQ = require('qlobber-fsq').QlobberFSQ

ESM is supported since version 11. For CommonJS, use require('qlobber-fsq').QlobberFSQ; the default export is not available.

QlobberFSQ (CJS, default)

✓ const { QlobberFSQ } = require('qlobber-fsq')

✗ const QlobberFSQ = require('qlobber-fsq')

The required object is an object with QlobberFSQ property; not a constructor directly. This is a common footgun.

QlobberFSQ (type import)

✓ import type { QlobberFSQ } from 'qlobber-fsq'

✗ import QlobberFSQ from 'qlobber-fsq'

When using TypeScript, importing QlobberFSQ as default is incorrect; it must be a named type import.

Create a QlobberFSQ instance, subscribe to a topic pattern with multi-level wildcard, publish a message, and handle life cycle events.

import { QlobberFSQ } from 'qlobber-fsq'; import assert from 'node:assert'; const fsq = new QlobberFSQ({ fsq_dir: '/tmp/fsq-test', deliv_order: 'random' }); fsq.subscribe('test.#', (data, info) => { console.log(`Received on ${info.topic}: ${data.toString()}`); assert.strictEqual(info.topic, 'test.bar'); assert.strictEqual(data.toString(), 'hello'); }); fsq.on('start', () => { fsq.publish('test.bar', 'hello'); // cleanup after short delay setTimeout(() => fsq.stop_watching(), 100); }); fsq.on('stop', () => { console.log('Cleanup complete'); });

Debug

Known issues

breakingIn v9.0.0, the `QlobberFSQ` constructor options changed: `order_by_expiry` was removed; use `deliv_order` instead.

fix

Replace `order_by_expiry: true` with `deliv_order: 'by_expiry'`.

affects: >=9.0.0 <14.0.0

breakingIn v11.0.0, the module switched to named ESM export; `require('qlobber-fsq')` no longer returns the constructor.

fix

Use `const { QlobberFSQ } = require('qlobber-fsq')` instead of `const QlobberFSQ = require('qlobber-fsq')`.

affects: >=11.0.0

deprecatedThe `stop_watching()` method is deprecated in v14.0.0; use `close()` instead.

fix

Replace `fsq.stop_watching()` with `fsq.close()`.

affects: >=14.0.0

gotchaWhen using the streaming interface, the handler MUST set `handler.accept_stream = true` to be called with a readable stream.

fix

Define the handler function and set `.accept_stream = true` before subscribing.

affects: >=1.0.0

gotchaMessage ordering is not guaranteed across subscribers unless `deliv_order` is set to `'by_expiry'` and messages are published with explicit expiry times.

fix

If ordering is required, set `deliv_order: 'by_expiry'` in constructor and ensure each publish call includes an `expiry` option (milliseconds).

affects: >=1.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Using CommonJS require() to load the ESM entry point of qlobber-fsq v11+.

fix

Use `const { QlobberFSQ } = require('qlobber-fsq')` or switch to ESM `import { QlobberFSQ } from 'qlobber-fsq'`.

TypeError: QlobberFSQ is not a constructor

Using `import QlobberFSQ from 'qlobber-fsq'` (default import) which is incorrect because the package exports only named export.

fix

Use `import { QlobberFSQ } from 'qlobber-fsq'` (named import).

Error: ENOENT: no such file or directory, mkdir '/shared/fsq'

The `fsq_dir` directory does not exist or is not writable.

fix

Ensure the directory exists and the process has write permissions. For example, use a `tmp` folder: `{ fsq_dir: '/tmp/fsq-test' }`.

Error: Unexpected data after publish: stream not expected

Attempting to write to a stream returned by publish() without subscribing with a stream handler.

fix

Add `handler.accept_stream = true` on the subscriber handler function, or use the non-stream publish signature `publish(topic, payload, ...)`.

Upgrade

Version history

14.0.0latest on npm

Audit

Dependencies

qlobberrequiredCore matching engine for topic wildcards

tmprequiredTemporary file creation for atomic writes

semveroptionalVersion checks for filesystem lock files

Agent activity

28 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/davedoesdev/qlobber-fsq ↗

packageqlobber-fsq ↗

homepagehttps://github.com/davedoesdev/qlobber-fsq ↗