Validation

Runtime validation of job inputs, outputs, continuations and blockers with Zod, Valibot, TypeBox or ArkType.

Queuert's runtime validation follows an adapter pattern. The core provides createJobTypes, which accepts raw validation and codec functions. Schema-specific adapters (Zod, Valibot, TypeBox, ArkType) are implemented in user-land, wrapping their respective schema libraries into the JobTypes interface.

Each adapter:

  1. Accepts schema definitions in the library's native format.
  2. Infers the job type definitions from the schemas, providing the same compile-time safety as defineJobTypes.
  3. Calls createJobTypes with functions that delegate to the schema library.

When to use runtime validation instead of the type-only defineJobTypes is covered in the Runtime Validation guide.

Runtime form vs stored form

A job type definition's input and output describe the runtime form — what a handler receives and what a client read returns. The stored form is what the state adapter persists, and it must be JSON-serializable.

The two forms are bridged by an encoder and a decoder for each of input and output:

  • encodeInput / encodeOutput run on every write, turning the runtime form into the stored form.
  • decodeInput / decodeOutput run on every read, turning the stored form back into the runtime form.

For most schemas the two forms are identical and both methods are a validation pass that returns the value unchanged. They diverge when a schema transforms — a Date in the handler stored as an ISO string, for instance. Whatever an encoder returns is checked against isJsonSerializable by createJobTypes itself, so an adapter that lets a Date reach storage fails on the first write, before anything is stored.

defineJobTypes has no codec, so the runtime form is the stored form: it constrains input and output to JSON-serializable types at compile time, and a definition carrying a Date, Map or bigint is a type error.

Define job types

src/index.ts

// Define job types with Zod schemas
const jobTypes = createZodJobTypes({
  // Entry point with nominal continuation validation
  "fetch-data": {
    entry: true,
    input: z.object({
      url: z.url(),
      headers: z.record(z.string(), z.string()).optional(),
    }),
    // Nominal validation: validates by type name
    continueWith: z.object({
      typeName: z.literal("process-data"),
    }),
  },

  // Continuation job
  "process-data": {
    input: z.object({
      data: z.object({
        items: z.array(z.number()),
        source: z.string(),
      }),
    }),
    output: z.object({
      processed: z.boolean(),
      itemCount: z.number(),
    }),
  },

  // Entry point with structural blocker validation
  "batch-process": {
    entry: true,
    input: z.object({
      batchId: z.string(),
    }),
    output: z.object({
      success: z.boolean(),
    }),
    // Structural validation: any blocker with { token: string } input is valid
    blockers: z.array(
      z.object({
        input: z.object({ token: z.string() }),
      }),
    ),
  },

  // Auth job - can be used as blocker due to structural match
  auth: {
    entry: true,
    input: z.object({
      token: z.string(),
    }),
    output: z.object({
      userId: z.string(),
    }),
  },
});

The adapter

Complete adapter implementations for each library. What each one costs per job is on the Runtime Performance page.

src/zod-adapter.ts

/**
 * Zod Adapter for Queuert Runtime Validation
 *
 * This is a user-land adapter that shows how to integrate Zod with Queuert's
 * runtime validation system. The same pattern applies to Valibot, ArkType,
 * or any other validation library.
 *
 * Every schema here is identity: `z.input` equals `z.output`, so each field's
 * encoder and decoder are the same validation pass. A schema that transforms
 * would be applied again on every read; see `examples/validation/codec-zod` for the
 * transforming case, where the runtime form and the stored form differ (a
 * `Date` handler-side, an ISO string at rest).
 *
 * Each schema is compiled once with `z.compile`, so the parse that runs on every
 * job read and write takes Zod's generated fast path. A schema Zod cannot compile
 * keeps its regular parser.
 */

import {
  type BaseJobTypeDefinitions,
  type JobTypesDefinitions,
  type JobTypeDefinitionErrors,
  type JobTypeReference,
  type JobTypes,
  type ValidatedJobTypeDefinitions,
  createJobTypes,
} from "queuert";
import { z } from "zod";

/**
 * Schema definition for a single job type using Zod.
 */
export type ZodJobTypeSchema = {
  /** Whether this job type can start a chain (entry point). Default: false */
  entry?: boolean;
  /** Zod schema for validating job input */
  input: z.ZodType;
  /** Zod schema for validating job output. Omit if job must continue. */
  output?: z.ZodType;
  /**
   * Zod schema for validating continuation targets.
   * Receives { typeName, input } object at runtime.
   * Schema can validate typeName (nominal), input (structural), or both.
   *
   * @example
   * // Nominal: validate by type name only
   * continueWith: z.object({ typeName: z.literal("step2") })
   *
   * // Structural: validate by input shape only
   * continueWith: z.object({ input: z.object({ payload: z.unknown() }) })
   *
   * // Both: validate type name and input shape
   * continueWith: z.object({ typeName: z.literal("step2"), input: z.object({ data: z.string() }) })
   */
  continueWith?: z.ZodType<JobTypeReference>;
  /**
   * Zod schema for validating blocker references.
   * Receives array of { typeName, input } objects at runtime.
   * Schema can validate typeName (nominal), input (structural), or both.
   *
   * @example
   * // Fixed blockers by name (tuple)
   * blockers: z.tuple([
   *   z.object({ typeName: z.literal("auth") }),
   *   z.object({ typeName: z.literal("config") }),
   * ])
   *
   * // Variable blockers by name (array)
   * blockers: z.array(z.object({ typeName: z.literal("processor") }))
   *
   * // Structural validation: any blocker with matching input shape
   * blockers: z.array(z.object({ input: z.object({ token: z.string() }) }))
   */
  blockers?: z.ZodType<readonly JobTypeReference[]>;
};

/**
 * Infer BaseJobTypeDefinitions from Zod schemas.
 * This enables compile-time type safety for the job types.
 */
type InferZodJobTypes<T extends Record<string, ZodJobTypeSchema>> = {
  [K in keyof T & string]: {
    entry: T[K]["entry"] extends true ? true : undefined;
    input: z.infer<T[K]["input"]>;
    output: T[K]["output"] extends z.ZodType ? z.infer<T[K]["output"]> : undefined;
    continueWith: T[K]["continueWith"] extends z.ZodType<infer U>
      ? U extends JobTypeReference
        ? U
        : JobTypeReference
      : undefined;
    blockers: T[K]["blockers"] extends z.ZodType<infer U>
      ? U extends readonly JobTypeReference[]
        ? U
        : readonly JobTypeReference[]
      : undefined;
  };
};

/**
 * Create a Zod-based job type registry.
 *
 * This adapter:
 * 1. Accepts Zod schemas for each job type
 * 2. Infers TypeScript types from the schemas
 * 3. Validates at runtime using Zod's .parse() method
 *
 * Errors thrown by Zod are caught by the core registry and wrapped
 * in JobTypeValidationError with the appropriate error code.
 *
 * @example
 * const jobTypes = createZodJobTypes({
 *   "process-data": {
 *     entry: true,
 *     input: z.object({ dataId: z.string() }),
 *     output: z.object({ result: z.number() }),
 *   },
 *   "send-notification": {
 *     entry: true,
 *     input: z.object({ userId: z.string(), message: z.string() }),
 *     output: z.object({ sent: z.boolean() }),
 *   },
 * });
 */
export const createZodJobTypes = <
  const T extends Record<string, ZodJobTypeSchema>,
  const TExternal extends
    | JobTypes<BaseJobTypeDefinitions>
    | readonly JobTypes<BaseJobTypeDefinitions>[] = readonly [],
>(
  schemas: [InferZodJobTypes<T>] extends [
    ValidatedJobTypeDefinitions<InferZodJobTypes<T>, JobTypesDefinitions<TExternal>>,
  ]
    ? T
    : JobTypeDefinitionErrors<InferZodJobTypes<T>, JobTypesDefinitions<TExternal>>,
  _externalDefinitions?: TExternal,
) => {
  const _schemas = Object.fromEntries(
    Object.entries(schemas as Record<string, ZodJobTypeSchema>).map(([typeName, schema]) => [
      typeName,
      {
        entry: schema.entry,
        input: z.compile(schema.input),
        output: schema.output && z.compile(schema.output),
        continueWith: schema.continueWith && z.compile(schema.continueWith),
        blockers: schema.blockers && z.compile(schema.blockers),
      },
    ]),
  );
  const getSchema = (typeName: string): ZodJobTypeSchema => {
    const schema = _schemas[typeName];
    if (!schema) {
      throw new Error(`Unknown job type: ${typeName}`);
    }
    return schema;
  };

  const parseInput = (typeName: string, input: unknown): unknown =>
    getSchema(typeName).input.parse(input);

  const parseOutput = (typeName: string, output: unknown): unknown => {
    const schema = getSchema(typeName).output;
    if (!schema) throw new Error(`Job type "${typeName}" does not have an output schema`);
    return schema.parse(output);
  };

  return createJobTypes<InferZodJobTypes<T>, JobTypesDefinitions<TExternal>>({
    getTypeNames: () => Object.keys(_schemas),
    validateEntry: (typeName) => {
      const schema = getSchema(typeName);
      if (schema.entry !== true) {
        throw new Error(`Job type "${typeName}" is not an entry point`);
      }
    },

    encodeInput: parseInput,
    decodeInput: parseInput,
    encodeOutput: parseOutput,
    decodeOutput: parseOutput,

    validateContinueWith: (typeName, continuation) => {
      const schema = getSchema(typeName);
      if (schema.continueWith) {
        schema.continueWith.parse(continuation);
      } else {
        throw new Error(`Job type "${typeName}" does not support continuations`);
      }
    },

    validateBlockers: (typeName, blockers) => {
      const schema = getSchema(typeName);
      if (schema.blockers) {
        schema.blockers.parse(blockers);
      } else if (blockers.length > 0) {
        throw new Error(`Job type "${typeName}" does not support blockers`);
      }
    },
  });
};

The JobTypes interface

The JobTypes object validates at each boundary:

JobTypes

A rejected value throws JobTypeValidationError; its codes and how it surfaces are in Runtime Validation.

Codec calls

Each codec method takes the typeName and the value. An adapter whose schemas only validate passes one function as both the encoder and the decoder of a field, so a schema that transforms would be applied again on every read; transforming schemas belong in a codec adapter such as the validation/codec-zod example. The encoders are the gate: they run on every write, and a value they reject never reaches the database. The decoders run on every read and only for type names the registry lists in getTypeNames. When a decoder throws, the read that needed the value fails with JobTypeValidationError.

Caution

Keep a job type, and a decoder that accepts every stored shape of it, for as long as rows of that type remain in the database. A row whose job type the registry does not list is read in its stored form, so its input and output do not match the declared types; a decoder that rejects an older stored shape makes every read of that row — including a dashboard page listing it — fail. Delete the chains of a job type before removing it, and change a schema in a way that still decodes rows written under the previous one.

Conformance

Each example checks its adapter with validationAdapterConformanceCases; see Custom validation adapter.

src/zod-adapter.spec.ts

import {
  type ValidationAdapterConformanceContext,
  validationAdapterConformanceCases,
} from "queuert/conformance";
import { describe, test } from "vitest";
import { z } from "zod";

import { createZodJobTypes } from "./zod-adapter.ts";

describe("zod adapter conformance", () => {
  const context: ValidationAdapterConformanceContext = {
    basic: {
      buildEntry: () =>
        createZodJobTypes({
          main: {
            entry: true,
            input: z.object({ id: z.string() }),
            output: z.object({ ok: z.boolean() }),
          },
        }),
      buildNonEntry: () =>
        createZodJobTypes({
          internal: {
            input: z.object({ id: z.string() }),
            output: z.object({ ok: z.boolean() }),
          },
        }),
      buildContinuationOnly: () =>
        createZodJobTypes({
          main: {
            entry: true,
            input: z.object({ id: z.string() }),
            continueWith: z.object({ typeName: z.literal("next") }),
          },
          next: {
            input: z.object({ data: z.string() }),
            output: z.object({ done: z.boolean() }),
          },
        }),
    },
    continuations: {
      buildNominal: () =>
        createZodJobTypes({
          step1: {
            entry: true,
            input: z.object({ id: z.string() }),
            continueWith: z.object({ typeName: z.literal("step2") }),
          },
          step2: {
            input: z.object({ data: z.unknown() }),
            output: z.object({ done: z.boolean() }),
          },
        }),
      buildStructural: () =>
        createZodJobTypes({
          router: {
            entry: true,
            input: z.object({ route: z.string() }),
            continueWith: z.object({ input: z.object({ payload: z.string() }) }),
          },
          handler: {
            input: z.object({ payload: z.string() }),
            output: z.object({ handled: z.boolean() }),
          },
        }),
    },
    blockers: {
      buildNominal: () =>
        createZodJobTypes({
          main: {
            entry: true,
            input: z.object({ id: z.string() }),
            output: z.object({ done: z.boolean() }),
            blockers: z.array(z.object({ typeName: z.literal("auth") })),
          },
          auth: {
            entry: true,
            input: z.object({ token: z.string() }),
            output: z.object({ userId: z.string() }),
          },
        }),
      buildStructural: () =>
        createZodJobTypes({
          main: {
            entry: true,
            input: z.object({ id: z.string() }),
            output: z.object({ done: z.boolean() }),
            blockers: z.array(z.object({ input: z.object({ token: z.string() }) })),
          },
          auth: {
            entry: true,
            input: z.object({ token: z.string() }),
            output: z.object({ userId: z.string() }),
          },
        }),
    },
    external: {
      buildWithExternalSlice: () => {
        const notifications = createZodJobTypes({
          "notifications.send-notification": {
            entry: true,
            input: z.object({ userId: z.string(), message: z.string() }),
            output: z.object({ sentAt: z.string() }),
          },
        });
        return createZodJobTypes(
          {
            "orders.place-order": {
              entry: true,
              input: z.object({ userId: z.string() }),
              continueWith: z.object({ typeName: z.literal("orders.confirm-order") }),
            },
            "orders.confirm-order": {
              input: z.object({ orderId: z.number() }),
              output: z.object({ confirmedAt: z.string() }),
              blockers: z.tuple([
                z.object({ typeName: z.literal("notifications.send-notification") }),
              ]),
            },
          },
          notifications,
        );
      },
      buildWithExternalSlices: () => {
        const notifications = createZodJobTypes({
          "notifications.send-notification": {
            entry: true,
            input: z.object({ userId: z.string(), message: z.string() }),
            output: z.object({ sentAt: z.string() }),
          },
        });
        const payments = createZodJobTypes({
          "payments.charge": {
            entry: true,
            input: z.object({ amount: z.number() }),
            output: z.object({ receiptId: z.string() }),
          },
        });
        return createZodJobTypes(
          {
            "orders.place-order": {
              entry: true,
              input: z.object({ userId: z.string() }),
              continueWith: z.object({ typeName: z.literal("orders.confirm-order") }),
            },
            "orders.confirm-order": {
              input: z.object({ orderId: z.number() }),
              output: z.object({ confirmedAt: z.string() }),
              blockers: z.tuple([
                z.object({ typeName: z.literal("notifications.send-notification") }),
                z.object({ typeName: z.literal("payments.charge") }),
              ]),
            },
          },
          [notifications, payments] as const,
        );
      },
    },
  };

  for (const conformanceCase of validationAdapterConformanceCases) {
    test(conformanceCase.title, async () => {
      await conformanceCase.run(context);
    });
  }
});

Examples

Validation adapters

Codecs

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open