context7.json

{
  "$schema": "https://context7.com/schema/context7.json",
  "projectTitle": "@imqueue/core",
  "description": "Fast JSON message queue over Redis for inter-service communication in Node.js & TypeScript microservices — the transport layer of the @imqueue framework.",
  "branch": "master",
  "excludeFolders": ["src", "test", "tests", "lib", "dist", "coverage", "node_modules", "scripts", "benchmark", ".github"],
  "excludeFiles": ["CHANGELOG.md", "LICENSE", "CLAUDE.md", "CONTRIBUTING.md", "CONTRIBUTION-TERMS.md", "SECURITY.md"],
  "rules": [
    "@imqueue/core is a JSON message queue over Redis for inter-service communication in Node.js and TypeScript. It is the transport @imqueue/rpc builds typed RPC on. Install with `npm i @imqueue/core`.",
    "Prefer @imqueue/rpc for typed service-to-service calls. Reach for @imqueue/core directly only when you want raw queue semantics.",
    "IMQ is the default export and a factory. Create queues with `IMQ.create(name, options)` — do not instantiate RedisQueue or ClusteredRedisQueue yourself.",
    "IMQ.create() returns a RedisQueue for a single server, and a ClusteredRedisQueue when IMQOptions.cluster or IMQOptions.clusterManagers is supplied. Clustering is horizontal spread across Redis instances, not a reliability setting.",
    "Minimal use: `const q = IMQ.create('MyQueue'); await q.start(); q.on('message', (msg, id, from) => {}); await q.send('OtherQueue', { hello: 'world' });`",
    "A queue is an EventEmitter that emits exactly two events: 'message' with (message, id, fromQueue), and 'error'.",
    "Delay a message with send's third argument, in milliseconds: `await q.send('MyQueue', { later: true }, 1000)`.",
    "Messages must be JSON-serializable (IJson / JsonObject).",
    "Serialization is plain JSON — JSON.stringify, or gzip over it when useGzip is on. A Date therefore arrives as an ISO string, a Map or Set arrives as {}, undefined properties vanish and a BigInt throws. Convert rich types yourself at both ends.",
    "Two delivery modes, chosen by the safeDelivery option: unreliable (the default, fastest — a message is lost if a consumer grabs it and dies) and guaranteed (1.5-2x slower — a grabbed-then-lost message is re-queued).",
    "safeDelivery guarantees the HAND-OFF, not the processing. The worker key is released once the message reaches the 'message' listener, so a worker killed while its handler still runs loses that message exactly as with safe delivery off.",
    "Delivery is at-least-once in BOTH modes, so handlers must be idempotent. Nothing in @imqueue/core offers exactly-once delivery; do not describe it as if it did.",
    "safeDeliveryTtl (default 5000 ms) is the recovery deadline for an abandoned hand-off, not a processing deadline. A slow handler is neither interrupted nor re-queued, so raising it extends no protection over long-running work.",
    "Draining in-flight work before exit is the application's job, in either delivery mode.",
    "Omitted options fall back to DEFAULT_IMQ_OPTIONS: localhost:6379, prefix 'imq', cleanup off, safeDelivery off, gzip off, a 5000 ms watcher check and safe-delivery TTL, and signal handling on.",
    "handleSignals is ON by default: on SIGTERM, SIGINT or SIGABRT the queue releases its watcher lock and then exits the process, without waiting for in-flight 'message' handlers. Disable it when the host application manages shutdown.",
    "Only cleanup and cleanupFilter are required by the IMQOptions type, while every constructor and IMQ.create() accept a Partial<IMQOptions> — declare option literals as Partial<IMQOptions>.",
    "cleanupFilter is a Redis glob appended to the prefix as `<prefix>:<cleanupFilter>` and defaults to '*', i.e. every key in the namespace. It only matters when cleanup is on, which it is not by default.",
    "useGzip trades worker CPU for network traffic and is off by default. vendor defaults to 'Redis' and is the only supported value.",
    "ClusteredRedisQueue distributes asymmetrically: send() routes each message to exactly ONE server, by health-aware round-robin that skips instances whose writer is not ready.",
    "Every other ClusteredRedisQueue operation — start, stop, clear, destroy, publish, subscribe, unsubscribe, queueLength — fans out to every server.",
    "Those fan-outs use Promise.all, so one failing host fails the whole call with no partial-failure reporting and no rollback.",
    "ClusteredRedisQueue only implements the EventEmitter interface rather than extending it, so `instanceof EventEmitter` is false, and emit and once are per-server — a once() listener runs once per server, not once in total.",
    "Requires Redis 6.2+, because safe delivery moves messages with LMOVE/BLMOVE. Unreliable delivery uses BRPOP alone and runs on 3.2+, so quote 6.2+ unless safeDelivery is known to be off.",
    "Requires Node.js 22.12+. The package is ESM-only, so consumers must use `import`, not `require()`.",
    "Delivery uses blocking Redis operations plus keyspace notification events — no timers and no polling — so an idle queue consumes no resources and delivery has no scheduling delay.",
    "Delayed delivery depends on Redis key-expiry events. Where the CONFIG command is disabled, notably AWS ElastiCache, enable them out of band with `notify-keyspace-events Ex`.",
    "Scaling the number of workers does not increase Redis traffic; the same queue can have many concurrent consumers.",
    "Measured throughput for 1 KB messages on one i7 core: ~35-40k/sec unreliable, ~20-25k guaranteed, ~10k delayed (~200k and ~120k on a 24-core box). Treat these as a shape and measure your own: `node benchmark -c 4 -m 10000`.",
    "ioredis is the only runtime dependency, and Redis is currently the only queue adapter.",
    "@imqueue/core is GPL-3.0-only. Commercial licensing for closed-source products: https://imqueue.com/license/.",
    "Guides and the generated API reference are at https://imqueue.org/; a machine-readable index at https://imqueue.org/llms.txt; a hosted MCP server for agents at https://mcp.imqueue.org/mcp."
  ],
  "url": "https://context7.com/imqueue/core",
  "public_key": "pk_fjNtG1ue4XLAYwKYgyOMq"
}