Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/visible/cruel/llms.txt

Use this file to discover all available pages before exploring further.

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' }

Build docs developers (and LLMs) love

Get started for freeTalk to us