{"_id":"@adaskothebeast/http-params-processor-value-to-uuid","name":"@adaskothebeast/http-params-processor-value-to-uuid","dist-tags":{"latest":"12.0.0"},"versions":{"12.0.0":{"name":"@adaskothebeast/http-params-processor-value-to-uuid","version":"12.0.0","description":"Canonical, no dash, braced, urn and base64 UUID output strategies for HttpParamsProcessor.","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","value-conversion","uuid","guid","base64","urn"],"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-value-to-uuid@12.0.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-GfhvJANRebL7tGC21nPcDBDtFJ4+jSh2PLBNjtJ0Oo5Re9DORBHjUgeq241jQQTZUf64rs+RyzEsb2LkV3hLTg==","shasum":"d0618e028f1fda6c76b66a547535c10108e4e765","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-value-to-uuid/-/http-params-processor-value-to-uuid-12.0.0.tgz","fileCount":23,"unpackedSize":30567,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCOjesvUfMZW/hEbd+/vJDmvsFuhhOEePRdRtcwH/pidAIgCxHpjB7v322Fy64cxmo7OfhW+/MRvXvwdpgzEOu5iJE="}]},"_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-uuid_12.0.0_1785236466613_0.6829367034104865"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-28T11:01:06.460Z","12.0.0":"2026-07-28T11:01:06.770Z","modified":"2026-07-28T11:01:07.027Z"},"maintainers":[{"name":"adasko","email":"adaskothebeast@gmail.com"}],"description":"Canonical, no dash, braced, urn and base64 UUID output strategies for HttpParamsProcessor.","homepage":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","value-conversion","uuid","guid","base64","urn"],"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-uuid\n\n**UUID output strategies for [HttpParamsProcessor](https://github.com/AdaskoTheBeAsT/HttpParamsProcessor): canonical, no dash, braced, urn and base64 \"short guid\" formats.**\n\n[![npm](https://img.shields.io/npm/v/%40adaskothebeast%2Fhttp-params-processor-value-to-uuid?color=cb3837&logo=npm)](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-uuid)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nNo runtime dependency beyond `core` (hex and base64 are computed in-package, `uuid` is **not** needed). ESM + CJS. `sideEffects: false`.\n\n---\n\n## 📦 Install\n\n```bash\nnpm i @adaskothebeast/http-params-processor-value-to-uuid @adaskothebeast/http-params-processor-core\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 `UuidComponents` shape from `core` (`{ bytes: Uint8Array }`, 16 bytes in RFC 4122 order) - normally produced by [`-value-from-uuid`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-uuid) - and renders it as a query string value.\n\n| Class                          | Format                  | Example output                                  |\n| ------------------------------ | ----------------------- | ----------------------------------------------- |\n| `CanonicalUuidValueToStrategy` | hyphenated, .NET \"D\"    | `550e8400-e29b-41d4-a716-446655440000`          |\n| `NoDashUuidValueToStrategy`    | 32 hex digits, .NET \"N\" | `550e8400e29b41d4a716446655440000`              |\n| `BracedUuidValueToStrategy`    | braces, .NET \"B\"        | `{550e8400-e29b-41d4-a716-446655440000}`        |\n| `UrnUuidValueToStrategy`       | RFC 4122 URN            | `urn:uuid:550e8400-e29b-41d4-a716-446655440000` |\n| `Base64UuidValueToStrategy`    | base64 encoded bytes    | `VQ6EAOKbQdSnFkRmVUQAAA`                        |\n\nByte level formatting is the point: a .NET minimal API that binds `Guid` accepts \"D\", \"N\", \"B\" and \"P\" shapes, Java's `UUID.fromString` insists on the canonical form, and shortened base64 identifiers keep URLs small. Same identifier, one converter swap.\n\nAlso exported: `UuidValueToStrategyBase` (extend it for a custom hex layout) plus the option types `UuidValueToOptions` and `Base64UuidValueToOptions`.\n\n---\n\n## ⚡ Usage\n\n```ts\nimport { ParamsProcessor, createValueConverter } from '@adaskothebeast/http-params-processor-core';\nimport { UuidStringValueFromStrategy } from '@adaskothebeast/http-params-processor-value-from-uuid';\nimport { BracedUuidValueToStrategy, CanonicalUuidValueToStrategy } from '@adaskothebeast/http-params-processor-value-to-uuid';\n\nconst processor = new ParamsProcessor({\n  valueConverters: [createValueConverter(new UuidStringValueFromStrategy(), new CanonicalUuidValueToStrategy())],\n});\n\nprocessor.process('p', { id: '550E8400-E29B-41D4-A716-446655440000' });\n// [['p.id', '550e8400-e29b-41d4-a716-446655440000']]\n\n// a backend that wants the .NET \"B\" format in upper case\nconst dotnet = new ParamsProcessor({\n  valueConverters: [createValueConverter(new UuidStringValueFromStrategy(), new BracedUuidValueToStrategy({ uppercase: true }))],\n});\n\ndotnet.process('p', { id: '550e8400-e29b-41d4-a716-446655440000' });\n// [['p.id', '{550E8400-E29B-41D4-A716-446655440000}']]\n```\n\n---\n\n## 🎛️ Options and configuration\n\n```ts\ninterface UuidValueToOptions {\n  uppercase?: boolean; // defaults to false\n}\n\ninterface Base64UuidValueToOptions {\n  urlSafe?: boolean; // defaults to true  (`-` and `_` instead of `+` and `/`)\n  padding?: boolean; // defaults to false (22 characters, no `=`)\n}\n```\n\n| Class                          | Constructor                                  | Options                    |\n| ------------------------------ | -------------------------------------------- | -------------------------- |\n| `CanonicalUuidValueToStrategy` | `new CanonicalUuidValueToStrategy(options?)` | `UuidValueToOptions`       |\n| `NoDashUuidValueToStrategy`    | `new NoDashUuidValueToStrategy(options?)`    | `UuidValueToOptions`       |\n| `BracedUuidValueToStrategy`    | `new BracedUuidValueToStrategy(options?)`    | `UuidValueToOptions`       |\n| `UrnUuidValueToStrategy`       | `new UrnUuidValueToStrategy()`               | none, always lower case    |\n| `Base64UuidValueToStrategy`    | `new Base64UuidValueToStrategy(options?)`    | `Base64UuidValueToOptions` |\n\n`uppercase: true` upper cases the whole rendered string, which is why `UrnUuidValueToStrategy` does not expose it: the `urn:uuid:` prefix has to stay lower case. `Base64UuidValueToStrategy` has no `uppercase` option either - base64 is case sensitive.\n\nAll five strategies share the same `canHandle`, a structural guard over `UuidComponents`: an object whose `bytes` property is a `Uint8Array` of exactly 16 bytes.\n\n| `canHandle` input                        | Result  |\n| ---------------------------------------- | ------- |\n| `{ bytes: <16 byte Uint8Array> }`        | `true`  |\n| `{ bytes: new Uint8Array(4) }`           | `false` |\n| a bare `Uint8Array`                      | `false` |\n| `'550e8400-e29b-41d4-a716-446655440000'` | `false` |\n| `null`                                   | `false` |\n\n### Custom formats\n\n```ts\nimport { UuidValueToOptions, UuidValueToStrategyBase } from '@adaskothebeast/http-params-processor-value-to-uuid';\n\nclass ParenUuidValueToStrategy extends UuidValueToStrategyBase {\n  constructor(options: UuidValueToOptions = {}) {\n    super(options);\n  }\n\n  protected override format(bytes: Uint8Array): string {\n    return `(${[...bytes].map((b) => b.toString(16).padStart(2, '0')).join('')})`;\n  }\n}\n```\n\nThe base class implements `canHandle` and the `uppercase` handling; you only supply `format`.\n\n---\n\n## 📤 Output examples\n\nAll rows use the same bytes, `[0x55, 0x0e, 0x84, 0x00, 0xe2, 0x9b, 0x41, 0xd4, 0xa7, 0x16, 0x44, 0x66, 0x55, 0x44, 0x00, 0x00]`:\n\n| Strategy                                                           | Output                                          |\n| ------------------------------------------------------------------ | ----------------------------------------------- |\n| `new CanonicalUuidValueToStrategy()`                               | `550e8400-e29b-41d4-a716-446655440000`          |\n| `new CanonicalUuidValueToStrategy({ uppercase: true })`            | `550E8400-E29B-41D4-A716-446655440000`          |\n| `new NoDashUuidValueToStrategy()`                                  | `550e8400e29b41d4a716446655440000`              |\n| `new BracedUuidValueToStrategy()`                                  | `{550e8400-e29b-41d4-a716-446655440000}`        |\n| `new UrnUuidValueToStrategy()`                                     | `urn:uuid:550e8400-e29b-41d4-a716-446655440000` |\n| `new Base64UuidValueToStrategy()`                                  | `VQ6EAOKbQdSnFkRmVUQAAA`                        |\n| `new Base64UuidValueToStrategy({ urlSafe: false, padding: true })` | `VQ6EAOKbQdSnFkRmVUQAAA==`                      |\n\nThe url-safe alphabet only shows up when the bytes need it. For `fffefd00-0102-7f80-8110-203040506070`:\n\n```text\nnew Base64UuidValueToStrategy()                                    -> __79AAECf4CBECAwQFBgcA\nnew Base64UuidValueToStrategy({ urlSafe: false, padding: true })   -> //79AAECf4CBECAwQFBgcA==\nnew Base64UuidValueToStrategy({ urlSafe: false })                  -> //79AAECf4CBECAwQFBgcA\n```\n\nLeading zero bytes are always padded, so 16 zero bytes render as `00000000-0000-0000-0000-000000000000`, not a shortened literal.\n\n---\n\n## ⚠️ Edge cases\n\n- **`canHandle` is length strict.** `{ bytes: new Uint8Array(4) }` is declined rather than rendered as a short hex string, so a malformed intermediate value falls through to the next converter instead of producing an invalid identifier.\n- **A bare `Uint8Array` is not claimed**, only the wrapped `{ bytes }` shape. Register [`UuidBytesValueFromStrategy`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-uuid) as the _from_ half to get there.\n- **Base64 output is 22 characters by default.** 16 bytes are not a multiple of 3, so the final group encodes a single byte: with `padding: true` it is followed by `==` (24 characters total), and without padding those two characters are simply omitted.\n- **`urlSafe` defaults to `true`** and only switches to the standard alphabet when you pass `urlSafe: false` explicitly (any other value keeps `-`/`_`). Url-safe output needs no percent-encoding in a query string, while `+` and `/` from the standard alphabet do.\n- **Base64 encodes RFC 4122 byte order**, which differs from the mixed-endian layout of .NET `Guid.ToByteArray()`. A .NET service that does `new Guid(bytes)` on the decoded value will see a different UUID unless it re-orders the first three fields.\n- **Nothing is validated beyond the byte count.** Version and variant nibbles are irrelevant here, so the nil UUID, the max UUID and non-RFC byte patterns all serialize happily - enforce versions on the _from_ side with the `versions` option.\n- **All five strategies accept exactly the same input shape**, and converters are tried in registration order with the first matching `canHandle` winning. Register at most one UUID converter per processor, or use separate processors when different endpoints need different formats.\n- `uppercase` affects the entire rendered string, so it upper cases the plain hex of `NoDashUuidValueToStrategy` and the hex inside the braces of `BracedUuidValueToStrategy` (the braces have no case of their own).\n\n---\n\n## 🔗 Related packages\n\n- Inputs: [`-value-from-uuid`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-uuid) (`UuidStringValueFromStrategy`, `UuidBytesValueFromStrategy`)\n- Other outputs: [`-value-to-decimal`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-decimal), [`-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-9f3fc1190d484ba414e29e24066f6132"}