Hooks

Drop-in replacements for React hooks with chaos injection.

Every hook accepts an optional options object as its last argument. All options extend HookMetadata:

Field	Type	Description
`name`	`string`	Identifier for targeting and logging
`component`	`string`	Enclosing component name
`probability`	`number`	Override the default probability (0–1)
`failures`	`string[]`	Allowed failure modes for this hook

useVolatileState

const [state, setState] = useVolatileState(initialState, options?)

Wraps useState. Chaos is injected when the setter is called.

Failure	Behavior
`delay`	State update is applied after a random delay
`error`	Throws a `VolatileError`
`corrupt`	Applies a corrupted value instead of the real one

Custom Corruptor

const [name, setName] = useVolatileState('hello', {
  failures: ['corrupt'],
  corruptor: (value) => value.toUpperCase() + '!!',
});

useVolatileEffect

useVolatileEffect(effect, deps, options?)

Wraps useEffect. Chaos is injected when the effect runs.

Failure	Behavior
`delay`	Effect execution is delayed
`error`	Throws a `VolatileError`
`skip`	Effect is skipped entirely

useVolatileEffect(() => {
  fetchData();
  return () => cleanup();
}, [id], {
  name: 'fetchData',
  component: 'UserProfile',
  failures: ['delay', 'skip'],
});

useVolatileLayoutEffect works identically but wraps useLayoutEffect.

useVolatileReducer

const [state, dispatch] = useVolatileReducer(reducer, initialState, options?)

Wraps useReducer. Chaos is injected when dispatch is called.

Failure	Behavior
`delay`	Dispatch is applied after a random delay
`error`	Throws a `VolatileError`

useVolatileMemo

const value = useVolatileMemo(factory, deps, options?)

Wraps useMemo. Chaos is injected during memoization.

Failure	Behavior
`error`	Throws a `VolatileError`

useVolatileCallback

const fn = useVolatileCallback(callback, deps, options?)

Wraps useCallback. Chaos is injected when the returned function is called.

Failure	Behavior
`error`	Throws a `VolatileError`
`delay`	Callback returns a Promise that resolves after a delay
`noop`	Callback does nothing, returns `undefined`

useVolatileAsync

const { data, error, loading, execute } = useVolatileAsync(asyncFn, options?)

Wraps an async function with loading/error state management and chaos injection.

Failure	Behavior
`delay`	Adds a random delay before executing
`reject`	Rejects with a `VolatileError`
`timeout`	Waits 3x the delay range then rejects

const { data, error, loading, execute } = useVolatileAsync(
  () => fetch('/api/users').then(r => r.json()),
  { name: 'fetchUsers', failures: ['delay', 'reject'] },
);

// call execute() to run the async function
<button onClick={() => execute()}>Load</button>

useChaosTrigger

const { trigger, isActive, engine } = useChaosTrigger()

Manual control hook. Does not wrap any React hook — use it to emit chaos events programmatically.

trigger({
  type: 'state',
  failure: 'error',
  target: 'manualTest',
  component: 'DebugPanel',
});