Skip to content
/ typed-fetcher Public

Typed-fetcher is a npm package for typed HTTP requests.

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

legusha/typed-fetcher

BranchesTags

Repository files navigation

Typed-fetcher

npm badge

Typed-fetcher is a scalable and flexible package for typed HTTP requests.

Description

Typed-fetcher is a lightweight, dependency-free TypeScript package for making fully typed HTTP requests. It enables you to define request and response types, ensuring type safety throughout your API calls. With built-in error handling that eliminates the need for try/catch, flexible support for custom HTTP providers (like fetch or XMLHttpRequest), and easy integration with both npm and yarn, Typed-fetcher streamlines HTTP communication in modern TypeScript and JavaScript projects. Its customizable error management and provider system make it suitable for a wide range of use cases, from simple REST APIs to complex, enterprise-grade applications.

Features

  • Typed requests
  • Typed responses
  • Error handling
  • No need try/catch
  • No need for JSON.stringify/parse for body
  • No dependencies
  • Custom fetch providers (if needed)
  • Custom error handling (if needed)
  • Retry request with convenient configuration
  • Retry request with Circuit Breaker and convenient configuration

Supports the following HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

Installation

npm

  npm i typed-fetcher

yarn

  yarn add typed-fetcher

ES Modules

import { httpClient } from 'typed-fetcher';

const { data, error } = await httpClient.get<SomeInterface>('https://example.com');

CommonJS

const { httpClient } = require('typed-fetcher')

const { data, error } = await httpClient.get<SomeInterface>('https://example.com');

HTML script

<script src="https://cdn.jsdelivr.net/npm/typed-fetcher@1.0.14/dist/index.umd.js"></script>
<script>
    const { httpClient } = window.typedFetcher
    
    const { data, error } = await httpClient.get<SomeInterface>('https://example.com');
</script>
})()

Usage

Response data

Pass an interface to the request, and it will be returned as a response in data property

import { httpClient } from 'typed-fetcher';

// For example:
interface SomeInterface {
  id: number;
  name: string;
}

const { data, error } = await httpClient.get<SomeInterface>('https://some-api.com/some-endpoint');

If we have success response we will get the following structure:

{
  data: SomeInterface;
  error: null;
}

If we have error response we will get the following structure:

{
  data: null
  error: HttpErrorBase;
}

Error has the following structure:

interface HttpErrorBase {
  type: 'JSON' | 'ARRAY_BUFFER';
  status: number;
  message: string;
  details: null | unknown | ArrayBuffer;
}

Origin field is a reference to the response object, if you are need to get reference on response object you can use fetchGet, fetchPost and etc property whose name starts with fetch:

const { data, error, origin } = await httpClient.fetchGet<SomeInterface>('https://some-api.com/some-endpoint');

Apply options for every request; the body and method will ignored because it is not needed.

const exampleToken = ''
const options = {
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${exampleToken}`,
  },
} as const

// And then this options will be applied for every request
httpClient.applyOptions(options)

Unapply options for every request

httpClient.unapplyOptions()

Rewrite options for concrete request. You can rewrite options for some request, it applies only for this request once. The body will be converted to JSON automatically if responseAs setting is json and method will be ignored because it is not needed.

const optionsForConcreteRequest = {
  credentials: 'omit',
} as const

const { data, error } = await httpClient
  .get<SomeInterface>('https://some-api.com/some-endpoint', optionsForConcreteRequest);

Apply settings for every request

const settings = {
  responseAs: 'json' | 'text' | 'arrayBuffer',
  baseUrl: 'https://example.com' // it will added to every url
}

// And then this settings will be applied for every request
httpClient.applySettings(options)

Unapply settings for every request

httpClient.unapplySettings()

Rewrite settings for concrete request. You can rewrite settings for some request, it applies only for this request once.

const settingsForConcreteRequest = {
  responseAs: 'text',
  baseUrl: 'https://some-api.com'
}
const { data, error } = await httpClient
  .get<SomeInterface>('/some-endpoint', {}, settingsForConcreteRequest);

Unsafe requests

If you prefer to work with try/catch blocks or expect successful responses and want to access data directly, you can use the *Unsafe methods. These methods return the data directly (type Data) instead of the { data, error } object.

Note: If the request fails (non-2xx status or network error), these methods will throw an error. You must wrap these calls in a try/catch block to handle failures.

Supported methods: getUnsafe, postUnsafe, putUnsafe, patchUnsafe, deleteUnsafe, headUnsafe, optionsUnsafe.

try {
  // GET: Returns Data directly
  const user = await httpClient.getUnsafe<User>('/user/1');
  console.log(user.name);

  // POST: Sends data and returns response Data
  const newUser = await httpClient.postUnsafe<User>('/user', { body: { name: 'Alice' } });

  // PUT: Updates data and returns response Data
  const updatedUser = await httpClient.putUnsafe<User>('/user/1', { body: { name: 'Alice Smith' } });

  // PATCH: Partially updates data and returns response Data
  const patchedUser = await httpClient.patchUnsafe<User>('/user/1', { body: { name: 'Alice Jones' } });

  // DELETE: Deletes data and returns response Data
  const deletedUser = await httpClient.deleteUnsafe<User>('/user/1');

  // HEAD: Returns Headers
  const headHeaders = await httpClient.headUnsafe('/user/1');

  // OPTIONS: Returns Headers
  const optionsHeaders = await httpClient.optionsUnsafe('/user/1');

} catch (error) {
  // error is HttpError (or Error)
  // This block catches errors from ANY of the above requests
  console.error('Request failed:', error);
}

Timeout and Circuit Breaker

You can configure retry attempts and circuit breaker to handle network instability.

Retry only:

const settings = {
  responseAs: 'json',
  timeout: {
    retry: {
      errorStatus: [429, 500, 524],
      delays: [600, 3000, 6000, 9000],
      totalWaitTime: 60000,
    }
  }
}

httpClient.applySettings(settings); // or pass to individual request

Retry + Circuit Breaker:

const settings = {
  responseAs: 'json',
  timeout: {
    retry: {
      errorStatus: [429, 500, 524],
      delays: [600, 3000, 6000, 9000],
      totalWaitTime: 60000,
    },
    circuitBreaker: {
      failureThreshold: 3,
      successThreshold: 1,
      timeout: 3000,
    }
  }
}

httpClient.applySettings(settings); // or pass to individual request

Settings Parameters

By default retry requests and circuit breaker are disabled

Parameter Name Type Description
responseAs 'json' | 'text' | 'arrayBuffer' Determines how the response body is parsed. Default is 'json'.
baseUrl string Base URL to be prepended to all request URLs. Optional.
timeout object Configuration object for retry policies and circuit breaker. Optional.
timeout.retry object Retry strategy configuration. Required if timeout is defined.
timeout.retry.errorStatus number[] List of HTTP status codes that trigger a retry (e.g., [429, 500, 524]).
timeout.retry.delays number[] Array of delays (in ms) between retry attempts.
timeout.retry.totalWaitTime number Maximum amount of time (in ms) to wait for retries before giving up.
timeout.circuitBreaker object Circuit breaker configuration to prevent cascading failures. Optional.
timeout.circuitBreaker.failureThreshold number Number of failed requests before the circuit opens.
timeout.circuitBreaker.successThreshold number Number of successful requests required to close the circuit.
timeout.circuitBreaker.timeout number Duration (in ms) to wait in the open state before attempting a reset (half-open).

Rewrite fetch provider or error manager

If you want to rewrite implementation with fetch provider you should pass your provider to second argument, all example you can find it below in the documentation

import { HttpErrorManager } from 'typed-fetcher';

const errorManager = new HttpErrorManager();
const httpClient = new HttpClient(errorManager, /* pass your custom fetch provider*/);

If you want to rewrite implementation with error manager you should pass your provider to first argument, all example you can find it below in the documentation

import { FetchProvider } from 'typed-fetcher';

const fetchProvider = new FetchProvider()
const yourErrorManager: HttpErrorManagerBase = {}
const httpClient = new HttpClient(yourErrorManager, fetchProvider);

Example request

GET request:

interface User {
  name: string
  id: number
}

void (async (): Promise<void> => {
  const { data, error } = await httpClient.get<User>(`/posts`)

  if (error) {
    // do something with error
    return
  }
  console.log(data)
})()

POST request:

void (async (): Promise<void> => {
  const user: User = {
    name: 'Example name',
    id: 1,
  }
  const { data, error } = await httpClient.post<User>(`/posts`, { body: user })

  if (error) {
    // do something with error
    return
  }
  console.log(data)
})()

PUT request:

void (async (): Promise<void> => {
  const user: User = {
    name: 'Example name',
    id: 1,
  }
  const { data, error } = await httpClient.put<User>(`/posts`, { body: user })

  if (error) {
    // do something with error
    return
  }
  console.log(data)
})()

DELETE request:

void (async (): Promise<void> => {
  const userId = 1
  const { data, error } = await httpClient.delete<User>(`/posts/${userId}`)

  if (error) {
    // do something with error
    return
  }
  console.log(data)
})()

Auth or headers:

void (async (): Promise<void> => {
  const exampleToken = ''
  const requestOptions = {
    credentials: 'include', // if you use cookies auth
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${exampleToken}`,
    },
  } as const
  
  const {data, error} = await httpClient.get<User>(`/posts/${userId}`, requestOptions)

  if (error) {
    // do something with error
    return
  }
  console.log(data)
})()

XMLHttpRequest provider

You can use any implementation to perform requests — for example:

  • fetch (default)
  • XMLHttpRequest
  • Custom implementation of fetch (sometimes this happens)
import { HttpClient, HttpErrorManager, XmlHttpProvider } from 'typed-fetcher'

const httpErrorManager = new HttpErrorManager()
const xmlHttpProvider = new XmlHttpProvider()
const httpClient = new HttpClient(httpErrorManager, xmlHttpProvider)

Custom provider

You need to write a custom provider if you want to use custom implementation of fetch.

// interface HttpFetchProvider {
//   fetch: (params: RequestParams) => Promise<Response>;
// }

import { HttpFetchProvider, HttpErrorManager } from 'typed-fetcher';

class CustomProvider implements HttpFetchProvider {
  public fetch(params: RequestParams): Promise<Response> {
    // write your own implementation
  }
}

const customProvider = new CustomProvider();
const httpErrorManager = new HttpErrorManager();

const fetch = new HttpClient(httpErrorManager, customProvider);

Custom error handling

You need to write a custom error handler if you want to handle errors in a custom way.

// interface HttpErrorManagerBase {
//    throw: (response: Response, dataText: string) => never;
//    parse: <Data>(errorData: unknown) => HttpResponseFull<Data>;
// }

import { HttpErrorManagerBase, HttpErrorJSON } from 'typed-fetcher';

class ErrorHandler extends HttpErrorManagerBase {
  private readonly errorMessage = 'Custom error message';
  
  public throw(response: Response, dataText: string): never {
    // You need to throw an error in this method
    
    // For example:
    throw new Error(this.errorMessage);
  }
  
  parse<Data>(errorData: unknown): HttpResponseFull<Data> {
    // And this mehod you need a parse error which you throw in the throw method
    // You need to return an error in this method
    
    // For example:
    
    if (errodData instanceof Error && errorData.message === this.errorMessage) {
      const message: string = 'Your custom message'
      const status: number = 500;
      const details: unknown | null = null;
      
      return {
        data: null,
        error: new HttpErrorJSON(message, status, details) // or you can extend from class HttpErrorBase and write your own error
      }
    }
  }
}
const errorHandler = new ErrorHandler();
const httpErrorManager = new HttpErrorManager(errorHandler);

About

Typed-fetcher is a npm package for typed HTTP requests.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

15 tags

Packages

 
 
 

Contributors 2

  •  
  •  

Languages