Skip to content

A complete Axios wrapper that uses RxJS observables instead of promises

License

Notifications You must be signed in to change notification settings

JoseLion/rxjs-axios

Folders and files

NameName
Last commit message
Last commit date

Latest commit

29e87ad ยท Jun 23, 2024

History

39 Commits
Jun 23, 2024
Jun 23, 2024
Jun 23, 2024
Jun 23, 2024
Jan 26, 2023
Jun 23, 2024
Nov 25, 2023
Jun 23, 2024
Nov 6, 2022
Nov 26, 2023
Jan 21, 2024
Jun 23, 2024
Jun 23, 2024
Jun 23, 2024
Jun 23, 2024
Jun 23, 2024
Jun 23, 2024

Repository files navigation

CI CodeQL Pages Release NPM version NPM bundle size NPM downloads NPM license GitHub Release Date Known Vulnerabilities

rxjs-axios

A complete Axios wrapper that uses RxJS observables instead of promises. Same Axios API, but anything that used to return a Promise<T> will now return an Observable<T> instead.

Overview

Even though there are a few options out there for Axios wrappers converting its promise-based methods to observables, this library offers a few extra features that make it different:

  • Based on Axios v1.0.0 and forward.
  • TypeScript first oriented.
    • Written 100% in TypeScript; everything has type definitions.
    • All Axios types are re-exported, so you can import everything from rxjs-axios.
    • Methods no longer default their type to any. Instead, they default to unknown, which not only makes things safer but also forces you to add better types to your code.
  • Unsubscribing cancels the request.
    • Cancellation happens on the observable teardown logic, with no mutation or workarounds.
    • Uses AbortController instead of Axios deprecated CancelToken.
  • Seamless usage; works just like Axios.
    • Besides the Observables, you won't feel any difference with Axios API.
    • All Axios methods are provided. Other libraries only provide the most commonly used methods (e.g., get, post, put, etc.), while rxjs-axios provide everything available in the Axios instance, like request(..), all form-related methods (e.g., postForm(..), toFormData(..), formToJSON(..), etc.), isAxiosError(..), defaults, interceptors.
  • Fully tested.
    • Ensure compatibility around NodeJS, Axios, and RxJS versions.
    • Safer upgrades, no unexpected surprises.

Versions Compatibility

  • NodeJS: >=16
  • Axios: >=1.0.0
  • RxJS: >=5.5.12

Install

This library has axios and rxjs as required peer dependencies, so don't forget to add them too.

With NPM:

npm i rxjs-axios axios rxjs

With Yarn:

yarn add rxjs-axios axios rxjs

Usage

You can use rxjs-axios the same way as you would do with Axios. The only difference is that request will result in an Observable<AxiosResponse<T>>, so you'll have to subscribe to the observable to get the response. If you're using TypeScript, remember to add a type to the method's generic ๐Ÿ˜‰.

Simple example:

import { axios } from "rxjs-axios";
import { map } from "rxjs"

axios.get<User[]>("/api/users")
  .pipe(map(({ data }) => data))
  .subscribe(users => {
    // do anything with users array
  });

This becomes particularly cleaner on ReactJS, as you can unsubscribe on the useEffect(..) clean-up callback:

import { ReactElement, useEffect, useState } from "react";
import { axios } from "rxjs-axios";
import { finalize, map } from "rxjs"

function UsersScreen(): ReactElement {
  const [pending, setPending] = useState(false);
  const [users, setUsers] = useState<User[]>([]);

  useEffect(() => {
    setPending(true);

    const subscription = axios.get<User[]>("/api/users")
      .pipe(
        map(({ data }) => data),
        finalize(() => setPending(false)),
      )
      .subscribe(setUsers);

    // The request will be canceled if the component is unmounted and the
    // subscription was not yet complete
    return () => subscription.unsubscribe();
  }, []);

  return (
    <DataTable
      pending={pending}
      data={users}
      // ...rest of DataTable props
    />
  )
}

Something's missing?

Suggestions are always welcome! Please create an issue describing the request, feature, or bug. We'll try to look into it as soon as possible ๐Ÿ™‚

Contributions

Contributions are very welcome! To do so, please fork this repository and open a Pull Request to the main branch.

License

MIT License