Standard Library

Rhythm workflows run in a sandboxed environment with a specialized standard library designed for durable execution. Because workflows are persisted to the database and resumed, the standard library focuses on orchestration, state management, and deterministic operations.

Task

The Task module is the primary way to execute logic outside of the workflow sandbox. Tasks are written in your application's native language (e.g., Python) and are executed by workers.

Task.run

Executes a task and optionally waits for the result.

// Call a task and wait for it to complete
const result = await Task.run("process-payment", {
  amount: 50.00,
  currency: "USD"
})

// Fire-and-forget (don't use await)
Task.run("send-telemetry", { event: "workflow_started" })

Parameters:

• target_name: The name of the task registered in your application.
• inputs: A JSON-serializable object passed to the task.

Returns: The JSON-serializable output returned by the task implementation.

Signal

Signals allow workflows to react to external events. When a workflow reaches a Signal.when call, it suspends execution and persists its state until the signal is received or a timeout occurs.

Signal.when

Pauses the workflow until a specific signal is delivered.

try {
  const approval = await Signal.when("manager-approval", { 
    timeout: "24h" 
  })
  // approval contains the payload sent with the signal
} catch (err) {
  // If the timeout is reached, an error is thrown
  if (err.type === "TimeoutError") {
    await Task.run("notify-expiration", { id: Inputs.id })
  }
}

Parameters:

• signal_name: The unique identifier for the event the workflow is waiting for.
• options: An object containing:
  • timeout: (Optional) A string representing the duration to wait (e.g., "1h", "24h", "30m").

Returns: The payload object provided by the external caller who triggered the signal.

Math

Rhythm provides a deterministic subset of the standard JavaScript Math object. These functions ensure that mathematical operations produce consistent results across different platforms and resumptions.

Supported Functions

• Math.floor(x): Returns the largest integer less than or equal to x.
• Math.ceil(x): Returns the smallest integer greater than or equal to x.
• Math.round(x): Returns the value of a number rounded to the nearest integer.
• Math.abs(x): Returns the absolute value of x.

Example:

let itemWeight = 3.7
let total = Math.floor(itemWeight) // 3

Inputs

The Inputs object contains the initial data passed to the workflow when it was started. It is read-only.

// Accessing data passed at start-time
const userId = Inputs.userId
const orderId = Inputs.order.id

Context and Lifecycle

Workflows use standard JavaScript-like control flow to manage their lifecycle.

return

Ending a workflow with return completes the execution and saves the provided value as the workflow's final output. This output can be read by the client that started the workflow or by a parent workflow.

return {
  status: "success",
  processedItems: 42
}

throw / try...catch

Standard error handling is supported. If an error is thrown and not caught, the workflow execution status is set to Failed.

try {
  await Task.run("risky-operation", {})
} catch (err) {
  // Handle task failure or timeout
  console.log(err.message)
}

Global Functions

console.log

Logs a message to the workflow's execution log. This is useful for debugging and tracking progress in the database.

console.log("Starting processing for user", Inputs.userId)