{"id":47719,"library":"fsqu","title":"FSqu: Filesystem-backed job queue","description":"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.","status":"active","version":"1.1.3","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","queue","job","fs","filesystem","schedule"],"install":[{"cmd":"npm install fsqu","lang":"bash","label":"npm"},{"cmd":"yarn add fsqu","lang":"bash","label":"yarn"},{"cmd":"pnpm add fsqu","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for debugging output (DEBUG=fsqu:*)","package":"debug","optional":true},{"reason":"Used in quickstart example for flow control, not a runtime dependency","package":"async","optional":true}],"imports":[{"note":"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)`.","wrong":"import FSqu from 'fsqu'; // CommonJS only, no ESM exports","symbol":"FSqu","correct":"const FSqu = require('fsqu');"},{"note":"The constructor is `FSqu.fsqu`. The module exports an object with an `fsqu` property.","wrong":"const q = new FSqu({ name: 'myqueue' }); // FSqu is the module, not the constructor. Use FSqu.fsqu","symbol":"fsqu constructor","correct":"const q = new FSqu.fsqu({ name: 'myqueue', path: '/tmp/queues' });"},{"note":"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.","wrong":"q.pushData('data', callback); // Missing opts object – will error if second arg is not an object or function","symbol":"q.pushData","correct":"q.pushData('data', { delay: 1000 }, callback);"}],"quickstart":{"code":"const FSqu = require('fsqu');\nconst async = require('async');\nconst fs = require('fs');\n\nconst fsqu = new FSqu.fsqu({\n  name: 'a-test-queue',\n  path: '/tmp/fsqu/test-queues-with-fsqu',\n  landing: '/tmp/fsqu/landing'\n});\n\nasync.series([\n  cb => fsqu.init(cb),\n  cb => fsqu.pushData('contents of file #1', cb),\n  cb => fsqu.pushData('contents of file #2', cb),\n  cb => fsqu.pop(cb),\n  cb => fsqu.pop(cb),\n], (err, res) => {\n  if (err) console.error(err);\n  console.log(fs.readFileSync(res[3].loc, { encoding: 'utf8' }));\n  console.log(fs.readFileSync(res[4].loc, { encoding: 'utf8' }));\n  fsqu.end(err => console.log('all done', err));\n});","lang":"javascript","description":"Demonstrates queue initialization, pushing data, popping entries, and reading the landing location."},"warnings":[{"fix":"Do not rely on strict ordering. Use if order is critical.","message":"No FIFO guarantees: insertion order is mostly kept but not guaranteed.","severity":"gotcha","affected_versions":"all"},{"fix":"Set `landing` to a directory on the same filesystem as the queue to avoid cross-device moves.","message":"The `pop()` operation moves the file to the landing directory, not copies. Ensure the landing directory is on the same filesystem.","severity":"gotcha","affected_versions":"all"},{"fix":"Always pass a callback function to pushData, pushStream, pushFile.","message":"The `pushData` callback signature: `cb` is mandatory and must be a function. Omitting it causes an error.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Ensure id contains only lowercase alphanumeric characters.","message":"The `id` option for push operations must match regex `^([0-9a-z]+)$`. Failing to do so results in an error.","severity":"gotcha","affected_versions":"all"},{"fix":"Always call `q.init(callback)` before using the queue.","message":"Queue initialization (`init`) must be called before any push/pop operations.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'1.1.3':30 'addit':57 'at-least-onc':48 'at-most-onc':43 'back':4 'beyond':92 'constant':82 'constant-tim':81 'core':94 'debug':75 'delays/scheduling':42 'deliveri':52 'depend':91 'design':62 'differenti':80 'direct':55 'directori':22 'element':25 'extern':90 'file':28,56,71 'filesystem':3,16,104 'filesystem-back':2 'frequent':38 'fs':103 'fsqu':1,7 'handl':69 'implement':8 'javascript':100 'job':5,9,102 'key':79 'larg':70 'latest':33 'least':50 'log':78 'machin':66 'model':53 'modul':76,95 'mv':59 'node.js':93 'oper':84 'pipelin':67 'process':98 'queue':6,10,19,87,101 'regardless':85 'regular':15 'releas':35 'restart':99 'schedul':105 'singl':65 'single-machin':64 'size':88 'stabl':34 'support':41 'surviv':97 'time':83 'top':12 'updat':39 'use':73 'version':29 'via':58","created_at":"2026-06-07T16:52:57.252410+00:00","updated_at":"2026-06-07T16:52:57.252410+00:00","problems":[{"fix":"Use `new FSqu.fsqu(opts)` instead.","cause":"Using `new FSqu(opts)` incorrectly; FSqu is an object, not the constructor itself.","error":"TypeError: FSqu is not a constructor"},{"fix":"Always pass a function as the last argument to pushData/pushStream/pushFile.","cause":"Omitting the callback or passing a non-function to pushData.","error":"TypeError: cb is not a function"},{"fix":"Use only lowercase letters and digits (0-9, a-z) for id.","cause":"The `id` option does not match the required regex.","error":"Error: invalid id"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://codeberg.org/pepmartinez/fsqu","github":null,"docs":null,"changelog":null,"pypi":null,"npm":"fsqu","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}