@spa-tools/api-client

React Hook Reference

If you're fetching data in a React based SPA, then boy do we have an awesome hook for you! But if it's not to your liking, then creating your own using the callEndpoint function is a breeze.

This reference uses Typescript syntax but works for Javascript as well (simply ignore all type usage).

useCallEndpoint()

The useCallEndpoint<D, E, S> hook wraps the callEndpoint function to provide a sweet React dev experience for fetching API data right where you need it most (directly within your function components).

Usage

import { useEffect } from 'react';
import { useCallEndpoint } from '@spa-tools/api-client';

function LoadRecipes() {
  const [loadRecipes, recipesResult, areRecipesLoading, clearRecipes] = useCallEndpoint(
    'https://dummyjson.com/recipes',
    {
      serverModelOptions: { jsonDataDotPath: 'recipes' },
    }
  );

  useEffect(() => {
    if (recipesResult?.data && !areRecipesLoading) {
      console.log(`loadRecipes call completed:`);
      console.log(recipesResult.data);
    } else if (recipesResult?.error) {
      console.error(`loadRecipes call errored:`);
      console.error(recipesResult.error);
    }
  }, [areRecipesLoading, recipesResult]);

  return (
    <div>
      <h1>Recipes</h1>
      <div>
        <button disabled={recipesResult?.data?.length} onClick={loadRecipes}>
          Load Recipes
        </button>
        <button disabled={!!recipesResult?.data?.length} onClick={clearRecipes}>
          Clear Recipes
        </button>
      </div>
      <div>
        {areRecipesLoading ? (
          <div>Loading recipes...</div>
        ) : (
          <ul>{recipesResult?.data?.map((recipe) => <li key={recipe.id}>{recipe.name}</li>)}</ul>
        )}
      </div>
    </div>
  );
}

Generics

There are three generic types that can be included when calling useCallEndpoint in the following order:

• D is used to define the shape of the result data returned from the endpoint
• E is used to define the shape of the error data returned from the endpoint
• S is used to define the shape of the state passed to the endpoint for interpolation

Method overloads

There are six method signature overloads for useCallEndpoint that can be used to setup the hook to make call execution succinct, flexible, and comprehensive:

• useCallEndpoint<D, E, S>(url)
• useCallEndpoint<D, E, S>(url, options)
• useCallEndpoint<D, E, S>(url, appendData)
• useCallEndpoint<D, E, S>(url, options, appendData)
• useCallEndpoint<D, E, S>(options)
• useCallEndpoint<D, E, S>(options, appendData)

Parameters

Parameter	Type	Description
url	string	The URL of the endpoint to be called
options	EndpointOptions	An object that can be used to configure the request
appendData	boolean	When set to true, appends data from successive GET execution calls for an endpoint that supports pagination This is useful in UX scenarios such as "load more", "infinite scroll", etc.

Returns

Returns a UseCallEndpointTuple.

UseCallEndpointTuple

The UseCallEndpointTuple tuple const is returned from the useCallEndpoint hook and contains the following elements:

1. execute - A function that when called asynchronously executes the endpoint request

   The execute function can be called with optional parameters via following overrides:

   • No params - execute()
   • With just exec options - execute(options: Pick<EndpointOptions, 'body' | 'pageToken' | 'recordSkip' | 'signal'>)
   • With just state - execute(state: S)
   • With exec options and state - execute(options: Pick<EndpointOptions, 'body' | 'pageToken' | 'recordSkip' | 'signal'>, state: S)

2. result - An EndpointResult object that contains the result of the endpoint request

3. pending - A boolean that indicates if the endpoint request is currently in progress

4. clear - A function that when called clears the result of the endpoint request