{"_id":"@adaskothebeast/http-params-processor-core","_rev":"4-f8a0bb660d1baca316d472436455238e","name":"@adaskothebeast/http-params-processor-core","dist-tags":{"latest":"12.0.0"},"versions":{"10.0.0":{"name":"@adaskothebeast/http-params-processor-core","version":"10.0.0","keywords":["params","query","url","http","serialization","axios","fetch","typescript"],"author":{"name":"Adam Pluciński","email":"adaskothebeast@gmail.com"},"license":"MIT","_id":"@adaskothebeast/http-params-processor-core@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":"9a1df465eb1d36da58ae5ef05db26903314fceaa","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-core/-/http-params-processor-core-10.0.0.tgz","fileCount":55,"integrity":"sha512-s5GMdg7SJQHgOeM0jFMI7c9bgnVHYRKCGnHV7aJOlMxJqTW3OP2xrG0K6pPAf2rpn1z48ba+CC2a+HR/qB+OBw==","signatures":[{"sig":"MEUCIQDCA0QCWi2mGPhvAyXOxvlyRpUN/e254xYeYSlK9v9CrQIgDYm6/Xy+OXAQuzhJGo4aZc3OwrkgxekKBSOcyO47TZk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":69709},"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":"Framework-agnostic params processor for converting complex objects to query parameters","directories":{},"sideEffects":false,"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/http-params-processor-core_10.0.0_1768076728236_0.20697067426237692","host":"s3://npm-registry-packages-npm-production"}},"11.0.0":{"name":"@adaskothebeast/http-params-processor-core","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-core@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":"210e2b8b68611fe93151f83c717020d99fee367a","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-core/-/http-params-processor-core-11.0.0.tgz","fileCount":30,"integrity":"sha512-5ExPcwBaq4XmUtWYT7nCL6Ftz29HsDlgT7vWHGLkKqguRGGewwqGWeOaRYjEchFrSuC648qAU7SaDBI4lfvv4Q==","signatures":[{"sig":"MEUCIQDihf7KCWLZM68DdBsTCzDnY423UfVPtGzzMs1atSsMagIgHvw63N1SB10IxLbV56XdVzyPbrGw6MvsSasFSC+iq/4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@adaskothebeast%2fhttp-params-processor-core@11.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":75902},"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:d608138f-6f4b-4d89-8db7-c0404e20ad06"}},"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-core_11.0.0_1768758180083_0.9062076475344572","host":"s3://npm-registry-packages-npm-production"}},"11.1.0":{"name":"@adaskothebeast/http-params-processor-core","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-core@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":"2895416ecd7b775c926f0ab1d66691670097f851","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-core/-/http-params-processor-core-11.1.0.tgz","fileCount":30,"integrity":"sha512-L23cDh8SyOxyCnkt3jBUgnbw3ow5KMh41aWa/i9ep4u+Yxq2qX7YTvMIh/eamOO0iDM5fDVZfvES6TMXRwg6Zg==","signatures":[{"sig":"MEUCIQCxPz5Za6Wg23lMnBLEle6MZzFrgJ9iQo9VIFlIDCTr+wIgXq54vad2YG3NUxZUVp6a09SD/GbirB3vYFkLKfJ0FF4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@adaskothebeast%2fhttp-params-processor-core@11.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":75902},"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:d608138f-6f4b-4d89-8db7-c0404e20ad06"}},"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-core_11.1.0_1768758927461_0.2880943101314779","host":"s3://npm-registry-packages-npm-production"}},"12.0.0":{"name":"@adaskothebeast/http-params-processor-core","version":"12.0.0","description":"Framework agnostic processor that turns deeply nested objects and arrays into HTTP query parameters your backend can model bind. Zero dependencies.","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","url-search-params","model-binding","deep-object","zero-dependencies"],"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","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-core@12.0.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-U7SjKGXGiQbTqLsXYgcYosnc39lq8eoUimAdj1aTKM+ejYAd+aiY+vfTLyExWH7vhqGMEsXL3kgt3ePcAmZ7mw==","shasum":"82819d471294523282b0c1bee9b9fb24dceb6304","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-core/-/http-params-processor-core-12.0.0.tgz","fileCount":35,"unpackedSize":55972,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGcMz+xx3Y0UO2J15goZvyhE9SyzLk/9jFSHvWiwByK+AiEAqWC8EIBXKPSQ+qLc5C1eEwP+PBrqCFeci1qclLQcT4o="}]},"_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-core_12.0.0_1785235855283_0.08490429961016854"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-10T20:25:28.176Z","modified":"2026-07-28T10:50:55.680Z","10.0.0":"2026-01-10T20:25:28.409Z","11.0.0":"2026-01-18T17:43:00.214Z","11.1.0":"2026-01-18T17:55:27.615Z","12.0.0":"2026-07-28T10:50:55.433Z"},"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-core\n\n**The framework-agnostic engine of [HttpParamsProcessor](https://github.com/AdaskoTheBeAsT/HttpParamsProcessor): turns deeply nested objects into flat query parameter pairs.**\n\n[![npm](https://img.shields.io/npm/v/%40adaskothebeast%2Fhttp-params-processor-core?color=cb3837&logo=npm)](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-core)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nZero runtime dependencies. ESM + CJS. `sideEffects: false`.\n\n---\n\n## 📦 Install\n\n```bash\nnpm i @adaskothebeast/http-params-processor-core\n```\n\n`core` is a **peer dependency of every other package** in the family - adapters (`-angular`, `-fetch`, `-axios`, `-react-*`), key formatting strategies (`-key-*`) and value strategies (`-value-*`) all need it installed alongside them.\n\n---\n\n## 🎯 What it does\n\n`ParamsProcessor` walks an object graph recursively and emits `[key, value]` string pairs:\n\n```ts\nimport { ParamsProcessor } from '@adaskothebeast/http-params-processor-core';\n\nconst processor = new ParamsProcessor();\n\nprocessor.process('p', {\n  arr: [{ id: '1', innerArr: [{ id: '1.1', text: 'first' }] }],\n});\n```\n\n```text\np.arr[0].id                = 1\np.arr[0].innerArr[0].id    = 1.1\np.arr[0].innerArr[0].text  = first\n```\n\nTwo things are pluggable:\n\n- **key formatting** - how nested keys are spelled (`user.name`, `user[name]`, `user_name`, …)\n- **value conversion** - a two-stage `from → to` pipeline that normalizes a library type into a neutral shape and then renders it as a string\n\n---\n\n## 🧰 API\n\n### `ParamsProcessor`\n\n| Member                                  | Returns                              | Notes                                                           |\n| --------------------------------------- | ------------------------------------ | --------------------------------------------------------------- |\n| `new ParamsProcessor(options?)`         | -                                    | `options` sets the instance-wide defaults                       |\n| `createParamsProcessor(options?)`       | `ParamsProcessor`                    | Factory helper, identical to the constructor                    |\n| `process(key, obj, options?)`           | `ParamsEntry[]` (`[key, value][]`)   | The primitive every adapter builds on; preserves duplicate keys |\n| `toQueryString(key, obj, options?)`     | `string`                             | `encodeURIComponent`-encoded, **no** leading `?`                |\n| `toURLSearchParams(key, obj, options?)` | `URLSearchParams`                    | Uses `append`, so array entries survive                         |\n| `toPlainObject(key, obj, options?)`     | `Record<string, string \\| string[]>` | Duplicate keys collapse into arrays - handy for `axios.params`  |\n\n`options` (`ParamsProcessorOptions`) can be passed per call and overrides the instance defaults:\n\n```ts\ninterface ParamsProcessorOptions {\n  keyFormatter?: IKeyFormattingStrategy;\n  valueConverters?: IValueConverter[];\n}\n```\n\n### Types\n\n`ParamsEntry`, `Primitive`, `ProcessableInput`, `isPlainObjectOrArray`.\n\n### Key formatting\n\n| Export                         | Purpose                                                                  |\n| ------------------------------ | ------------------------------------------------------------------------ |\n| `IKeyFormattingStrategy`       | `formatObjectKey`, `formatArrayKey`, optional `transformComplexObject`   |\n| `IParamsAppender`              | Minimal `append(key, value)` sink used by `transformComplexObject`       |\n| `DefaultKeyFormattingStrategy` | Dot notation for objects (`user.name`), brackets for arrays (`items[0]`) |\n\n### Value conversion pipeline\n\n| Export                                                      | Purpose                                                       |\n| ----------------------------------------------------------- | ------------------------------------------------------------- |\n| `IValueFromStrategy<TFrom, TTo>`                            | `normalizeValue` + `canHandle` - library type → neutral shape |\n| `IValueToStrategy<TFrom>`                                   | `serializeValue` + `canHandle` - neutral shape → `string`     |\n| `IValueConverter`, `ValueConverter`, `createValueConverter` | Pairs one `from` with one `to`                                |\n| `DefaultDateValueFromStrategy`                              | `Date` → `Date` (pass-through)                                |\n| `DefaultDateValueToStrategy`                                | `Date` → `toISOString()`                                      |\n| `DefaultPrimitiveValueToStrategy`                           | `string \\| number \\| boolean` → `String(value)`               |\n\n### Intermediate models\n\n| Export                                                    | Shape                                                                           |\n| --------------------------------------------------------- | ------------------------------------------------------------------------------- |\n| `DurationComponents`                                      | `{ years?, months?, weeks?, days?, hours?, minutes?, seconds?, milliseconds? }` |\n| `PeriodComponents`                                        | `{ years?, months?, weeks?, days? }` (calendar-based, not convertible to ms)    |\n| `DecimalComponents` + `isDecimalComponents`               | `{ decimal: string }` - lossless, non-exponential literal                       |\n| `UuidComponents` + `isUuidComponents`, `UUID_BYTE_LENGTH` | `{ bytes: Uint8Array }` - 16 bytes, RFC 4122 order                              |\n\n---\n\n## 🎛️ Configuration\n\n```ts\nimport { ParamsProcessor, createValueConverter } from '@adaskothebeast/http-params-processor-core';\nimport { BracketNotationKeyFormattingStrategy } from '@adaskothebeast/http-params-processor-key-bracket-notation';\nimport { LuxonDateTimeValueFromStrategy } from '@adaskothebeast/http-params-processor-value-from-luxon';\nimport { UnixTimestampValueToStrategy } from '@adaskothebeast/http-params-processor-value-to-unix-timestamp';\n\nconst processor = new ParamsProcessor({\n  keyFormatter: new BracketNotationKeyFormattingStrategy(),\n  valueConverters: [createValueConverter(new LuxonDateTimeValueFromStrategy(), new UnixTimestampValueToStrategy())],\n});\n```\n\nConverters are tried **in order**, first `canHandle` wins - put the specific ones first.\n\n> ⚠️ Passing `valueConverters` **replaces** the defaults. If you still want plain `Date`s and primitives handled, append `createValueConverter(new DefaultDateValueFromStrategy(), new DefaultDateValueToStrategy())` and a primitive converter yourself - otherwise unmatched values fall back to `String(value)`.\n\n### Writing your own strategy\n\n```ts\nimport { IValueFromStrategy, IValueToStrategy } from '@adaskothebeast/http-params-processor-core';\n\nclass BigIntValueFromStrategy implements IValueFromStrategy<bigint, string> {\n  normalizeValue(value: bigint): string {\n    return value.toString();\n  }\n  canHandle(value: unknown): value is bigint {\n    return typeof value === 'bigint';\n  }\n}\n```\n\n---\n\n## 📤 Output examples\n\n```ts\nconst processor = new ParamsProcessor();\nconst filter = { page: 2, tags: ['a', 'b'], from: new Date('2024-01-15T10:30:00Z') };\n\nprocessor.toQueryString('p', filter);\n// p.page=2&p.tags%5B0%5D=a&p.tags%5B1%5D=b&p.from=2024-01-15T10%3A30%3A00.000Z\n\nprocessor.toPlainObject('p', filter);\n// { 'p.page': '2', 'p.tags[0]': 'a', 'p.tags[1]': 'b', 'p.from': '2024-01-15T10:30:00.000Z' }\n\nprocessor.process('', 'plain-value');\n// [['', 'plain-value']]\n```\n\n---\n\n## 📐 Behaviour you can rely on\n\n- `null` and `undefined` properties are **skipped** entirely (no empty `key=`).\n- A `$type` property (typical .NET/JSON.NET discriminator) is ignored.\n- **Circular references throw** `Error: Circular reference detected at key: <key>` instead of hanging.\n- Non-plain objects (`Date`, `Decimal`, `Uint8Array`, class instances…) are offered to the value converters **before** traversal, so they are never walked property by property.\n- Plain objects and arrays are always traversed; only a `keyFormatter.transformComplexObject` that returns non-`null` (e.g. the JSON strategy) can short-circuit that.\n- Array order is preserved, and `process` never merges duplicate keys - only `toPlainObject` groups them.\n- Empty arrays and empty objects contribute no entries.\n- Values are encoded once by `toQueryString`/`toURLSearchParams`; `process` returns **raw** strings, so encode them yourself when building URLs manually.\n\n---\n\n## 🔗 Related packages\n\nAdapters: [`-angular`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-angular), [`-angular-resource`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-angular-resource), [`-fetch`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-fetch), [`-axios`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-axios), [`-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\nKey formatting: `-key-bracket-notation`, `-key-rails`, `-key-flat`, `-key-custom-delimiter`, `-key-json`.\n\nValues in: `-value-from-dayjs`, `-value-from-luxon`, `-value-from-moment`, `-value-from-js-joda`, `-value-from-decimal`, `-value-from-uuid`.\nValues out: `-value-to-iso`, `-value-to-nodatime`, `-value-to-unix-timestamp`, `-value-to-ms-timestamp`, `-value-to-date-fns`, `-value-to-decimal`, `-value-to-uuid`.\n\nFull matrix, adapter recipes and migration notes: [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":"Framework agnostic processor that turns deeply nested objects and arrays into HTTP query parameters your backend can model bind. Zero dependencies.","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","url-search-params","model-binding","deep-object","zero-dependencies"]}