sidequest

Sidequest

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

For the complete documentation, visit docs.sidequestjs.com.

For a comprehensive FAQ, visit docs.sidequestjs.com/faq.

✨ Features

• 🚀 High Performance - Worker threads for non-blocking job processing
• 🗄️ Multiple Backends - SQLite, PostgreSQL, MySQL support out of the box
• ✅ ESM and CJS support - Fully compatible with modern JavaScript
• 📝 Support for Typescript - Supports TypeScript jobs by default if you are using Node.js >= v23.6.0
• 📊 Web Dashboard - Beautiful, responsive dashboard for monitoring jobs and queues
• 🎯 Queue Management - Multiple queues with configurable workers and priorities
• 🫀 Job Lifecycle Management - Configurable retry with exponential backoff, snooze, and fail mechanisms
• ⏰ Scheduled Jobs - Support for scheduling jobs to run at specific times
• 🔒 Job Uniqueness - Prevent duplicate jobs with flexible uniqueness constraints
• 🛠️ CLI Tools - Command-line interface for database migrations and management
• 🏗️ Monorepo Architecture - Modular packages for flexible deployment

📦 Installation

To get started with Sidequest, first install the main package:

npm install sidequest
# or
yarn add sidequest

To keep the application minimal, the main package does not include the backend drivers. Thus you need to install only the driver you will use:

PostgreSQL (recommended)

npm install @sidequest/postgres-backend
# or
yarn add @sidequest/postgres-backend

SQLite (default - not recommended for production)

npm install @sidequest/sqlite-backend
# or
yarn add @sidequest/sqlite-backend

MySQL

npm install @sidequest/mysql-backend
# or
yarn add @sidequest/mysql-backend

⚙️ Usage

1. Create a Job class

// jobs/EmailJob.js
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

// app.js
import { Sidequest } from "sidequest";

// Start Sidequest
await Sidequest.start({
  // You can leave the config empty to use the default SQLite backend.
  // Make sure to install the SQLite backend driver if you want to use it.
  backend: {
    driver: "@sidequest/postgres-backend",
    config: "postgres://postgres:postgres@localhost:5432",
  },
});

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

3. Enqueue Jobs

// Somewhere in your application
import { Sidequest } from "sidequest";
import { EmailJob } from "./jobs/EmailJob.js";

// Simple job
await Sidequest.build(EmailJob).enqueue("[e-mail]", "Welcome!", "Thanks for signing up!");

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

📄 License

This project is licensed under the LGPL-3.0-or-later license.

🆘 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Made with ❤️ by Lucas Merencia and Giovani Guizzo