win-guid

A module for decoding and encoding Windows GUIDs in the Windows GUID byte layout used by COM, OLE, and Compound File Binary Format (CFBF), and converting them back to the canonical string form when needed.

This is useful when dealing with Microsoft file formats such as .asf, .doc, .xls, .ppt, OLE/COM Structured Storage (CFBF), or other binary formats that store GUIDs in Windows order.

Windows 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 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

import { parseWindowsGuid } from "win-guid";

const bytes = parseWindowsGuid("00020906-0000-0000-C000-000000000046");

// Uint8Array(16) in Windows GUID byte order

Use the Guid helper class

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 / CFBF byte order.

Notes:

• The returned value is a Uint8Array(16)
• It represents the Windows GUID byte layout (as stored in COM, OLE, CFBF, and related formats)

const bytes = guid.bytes;

Licence

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