{"_id":"@adaskothebeast/http-params-processor-value-from-uuid","name":"@adaskothebeast/http-params-processor-value-from-uuid","dist-tags":{"latest":"12.0.0"},"versions":{"12.0.0":{"name":"@adaskothebeast/http-params-processor-value-from-uuid","version":"12.0.0","description":"UUID byte array and string input strategies for HttpParamsProcessor value conversion.","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","value-conversion","uuid","guid","rfc4122"],"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","uuid":"^14.0.1"},"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-uuid@12.0.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-imOFdvZ7VjGC2gJ4MWunFAECk7YGdlKDS0WDOp9HbXqWGYws9IKUnW/Bio+cwGEKfoZH6W19rKW5CF4gOBOA+Q==","shasum":"5cc1caa20c552f27d4be1d354c0916c5ee875785","tarball":"https://registry.npmjs.org/@adaskothebeast/http-params-processor-value-from-uuid/-/http-params-processor-value-from-uuid-12.0.0.tgz","fileCount":15,"unpackedSize":28733,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCrTPUTH4Hx+jkUDYjar3M8nRTzepjXCUpmI0o9DFBFBQIhAM2WDqMKV4Q8sfnVQ7LnHNyHHihJck8YBDTSvDmBkKqQ"}]},"_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-uuid_12.0.0_1785236269294_0.6717097801101413"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-28T10:57:49.106Z","12.0.0":"2026-07-28T10:57:49.448Z","modified":"2026-07-28T10:57:49.716Z"},"maintainers":[{"name":"adasko","email":"adaskothebeast@gmail.com"}],"description":"UUID byte array and string input strategies for HttpParamsProcessor value conversion.","homepage":"https://github.com/AdaskoTheBeAsT/HttpParamsProcessor","keywords":["http","http-params","query-string","query-params","querystring","nested-objects","serializer","typescript","value-conversion","uuid","guid","rfc4122"],"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-uuid\n\n**UUID input strategies for [HttpParamsProcessor](https://github.com/AdaskoTheBeAsT/HttpParamsProcessor): canonical, braced, urn and unhyphenated strings or raw 16 byte arrays, normalized to RFC 4122 bytes.**\n\n[![npm](https://img.shields.io/npm/v/%40adaskothebeast%2Fhttp-params-processor-value-from-uuid?color=cb3837&logo=npm)](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-uuid)\n[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\nPeer dependencies: `core` + `uuid` (types ship with `uuid`, no companion `@types` package). ESM + CJS. `sideEffects: false`.\n\n---\n\n## 📦 Install\n\n```bash\nnpm i @adaskothebeast/http-params-processor-value-from-uuid @adaskothebeast/http-params-processor-core uuid\n```\n\n---\n\n## 🎯 What it does\n\nThese are **value-from** strategies: the first half of the conversion pipeline. They normalize a UUID into the neutral `UuidComponents` shape from `core` (`{ bytes: Uint8Array }`, 16 bytes in RFC 4122 order), and a **value-to** strategy from [`-value-to-uuid`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-uuid) decides the wire format.\n\n| Class                         | Normalizes                                                 | Produces                       |\n| ----------------------------- | ---------------------------------------------------------- | ------------------------------ |\n| `UuidStringValueFromStrategy` | `string` (canonical, braced, urn, unhyphenated)            | `UuidComponents` (`{ bytes }`) |\n| `UuidBytesValueFromStrategy`  | `Uint8Array` (16 bytes, as returned by `uuid`'s `parse()`) | `UuidComponents` (`{ bytes }`) |\n\nWorking at the byte level is what makes the output side interchangeable: the same identifier can be emitted as `550e8400-e29b-41d4-a716-446655440000`, `{550E8400-…}` for a .NET `Guid.Parse` binder, `urn:uuid:…` or a 22 character base64 \"short guid\", without the caller knowing.\n\nAlso exported (type only): `UuidStringValueFromOptions`, `UuidValueFromOptions`, `UuidStringForm`, `UuidVersion`.\n\n---\n\n## ⚡ Usage\n\n```ts\nimport { ParamsProcessor, createValueConverter } from '@adaskothebeast/http-params-processor-core';\nimport { UuidBytesValueFromStrategy, UuidStringValueFromStrategy } from '@adaskothebeast/http-params-processor-value-from-uuid';\nimport { CanonicalUuidValueToStrategy } from '@adaskothebeast/http-params-processor-value-to-uuid';\nimport { parse } from 'uuid';\n\nconst processor = new ParamsProcessor({\n  valueConverters: [createValueConverter(new UuidBytesValueFromStrategy(), new CanonicalUuidValueToStrategy()), createValueConverter(new UuidStringValueFromStrategy({ forms: ['canonical', 'braced'] }), new CanonicalUuidValueToStrategy())],\n});\n\nprocessor.process('p', {\n  id: '{550E8400-E29B-41D4-A716-446655440000}',\n  parentId: parse('6ba7b810-9dad-11d1-80b4-00c04fd430c8'),\n});\n// [['p.id',       '550e8400-e29b-41d4-a716-446655440000'],\n//  ['p.parentId', '6ba7b810-9dad-11d1-80b4-00c04fd430c8']]\n```\n\n---\n\n## 🎛️ Options and configuration\n\n```ts\ntype UuidVersion = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;\ntype UuidStringForm = 'canonical' | 'braced' | 'urn' | 'unhyphenated';\n\ninterface UuidValueFromOptions {\n  versions?: readonly UuidVersion[];\n  strict?: boolean;\n}\n\ninterface UuidStringValueFromOptions extends UuidValueFromOptions {\n  forms?: readonly UuidStringForm[];\n}\n```\n\n| Option     | Applies to           | Default         | Effect                                                                                                                                    |\n| ---------- | -------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `forms`    | string strategy only | `['canonical']` | Which textual shapes are unwrapped and accepted                                                                                           |\n| `versions` | both strategies      | unset           | Allowlist of accepted version nibbles; other versions are declined (or throw in strict mode)                                              |\n| `strict`   | both strategies      | `false`         | Claim values of the right _shape_ even when validation fails, so they **throw** instead of silently falling through to the next converter |\n\nAccepted string forms:\n\n| `UuidStringForm` | Example                                         | Note                                                                                                          |\n| ---------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| `canonical`      | `550e8400-e29b-41d4-a716-446655440000`          | 36 chars, the default                                                                                         |\n| `braced`         | `{550e8400-e29b-41d4-a716-446655440000}`        | 38 chars, .NET \"B\"                                                                                            |\n| `urn`            | `urn:uuid:550e8400-e29b-41d4-a716-446655440000` | 45 chars, prefix match is case insensitive                                                                    |\n| `unhyphenated`   | `550e8400e29b41d4a716446655440000`              | 32 chars, .NET \"N\", opt-in because a bare 32 character hex string is indistinguishable from other identifiers |\n\n```ts\n// only v4, and shout when something else shows up\nnew UuidStringValueFromStrategy({ versions: [4], strict: true });\n\n// accept every textual form\nnew UuidStringValueFromStrategy({\n  forms: ['canonical', 'braced', 'urn', 'unhyphenated'],\n});\n\n// bytes, v7 only\nnew UuidBytesValueFromStrategy({ versions: [7] });\n```\n\n---\n\n## 📤 Output examples\n\n`UuidStringValueFromStrategy` with the default options:\n\n| Input                                                        | `canHandle` | `normalizeValue`                       |\n| ------------------------------------------------------------ | ----------- | -------------------------------------- |\n| `'550e8400-e29b-41d4-a716-446655440000'`                     | `true`      | `{ bytes: parse('550e8400-…') }`       |\n| `'550E8400-E29B-41D4-A716-446655440000'`                     | `true`      | same bytes (case is normalized)        |\n| `NIL` (`'00000000-0000-0000-0000-000000000000'`)             | `true`      | 16 zero bytes                          |\n| `'{550e8400-…}'`, `'urn:uuid:550e8400-…'`, `'550e8400e29b…'` | `false`     | not claimed until the form is opted in |\n| `'not-a-uuid'`, `''`, `42`                                   | `false`     | -                                      |\n\nWith `forms: ['canonical', 'braced', 'urn', 'unhyphenated']`, all four shapes of the same identifier normalize to identical bytes.\n\n`UuidBytesValueFromStrategy`:\n\n| Input                                      | `canHandle` | `normalizeValue`        |\n| ------------------------------------------ | ----------- | ----------------------- |\n| `parse('550e8400-…')` (16 bytes)           | `true`      | a **copy** of the bytes |\n| `new Uint8Array(15)`, `new Uint8Array(17)` | `false`     | wrong length            |\n| `'550e8400-…'`, `null`, `[1, 2, 3]`        | `false`     | not a `Uint8Array`      |\n\n---\n\n## ⚠️ Edge cases\n\n- **Validation errors are exact.** `normalizeValue` throws:\n\n  ```text\n  Invalid UUID: 'not-a-uuid'\n  Invalid UUID: version 1 is not allowed\n  Invalid UUID: expected 16 bytes, received 8\n  ```\n\n- **`canHandle` normally declines instead of throwing.** An invalid UUID string simply falls through to the next converter, which is what you want when the same processor also serializes ordinary strings.\n- **`strict: true` flips that trade-off.** The string strategy then claims anything with a plausible length for one of the enabled forms (36 / 38 / 45 / 32 characters), so `'550e8400-e29b-91d4-a716-446655440000'` (an invalid version nibble) is claimed and `normalizeValue` throws; `'short'` is still declined. The bytes strategy in strict mode claims **every** `Uint8Array`, including `new Uint8Array(4)`, and then throws on the length check.\n- **`versions` filters on the detected version nibble.** Detection goes through `uuid`'s `version()`, and anything it rejects yields `undefined`, which is never allowed. Note that the nil UUID reports version `0`, which is not a member of `UuidVersion`, so a `versions` allowlist always excludes it.\n- **Version filtering combined with `strict: true` claims first and validates later**: `canHandle` returns `true` for a valid UUID of a disallowed version so that `normalizeValue` can throw `Invalid UUID: version <n> is not allowed`.\n- **Bytes are copied**, never aliased (`new Uint8Array(value)`), so mutating your buffer after `normalizeValue` cannot change the serialized value.\n- **Byte order is RFC 4122**, the layout produced by `uuid`'s `parse()`. .NET's `Guid.ToByteArray()` uses a mixed-endian layout, so re-order those bytes yourself before feeding them in.\n- **The bytes strategy is more specific than the string one**, but both can be registered - put the byte converter first, since converters are tried in registration order and the first `canHandle` wins.\n- **`unhyphenated` is length driven**: with that form enabled, every 32 character string is unwrapped and validated, so enable it only where the values really are UUIDs.\n\n---\n\n## 🔗 Related packages\n\n- Outputs: [`-value-to-uuid`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-to-uuid) (`CanonicalUuidValueToStrategy`, `NoDashUuidValueToStrategy`, `BracedUuidValueToStrategy`, `UrnUuidValueToStrategy`, `Base64UuidValueToStrategy`)\n- Other inputs: [`-value-from-decimal`](https://www.npmjs.com/package/@adaskothebeast/http-params-processor-value-from-decimal), [`-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-ff89f1f8b645c4efa7784c8585f637e8"}