Sidequest.js

https://docs.sidequestjs.com
Admin
Sidequest.js is a robust, distributed job processing system for Node.js, offering cloud and database...
Tokens:43,148
Snippets:207
Trust Score:6.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Sidequest CLI Quick Start

Source: https://docs.sidequestjs.com/cli

A three-step guide to get started with the Sidequest CLI: configuring the backend connection, running database migrations, and starting Sidequest.

```bash
# 1. Configure your backend connection
sidequest config
# 2. Run database migrations
sidequest migrate
# 3. Start using Sidequest in your application
```

--------------------------------

### Start Sidequest Engine

Source: https://docs.sidequestjs.com/quick-start

Initializes and starts the Sidequest engine with default configurations. This code snippet demonstrates how to import the Sidequest class and call the `start` method to get the engine running. It also logs the dashboard URL.

```typescript
// app.js
import { Sidequest } from "sidequest";
// Quick start Sidequest with default settings and Dashboard enabled
await Sidequest.start();
console.log("Sidequest started! Dashboard: http://localhost:8678");
```

--------------------------------

### Install Dependencies

Source: https://docs.sidequestjs.com/examples

Installs the necessary Node.js dependencies for the Sidequest project using Yarn.

```bash
yarn install
```

--------------------------------

### Enqueue a Job

Source: https://docs.sidequestjs.com/quick-start

Demonstrates how to enqueue a job using Sidequest. It involves importing the Sidequest class and the custom Job class, then using `Sidequest.build()` to create a job instance and `enqueue()` to add it to the queue. This example enqueues an `EmailJob`.

```typescript
// Somewhere in your application
import { Sidequest } from "sidequest";
import { EmailJob } from "./jobs/EmailJob.js";
// Simple job
await Sidequest.build(EmailJob).enqueue("user@example.com", "Welcome!", "Thanks for signing up!");
```

--------------------------------

### Hello World Main Application

Source: https://docs.sidequestjs.com/examples

Starts the Sidequest engine with default configuration and enqueues an instance of 'HelloJob' with the parameter 'John Doe'. This illustrates how to initiate Sidequest and dispatch jobs.

```ts
import { Sidequest } from "sidequest";
import { HelloJob } from "./hello-job.js";
await Sidequest.start();
await Sidequest.build(HelloJob).enqueue("John Doe");
```

--------------------------------

### Start Sidequest with PostgreSQL Backend and Dashboard

Source: https://docs.sidequestjs.com/engine/starting

Launches Sidequest with a PostgreSQL backend and enables the dashboard. This example demonstrates providing custom configuration for the backend driver, connection string, and dashboard port.

```typescript
import { Sidequest } from "sidequest";
await Sidequest.start({
  backend: {
    driver: "@sidequest/postgres-backend",
    config: "postgresql://postgres:postgres@localhost:5432/postgres",
  },
  dashboard: {
    enabled: true,
    port: 8678,
  },
});
console.log("Sidequest is running!");
```

--------------------------------

### Production Startup Configuration

Source: https://docs.sidequestjs.com/engine/starting

Starts the Sidequest engine with production-specific configurations, including backend setup, queue definitions, job limits, logging level, and dashboard authentication.

```typescript
await Sidequest.start({
  backend: {
    driver: "@sidequest/postgres-backend",
    config: process.env.DATABASE_URL,
  },
  queues: [
    { name: "default", concurrency: 5, priority: 50 },
    { name: "critical", concurrency: 10, priority: 100 },
  ],
  maxConcurrentJobs: 20,
  logger: {
    level: "info",
    json: true,
  },
  dashboard: {
    enabled: true,
    port: parseInt(process.env.DASHBOARD_PORT || "8678"),
    auth: {
      user: process.env.DASHBOARD_USER!,
      password: process.env.DASHBOARD_PASSWORD!,
    },
  },
});
```

--------------------------------

### Development Setup Example

Source: https://docs.sidequestjs.com/engine/configuration

An example configuration for development environments. It uses verbose debug logging, disables JSON formatting for easier readability, and enables the dashboard without authentication for local testing. It defaults to a SQLite backend for simplicity.

```typescript
import { Sidequest } from "sidequest";
await Sidequest.start({
  logger: {
    level: "debug", // Verbose logging for development
    json: false,
  },
  dashboard: {
    enabled: true,
    port: 3000,
    // No auth for local development
  },
  // Use default SQLite backend for easy setup
});
```

--------------------------------

### Start Sidequest with Default SQLite Backend

Source: https://docs.sidequestjs.com/engine/starting

Initiates the Sidequest job processing system using the default SQLite backend. This is a simple way to get started without explicit configuration.

```typescript
import { Sidequest } from "sidequest";
await Sidequest.start();
```

--------------------------------

### Build Examples

Source: https://docs.sidequestjs.com/examples

Builds the example applications for Sidequest.js.

```bash
yarn build:examples
```

--------------------------------

### Development Sidequest Engine Startup

Source: https://docs.sidequestjs.com/engine/starting

Shows a typical startup configuration for a development environment. This setup might include enabling the dashboard and setting a verbose logging level for easier debugging.

```javascript
import Sidequest from '@sidequest/sidequest';

async function startDevelopmentEngine() {
  await Sidequest.start({
    workers: 1, // Single worker for development
    dashboard: {
      enabled: true,
      port: 3000
    },
    logging: {
      level: 'debug'
    }
  });
  console.log('Sidequest engine started in development mode!');
}

startDevelopmentEngine();
```

--------------------------------

### Run Example

Source: https://docs.sidequestjs.com/examples

Executes a specific Sidequest example application using Node.js.

```bash
node examples/dist/01-hello-world/index.js
```

--------------------------------

### Partial Sidequest Setup

Source: https://docs.sidequestjs.com/engine/index

Demonstrates how to partially set up Sidequest to enable enqueueing jobs without starting the full job processing. This is useful for scenarios where only enqueueing is needed.

```javascript
import Sidequest from 'sidequestjs';

// Partially configure Sidequest to allow enqueueing without processing
Sidequest.configure({
  // ... other configuration options if needed
});

// Now you can enqueue jobs without starting the full engine
// Sidequest.enqueue('jobName', { data: '...' });
```

--------------------------------

### Production Setup Example

Source: https://docs.sidequestjs.com/engine/configuration

Demonstrates a typical production configuration for SidequestJS. It uses a PostgreSQL backend, defines multiple queues with specific priorities and concurrency, sets a maximum of concurrent jobs, enables structured JSON logging, and configures the dashboard with authentication.

```typescript
import { Sidequest } from "sidequest";
await Sidequest.start({
  backend: {
    driver: "@sidequest/postgres-backend",
    config: process.env.DATABASE_URL,
  },
  queues: [
    { name: "default", concurrency: 5, priority: 50 },
    { name: "critical", concurrency: 10, priority: 100 },
    { name: "emails", concurrency: 2, priority: 30 },
  ],
  maxConcurrentJobs: 20,
  logger: {
    level: "info",
    json: true, // Structured logging for production
  },
  dashboard: {
    enabled: true,
    port: parseInt(process.env.DASHBOARD_PORT || "8678"),
    auth: {
      user: process.env.DASHBOARD_USER!,
      password: process.env.DASHBOARD_PASSWORD!,
    },
  },
});
```

--------------------------------

### Minimal Sidequest Engine Startup

Source: https://docs.sidequestjs.com/engine/starting

Demonstrates the most basic way to start the Sidequest engine. This configuration is suitable for simple use cases or development environments where advanced options are not required.

```javascript
import Sidequest from '@sidequest/sidequest';

async function startEngine() {
  await Sidequest.start();
  console.log('Sidequest engine started successfully!');
}

startEngine();
```

--------------------------------

### MySQL Connection String Examples

Source: https://docs.sidequestjs.com/cli

Examples of connection strings for MySQL, including local, remote, and SSL configurations.

```bash
# Local MySQL
mysql://root:password@localhost:3306/sidequest
# Remote MySQL
mysql://user:password@mysql.example.com:3306/sidequest
# MySQL with SSL
mysql://user:password@localhost:3306/sidequest?ssl=true
```

--------------------------------

### SideQuestJS Engine Documentation Overview

Source: https://docs.sidequestjs.com/engine/index

Provides an overview of the SideQuestJS engine's documentation, linking to specific guides for configuration, starting, enqueuing jobs, graceful shutdown, and cleanup. It also references broader system documentation for jobs, queues, and the dashboard.

```APIDOC
SideQuestJS Engine Guides:

Configuration:
  - Detailed configuration options and backend setup.
  - Link: https://docs.sidequestjs.com/engine/configuration

Starting:
  - Engine startup process and initialization.
  - Link: https://docs.sidequestjs.com/engine/starting

Enqueue:
  - Job building and enqueuing patterns.
  - Link: https://docs.sidequestjs.com/engine/enqueue

Graceful Shutdown:
  - Proper shutdown procedures.
  - Link: https://docs.sidequestjs.com/engine/graceful-shutdown

Cleanup:
  - Maintenance and cleanup operations.
  - Link: https://docs.sidequestjs.com/engine/cleanup

Broader System Documentation:

Jobs:
  - Creating and managing job classes.
  - Link: https://docs.sidequestjs.com/jobs/index

Queues:
  - Queue concepts and management.
  - Link: https://docs.sidequestjs.com/queues/index

Dashboard:
  - Web interface for monitoring and management.
  - Link: https://docs.sidequestjs.com/dashboard

Navigation:
  - Previous: Concurrency (https://docs.sidequestjs.com/queues/concurrency)
  - Next: Configuration (https://docs.sidequestjs.com/engine/configuration)

License:
  - LGPL-3.0 License

Copyright:
  - © 2025 Lucas Merencia and Giovani Guizzo
```

--------------------------------

### Basic Sidequest.js Job Implementation

Source: https://docs.sidequestjs.com/jobs

Provides a fundamental example of creating a job in Sidequest.js. It shows extending the `Job` class and implementing the `run` method with business logic, including handling different actions and throwing errors.

```typescript
import { Job } from "@sidequest/engine";
import { getUserById, sendWelcomeEmail } from "./myAwesomeApp";
export class ProcessUserJob extends Job {
  async run(userId: number, action: string) {
    // Your business logic here
    const user = await getUserById(userId);
    if (action === "send_welcome_email") {
      await sendWelcomeEmail(user.email);
      return { emailSent: true, userId };
    }
    throw new Error(`Unknown action: ${action}`);
  }
}
```

--------------------------------

### Create an Email Job

Source: https://docs.sidequestjs.com/quick-start

Defines a custom Job class for sending emails. This class extends the base Job class from Sidequest and implements the `run` method to handle the email sending logic. It accepts recipient, subject, and body as arguments.

```typescript
// 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() };
  }
}
```

--------------------------------

### Production Sidequest Engine Startup

Source: https://docs.sidequestjs.com/engine/starting

Illustrates a production-ready configuration for starting the Sidequest engine. This includes setting up multiple worker processes, enabling the dashboard, and configuring logging for robust operation.

```javascript
import Sidequest from '@sidequest/sidequest';

async function startProductionEngine() {
  await Sidequest.start({
    workers: 4, // Number of worker processes
    dashboard: {
      enabled: true,
      port: 3000
    },
    logging: {
      level: 'info'
    }
  });
  console.log('Sidequest engine started in production mode!');
}

startProductionEngine();
```

--------------------------------

### Main Application - Enqueue Job

Source: https://docs.sidequestjs.com/examples

Demonstrates how to start the Sidequest application and enqueue a `CountWordJob`. The job is configured to scrape the Node.js Wikipedia page and count the occurrences of the word 'package'.

```ts
import { Sidequest } from "sidequest";
import { CountWordJob } from "./count-word-job.js";
await Sidequest.start();
await Sidequest.build(CountWordJob).enqueue("https://en.wikipedia.org/wiki/Node.js", "package");
```

--------------------------------

### Sidequest Engine API Documentation

Source: https://docs.sidequestjs.com/engine

API documentation for the main Sidequest engine entry point, including configuration and starting the system.

```APIDOC
Sidequest:
  configure(options?: object)
    Configures the Sidequest engine with various options.
    Parameters:
      options: An object containing configuration settings for the engine and dashboard.

  start(options?: object)
    Starts the Sidequest engine, initiating job processing and optionally the dashboard.
    Parameters:
      options: An object containing configuration settings for the engine and dashboard.
      Example:
        Sidequest.start({ dashboard: { enabled: false } })

  job(jobName: string, callback: Function)
    Defines a new job with a given name and its execution logic.
    Parameters:
      jobName: The name of the job.
      callback: The function to execute when the job is processed.

  queue(queueName: string, options?: object)
    Defines a new queue with a given name and optional configuration.
    Parameters:
      queueName: The name of the queue.
      options: Configuration options for the queue, such as concurrency and priority.
```

--------------------------------

### PostgreSQL Connection String Examples

Source: https://docs.sidequestjs.com/cli

Examples of connection strings for PostgreSQL, including local, remote with SSL, and custom port configurations.

```bash
# Local PostgreSQL
postgresql://postgres:password@localhost:5432/sidequest
# Remote PostgreSQL with SSL
postgresql://user:password@db.example.com:5432/sidequest?sslmode=require
# PostgreSQL with custom port
postgresql://postgres:password@localhost:5433/sidequest
```

--------------------------------

### SideQuestJS Engine Documentation Overview

Source: https://docs.sidequestjs.com/engine

This section outlines the key documentation areas for the SideQuestJS engine. It covers configuration, starting the engine, enqueuing jobs, and handling graceful shutdowns and cleanup operations. Links to related guides provide more in-depth information on each topic.

```APIDOC
SideQuestJS Engine Documentation:

Related Guides:
  - Configuration: Detailed configuration options and backend setup.
  - Starting: Engine startup process and initialization.
  - Enqueue: Job building and enqueuing patterns.
  - Graceful Shutdown: Proper shutdown procedures.
  - Cleanup: Maintenance and cleanup operations.

Broader System Documentation:
  - Jobs: Creating and managing job classes.
  - Queues: Queue concepts and management.
  - Dashboard: Web interface for monitoring and management.

Navigation:
  - Previous: Concurrency documentation.
  - Next: Configuration documentation.

License:
  - LGPL-3.0 License.

Copyright:
  - © 2025 Lucas Merencia and Giovani Guizzo
```

--------------------------------

### Install PostgreSQL Backend

Source: https://docs.sidequestjs.com/engine/backends

Installs the PostgreSQL backend package for SidequestJS using npm.

```bash
npm install @sidequest/postgres-backend
```

--------------------------------

### MongoDB Connection String Examples

Source: https://docs.sidequestjs.com/cli

Examples of connection strings for MongoDB, including local, authenticated, and MongoDB Atlas configurations.

```bash
# Local MongoDB
mongodb://localhost:27017/sidequest
# MongoDB with authentication
mongodb://user:password@localhost:27017/sidequest
# MongoDB Atlas
mongodb+srv://user:password@cluster.mongodb.net/sidequest
```

--------------------------------

### Basic Sidequest.js Startup

Source: https://docs.sidequestjs.com/engine/configuration

Starts the Sidequest.js engine with default settings, automatically using the SQLite backend and enabling the dashboard. Ensure the appropriate backend driver (e.g., `@sidequest/sqlite-backend`) is installed.

```typescript
import { Sidequest } from "sidequest";
await Sidequest.start();
console.log("Sidequest started! Dashboard: http://localhost:8678");
```

--------------------------------

### Switching Backends: MySQL

Source: https://docs.sidequestjs.com/engine/configuration

Example configuration for using the MySQL backend with SidequestJS. This requires installing the `@sidequest/mysql-backend` package and providing a valid MySQL connection string.

```typescript
backend: {
  driver: "@sidequest/mysql-backend",
  config: "mysql://root:mysql@localhost:3306/testdb",
}
```

--------------------------------

### Switching Backends: PostgreSQL

Source: https://docs.sidequestjs.com/engine/configuration

Example configuration for using the PostgreSQL backend with SidequestJS. This requires installing the `@sidequest/postgres-backend` package and providing a valid PostgreSQL connection string.

```typescript
backend: {
  driver: "@sidequest/postgres-backend",
  config: "postgresql://postgres:postgres@localhost:5432/postgres",
}
```

--------------------------------

### Install Sidequest CLI with pnpm

Source: https://docs.sidequestjs.com/installation

Installs the Sidequest CLI tool globally using pnpm, enabling command-line management of backend migrations and configurations.

```bash
pnpm add -g @sidequest/cli
```

--------------------------------

### Install Sidequest CLI

Source: https://docs.sidequestjs.com/cli

Instructions for installing the Sidequest CLI globally using npm, yarn, or pnpm. This allows the CLI to be accessed from any directory.

```bash
npm install -g @sidequest/cli
```

```bash
yarn global add @sidequest/cli
```

```bash
pnpm add -g @sidequest/cli
```

--------------------------------

### Triggering API-Triggered Jobs

Source: https://docs.sidequestjs.com/examples

Provides bash commands to start the Express.js server and trigger an email sending job via a curl request.

```bash
# Start the server
npm run start
# Trigger a job
curl "http://localhost:3000/send-email?email=test@example.com"
```

--------------------------------

### Install MySQL Backend

Source: https://docs.sidequestjs.com/engine/backends

Installs the MySQL backend package for SidequestJS using npm.

```bash
npm install @sidequest/mysql-backend
```

--------------------------------

### SQLite Connection String Examples

Source: https://docs.sidequestjs.com/cli

Examples of connection strings for SQLite, including relative path, absolute path, and in-memory database.

```bash
# Relative path
./sidequest.sqlite
# Absolute path
/var/data/sidequest.sqlite
# In-memory (testing only)
:memory:
```

--------------------------------

### Install Sidequest CLI with npm

Source: https://docs.sidequestjs.com/installation

Installs the Sidequest CLI tool globally using npm, allowing for command-line management of backend migrations and configurations.

```bash
npm install -g @sidequest/cli
```

--------------------------------

### Install SQLite Backend

Source: https://docs.sidequestjs.com/engine/backends

Installs the SQLite backend package for SidequestJS using npm.

```bash
npm install @sidequest/sqlite-backend
```

--------------------------------

### Install PostgreSQL Backend Driver

Source: https://docs.sidequestjs.com/installation

Installs the PostgreSQL backend driver for Sidequest.js, recommended for production environments. Supports npm, yarn, and pnpm.

```bash
npm install @sidequest/postgres-backend
```

```bash
yarn add @sidequest/postgres-backend
```

```bash
pnpm add @sidequest/postgres-backend
```

--------------------------------

### Install MongoDB Backend

Source: https://docs.sidequestjs.com/engine/backends

Installs the MongoDB backend package for SidequestJS using npm.

```bash
npm install @sidequest/mongo-backend
```

--------------------------------

### Basic TypeScript Job Example

Source: https://docs.sidequestjs.com/jobs/index

Demonstrates how to create a basic job in TypeScript by extending the Job class and implementing the run method. This job processes user data and sends a welcome email based on a specified action. It requires the 'getUserById' and 'sendWelcomeEmail' functions from './myAwesomeApp'.

```typescript
import { Job } from "@sidequest/engine";
import { getUserById, sendWelcomeEmail } from "./myAwesomeApp";

export class ProcessUserJob extends Job {
  async run(userId: number, action: string) {
    // Your business logic here
    const user = await getUserById(userId);
    if (action === "send_welcome_email") {
      await sendWelcomeEmail(user.email);
      return { emailSent: true, userId };
    }
    throw new Error(`Unknown action: ${action}`);
  }
}
```

--------------------------------

### Install Sidequest CLI with yarn

Source: https://docs.sidequestjs.com/installation

Installs the Sidequest CLI tool globally using yarn, providing command-line capabilities for backend migrations and configurations.

```bash
yarn global add @sidequest/cli
```

--------------------------------

### Development Startup Configuration

Source: https://docs.sidequestjs.com/engine/starting

Starts the Sidequest engine with development-focused configurations, enabling verbose logging and disabling dashboard authentication for local use.

```typescript
await Sidequest.start({
  logger: {
    level: "debug", // Verbose logging
    json: false, // Human-readable logs
  },
  dashboard: {
    enabled: true,
    port: 3000,
    // No auth for local development
  },
});
```

--------------------------------

### SQLite Connection Examples

Source: https://docs.sidequestjs.com/engine/backends

Provides examples of different connection string formats for the SQLite backend.

```typescript
// File-based SQLite
config: "./data/sidequest.sqlite";
// Absolute path
config: "/var/lib/sidequest/jobs.db";
// In-memory database (testing only)
config: ":memory:";
```

--------------------------------

### Build Sidequest from Source

Source: https://docs.sidequestjs.com/development

Steps to clone the repository, install dependencies, and build all packages for Sidequest.js.

```bash
git clone https://github.com/sidequestjs/sidequest.git
cd sidequest
corepack enable
yarn install
yarn build
```

--------------------------------

### Start Sidequest Engine and Dashboard

Source: https://docs.sidequestjs.com/engine/index

Starts the Sidequest engine, including job processing and the monitoring dashboard. Can be called after `configure` without parameters.

```typescript
import { Sidequest } from "sidequest";
await Sidequest.start({
  backend: {
    driver: "@sidequest/postgres-backend",
    config: process.env.DATABASE_URL,
  },
  dashboard: {
    port: 3000,
    auth: {
      username: "admin",
      password: "secure-password",
    },
  },
});
console.log("Sidequest started! Dashboard: http://localhost:3000");
```

--------------------------------

### Sidequest Basic Custom Configuration

Source: https://docs.sidequestjs.com/engine/configuration

Provides a basic example of starting Sidequest with custom configurations. It includes settings for the backend database driver and connection string, definitions for multiple queues with their concurrency and priority, and basic dashboard settings like enabling it and setting authentication credentials.

```typescript
import { Sidequest } from "sidequest";
await Sidequest.start({
  // 1. Backend: choose your preferred database
  backend: {
    driver: "@sidequest/postgres-backend", // or @sidequest/sqlite-backend, @sidequest/mysql-backend, etc.
    config: "postgresql://postgres:postgres@localhost:5432/postgres",
  },
  // 2. Queues: define queue names, priorities, concurrency, and initial state
  queues: [
    { name: "default", concurrency: 2, priority: 50, state: "active" },
    { name: "critical", concurrency: 5, priority: 100, state: "active" },
    { name: "reports", concurrency: 1, state: "paused" },
  ],
  // 3. Job processing configuration
  maxConcurrentJobs: 50,
  // 4. Dashboard: enable/disable, set port, and basic auth
  dashboard: {
    enabled: true,
    port: 8678,
    auth: {
      user: "admin",
      password: "secret",
    },
  },
});
```

--------------------------------

### Install MySQL Backend Driver

Source: https://docs.sidequestjs.com/installation

Installs the MySQL backend driver for Sidequest.js. This command is compatible with npm, yarn, and pnpm.

```bash
npm install @sidequest/mysql-backend
```

```bash
yarn add @sidequest/mysql-backend
```

```bash
pnpm add @sidequest/mysql-backend
```

--------------------------------

### Install MongoDB Backend Driver

Source: https://docs.sidequestjs.com/installation

Installs the MongoDB backend driver for Sidequest.js. Supports npm, yarn, and pnpm.

```bash
npm install @sidequest/mongo-backend
```

```bash
yarn add @sidequest/mongo-backend
```

```bash
pnpm add @sidequest/mongo-backend
```

--------------------------------

### Minimal Job Enqueue Example

Source: https://docs.sidequestjs.com/engine/enqueue

A basic example of enqueueing a job with minimal configuration. This demonstrates the fundamental usage of Sidequest.build() and .enqueue().

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

// Simple job with default settings
await Sidequest.build(EmailJob).enqueue("user@example.com", "Welcome!", "Thanks for signing up!");
```

--------------------------------

### Restarting Sidequest Engine

Source: https://docs.sidequestjs.com/engine/starting

Illustrates the process of stopping an existing Sidequest instance and then starting it again with a new configuration, useful for updates or changes.

```typescript
// Stop the current instance
await Sidequest.stop();
// Start with new configuration
await Sidequest.start(newConfig);
```

--------------------------------

### Install SQLite Backend Driver

Source: https://docs.sidequestjs.com/installation

Installs the SQLite backend driver for Sidequest.js, suitable for development and small applications. Supports npm, yarn, and pnpm.

```bash
npm install @sidequest/sqlite-backend
```

```bash
yarn add @sidequest/sqlite-backend
```

```bash
pnpm add @sidequest/sqlite-backend
```

--------------------------------

### Monitoring Sidequest Startup with Debug Logs

Source: https://docs.sidequestjs.com/engine/starting

Starts the Sidequest engine with debug logging enabled to monitor the detailed steps of the startup process, including configuration, worker initialization, and server readiness.

```typescript
await Sidequest.start({
  logger: {
    level: "debug", // Shows detailed startup logs
  },
});
// Look for these log messages:
// "Configuring Sidequest engine"
// "Starting Sidequest using backend @sidequest/postgres-backend"
// "Starting main worker..."
// "Main worker is ready"
// "Server running on http://localhost:8678"
```

--------------------------------

### Start Sidequest Engine and Dashboard

Source: https://docs.sidequestjs.com/engine

Starts the Sidequest engine, including job processing and the monitoring dashboard. Can be called after `configure` or with full configuration.

```typescript
import { Sidequest } from "sidequest";
await Sidequest.start({
  backend: {
    driver: "@sidequest/postgres-backend",
    config: process.env.DATABASE_URL,
  },
  dashboard: {
    port: 3000,
    auth: {
      username: "admin",
      password: "secure-password",
    },
  },
});
console.log("Sidequest started! Dashboard: http://localhost:3000");
```

--------------------------------

### Install Sidequest Dashboard and Backend Drivers

Source: https://docs.sidequestjs.com/dashboard

Installs the Sidequest dashboard package and the necessary backend driver for database integration (e.g., PostgreSQL, SQLite, MySQL, MongoDB).

```bash
npm install @sidequest/dashboard
# or
yarn add @sidequest/dashboard

# For PostgreSQL (recommended)
npm install @sidequest/postgres-backend
# For SQLite
npm install @sidequest/sqlite-backend
# For MySQL
npm install @sidequest/mysql-backend
# For MongoDB
npm install @sidequest/mongo-backend
```

--------------------------------

### Install Backend Driver

Source: https://docs.sidequestjs.com/cli

This snippet demonstrates how to install a missing backend driver, such as '@sidequest/postgres-backend'. This is necessary when the CLI cannot find the required driver package. It assumes you are using npm for package management.

```bash
npm install @sidequest/postgres-backend
```

--------------------------------

### Run Sidequest in Development Mode

Source: https://docs.sidequestjs.com/development

Command to start the development server for Sidequest.js, enabling automatic rebuilding and providing access to the documentation site.

```bash
yarn dev
```

--------------------------------

### Start Standalone Sidequest Dashboard

Source: https://docs.sidequestjs.com/dashboard

Initializes and starts the Sidequest dashboard as a standalone service, connecting to a specified backend driver and configuration. This allows monitoring without running the full Sidequest engine.

```typescript
// or import form `sidequest` directly if you have the full library
import { SidequestDashboard } from "@sidequest/dashboard";
const dashboard = new SidequestDashboard();
await dashboard.start({
  enabled: true,
  port: 8678,
  backendConfig: {
    driver: "@sidequest/postgres-backend",
    config: "postgresql://localhost:5432/sidequest",
  },
});
console.log("Dashboard available at http://localhost:8678");
```

--------------------------------

### Sidequest Configuration File - Direct Connection

Source: https://docs.sidequestjs.com/cli

Example of a Sidequest configuration file using a direct connection string for a SQLite backend.

```json
{
  "backend": "@sidequest/sqlite-backend",
  "connection": {
    "type": "direct",
    "value": "./sidequest.sqlite"
  }
}
```

--------------------------------

### Start Sidequest with Default Dashboard

Source: https://docs.sidequestjs.com/dashboard

Starts the Sidequest instance with the dashboard enabled on the default port (8678). This is the most basic way to get the dashboard running.

```typescript
import { Sidequest } from "sidequest";
// Dashboard runs on default port 8678
await Sidequest.start();
console.log("Dashboard available at http://localhost:8678");
```

--------------------------------

### Successful Job Result Example

Source: https://docs.sidequestjs.com/jobs

Demonstrates how a job's successful return value is stored in the `result` field. The example shows a `CalculationJob` that returns an object with a sum and a timestamp.

```typescript
export class CalculationJob extends Job {
  async run(a: number, b: number) {
    const result = a + b;
    return { sum: result, timestamp: new Date() };
  }
}
// After completion, job.result contains:
// { sum: 42, timestamp: "2024-01-01T12:00:00.000Z" }
```

--------------------------------

### Job Error Information Example

Source: https://docs.sidequestjs.com/jobs

Illustrates how error details are stored in the `errors` array when a job fails. The example shows the structure of an error object, including name, message, stack trace, attempt number, and timestamp.

```json
[
  {
    "name": "Error",
    "message": "Database connection failed",
    "stack": "Error: Database connection failed\n    at ...",
    "attempt": 0,
    "attempt_by": "worker-1",
    "attempted_at": "2024-01-01T12:00:00.000Z"
  },
  ...
]
```

--------------------------------

### Successful Job Result Example

Source: https://docs.sidequestjs.com/jobs/index

Demonstrates how a job's successful return value is stored in the `result` field. The example shows a TypeScript class `CalculationJob` with a `run` method that returns an object containing a sum and a timestamp.

```typescript
export class CalculationJob extends Job {
  async run(a: number, b: number) {
    const result = a + b;
    return { sum: result, timestamp: new Date() };
  }
}
// After completion, job.result contains:
// { sum: 42, timestamp: "2024-01-01T12:00:00.000Z" }
```

--------------------------------

### Sidequest CLI - Development Workflow Initialization

Source: https://docs.sidequestjs.com/cli

Initializes a Sidequest project by navigating to the project directory and running the configuration wizard.

```bash
cd my-project
sidequest config
```

--------------------------------

### High-Throughput Setup Example

Source: https://docs.sidequestjs.com/engine/configuration

Configuration optimized for high-throughput scenarios. This setup uses a PostgreSQL backend, increases the maximum concurrent jobs, and tunes thread and timeout settings for performance. It also configures more frequent intervals for stale job cleanup and finished job cleanup.

```typescript
import { Sidequest } from "sidequest";
await Sidequest.start({
  backend: {
    driver: "@sidequest/postgres-backend",
    config: "postgresql://postgres:postgres@localhost:5432/postgres",
  },
  maxConcurrentJobs: 100,
  minThreads: 8,
  maxThreads: 16,
  idleWorkerTimeout: 30000, // 30 seconds for high throughput
  releaseStaleJobsIntervalMin: 30, // More frequent stale job cleanup
  cleanupFinishedJobsIntervalMin: 30, // More frequent cleanup
  queueDefaults: {
    concurrency: 20, // Higher default concurrency
  },
});
```

--------------------------------

### Error Handling During Startup

Source: https://docs.sidequestjs.com/engine/starting

Demonstrates how to catch and handle potential errors that may occur when initializing the Sidequest engine using a try-catch block.

```typescript
try {
  await Sidequest.start(config);
  console.log("Sidequest started successfully");
} catch (error) {
  console.error("Failed to start Sidequest:", error);
}
```

--------------------------------

### Job Error Information Structure

Source: https://docs.sidequestjs.com/jobs/index

Illustrates the structure of error details stored in the `errors` array when jobs fail. The example shows an array containing error objects with properties like name, message, stack trace, attempt number, worker identifier, and attempt timestamp.

```json
[
  {
    "name": "Error",
    "message": "Database connection failed",
    "stack": "Error: Database connection failed\n    at ...",
    "attempt": 0,
    "attempt_by": "worker-1",
    "attempted_at": "2024-01-01T12:00:00.000Z"
  },
  ...
]
```

--------------------------------

### Install Sidequest.js Main Package

Source: https://docs.sidequestjs.com/installation

Installs the core Sidequest.js package, which is required for all applications. This command is compatible with npm, yarn, and pnpm.

```bash
npm install sidequest
```

```bash
yarn add sidequest
```

```bash
pnpm add sidequest
```

--------------------------------

### Configuring Queues in Sidequest.start()

Source: https://docs.sidequestjs.com/queues/index

Demonstrates how to configure queues when starting the Sidequest engine. This includes setting properties like concurrency, priority, and state for each queue.

```javascript
const sidequest = require('sidequestjs');

const config = {
  queues: [
    {
      name: 'emails',
      concurrency: 5,
      priority: 10,
      state: 'active' // or 'paused'
    },
    {
      name: 'reports',
      concurrency: 2,
      priority: 5,
      state: 'active'
    }
  ],
  maxConcurrentJobs: 10
};

sidequest.start(config);

```

--------------------------------

### Hello World Job Class

Source: https://docs.sidequestjs.com/examples

Defines a basic job class 'HelloJob' that extends the 'Job' base class. The 'run' method accepts a name parameter and logs a greeting. This demonstrates the fundamental structure of a Sidequest job.

```ts
/* eslint-disable no-console */
import { Job } from "sidequest";
export class HelloJob extends Job {
  run(name: string) {
    const msg = `hello ${name}`;
    console.log(msg);
    return msg;
  }
}
```

--------------------------------

### Run Sidequest Tests

Source: https://docs.sidequestjs.com/development

Commands to run the test suite for Sidequest.js, including options for starting database containers or running a minified test suite.

```bash
# Starts all the test DBs in Docker containers
yarn db:all
# Run tests for all packages
yarn test:all
```

```bash
# Run tests without backend implementations
yarn test
```

--------------------------------

### Invoke Sidequest CLI

Source: https://docs.sidequestjs.com/cli

Demonstrates how to invoke the Sidequest CLI using its full name 'sidequest' or its alias 'sq'. Includes an example of how to view the help menu.

```bash
sidequest --help
# or
sq --help
```

--------------------------------

### Build and Enqueue Jobs

Source: https://docs.sidequestjs.com/engine

Demonstrates building and enqueuing jobs using the builder pattern, including simple enqueuing and advanced configuration with queue, timeout, attempts, availability, and uniqueness settings.

```typescript
import { EmailJob } from "./jobs/EmailJob.js";
// Simple job enqueuing
await Sidequest.build(EmailJob).enqueue("user@example.com", "Welcome!", "Thanks for signing up!");
// Advanced job configuration
await Sidequest.build(EmailJob)
  .queue("email")
  .timeout(30000)
  .maxAttempts(3)
  .availableAt(new Date(Date.now() + 60000)) // 1 minute delay
  .uniqueness({ key: "email", ttl: 300000 }) // 5 minute uniqueness
  .enqueue("user@example.com", "Welcome!", "Thanks for signing up!");
```

--------------------------------

### Configure Queues in Sidequest.start()

Source: https://docs.sidequestjs.com/queues

Demonstrates how to define and configure multiple queues with their respective properties like name, concurrency, priority, and initial state when starting Sidequest.

```typescript
await Sidequest.start({
  queues: [
    { name: "default", concurrency: 2, priority: 50 },
    { name: "critical", concurrency: 5, priority: 100 },
    { name: "reports", concurrency: 1, state: "paused" },
  ],
});
```
Tokens:
Raw