node-sidekiq-client

Redis client for dispatching Sidekiq-compatible jobs from Node.js.

Description

This library lets you enqueue jobs into Redis in the same format expected by Sidekiq, a background job processor for Ruby.

Features

• performAsync – enqueue job immediately
• performIn – schedule job after a delay (in milliseconds)
• performAt – schedule job at a specific Unix timestamp in milliseconds

Jobs are serialized as Sidekiq-compatible JSON payloads:

{
  "class": "MyWorker",
  "queue": "default",
  "args": [ ... ],
  "jid": "abc123...",
  "created_at": 1717291569.153,
  "enqueued_at": 1717291569.153,
  "retry": false
}

Installation

npm install node-sidekiq-client

Usage

Initialize the client

// Option A: using Redis URL
const { SidekiqClient } = require("node-sidekiq-client");
const client = new SidekiqClient("redis://localhost:6379/0");

// Option B: using an existing Redis client
const { createClient } = require("redis");
const redis = createClient({ url: "redis://localhost:6379/0" });
await redis.connect();
const client = new SidekiqClient(redis);

Enqueue a job immediately

const jid = await client.performAsync(
  "default",
  "EmailWorker",
  [{ to: "[email protected]", subject: "Welcome!" }],
  { retry: false }
);

console.log(`Enqueued job with JID: ${jid}`);

Schedule a job after a delay

const jid = await client.performIn(
  30000, // 30 seconds in milliseconds
  "low",
  "CleanupWorker",
  [{ path: "/tmp/cache" }],
  { retry: true }
);

console.log(`Scheduled job with JID: ${jid}`);

Schedule a job at a specific time

const timestamp = new Date("2025-06-10T10:00:00Z").getTime(); // milliseconds

await client.performAt(
  timestamp,
  "reports",
  "DailyReportWorker",
  [{ date: "2025-06-09" }],
  { retry: false }
);

API Reference

new SidekiqClient(redis: string | RedisClientType | RedisClientPoolType)

• redis: A Redis URL string ("redis://...") or a connected Redis client instance.
• Automatically connects if a string is provided.

performAsync(queue, jobClass, args, options?) => Promise<string>

• queue (string): Name of the Redis queue.
• jobClass (string): Name of the Sidekiq worker class.
• args (any[]): Array of JSON-serializable arguments.
• options (object, optional): Additional Sidekiq options like retry, backtrace, etc.
• Returns a 24-character hex job ID (jid).

performIn(msFromNow, queue, jobClass, args, options?) => Promise<string>

• msFromNow (number): Delay in milliseconds from now.
• Other arguments same as performAsync.
• Adds job to Redis "schedule" sorted set with appropriate score.

performAt(unixTimestampMs, queue, jobClass, args, options?) => Promise<string>

• unixTimestampMs (number): Unix timestamp in milliseconds (e.g., Date.now()).
• Other arguments same as performAsync.
• Adds job to Redis "schedule" sorted set at exact given time.

Testing

Run tests with Redis running locally:

npm install
npm test

Tests are located in the tests/ directory and use Jest.

Contributing

1. Fork this repository
2. Create a feature branch
3. Add your feature or bugfix with tests
4. Open a pull request

License

See LICENSE file for details.