torc-api/README.md

torc-api is a lightweight wrapper to simplify HTTP requests

# 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

```bash
npm install torc-api
```

---


## 📦 Basic Example

### Fetch data with automatic JSON formatting

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

```ts
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:

```ts
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 |

---