Introducing reixo - The TypeScript HTTP Client That Replaces axios

npm install reixo
# or
yarn add reixo
# or
pnpm add reixo

import { HTTPBuilder } from 'reixo'

const client = new HTTPBuilder()
  .withBaseURL('https://api.example.com')
  .withTimeout(10_000)
  .withHeader('Authorization', 'Bearer <token>')
  .build()

// Traditional throwing style
const response = await client.get<User[]>('/users')
console.log(response.data)  // User[]

// No-throw Result<T, E> style — the recommended approach
const result = await client.tryGet<User[]>('/users')
if (result.ok) {
  console.log(result.data.data)  // User[]
} else {
  console.error(result.error.status)  // HTTPError.status
}

// With axios — try/catch everywhere
try {
  const res = await axios.get('/users')
  return res.data
} catch (err) {
  if (axios.isAxiosError(err)) {
    console.error(err.response?.status)
  }
}

// With reixo — clean Result pattern
const result = await client.tryGet<User[]>('/users')
if (!result.ok) {
  console.error(result.error.status)  // Fully typed!
  return
}
return result.data.data

import {
  HTTPError,
  NetworkError,
  TimeoutError,
  AbortError,
  CircuitOpenError,
} from 'reixo'

try {
  await client.get('/api/data')
} catch (err) {
  if (err instanceof HTTPError) {
    console.error(`HTTP ${err.status}: ${err.statusText}`)
  } else if (err instanceof TimeoutError) {
    console.error(`Timed out after ${err.timeoutMs}ms`)
  } else if (err instanceof CircuitOpenError) {
    console.warn('Circuit breaker open — using fallback')
  } else if (err instanceof NetworkError) {
    console.error('Network failure:', err.message)
  }
}

const client = new HTTPBuilder()
  .withBaseURL('https://api.example.com')
  .withRetry({
    maxRetries: 3,
    initialDelayMs: 200,
    backoffFactor: 2,
    jitter: true,  // Spread concurrent retries
    retryCondition: (err) => {
      if (err instanceof NetworkError) return true
      if (err instanceof HTTPError) return err.status >= 500 || err.status === 429
      return false
    },
    onRetry: (err, attempt, delayMs) => {
      console.log(`Retry #${attempt} in ${delayMs}ms`)
    },
  })
  .build()

const client = new HTTPBuilder()
  .withCircuitBreaker({
    failureThreshold: 5,       // Open after 5 consecutive failures
    resetTimeoutMs: 30_000,    // Attempt recovery after 30s
    onStateChange: (prev, next) => {
      console.log(`Circuit: ${prev} → ${next}`)
    },
  })
  .build()

// When the breaker is OPEN, requests fail immediately with CircuitOpenError
// — without hitting the network

const client = new HTTPBuilder()
  .withBaseURL('https://api.example.com')
  .withDeduplication()
  .build()

// All 5 share one Promise — only 1 network request!
const [r1, r2, r3, r4, r5] = await Promise.all([
  client.get('/config'),
  client.get('/config'),
  client.get('/config'),
  client.get('/config'),
  client.get('/config'),
])

const client = new HTTPBuilder()
  .withOpenTelemetry({
    serviceName: 'checkout-service',
    baggage: { 'user.tier': 'premium' },
  })
  .build()

// Continuing an incoming trace (in Express/Next.js/Hono)
import { parseTraceparent } from 'reixo'

const parentCtx = parseTraceparent(req.headers['traceparent'])
const tracedClient = new HTTPBuilder()
  .withOpenTelemetry({ parentContext: parentCtx ?? undefined })
  .build()

const client = new HTTPBuilder()
  .withCache({
    ttl: 120_000,
    strategy: 'stale-while-revalidate',
    storage: 'memory',
    maxEntries: 200,
  })
  .build()

const res = await client.get('/config')
if (res.cacheMetadata?.hit) {
  console.log(`Cache hit — ${res.cacheMetadata.age}s old`)
}

import { createAuthInterceptor } from 'reixo'

// When multiple requests fail with 401 simultaneously,
// only ONE token refresh is triggered — the rest queue
const authInterceptor = createAuthInterceptor(client, {
  getAccessToken: () => localStorage.getItem('access_token'),
  refreshTokens: async () => {
    const res = await client.post('/auth/refresh', {
      refreshToken: localStorage.getItem('refresh_token'),
    })
    localStorage.setItem('access_token', res.data.accessToken)
    return res.data.accessToken
  },
  shouldRefresh: (err) => err instanceof HTTPError && err.status === 401,
})
client.addRequestInterceptor(authInterceptor)

const client = new HTTPBuilder()
  .withOfflineQueue({
    storage: 'localStorage',  // Persist across page reloads
    maxSize: 100,
  })
  .build()

// Requests queue while offline — drain automatically on reconnect
await client.post('/events', { type: 'click', timestamp: Date.now() })

client.on('queue:drain', () => console.log('All offline requests complete'))

import { WebSocketClient, SSEClient, GraphQLClient } from 'reixo'

// WebSocket with auto-reconnect
const ws = new WebSocketClient({
  url: 'wss://api.example.com/ws',
  reconnect: { maxRetries: 10, initialDelayMs: 1_000 },
  heartbeat: { interval: 30_000, message: 'ping' },
})

// Server-Sent Events
const sse = new SSEClient({
  url: 'https://api.example.com/stream',
  headers: { Authorization: 'Bearer token' },
})

// Type-safe GraphQL
const gql = new GraphQLClient('https://api.example.com/graphql')
const { data } = await gql.query<{ user: User }>({
  query: `query GetUser($id: ID!) { user(id: $id) { id name } }`,
  variables: { id: '1' },
})

// Before (axios)
import axios from 'axios'
const api = axios.create({ baseURL: 'https://api.example.com' })
const res = await api.get('/users')
res.data  // User[]

// After (reixo)
import { HTTPBuilder } from 'reixo'
const api = new HTTPBuilder().withBaseURL('https://api.example.com').build()
const res = await api.get<User[]>('/users')
res.data  // User[] — same shape!

import { MockAdapter, HTTPClient, HTTPError } from 'reixo'
import { describe, it, expect } from 'vitest'

const mock = new MockAdapter()
const client = new HTTPClient({ transport: mock.transport })

mock.onGet('/users').reply(200, [{ id: 1, name: 'Alice' }])
mock.onGet('/users/999').reply(404, { error: 'Not found' })

it('fetches users', async () => {
  const res = await client.get('/users')
  expect(res.status).toBe(200)
})

it('throws on 404', async () => {
  await expect(client.get('/users/999')).rejects.toBeInstanceOf(HTTPError)
})

npm install reixo