A wrapper around react-query to allow strong typing for your endopints

·

Report Bug

·

Request Feature

About The Project

The aim of this project is to create a wrapper around react-query with for easily strong-typing your endpoints.

By using typescript's augmentation feature, you will define your routes along with response and payload types and then you will be able to have strong typing for your endpoints

A companion node cli is under development

Built With

• React Query

Prerequisites

you need to have the following libraries already installed:

• React Query

Getting Started

Install the library from npm registry

Installation

This is an example of how to list things you need to use the software and how to install them.

• npm

npm i apperside/react-query-wrapper

• yarn

yarn add apperside/react-query-wrapper

Usage

This library is a wrapper around react-query, so before you begin using this library, you need to install and configure react-query as explained in their docs.

react-query-wrapper is also based on the concept of augmentation, you can find more about typescript augmentation in the dedicated documentation.

The first interface to know about is AppRoutes, which is declared as follows

    export interface AppRoutes {
      main: MainApi
    }
    
    export interface MainApi {
      /**
       * TO BE AUGMENTED
       */
    }

The statement main: MainApi means that the app has one default api, whose scope is main. You can create as many scopes you want, we will speak about api scopes later on.

In order to agument the main scope and add your routes, you have to augment MainApi interface

    /**
     * You have to add this declaration wherever you want to augment librariy's types
     */
    declare module "react-query-wrapper" {
      /**
       * Augment this interface to add al custom endpoints
       */
      export interface MainApi {
        // MyApiResponseType and MyApiPayloadType are whatever type you want depending on your endpoint response and payload
        "my-route": { responseType: MyApiResponseType, payloadType: MyApiPayloadType }
        // if the payload is the same as the response, you can omit the payloadType 
        "another-custom-route": { responseType: MyApiResponseType2 }
      }
    }

let say we augment our main api like this

    type MyApiResponseType = { field1: string }
    type MyApiPayloadType = { field2: string }
    type MyApiResponseType2 = { field3: string }
    
    declare module "react-query-wrapper" {
      export interface MainApi {
        "my-route": { responseType: MyApiResponseType, payloadType: MyApiPayloadType }
        "another-custom-route": { responseType: MyApiResponseType2 }
      }
    }

we will have the following typescript behavior useAppQuery is nothing else that a wrapper around react-query's useQuery, it just wraps it with strong typing thanks to typescript augmentation. Together with useAppQuery there is also useAppMutation

As your can see, types are automatically inferred based on the types declared in augmentation

PATH PARAMS

You can also use routes with variable parameters. Given we augment the api like this

      type MyApiResponseType = { field1: string }
      type MyApiPayloadType = { field2: string }
      
      export interface MainApi {
            "my-route/:id": { responseType: MyApiResponseType, payloadType: MyApiPayloadType },
      }

we can use this endpoint like this:

QUERY

    const query = useAppQuery("my-route/:id", { pathParams: { id: "123" } });

MUTATION

    const mutation = useAppMutation("my-route/:id")
    mutation.mutate({ field2: "value", pathParams: { id: "123" } })

API SCOPES

You can use augmentation to add as many set of apis as you need, you just need to augment the interface RoutesMapping. An api scope is intended to be a group of endpoint pointing to the same server and having the same prefix. Let say we do the augmentation in the following way

      type MyApiResponseType = { field1: string }
      type MyApiPayloadType = { field2: string }
      type MyApiResponseType2 = { field3: string }
    
      export interface MainApi {
        "my-route/:id": { responseType: MyApiResponseType, payloadType: MyApiPayloadType },
      }
    
      /**
       * Augment this interface to as many groups of api you need.
       * A group of api is a set of endpoints that share the same prefix,server,port and protocol
       */
      export interface RoutesMapping {
        
        anotherApi: {
          "another-api-route": { responseType: { anotherApiResponseField: string } }
        }
      }

You will be able to use the other scope like this

      const query = useAppQuery({ scope: "anotherApi", route: "another-api-route" });
    
      const mutation = useAppMutation({ scope: "anotherApi", route: "another-api-route" })

You will have full intellisense also in this case

INITIALIZATION

after you have defined all of your routes, you need to initialize the library by providing the server informations for all the defined api scopes. A good point to do this could be the same point where you initialize react-query's query client and pass it to the app's context (as explained in their docs)

    import { initNetworking } from "react-query-wrapper";
    
    initNetworking({
      servers: {
        /**
         * this api will point to https://my.server.com:443/api/v1
         */
        main: {
          port: 443,
          serverAddress: "my.server.com",
          protocol: "https",
          baseUrl: "api/v1"
        },
        /**
         * this api will point to https://my.second.server.com:443/custom/v2
         */
        otherApi: {
          port: 443,
          serverAddress: "my.second.server.com",
          protocol: "https",
          baseUrl: "custom/v2"
        }
      }
    });

Roadmap

• [x] Publish initial version

[] Add documentation

[] Add tests

[] Split in different packages (ui-core, redux-utils, api-utils)

[] Much more 😅

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Don't forget to give the project a star! Thanks again!

1. Fork the Project

2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

3. Commit your Changes (git commit -m 'Add some AmazingFeature')

4. Push to the Branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

Your Name Apperside - https://apperside.com - [email protected]

Project Link: https://github.com/apperside/react-query-wrapper