node-sidekiq-client/README.md

Sidekiq client for nodejs

# 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](https://github.com/sidekiq/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:

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

## Installation

```bash
npm install node-sidekiq-client
```

## Usage

### Initialize the client

```js
// 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

```js
const jid = await client.performAsync(
  "default",
  "EmailWorker",
  [{ to: "user@example.com", subject: "Welcome!" }],
  { retry: false }
);

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

---

### Schedule a job after a delay

```js
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

```js
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:

```bash
npm install
npm test
```

Tests are located in the `tests/` directory and use [Jest](https://jestjs.io/).

---

## 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](./LICENSE) file for details.