TypeScript Types

TypeScript types and interfaces for Cruel chaos testing

Cruel exports comprehensive TypeScript types for all configuration options and interfaces.

Core Options

ChaosOptions

Base chaos configuration options used throughout Cruel.

interface ChaosOptions {
  fail?: number
  delay?: number | [number, number]
  timeout?: number
  jitter?: number
  corrupt?: number
  spike?: number | [number, number]
  enabled?: boolean
}

fail · number

Probability (0-1) of random failures

delay · number | [number, number]

Fixed delay in ms or range [min, max] for random delay

timeout · number

Probability (0-1) of operations timing out (never completing)

jitter · number

Random jitter to add to delays (0 to jitter ms)

corrupt · number

Probability (0-1) of corrupting string responses

spike · number | [number, number]

Additional delay spike in ms or range [min, max]

enabled · boolean

Whether chaos is enabled (allows conditional chaos)

Network Options

NetworkOptions

Extends ChaosOptions with network-specific chaos.

interface NetworkOptions extends ChaosOptions {
  latency?: number | [number, number]
  packetLoss?: number
  bandwidth?: number
  disconnect?: number
  dns?: number
}

latency · number | [number, number]

Network latency in ms or range

packetLoss · number

Probability (0-1) of packet loss

bandwidth · number

Simulated bandwidth limit in kbps

disconnect · number

Probability (0-1) of connection disconnect

dns · number

Probability (0-1) of DNS failures

HttpOptions

Extends ChaosOptions with HTTP-specific chaos.

interface HttpOptions extends ChaosOptions {
  status?: number | number[]
  rateLimit?: number | { rate: number; status?: number; retryAfter?: number }
  slowBody?: number | [number, number]
  truncate?: number
  malformed?: number
  headers?: Record<string, string>
}

status · number | number[]

HTTP status code(s) to return

rateLimit · number | object

Rate limit probability or configuration object with rate, status, and retryAfter

slowBody · number | [number, number]

Delay for response body in ms or range

truncate · number

Probability (0-1) of truncating response body

malformed · number

Probability (0-1) of returning malformed response

headers · Record<string, string>

Custom headers to inject

StreamOptions

Extends ChaosOptions with streaming-specific chaos.

interface StreamOptions extends ChaosOptions {
  cut?: number
  pause?: number | [number, number]
  reorder?: number
  duplicate?: number
  dropChunks?: number
  corruptChunks?: number
}

cut · number

Probability (0-1) of cutting stream mid-transfer

pause · number | [number, number]

Pause duration in ms or range

reorder · number

Probability (0-1) of reordering chunks

duplicate · number

Probability (0-1) of duplicating chunks

dropChunks · number

Probability (0-1) of dropping chunks

corruptChunks · number

Probability (0-1) of corrupting chunks

AI SDK Options

AIOptions

Extends ChaosOptions with AI-specific chaos for language models.

interface AIOptions extends ChaosOptions {
  rateLimit?: number | { rate: number; retryAfter?: number }
  overloaded?: number
  contextLength?: number
  contentFilter?: number
  modelUnavailable?: number
  tokenLimit?: number
  streamCut?: number
  slowTokens?: number | [number, number]
  partialResponse?: number
  invalidJson?: number
}

rateLimit · number | object

Rate limit probability or configuration with rate and retryAfter

overloaded · number

Probability (0-1) of model being overloaded

contextLength · number

Probability (0-1) of context length errors

contentFilter · number

Probability (0-1) of content filter triggering

modelUnavailable · number

Probability (0-1) of model being unavailable

tokenLimit · number

Token limit for responses

streamCut · number

Probability (0-1) of cutting token streams

slowTokens · number | [number, number]

Delay per token in ms or range

partialResponse · number

Probability (0-1) of returning partial responses

invalidJson · number

Probability (0-1) of returning invalid JSON

CruelModelOptions

Options for cruelModel() function.

type CruelModelOptions = CruelChaosOptions

interface CruelChaosOptions {
  onChaos?: (event: ChaosEvent) => void
  fail?: number
  delay?: number | [number, number]
  timeout?: number
  rateLimit?: number | { rate: number; retryAfter?: number }
  overloaded?: number
  contextLength?: number
  contentFilter?: number
  modelUnavailable?: number
  invalidApiKey?: number
  quotaExceeded?: number
  streamCut?: number
  slowTokens?: number | [number, number]
  partialResponse?: number
  corruptChunks?: number
  toolFailure?: number
  toolTimeout?: number
  emptyResponse?: number
  finishReason?: LanguageModelV3UnifiedFinishReason
  tokenUsage?: { inputTokens?: number; outputTokens?: number }
}

onChaos · (event: ChaosEvent) => void

Callback function invoked when chaos events occur

toolFailure · number

Probability (0-1) of tool execution failures

toolTimeout · number

Probability (0-1) of tool execution timeouts

finishReason · LanguageModelV3UnifiedFinishReason

Override finish reason in responses

tokenUsage · object

Override token usage counts with inputTokens and outputTokens

CruelProviderOptions

Options for cruelProvider() function.

interface CruelProviderOptions extends CruelChaosOptions {
  models?: Record<string, CruelChaosOptions>
}

models · Record<string, CruelChaosOptions>

Model-specific chaos configuration, keyed by model ID

CruelMiddlewareOptions

Options for cruelMiddleware() function.

type CruelMiddlewareOptions = CruelChaosOptions

Resilience Patterns

CircuitBreakerOptions

Configuration for circuit breaker pattern.

interface CircuitBreakerOptions {
  threshold: number
  timeout: number
  onOpen?: () => void
  onClose?: () => void
  onHalfOpen?: () => void
}

threshold · number · required

Number of failures before opening circuit

timeout · number · required

Time in ms before attempting to close circuit

onOpen · () => void

Callback when circuit opens

onClose · () => void

Callback when circuit closes

onHalfOpen · () => void

Callback when circuit enters half-open state

RetryOptions

Configuration for retry pattern.

interface RetryOptions {
  attempts: number
  delay?: number | [number, number]
  backoff?: 'fixed' | 'linear' | 'exponential'
  maxDelay?: number
  onRetry?: (attempt: number, error: Error) => void
  retryIf?: (error: Error) => boolean
}

attempts · number · required

Maximum number of retry attempts

delay · number | [number, number]

Delay between retries in ms or range

backoff · 'fixed' | 'linear' | 'exponential'

Backoff strategy for retry delays

maxDelay · number

Maximum delay in ms (caps backoff)

onRetry · (attempt: number, error: Error) => void

Callback invoked before each retry

retryIf · (error: Error) => boolean

Predicate to determine if error should trigger retry

BulkheadOptions

Configuration for bulkhead pattern (concurrency limiting).

interface BulkheadOptions {
  maxConcurrent: number
  maxQueue?: number
  onReject?: () => void
}

maxConcurrent · number · required

Maximum number of concurrent executions

maxQueue · number

Maximum queue size for waiting requests

onReject · () => void

Callback when request is rejected due to full queue

TimeoutOptions

Configuration for timeout pattern.

interface TimeoutOptions {
  ms: number
  onTimeout?: () => void
}

ms · number · required

Timeout duration in milliseconds

onTimeout · () => void

Callback invoked when timeout occurs

FallbackOptions

Configuration for fallback pattern.

interface FallbackOptions<T> {
  fallback: T | (() => T | Promise<T>)
  onFallback?: (error: Error) => void
}

fallback · T | (() => T | Promise<T>) · required

Fallback value or function to provide value on error

onFallback · (error: Error) => void

Callback invoked when fallback is used

HedgeOptions

Configuration for hedge (parallel request) pattern.

interface HedgeOptions {
  count: number
  delay: number
}

count · number · required

Number of parallel requests to make

delay · number · required

Delay in ms between launching each request

RateLimiterOptions

Configuration for rate limiter.

interface RateLimiterOptions {
  requests: number
  interval: number
  onLimit?: () => void
}

requests · number · required

Number of requests allowed per interval

interval · number · required

Time interval in milliseconds

onLimit · () => void

Callback when rate limit is exceeded

CacheOptions

Configuration for caching wrapper.

interface CacheOptions<T> {
  ttl: number
  key?: (...args: unknown[]) => string
  onHit?: (key: string) => void
  onMiss?: (key: string) => void
}

ttl · number · required

Time-to-live for cache entries in milliseconds

key · (...args: unknown[]) => string

Custom key generation function (defaults to JSON.stringify of args)

onHit · (key: string) => void

Callback on cache hit

onMiss · (key: string) => void

Callback on cache miss

Configuration & State

CruelConfig

Global configuration for Cruel.

interface CruelConfig {
  enabled: boolean
  seed?: number
  log?: boolean
  safe?: boolean
}

enabled · boolean · required

Whether Cruel is globally enabled

seed · number

Random seed for deterministic behavior

log · boolean

Enable logging of chaos events

safe · boolean

Safe mode (reduces chaos intensity)

Stats

Statistics tracking interface.

interface Stats {
  calls: number
  failures: number
  timeouts: number
  delays: number
  corrupted: number
  rateLimited: number
  streamsCut: number
  latencies: number[]
  byTarget: Map<string, { calls: number; failures: number; latencies: number[] }>
}

ScenarioConfig

Configuration for chaos scenarios.

interface ScenarioConfig {
  name: string
  duration?: number
  chaos?: ChaosOptions
}

name · string · required

Scenario name

duration · number

Scenario duration in milliseconds

chaos · ChaosOptions

Chaos configuration for scenario

Events

ChaosEvent

Union type of all possible chaos events.

type ChaosEvent =
  | { type: 'rateLimit'; modelId: string }
  | { type: 'overloaded'; modelId: string }
  | { type: 'contextLength'; modelId: string }
  | { type: 'contentFilter'; modelId: string }
  | { type: 'modelUnavailable'; modelId: string }
  | { type: 'invalidApiKey'; modelId: string }
  | { type: 'quotaExceeded'; modelId: string }
  | { type: 'emptyResponse'; modelId: string }
  | { type: 'fail'; modelId: string }
  | { type: 'timeout'; modelId: string }
  | { type: 'delay'; modelId: string; ms: number }
  | { type: 'streamCut'; modelId: string }
  | { type: 'slowTokens'; modelId: string; ms: number }
  | { type: 'corruptChunk'; modelId: string }
  | { type: 'partialResponse'; modelId: string }
  | { type: 'toolFailure' }
  | { type: 'toolTimeout' }