Job Type References
Job type definition patterns and type hierarchy.
Overview
This document describes the model for how job types reference each other. Instead of referencing other job types by name only, the system supports two reference modes that can be combined flexibly.
Reference Modes
Nominal Reference (by typeName)
Explicitly reference job types by their name. Supports union of names for flexibility:
TypeScript
{
typeName: "step2" | "step2_alt";
}Structural Reference (by input)
Reference job types by their input type signature. This matches all job types whose input matches the given structure:
TypeScript
{ input: { b: boolean } | { c: string } }When multiple job types match, the user decides which one to use at runtime.
Application
Continuation (continueWith)
Defines what job types a job can continue to. References can use either mode or combine them with unions:
TypeScript
continueWith: { typeName: 'step2' | 'step2_alt' } | { input: { c: boolean } }Structural references enable loose coupling — a router doesn't need to know every handler by name:
TypeScript
const jobTypes = defineJobTypes<{
router: {
entry: true;
input: { path: string };
continueWith: { input: { payload: string } };
};
"handler-a": {
input: { payload: string };
output: { resultA: string };
};
"handler-b": {
input: { payload: string };
output: { resultB: number };
};
}>();
// continueWith accepts either "handler-a" or "handler-b" — both match the input shapeBlockers
Defines job types that must complete before this job can run. Blockers are an ordered array supporting two slot types:
Fixed slots: Each position requires exactly one blocker matching the reference.
TypeScript
blockers: [{ typeName: "auth" }, { typeName: "validate" }];Rest/variadic slots: Zero or more blockers matching the reference.
TypeScript
blockers: [
{ typeName: 'auth' },
...{ typeName: 'validator' }[]
]Structural references allow any entry job type with a matching input shape to satisfy a blocker slot:
TypeScript
const jobTypes = defineJobTypes<{
"fetch-a": {
entry: true;
input: { url: string };
output: { data: string };
};
"fetch-b": {
entry: true;
input: { url: string };
output: { data: string };
};
aggregate: {
entry: true;
input: null;
output: { combined: string[] };
blockers: [...{ input: { url: string } }[]];
};
}>();
// aggregate accepts any number of blockers whose input has { url: string }
// — both "fetch-a" and "fetch-b" qualifyBlocker Output Typing
When accessing job.blockers, outputs are typed based on the reference:
- Nominal reference: Output type of the named job type(s)
- Structural reference: Union of output types from all matching job types
TypeScript
const jobTypes = defineJobTypes<{
auth: {
entry: true;
input: { token: string };
output: { userId: string };
};
validate: {
entry: true;
input: { data: unknown };
output: { valid: boolean };
};
process: {
entry: true;
input: { action: string };
output: { done: boolean };
blockers: [{ typeName: "auth" }, { typeName: "validate" }];
};
}>();
const processors = createProcessors({
client,
jobTypes,
processors: {
process: {
attemptHandler: async ({ job, complete }) => {
const [auth, validate] = job.blockers;
// auth.output is { userId: string }
// validate.output is { valid: boolean }
return withTxHooks(async (txHooks) =>
db.transaction(async (tx) =>
complete({
tx,
txHooks,
output: { done: auth.output.userId !== "" && validate.output.valid },
}),
),
);
},
},
},
});Structural Matching Semantics
When using { input: Type }, the system finds all job types whose input matches that type. This enables abstraction — multiple implementations can share an input contract — and runtime flexibility — the caller chooses the specific implementation when calling continueWith.
Validation
With defineJobTypes, references are checked at compile time only; with createJobTypes, they are also validated at runtime and invalid references throw JobTypeValidationError. See Runtime Validation.
See Also
- Chain Patterns — Continuation patterns (linear, branched, loops, go-to)
- Job Blockers — Fan-out/fan-in dependencies
- Chain Model — Chain structure, Promise analogy
- Job Processing — Handler lifecycle,
complete, and the worker lease