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 overlapping getTypeNames() throw DuplicateJobTypeError at runtime.
  • createWorkerRunner / processors — overlapping processor keys produce a TypeScript error at compile time and throw DuplicateJobTypeError at 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 to Record<never, never>
  • blockers validates against entry types in T & TExternal
  • The registry's phantom type remains T only — TExternal types 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-notification

See 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.

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open