torc-api

torc-api is a lightweight wrapper to simplify HTTP requests, similar to axios, but with a more explicit and strongly-typed approach. It includes two main classes: API for handling HTTP requests, and Data for structuring responses or payloads.

🚀 Installation

npm install torc-api

📦 Basic Example

Fetch data with automatic JSON formatting

This is equivalent to calling response.json() manually:

import { API, Data } from 'torc-api'

const pokeApi = new API({
  url: 'https://pokeapi.co/api/v2/pokemon'
})

async function fetchPokemon(pokemonName: string): Promise<Data<string>> {
  const data = await pokeApi.get<string>({
    endpoint: pokemonName,
    formatToJSON: true
  })

  return data
}

fetchPokemon('ditto').then(data => console.log('data:', data))

Get the raw Response object

If you set formatToJSON to false (which is the default), you'll receive the raw Response instead of a Data object:

async function fetchPokemon(pokemonName: string): Promise<Response> {
  const response = await pokeApi.get({
    endpoint: pokemonName,
    formatToJSON: false
  })

  return response
}

🔧 API: Configuration

When creating an API instance, you can provide:

| Property | Type | Required | Description | | -------- | ------------ | -------- | -------------------------------- | | url | string | ✅ | Base URL for all requests | | headers | HeadersInit| ❌ | Default headers for all requests (can be overridden per call) | | options | APIOptions | ❌ | Default options for all requests |

📄 APIOptions

APIOptions extends the native RequestInit object and adds:

| Property | Type | Default | Description | | ------------ | -------- | ------- | ----------------------------------------- | | formatToJSON | boolean| false | Whether to automatically call .json() on the response | | abortSeconds | number | 20 | Time (in seconds) before the request is automatically aborted |

📦 Data

The Data<T> class wraps a response value and potential error in a unified structure:

Properties

| Property | Type | Description | | -------- | -------------- | ------------------- | | value | DataValue<T> | The response data | | error | DataError | The error (if any) |

Static Methods

| Method | Returns | Description | | -----------------------------| ------------ | ------------------------------------- | | Data.failure(error: DataError) | Data<null> | Creates a Data instance with a given error | | Data.success<T>(value: T) | Data<T> | Creates a Data instance with a given value |