Quirrel

https://docs.quirrel.dev/
Admin
Quirrel is a job queueing service designed specifically for serverless environments, enabling...
Tokens:14,810
Snippets:143
Trust Score:7.8
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install and Run Quirrel Server Locally

Source: https://docs.quirrel.dev/getting-started/next-js

Installs the Quirrel server package and provides a script to run it alongside the Next.js development server. This setup is essential for local development and testing of Quirrel queues.

```bash
npm install quirrel
npx quirrel
```

```json
"scripts": {
  "dev": "concurrently 'next dev' 'quirrel'"
}
```

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

### Install and Run Quirrel Local Server

Source: https://docs.quirrel.dev/development

Installs Quirrel and starts the local development server. The server automatically scans for CronJobs in your project and can detect and use the default development port of frameworks like Next.js.

```bash
npm install quirrel
quirrel
```

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

### Express/Connect Queue Setup

Source: https://docs.quirrel.dev/api/express

Demonstrates how to initialize and use a Quirrel queue within an Express application. This includes setting up the Express app, defining a queue with a worker function, and mounting the queue to the Express app.

```APIDOC
## POST /websites/quirrel_dev

### Description
Initializes and integrates a Quirrel queue into an Express or Connect.js application.

### Method
POST

### Endpoint
/websites/quirrel_dev

### Parameters
#### Query Parameters
- **QUIRREL_BASE_URL** (string) - Required - The base URL for your Quirrel instance. This must be specified if not using the default development port.

#### Request Body
This endpoint does not have a request body.

### Request Example
```javascript
import { Queue } from "quirrel/connect";
import Express from "express";

const app = Express()

const someQueue = Queue(
  "someQueue",
  async (job, meta) => {
    // do something with job payload and metadata
    console.log("Processing job:", job, "with meta:", meta);
  }
)

app.use(someQueue)

app.listen(3000)
```

### Response
#### Success Response (200)
This endpoint typically returns a 200 OK status upon successful setup, indicating the queue is integrated with the Express app.

#### Response Example
```json
{
  "message": "Queue 'someQueue' integrated successfully."
}
```

### Notes
- The `QUIRREL_BASE_URL` environment variable must be set for the queue to function correctly, especially when not using default ports.
- The `Queue` function takes a path, a worker function, and optional default job options.
```

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

### Netlify Queue Function

Source: https://docs.quirrel.dev/api/netlify

This example demonstrates how to create a Quirrel queue function for Netlify. It exports a handler that initializes the queue with a specified path and a worker function to process jobs.

```APIDOC
## POST /.netlify/functions/someQueue

### Description
Creates a new Quirrel queue that can be triggered via a Netlify Function. The queue processes jobs using the provided worker function.

### Method
POST

### Endpoint
`/.netlify/functions/someQueue`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(Not directly applicable for the function definition, but job payloads are passed to the worker)

### Request Example
(Not applicable for function definition)

### Response
#### Success Response (200)
(Not directly applicable for function definition)

#### Response Example
(Not applicable for function definition)

## Queue Constructor

### Description
Initializes a Quirrel queue instance. This function must be exported from a Netlify Function file.

### Method
N/A (Constructor)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { Queue } from "quirrel/netlify";

export const handler = Queue(
  ".netlify/functions/someQueue",
  async (job, meta) => {
    // do something with job.payload and meta
  }
);

export default handler;
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

### Parameters
#### Path Parameters
*   **path** (`string`) - Required - The route that this queue is reachable at. This should typically be the path to your Netlify function.
*   **worker** (`(job: T, meta: JobMeta) => Promise<void>`) - Required - A function that takes the job's payload and metadata and performs the desired asynchronous operation.
*   **defaultJobOptions** (`{ exclusive?: boolean }`) - Optional - Use to set default options applied to every job, such as `exclusive` to prevent concurrent execution of jobs for this queue.
```

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

### Configure Concurrent Startup with npm Scripts

Source: https://docs.quirrel.dev/faq

This snippet shows how to use `concurrently` within an npm script to run Quirrel and another development server (like Next.js) simultaneously. It's useful for streamlining the development environment setup.

```json
{
  "scripts": {
    "dev": "concurrently --raw \"quirrel\" \"next dev\"",
    "...": "..."
  }
}
```

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

### Schedule a Job for a Specific Date (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Example of enqueuing a job with a specific execution date using the `runAt` option. This is useful for scheduling tasks at a precise future time.

```typescript
birthdayQueue.enqueue(user.id, {
  runAt: user.birthday,
});
```

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

### Enqueue Job in Next.js App Router

Source: https://docs.quirrel.dev/getting-started/next-js

Demonstrates how to enqueue a new job into a previously defined email queue within a Next.js App Router project. It shows how to import the queue and use the `.enqueue` method with job data and optional scheduling.

```typescript
import { emailQueue } from "app/api/queues/email"

// could be some API route / getServerSideProps / ...
export default async (req, res) => {

  await emailQueue.enqueue(
    ..., // job to be enqueued
    { delay: "24h" } // scheduling options
  )

}
```

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

### Enqueue Job in Next.js Pages Router

Source: https://docs.quirrel.dev/getting-started/next-js

Demonstrates how to enqueue a new job into a previously defined email queue within a Next.js Pages Router project. It shows how to import the queue and use the `.enqueue` method with job data and optional scheduling.

```typescript
import EmailQueue from "pages/api/queues/email"

// could be some API route / getServerSideProps / ...
export default async (req, res) => {

  await EmailQueue.enqueue(
    ..., // job to be enqueued
    { delay: "24h" } // scheduling options
  )

}
```

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

### Schedule a Repeated Job (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Example of enqueuing a job that will repeat a specified number of times at a given interval. The job runs at the initial `runAt` time, and then repeats `times` number of times, each separated by `every` interval.

```typescript
todoReminders.enqueue(todo.id, {
  runAt: todo.scheduled_date,
  id: todo.id,
  repeat: {
    every: "1d",
    times: 3,
  },
});
```

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

### Create Email Queue for Next.js App Router

Source: https://docs.quirrel.dev/getting-started/next-js

Defines an email queue using Quirrel's `Queue` function for a Next.js App Router project. It specifies the route for the queue and an asynchronous worker function to handle job execution, such as sending emails.

```typescript
import { Queue } from "quirrel/next-app"

export const emailQueue = Queue(
  "api/queues/email", // 👈 the route it's reachable on
  async job => {
    await email.send( ... )
  }
)

export const POST = emailQueue
```

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

### Create Email Queue for Next.js Pages Router

Source: https://docs.quirrel.dev/getting-started/next-js

Defines an email queue using Quirrel's `Queue` function for a Next.js Pages Router project. It specifies the route for the queue and an asynchronous worker function to handle job execution, such as sending emails.

```typescript
import { Queue } from "quirrel/next-pages"

export default Queue(
  "api/queues/email", // 👈 the route it's reachable on
  async job => {
    await email.send( ... )
  }
)
```

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

### Generate Quirrel API Token with cURL

Source: https://docs.quirrel.dev/deployment/railway

Use the cURL command to generate a new API token for your Quirrel instance. This requires your Railway deployment URL and the PASSPHRASE set during setup.

```bash
curl --user ignored:<PASSPHRASE> -X PUT https://mighty-owl-production.up.railway.app/tokens/foo
```

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

### Enqueue a Retryable Job (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Example of enqueuing a job with a retry strategy. The `retry` option specifies an array of delays after which the job should be retried if it fails. Currently, there's a hard limit of 10 retry attempts.

```typescript
apiIntegrationQueue.enqueue(
  { ... },
  {
    retry: ["10sec", "5min", "1h"]
  }
);
```

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

### Get a Job by ID (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Retrieves a specific job from the queue using its unique ID. Returns the `Job` object if found, otherwise returns `null`.

```typescript
getById(id: string): Promise<Job<T> | null>
```

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

### Queue Creation and Export

Source: https://docs.quirrel.dev/api/remix

Demonstrates how to create a new Quirrel queue in a server-only file and export it for use in Remix.

```APIDOC
## POST /queues/someQueue

### Description
This endpoint represents a Quirrel queue that processes jobs asynchronously. The worker function defined in `someQueue.server.ts` will be executed for each job.

### Method
POST

### Endpoint
`/queues/someQueue`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **job** (any) - Required - The payload of the job to be processed.
- **meta** (JobMeta) - Required - Metadata associated with the job.

### Request Example
```json
{
  "job": {
    "data": "example payload"
  },
  "meta": {
    "name": "someQueue",
    "id": "some-job-id",
    "timestamp": 1678886400000
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates that the job was successfully processed.

#### Response Example
```json
{
  "message": "Job processed successfully"
}
```

### Worker Function Signature
```typescript
async (job: T, meta: JobMeta): Promise<void>
```

### `Queue` Function Signature
```typescript
function Queue<T>(
  path: string,
  worker: (job: T, meta: JobMeta): Promise<void>,
  defaultJobOptions?: { exclusive?: boolean }
): QueueInstance<T>
```

### `Queue` Parameters
- **path** (string) - Required - The route that this queue is reachable at.
- **worker** (function) - Required - A function that takes the job's payload and returns a `Promise`.
- **defaultJobOptions** (object) - Optional - Use to set default options applied to every job. Contains:
  - **exclusive** (boolean) - Optional - If true, only one job will be processed at a time.
```

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

### Acquire Quirrel Authentication Token

Source: https://docs.quirrel.dev/deployment/connecting

This command demonstrates how to acquire an authentication token from your Quirrel Server. It uses `curl` and requires placeholders for the passphrase, Quirrel server URL, and the desired token name.

```shell
curl --user ignored:{PASSPHRASE} -X PUT {QUIRREL_SERVER_URL}/tokens/{NAME_OF_TOKEN}
```

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

### Queue Initialization

Source: https://docs.quirrel.dev/api/nuxt

This section shows how to initialize a Quirrel queue in your Nuxt.js application.

```APIDOC
## POST /api/someQueue

### Description
Initializes a new Quirrel queue named 'someQueue' and defines a worker function to process jobs.

### Method
POST

### Endpoint
/api/someQueue

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **path** (string) - Required - The route that this queue is reachable at.
* **worker** (function) - Required - A function that takes the job's payload and returns a `Promise`.
* **defaultJobOptions** (object) - Optional - Use to set default options applied to every job. 
  * **exclusive** (boolean) - Optional - If true, only one job can run at a time.

### Request Example
```javascript
// api/someQueue.js
import { Queue } from "quirrel/nuxt";

export default Queue(
  "someQueue",
  async (job, meta) => {
    // do something with job.data and meta
    console.log(job.data);
  },
  { exclusive: true } // Optional default job options
);
```

### Response
#### Success Response (200)
Indicates that the queue has been successfully registered.

#### Response Example
```json
{
  "message": "Queue registered successfully"
}
```
```

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

### Configure Quirrel CI Script for Deployments

Source: https://docs.quirrel.dev/deployment/connecting

This script configuration ensures that `quirrel ci` is run during the build process for deployments. It requires the QUIRREL_API_URL, QUIRREL_TOKEN, and QUIRREL_BASE_URL environment variables to be set.

```json
{
  "scripts": {
    "build": "npm run build && quirrel ci"
  }
}
```

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

### Create SvelteKit Queue with Quirrel

Source: https://docs.quirrel.dev/api/sveltekit

This snippet demonstrates how to create a new queue in SvelteKit using the Quirrel library. The queue is defined with a specific route and a worker function to process jobs. It must be exported as a server route to function correctly.

```typescript
import { Queue } from "quirrel/sveltekit";

const queue = Queue(
  "greetingsQueue", // 👈 the route it's reachable on
  async (job, meta) => {
    // do something
  }
);

export const POST = queue

export default queue

```

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

### Open Quirrel Admin UI

Source: https://docs.quirrel.dev/development

Opens the Quirrel admin interface in your browser, which is useful for local development and managing CronJobs.

```bash
quirrel ui
```

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

### Create Netlify Queue Function

Source: https://docs.quirrel.dev/api/netlify

This JavaScript snippet demonstrates how to create a new queue using Quirrel within a Netlify Function. It requires the 'quirrel/netlify' package and exports a handler that processes jobs asynchronously.

```javascript
import { Queue } from "quirrel/netlify";

export const handler = Queue(
  ".netlify/functions/someQueue",
  async (job, meta) => {
    // do something
  }
);

export default handler;

```

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

### Schedule a Job with a Delay (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Demonstrates enqueuing a job with a delay specified in a human-readable format (e.g., '7d' for 7 days). The delay is calculated in milliseconds.

```typescript
welcomeUserQueue.enqueue(user.id, {
  delay: "7d", // same as 7 * 24 * 60 * 60 * 1000
});
```

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

### Iterate Over Pending Jobs (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Demonstrates how to use the async iterator returned by `queue.get()` to retrieve and process pending jobs in batches. This is useful for handling jobs that are waiting to be executed.

```typescript
for await (const jobs of queue.get()) {
  // do something
}
```

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

### Create and Use Quirrel Queue with Express

Source: https://docs.quirrel.dev/api/express

This snippet demonstrates how to initialize a Quirrel queue and integrate it as middleware into an Express application. It requires the 'quirrel/connect' package and Express. The queue is defined with a path, a worker function to process jobs, and then attached to the Express app.

```typescript
import { Queue } from "quirrel/connect";  
import Express from "express";  
  
const app = Express()  
  
const someQueue = Queue(  
  "someQueue",  
  async (job, meta) => {  
    // do something  
  }  
)  
  
app.use(someQueue)  
  
app.listen(3000)
```

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

### POST /greetingsQueue

Source: https://docs.quirrel.dev/api/sveltekit

Creates a new queue named 'greetingsQueue' that can be reached at the /greetingsQueue route. Jobs added to this queue will be processed by the provided worker function.

```APIDOC
## POST /greetingsQueue

### Description
Creates a new queue that can be reached at the specified route. Jobs added to this queue will be processed by the provided worker function.

### Method
POST

### Endpoint
/greetingsQueue

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This endpoint does not directly handle a request body for job creation. Job creation is typically done via a separate client-side or server-side mechanism that interacts with the queue.

### Request Example
```json
{
  "example": "POST request to /greetingsQueue to add a job"
}
```

### Response
#### Success Response (200)
This endpoint primarily serves to expose the queue. A successful response indicates the queue is set up. Job-related responses would depend on the job creation mechanism.

#### Response Example
```json
{
  "example": "Queue setup successful"
}
```

### Worker Function Signature
```typescript
async (job: T, meta: JobMeta): Promise<void>
```

### Queue Function Signature
```typescript
function Queue<T>(
  path: string,
  worker: (job: T, meta: JobMeta) => Promise<void>,
  defaultJobOptions?: { exclusive?: boolean }
): QueueInstance<T>
```

#### Parameter Details
- **path** (string) - Required - The route that this queue is reachable at.
- **worker** (function) - Required - A function that takes the job's payload and returns a `Promise`.
- **defaultJobOptions** (object) - Optional - Use to set default options applied to every job. Contains:
  - **exclusive** (boolean) - Optional - If true, only one job will be processed at a time.
```

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

### Run Quirrel Docker Container

Source: https://docs.quirrel.dev/deployment/docker

Executes the Quirrel Docker container, mapping the environment variables from a .env file and exposing the service on port 9181. Replace `<name_of_your_container>` with a desired name.

```docker
docker run --env-file .env -p 9181:9181 ghcr.io/quirrel-dev/quirrel:main
```

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

### Queue Function Signature

Source: https://docs.quirrel.dev/api/next

Details on the parameters for the `Queue` function used to create queues.

```APIDOC
## Queue Function

### Description
Creates a new Quirrel queue instance.

### Function Signature
```typescript
function Queue<T>(
  path: string,
  worker: (job: T, meta: JobMeta) => Promise<void>,
  defaultJobOptions?: { exclusive?: boolean }
): QueueInstance<T>
```

### Parameters
#### Path Parameters
- **path** (string) - Required - The route that this queue is reachable at.
- **worker** (function) - Required - A function that takes the job's payload and returns a `Promise`.
- **defaultJobOptions** (object) - Optional - Use to set default options applied to every job. Includes:
  - **exclusive** (boolean) - Optional - If true, only one job can run at a time for this queue.
```

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

### Pull Quirrel Docker Image

Source: https://docs.quirrel.dev/deployment/docker

Pulls the latest official Quirrel Docker image from GitHub Container Registry. This is the first step in deploying Quirrel via Docker.

```docker
docker pull ghcr.io/quirrel-dev/quirrel:main
```

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

### Enqueue a Job with Options (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Enqueues a new Job into the queue with various optional configurations for scheduling, retries, and exclusivity. The function returns a Promise that resolves to the created Job object. Supports scheduling by date, delay, repetition, and CRON expressions.

```typescript
async enqueue(
  payload: T,
  options: {
    id?: string;
    override?: boolean;

    runAt?: Date;
    delay?: number | string;
    repeat?: {
      every?: number | string;
      times?: number;
      cron?: string | [schedule: string, timezone: string];
    }
    retry?: (number | string)[];

    exclusive?: boolean;
  }
): Promise<Job<T>>
```

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

### Nuxt.js Configuration

Source: https://docs.quirrel.dev/api/nuxt

This section explains how to register the Quirrel queue as a server middleware in your Nuxt.js configuration.

```APIDOC
## Nuxt Configuration (`nuxt.config.js`)

### Description
Register the queue file as a server middleware in your `nuxt.config.js` file to make it accessible.

### Method
N/A (Configuration file)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```javascript
// nuxt.config.js
export default {
  serverMiddleware: [
    // will register the queue with Nuxt
    "~/api/someQueue.js",
  ]
}
```

### Response
N/A
```

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

### Schedule a Booking Reminder (TypeScript)

Source: https://docs.quirrel.dev/recipes/event-reminder

Schedules a booking reminder by enqueuing a job to the booking reminder queue. It specifies the booking ID, the exact time to run the reminder (30 minutes before the event), and a unique ID for the job, allowing for later management.

```typescript
import bookingReminder from "api/booking-reminder"
import { subMinutes } from "date-fns"

async function createBooking(...) {
  const booking = await createBooking(...);

  await bookingReminder.enqueue(
    booking.id,
    {
      runAt: subMinutes(booking.event.date, 30),

      // allows us to address this job later for deletion
      id: booking.id
    }
  )
}

```

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

### Schedule a Job using CRON Expression (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Shows how to enqueue a job that runs on a CRON schedule. The `cron` option accepts a CRON string and an optional timezone. If no timezone is provided, it defaults to 'Etc/UTC'.

```typescript
billingQueue.enqueue(undefined, {
  id: "billing", // makes sure job isn't duplicated
  override: true, // if another job with that ID already exists, override it
  repeat: {
    cron: ["* * * * 1 *", "Europe/Berlin"],
  },
});
```

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

### Integrate Quirrel into package.json Scripts

Source: https://docs.quirrel.dev/development

Adds Quirrel to your `package.json` scripts to ensure it runs concurrently with your framework's development server, such as Next.js. This allows for seamless local development of CronJobs.

```json
{
  "scripts": {
    "dev": "concurrently 'next dev' 'quirrel'"
  }
}
```

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

### Queue Creation API

Source: https://docs.quirrel.dev/api/redwood

This section details how to create a new queue using the Quirrel Redwood integration. Queues must be exported from a Serverless Function to operate correctly.

```APIDOC
## POST /api/src/functions/someQueue.js

### Description
Creates a new queue instance that can be used for background job processing. The queue must be exported from a Serverless Function.

### Method
POST

### Endpoint
/api/src/functions/someQueue.js

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This endpoint does not directly accept a request body for creation. The queue is defined within the serverless function code.

### Request Example
```javascript
import { Queue } from "quirrel/redwood";

export const handler = Queue(
  "someQueue",
  async (job, meta) => {
    // do something with job payload and meta
    console.log("Processing job:", job);
  }
);

export default handler;
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful queue setup.

#### Response Example
```json
{
  "message": "Queue 'someQueue' created successfully."
}
```

### Notes
- The `path` parameter in the `Queue` function defines the route at which the queue is reachable.
- The `worker` parameter is a function that processes each job.
- `defaultJobOptions` can be provided to set default options for all jobs enqueued to this queue.
```

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

### Define a CronJob in Next.js with Quirrel

Source: https://docs.quirrel.dev/api/cronjob

This snippet demonstrates how to define a CronJob in a Next.js application using the Quirrel library. It specifies the route, the cron schedule (including time zone), and the asynchronous function to be executed. The cron schedule can be a standard cron string or a predefined keyword like '@weekly'.

```typescript
import { CronJob } from "quirrel/next";

export default CronJob(
  "api/someCronJob", // the route that it's reachable on
  ["0 2 * * *", "Europe/Berlin"], // every day at 2AM, in Berlin time. you can also write @weekly or @daily!
  async (job) => {
    // do something
  }
);

```

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

### Create Nuxt.js Queue with Quirrel

Source: https://docs.quirrel.dev/api/nuxt

This snippet demonstrates how to create a new Quirrel queue within a Nuxt.js application. It imports the Queue class from 'quirrel/nuxt' and defines a worker function to process jobs. The queue is then exported as default.

```javascript
import { Queue } from "quirrel/nuxt";

export default Queue(
  "someQueue",
  async (job, meta) => {
    // do something
  }
);

```

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

### Enqueue CSV Processing Task (TypeScript/Blitz.js)

Source: https://docs.quirrel.dev/recipes/processing-upload-in-background

This mutation handles the initial upload by creating a new record in the `uploadedCsv` database table and then enqueuing the record's ID into the `csvProcessingQueue`. It utilizes Prisma for database operations and a custom Quirrel queue for task management.

```typescript
// app/mutations/uploadCsvForProcessing
import db from "db"
import csvProcessingQueue from "app/api/process-csv"

export default async function uploadCsvForProcessing(data: string) {
  const record = await db.uploadedCsv.create({
    data: {data},
  })

  await csvProcessingQueue.enqueue(record.id)

  return record.id
}
```

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

### App Router Queue Handler

Source: https://docs.quirrel.dev/api/next

Defines a Quirrel queue using the App Router's Route Handler pattern.

```APIDOC
## POST /api/queues/sample

### Description
This endpoint is a Route Handler for a Quirrel queue, processing jobs asynchronously.

### Method
POST

### Endpoint
/api/queues/sample

### Parameters
#### Request Body
- **job** (any) - The payload of the job to be processed.
- **meta** (JobMeta) - Metadata associated with the job.

### Request Example
```json
{
  "job": {},
  "meta": {}
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the job was successfully processed.

#### Response Example
```json
{
  "message": "Job processed successfully"
}
```
```

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

### Update Next.js Quirrel Import and Route

Source: https://docs.quirrel.dev/migrating-to-v1

This snippet demonstrates how to update the import statement and the queue route string for Next.js projects when migrating to Quirrel v1. It shows the old syntax and the new, required syntax.

```diff
-import { Queue } from "@quirrel/next"
+import { Queue } from "quirrel/next"
// ...
export default Queue(
- "someQueue",
+ "api/someQueue",
  async () => {
    // ...
  }
)
```

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

### Register Nuxt.js Queue as Server Middleware

Source: https://docs.quirrel.dev/api/nuxt

This configuration snippet shows how to register a Quirrel queue as server middleware in a Nuxt.js project. By including the queue's file path in the `serverMiddleware` array in `nuxt.config.js`, the queue becomes accessible.

```javascript
export default {
  serverMiddleware: [
    // will register the queue with Nuxt
    "~/api/someQueue.js",
  ]
}

```

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

### Quirrel Queue Function Signature

Source: https://docs.quirrel.dev/api/remix

Illustrates the TypeScript signature for the Quirrel Queue function. It takes a path, a worker function, and optional default job options, returning a QueueInstance.

```typescript
function Queue<T>(  
  path: string,  
  worker: (job: T, meta: JobMeta): Promise<void>,  
  defaultJobOptions?: { exclusive?: boolean }  
): QueueInstance<T>  

```

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

### POST /api/someQueue

Source: https://docs.quirrel.dev/api/blitz

This endpoint represents a Quirrel queue instance created using the Blitz.js recipe. It allows you to define a queue, specify a worker function to process jobs, and set default job options.

```APIDOC
## POST /api/someQueue

### Description
Creates and exports a Quirrel queue instance from a Blitz.js API route. The queue processes jobs asynchronously using a provided worker function.

### Method
POST

### Endpoint
`/api/someQueue`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **job** (any) - Required - The payload of the job to be processed.
* **meta** (JobMeta) - Required - Metadata associated with the job.

### Request Example
```json
{
  "job": {
    "userId": "123",
    "action": "sendWelcomeEmail"
  },
  "meta": {
    "attempts": 1,
    "delay": 0
  }
}
```

### Response
#### Success Response (200)
Indicates that the job has been successfully queued or processed.

#### Response Example
```json
{
  "message": "Job processed successfully"
}
```

#### Error Response (e.g., 500)
Indicates an error occurred during job processing.

```json
{
  "error": "Failed to process job: Internal server error"
}
```
```

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

### Create Vercel Serverless Queue - TypeScript

Source: https://docs.quirrel.dev/api/vercel

This snippet demonstrates how to create a new Quirrel queue within a Vercel Serverless Function. It requires the 'quirrel/vercel' package and exports a Queue instance configured with a path and a worker function.

```typescript
import { Queue } from "quirrel/vercel";

export default Queue(
  "api/someQueue",
  async (job, meta) => {
    // do something
  }
);

```

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

### Remove Old Data with Quirrel CronJob (TypeScript)

Source: https://docs.quirrel.dev/recipes/remove-old-data

This snippet demonstrates how to set up a CronJob using Quirrel in a TypeScript environment. It schedules a task to run hourly, deleting log entries older than 3 days for non-premium customers. Dependencies include 'db' for database operations, 'quirrel/blitz' for CronJob functionality, and 'date-fns' for date manipulation.

```typescript
import db from "db";
import { CronJob } from "quirrel/blitz";
import { subDays } from "date-fns";

export default CronJob(
  "api/remove-old-data", // 👈 the route that it's reachable on
  "0 * * * *", // same as @hourly (see https://crontab.guru/)
  async () => {
    await db.logs.deleteMany({
      where: {
        customer: {
          isPremium: false,
        },
        date: {
          lt: subDays(Date.now(), 3),
        },
      },
    });
  }
);

```

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

### Define Quirrel Environment Variables for Docker

Source: https://docs.quirrel.dev/deployment/docker

Specifies the necessary environment variables for the Quirrel Docker container, including Redis connection details and passphrases. These are typically stored in a .env file.

```env
REDIS_URL=your_redis_url
PASSPHRASES=your_passphrases
REDIS_TLS_CA_BASE64=your_base64_encoded_certificate # if applicable
REDIS_TLS_CA_FILE=your_certificate_file_path # if applicable
```

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

### POST /api/someQueue

Source: https://docs.quirrel.dev/api/vercel

Creates a new Quirrel Serverless Function queue. This queue can be used to process jobs asynchronously. Ensure the queue is exported from a Serverless Function to function correctly.

```APIDOC
## POST /api/someQueue

### Description
Creates a new Quirrel Serverless Function queue. This queue can be used to process jobs asynchronously. Ensure the queue is exported from a Serverless Function to function correctly.

### Method
POST

### Endpoint
/api/someQueue

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
This endpoint does not explicitly define a request body in the provided documentation. The queue configuration is handled during the function's initialization.

### Request Example
```typescript
import { Queue } from "quirrel/vercel";

export default Queue(
  "api/someQueue",
  async (job, meta) => {
    // do something with the job payload and metadata
    console.log("Processing job:", job);
  }
);
```

### Response
#### Success Response (200)
This endpoint does not return a specific success response body. The success is indicated by the successful deployment and availability of the queue.

#### Response Example
None provided.
```

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

### Invoke a Job Instance (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Invokes the execution of a `Job` instance directly. Returns `false` if the job has already been executed or deleted, otherwise returns `true` upon successful invocation.

```typescript
invoke(): Promise<boolean>
```

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

### Pages Router Queue Handler

Source: https://docs.quirrel.dev/api/next

Defines a Quirrel queue using the Pages Router's API Route pattern.

```APIDOC
## POST /api/queues/sample

### Description
This endpoint is an API Route for a Quirrel queue, processing jobs asynchronously.

### Method
POST

### Endpoint
/api/queues/sample

### Parameters
#### Request Body
- **job** (any) - The payload of the job to be processed.
- **meta** (JobMeta) - Metadata associated with the job.

### Request Example
```json
{
  "job": {},
  "meta": {}
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the job was successfully processed.

#### Response Example
```json
{
  "message": "Job processed successfully"
}
```
```

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

### Create Queue with Next.js App Router

Source: https://docs.quirrel.dev/api/next

Defines a new queue using Quirrel within a Next.js App Router route handler. The queue is exported as the POST handler for the specified route. Ensure the queue is exported from a Route Handler for proper functionality.

```typescript
import { Queue } from "quirrel/next-app";
  
export const sampleQueue = Queue(
  "api/queues/sample",
  async (job, meta) => {
    // do something
  }
);
  
export const POST = sampleQueue;
```

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

### Create a Quirrel Queue in Blitz.js

Source: https://docs.quirrel.dev/api/blitz

This snippet demonstrates how to create a new Quirrel queue within a Blitz.js API route. It requires the 'quirrel/blitz' package and exports a Queue instance that handles job processing.

```typescript
import { Queue } from "quirrel/blitz";

export default Queue(
  "api/someQueue",
  async (job, meta) => {
      // do something
  }
);

```

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

### Enqueue an Ordered and Exclusive Job (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Demonstrates enqueuing a job with an ID and setting `exclusive: true`. This ensures that if multiple jobs share the same `runAt` time, they are ordered by their ID, and `exclusive: true` prevents concurrent execution of jobs within the same queue.

```typescript
orderQueue.enqueue(
  { ... },
  {
    id: "1234", // if two jobs share the same `runAt`, they're ordered by ID.
    exclusive: true, // make sure only one job is executed at once
  }
);
```

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

### Pin Quirrel Version in Dockerfile

Source: https://docs.quirrel.dev/deployment/railway

Update the Dockerfile to specify a particular version of the Quirrel Docker image. This ensures consistent deployments by avoiding unexpected changes from the 'main' branch.

```dockerfile
- FROM ghcr.io/quirrel-dev/quirrel:main
+ FROM ghcr.io/quirrel-dev/quirrel:sha-f218c98
```

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

### Quirrel Queue Function Signature

Source: https://docs.quirrel.dev/api/express

This shows the TypeScript signature for the Quirrel Queue function. It outlines the parameters required for creating a queue instance, including the path, the worker function, and optional default job options.

```typescript
function Queue<T>(  
  path: string,  
  worker: (job: T, meta: JobMeta): Promise<void>,  
  defaultJobOptions?: { exclusive?: boolean }  
): QueueInstance<T>
```

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

### Define Database Model for Uploaded Data (Prisma)

Source: https://docs.quirrel.dev/recipes/processing-upload-in-background

Defines a Prisma schema for storing uploaded CSV data. It includes an auto-incrementing ID and a string field for the data itself. This model serves as the basis for storing uploaded content before processing.

```prisma
model UploadedCSV {
  id          Number @id @default(autoincrement())
  data        String
}
```

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

### Process Uploaded CSV Data with Quirrel Queue (TypeScript/Blitz.js)

Source: https://docs.quirrel.dev/recipes/processing-upload-in-background

This code defines a Quirrel queue worker that fetches uploaded CSV data from the database using its ID, performs the necessary processing, and then deletes the record from the database. It demonstrates how to consume tasks from a queue and interact with the database.

```typescript
// app/api/process-csv
import db from "db"
import {Queue} from "quirrel/blitz"

export default Queue("api/process-csv", async (uploadId: number) => {
  const upload = await db.uploadedCsv.findUnique({
    where: {id: uploadId},
  })

  await doYourProcessing(upload.data)

  await db.uploadedCsv.delete({where: {id: uploadId}})
})
```

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

### Create Queue with Next.js Pages Router

Source: https://docs.quirrel.dev/api/next

Creates a new queue using Quirrel within a Next.js Pages Router API route. The queue is exported as the default export of the API route file. It's crucial to export the queue from an API Route for it to function correctly.

```typescript
import { Queue } from "quirrel/next-pages";
  
export default Queue("api/queues/sample", async (job, meta) => {
  // do something
});
```

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

### Create Quirrel Queue in Redwood Function

Source: https://docs.quirrel.dev/api/redwood

This snippet demonstrates how to create a new Quirrel queue within a Redwood serverless function. It utilizes the `Queue` constructor from 'quirrel/redwood' and requires exporting the handler for the queue to function correctly. The worker function processes jobs and can optionally accept default job options.

```javascript
import { Queue } from "quirrel/redwood";

export const handler = Queue(
  "someQueue",
  async (job, meta) => {
    // do something
  }
);

export default handler;
```

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

### Export Queue as Remix Route Action (.ts)

Source: https://docs.quirrel.dev/api/remix

Exports a previously defined Quirrel queue as a route action in a Remix application. This makes the queue accessible and functional within the application's routing system.

```typescript
import someQueue from "~/queues/someQueue.server";  
  
export const action = someQueue;  

```

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

### Invoke a Job by ID (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Retrieves a job by its ID and immediately invokes its execution. Returns the `Job` object if found and invoked, otherwise returns `null`.

```typescript
invoke(id: string): Promise<Job<T> | null>
```

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

### Define Booking Reminder Queue (TypeScript)

Source: https://docs.quirrel.dev/recipes/event-reminder

Defines a Quirrel queue for sending booking reminders. It takes a booking ID, finds the booking details, and sends an SMS notification. This is the core function for scheduling reminders.

```typescript
import { Queue } from "quirrel/next";

export default Queue("api/booking-reminder", async (bookingId) => {
  const booking = await findBooking(bookingId);

  await sendSms({
    to: booking.user.phoneNumber,
    body: `Put on your dancing shoes for ${booking.event.title} 🕺`,
  });
});

```

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

### Create Monthly Invoice CronJob with Quirrel

Source: https://docs.quirrel.dev/recipes/monthly-invoices

This TypeScript code defines a scheduled job using Quirrel's CronJob to generate monthly invoices. It fetches customer data from a database and uses the Stripe API to finalize invoices for each customer. The job is configured to run once a month.

```typescript
import db from "db";
import { CronJob } from "quirrel/blitz";
import stripe from "stripe";

export default CronJob(
  "api/monthly-invoice", // 👈 the route that it's reachable on
  "0 0 1 * *", // same as @monthly (see https://crontab.guru/)
  async () => {
    const customers = await db.customers.findAll();
    await Promise.all(
      customers.map(async (customer) => {
        await stripe.finalizeInvoice(customer.stripeId);
      })
    );
  }
);

```

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

### Define a Quirrel Queue in Remix (.server.ts)

Source: https://docs.quirrel.dev/api/remix

Defines a new Quirrel queue in a Remix application. The queue must be exported from a file with the `.server` extension to be recognized by server code pruning. The worker function processes jobs and metadata.

```typescript
import { Queue } from "quirrel/remix";  
  
export default Queue(  
  "queues/someQueue",  
  async (job, meta) => {  
    // do something  
  },
);

```

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

### Enqueue Multiple Jobs at Once (TypeScript)

Source: https://docs.quirrel.dev/api/queue

The `enqueueMany` method allows for the creation of multiple jobs in a single operation, improving efficiency. It accepts an array of job objects, each with a payload and optional configuration. There is a hard limit of 1000 jobs per `enqueueMany` call.

```typescript
async enqueueMany(
  jobs: { payload: T; options?: EnqueueJobOpts }[]
): Promise<Job<T>[]>
```

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

### Configure Retry Schedule for Reminders (TypeScript)

Source: https://docs.quirrel.dev/recipes/event-reminder

Configures a retry schedule for the booking reminder queue. If the SMS sending fails, Quirrel will automatically retry the job at specified intervals (10 seconds, 1 minute, and 2 minutes after the scheduled date).

```typescript
export default Queue(
  "api/booking-reminder",
  ...,
  {
    // if execution fails, it will be retried
    // 10s, 1min and 2mins after the scheduled date
    retry: [ "10s", "1min", "2min" ]
  }
)

```

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

### Quirrel Queue Function Signature

Source: https://docs.quirrel.dev/api/blitz

This shows the TypeScript signature for the Quirrel Queue function used in Blitz.js. It outlines the parameters for path, worker function, and optional default job options.

```typescript
function Queue<T>(
  path: string,
  worker: (job: T, meta: JobMeta): Promise<void>,
  defaultJobOptions?: { exclusive?: boolean }
): QueueInstance<T>

```

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

### Delete a Job Instance (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Deletes a `Job` instance from the queue. Returns `false` if the job has already been deleted or executed, otherwise returns `true` upon successful deletion.

```typescript
delete(): Promise<boolean>
```

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

### Check if Upload Has Finished Processing (TypeScript/Blitz.js)

Source: https://docs.quirrel.dev/recipes/processing-upload-in-background

This query checks if an upload has been processed by querying the `uploadedCsv` table for the existence of a record with the given `uploadId`. If no record is found, it implies the processing is complete and the record has been deleted. This provides a way to determine the status of an upload.

```typescript
// app/queries/hasFinishedProcessing
import db from "db"

export default async function hasFinishedProcessing(uploadId: number) {
  const count = await db.uploadedCsv.count({where: {uploadId}})
  return count === 0
}
```

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

### Quirrel Queue Function Signature

Source: https://docs.quirrel.dev/api/redwood

This shows the TypeScript signature for the Quirrel `Queue` function. It defines the parameters required for creating a queue, including the path, the worker function, and optional default job options.

```typescript
function Queue<T>(
  path: string,
  worker: (job: T, meta: JobMeta): Promise<void>,
  defaultJobOptions?: { exclusive?: boolean }
): QueueInstance<T>
```

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

### Delete a Job by ID (TypeScript)

Source: https://docs.quirrel.dev/api/queue

Retrieves a job by its ID and deletes it from the queue. Returns the `Job` object if found and deleted, otherwise returns `null`.

```typescript
delete(id: string): Promise<Job<T> | null>
```

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

### Disable Quirrel Telemetry

Source: https://docs.quirrel.dev/faq

This command demonstrates how to opt out of anonymous telemetry collection in Quirrel by setting the `DISABLE_TELEMETRY` environment variable. This ensures user privacy and prevents data sharing.

```bash
export DISABLE_TELEMETRY=1
```

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

### Replace Leaked Encryption Secret in Quirrel

Source: https://docs.quirrel.dev/faq

Instructions for rotating the encryption secret in Quirrel to mitigate a security breach. This involves setting old and new secrets as environment variables to ensure continuity of existing jobs.

```bash
# Set the old leaked secret to allow decryption of pending jobs
export QUIRREL_OLD_SECRETS='["<your-leaked-secret>"]'

# Set the new encryption secret
export QUIRREL_ENCRYPTION_SECRET="<your-new-secret>"

# After all old jobs are processed, remove the old secrets
# unset QUIRREL_OLD_SECRETS
```

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

### Delete a Booking Reminder (TypeScript)

Source: https://docs.quirrel.dev/recipes/event-reminder

Deletes a scheduled booking reminder job from the queue. This is typically called when a booking is canceled, ensuring that no reminder is sent for a canceled event. It uses the same ID provided during enqueuing.

```typescript
import bookingReminder from "api/booking-reminder"

async function cancelBooking(...) {
  ...
  await bookingReminder.delete(
    bookingId // this is the same ID we set above
  )
}

```
Tokens:
Raw