# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build & Test Commands

- **Run all tests**: `npm test` (runs lint, unit tests, and security audit)
- **Lint only**: `npm run test:lint`
- **Unit tests only**: `npm run test:unit`
- **Run single test file**: `NODE_ENV=test NODE_PATH=. npx mocha -r test/setup.js test/<filename>.js`
- **Build**: `npm run build` (transpiles src/ to lib/ via Babel)

## Architecture

This is a queue abstraction library that wraps different queue backends. Currently only AWS SQS is implemented.

### Core Classes

- **Queue** (`src/queue.js`): Abstract base class defining the public API. Implementations extend this class and override internal methods (`_fetch`, `_transform`, `_delete`, `_touch`, `_send`, `_connect`, `_lock`, `_unlock`).

- **SQSQueue** (`src/sqs.js`): AWS SQS implementation. Uses batch operations for delete/send/touch to optimize API calls. The SQS client is configured with timeouts based on `SQS_FETCH_WAIT`.

- **QueuePool** (`src/pool.js`): Distributes work across multiple queues with weighted load balancing. Uses MurmurHash for consistent bucket assignment when sending messages.

- **QueueItem** (`src/item.js`): Represents a workflow-based queue item with multi-level job scheduling. Jobs can be organized into workflow levels that execute in order.

### Key Utilities

- **BatchOperation** (`src/batch-operation.js`): Batches operations up to a size limit or timeout, whichever comes first. Used by SQS for efficient batch API calls.

- **ItemPool** (`src/item-pool.js`): Concurrency limiter that tracks how many items are "in flight" to prevent overload.

### Event System

Queues emit `message` events for incoming items and `error` events for failures. The base Queue class attaches a default error handler that throws unhandled errors via setTimeout.

## Environment Variables

- `BATCH_SIZE`: Items per fetch batch (default: 10)
- `QUEUE_POOL_SIZE`: Max concurrent items in flight (default: 20)
- `SQS_AWS_REGION`: AWS region (falls back to `AWS_REGION`)
- `SQS_FETCH_WAIT`: Long poll wait time in seconds (default: 20)