Advanced
Queue reference
Options, types, errors and JSON rules of VitNode's queue API - buildQueueTask, dispatch(task, payload, options), QueueTaskInput and QueueTaskPayload.
Signatures, options, types and errors of the background task queue. For a walkthrough, start with Queue.
buildQueueTask
Server-only. Import it from your plugin's @/api/builders (bindApiPlugin(manifest).buildQueueTask), which fills in pluginId. It returns a QueueTaskDefinition<Plugin, Name, Schema>. The unbound buildQueueTask from @vitnode/core/api/lib/queue takes the same options plus a required pluginId.
Prop
Type
Register the task in a top-level module's queueTasks array.
dispatch()
c.get("queue").dispatch() resolves to { deduplicated: boolean; id: number | null } and only inserts a row.
dispatch(task: QueueTaskDefinition, payload: QueueTaskInput<typeof task>, options?: QueueDispatchOptions)The row is stored under the definition's pluginId and name, whichever plugin's request dispatches it; the options cannot override them. The payload is checked at compile time against the schema's input, then validated at runtime. dispatch throws when the task is not registered or another task holds its name.
Prop
Type
Types
All from @vitnode/core/api/lib/queue, except QueueDispatchOptions and QueueDispatchResult from @vitnode/core/api/models/queue.
| Type | Meaning |
|---|---|
QueueTaskDefinition<Plugin, Name, Schema> | A typed task, as the bound builder returns it. |
QueueTaskInput<typeof task> | What dispatch(task, payload) accepts: the schema's input. |
QueueTaskPayload<typeof task> | What the handler receives: the schema's output. |
QueueDispatchOptions | The third argument of dispatch. |
QueueDispatchResult | { deduplicated, id }. |
Input and output differ when the schema transforms. With at: z.iso.datetime().transform(value => new Date(value)), dispatch takes a string and the handler gets a Date.
JSON payloads
A payload is stored as JSON in core_queue.payload and parsed back for the handler. Before validating, dispatch copies the payload to JSON and throws QueuePayloadValidationError instead of letting JSON.stringify change it:
- Rejected:
Date,Map,Setand other class instances,NaN,Infinity,bigint, functions, circular references, andundefinedor missing (sparse) array items. - Omitted: object properties set to
undefined, exactly as JSON drops them. Make such fields.optional(). - Stored: the JSON input, never the schema's output. The worker parses it again, so a transform runs on every attempt and stored rows stay readable after a transform changes.
The schema's input type must be JSON, so z.date() or z.map() in a payload schema is a compile error. Use z.iso.datetime(), optionally with a .transform().
Errors
| Error | Thrown by | When | Enqueued |
|---|---|---|---|
QueuePayloadValidationError | dispatch | The payload is not JSON, or the schema rejects it. reason lists paths and issue codes, never values. | No |
QueueTaskRegistrationError | dispatch(task, ...) | The task is not registered, or a different task is registered under its name. | No |
QueueTaskRegistrationError | buildApiPlugin | An entry in queueTasks is not a task definition, a task is registered by another plugin, or two different tasks of one plugin share a name. | - |
When the worker finds a stored payload its task's schema rejects, the row becomes failed at once with Invalid payload: ā¦ in lastError; it is not retried and is kept. A row whose task is not registered is retried with No handler registered for queue task "ā¦" until it runs out of attempts.