# Sidequest.js - Distributed Job Queue for Node.js

Sidequest.js is a modern, scalable background job processor for Node.js applications. Built with TypeScript, it is designed for production use, offering reliable job processing with support for multiple database backends, a beautiful web dashboard, and comprehensive monitoring capabilities.

For full documentation, visit https://docs.sidequestjs.com.
For the GitHub repository: https://github.com/sidequestjs/sidequest
Homepage: https://sidequestjs.com/

---

## Key Features

- High Performance: Worker threads for non-blocking job processing
- Multiple Backends: Supports SQLite, PostgreSQL, and MySQL out of the box
- ESM and CJS Support: Fully compatible with modern JavaScript environments
- TypeScript Support: Run TypeScript jobs natively on Node.js >= 24
- Web Dashboard: Monitor jobs and queues with a beautiful dashboard
- Queue Management: Multiple queues with configurable workers and priorities
- Job Lifecycle Management: Retries with exponential backoff, snooze, and fail mechanisms
- Scheduled Jobs: Schedule jobs to run at specific times
- Job Uniqueness: Prevent duplicate jobs with flexible uniqueness constraints
- CLI Tools: Command-line interface for migrations and management
- Monorepo Architecture: Modular packages for flexible deployment

---

## Usage Examples

### 1. Define a Job

```typescript
import { Job } from "sidequest";

export class EmailJob extends Job {
  async run(to, subject, body) {
    console.log(`Sending email to ${to}: ${subject}`);
    // Your email sending logic here
    return { sent: true, timestamp: new Date() };
  }
}
```

### 2. Configure and Start Sidequest

```typescript
import { Sidequest } from "sidequest";

await Sidequest.start({
  backend: {
    driver: "@sidequest/postgres-backend",
    config: "postgres://postgres:postgres@localhost:5432",
  },
});

console.log("Sidequest started! Dashboard: http://localhost:8678");
```

### 3. Enqueue Jobs

```typescript
import { Sidequest } from "sidequest";
import { EmailJob } from "./jobs/EmailJob.js";

await Sidequest.build(EmailJob).enqueue("user@example.com", "Welcome!", "Thanks for signing up!");
```

---

## Why Choose Sidequest.js

Traditional Node.js schedulers like node-cron and node-schedule work well for simple, process-level job scheduling, but quickly run into limitations in distributed environments. If you scale your application across multiple servers, scheduled jobs run multiple times unless you build your own distributed lock—adding operational complexity and risk.

These schedulers also execute jobs in the main thread, risking blocked APIs and poor responsiveness when tasks perform blocking I/O.

Sidequest.js solves these problems head-on:

- Distributed, Reliable Execution: Coordinates jobs across multiple nodes using your existing database (PostgreSQL, MySQL, SQLite), guaranteeing each job runs only once—even in multi-instance deployments.
- Worker Thread Isolation: Runs heavy jobs in separate worker threads, keeping your main application thread responsive.
- Developer Experience: Define a job class, enqueue, and let Sidequest.js handle persistence, distribution, retries, and isolation with minimal configuration.
- No External Brokers Required: Unlike Airflow, RabbitMQ, or SQS, Sidequest.js doesn’t require you to manage separate queueing infrastructure, orchestration systems, or cloud services. It runs entirely within your stack, with no vendor lock-in.
- Full Control and Transparency: You get complete control over job execution, retries (with exponential backoff), scheduling, and deduplication—without the operational cost of RabbitMQ or the complexity of Airflow.
- Easy Local Development: Develop and test locally, without emulating cloud services or setting up complex brokers.

### How does Sidequest.js compare to RabbitMQ, Airflow, and others?

- RabbitMQ & Kafka: These message brokers excel at throughput and decoupling producers/consumers, but require separate infrastructure, complex configuration, and are optimized for message delivery—not job durability, retries, or deduplication. If you just need robust background job processing, they’re overkill and add operational overhead.
- Airflow: Great for complex workflow orchestration with DAGs, but introduces a heavy Python-centric operational footprint. For most Node.js apps, it’s overkill: you don’t want another stack just for background jobs.
- AWS SQS & cloud-native queues: Convenient if you’re all-in on a cloud provider, but introduce vendor lock-in and eventual consistency. Handling distributed locking or deduplication often means glue code and extra services. Simple needs quickly spiral into complex architectures.
- Traditional Schedulers: node-cron, node-schedule, and similar libraries are easy to start with but lack coordination, reliability, and scalability when your app grows.

Sidequest.js takes a different approach:
- Runs inside your Node.js stack, using the database you already maintain.
- No external brokers, cloud services, or orchestration systems required.
- Guarantees job uniqueness and reliability.
- Transparent, expressive API for developers.

Ready to scale background tasks the right way?  
Try Sidequest.js for a cleaner, safer, and more scalable approach to Node.js job processing.

Learn more: https://github.com/sidequestjs/sidequest