---
title: Worker
description: Worker protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Worker System Protocol

Background task processing system with queues, priorities, and retry logic.

Provides a robust foundation for async task execution similar to:

- Sidekiq (Ruby)

- Celery (Python)

- Bull/BullMQ (Node.js)

- AWS SQS/Lambda

Features:

- Task queues with priorities

- Task scheduling and retry logic

- Batch processing

- Dead letter queues

- Task monitoring and logging

@example Basic task

```typescript

const task: Task = \{

id: 'task-123',

type: 'send_email',

payload: \{ to: 'user@example.com', subject: 'Welcome' \},

queue: 'notifications',

priority: 5

\};

```

<Callout type="info">
**Source:** `packages/spec/src/system/worker.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { BatchProgress, QueueConfig, Task, TaskExecutionResult, TaskPriority, TaskRetryPolicy, TaskStatus, WorkerStats } from '@objectstack/spec/system';
import type { BatchProgress, QueueConfig, Task, TaskExecutionResult, TaskPriority, TaskRetryPolicy, TaskStatus, WorkerStats } from '@objectstack/spec/system';

// Validate data
const result = BatchProgress.parse(data);
```

---

## BatchProgress

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **batchId** | `string` | ✅ | Batch job identifier |
| **total** | `integer` | ✅ | Total number of items |
| **processed** | `integer` | ✅ | Items processed |
| **succeeded** | `integer` | ✅ | Items succeeded |
| **failed** | `integer` | ✅ | Items failed |
| **percentage** | `number` | ✅ | Progress percentage |
| **status** | `Enum<'pending' \| 'running' \| 'completed' \| 'failed' \| 'cancelled'>` | ✅ | Batch status |
| **startedAt** | `string` | optional | When batch started |
| **completedAt** | `string` | optional | When batch completed |


---

## QueueConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Queue name (snake_case) |
| **concurrency** | `integer` | ✅ | Max concurrent task executions |
| **rateLimit** | `Object` | optional | Rate limit configuration |
| **defaultRetryPolicy** | `Object` | optional | Default retry policy for tasks |
| **deadLetterQueue** | `string` | optional | Dead letter queue name |
| **priority** | `integer` | ✅ | Queue priority (lower = higher priority) |
| **autoScale** | `Object` | optional | Auto-scaling configuration |


---

## Task

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Unique task identifier |
| **type** | `string` | ✅ | Task type (snake_case) |
| **payload** | `any` | ✅ | Task payload data |
| **queue** | `string` | ✅ | Queue name |
| **priority** | `Enum<'critical' \| 'high' \| 'normal' \| 'low' \| 'background'>` | ✅ | Task priority level |
| **retryPolicy** | `Object` | optional | Retry policy configuration |
| **timeoutMs** | `integer` | optional | Task timeout in milliseconds |
| **scheduledAt** | `string` | optional | ISO 8601 datetime to execute task |
| **attempts** | `integer` | ✅ | Number of execution attempts |
| **status** | `Enum<'pending' \| 'queued' \| 'processing' \| 'completed' \| 'failed' \| 'cancelled' \| 'timeout' \| 'dead'>` | ✅ | Current task status |
| **metadata** | `Object` | optional | Task metadata |


---

## TaskExecutionResult

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **taskId** | `string` | ✅ | Task identifier |
| **status** | `Enum<'pending' \| 'queued' \| 'processing' \| 'completed' \| 'failed' \| 'cancelled' \| 'timeout' \| 'dead'>` | ✅ | Execution status |
| **result** | `any` | optional | Execution result data |
| **error** | `Object` | optional | Error details if failed |
| **durationMs** | `integer` | optional | Execution duration in milliseconds |
| **startedAt** | `string` | ✅ | When execution started |
| **completedAt** | `string` | optional | When execution completed |
| **attempt** | `integer` | ✅ | Attempt number (1-indexed) |
| **willRetry** | `boolean` | ✅ | Whether task will be retried |


---

## TaskPriority

### Allowed Values

* `critical`
* `high`
* `normal`
* `low`
* `background`


---

## TaskRetryPolicy

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **maxRetries** | `integer` | ✅ | Maximum retry attempts |
| **backoffStrategy** | `Enum<'fixed' \| 'linear' \| 'exponential'>` | ✅ | Backoff strategy between retries |
| **initialDelayMs** | `integer` | ✅ | Initial retry delay in milliseconds |
| **maxDelayMs** | `integer` | ✅ | Maximum retry delay in milliseconds |
| **backoffMultiplier** | `number` | ✅ | Multiplier for exponential backoff |


---

## TaskStatus

### Allowed Values

* `pending`
* `queued`
* `processing`
* `completed`
* `failed`
* `cancelled`
* `timeout`
* `dead`


---

## WorkerStats

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **workerName** | `string` | ✅ | Worker name |
| **totalProcessed** | `integer` | ✅ | Total tasks processed |
| **succeeded** | `integer` | ✅ | Successful tasks |
| **failed** | `integer` | ✅ | Failed tasks |
| **active** | `integer` | ✅ | Currently active tasks |
| **avgExecutionMs** | `number` | optional | Average execution time in milliseconds |
| **uptimeMs** | `integer` | ✅ | Worker uptime in milliseconds |
| **queues** | `Record<string, Object>` | optional | Per-queue statistics |


---

