Basic Chaos API

Core chaos testing methods for injecting failures, delays, and timeouts

cruel()

Wraps a function with chaos behavior.

function cruel<T extends AnyFn>(fn: T, options: ChaosOptions = {}): T

fn · T extends AnyFn · required

The function to wrap with chaos behavior

options · ChaosOptions

Chaos configuration options

Show properties

fail · number

Probability of failure (0-1)

delay · number | [number, number]

Delay in milliseconds or range [min, max]

timeout · number

Probability of timeout (0-1)

jitter · number

Random jitter in milliseconds (0 to jitter)

corrupt · number

Probability of data corruption (0-1)

spike · number | [number, number]

Latency spike in milliseconds or range

enabled · boolean

Whether chaos is enabled for this function

Returns: T - Wrapped function with chaos behavior

Example

import { cruel } from '@cruel/cruel'

const fetchUser = cruel(async (id: string) => {
  return db.users.findById(id)
}, { fail: 0.1, delay: [100, 500] })

---

cruel.fail()

Wraps a function to fail at a specific rate.

function fail<T extends AnyFn>(fn: T, rate = 0.1): T

fn · T extends AnyFn · required

The function to wrap

rate · number · default: "0.1"

Failure rate (0-1). Default is 0.1 (10%)

Returns: T - Function that fails randomly at the specified rate

Example

import { cruel } from '@cruel/cruel'

const unreliableApi = cruel.fail(async () => {
  return fetch('/api/data')
}, 0.2) // Fails 20% of the time

---

cruel.slow()

Wraps a function to add artificial delay.

function slow<T extends AnyFn>(fn: T, delay: number | [number, number] = 500): T

fn · T extends AnyFn · required

The function to wrap

delay · number | [number, number] · default: "500"

Delay in milliseconds, or range [min, max] for random delay

Returns: T - Function with added delay

Example

import { cruel } from '@cruel/cruel'

const slowQuery = cruel.slow(async (query: string) => {
  return db.execute(query)
}, [1000, 3000]) // Random delay between 1-3 seconds

---

cruel.timeout()

Wraps a function to timeout at a specific rate.

function timeout<T extends AnyFn>(fn: T, rate = 0.1): T

fn · T extends AnyFn · required

The function to wrap

rate · number · default: "0.1"

Timeout rate (0-1). Default is 0.1 (10%)

Returns: T - Function that times out randomly at the specified rate

Example

import { cruel } from '@cruel/cruel'

const timeoutProne = cruel.timeout(async () => {
  return longRunningOperation()
}, 0.15) // Times out 15% of the time

---

cruel.flaky()

Wraps a function with flaky behavior (combination of failures, timeouts, and delays).

function flaky<T extends AnyFn>(fn: T, intensity = 0.2): T

fn · T extends AnyFn · required

The function to wrap

intensity · number · default: "0.2"

Flakiness intensity (0-1). Higher values mean more chaos

Returns: T - Flaky function with combined chaos behaviors

Behavior: Applies chaos with:

• fail: intensity * 0.5
• timeout: intensity * 0.25
• delay: [100, 1000]

Example

import { cruel } from '@cruel/cruel'

const flakyService = cruel.flaky(async () => {
  return externalAPI.getData()
}, 0.3) // 30% intensity

---

cruel.unreliable()

Wraps a function with high unreliability (failures, timeouts, delays, jitter).

function unreliable<T extends AnyFn>(fn: T): T

fn · T extends AnyFn · required

The function to wrap

Returns: T - Highly unreliable function

Behavior: Applies chaos with:

• fail: 0.3
• timeout: 0.1
• delay: [200, 2000]
• jitter: 500

Example

import { cruel } from '@cruel/cruel'

const unreliableDB = cruel.unreliable(async (query: string) => {
  return database.query(query)
})

---

cruel.nightmare()

Wraps a function with extreme chaos for stress testing.

function nightmare<T extends AnyFn>(fn: T): T

fn · T extends AnyFn · required

The function to wrap

Returns: T - Function with extreme chaos behavior

Behavior: Applies chaos with:

• fail: 0.5
• timeout: 0.2
• delay: [500, 5000]
• jitter: 1000

Example

import { cruel } from '@cruel/cruel'

const worstCase = cruel.nightmare(async () => {
  return criticalOperation()
})