world.queue

The world.queue interface provides access to workflow run queuing and processing. Use it to enqueue runs for background execution and create handlers to process queued items.

Import

import { getWorld } from "workflow/runtime";

const world = getWorld();
const queue = world.queue;

Methods

getDeploymentId()

Get the current deployment ID. Useful for routing queue messages to the correct deployment.

const deploymentId = await world.queue.getDeploymentId();

Returns: string — The current deployment ID

queue()

Enqueue a workflow run for background processing.

const messageId = await world.queue.queue(name, message, opts);

Parameters:

Parameter	Type	Description
`name`	`ValidQueueName`	The queue name
`message`	`object`	The message payload to enqueue
`opts`	`object`	Optional configuration

Returns: MessageId

createQueueHandler()

Create a handler function for processing queued messages.

const handler = world.queue.createQueueHandler(prefix, callback);

Parameters:

Parameter	Type	Description
`prefix`	`string`	Queue name prefix to match
`callback`	`function`	Handler function called for each queued message

Returns: Queue handler function

Examples

Enqueue a Workflow Run for Background Processing

import { getWorld } from "workflow/runtime";

export async function POST(req: Request) {
  const { workflowName, input } = await req.json();

  const world = getWorld();
  const messageId = await world.queue.queue(workflowName, { 
    input,
    priority: "normal",
  }); 

  return Response.json({ messageId });
}

Create a Queue Handler for Processing

import { getWorld } from "workflow/runtime";

const world = getWorld();

const handler = world.queue.createQueueHandler("my-workflows", async (message) => { 
  console.log("Processing:", message);
  // Handle the queued workflow message
});

Get Current Deployment ID

import { getWorld } from "workflow/runtime";

const world = getWorld();
const deploymentId = await world.queue.getDeploymentId(); 
console.log("Running on deployment:", deploymentId);

start() — Higher-level API for starting workflow runs
Starting Workflows — Core concepts for workflow invocation
world.runs — Inspect queued and running workflows

world.queue

On this page