Global Options

The ApiProvider from @vergestack/api-react allows you to set up global configuration options via React contexts. Local options passed to hooks take precedence over global options, allowing for fine-grained control when needed.

Available Options

The ApiProvider accepts an options object with the following properties:

• onStart: Called when the action starts executing
• onSuccess: Called when the action is successful
• onError: Called when the action encounters one or more errors
• onComplete: Called after the action completes, regardless of success or failure

Usage Example

Here's an example of how to set up the ApiProvider with global configuration:

import { ApiProvider, ApiErrorWithMetadata } from '@vergestack/api-react';
 
function App() {
  const globalOptions = {
    onStart: () => {
      console.log('Global start handler');
    },
    onSuccess: (data: unknown) => {
      console.log('Global success handler:', data);
    },
    onError: (errors: ApiErrorWithMetadata[]) => {
      console.error('Global error handler:', errors);
    },
    onComplete: () => {
      console.log('Global completion handler');
    }
  };
 
  return (
    <ApiProvider value={{ options: globalOptions }}>
      {/* Your app components */}
    </ApiProvider>
  );
}

Callbacks

onStart

The global onStart callback is triggered when any action starts execution. It doesn't receive any arguments.

onStart: () => void

onSuccess

The global onSuccess callback is triggered when any action completes successfully. It receives the action's result data as its argument.

onSuccess: (data: unknown) => void

onError

The global onError callback is triggered when any action encounters an error. It receives a list of error objects.

onError: (errors: ApiErrorWithMetadata[]) => void

onComplete

The global onComplete callback is executed after any action finishes, regardless of whether it succeeded or failed. It doesn't receive any arguments.

onComplete: () => void

Overriding Global Configuration

The global configuration can be overridden by passing local options to individual useAction hooks. Local options take precedence over global options.

import { useAction } from '@vergestack/api-react';
import { greetingAction } from './actions';
 
function MyComponent() {
  const { data, errors, execute } = useAction(greetingAction, {
    onSuccess: (data) => {
      console.log('Local success handler:', data);
    }
    // This will override the global onSuccess handler for this specific useAction call
  });
 
  // Rest of your component code
}

By using the ApiProvider with global configuration, you can set up default behavior for all actions in your application, while still maintaining the flexibility to customize behavior for specific cases using local configuration.