{"id":14352,"library":"win-guid","title":"Windows Legacy GUID Parser","description":"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.","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/Borewit/win-guid","tags":["javascript","GUID","Windows","COM","CFBF","registry","UEFI","objectGUID","GPT"],"install":[{"cmd":"npm install win-guid","lang":"bash","label":"npm"},{"cmd":"yarn add win-guid","lang":"bash","label":"yarn"},{"cmd":"pnpm add win-guid","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const parseWindowsGuid = require('win-guid').parseWindowsGuid;","symbol":"parseWindowsGuid","correct":"import { parseWindowsGuid } from 'win-guid';"},{"note":"Guid is a named export, not a default export.","wrong":"import Guid from 'win-guid';","symbol":"Guid","correct":"import { Guid } from 'win-guid';"},{"note":"The `fromString` method is a static method of the `Guid` class, not a top-level export.","wrong":"import { fromString } from 'win-guid'; const guid = fromString('...');","symbol":"Guid.fromString","correct":"import { Guid } from 'win-guid'; const guid = Guid.fromString('...');"}],"quickstart":{"code":"import { parseWindowsGuid, Guid } from 'win-guid';\n\n// Example GUID from Microsoft's OLE Compound File (CFBF) format\nconst windowsGuidString = \"00020810-0000-0000-C000-000000000046\";\n\n// Parse a GUID string into a 16-byte Uint8Array (Windows byte order)\nconst bytes = parseWindowsGuid(windowsGuidString);\nconsole.log('Parsed bytes (Windows order):', Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join(' '));\n// Expected: 10 08 02 00 00 00 00 00 c0 00 00 00 00 00 00 46\n\n// Use the Guid helper class\nconst guidInstance = Guid.fromString(windowsGuidString);\n\n// Access the raw bytes from the Guid instance\nconsole.log('Guid instance bytes:', Array.from(guidInstance.bytes).map(b => b.toString(16).padStart(2, '0')).join(' '));\n\n// Convert the Guid instance back to its canonical string form\nconst canonicalString = guidInstance.toString();\nconsole.log('Canonical string:', canonicalString);\n// Expected: 00020810-0000-0000-C000-000000000046\n\n// Demonstrate the difference with RFC 9562 UUID byte order concept\n// If this were an RFC 9562 UUID, the initial bytes would be different.\n// For '00112233-4455-6677-8899-AABBCCDDEEFF':\n// RFC 9562 UUID layout: 00 11 22 33 44 55 66 77 88 99 AA BB CC DD EE FF\n// Windows GUID layout:  33 22 11 00 55 44 77 66 88 99 AA BB CC DD EE FF\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=0.2.1"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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).","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'0.2.1':88 '9562':32,106 'activ':57 'adher':21 'binari':130 'bug':95 'byte':27,116 'canon':67 'cfbf':49,137 'class':77 'com':47,136 'crucial':37 'current':84 'decod':16 'design':12 'differenti':102 'directori':58 'distinct':29 'document':98 'encod':14 'endian':26 'explicit':101 'field':123 'firmwar':44 'first':121 'fix':96 'focus':92 'format':35,132 'gpt':52,141 'guid':3,7,19,68,75,134 'handl':112 'helper':76 'improv':99 'includ':46 'indispens':126 'interoper':128 'javascript':133 'javascript/typescript':10 'layout':28 'legaci':2,18 'librari':108 'like':109 'make':124 'manipul':82 'microsoft':42,131 'minor':94 'mix':25 'mixed-endian':24 'modul':11 'object':80 'object-ori':79 'objectguid':59,140 'ole':48 'order':117 'orient':81 'packag':62 'pars':66 'parser':4 'provid':63 'recent':90 'registri':55,138 'reorder':118 'rfc':31,105 'specif':114 'stabl':85 'standard':45 'storag':51 'string':69 'structur':50 'three':122 'uefi':53,139 'uint8array':71 'updat':91 'util':64 'uuid':33,107 'uuidjs/uuid':110 'valu':60 'various':41 'version':86 'win':6 'win-guid':5 'window':1,17,54,115,135 'work':39","created_at":"2026-04-20T01:59:15.980350+00:00","updated_at":"2026-04-20T01:59:15.980350+00:00","problems":[{"fix":"Check the input string for correct hyphen placement, hexadecimal character validity, and length. It must be `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.","cause":"The input string passed to `parseWindowsGuid` or `Guid.fromString` did not match the expected canonical GUID pattern.","error":"Error: Invalid GUID string format"},{"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');`.","cause":"Attempting to `require('win-guid')` and use named exports as direct properties in a CommonJS context, or incorrect ESM import syntax.","error":"TypeError: Guid is not a constructor (or similar import error in CJS)"},{"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.","cause":"Confusing Windows legacy GUID byte layout with RFC 9562 UUID (network byte order).","error":"Incorrect byte order when comparing with another UUID library"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/Borewit/win-guid","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/win-guid","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}