{"_id":"@adaskothebeast/http-params-processor-key-json","_rev":"4-321cb23bbbcdc5d75c6656f4f9c2f754","name":"@adaskothebeast/http-params-processor-key-json","dist-tags":{"latest":"12.0.0"},"versions":{"10.0.0":{"name":"@adaskothebeast/http-params-processor-key-json","version":"10.0.0","_id":"@adaskothebeast/http-params-processor-key-json@10.0.0","maintainers":[{"name":"adasko","email":"adaskothebeast@gmail.com"}],"dist":{"shasum":"21659f458cc97880598fbe2ca2e13f5b7d1a198d","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-key-json/-/http-params-processor-key-json-10.0.0.tgz","fileCount":15,"integrity":"sha512-fSYUTsUWsZ7XA4VhbqdwCwDM3Zk3o5GmLrblRg4azFhccYbi5SG3W4WNpeL+2Bv7/N7a8uhvxZmaVn5lQph8oA==","signatures":[{"sig":"MEUCIEGyzeuQl7m3/LEGSp/vhhyib5YsBIhpkYJnLt4TTezNAiEAofLLLvwKHoZI4v95yOf/OBB4krab+5GVNvbXMOp68lE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28273},"main":"./src/index.js","type":"commonjs","types":"./src/index.d.ts","gitHead":"1e61d6323f67038b9af916e4f3d263a73fe76497","_npmUser":{"name":"adasko","email":"adaskothebeast@gmail.com"},"_npmVersion":"11.6.2","description":"> Transform complex TypeScript objects into query parameters for Angular, Axios, Fetch, and more","directories":{},"sideEffects":false,"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"peerDependencies":{"@adaskothebeast/http-params-processor-core":"^10.0.0"},"_npmOperationalInternal":{"tmp":"tmp/http-params-processor-key-json_10.0.0_1768077156801_0.8213455001291528","host":"s3://npm-registry-packages-npm-production"}},"11.0.0":{"name":"@adaskothebeast/http-params-processor-key-json","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-key-json@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":"1d073d8830fa2bd1ec13d0a1c2f376e7bfe0cbb8","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-key-json/-/http-params-processor-key-json-11.0.0.tgz","fileCount":8,"integrity":"sha512-9TV2cvLyIXo76aXQE23gCPo5prSbaDc5FNgn8+b+iNhzTw0sE7+dBPS+w4dI+iIelqC+poANLmHbZx0G58Z09Q==","signatures":[{"sig":"MEUCIBdG1TDgz78YlwA9UgBDm9q2dJDGRxVw7+qJ1shrI0/XAiEA3HLUmL9G3jyn0SaXKEQNZBc2KpeSvpMsEmPVahoPdnU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@adaskothebeast%2fhttp-params-processor-key-json@11.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":39357},"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:64cc706b-29ab-443f-805f-b075369bedad"}},"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-key-json_11.0.0_1768758175324_0.6910055450031969","host":"s3://npm-registry-packages-npm-production"}},"11.1.0":{"name":"@adaskothebeast/http-params-processor-key-json","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-key-json@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":"71e33b06e38b8820e0b1192095726a3ea262a174","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-key-json/-/http-params-processor-key-json-11.1.0.tgz","fileCount":8,"integrity":"sha512-9Kzc5K57LgW95dKN/Qu3aJwmFXaFwzrBV0UNfO+iJM93GV6+4rTF4Q6v3evWJJP9dsehhgNP1vf2JYiQk4QmqA==","signatures":[{"sig":"MEQCIAZbL7jh7QB5xfmHoTOT4sosFKrnecWr2Kk2bBeIlTPbAiBZfeCYTBN4i944vJDWdgb6B7UAy+mbk4I6Xk+TGsmnQA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@adaskothebeast%2fhttp-params-processor-key-json@11.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":39357},"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:64cc706b-29ab-443f-805f-b075369bedad"}},"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-key-json_11.1.0_1768758917329_0.0657468609719929","host":"s3://npm-registry-packages-npm-production"}},"12.0.0":{"name":"@adaskothebeast/http-params-processor-key-json","version":"12.0.0","description":"JSON key formatting strategy for HttpParamsProcessor that serializes whole objects into a single JSON query parameter.","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","key-formatting","json"],"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-key-json@12.0.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-QwEDlYY0nEqyH5CAmjAUnx0R/zZgRZWymj/TjK+t2vjz/ItIqbZC0HmoK56da66JSUpsrmH3xN6D/4B3SFTPRQ==","shasum":"0c2096dae2c9c8bd4ee89bb0e920e679acf9d1b0","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-key-json/-/http-params-processor-key-json-12.0.0.tgz","fileCount":9,"unpackedSize":13880,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICaE1dtWRBM3TbTwI9vjp+DzwcVFlZ4+AYKMYDbB4WKRAiEAjwnP6mvfQLudYFP4JKS7XtObz5xZoRKjI1xDjDX3/ZY="}]},"_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-key-json_12.0.0_1785235989098_0.2922642493247545"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-10T20:32:36.695Z","modified":"2026-07-28T10:53:09.449Z","10.0.0":"2026-01-10T20:32:36.956Z","11.0.0":"2026-01-18T17:42:55.544Z","11.1.0":"2026-01-18T17:55:17.546Z","12.0.0":"2026-07-28T10:53:09.243Z"},"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-key-json\n\n**One parameter, one JSON string: [HttpParamsProcessor](https://github.com/AdaskoTheBeAsT/HttpParamsProcessor) stops flattening and sends `filter={\"status\":\"active\",\"count\":5}` instead.**\n\n[![npm](https://img.shields.io/npm/v/%40adaskothebeast%2Fhttp-params-processor-key-json?color=cb3837&logo=npm)](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-key-json)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nNo runtime dependency beyond `core` (its only peer dependency, `^12.0.0`). ESM + CJS. `sideEffects: false`.\n\n---\n\n## 📦 Install\n\n```bash\nnpm i @adaskothebeast/http-params-processor-key-json @adaskothebeast/http-params-processor-core\n```\n\n---\n\n## 🎯 What it does\n\nEvery other key strategy changes how nested keys are **spelled**. This one opts out of flattening entirely: it implements the optional `transformComplexObject` hook of `IKeyFormattingStrategy`, and because that hook returns a non-`null` appender, `ParamsProcessor` short-circuits its recursion and emits a single pair whose value is `JSON.stringify(obj)`.\n\n| Input                                        | `DefaultKeyFormattingStrategy` (core) | `JsonKeyFormattingStrategy`            |\n| -------------------------------------------- | ------------------------------------- | -------------------------------------- |\n| `{ status: 'active', count: 5 }` at `filter` | `filter.status`, `filter.count`       | `filter={\"status\":\"active\",\"count\":5}` |\n| `['a', 'b', 'c']` at `tags`                  | `tags[0]`, `tags[1]`, `tags[2]`       | `tags=[\"a\",\"b\",\"c\"]`                   |\n\nUse it when the endpoint expects a JSON blob in the query string (search DSLs, GraphQL-ish `variables`, OData-like `$filter` replacements, or your own `?filter=` convention) and you do not want to call `JSON.stringify` by hand at every call site.\n\n---\n\n## 🧰 API\n\n### `JsonKeyFormattingStrategy`\n\nImplements `IKeyFormattingStrategy` from `core`.\n\n| Member                                     | Returns            | Result                                             |\n| ------------------------------------------ | ------------------ | -------------------------------------------------- |\n| `new JsonKeyFormattingStrategy()`          | -                  | No constructor options                             |\n| `formatObjectKey(parentKey, propertyKey)`  | `string`           | `` `${parentKey}.${propertyKey}` `` (dot notation) |\n| `formatArrayKey(parentKey, index)`         | `string`           | `` `${parentKey}[${index}]` ``                     |\n| `transformComplexObject(params, key, obj)` | `T` (never `null`) | `params.append(key, JSON.stringify(obj))`          |\n\n`params` is an `IParamsAppender` (a minimal `append(key, value)` sink supplied by `core`); `obj` is `Record<string, unknown> | unknown[]`.\n\nBecause `transformComplexObject` never returns `null`, `formatObjectKey` and `formatArrayKey` are effectively unreachable when the strategy is driven by `ParamsProcessor` - they exist so the class satisfies the interface (and mirror the core defaults if you call them directly).\n\n---\n\n## ⚡ Usage\n\n```ts\nimport { ParamsProcessor } from '@adaskothebeast/http-params-processor-core';\nimport { JsonKeyFormattingStrategy } from '@adaskothebeast/http-params-processor-key-json';\n\nconst processor = new ParamsProcessor({\n  keyFormatter: new JsonKeyFormattingStrategy(),\n});\n\nprocessor.process('filter', { status: 'active', count: 5 });\n// [['filter', '{\"status\":\"active\",\"count\":5}']]\n\nprocessor.toQueryString('filter', { status: 'active', count: 5 });\n// filter=%7B%22status%22%3A%22active%22%2C%22count%22%3A5%7D\n```\n\nThe same `keyFormatter` option is accepted by every adapter (`-angular`, `-angular-resource`, `-fetch`, `-axios`, `-react-tanstack-query`, `-react-swr`), because they all forward their options object to `ParamsProcessor`.\n\nMixing shapes per request is easy, since `keyFormatter` can also be passed per call:\n\n```ts\nconst processor = new ParamsProcessor();\nconst json = new JsonKeyFormattingStrategy();\n\nprocessor.toQueryString('page', { page: 2 }); // page.page=2  (dot notation)\nprocessor.toQueryString('filter', { status: 'active' }, { keyFormatter: json }); // filter=%7B%22status%22%3A%22active%22%7D\n```\n\n---\n\n## 🎛️ Options and configuration\n\nNo constructor options: the output is whatever `JSON.stringify` produces, with no replacer, no indentation and no custom key ordering (properties keep insertion order).\n\nShape the payload before handing it over if you need control:\n\n```ts\nprocessor.process('filter', {\n  status: 'active',\n  from: new Date('2024-01-15T10:30:00Z').toISOString(),\n});\n// [['filter', '{\"status\":\"active\",\"from\":\"2024-01-15T10:30:00.000Z\"}']]\n```\n\nRegistering `valueConverters` does **not** affect the JSON blob (see edge cases), so pre-serialize dates, decimals and UUIDs yourself when using this strategy.\n\n---\n\n## 📤 Output examples\n\n```ts\nconst strategy = new JsonKeyFormattingStrategy();\nconst processor = new ParamsProcessor({ keyFormatter: strategy });\n```\n\n```text\nprocess('filter', { status: 'active', count: 5 })\n  filter = {\"status\":\"active\",\"count\":5}\n\nprocess('tags', ['a', 'b', 'c'])\n  tags   = [\"a\",\"b\",\"c\"]\n\nprocess('data', { user: { name: 'John', age: 30 }, active: true })\n  data   = {\"user\":{\"name\":\"John\",\"age\":30},\"active\":true}\n\nprocess('p', 'plain-value')\n  p      = plain-value        (primitives are not JSON encoded)\n```\n\n```ts\nprocessor.toPlainObject('data', { user: { name: 'John' } });\n// { data: '{\"user\":{\"name\":\"John\"}}' }\n```\n\n---\n\n## ⚠️ Edge cases\n\n- **Primitives bypass the hook.** `transformComplexObject` only runs for objects and arrays, so `process('p', 'plain-value')` still yields `[['p', 'plain-value']]` (no surrounding quotes).\n- **Value converters never see the inside of the blob.** `JSON.stringify` handles nested values itself, so `Date` becomes an ISO string via `toJSON`, a `Uint8Array` becomes `{\"0\":…}` and `decimal.js` values use their own `toJSON`. Only a non-plain object passed as the **root** is converted, because `core` offers such roots to the converters before calling the hook.\n- **Core's traversal rules do not apply inside the blob**: `undefined` properties are dropped by `JSON.stringify` (as are functions and symbols), `null` is kept as `null`, a `$type` discriminator is kept, and `{}` / `[]` still emit a pair (`p={}`, `p=[]`) instead of nothing.\n- **Circular references throw `TypeError: Converting circular structure to JSON`** from `JSON.stringify`, not the `Error: Circular reference detected at key: <key>` you get from `core`, because the hook runs before the cycle check.\n- `BigInt` values make `JSON.stringify` throw `TypeError: Do not know how to serialize a BigInt`.\n- The whole payload lands in one parameter value, so it is percent encoded in full: expect long URLs and check your server's query string limit (often 2 - 8 KB). Consider `POST` for large filters.\n- The backend must `JSON.parse` the value itself; no model binder will do it for you, and the parameter is opaque to caches and gateway rules that inspect individual query parameters.\n\n---\n\n## 🔗 Related packages\n\n- Flattening strategies: [`-key-bracket-notation`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-key-bracket-notation) (`user[name]`), [`-key-rails`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-key-rails) (`items[]`), [`-key-flat`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-key-flat) (`user_name`), [`-key-custom-delimiter`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-key-custom-delimiter) (`user:name`)\n- Engine: [`-core`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-core) (`IKeyFormattingStrategy`, `IParamsAppender`)\n\nFull matrix and adapter 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":"JSON key formatting strategy for HttpParamsProcessor that serializes whole objects into a single JSON query parameter.","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","key-formatting","json"]}