{"_id":"@adaskothebeast/http-params-processor-value-to-decimal","name":"@adaskothebeast/http-params-processor-value-to-decimal","dist-tags":{"latest":"12.0.0"},"versions":{"12.0.0":{"name":"@adaskothebeast/http-params-processor-value-to-decimal","version":"12.0.0","description":"Plain, fixed, numeric and exponential decimal output strategies for HttpParamsProcessor, keeping decimal.js values lossless.","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-to-decimal@12.0.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-FxkTTVxixTUNWs1PkDqpI+FWMR7uSQvjdwrXXwSWwtlbU97PJ+Hm34bW5JdfnQkmRCdH5Oq11nGFgAsdkTBMAw==","shasum":"161af08ab47b5cc180e91e4751d5b6d05ab4e866","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-value-to-decimal/-/http-params-processor-value-to-decimal-12.0.0.tgz","fileCount":17,"unpackedSize":24396,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDEtyzo05XtYF3GY1uT7yVWVLypa5G3v+Cw1ovz+Vzd1wIhAJeFLrhQ4EDGeCxTm3E2JHt/4wDIGLVLwNdMQePeJvhy"}]},"_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-to-decimal_12.0.0_1785236340390_0.36116526224244083"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-28T10:59:00.257Z","12.0.0":"2026-07-28T10:59:00.544Z","modified":"2026-07-28T10:59:00.733Z"},"maintainers":[{"name":"adasko","email":"adaskothebeast@gmail.com"}],"description":"Plain, fixed, numeric and exponential decimal output strategies for HttpParamsProcessor, keeping decimal.js values lossless.","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-to-decimal\n\n**Decimal output strategies for [HttpParamsProcessor](https://github.com/AdaskoTheBeAsT/HttpParamsProcessor): plain literals, fixed decimal places, number literals and exponential notation.**\n\n[![npm](https://img.shields.io/npm/v/%40adaskothebeast%2Fhttp-params-processor-value-to-decimal?color=cb3837&logo=npm)](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-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-to-decimal @adaskothebeast/http-params-processor-core decimal.js\n```\n\n---\n\n## 🎯 What it does\n\nThese are **value-to** strategies: the second half of the conversion pipeline. Each one consumes the neutral `DecimalComponents` shape from `core` (`{ decimal: string }`) - normally produced by [`-value-from-decimal`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-decimal) - and renders it as a query string value.\n\n| Class                               | Renders as                        | Example output                             |\n| ----------------------------------- | --------------------------------- | ------------------------------------------ |\n| `DecimalStringValueToStrategy`      | the lossless literal, verbatim    | `12345678901234567890.1234567890123456789` |\n| `DecimalFixedValueToStrategy`       | fixed decimal places (money)      | `12.50`                                    |\n| `DecimalNumberValueToStrategy`      | JavaScript number literal         | `12.5`                                     |\n| `DecimalExponentialValueToStrategy` | exponential / scientific notation | `1.25e+8`                                  |\n\n`DecimalStringValueToStrategy` is the safe default: it is the format ASP.NET Core, Rails and Spring decimal binders expect, and it is the only one of the four that cannot lose a digit.\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 { DecimalFixedValueToStrategy, 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', { total: new Decimal('12.5') });\n// [['p.total', '12.5']]\n\n// money oriented processor: always two decimal places\nconst money = new ParamsProcessor({\n  valueConverters: [createValueConverter(new DecimalValueFromStrategy(), new DecimalFixedValueToStrategy(2))],\n});\n\nmoney.process('p', { total: new Decimal('12.5') });\n// [['p.total', '12.50']]\n```\n\n---\n\n## 🎛️ Options and configuration\n\n| Class                               | Constructor                                                  | Defaults                                                   |\n| ----------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- |\n| `DecimalStringValueToStrategy`      | `new DecimalStringValueToStrategy()`                         | no options                                                 |\n| `DecimalFixedValueToStrategy`       | `new DecimalFixedValueToStrategy(decimalPlaces?, rounding?)` | `decimalPlaces = 2`, `rounding = Decimal.ROUND_HALF_UP`    |\n| `DecimalNumberValueToStrategy`      | `new DecimalNumberValueToStrategy()`                         | no options                                                 |\n| `DecimalExponentialValueToStrategy` | `new DecimalExponentialValueToStrategy(significantDigits?)`  | `significantDigits = undefined` (as many digits as needed) |\n\n- `rounding` is any `decimal.js` rounding constant (`Decimal.ROUND_HALF_UP`, `Decimal.ROUND_DOWN`, …) and is forwarded to `Decimal.prototype.toFixed(decimalPlaces, rounding)`.\n- `significantDigits` is forwarded to `Decimal.prototype.toExponential`, which interprets it as the number of digits **after** the decimal point, so `2` renders `125400000` as `1.25e+8`.\n\nAll four strategies share the same `canHandle`, a structural guard over `DecimalComponents`: an object whose `decimal` property is a string matching `/^[+-]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)$/`.\n\n| `canHandle` input        | Result                                             |\n| ------------------------ | -------------------------------------------------- |\n| `{ decimal: '-0.5' }`    | `true`                                             |\n| `{ decimal: '1.25e+8' }` | `false` (exponential input is not a plain literal) |\n| `{ decimal: 'abc' }`     | `false`                                            |\n| `'1.5'`                  | `false` (a bare string is never claimed)           |\n| `null`                   | `false`                                            |\n\n---\n\n## 📤 Output examples\n\n```ts\nnew DecimalStringValueToStrategy().serializeValue({\n  decimal: '12345678901234567890.1234567890123456789',\n});\n// '12345678901234567890.1234567890123456789'\n```\n\n| Strategy                                                 | `DecimalComponents`        | Output    |\n| -------------------------------------------------------- | -------------------------- | --------- |\n| `new DecimalFixedValueToStrategy()`                      | `{ decimal: '12.5' }`      | `12.50`   |\n| `new DecimalFixedValueToStrategy(2)`                     | `{ decimal: '1.005' }`     | `1.01`    |\n| `new DecimalFixedValueToStrategy(2)`                     | `{ decimal: '1.004' }`     | `1.00`    |\n| `new DecimalFixedValueToStrategy(0, Decimal.ROUND_DOWN)` | `{ decimal: '1.9' }`       | `1`       |\n| `new DecimalNumberValueToStrategy()`                     | `{ decimal: '12.50' }`     | `12.5`    |\n| `new DecimalNumberValueToStrategy()`                     | `{ decimal: '-0.001' }`    | `-0.001`  |\n| `new DecimalExponentialValueToStrategy()`                | `{ decimal: '125000000' }` | `1.25e+8` |\n| `new DecimalExponentialValueToStrategy(2)`               | `{ decimal: '125400000' }` | `1.25e+8` |\n\n---\n\n## ⚠️ Edge cases\n\n- `DecimalNumberValueToStrategy` **throws** when the literal cannot become a finite double:\n\n  ```text\n  Error: Decimal '<literal>' cannot be represented as a finite number\n  ```\n\n  This is deliberate - silently emitting `Infinity` would be worse. Use `DecimalStringValueToStrategy` for values outside the double range.\n\n- `DecimalNumberValueToStrategy` also **drops trailing zeros** (`'12.50'` → `12.5`) and can lose digits beyond 17 significant figures, because the value passes through `Number`. Never use it for money you intend to compare byte for byte.\n- `DecimalFixedValueToStrategy` **rounds**, it does not validate. `1.005` becomes `1.01` with the default half-up mode, while `Decimal.ROUND_DOWN` truncates instead (`1.9` → `1` at zero decimal places).\n- `DecimalExponentialValueToStrategy` output always carries an explicit sign in the exponent (`1.25e+8`, `1e-7`). Round-tripping it needs a backend that accepts scientific notation.\n- Exponential **inputs** are rejected by `canHandle`, so `{ decimal: '1.25e+8' }` is not claimed by any of these strategies. `DecimalValueFromStrategy` never produces such a literal (it uses `toFixed()`), so this only matters if you build `DecimalComponents` by hand.\n- Only one converter can win per value: converters are tried in registration order and the first matching `canHandle` claims the value. Since all four strategies accept exactly the same input shape, register at most one decimal converter per processor - or branch by key with separate processors.\n- These strategies do not depend on the _from_ side at runtime; anything that produces `{ decimal: '<plain literal>' }` works, including your own `bigint` or string based normalizer.\n\n---\n\n## 🔗 Related packages\n\n- Inputs: [`-value-from-decimal`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-decimal)\n- Other outputs: [`-value-to-uuid`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-uuid), [`-value-to-iso`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-iso), [`-value-to-nodatime`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-nodatime), [`-value-to-unix-timestamp`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-unix-timestamp), [`-value-to-ms-timestamp`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-ms-timestamp), [`-value-to-date-fns`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-date-fns)\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-0bd2e424c7c37ba8a3da47aaaa5ce660"}