{"_id":"@adaskothebeast/http-params-processor-value-from-decimal","name":"@adaskothebeast/http-params-processor-value-from-decimal","dist-tags":{"latest":"12.0.0"},"versions":{"12.0.0":{"name":"@adaskothebeast/http-params-processor-value-from-decimal","version":"12.0.0","description":"decimal.js input strategy for HttpParamsProcessor, enabling lossless decimal query parameters.","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","value-conversion","decimal","decimal.js","bignumber","precision"],"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","decimal.js":"^10.6.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-value-from-decimal@12.0.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-ArHka3Vxffr4xISqMVM0IcACXhN136aIMJp4+nyHV3CKVoOPJOOjujQNKyjnsnqj1+JT1s6TXBfxgD/zdyv5bw==","shasum":"d9392049495c2a3bdc72c7e620cf2c9710c22209","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-value-from-decimal/-/http-params-processor-value-from-decimal-12.0.0.tgz","fileCount":9,"unpackedSize":13991,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIF86JDqsU2fobu5sFREFYxX+Vc8jWgNM/mFZVL025UScAiAYQ4Wwa7OY5c5Gp39HYBLO2RikrnEWZ70Ml9FsFGFbCw=="}]},"_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-value-from-decimal_12.0.0_1785236181581_0.06826005128043655"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-28T10:56:21.424Z","12.0.0":"2026-07-28T10:56:21.720Z","modified":"2026-07-28T10:56:22.009Z"},"maintainers":[{"name":"adasko","email":"adaskothebeast@gmail.com"}],"description":"decimal.js input strategy for HttpParamsProcessor, enabling lossless decimal query parameters.","homepage":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","value-conversion","decimal","decimal.js","bignumber","precision"],"repository":{"type":"git","url":"git+https://github.com/AdaskoTheBeAsT/HttpParamsProcessor.git"},"author":{"name":"Adam Pluciński","email":"adaskothebeast@gmail.com","url":"https://github.com/adaskothebeast"},"bugs":{"url":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor/issues"},"license":"MIT","readme":"# 🔢 @adaskothebeast/http-params-processor-value-from-decimal\n\n**`decimal.js` input strategy for [HttpParamsProcessor](https://github.com/AdaskoTheBeAsT/HttpParamsProcessor): turns `Decimal` instances into a lossless, never exponential decimal literal.**\n\n[![npm](https://img.shields.io/npm/v/%40adaskothebeast%2Fhttp-params-processor-value-from-decimal?color=cb3837&logo=npm)](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-decimal)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nPeer dependencies: `core` + `decimal.js` (types ship with `decimal.js`, no companion `@types` package). ESM + CJS. `sideEffects: false`.\n\n---\n\n## 📦 Install\n\n```bash\nnpm i @adaskothebeast/http-params-processor-value-from-decimal @adaskothebeast/http-params-processor-core decimal.js\n```\n\n---\n\n## 🎯 What it does\n\nThis is a **value-from** strategy: the first half of the conversion pipeline. It normalizes a `decimal.js` value into the neutral `DecimalComponents` shape from `core` (`{ decimal: string }`), and a **value-to** strategy from [`-value-to-decimal`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-decimal) decides the wire format.\n\n| Class                      | Normalizes | Produces                            |\n| -------------------------- | ---------- | ----------------------------------- |\n| `DecimalValueFromStrategy` | `Decimal`  | `DecimalComponents` (`{ decimal }`) |\n\nWhy not just let the processor call `String(value)`?\n\n```ts\nString(new Decimal('1e-7')); // '1e-7'      - exponential, rejected by many binders\nString(new Decimal('1e21')); // '1e+21'     - exponential again\nNumber('12345678901234567890.1234567890123456789'); // 12345678901234567000 - digits lost\n```\n\n`DecimalValueFromStrategy` calls `toFixed()` with no argument, which is the one `decimal.js` formatter that is both **lossless** (every significant digit is kept) and **never exponential**, whatever the ambient `toExpNeg` / `toExpPos` settings are.\n\n---\n\n## ⚡ Usage\n\n```ts\nimport { ParamsProcessor, createValueConverter } from '@adaskothebeast/http-params-processor-core';\nimport { DecimalValueFromStrategy } from '@adaskothebeast/http-params-processor-value-from-decimal';\nimport { DecimalStringValueToStrategy } from '@adaskothebeast/http-params-processor-value-to-decimal';\nimport Decimal from 'decimal.js';\n\nconst processor = new ParamsProcessor({\n  valueConverters: [createValueConverter(new DecimalValueFromStrategy(), new DecimalStringValueToStrategy())],\n});\n\nprocessor.process('p', {\n  price: new Decimal('12.50'),\n  rate: new Decimal('1e-7'),\n});\n// [['p.price', '12.5'], ['p.rate', '0.0000001']]\n```\n\n---\n\n## 🎛️ Options and configuration\n\n`DecimalValueFromStrategy` has **no constructor options** - the intermediate literal is intentionally fixed, and formatting decisions (fixed decimal places, exponential notation, number literals) belong to the paired value-to strategy.\n\n`canHandle` accepts a value when both conditions hold:\n\n- `Decimal.isDecimal(value)` is `true`, which also covers instances created from a `Decimal.clone({ precision: 40 })` constructor\n- `value.isFinite()` is `true`\n\nEverything else is left to the next converter, including:\n\n| Input                                       | `canHandle` | Reason                                                           |\n| ------------------------------------------- | ----------- | ---------------------------------------------------------------- |\n| `new Decimal('123.45')`, `new Decimal(0)`   | `true`      | finite `Decimal` instance                                        |\n| `new Cloned('123.45')`                      | `true`      | clones are still `Decimal`s                                      |\n| `new Decimal(NaN)`, `new Decimal(Infinity)` | `false`     | not finite                                                       |\n| `'123.45'`                                  | `false`     | decimal shaped **strings** are ambiguous (`phone`, `postalCode`) |\n| `123.45`                                    | `false`     | plain numbers are handled by the primitive converter             |\n| `null`, `{ decimal: '1' }`                  | `false`     | not a `Decimal`                                                  |\n\n---\n\n## 📤 Output examples\n\n`normalizeValue` results, straight from the test suite:\n\n| `Decimal` input                              | `DecimalComponents.decimal`                  |\n| -------------------------------------------- | -------------------------------------------- |\n| `'12345678901234567890.1234567890123456789'` | `'12345678901234567890.1234567890123456789'` |\n| `'+42'`                                      | `'42'`                                       |\n| `'.5'`                                       | `'0.5'`                                      |\n| `'1.25e+8'`                                  | `'125000000'`                                |\n| `'1e-7'`                                     | `'0.0000001'`                                |\n| `'-0.001'`                                   | `'-0.001'`                                   |\n\n---\n\n## ⚠️ Edge cases\n\n- **Strings and numbers are never claimed.** If your API sends decimals as strings, convert them to `Decimal` first, otherwise they flow through the default primitive handling untouched.\n- **`NaN` and `Infinity` are not claimed**, so they end up in the fallback `String(value)` path (`'NaN'`, `'Infinity'`) rather than producing an unparsable decimal literal. Filter them out before serializing if your backend rejects them.\n- **Input notation is normalized**: a leading `+` is dropped, a bare `.5` gains its integer zero, and exponential inputs are expanded. The sign of negative values is preserved (`-0.001`).\n- **Very small or very large magnitudes expand fully.** `new Decimal('1e-30')` becomes a 30 decimal place literal; that is intentional (lossless), but keep URL length limits in mind.\n- **Precision comes from the `Decimal` you pass in.** This strategy never re-rounds, so if the value was already truncated by a `Decimal.clone({ precision })` operation, the truncation is what gets serialized.\n- The neutral literal only travels one hop: pair it with a value-to strategy whose `canHandle` recognizes `DecimalComponents`. Registering the from-strategy alone means the object `{ decimal: '12.5' }` reaches the fallback `String(value)` path.\n\n---\n\n## 🔗 Related packages\n\n- Outputs: [`-value-to-decimal`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-decimal) (`DecimalStringValueToStrategy`, `DecimalFixedValueToStrategy`, `DecimalNumberValueToStrategy`, `DecimalExponentialValueToStrategy`)\n- Other inputs: [`-value-from-uuid`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-uuid), [`-value-from-luxon`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-luxon), [`-value-from-dayjs`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-dayjs), [`-value-from-moment`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-moment), [`-value-from-js-joda`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-js-joda)\n- Engine: [`-core`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-core)\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","_rev":"1-4b234f0f55beb1e24dbb10a7b17ccff9"}