win-guid

library0.2.1jsnpmunverified

win-guid is a JavaScript/TypeScript module designed for encoding and decoding Windows legacy GUIDs, which adhere to a mixed-endianness byte layout distinct from RFC 9562 UUIDs. This format is crucial when working with various Microsoft and firmware standards, including COM, OLE, CFBF (Structured Storage), GPT, UEFI, Windows Registry, and Active Directory objectGUID values. The package provides utilities to parse canonical GUID strings into `Uint8Array`s and a `Guid` helper class for object-oriented manipulation. The current stable version is 0.2.1, with recent updates focusing on minor bug fixes and documentation improvements. It explicitly differentiates itself from RFC 9562 UUID libraries (like `uuidjs/uuid`) by handling the specific Windows byte order reordering in the first three fields, making it indispensable for interoperability with binary Microsoft formats.

serialization http-networking

npm install win-guid

github ↗package ↗

INSTALL

IMPORT

SIG · WIN-GUID

win-guid

serializationjavascriptv0.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parseWindowsGuid

✓ import { parseWindowsGuid } from 'win-guid';

✗ const parseWindowsGuid = require('win-guid').parseWindowsGuid;

The package is primarily designed for ESM, but CommonJS can import named exports. Ensure your project is configured for ESM or use dynamic import/bundler.

Guid

✓ import { Guid } from 'win-guid';

✗ import Guid from 'win-guid';

Guid is a named export, not a default export.

Guid.fromString

✓ import { Guid } from 'win-guid'; const guid = Guid.fromString('...');

✗ import { fromString } from 'win-guid'; const guid = fromString('...');

The `fromString` method is a static method of the `Guid` class, not a top-level export.

Demonstrates parsing a Windows legacy GUID string into a byte array, creating a `Guid` object, accessing its bytes, and converting it back to a string.

import { parseWindowsGuid, Guid } from 'win-guid'; // Example GUID from Microsoft's OLE Compound File (CFBF) format const windowsGuidString = "00020810-0000-0000-C000-000000000046"; // Parse a GUID string into a 16-byte Uint8Array (Windows byte order) const bytes = parseWindowsGuid(windowsGuidString); console.log('Parsed bytes (Windows order):', Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join(' ')); // Expected: 10 08 02 00 00 00 00 00 c0 00 00 00 00 00 00 46 // Use the Guid helper class const guidInstance = Guid.fromString(windowsGuidString); // Access the raw bytes from the Guid instance console.log('Guid instance bytes:', Array.from(guidInstance.bytes).map(b => b.toString(16).padStart(2, '0')).join(' ')); // Convert the Guid instance back to its canonical string form const canonicalString = guidInstance.toString(); console.log('Canonical string:', canonicalString); // Expected: 00020810-0000-0000-C000-000000000046 // Demonstrate the difference with RFC 9562 UUID byte order concept // If this were an RFC 9562 UUID, the initial bytes would be different. // For '00112233-4455-6677-8899-AABBCCDDEEFF': // 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

Debug

Known issues

breakingVersion 0.2.1 fixed an invalid CommonJS `main` property. This might affect projects that were previously relying on an incorrect CommonJS entry point for `require()`-style imports. Projects specifically targeting CommonJS might need to adjust their import statements or bundling configurations.

fix

Ensure your environment is set up for ESM imports (e.g., `type: module` in `package.json`, `.mjs` files) or use dynamic `import()` for CommonJS contexts. If encountering issues, verify bundler configuration for ESM compatibility.

affects: >=0.2.1

gotchaThis library specifically handles Windows legacy GUID byte layout, which has a mixed-endianness format for the first three components (Data1, Data2, Data3). This is distinct from the network byte order (big-endian) used by RFC 9562 UUIDs.

fix

Always be mindful of the byte order when converting to or from other UUID/GUID representations. If working with RFC 9562 compliant UUIDs (e.g., for standard HTTP headers), use a library like `uuid` instead of `win-guid`. This library is for specific Windows binary formats.

affects: >=0.1.0

gotchaThe parsing functions (`parseWindowsGuid`, `Guid.fromString`) perform strict validation of the input GUID string format. Any deviation from the canonical `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` pattern will result in an error.

fix

Ensure all input GUID strings adhere to the strict canonical format. Pre-process or validate input strings if they might come in non-standard formats (e.g., with braces, different separators, or incorrect lengths).

affects: >=0.1.0

Errors

Common errors & fixes

Error: Invalid GUID string format

The input string passed to `parseWindowsGuid` or `Guid.fromString` did not match the expected canonical GUID pattern.

fix

Check the input string for correct hyphen placement, hexadecimal character validity, and length. It must be `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.

TypeError: Guid is not a constructor (or similar import error in CJS)

Attempting to `require('win-guid')` and use named exports as direct properties in a CommonJS context, or incorrect ESM import syntax.

fix

For ESM, use `import { Guid } from 'win-guid';`. For CommonJS, after v0.2.1, it's generally recommended to use dynamic `import()` for ESM-first packages or ensure your bundler properly transpiles. If directly `require`ing, access named exports: `const { Guid } = require('win-guid');`.

Incorrect byte order when comparing with another UUID library

Confusing Windows legacy GUID byte layout with RFC 9562 UUID (network byte order).

fix

Remember that `win-guid` specifically implements the mixed-endian Windows byte order. If you're comparing against a standard UUID, ensure you're accounting for the byte reordering in the first 8 bytes (Data1, Data2, Data3) or convert the `win-guid` output to RFC 9562 order manually if necessary for specific comparisons.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Borewit/win-guid ↗

packagehttps://www.npmjs.com/package/win-guid ↗