{"_id":"@adaskothebeast/http-params-processor-fetch","_rev":"4-e9e3bc4e6ebff67c5a0fe6d5260413e5","name":"@adaskothebeast/http-params-processor-fetch","dist-tags":{"latest":"12.0.0"},"versions":{"10.0.0":{"name":"@adaskothebeast/http-params-processor-fetch","version":"10.0.0","keywords":["fetch","params","query","url","URLSearchParams","http","serialization","typescript"],"author":{"name":"Adam Pluciński","email":"adaskothebeast@gmail.com"},"license":"MIT","_id":"@adaskothebeast/http-params-processor-fetch@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":"b080c811d1a386e22430040896dc99e68b9184d9","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-fetch/-/http-params-processor-fetch-10.0.0.tgz","fileCount":11,"integrity":"sha512-80rVeslAWgYRf0VahMH8EQdF6FRq1k/jrgG3fK7IM6f4/2LlMz/7V2N0sFoNnqS+QNJhkW7Vx54jUHzKU8aoSA==","signatures":[{"sig":"MEYCIQC4WBu+sRscPnd0JbvHYF71cRfaFIIehpTUeRTElF8aRQIhAJoCwXJqWHxhDh7yWYZ6cso6cWF6DTVAOziWyweQWJpE","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44152},"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":"Fetch API adapter for params-processor - serialize complex objects to URLSearchParams","directories":{},"sideEffects":false,"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"peerDependencies":{"@adaskothebeast/http-params-processor-core":"^10.0.0"},"_npmOperationalInternal":{"tmp":"tmp/http-params-processor-fetch_10.0.0_1768077024117_0.33873941568419874","host":"s3://npm-registry-packages-npm-production"}},"11.0.0":{"name":"@adaskothebeast/http-params-processor-fetch","version":"11.0.0","author":{"url":"https://github.com/adaskothebeast","name":"Adam Pluciński","email":"adaskothebeast@gmail.com"},"license":"MIT","_id":"@adaskothebeast/http-params-processor-fetch@11.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":"7766fb8e2ee8eed31fffc8869c10611e771ddc40","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-fetch/-/http-params-processor-fetch-11.0.0.tgz","fileCount":8,"integrity":"sha512-M5aRnj6ax5lkyOvmXnIITibpdWHN1LtNatKQe6CG1mitbzD0qux1ZL4yuOGAgc6nTQkpA1/7feMiE9WLYAY3SQ==","signatures":[{"sig":"MEQCICkR9/aPKZXdxmvxGlh5uYjhbGhzd+HkJcsb0zfFX596AiBICLNqX8DVQyKxU15ir7l1YP58Q9tg9GeKkfWFE1Bkfg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@adaskothebeast%2fhttp-params-processor-fetch@11.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":56480},"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:c854a749-e418-4810-b761-400dd5e62783"}},"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-fetch_11.0.0_1768758176454_0.6031993638233561","host":"s3://npm-registry-packages-npm-production"}},"11.1.0":{"name":"@adaskothebeast/http-params-processor-fetch","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-fetch@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":"143280348f11029284e5b81f9eba1eb8a093116c","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-fetch/-/http-params-processor-fetch-11.1.0.tgz","fileCount":8,"integrity":"sha512-EpP5OSM526Sa/CT80N5IdixP5iLwyRf1U0om24rkoJNdM0PRL4tqcl5csOgm9I9StSJ7QqwLQVoZ07O5dNEv8w==","signatures":[{"sig":"MEYCIQC/8VwJVi7v4vtsvNV2jKNvnFbaBmUpfDtunC2jHUFkqgIhAMk4diW82mPZNut21lYcCTnca9rp3bG6EVxwV9Vw5/f4","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@adaskothebeast%2fhttp-params-processor-fetch@11.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":56480},"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:c854a749-e418-4810-b761-400dd5e62783"}},"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-fetch_11.1.0_1768758914485_0.9709080048050445","host":"s3://npm-registry-packages-npm-production"}},"12.0.0":{"name":"@adaskothebeast/http-params-processor-fetch","version":"12.0.0","description":"fetch helpers that build URLs and URLSearchParams from deeply nested query parameter objects.","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","fetch","url-search-params","url-builder"],"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"},"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-fetch@12.0.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-Ex9hSsrwXYiJXO2wUYgNeKya+yLeGLzZI2RBQ/EDZ4jY4pFdXXKJB1go+10PcbDjlCRJqU1yUY99sk290xn/Tw==","shasum":"06fe615489f3dbac07415485c74663752bc5caa5","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-fetch/-/http-params-processor-fetch-12.0.0.tgz","fileCount":9,"unpackedSize":32017,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHtXaTnfSP0sDI2vtGcJnTyR5+8B6nk7tPhxoD1kfIzoAiBaeAFunqajZMNfYPclpWMLBmX77G6GsultGlPu0mo5QQ=="}]},"_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-fetch_12.0.0_1785235896826_0.8536982242292992"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-10T20:30:24.040Z","modified":"2026-07-28T10:51:37.177Z","10.0.0":"2026-01-10T20:30:24.267Z","11.0.0":"2026-01-18T17:42:56.578Z","11.1.0":"2026-01-18T17:55:14.679Z","12.0.0":"2026-07-28T10:51:36.962Z"},"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-fetch\n\n**The `fetch` adapter of [HttpParamsProcessor](https://github.com/AdaskoTheBeAsT/HttpParamsProcessor): URL builders and `URLSearchParams` factories for deeply nested query objects.**\n\n[![npm](https://img.shields.io/npm/v/%40adaskothebeast%2Fhttp-params-processor-fetch?color=cb3837&logo=npm)](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-fetch)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nNo runtime dependency beyond `core`; it only uses the platform `URL` and `URLSearchParams`. ESM only (`\"type\": \"module\"`). `sideEffects: false`.\n\n---\n\n## 📦 Install\n\n```bash\nnpm i @adaskothebeast/http-params-processor-fetch @adaskothebeast/http-params-processor-core\n```\n\nPeer dependencies: `@adaskothebeast/http-params-processor-core ^12.0.0`. Nothing else - `fetch` is part of the platform.\n\n---\n\n## 🎯 What it does\n\n`FetchParamsProcessor` flattens a nested object into query parameters and then hands you the exact shape you need at the call site:\n\n| You need                          | Method              |\n| --------------------------------- | ------------------- |\n| a ready-to-fetch URL string       | `buildUrl`          |\n| a `URL` instance                  | `buildUrlObject`    |\n| a query string without `?`        | `toQueryString`     |\n| a `URLSearchParams` body          | `toURLSearchParams` |\n| to extend params you already have | `appendTo`          |\n\n---\n\n## 🧰 API\n\n### `FetchParamsProcessor`\n\n| Member                                         | Returns                | Notes                                                       |\n| ---------------------------------------------- | ---------------------- | ----------------------------------------------------------- |\n| `new FetchParamsProcessor(config?)`            | -                      | `config` sets instance-wide defaults                        |\n| `createFetchParamsProcessor(config?)`          | `FetchParamsProcessor` | Factory helper, identical to the constructor                |\n| `toURLSearchParams(key, obj, options?)`        | `URLSearchParams`      | Built with `append`, so repeated keys survive               |\n| `toQueryString(key, obj, options?)`            | `string`               | `encodeURIComponent`-encoded, **no** leading `?`            |\n| `buildUrl(baseUrl, key, obj, options?)`        | `string`               | Adds `?` or `&` depending on the base URL                   |\n| `buildUrlObject(baseUrl, key, obj, options?)`  | `URL`                  | Accepts a `string` or a `URL`, keeps existing search params |\n| `appendTo(existingParams, key, obj, options?)` | `URLSearchParams`      | Mutates and returns the **same** instance you passed in     |\n| `coreProcessor`                                | `ParamsProcessor`      | Getter for the underlying core instance                     |\n\n### Standalone helpers\n\n| Function                                    | Returns           |\n| ------------------------------------------- | ----------------- |\n| `buildFetchUrl(baseUrl, key, obj, config?)` | `string`          |\n| `toFetchParams(key, obj, config?)`          | `URLSearchParams` |\n\nBoth create a throwaway processor per call, so prefer an instance in hot paths.\n\n### Types\n\n`FetchParamsProcessorConfig` (`{ keyFormatter?, valueConverters? }`). Per-call `options` use the core `ParamsProcessorOptions`.\n\n### Re-exports from `core`\n\nValues: `ValueConverter`, `createValueConverter`, `DefaultKeyFormattingStrategy`, `DefaultDateValueFromStrategy`, `DefaultDateValueToStrategy`, `DefaultPrimitiveValueToStrategy`.\nTypes: `ParamsProcessorOptions`, `ProcessableInput`, `ParamsEntry`, `IKeyFormattingStrategy`, `IValueConverter`, `IValueFromStrategy`, `IValueToStrategy`, `DurationComponents`, `PeriodComponents`.\n\n---\n\n## ⚡ Usage\n\n```ts\nimport { createFetchParamsProcessor } from '@adaskothebeast/http-params-processor-fetch';\n\nconst processor = createFetchParamsProcessor();\n\nconst url = processor.buildUrl('/api/products', 'filter', {\n  category: 'electronics',\n  price: { min: 100, max: 500 },\n});\n// /api/products?filter.category=electronics&filter.price.min=100&filter.price.max=500\n\nconst res = await fetch(url);\n```\n\nAs a form encoded body:\n\n```ts\nconst body = processor.toURLSearchParams('filter', { status: 'active' });\n\nawait fetch('/api/search', { method: 'POST', body });\n```\n\nMerging into pagination params you already built:\n\n```ts\nconst params = new URLSearchParams({ page: '1', size: '10' });\nprocessor.appendTo(params, 'filter', { status: 'active' });\n// page=1&size=10&filter.status=active\n\nawait fetch(`/api/data?${params}`);\n```\n\nAbsolute URLs as objects, and the one-liners:\n\n```ts\nimport { buildFetchUrl, toFetchParams } from '@adaskothebeast/http-params-processor-fetch';\n\nconst target = processor.buildUrlObject('https://api.example.com/products', 'filter', { category: 'electronics' });\nawait fetch(target);\n\nawait fetch(buildFetchUrl('/api/products', 'filter', { inStock: true }));\nawait fetch(`/api/data?${toFetchParams('filter', { status: 'active' })}`);\n```\n\n---\n\n## 🎛️ Options and configuration\n\n```ts\nimport { createFetchParamsProcessor, createValueConverter } from '@adaskothebeast/http-params-processor-fetch';\nimport { FlatKeyFormattingStrategy } from '@adaskothebeast/http-params-processor-key-flat';\n\nconst processor = createFetchParamsProcessor({\n  keyFormatter: new FlatKeyFormattingStrategy('_'),\n});\n\nprocessor.toQueryString('filter', { status: 'active' });\n// filter_status=active\n```\n\nEvery method also takes a per-call `options` argument (`{ keyFormatter?, valueConverters? }`) that overrides the instance defaults for that call. `buildFetchUrl` and `toFetchParams` accept the same shape as their last argument instead, because they construct the processor for you.\n\nProviding `valueConverters` replaces the core defaults, so re-register a `Date` converter if you still pass native dates.\n\n---\n\n## 📤 Output examples\n\n```ts\nconst processor = new FetchParamsProcessor();\n\nprocessor.toQueryString('filter', { name: 'John Doe', status: 'active' });\n// filter.name=John%20Doe&filter.status=active\n\nprocessor.toQueryString('filter', { query: 'a=b&c=d' });\n// filter.query=a%3Db%26c%3Dd\n\nprocessor.buildUrl('/api/products', 'filter', { status: 'active' });\n// /api/products?filter.status=active\n\nprocessor.buildUrl('/api/products?page=1', 'filter', { status: 'active' });\n// /api/products?page=1&filter.status=active\n\nprocessor.buildUrl('/api/products', 'filter', { a: null, b: undefined });\n// /api/products\n\nprocessor.toURLSearchParams('items', ['a', 'b', 'c']).get('items[1]');\n// 'b'\n\nprocessor.toURLSearchParams('filter', { createdAt: new Date('2024-01-01T00:00:00.000Z') }).get('filter.createdAt');\n// '2024-01-01T00:00:00.000Z'\n```\n\n---\n\n## ⚠️ Edge cases\n\n- `buildUrl` returns the base URL **unchanged** when the object produces no entries (all `null`/`undefined`, or an empty object/array), so you never get a dangling `?`.\n- The separator is chosen with `baseUrl.includes('?')`. A base URL that already ends in `?` or `&` will therefore get another `&` appended.\n- `buildUrlObject` goes through `new URL(...)`, which **requires an absolute URL**; relative paths like `/api/products` throw. Use `buildUrl` for relative URLs.\n- `appendTo` mutates the instance you pass in and returns that very instance, and it always **appends**, so calling it twice with the same key duplicates the entries.\n- `toQueryString` encodes with `encodeURIComponent` (space becomes `%20`), while `String(urlSearchParams)` encodes space as `+`. Both are valid in a query string, but the two helpers do not produce byte-identical output.\n- Values coming out of `toURLSearchParams` are **not** double-encoded: `get()` returns the decoded value (`2024-01-01T00:00:00.000Z`).\n- `null` and `undefined` are skipped at every depth, `$type` is ignored, and circular references throw `Error: Circular reference detected at key: <key>`.\n- Unmatched values fall back to `String(value)`.\n- Nothing here calls `fetch`; you stay in control of method, headers, credentials and error handling.\n\n---\n\n## 🔗 Related packages\n\n- Engine: [`-core`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-core)\n- Other adapters: [`-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), [`-react-tanstack-query`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-react-tanstack-query), [`-react-swr`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-react-swr)\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":"fetch helpers that build URLs and URLSearchParams from deeply nested query parameter objects.","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","fetch","url-search-params","url-builder"]}