API reference — slowdep

Exports

All exports

slowdep exports two functions and three types.

export	kind	description
withLatency	function	Wraps a single async function with lognormal latency and optional error injection.
withLatencyAll	function	Wraps every async method on an object with the same latency profile.
LatencyOptions	interface	The shape of a custom latency profile object ({ p50, p99, errorRate? }).
LatencyPreset	type	Union of all preset string literals.
LatencyProfile	type	Union of LatencyPreset and LatencyOptions — the type accepted by both functions.

Functions

withLatency

function withLatency<
  T extends (...args: any[]) => Promise<any>
>(
  fn: T,
  profile: LatencyProfile
): T

param	type	required	description
fn	(...args: any[]) => Promise<any>	yes	Async function to wrap. Must return a Promise.
profile	LatencyProfile	yes	Preset string name or custom options object.

Returns: T — same type as fn. Each call samples lognormal delay, optionally rejects (errorRate), then delegates to fn.

Functions

withLatencyAll

function withLatencyAll<T extends object>(
  client: T,
  profile: LatencyProfile
): T

param	type	required	description
client	object	yes	Any object. All methods returning a Promise are wrapped. Synchronous methods pass through.
profile	LatencyProfile	yes	Applied uniformly to all wrapped methods.

Returns: T — new object with same shape as client. this binding is preserved on all wrapped methods.

Types

LatencyOptions interface

interface LatencyOptions {
  p50: number         // median latency in ms (required)
  p99: number         // 99th-percentile latency in ms (required, must be > p50)
  errorRate?: number  // fraction of calls that reject [0, 1] (default: 0)
}

field	type	default	description
p50	number	—	Median latency in milliseconds. Half of sampled delays fall below this value.
p99	number	—	99th-percentile latency in milliseconds. Must be greater than p50. Used with p50 to parameterize the lognormal distribution.
errorRate	number	0	Fraction of calls that reject with `new Error('Simulated transient error')` before the underlying function is called. Range 0�1.

Types

LatencyPreset type

type LatencyPreset =
  | 'postgres'
  | 'mysql'
  | 'redis'
  | 'mongodb'
  | 'dynamodb'
  | 's3'
  | 'stripe'
  | 'openai'
  | 'anthropic'
  | 'http'

type LatencyProfile = LatencyPreset | LatencyOptions

Preset values

All preset values

postgres 5ms 50ms 200ms 0.001

mysql 4ms 40ms 180ms 0.001

redis 1ms 5ms 20ms 0.0005

mongodb 8ms 60ms 250ms 0.001

dynamodb 3ms 15ms 50ms 0.0005

s3 30ms 150ms 500ms 0.001

stripe 200ms 800ms 2000ms 0.002

openai 800ms 3000ms 8000ms 0.005

anthropic 600ms 2500ms 7000ms 0.005

http 80ms 300ms 1000ms 0.01

Math

Distribution formula

The lognormal distribution is parameterized from p50 and p99 as follows:

// Parameters derived from preset or LatencyOptions
mu    = ln(p50)
sigma = (ln(p99) - ln(p50)) / 2.326

// Box-Muller transform: two uniform ? standard normal z
u1    = Math.random()
u2    = Math.random()
z     = sqrt(-2 * ln(u1)) * cos(2 * Math.PI * u2)

// Lognormal sample (milliseconds)
delay = exp(mu + sigma * z)

// Cap at 3� p99 to bound the theoretical infinite tail
delay = min(delay, p99 * 3)

The constant 2.326 is the z-score of the 99th percentile of the standard normal distribution (invNorm(0.99) � 2.326).