Examples

This page showcases practical examples that demonstrate how to use Sidequest.js in real-world scenarios. Each example includes complete, runnable code that you can use as a starting point for your own applications.

1. Hello World

The simplest possible Sidequest example - creating and running a basic job.

What it demonstrates:

• Creating a basic job class
• Starting Sidequest with default configuration
• Enqueueing a job with parameters

Job Class

/* 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;
  }
}

Main Application

import { Sidequest } from "sidequest";
import { HelloJob } from "./hello-job.js";

await Sidequest.start();

await Sidequest.build(HelloJob).enqueue("John Doe");

Key concepts:

• All jobs extend the Job base class
• The run() method contains your job logic
• Jobs can accept parameters and return values
• Sidequest starts with sensible defaults (SQLite backend, dashboard on port 8678)

2. Recurring Jobs

Schedule jobs to run automatically at specified intervals using cron expressions.

What it demonstrates:

• Using the .schedule() method instead of .enqueue()
• Cron expression syntax for job scheduling
• Setting up recurring background tasks

Job Class

/* eslint-disable no-console */

import { Job } from "sidequest";

export class SampleJob extends Job {
  run() {
    const msg = "sample job";
    console.log(msg);
    return msg;
  }
}

Main Application

import { Sidequest } from "sidequest";
import { SampleJob } from "./sample-job.js";

await Sidequest.start();

// every 10 minutes
await Sidequest.build(SampleJob).schedule("*/10 * * * * *");

Key concepts:

• Use .schedule() for recurring jobs instead of .enqueue()
• Cron expressions control when jobs run (this example runs every 10 seconds)
• Scheduled jobs are in-memory only and need to be re-registered on restart
• Scheduled jobs enqueue other jobs (those are persisted)
• Perfect for maintenance tasks, data processing, or periodic notifications

3. Job Snoozing

Implement jobs that can pause themselves and resume later, useful for waiting on external conditions.

What it demonstrates:

• Using this.snooze() to pause job execution
• Handling jobs that need to wait for external conditions
• Job lifecycle management

Job Class

import { Job } from "sidequest";

export class SnoozeJob extends Job {
  run() {
    // Pauses the job for 10 seconds before retrying — can be used to wait for external conditions.
    return this.snooze(10_000);
  }
}

Main Application

import { Sidequest } from "sidequest";
import { SnoozeJob } from "./snooze-job.js";

await Sidequest.start();

await Sidequest.build(SnoozeJob).enqueue();

Key concepts:

• this.snooze(milliseconds) pauses a job and reschedules it for later
• Useful for rate limiting, waiting for external APIs, or implementing backoff strategies
• The job will be retried after the specified delay
• Snoozing doesn't count against the job's retry attempts

4. API-Triggered Jobs

Integrate Sidequest with a web API to enqueue jobs from HTTP requests.

What it demonstrates:

• Enqueueing jobs from within an Express.js application
• Asynchronous job processing triggered by user actions
• Separating web request handling from background processing

Job Class

/* eslint-disable no-console */

import { Job } from "sidequest";

export class SendEmailJob extends Job {
  run(email: string) {
    const msg = `sending email to ${email}`;
    console.log(msg);
    return msg;
  }
}

Express Application

/* eslint-disable no-console */

import { Sidequest } from "sidequest";

import express from "express";
import { SendEmailJob } from "./send-email-job.js";

const app = express();

app.get("/send-email", (req, res) => {
  const email = req.query.email ?? "email@example.com";
  void Sidequest.build(SendEmailJob).enqueue(email as string);
  res.send(204);
});

await Sidequest.start();

app.listen(3000, () => {
  console.log("call http://localhost:3000/send-email?email=test@example.com");
});

Key concepts:

• Jobs are enqueued asynchronously and don't block the HTTP response
• Use void when you don't need to wait for job completion
• This pattern is perfect for time-consuming tasks like sending emails, processing images, or generating reports
• The API responds immediately while work happens in the background

Try it out:

# Start the server
npm run start

# Trigger a job
curl "http://localhost:3000/send-email?email=test@example.com"

5. Web Scraping

A more complex example that demonstrates real-world job processing with external HTTP requests and data processing.

What it demonstrates:

• Jobs that make external HTTP requests
• Processing and parsing HTML data
• Returning structured results from jobs
• Using external dependencies (cheerio for HTML parsing)

Job Class

/* eslint-disable no-console */

import { load } from "cheerio";
import { Job } from "sidequest";

export class CountWordJob extends Job {
  async run(url: string, word: string) {
    const response = await fetch(url);
    const html = await response.text();

    const $ = load(html);
    const text = $("body").text();

    const regex = new RegExp(`\\b${word}\\b`, "gi");
    const matches = text.match(regex);
    const count = matches ? matches.length : 0;

    console.log(`The word "${word}" appears ${count} times on the page ${url}`);

    // Return the result as an object
    // Will be available in the result of the job
    return {
      word,
      count,
      url,
    };
  }
}

Main Application

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");

Key concepts:

• Jobs can make external HTTP requests and process the responses
• Use async/await for asynchronous operations within jobs
• Return structured data that will be stored with the job results
• External libraries like cheerio can be used for data processing
• Perfect for data collection, content analysis, or API integration tasks
• If the job fails (e.g., rate limiting), it will be retried based on your configuration

Running the Examples

All examples are located in the /examples directory of the Sidequest repository. To run any example, navigate to Sidequest's root directory and run:

yarn install

Then build the examples:

yarn build:examples

Then run any example with:

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

Viewing the Dashboard

All examples start the Sidequest dashboard automatically. You can view job execution in real-time:

http://localhost:8678

The dashboard shows:

• Job execution status and history
• Queue management and statistics
• Real-time job processing metrics
• Job details including arguments and results

Next Steps

After exploring these examples:

1. Learn about Job Classes - Understand job lifecycle and advanced features
2. Explore Queue Management - Configure queues for different priorities and concurrency
3. Read the Configuration Guide - Customize Sidequest for your environment
4. Check out the Dashboard - Monitor and manage your jobs
5. Review Best Practices - Production deployment considerations