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.

This guide will help you inject your first chaos and start testing your application’s resilience.
1

Install Cruel

Install Cruel using your package manager:
npm install cruel
2

Inject basic chaos

Wrap any async function with cruel() to inject failures, delays, and timeouts:
import { cruel } from "cruel"

// Wrap your API function
const api = cruel(fetch, {
  fail: 0.1,          // 10% of calls will fail
  delay: [100, 500],  // Add 100-500ms random delay
  timeout: 0.05,      // 5% of calls will timeout
})

// Use it like the original function
const res = await api("https://api.example.com")
The cruel() function returns a wrapped version that behaves identically to the original, but with chaos injected based on your configuration.
3

Use shorthand helpers

Cruel provides convenient shortcuts for common chaos patterns:
import { cruel } from "cruel"

// 10% failure rate
const failingApi = cruel.fail(fetch, 0.1)

// Add 500ms delay to every call
const slowApi = cruel.slow(fetch, 500)

// Random delays between 200-1000ms
const laggyApi = cruel.slow(fetch, [200, 1000])

// 10% of calls never resolve
const timeoutApi = cruel.timeout(fetch, 0.1)

// Random chaos (failures, timeouts, delays)
const flakyApi = cruel.flaky(fetch)

// Extreme chaos
const nightmareApi = cruel.nightmare(fetch)
These helpers make it easy to test specific failure modes without writing full configuration objects.
4

Test resilience patterns

Combine chaos with resilience patterns like circuit breakers and retries:
import { cruel } from "cruel"

// Simulate a flaky API
let attempts = 0
const flakyTask = async () => {
  attempts++
  if (attempts < 3) throw new Error("Service temporarily unavailable")
  return { success: true, attempts }
}

// Add resilience with retry and circuit breaker
const resilientApi = cruel.compose(flakyTask, {
  retry: {
    attempts: 4,
    delay: 100,
    backoff: "exponential",  // 100ms, 200ms, 400ms
  },
  circuitBreaker: {
    threshold: 5,    // Open circuit after 5 failures
    timeout: 30000,  // Try again after 30 seconds
  },
  fallback: { success: false, cached: true },
})

const result = await resilientApi()
console.log(result) // { success: true, attempts: 3 }
The cruel.compose() function lets you combine chaos with multiple resilience patterns in a single wrapper.
5

Explore specialized chaos

Cruel provides domain-specific chaos for network, HTTP, streams, and AI:
import { cruel } from "cruel"

// Network chaos
const unstableNetwork = cruel.network.packetLoss(fetch, 0.1)
const slowNetwork = cruel.network.latency(fetch, [100, 500])
const offlineNetwork = cruel.network.offline(fetch)

// HTTP chaos
const serverErrors = cruel.http.serverError(fetch, 0.1)
const rateLimited = cruel.http.rateLimit(fetch, 0.05)
const badGateway = cruel.http.badGateway(fetch, 0.1)

// Stream chaos (for streaming responses)
const cutStreams = cruel.stream.cut(streamFn, 0.1)
const corruptStreams = cruel.stream.corrupt(streamFn, 0.05)

// AI-specific chaos (rate limits, context length, etc.)
const aiChaos = cruel.ai.realistic(generateText)
const aiNightmare = cruel.ai.nightmare(generateText)
Each namespace provides functions tailored to specific failure modes you’ll encounter in production.

​
Next steps

Now that you’ve injected your first chaos, you can:

Build docs developers (and LLMs) love

Get started for freeTalk to us