libra-query

A React Query wrapper library for HTTP requests with Axios, providing a type-safe and easy-to-use API for data fetching and mutations in React applications.

Features

• Type-safe: Built with TypeScript for full type safety
• React Query Integration: Leverages the power of React Query for caching, refetching, and state management
• Request Builder Pattern: Fluent API for building HTTP requests
• Flexible Configuration: Support for custom headers, interceptors, and request options
• Multiple HTTP Methods: Built-in support for GET, POST, PUT, DELETE, etc.
• Automatic Query Keys: Smart query key generation for optimal caching

Installation

pnpm add libra-query
# or
npm install libra-query
# or
yarn add libra-query

Peer Dependencies

This package requires the following peer dependencies:

{
  "react": "^18.0.0",
  "@tanstack/react-query": "^5.0.0"
}

Quick Start

1. Wrap your app with the provider

import { LibraQueryProvider } from 'libra-query/provider';

function App() {
  return (
    <LibraQueryProvider
      baseURL="https://api.example.com"
      timeout={30000}
      headers={{
        'X-Custom-Header': 'value',
      }}
      requestInterceptor={(config) => {
        // Modify request config before sending
        console.log('Request:', config);
        return config;
      }}
      responseInterceptor={(response) => {
        // Modify response data
        console.log('Response:', response);
        return response;
      }}
    >
      {/* Your app components */}
    </LibraQueryProvider>
  );
}

2. Set up the request builder

import { RequestBuilder } from 'libra-query/builder';
import { useLibraQuery } from 'libra-query/provider';

// Define your API endpoints
export const getUserApi = new RequestBuilder({
  url: '/api/user',
  method: 'get',
});

export const updateUserApi = new RequestBuilder({
  url: '/api/user',
  method: 'put',
});

3. Use in your components

import { useMemo } from 'react';
import { getUserApi, updateUserApi } from './api';
import { useLibraQuery } from 'libra-query/provider';

function UserProfile() {
  const { requestInstance } = useLibraQuery();

  // Configure the request builder to use the provider's request instance
  const userApi = useMemo(() => new RequestBuilder({
    url: '/api/user',
    method: 'get',
    requestFn: requestInstance,
  }), [requestInstance]);

  // Fetch data with useQuery
  const { data: user, isLoading, error } = userApi.useQuery();

  // Update data with useMutation
  const updateMutation = updateUserApi.useMutation({
    onSuccess: () => {
      console.log('User updated successfully');
    },
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error loading user</div>;

  return (
    <div>
      <h1>{user?.name}</h1>
      <button onClick={() => updateMutation.mutate({ name: 'New Name' })}>
        Update Name
      </button>
    </div>
  );
}

API Reference

LibraQueryProvider

Provider component that wraps your app with React Query and provides a configured Axios instance.

Props

interface LibraQueryConfig {
  baseURL?: string;           // Base URL for all API requests
  timeout?: number;           // Request timeout in milliseconds (default: 30000)
  headers?: RawAxiosRequestHeaders;  // Custom headers to include in all requests
  requestInterceptor?: (config) => config | Promise<config>;  // Request interceptor
  responseInterceptor?: (response) => response | Promise<response>;  // Response interceptor
  responseErrorInterceptor?: (error) => any | Promise<any>;  // Error interceptor
  silence?: boolean;          // Disable automatic error messages (default: false)
}

Example

<LibraQueryProvider
  baseURL="https://api.example.com"
  headers={{
    'Authorization': 'Bearer token',
    'X-Custom-Header': 'value',
  }}
  requestInterceptor={(config) => {
    console.log('Sending request:', config);
    return config;
  }}
  responseInterceptor={(response) => {
    console.log('Received response:', response);
    return response;
  }}
>
  <App />
</LibraQueryProvider>

useLibraQuery

Hook to access the request instance and configuration from the LibraQueryProvider.

function MyComponent() {
  const { requestInstance, config } = useLibraQuery();

  // Use requestInstance with RequestBuilder
  const api = useMemo(() => new RequestBuilder({
    url: '/endpoint',
    requestFn: requestInstance,
  }), [requestInstance]);

  // ...
}

RequestBuilder

The core class for building API requests.

Constructor Options

interface RequestBuilderOptions<Req, Res> {
  method?: Lowercase<Method>; // HTTP method, default: 'get'
  url: string;                // API endpoint URL
  urlPathParams?: string[];   // Path parameters, e.g., ['id'] for '/api/user/{id}'
  requestFn?: <T>(config: AxiosRequestConfig) => Promise<T>;
  meta?: RequestBuilderMeta;
  useQueryOptions?: UseQueryOptions<Res, Error, Res>;
  useMutationOptions?: UseMutationOptions<Res, Error, Req>;
}

Methods

request(params?, config?)

Make a direct HTTP request.

const data = await api.request({ userId: 123 });

useQuery(params?, options?)

React Query hook for fetching data.

const { data, isLoading, error } = api.useQuery(
  { page: 1 },
  {
    staleTime: 60000,
  }
);

useMutation(options?)

React Query hook for mutations.

const mutation = api.useMutation({
  onSuccess: (data) => {
    console.log('Success:', data);
  },
});

mutation.mutate({ name: 'John' });

ReactQueryProvider

Legacy provider component (use LibraQueryProvider instead for full functionality).

import { ReactQueryProvider } from 'libra-query/provider';

<ReactQueryProvider>{children}</ReactQueryProvider>

Default Configuration

The default configuration includes:

• Stale Time: 5 minutes
• Retry: 1 retry on failure
• Refetch on Window Focus: Disabled
• Refetch on Reconnect: Enabled

Custom Request Function

You can create custom request instances:

import { getRequestFn } from 'libra-query';
import { RequestBuilder } from 'libra-query/builder';

const customRequest = getRequestFn({
  prefix: 'https://api.example.com',
  requestInterceptor: (config) => {
    // Modify request config
    config.headers = {
      ...config.headers,
      'X-Custom-Header': 'value',
    };
    return config;
  },
  silence: false,
});

const api = new RequestBuilder({
  url: '/endpoint',
  requestFn: customRequest,
});

License

MIT