PAS HOOKS

This project was bootstrapped with Create React App.

Description

This project includes react query hooks wrapping API Endpoints as specified in the swagger documentation here: https://api.pas.dirox.dev/explorer#/. The name of each hook closely follows the api endpoint. For example, the endpoint /api/v1/users/angel-current-status can be used by calling useGetUsersAngelCurrentStatusQuery. If any api requires any query params like this api /api/v1/users/:user-id/angel-current-status then the argument passed in the query represents user-id. The hooks are written in Typescript so you will get instructed on how to pass in the correct argument while typing. If you have questions, please contact Viet Dang at [email protected].

This project uses the following libraries under peerDependencies. Please ensure that your project uses the same library version (if you have already installed the library in your project). Or contact Viet at [email protected] for update if necessary.

"peerDependencies": {
    "@tanstack/react-query-devtools": "^4.33.0",
    "react-query": "^3.39.3",
    "@types/react-dom": "^17.0.2",
    "axios": "^1.5.0",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "react-scripts": "5.0.1"
},

Documentation reference

@tanstack/react-query-devtools

react-query

axios

How to use

In the App.jsx (or App.tsx file), import the withPasQuery:

import { withPasQuery } from 'pas_hooks';

And then wrap it around the component returned in App, pass in the domain endpoint as the second argument like this:

const WrappedComponent = withPasQuery(YourComponent, "https://api.pas.dirox.dev");
return <WrappedComponent/>

By doing this, you will get accessed to all query and mutation hooks in the props of YourComponent. When you want to use any hooks provided by pas_hooks, you can simply destructure it from the usePasHook() imported from the pas_hooks module:

// Import the usePasHook
import { usePasHook } from 'pas_hooks'

// Replace the [nameOfHook] by the hook that you want to use. 
const { [nameOfHook] } = usePasHook()

For example, if you want to register a new user, you can destructure the register mutation hook from the usePasHook.

const { register } = usePasHook()

And invoke it

try { 
    const data = register({
        name: 'Name',
        email: 'Email',
        gender: 'Gender',
        password: 'Password',
        confirmPassword: 'Password',
        timezoneId: 'timezoneId',
        languageId: 'languageId'
    })
} catch (e) { 
    console.error(e) 
}

IMPORTANT: The [nameOfHook] here are the hooks that pas_hooks provided, corresponding to the existing PAS API endpoint provided in the Swagger Documentation. For example, the endpoint for register /api/v1/users/register should correspond to the register hook in the example above. The arguments used in invocation strictly follows what arguments are required in the Swagger API Endpoints.

If you want to create a custom login or register, you can do so by adding the third argument in the withPasQuery. The third argument requires method, endpoint and other optional argument such as queryKey (for useQuery hook), data (for useMutation hook).

function App() {
    const WrappedComponent = withPasQuery(Home, "https://api-testing.pas.dirox.dev", {
        useCustomGetAngelCurrentStatus: {
            endpoint: "/api/v1/users/angel-current-status",
            method: HttpRequestMethod.GET,
            queryKey: 'angel-current-status',
            isQuery: true,
        },
        customLogin: {
            endpoint: "/api/v1/users/login",
            method: HttpRequestMethod.POST,
            isQuery: false
        },
        useCustomGetPersonAlertsById: {
            endpoint: "/api/v1/users/person-alerts/:id",
            method: HttpRequestMethod.GET,
            isQuery: true,
            queryKey: ['person-alerts', ':id'],
        }
    });
    return <WrappedComponent/>
}

To use custom hook, simply destructure it from the usePasHook() query

const { customLogin } = usePasHook();
customLogin(credentials)

Important: If you pass in a route param like this

endpoint: "/api/v1/users/person-alerts/:id",

then please make sure that the first argument passed to your custom query is an object with key matches the queryParam. Like so:

useCustomGetPersonAlertsById({ id: 1 })

The second arguments is optional and it includes the callbackSuccess, callbackError, search, and other queryOptions (as specified in the react query documentation).

The hook returns a promise that allows you to access the data or error by using try catch block or chainable then. You can also reference the source code, and view the App.tsx file for how to use the usePasQuery, and the Home.tsx component for how to use the usePasHook()

There are two main types of pas_hooks function, query hook and mutation hook. The mutation hooks (like the register hook in the example above) are used to create/modify data on the Backend using HTTP methods (PUT, POST, PATCH, DELETE). Query hooks are used to get the data from the Backend using HTTP GET method.

Mutation hook does not include use or Query like the register hook in the example above.

The useQuery hooks are always prefixed with use and suffixed with Query For example:

const { useGetUserCurrentStatusQuery } = usePasHook()
const { data, error, isSuccess, isError, isLoading } = useGetUserCurrentStatusQuery({}, { enabled: true });

The data returned from those useQuery hooks (data, error, etc) follows react-query standard in their official documentation and the arguments used are specified in the Swagger Documentation If you have any questions, please contact me Viet Dang at [email protected]

Installations:

Run npm i pas_hooks to install the project.

Available Scripts

In the project directory, you can run:

npm start

Runs the app to view the test app. Open http://localhost:3000 to view it in your browser.

The page will reload when you make changes.
You may also see any lint errors in the console.

npm test

Launches the test runner in the interactive watch mode.
See the section about running tests for more information.

npm run build

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

npm run eject

Note: this is a one-way operation. Once you eject, you can't go back!

If you aren't satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you're on your own.

You don't have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn't feel obligated to use this feature. However we understand that this tool wouldn't be useful if you couldn't customize it when you are ready for it.

Learn More

You can learn more in the Create React App documentation.

To learn React, check out the React documentation.

Code Splitting

This section has moved here: https://facebook.github.io/create-react-app/docs/code-splitting

Analyzing the Bundle Size

This section has moved here: https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size

Making a Progressive Web App

This section has moved here: https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app

Advanced Configuration

This section has moved here: https://facebook.github.io/create-react-app/docs/advanced-configuration

Deployment

This section has moved here: https://facebook.github.io/create-react-app/docs/deployment

npm run build fails to minify

This section has moved here: https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify

Copyright

Copyright by Dirox https://dirox.com/