{"_id":"@acxxsdpj/libra-query","name":"@acxxsdpj/libra-query","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@acxxsdpj/libra-query","version":"1.0.0","description":"A React Query wrapper library for HTTP requests with Axios","type":"module","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.cjs","import":"./dist/index.js"},"./builder":{"types":"./dist/builder.d.ts","require":"./dist/builder.cjs","import":"./dist/builder.js"},"./provider":{"types":"./dist/provider.d.ts","require":"./dist/provider.cjs","import":"./dist/provider.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","prepublishOnly":"npm run build","typecheck":"tsc --noEmit"},"keywords":["react-query","axios","http","request","fetch","react","hooks"],"author":"","license":"MIT","repository":{"type":"git","url":""},"peerDependencies":{"react":"^18.0.0","@tanstack/react-query":"^5.0.0"},"dependencies":{"axios":"^1.6.0"},"devDependencies":{"@tanstack/react-query":"^5.0.0","@types/node":"^20.0.0","@types/react":"^18.0.0","tsup":"^8.0.0","typescript":"^5.0.0"},"engines":{"node":">=16.0.0"},"_id":"@acxxsdpj/libra-query@1.0.0","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-bb8XoRjziUo7U7B+ZFhfb1QRjRVKotSeC7H9Xt9NBC1ciXJIx8iiB/1EAh2cS8Hps5UN9oSaD2Gx4WbXbsLkPw==","shasum":"42e1d643f4296e8e76eff741a94c79a050996143","tarball":"https://registry.npmjs.org/@acxxsdpj/libra-query/-/libra-query-1.0.0.tgz","fileCount":21,"unpackedSize":83081,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH46jKMDvXhAghzFvusuHo47nEoM0y3aq0CTaW12t2kTAiAvLH6iw3Fghk3GZRhcuvC9wDF35El8wamgPHI/n5SDYQ=="}]},"_npmUser":{"name":"acxxsdpj","email":"acxxsdpj@gmail.com"},"directories":{},"maintainers":[{"name":"acxxsdpj","email":"acxxsdpj@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/libra-query_1.0.0_1773657177273_0.8492851417394307"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-16T10:32:57.206Z","1.0.0":"2026-03-16T10:32:57.425Z","modified":"2026-03-16T10:32:58.010Z"},"maintainers":[{"name":"acxxsdpj","email":"acxxsdpj@gmail.com"}],"description":"A React Query wrapper library for HTTP requests with Axios","keywords":["react-query","axios","http","request","fetch","react","hooks"],"repository":{"type":"git","url":""},"license":"MIT","readme":"# libra-query\n\nA 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.\n\n## Features\n\n- **Type-safe**: Built with TypeScript for full type safety\n- **React Query Integration**: Leverages the power of React Query for caching, refetching, and state management\n- **Request Builder Pattern**: Fluent API for building HTTP requests\n- **Flexible Configuration**: Support for custom headers, interceptors, and request options\n- **Multiple HTTP Methods**: Built-in support for GET, POST, PUT, DELETE, etc.\n- **Automatic Query Keys**: Smart query key generation for optimal caching\n\n## Installation\n\n```bash\npnpm add libra-query\n# or\nnpm install libra-query\n# or\nyarn add libra-query\n```\n\n## Peer Dependencies\n\nThis package requires the following peer dependencies:\n\n```json\n{\n  \"react\": \"^18.0.0\",\n  \"@tanstack/react-query\": \"^5.0.0\"\n}\n```\n\n## Quick Start\n\n### 1. Wrap your app with the provider\n\n```tsx\nimport { LibraQueryProvider } from 'libra-query/provider';\n\nfunction App() {\n  return (\n    <LibraQueryProvider\n      baseURL=\"https://api.example.com\"\n      timeout={30000}\n      headers={{\n        'X-Custom-Header': 'value',\n      }}\n      requestInterceptor={(config) => {\n        // Modify request config before sending\n        console.log('Request:', config);\n        return config;\n      }}\n      responseInterceptor={(response) => {\n        // Modify response data\n        console.log('Response:', response);\n        return response;\n      }}\n    >\n      {/* Your app components */}\n    </LibraQueryProvider>\n  );\n}\n```\n\n### 2. Set up the request builder\n\n```tsx\nimport { RequestBuilder } from 'libra-query/builder';\nimport { useLibraQuery } from 'libra-query/provider';\n\n// Define your API endpoints\nexport const getUserApi = new RequestBuilder({\n  url: '/api/user',\n  method: 'get',\n});\n\nexport const updateUserApi = new RequestBuilder({\n  url: '/api/user',\n  method: 'put',\n});\n```\n\n### 3. Use in your components\n\n```tsx\nimport { useMemo } from 'react';\nimport { getUserApi, updateUserApi } from './api';\nimport { useLibraQuery } from 'libra-query/provider';\n\nfunction UserProfile() {\n  const { requestInstance } = useLibraQuery();\n\n  // Configure the request builder to use the provider's request instance\n  const userApi = useMemo(() => new RequestBuilder({\n    url: '/api/user',\n    method: 'get',\n    requestFn: requestInstance,\n  }), [requestInstance]);\n\n  // Fetch data with useQuery\n  const { data: user, isLoading, error } = userApi.useQuery();\n\n  // Update data with useMutation\n  const updateMutation = updateUserApi.useMutation({\n    onSuccess: () => {\n      console.log('User updated successfully');\n    },\n  });\n\n  if (isLoading) return <div>Loading...</div>;\n  if (error) return <div>Error loading user</div>;\n\n  return (\n    <div>\n      <h1>{user?.name}</h1>\n      <button onClick={() => updateMutation.mutate({ name: 'New Name' })}>\n        Update Name\n      </button>\n    </div>\n  );\n}\n```\n\n## API Reference\n\n### LibraQueryProvider\n\nProvider component that wraps your app with React Query and provides a configured Axios instance.\n\n#### Props\n\n```tsx\ninterface LibraQueryConfig {\n  baseURL?: string;           // Base URL for all API requests\n  timeout?: number;           // Request timeout in milliseconds (default: 30000)\n  headers?: RawAxiosRequestHeaders;  // Custom headers to include in all requests\n  requestInterceptor?: (config) => config | Promise<config>;  // Request interceptor\n  responseInterceptor?: (response) => response | Promise<response>;  // Response interceptor\n  responseErrorInterceptor?: (error) => any | Promise<any>;  // Error interceptor\n  silence?: boolean;          // Disable automatic error messages (default: false)\n}\n```\n\n#### Example\n\n```tsx\n<LibraQueryProvider\n  baseURL=\"https://api.example.com\"\n  headers={{\n    'Authorization': 'Bearer token',\n    'X-Custom-Header': 'value',\n  }}\n  requestInterceptor={(config) => {\n    console.log('Sending request:', config);\n    return config;\n  }}\n  responseInterceptor={(response) => {\n    console.log('Received response:', response);\n    return response;\n  }}\n>\n  <App />\n</LibraQueryProvider>\n```\n\n### useLibraQuery\n\nHook to access the request instance and configuration from the LibraQueryProvider.\n\n```tsx\nfunction MyComponent() {\n  const { requestInstance, config } = useLibraQuery();\n\n  // Use requestInstance with RequestBuilder\n  const api = useMemo(() => new RequestBuilder({\n    url: '/endpoint',\n    requestFn: requestInstance,\n  }), [requestInstance]);\n\n  // ...\n}\n```\n\n### RequestBuilder\n\nThe core class for building API requests.\n\n#### Constructor Options\n\n```ts\ninterface RequestBuilderOptions<Req, Res> {\n  method?: Lowercase<Method>; // HTTP method, default: 'get'\n  url: string;                // API endpoint URL\n  urlPathParams?: string[];   // Path parameters, e.g., ['id'] for '/api/user/{id}'\n  requestFn?: <T>(config: AxiosRequestConfig) => Promise<T>;\n  meta?: RequestBuilderMeta;\n  useQueryOptions?: UseQueryOptions<Res, Error, Res>;\n  useMutationOptions?: UseMutationOptions<Res, Error, Req>;\n}\n```\n\n#### Methods\n\n##### `request(params?, config?)`\n\nMake a direct HTTP request.\n\n```ts\nconst data = await api.request({ userId: 123 });\n```\n\n##### `useQuery(params?, options?)`\n\nReact Query hook for fetching data.\n\n```ts\nconst { data, isLoading, error } = api.useQuery(\n  { page: 1 },\n  {\n    staleTime: 60000,\n  }\n);\n```\n\n##### `useMutation(options?)`\n\nReact Query hook for mutations.\n\n```ts\nconst mutation = api.useMutation({\n  onSuccess: (data) => {\n    console.log('Success:', data);\n  },\n});\n\nmutation.mutate({ name: 'John' });\n```\n\n### ReactQueryProvider\n\nLegacy provider component (use LibraQueryProvider instead for full functionality).\n\n```tsx\nimport { ReactQueryProvider } from 'libra-query/provider';\n\n<ReactQueryProvider>{children}</ReactQueryProvider>\n```\n\n### Default Configuration\n\nThe default configuration includes:\n\n- **Stale Time**: 5 minutes\n- **Retry**: 1 retry on failure\n- **Refetch on Window Focus**: Disabled\n- **Refetch on Reconnect**: Enabled\n\n### Custom Request Function\n\nYou can create custom request instances:\n\n```ts\nimport { getRequestFn } from 'libra-query';\nimport { RequestBuilder } from 'libra-query/builder';\n\nconst customRequest = getRequestFn({\n  prefix: 'https://api.example.com',\n  requestInterceptor: (config) => {\n    // Modify request config\n    config.headers = {\n      ...config.headers,\n      'X-Custom-Header': 'value',\n    };\n    return config;\n  },\n  silence: false,\n});\n\nconst api = new RequestBuilder({\n  url: '/endpoint',\n  requestFn: customRequest,\n});\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-21c86529345b422309c42940db2f6512"}