{"_id":"@adaskothebeast/http-params-processor-react-swr","_rev":"3-87d022ad3693e71155ec0936e8638e5a","name":"@adaskothebeast/http-params-processor-react-swr","dist-tags":{"latest":"12.0.0"},"versions":{"10.0.0":{"name":"@adaskothebeast/http-params-processor-react-swr","version":"10.0.0","keywords":["swr","react","params","query","url","http","serialization","typescript","vercel"],"author":{"name":"Adam Pluciński","email":"adaskothebeast@gmail.com"},"license":"MIT","_id":"@adaskothebeast/http-params-processor-react-swr@10.0.0","maintainers":[{"name":"adasko","email":"adaskothebeast@gmail.com"}],"homepage":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor","bugs":{"url":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor/issues"},"dist":{"shasum":"473277f67ad651aaf3436aa192e3dd56930bf308","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-react-swr/-/http-params-processor-react-swr-10.0.0.tgz","fileCount":9,"integrity":"sha512-9/YfW8DbegK6Vdnti03dbKbPiteMdh5mMVgTEo54MUERPSHqc64idbQ8YN9y9TzNLtEasXddOiuzzxiZ8yzY0Q==","signatures":[{"sig":"MEUCIQDnEaAvfwoT3P1LzDju5k2WQ02S+UtINuKrsDs/T0MyOAIgKnvmay5Snmf6PZkyPbdp08AtjM+LNvH0Tp7ZBopaH+c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37642},"main":"./src/index.js","type":"commonjs","types":"./src/index.d.ts","module":"./src/index.js","exports":{".":{"types":"./src/index.d.ts","import":"./src/index.js","require":"./src/index.js"}},"gitHead":"1e61d6323f67038b9af916e4f3d263a73fe76497","_npmUser":{"name":"adasko","email":"adaskothebeast@gmail.com"},"repository":{"url":"git+https://github.com/AdaskoTheBeAsT/HttpParamsProcessor.git","type":"git"},"_npmVersion":"11.6.2","description":"SWR integration for http-params-processor - serialize complex objects to query parameters","directories":{},"sideEffects":false,"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"peerDependencies":{"swr":"^2.0.0","react":"^18.0.0 || ^19.0.0","@adaskothebeast/http-params-processor-core":"^10.0.0"},"_npmOperationalInternal":{"tmp":"tmp/http-params-processor-react-swr_10.0.0_1768077069861_0.6333396795237818","host":"s3://npm-registry-packages-npm-production"}},"11.1.0":{"name":"@adaskothebeast/http-params-processor-react-swr","version":"11.1.0","author":{"url":"https://github.com/adaskothebeast","name":"Adam Pluciński","email":"adaskothebeast@gmail.com"},"license":"MIT","_id":"@adaskothebeast/http-params-processor-react-swr@11.1.0","maintainers":[{"name":"adasko","email":"adaskothebeast@gmail.com"}],"homepage":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor","bugs":{"url":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor/issues"},"dist":{"shasum":"8b3f09ab6a3e366c65ac8bf9dfaae98f0231a620","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-react-swr/-/http-params-processor-react-swr-11.1.0.tgz","fileCount":8,"integrity":"sha512-TRwzoeYXxW7ixuAIRnGI28CKK+F1fBOI4cUj1aFsMxdv7ybOosyvbeJQne+nVv+uAIAGmTDV8RroutlpccV/CQ==","signatures":[{"sig":"MEQCIH0HgbZ20E4v1KA6PgLGzhZ5V7W+hUjmF8pYj0e2yI+rAiAw83rSlgkl+3xxFgEz3Bb97g+MirBdDzPTV96QRVoDAw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@adaskothebeast%2fhttp-params-processor-react-swr@11.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":50295},"main":"./index.cjs","type":"module","types":"./index.d.ts","module":"./index.js","exports":{".":{"types":"./index.d.ts","import":"./index.js","default":"./index.js","require":"./index.cjs"},"./package.json":"./package.json"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:01d3102b-e9ed-4032-8853-fe59e4c25c78"}},"repository":{"url":"git+https://github.com/AdaskoTheBeAsT/HttpParamsProcessor.git","type":"git"},"_npmVersion":"11.6.2","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/http-params-processor-react-swr_11.1.0_1768758917003_0.1964504578393933","host":"s3://npm-registry-packages-npm-production"}},"12.0.0":{"name":"@adaskothebeast/http-params-processor-react-swr","version":"12.0.0","description":"SWR hooks, keys and fetchers for React requests with deeply nested query parameter objects.","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","react","swr","hooks","data-fetching"],"license":"MIT","author":{"name":"Adam Pluciński","email":"adaskothebeast@gmail.com","url":"https://github.com/adaskothebeast"},"repository":{"type":"git","url":"git+https://github.com/AdaskoTheBeAsT/HttpParamsProcessor.git"},"bugs":{"url":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor/issues"},"homepage":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor","type":"module","sideEffects":false,"main":"./index.cjs","module":"./index.js","types":"./index.d.ts","peerDependencies":{"@adaskothebeast/http-params-processor-core":"^12.0.0","swr":"^2.3.8"},"exports":{".":{"types":"./index.d.ts","import":"./index.js","default":"./index.js","require":"./index.cjs"},"./package.json":"./package.json"},"gitHead":"73d31a6c26a6f2819f6c98aabb36659532e4cdd0","_id":"@adaskothebeast/http-params-processor-react-swr@12.0.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-6lIFivK3fwZY177tVn01cCJ4qC2N2DlydenqSSpG1Op3gA8uAVuXth3C9ILhc+ovUZkdQrn5DFaJuwVFfoaK3w==","shasum":"3af7204c77166d301039168228ed3b537b1c4b1c","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-react-swr/-/http-params-processor-react-swr-12.0.0.tgz","fileCount":9,"unpackedSize":24418,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCSgrDrwbO5P9fBUsg7MpC9rqgOczGhC3Ut8/TFt8MaxgIhAPTHJtYo8iQSoXoy+wysigKOQ5J2bgNN3b9rwdmIuvG0"}]},"_npmUser":{"name":"adasko","email":"adaskothebeast@gmail.com"},"directories":{},"maintainers":[{"name":"adasko","email":"adaskothebeast@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/http-params-processor-react-swr_12.0.0_1785236043988_0.8115152315575462"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-10T20:31:09.740Z","modified":"2026-07-28T10:54:04.343Z","10.0.0":"2026-01-10T20:31:10.012Z","11.1.0":"2026-01-18T17:55:17.151Z","12.0.0":"2026-07-28T10:54:04.121Z"},"bugs":{"url":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor/issues"},"author":{"name":"Adam Pluciński","email":"adaskothebeast@gmail.com","url":"https://github.com/adaskothebeast"},"license":"MIT","homepage":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor","repository":{"type":"git","url":"git+https://github.com/AdaskoTheBeAsT/HttpParamsProcessor.git"},"maintainers":[{"name":"adasko","email":"adaskothebeast@gmail.com"}],"readme":"# ⚛️ @adaskothebeast/http-params-processor-react-swr\n\n**The SWR adapter of [HttpParamsProcessor](https://github.com/AdaskoTheBeAsT/HttpParamsProcessor): the flattened URL becomes the SWR key, so nested params cache and revalidate correctly.**\n\n[![npm](https://img.shields.io/npm/v/%40adaskothebeast%2Fhttp-params-processor-react-swr?color=cb3837&logo=npm)](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-react-swr)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nNo runtime dependency beyond `core` and SWR; requests use the platform `fetch`. ESM only (`\"type\": \"module\"`). `sideEffects: false`.\n\n---\n\n## 📦 Install\n\n```bash\nnpm i @adaskothebeast/http-params-processor-react-swr @adaskothebeast/http-params-processor-core\n```\n\nPeer dependencies: `@adaskothebeast/http-params-processor-core ^12.0.0`, `swr ^2.3.8`.\n\n---\n\n## 🎯 What it does\n\n`useSWRWithParams` flattens `params` under `paramsKey`, appends the query string to `url`, and passes that **complete URL string as the SWR key**:\n\n```text\nurl:      /api/users\nkey:      /api/users?filter.status=active\nfetcher:  GET on that key\n```\n\nBecause the key is a string derived from the serialized params, cache identity is exact and stable across renders with no memoization needed.\n\n---\n\n## 🧰 API\n\n| Export                                                          | Returns                           | Notes                                                    |\n| --------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------- |\n| `useSWRWithParams<TData, TError>(options)`                      | `SWRResponse<TData, TError>`      | Hook; wraps `useSWR(fullUrl, fetcher, swrOptions)`       |\n| `createSWRKey(url, paramsKey, params, processorOptions?)`       | `Key`                             | The same string key, for manual `useSWR`/`mutate` calls  |\n| `createFetcherWithParams<TData>(options)`                       | `(url: string) => Promise<TData>` | A fetcher that appends the params to the URL it receives |\n| `buildUrlWithParams(url, paramsKey, params, processorOptions?)` | `string`                          | The URL builder used internally                          |\n| `getProcessedUrl(url, paramsKey, params, processorOptions?)`    | `string`                          | Alias of `buildUrlWithParams`, handy for debugging       |\n\n### Options\n\n`UseSWRWithParamsOptions<TData, TError>`:\n\n| Option             | Type                              | Default             |\n| ------------------ | --------------------------------- | ------------------- |\n| `url`              | `string`                          | required            |\n| `paramsKey`        | `string`                          | required            |\n| `params`           | `Record<string, unknown>`         | required            |\n| `processorOptions` | `SWRParamsProcessorOptions`       | core defaults       |\n| `swrOptions`       | `SWRConfiguration<TData, TError>` | SWR defaults        |\n| `fetchFn`          | `typeof fetch`                    | global `fetch`      |\n| `fetchOptions`     | `RequestInit`                     | `{ method: 'GET' }` |\n\n`SWRParamsProcessorOptions` is `{ keyFormatter?, valueConverters? }`.\n\n`createFetcherWithParams` takes `{ paramsKey, params, processorOptions?, fetchFn?, fetchOptions? }`.\n\n---\n\n## ⚡ Usage\n\n```tsx\nimport { useSWRWithParams } from '@adaskothebeast/http-params-processor-react-swr';\n\nfunction Users() {\n  const { data, error, isLoading, mutate } = useSWRWithParams<User[]>({\n    url: '/api/users',\n    paramsKey: 'filter',\n    params: {\n      status: 'active',\n      roles: ['admin', 'user'],\n      dateRange: { from: new Date('2024-01-01'), to: new Date('2024-12-31') },\n    },\n    swrOptions: { revalidateOnFocus: false, keepPreviousData: true },\n  });\n\n  if (isLoading) return <Spinner />;\n  if (error) return <Error error={error} />;\n  return <UserList users={data ?? []} onRefresh={() => mutate()} />;\n}\n```\n\nWiring SWR yourself, for example to support conditional fetching:\n\n```ts\nimport { createSWRKey } from '@adaskothebeast/http-params-processor-react-swr';\nimport useSWR from 'swr';\n\nconst key = enabled ? createSWRKey('/api/users', 'filter', { status }) : null;\n\nconst { data } = useSWR<User[]>(key, (url: string) => fetch(url).then((r) => r.json()));\n```\n\nReusing the fetcher with a **base** URL as the key:\n\n```ts\nimport { createFetcherWithParams } from '@adaskothebeast/http-params-processor-react-swr';\nimport useSWR from 'swr';\n\nconst fetcher = createFetcherWithParams<User[]>({\n  paramsKey: 'filter',\n  params: { status: 'active' },\n  fetchOptions: { credentials: 'include' },\n});\n\nconst { data } = useSWR<User[]>('/api/users', fetcher);\n```\n\nInvalidating a specific entry:\n\n```ts\nimport { mutate } from 'swr';\n\nawait mutate(createSWRKey('/api/users', 'filter', { status: 'active' }));\n```\n\n---\n\n## 🎛️ Options and configuration\n\n```ts\nimport { FlatKeyFormattingStrategy } from '@adaskothebeast/http-params-processor-key-flat';\n\nuseSWRWithParams<User[]>({\n  url: '/api/users',\n  paramsKey: 'filter',\n  params: { user: { name: 'John' } },\n  processorOptions: { keyFormatter: new FlatKeyFormattingStrategy('_') },\n});\n// /api/users?filter_user_name=John\n```\n\n`processorOptions` is per call; there is no provider or global registry. A fresh `ParamsProcessor` is created inside `buildUrlWithParams` each time, so the options object is the only place configuration lives. `swrOptions` is forwarded to `useSWR` untouched, so all of SWR's configuration (dedupe interval, refresh interval, `fallbackData`, `onError`, …) applies.\n\nProviding `valueConverters` replaces the core defaults, so include a `Date` converter if you still pass native dates.\n\n---\n\n## 📤 Output examples\n\n```ts\nbuildUrlWithParams('/api/users', 'filter', { status: 'active', count: 10 });\n// /api/users?filter.status=active&filter.count=10\n\nbuildUrlWithParams('/api/users', 'filter', { user: { name: 'John', age: 30 } });\n// /api/users?filter.user.name=John&filter.user.age=30\n\nbuildUrlWithParams('/api/users', 'filter', { roles: ['admin', 'user'] });\n// /api/users?filter.roles%5B0%5D=admin&filter.roles%5B1%5D=user\n\nbuildUrlWithParams('/api/users', 'filter', {\n  createdAt: new Date('2024-01-01T00:00:00.000Z'),\n});\n// /api/users?filter.createdAt=2024-01-01T00%3A00%3A00.000Z\n\nbuildUrlWithParams('/api/users?page=1', 'filter', { status: 'active' });\n// /api/users?page=1&filter.status=active\n\nbuildUrlWithParams('/api/users', 'filter', { a: null, b: undefined });\n// /api/users\n\ncreateSWRKey('/api/users', 'filter', { status: 'active' });\n// '/api/users?filter.status=active'\n```\n\n---\n\n## ⚠️ Edge cases\n\n- The hook's key is a **string**, never `null`, so `useSWRWithParams` always fetches. For conditional fetching, build the key with `createSWRKey` and pass `null` to `useSWR` yourself, as shown above.\n- Do **not** feed a `createSWRKey` result into `createFetcherWithParams`. That fetcher appends the params again to whatever URL it receives, and since the URL already contains a `?`, you would get the parameters twice. Pair the fetcher with the plain base URL.\n- Non-`ok` responses throw `Error: HTTP error! status: <status>`; the body is not read, so parse errors yourself through `fetchFn` if you need details.\n- The response is always parsed with `response.json()`. Endpoints returning `204 No Content` or text will reject.\n- `fetchOptions` is spread **after** `method: 'GET'`, so passing `method` there overrides the verb (params still go in the query string, not the body).\n- Keys are compared as strings, so two params objects that serialize identically share one cache entry, while property reordering produces a different key and therefore a separate entry.\n- `buildUrlWithParams` returns the base URL unchanged when nothing is produced, and picks `&` over `?` when the URL already contains a `?`.\n- `null`/`undefined` params are skipped, `$type` is ignored, and circular references throw `Error: Circular reference detected at key: <key>` while the URL is being built (during render, since the key is computed eagerly).\n- Keys are encoded, so bracket characters appear as `%5B`/`%5D` in the final URL and in the SWR key.\n\n---\n\n## 🔗 Related packages\n\n- TanStack Query instead of SWR: [`-react-tanstack-query`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-react-tanstack-query)\n- Engine: [`-core`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-core)\n- Other adapters: [`-fetch`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-fetch), [`-axios`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-axios), [`-angular`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-angular), [`-angular-resource`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-angular-resource)\n- Key formatting: `-key-bracket-notation`, `-key-rails`, `-key-flat`, `-key-custom-delimiter`, `-key-json`\n- Values: `-value-from-*` and `-value-to-*`\n\nFull matrix and recipes: [main README](https://github.com/AdaskoTheBeAsT/HttpParamsProcessor#readme).\n\n---\n\n## 📄 License\n\n[MIT](./LICENSE) © Adam Pluciński\n","readmeFilename":"README.md","description":"SWR hooks, keys and fetchers for React requests with deeply nested query parameter objects.","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","react","swr","hooks","data-fetching"]}