win-guid

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

npm install win-guid

Usage

Parse a GUID string

Parses a canonical GUID string:

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

Use the Guid helper class

Creates a GUID from a canonical GUID string.

import { Guid } from "win-guid";

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

API

parseWindowsGuid(guid: string): Uint8Array

Parses a canonical GUID string:

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.

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

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.

const bytes = guid.bytes;

Licence

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