Skip to main content
Version: Next

wasp/server/jobs

Your app's Jobs, which you can submit from your server code.

Wasp generates two exports per Job, named after the worker function you pass to job in the Wasp Spec:

  • A value with the same name as the worker function (e.g. mySpecialJob), of type PgBossJob. Use it to submit the Job.
  • A generic type named after the worker function in PascalCase (e.g. MySpecialJob<Input, Output>), which is a JobFn with the Job's Entities. Use it to type the worker function.

Placeholder Types​

PgBossJob​

Placeholder

You can't import this name. Wasp generates the real exports from your Wasp Spec, named as the top of this page explains. This entry documents their general type.

A Job you can submit to be executed by its executor, pg-boss.

In the values Wasp generates (e.g. mySpecialJob), Input is JSONObject and Output is JSONValue | void, so submit accepts any JSON object, not only the Input type of the worker function.

Extends​

Type Parameters​

Input​

Input extends JSONObject

The type of the data you submit the Job with.

Output​

Output extends JSONValue | void

The type of the Job's result.

Entities​

Entities

The Entities the Job uses.

Properties​

executorName​

readonly executorName: string | symbol

The name of the Job's executor (a Symbol for pg-boss).

Overrides​

Job.executorName

jobName​

readonly jobName: string

The Job's name, which Wasp derives from the worker function you pass to job in the Wasp Spec.

Overrides​

Job.jobName

Methods​

delay()​

delay(startAfter): PgBossJob<Input, Output, Entities>

Returns a copy of this Job that delays the invocation of the worker function when you submit it.

Parameters​
startAfter​

string | number | Date

When to run the Job. One of:

  • A number: the number of seconds to delay.
  • A string: a UTC ISO date string (ending in Z) to run at.
  • A Date: the date to run at.
Returns​

PgBossJob<Input, Output, Entities>

Example​
import { mySpecialJob } from "wasp/server/jobs";

const submittedJob = await mySpecialJob
  .delay(10)
  .submit({ name: "Johnny" }, { retryLimit: 2 });
submit()​

submit(jobArgs, jobOptions?): Promise<PgBossSubmittedJob<Input>>

Submits the Job to be executed by pg-boss.

Parameters​
jobArgs​

Input

The JSON object the worker function receives as its args argument. Pass {} if the worker function takes no arguments. In JavaScript, you can also omit it, and the worker function receives null.

jobOptions?​

PgBossSendOptions

pg-boss specific options for the submission. They override the ones in the Job's performExecutorOptions.pgBoss field in the Wasp Spec.

Returns​

Promise<PgBossSubmittedJob<Input>>

Example​
import { mySpecialJob } from "wasp/server/jobs";

const submittedJob = await mySpecialJob.submit({ name: "Johnny" });

JobFn​

JobFn<Input, Output, Entities> = (args, context) => Promise<Output>

Placeholder

You can't import this name. Wasp generates the real exports from your Wasp Spec, named as the top of this page explains. This entry documents their general type.

The type of a Job's worker function: an async function that performs the Job's work. The value it returns is the Job's result.

Since Wasp executes Jobs on the server, the worker function's import path must lead to a Node.js file.

The type Wasp generates for each Job (e.g. MySpecialJob for mySpecialJob) fills in Entities. You must pass it the other two type arguments, Input and Output.

Type Parameters​

Input​

Input extends JSONObject

The type of the worker function's args argument.

Output​

Output extends JSONValue | void

The type of the worker function's return value.

Entities​

Entities

The type of context.entities.

Parameters​

args​

Input

The data you submit the Job with. For scheduled runs, it's the args in the Job's schedule field, or null if you didn't set them.

context​

The context object. Its entities field has the Prisma API for each Entity in the Job's entities field, keyed by the Entity's name (e.g. context.entities.Task exposes prisma.task from Prisma's CRUD API).

entities​

Entities

Returns​

Promise<Output>

Example​

import { type MySpecialJob } from "wasp/server/jobs";
import { type Task } from "wasp/entities";

type Input = { name: string };
type Output = { tasks: Task[] };

export const mySpecialJob: MySpecialJob<Input, Output> = async (
  { name },
  context,
) => {
  console.log(`Hello ${name}!`);
  const tasks = await context.entities.Task.findMany({});
  return { tasks };
};

Referenced Types​

Job​

This is a definition of a job (think draft or invocable computation), not the running instance itself. This can be submitted one or more times to be executed by some job executor via the same instance. Once submitted, you get a SubmittedJob to track it later.

Extended by​

Constructors​

Constructor​

new Job(jobName, executorName): Job

Parameters​
jobName​

string

executorName​

string | symbol

Returns​

Job

Properties​

executorName​

readonly executorName: string | symbol

jobName​

readonly jobName: string

SubmittedJob​

This is the result of submitting a Job to some executor. It can be used by callers to track things, or call executor-specific subclass functionality.

Constructors​

Constructor​

new SubmittedJob(job, jobId): SubmittedJob

Parameters​
job​

Job

jobId​

string

Returns​

SubmittedJob

Properties​

job​

readonly job: Job

jobId​

readonly jobId: string

JSONArray​

Extends​

Indexable​

[n: number]: JSONValue

JSONObject​

Indexable​

[key: string]: JSONValue

PgBossSubmittedJob​

The result of submitting a Job, which you can use to track it.

Extends​

Type Parameters​

Input​

Input extends JSONObject

Properties​

job​

readonly job: Job

The Job you submitted. It has the Job's jobName and executorName.

Overrides​

SubmittedJob.job

jobId​

readonly jobId: string | null

The ID of the Job in pg-boss, or null if pg-boss didn't create the Job because of a singleton option like singletonKey. In that case, pgBoss.cancel and pgBoss.resume reject, and pgBoss.details resolves to null.

pgBoss​

readonly pgBoss: object

pg-boss specific functions for the submitted Job.

cancel​

readonly cancel: () => Promise<PgBossUpdateResult>

Attempts to cancel the Job.

Returns​

Promise<PgBossUpdateResult>

See​

pg-boss's cancel docs

details​

readonly details: () => Promise<PgBossJobDetails<Input> | null>

Gets pg-boss's details about the Job, or null if it doesn't exist.

Returns​

Promise<PgBossJobDetails<Input> | null>

resume​

readonly resume: () => Promise<PgBossUpdateResult>

Attempts to resume a cancelled Job.

Returns​

Promise<PgBossUpdateResult>

See​

pg-boss's resume docs

JSONValue​

JSONValue = PrimitiveJSONValue | JSONArray | JSONObject

PgBossJobDetails​

PgBossJobDetails<Input> = object

pg-boss's details about a submitted Job.

This lists the most common fields. See all of them in pg-boss's getJobById docs.

Type Parameters​

Input​

Input extends JSONObject

Properties​

completedon​

completedon: Date | null

When the Job completed, if it did.

createdon​

createdon: Date

When the Job was created.

data​

data: Input

The data the Job was submitted with.

id​

id: string

The ID of the Job in pg-boss.

name​

name: string

The name of the Job.

output​

output: object | null

The Job's result:

  • When state is "completed", the worker function's return value. pg-boss wraps primitives and arrays in an object with a value property (e.g. { value: 42 }), and stores null if it returned nothing.
  • When state is "failed", the error. A Job that failed and is waiting to be retried also has the error here.
  • Otherwise, usually null.
retrycount​

retrycount: number

How many times pg-boss has retried the Job.

startedon​

startedon: Date | null

When the Job started, or null if it hasn't started yet.

state​

state: "created" | "retry" | "active" | "completed" | "expired" | "cancelled" | "failed"

The Job's state.

PgBossSendOptions​

PgBossSendOptions = object

pg-boss's options for submitting a Job.

This lists the most common ones. See all of them in pg-boss's send docs.

Properties​

expireInSeconds?​

optional expireInSeconds?: number

How many seconds the Job can run before it expires.

priority?​

optional priority?: number

Higher numbers have higher priority.

retentionSeconds?​

optional retentionSeconds?: number

How many seconds to keep the Job in the queue before archiving it.

retryBackoff?​

optional retryBackoff?: boolean

Whether to use exponential backoff between retries.

retryDelay?​

optional retryDelay?: number

How many seconds to wait between retries.

retryLimit?​

optional retryLimit?: number

How many times to retry the Job if it fails.

singletonKey?​

optional singletonKey?: string

Only allows one queued or active submission of this Job with this key at a time. If there already is one, pg-boss doesn't create a new one, and the submitted Job's jobId is null.

startAfter?​

optional startAfter?: number | string | Date

Delays the Job like PgBossJob.delay. (Default 0)

PgBossUpdateResult​

PgBossUpdateResult = object

pg-boss's result of attempting to cancel or resume a Job.

Properties​

jobs​

jobs: string[]

The IDs of the Jobs pg-boss tried to update: only the submitted Job's.

requested​

requested: number

How many Jobs pg-boss tried to update: always 1.

updated​

updated: number

How many Jobs pg-boss updated. It's 0 if pg-boss didn't change the Job (e.g. when you try to cancel a Job that already finished).

PrimitiveJSONValue​

PrimitiveJSONValue = string | number | boolean | undefined | null