Jobs

Some work should not hold up a response. Sending mail, calling a slow API, reindexing a thousand rows. A job is where that work goes.

Declare it

Put a file under your jobs/ directory. Default-export a job({ ... }) and import job from questpie/services.

import { job } from "questpie/services";
import { z } from "zod";

export default job({
	name: "send-welcome-email",
	schema: z.object({ userId: z.string() }),
	handler: async ({ payload, collections, email }) => {
		const user = await collections.user.findOne({
			where: { id: payload.userId },
		});
		if (!user) return;
		await email.send({
			to: user.email,
			subject: "Welcome!",
			html: `<p>Hi ${user.name}, thanks for signing up.</p>`,
		});
	},
	options: { retryLimit: 3, retryDelay: 30, retryBackoff: true },
});

Then build the dispatch surface. questpie add job send-welcome-email writes the file and runs this step for you.

questpie generate   # registers the job, adds queue.sendWelcomeEmail

What that file produced

The dispatch key comes from the file name, camel-cased. jobs/send-welcome-email.ts is queue.sendWelcomeEmail whatever you passed to name. That name is the durable string the broker stores. One file is one job.

Dispatch it

collection("user").hooks({
	afterChange: async ({ data, operation, queue }) => {
		if (operation !== "create") return;
		await queue.sendWelcomeEmail.publish({ userId: data.id });
	},
});

publish() parses the payload against schema first. A wrong shape throws at the call site, not in a worker an hour later. The worker parses it again before your handler runs.

It resolves to a dispatchId, the stable id for this logical run, never to the handler's return value. A job is fire and forget. If you need a result, write it to the database from the handler and read it back.

Inside a hook, publish() joins the ambient transaction, so a rollback queues nothing. See Transactional dispatch.

The handler argument

The handler takes one argument. It is the validated payload plus the flat app context, so destructure what you need.

handler: async ({ payload, dispatchId, idempotencyKey, locale, ...ctx }) => {};

• payload is the output of schema, already parsed.
• dispatchId is stable across retries and duplicate delivery. Pass it to a downstream provider as that provider's idempotency key.
• idempotencyKey is what the caller passed, when they passed one.
• locale is the app's default locale. The dispatching request's locale does not travel with the job.
• The rest is the same AppContext a route or hook gets. That is db, collections, globals, queue, email, search, realtime, kv, storage, services, logger, t and app. It includes queue, so a job can publish other jobs.

Options

options holds the per-job defaults. Every field is optional.

publish() takes these again as a second argument, cron aside, and a call-time value wins. It also takes three the job cannot declare. Dispatching covers both sets in full.

Recurring work

Add options.cron. A worker registers the schedule when it boots.

export default job({
	name: "purge-expired-sessions",
	schema: z.object({}),
	options: { cron: "0 3 * * *" }, // every day at 03:00
	handler: async ({ db }) => {
		/* ...delete expired sessions... */
	},
});

startAfter is stripped from a cron job. It means nothing for a schedule. Use queue.<name>.schedule(payload, cron) instead when the schedule carries a payload, or when you decide it at runtime.

Running a worker

Publishing only enqueues. Something has to drain the queue. Which entrypoint you write depends on the adapter.

import { app } from "#questpie";

await app.queue.listen();

Run that as its own process. Calling the wrong one for your adapter throws. Workers has all three, plus what each adapter reads.

Jobs you already have

The core module ships three, written the same way as yours. The framework publishes them, so you rarely call them.

Where each topic lives

Next

Emails is the typed template a welcome job renders, so the copy lives beside the schema instead of inside the handler.