Feature Slices
Organize job types and processors into independent feature modules.
As your application grows, defining all job types and processors in a single file becomes unwieldy. Feature slices let you split them by domain — each slice owns its type definitions and processor handlers, composed together at the application level.
Defining a Slice
A slice consists of two files: definitions and processors.
Files
- src/
- slice-notifications-definitions.ts
- slice-notifications-processors.ts
- slice-orders-definitions.ts
- slice-orders-processors.ts
- client.ts
- index.ts
Definitions declare the job types for a feature:
src/slice-notifications-definitions.ts
import { defineJobTypes } from "queuert";
export const notificationJobTypes = defineJobTypes<{
/*
* notifications.send-notification
*/
"notifications.send-notification": {
entry: true;
input: { userId: string; message: string };
output: { sentAt: string };
};
}>();Processors implement the handlers, typed against the slice's definitions:
src/slice-notifications-processors.ts
import { createProcessors } from "queuert";
import { client, stateAdapter } from "./client.ts";
import { notificationJobTypes } from "./slice-notifications-definitions.ts";
export const notificationProcessors = createProcessors({
client,
jobTypes: notificationJobTypes,
processors: {
"notifications.send-notification": {
attemptHandler: async ({ complete }) =>
stateAdapter.withTransaction(async (txCtx) =>
complete({ ...txCtx, output: { sentAt: new Date().toISOString() } }),
),
},
},
});createProcessors type-checks each handler against the slice's own definitions (plus any external defs it declares), then returns a Processors that's plugged into createWorkerRunner.
Composing Slices
At the application level, pass an array of slices to createClient:
src/client.ts
import { createClient, createInProcessStateAdapter } from "queuert";
import { notificationJobTypes } from "./slice-notifications-definitions.ts";
import { orderJobTypes } from "./slice-orders-definitions.ts";
export const stateAdapter = createInProcessStateAdapter({ mode: "async" });
export const client = createClient({
stateAdapter,
jobTypes: [orderJobTypes, notificationJobTypes],
});and an array of their processors to createWorkerRunner:
src/index.ts
await using workerRunner = createWorkerRunner({
client,
processors: [orderProcessors, notificationProcessors],
});
await workerRunner.start();Both fields accept a single slice or an array of slices. When an array is passed, duplicate type/processor keys are detected:
createClient/jobTypes— overlapping type names produce a TypeScript error at compile time; validated registries with overlappinggetTypeNames()throwDuplicateJobTypeErrorat runtime.createWorkerRunner/processors— overlapping processor keys produce a TypeScript error at compile time and throwDuplicateJobTypeErrorat runtime.
To run a slice's job types on different workers, split its registry with pickProcessors / omitProcessors — see Splitting a Registry.
Cross-Slice References
When a slice needs to reference job types from another slice — here, orders.confirm-order waits for a notification from the notifications slice — use the optional TExternal type parameter on defineJobTypes:
src/slice-orders-definitions.ts
import { type JobTypeDefinitions, defineJobTypes } from "queuert";
import type { notificationJobTypes } from "./slice-notifications-definitions.ts";
export const orderJobTypes = defineJobTypes<
{
/*
* orders.place-order --------------+--> orders.confirm-order
* notifications.send-notification -+
*/
"orders.place-order": {
entry: true;
input: { orderId: string; userId: string };
continueWith: { typeName: "orders.confirm-order" };
};
"orders.confirm-order": {
input: { orderId: string };
output: { confirmedAt: string };
blockers: [{ typeName: "notifications.send-notification" }];
};
},
JobTypeDefinitions<typeof notificationJobTypes>
>();- The first parameter,
T, holds the owned definitions, which become the registry's phantom type - The second parameter,
TExternal, is the read-only reference context and defaults toRecord<never, never> blockersvalidates against entry types inT & TExternal- The registry's phantom type remains
Tonly —TExternaltypes are not included
This eliminates the need for "workflow slices" that duplicate type definitions just to make blocker references type-check. When slices are passed as an array to createClient, all references resolve against the full set of definitions.
Processors that reference types from another slice need nothing special: the client already exposes every slice's types, so orders.place-order creates a notifications.send-notification chain and passes it as the blocker of its continuation, and orders.confirm-order reads the notification's typed output from job.blockers:
src/slice-orders-processors.ts
import { createProcessors } from "queuert";
import { client, stateAdapter } from "./client.ts";
import { orderJobTypes } from "./slice-orders-definitions.ts";
export const orderProcessors = createProcessors({
client,
jobTypes: orderJobTypes,
processors: {
"orders.place-order": {
attemptHandler: async ({ job, complete }) =>
stateAdapter.withTransaction(async (txCtx) => {
const notificationChain = await client.createChain({
...txCtx,
typeName: "notifications.send-notification",
input: { userId: job.input.userId, message: `Order ${job.input.orderId} received` },
});
return complete({
...txCtx,
continueWith: {
typeName: "orders.confirm-order",
input: { orderId: job.input.orderId },
blockers: [notificationChain],
},
});
}),
},
"orders.confirm-order": {
attemptHandler: async ({ job, complete }) => {
const [notification] = job.blockers;
return stateAdapter.withTransaction(async (txCtx) =>
complete({ ...txCtx, output: { confirmedAt: notification.output.sentAt } }),
);
},
},
},
});Naming Convention
Note
Prefix job type names with the slice name to avoid collisions and make logs and dashboards easy to scan by feature.
Text
orders.place-order
orders.confirm-order
notifications.send-notificationSee examples/guides-slices for the runnable code. See also Chain Patterns for continuation patterns and the API reference for defineJobTypes, createJobTypes, createProcessors, pickProcessors and omitProcessors.