Observability Hooks

Observability hooks fire as side-effects — they don’t change the return value. Configure them instance-wide or per-call.

onError

Fires once with the resolved error just before it’s thrown (and before recover):

const expectStatus = createExpectStatus({
  onError: (err, response) => {
    Sentry.captureException(err, {
      extra: { status: response.status, body: response.body },
    })
  },
})

onSuccess

Fires once when the status matches the expected status:

const expectStatus = createExpectStatus({
  onSuccess: (response) => {
    analytics.track('api_success', { status: response.status })
  },
})

Per-call override

Per-call hooks shadow instance hooks:

await expectStatus(200, response, {
  onError: (err, res) => console.error('Custom error handler', err),
  onSuccess: (res) => console.log('Custom success handler', res.status),
})

Error swallowing

Errors thrown inside hooks are swallowed to avoid breaking your application:

const expectStatus = createExpectStatus({
  onError: () => {
    throw new Error('Logging failed')  // swallowed — does not propagate
  },
})

vs recover / transform

Hook	Purpose	Affects return value?
onError	Observe errors (logging, metrics)	No
onSuccess	Observe successes (analytics)	No
recover	Catch errors, return fallback	Yes
transform	Reshape success body	Yes

Use hooks for side-effects. Use recover/transform when you need to change the return value.

Next steps

• Create Instance — full instance configuration
• Recover & Transform — return-value hooks