useAjax

Description

The useAjax composable is a reusable utility to streamline HTTP requests across the application. It wraps Nuxt’s native $fetch with a standardized interface, built-in support for loading indicators, error handling, and optional callback integration.

This composable allows you to easily handle asynchronous data fetching while reducing boilerplate and enforcing consistency across all API calls.

FEATURE GOALS

• Provide a centralized and configurable interface for AJAX requests.
• Support common HTTP methods (GET, POST, PUT, PATCH, DELETE).
• Allow dynamic configuration of request parameters, headers, and query strings.
• Integrate seamlessly with UI elements like loading indicators.
• Trigger error handling and allow for debug-level logs.
• Allow optional callbacks to handle responses in real-time.

FEATURE EXPECTATIONS

• Accepts and merges custom options with default configurations.
• Automatically distinguishes between GET and other request types for parameter placement (query vs body).
• Shows or hides a global loading indicator based on config.
• Handles exceptions gracefully and allows severity tagging.
• Optionally enables verbose debugging via the debug flag.
• Provides callback support for post-response logic.
• Error handling is delegated to a custom client error handler.
• Supports future notification system integration via show_notifications flag (currently disabled).

DEV STRATEGIES

1. Composables Logic

const response = await useAjax<User[]>('/api/users', {
  method: 'get',
  query: { role: 'admin' },
  headers: { Authorization: 'Bearer token' },
  debug: true
}, (data, response) => {
  if (data) {
    console.log('Success:', data);
  } else {
    console.warn('Failed:', response.errors);
  }
});

• Merge default config with custom options.
• Based on method, assign params to body or leave as query.
• Add required headers, including JSON defaults.
• Display loading state if enabled.
• On success, invoke callback and return the response.
• On failure, trigger client error handler, log errors, invoke callback, and return a standardized error object.

2. COMPOSABLE STRUCTURE

useAjax<T>(
  url: string,
  options?: {
    params?: object,
    method?: 'get' | 'post' | 'put' | 'patch' | 'delete',
    query?: object,
    headers?: object,
    show_notifications?: boolean,
    show_loading_indicator?: boolean,
    severity?: string,
    debug?: boolean
  },
  callback?: Function
): Promise<T | AjaxErrorResponse>

3. DEFAULT BEHAVIOR

4. ERROR RESPONSE STRUCTURE

• If the request fails, the returned response has this structure:

{
  success: false,
  errors: string[],
  data: any
}

• If debug: true, errors will contain the raw error message.

FLOW SUMMARY

• Composable is invoked with a URL, optional config, and a callback.
• Internal config is merged with defaults.
• $fetch is used to send the request with the final config.
• A global loading indicator is optionally triggered.
• On success:
  • Callback is called with response data.
  • Response is returned.
• On error:
  • Error is handled via customClientErrorHandler.
  • Callback is called with false and formatted error.
• Final error response object is returned.