Tasks

Tasks are the fundamental unit of work in Hyrex. They are TypeScript functions that can be executed asynchronously by workers, with automatic retry handling, monitoring, and durability.

Basic Task Definition

Define a task using the hy.task() method:

import { HyrexRegistry } from '@hyrex/hyrex';

const hy = new HyrexRegistry();

interface ProcessInput {
    file_path: string;
    options: Record<string, any>;
}

const processFile = hy.task({
    name: 'processFile',
    func: async (input: ProcessInput) => {
        // Task logic
        console.log(`Processing ${input.file_path}`);
        return { status: 'completed', file: input.file_path };
    }
});

Tasks can accept either zero arguments or one JSON-serializable argument. The return value must also be JSON-serializable or void.

Task Configuration

Configure task behavior with the config object:

const configuredTask = hy.task({
    name: 'configuredTask',
    config: {
        queue: 'processing',           // Target queue
        maxRetries: 3,                // Retry attempts (0-10, default: 3)
        timeoutSeconds: 300,          // Timeout in seconds
        priority: 5,                  // 1-10 (higher = more important, default: 3)
        cron: '0 * * * *',           // Optional cron schedule
        idempotencyKey: 'unique-key'  // Prevent duplicate executions
    },
    func: async (data: any) => {
        // Process with specific configuration
        return { processed: true };
    }
});

Configuration Options

queue: Route tasks to specific worker pools (default: “default”)
maxRetries: Number of retry attempts on failure (0-10, default: 3)
timeoutSeconds: Maximum execution time before timeout
priority: Task priority from 1-10 (default: 3)
cron: Cron expression for scheduled tasks
idempotencyKey: Unique key to prevent duplicate task executions

Sending Tasks

Queue tasks for asynchronous execution:

// Send with default configuration
const taskId = await processFile.send({
    file_path: '/data/input.csv',
    options: { format: 'csv' }
});

// Override configuration at runtime
const urgentTaskId = await processFile.withConfig({
    queue: 'high-priority',
    maxRetries: 5
}).send(input);

console.log(`Task ID: ${taskId}`);

Task Context

Access metadata about the current task execution:

import { getHyrexContext } from '@hyrex/hyrex';

const taskWithContext = hy.task({
    name: 'taskWithContext',
    func: async (data: any) => {
        // Get current task metadata
        const ctx = getHyrexContext();
        
        console.log(`Task ID: ${ctx.taskId}`);
        console.log(`Attempt: ${ctx.attemptNumber + 1}/${ctx.maxRetries + 1}`);
        console.log(`Queue: ${ctx.queue}`);
        console.log(`Parent ID: ${ctx.parentId}`);
        
        // Your task logic here
        return { processedBy: ctx.taskId };
    }
});

Context Properties

taskId: Unique identifier for the task
durableId: Persistent identifier for durable task storage
rootId: ID of the root task in the task tree
parentId: ID of the parent task (null if root)
workflowRunId: ID of the workflow run (if part of workflow)
taskName: Name of the task being executed
queue: Queue name where task is processed
priority: Task priority level
attemptNumber: Current attempt number (0-based)
maxRetries: Maximum retry attempts configured
timeoutSeconds: Timeout configuration
executorId: ID of the executor processing this task

Error Handling

Tasks can throw errors to trigger retries:

const taskWithRetries = hy.task({
    name: 'taskWithRetries',
    config: {
        maxRetries: 3
    },
    func: async (data: any) => {
        try {
            // Attempt operation
            const result = await externalApiCall(data);
            return result;
        } catch (error) {
            if (error instanceof TemporaryError) {
                // This will trigger a retry
                throw error;
            } else if (error instanceof PermanentError) {
                // This will not retry
                return { error: error.message, status: 'failed' };
            }
            throw error;
        }
    }
});

Retry Behavior

Throwing any exception triggers a retry (if retries remain)
Return a value to complete the task (even with errors)
Retries use exponential backoff by default

Input Validation

Use Zod schemas for type-safe input validation:

import { z } from 'zod';

const EmailSchema = z.object({
    to: z.string().email(),
    subject: z.string(),
    body: z.string()
});

const sendEmail = hy.task({
    name: 'sendEmail',
    argSchema: EmailSchema,
    func: async (input) => {
        // Input is automatically validated against schema
        // TypeScript knows input matches EmailSchema
        console.log(`Sending email to ${input.to}`);
        return { sent: true };
    }
});

// This will validate at runtime
await sendEmail.send({
    to: 'user@example.com',
    subject: 'Hello',
    body: 'Welcome!'
});

Task Results

The send() method returns a task ID immediately:

// Send a task
const taskId = await processFile.send(context);
console.log(`Task queued with ID: ${taskId}`);

// Note: The TypeScript SDK returns only the task ID
// Task status and results must be monitored through Hyrex Studio or logs

Best Practices

Use Type-Safe Interfaces

interface OrderContext {
    orderId: number;
    customerEmail: string;
    items: Array<{ sku: string; quantity: number }>;
}

const processOrder = hy.task({
    name: 'processOrder',
    func: async (context: OrderContext) => {
        // TypeScript ensures type safety
        return { orderId: context.orderId };
    }
});

Set Appropriate Timeouts

// Fast operations
config: { timeoutSeconds: 30 }

// Long-running jobs
config: { timeoutSeconds: 3600 }

Design for Idempotency

const processPayment = hy.task({
    name: 'processPayment',
    config: {
        idempotencyKey: 'payment-123'  // Prevents duplicate charges
    },
    func: async (context: PaymentContext) => {
        // Check if already processed
        const existing = await checkPaymentStatus(context.paymentId);
        if (existing) {
            return existing;
        }
        
        // Process payment
        const result = await chargeCard(context);
        await savePaymentResult(context.paymentId, result);
        return result;
    }
});

Handle Errors Gracefully

const fetchData = hy.task({
    name: 'fetchData',
    config: { maxRetries: 3 },
    func: async (context: FetchContext) => {
        try {
            return await fetchFromApi(context.url);
        } catch (error: any) {
            if (error.code === 'RATE_LIMIT') {
                // Retry with backoff
                throw error;
            } else if (error.code === 'INVALID_DATA') {
                // Don't retry, return error
                return { error: error.message, status: 'invalid_data' };
            }
            throw error;
        }
    }
});

Next Steps

Workflows

Orchestrate multiple tasks

Queues

Route tasks to worker pools

Retries

Configure retry strategies

Overview

SDK Reference

Examples

Production Guide

Basic Task Definition

Task Configuration

Configuration Options

Sending Tasks

Task Context

Context Properties

Error Handling

Retry Behavior

Input Validation

Task Results

Best Practices

Next Steps

Workflows

Queues

Retries

​Basic Task Definition

​Task Configuration

​Configuration Options

​Sending Tasks

​Task Context

​Context Properties

​Error Handling

​Retry Behavior

​Input Validation

​Task Results

​Best Practices

​Next Steps

Workflows

Queues

Retries

Basic Task Definition

Task Configuration

Configuration Options

Sending Tasks

Task Context

Context Properties

Error Handling

Retry Behavior

Input Validation

Task Results

Best Practices

Next Steps