uuid 11.1.1: Convert losslessly between UUIDv1 and sortable UUIDv6 strings or byte arrays using v1ToV6 and v6ToV1 while preserving timestamp, clock sequence, and node fields

# uuid 11.1.1: Lossless UUIDv1 and UUIDv6 Bidirectional Conversion

## Prior Search Results

A search for existing solutions returned three published samples for `uuid`:
- `sha256:1ea156854e9d9790ef435039f48dd14740346e2298e632d0a2256919d714c656`: Preserving custom timestamp and sequence options in UUIDv7 generation.
- `sha256:8b2025b2eb659b9e73fc86cfbcb996a22203b918221bc0acd4d78a59ea97074a`: Rejecting undersized buffers and out-of-bounds offsets in v1, v4, and v7.
- `sha256:3dad9d47b302dcfbbddb1d03c9bb8e3c19e51dba749ec10e59342ea124bb1952`: Supplying custom RNG functions for v4 entropy and stringifying buffer outputs.

This sample addresses a separate area introduced in RFC 9562 support: bidirectional field and byte conversions between UUIDv1 and UUIDv6 via `v1ToV6` and `v6ToV1`.

## Pinned Release

- Package: `uuid`
- Version: `11.1.1` (resolved in `package.json` and `package-lock.json`)

## Observed Behaviour

1. **Timestamp Field Reordering**: `v1ToV6` rearranges the 60-bit 100-nanosecond timestamp from UUIDv1 layout (`time_low`, `time_mid`, `time_hi`) into big-endian sortable layout (`time_high`, `time_mid`, `time_low`) and sets the version nibble to 6.
2. **Lossless Inversion**: `v6ToV1` reconstructs the original UUIDv1 string and byte values identically without losing clock sequence or node bits.
3. **Generator Equivalence**: Generating a UUID via `v6(options)` with explicit `msecs`, `nsecs`, `clockseq`, and `node` parameters produces the exact same value as calling `v1ToV6` on the output of `v1(options)` with those same parameters.
4. **Polymorphic Type Handling**: Both `v1ToV6` and `v6ToV1` accept canonical hyphenated string representations (returning strings) and 16-byte `Uint8Array` instances (returning a new 16-byte `Uint8Array`).
5. **Input Validation**: Passing non-UUID strings to `v1ToV6` or `v6ToV1` triggers string validation via `validate()`, throwing a `TypeError` with message `'Invalid UUID'`.

{"case":{"caseId":"case:sha256:25ed5b68475a0e75cb772bb73bf68baecd9db69803dc60d231338f2fa2e81687","contract":["v1ToV6 losslessly reorders a UUIDv1 into a sortable UUIDv6 by rearranging timestamp fields into big-endian order and setting version 6, while v6ToV1 restores the original UUIDv1.","v6(options) produces the exact same UUID string as passing v1(options) output into v1ToV6","v1ToV6 and v6ToV1 operate identically on 16-byte Uint8Array buffers and return Uint8Array instances","v1ToV6 and v6ToV1 reject non-UUID string inputs with TypeError('Invalid UUID')"],"goal":"Convert losslessly between UUIDv1 and sortable UUIDv6 strings or byte arrays using v1ToV6 and v6ToV1 while preserving timestamp, clock sequence, and node fields","kind":"HOW","packages":["pkg:npm/uuid@11.1.1"],"schemaVersion":1,"symbols":["v1ToV6","v6ToV1","v6","v1"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","executionContext":"node","language":"node","os":"linux","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/uuid@11.1.1"],"schemaVersion":1,"symbols":["v1ToV6","v6ToV1","v6","v1"],"verifierAdapter":"node-typescript@1"}

{
  "name": "npm-uuid-v11",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "npm-uuid-v11",
      "version": "1.0.0",
      "dependencies": {
        "uuid": "11.1.1"
      }
    },
    "node_modules/uuid": {
      "version": "11.1.1",
      "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.1.tgz",
      "integrity": "sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ==",
      "funding": [
        "https://github.com/sponsors/broofa",
        "https://github.com/sponsors/ctavan"
      ],
      "license": "MIT",
      "bin": {
        "uuid": "dist/esm/bin/uuid"
      }
    }
  }
}

{
  "name": "npm-uuid-v11",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "uuid": "11.1.1"
  }
}

import assert from 'node:assert/strict';
import { v1, v6, v1ToV6, v6ToV1, validate, version, parse } from 'uuid';

// 1. Lossless round-trip conversion on canonical UUID strings
const fixedNode = new Uint8Array([0x01, 0x23, 0x45, 0x67, 0x89, 0xab]);
const options = {
  msecs: 1321564380000,
  nsecs: 5432,
  clockseq: 0x385c,
  node: fixedNode,
};

const v1Str = v1(options);
assert.strictEqual(v1Str, 'edaeab38-1160-11e1-b85c-0123456789ab');
assert.strictEqual(validate(v1Str), true);
assert.strictEqual(version(v1Str), 1);

// v1ToV6 moves time-high (1e1), time-mid (1160), and time-low (edaeab38) into big-endian order
const v6Str = v1ToV6(v1Str);
assert.strictEqual(v6Str, '1e11160e-daea-6b38-b85c-0123456789ab');
assert.strictEqual(validate(v6Str), true);
assert.strictEqual(version(v6Str), 6);

// v6() generator with identical parameters matches v1ToV6(v1()) directly
const v6Direct = v6(options);
assert.strictEqual(v6Direct, v6Str);

// v6ToV1 losslessly reconstructs the original UUIDv1
const v1Restored = v6ToV1(v6Str);
assert.strictEqual(v1Restored, v1Str);
assert.strictEqual(version(v1Restored), 1);

// 2. Uint8Array byte-level transformation
const v1Bytes = parse(v1Str);
const v6Bytes = v1ToV6(v1Bytes);
assert.ok(v6Bytes instanceof Uint8Array);
assert.strictEqual(v6Bytes.length, 16);
assert.deepStrictEqual(v6Bytes, parse(v6Str));

const v1BytesRestored = v6ToV1(v6Bytes);
assert.ok(v1BytesRestored instanceof Uint8Array);
assert.strictEqual(v1BytesRestored.length, 16);
assert.deepStrictEqual(v1BytesRestored, v1Bytes);

// 3. String inputs are validated before conversion
assert.throws(
  () => v1ToV6('not-a-valid-uuid'),
  {
    name: 'TypeError',
    message: 'Invalid UUID',
  }
);
assert.throws(
  () => v6ToV1('not-a-valid-uuid'),
  {
    name: 'TypeError',
    message: 'Invalid UUID',
  }
);