win-guid

A module for encoding and decoding Windows legacy GUIDs using the Windows GUID byte layout,
a mixed-endianness format used by several long-standing Microsoft and firmware standards, including:

- Component Object Model (COM)
- Object Linking and Embedding (OLE)
- Compound File Binary Format (CFBF, Structured Storage)
- GUID Partition Table (GPT)
- Unified Extensible Firmware Interface (UEFI)
- Windows Registry binary GUID values
- Active Directory objectGUID values

This is commonly needed when working with Microsoft file and storage formats, such as .asf, .doc, .xls, .ppt,
and other binary formats based on OLE/COM Structured Storage (CFBF),
where GUIDs are stored in Windows byte order rather than RFC 9562-style UUID order.

Windows legacy GUID byte layout vs RFC 9562 UUID byte layout

The table below shows how GUID 00112233-4455-6677-8899-AABBCCDDEEFF is serialized as an RFC 9562 UUID versus a Windows GUID:

| UUID / GUID type | Serialized byte layout (hexadecimal) |
|-------------------------|---------------------------------------------------|
| RFC 9562 UUID layout | 00 11 22 33 44 55 66 77 88 99 AA BB CC DD EE FF |
| Windows GUID layout | 33 22 11 00 55 44 77 66 88 99 AA BB CC DD EE FF |

Windows legacy GUID layout reorders only the first three fields (32-bit, 16-bit, 16-bit). The remaining 8 bytes are stored as-is.

For RFC 9562 compliant UUIDs (network byte order), use uuid instead.

Installation

``bash
npm install win-guid
`

Usage

$3

Parses a canonical GUID string:
`js
import { parseWindowsGuid } from "win-guid";

const bytes = parseWindowsGuid("00020906-0000-0000-C000-000000000046");
`
into a 16-byte Uint8Array using Windows GUID byte order.
- Input is validated strictly
- Case-insensitive
- Throws an error on invalid input

$3

Creates a GUID from a canonical GUID string.
`js
import { Guid } from "win-guid";

const guid = Guid.fromString("00020906-0000-0000-C000-000000000046");
`

API

parseWindowsGuid(guid: string): Uint8Array

Parses a canonical GUID string:
`js
const bytes = parseWindowsGuid("00020906-0000-0000-C000-000000000046");
`

into a 16-byte Uint8Array using Windows GUID byte order.

- Input is validated strictly
- Case-insensitive
- Throws Error on invalid input

class Guid

Creates a GUID from a canonical GUID string.

`js
const guid = Guid.fromString("00020906-0000-0000-C000-000000000046");
`

guid.toString(): string

Converts the GUID back into the canonical string form.

- Always uppercase
- Round-trips cleanly with fromString

`js
guid.toString();
`
Outputs something like:
`
00020906-0000-0000-C000-000000000046
``

guid.bytes: Uint8Array

Provides access to the raw 16-byte GUID in Windows legacy GUID byte order.

`js
const bytes = guid.bytes;
``

Licence

This project is licensed under the MIT License. Feel free to use, modify, and distribute as needed.