win-guid 0.1.3 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +37 -9
  2. package/lib/guid.d.ts +1 -1
  3. package/package.json +55 -48
package/README.md CHANGED
@@ -4,14 +4,33 @@
4
4
 
5
5
  # win-guid
6
6
 
7
- Small, dependency-free utility for working with **Windows / CFBF GUIDs** in JavaScript and TypeScript.
7
+ A module for encoding and decoding **Windows legacy GUIDs** using the **Windows GUID byte layout**,
8
+ a mixed-endianness format used by several long-standing Microsoft and firmware standards, including:
8
9
 
9
- It parses canonical GUID strings into the **Windows byte layout** used by COM, OLE, and Compound File Binary Format (CFBF), and converts them back to the standard string form when needed.
10
+ - [Component Object Model (COM)](https://en.wikipedia.org/wiki/Component_Object_Model)
11
+ - [Object Linking and Embedding (OLE)](https://en.wikipedia.org/wiki/Object_Linking_and_Embedding)
12
+ - [Compound File Binary Format (CFBF, Structured Storage)](https://en.wikipedia.org/wiki/Compound_File_Binary_Format)
13
+ - [GUID Partition Table (GPT)](https://en.wikipedia.org/wiki/GUID_Partition_Table)
14
+ - [Unified Extensible Firmware Interface (UEFI)](https://en.wikipedia.org/wiki/UEFI)
15
+ - [Windows Registry](https://en.wikipedia.org/wiki/Windows_Registry) binary GUID values
16
+ - [Active Directory](https://en.wikipedia.org/wiki/Active_Directory) objectGUID values
10
17
 
11
- This is useful when dealing with Microsoft file formats such as `.asf`, `.doc,`, `.xls`, `.ppt`, structured storage,
12
- or other binary formats that store GUIDs in little-endian Windows order.
18
+ This is commonly needed when working with Microsoft file and storage formats, such as `.asf`, `.doc`, `.xls`, `.ppt`,
19
+ and other binary formats based on OLE/COM Structured Storage (CFBF),
20
+ where GUIDs are stored in Windows byte order rather than [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html)-style UUID order.
13
21
 
14
- For RFC9562 compliant UUIDs (network byte order), use [uuid](https://github.com/uuidjs/uuid) instead.
22
+ ## Windows legacy GUID byte layout vs RFC 9562 UUID byte layout
23
+
24
+ The table below shows how GUID `00112233-4455-6677-8899-AABBCCDDEEFF` is serialized as an [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html) UUID versus a Windows GUID:
25
+
26
+ | UUID / GUID type | Serialized byte layout (hexadecimal) |
27
+ |-------------------------|---------------------------------------------------|
28
+ | RFC 9562 UUID layout | `00 11 22 33 44 55 66 77 88 99 AA BB CC DD EE FF` |
29
+ | Windows GUID layout | `33 22 11 00 55 44 77 66 88 99 AA BB CC DD EE FF` |
30
+
31
+ Windows legacy GUID layout reorders only the first three fields (32-bit, 16-bit, 16-bit). The remaining 8 bytes are stored as-is.
32
+
33
+ For [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html) compliant UUIDs (network byte order), use [uuid](https://github.com/uuidjs/uuid) instead.
15
34
 
16
35
  ## Installation
17
36
 
@@ -23,16 +42,20 @@ npm install win-guid
23
42
 
24
43
  ### Parse a GUID string
25
44
 
45
+ Parses a canonical GUID string:
26
46
  ```js
27
47
  import { parseWindowsGuid } from "win-guid";
28
48
 
29
49
  const bytes = parseWindowsGuid("00020906-0000-0000-C000-000000000046");
30
-
31
- // Uint8Array(16) in Windows / CFBF byte order
32
50
  ```
51
+ into a 16-byte Uint8Array using Windows GUID byte order.
52
+ - Input is validated strictly
53
+ - Case-insensitive
54
+ - Throws an error on invalid input
33
55
 
34
56
  ### Use the Guid helper class
35
57
 
58
+ Creates a GUID from a canonical GUID string.
36
59
  ```js
37
60
  import { Guid } from "win-guid";
38
61
 
@@ -48,7 +71,7 @@ Parses a canonical GUID string:
48
71
  const bytes = parseWindowsGuid("00020906-0000-0000-C000-000000000046");
49
72
  ```
50
73
 
51
- into a 16-byte Uint8Array using Windows / CFBF byte order.
74
+ into a 16-byte `Uint8Array` using Windows GUID byte order.
52
75
 
53
76
  - Input is validated strictly
54
77
  - Case-insensitive
@@ -71,14 +94,19 @@ Converts the GUID back into the canonical string form.
71
94
 
72
95
  ```js
73
96
  guid.toString();
74
- ````
97
+ ```
75
98
  Outputs something like:
76
99
  ```
77
100
  00020906-0000-0000-C000-000000000046`
78
101
  ```
79
102
 
103
+ `guid.bytes: Uint8Array`
80
104
 
105
+ Provides access to the raw 16-byte GUID in Windows legacy GUID byte order.
81
106
 
107
+ ```js
108
+ const bytes = guid.bytes;
109
+ ```
82
110
 
83
111
  ## Licence
84
112
 
package/lib/guid.d.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  */
5
5
  export declare function parseWindowsGuid(guid: string): Uint8Array;
6
6
  export declare class Guid {
7
- private readonly bytes;
7
+ readonly bytes: Uint8Array;
8
8
  constructor(bytes: Uint8Array);
9
9
  static fromString(guid: string): Guid;
10
10
  /**
package/package.json CHANGED
@@ -1,48 +1,55 @@
1
- {
2
- "name": "win-guid",
3
- "version": "0.1.3",
4
- "description": "Windows GUID",
5
- "type": "module",
6
- "exports": "./lib/guid.js",
7
- "scripts": {
8
- "clean": "del-cli 'lib/**/*.js' 'lib/**/*.js.map' 'lib/**/*.d.ts' 'src/**/*.d.ts'",
9
- "compile-src": "tsc -p lib",
10
- "compile": "yarn run compile-src",
11
- "format": "biome format",
12
- "lint:ts": "biome check",
13
- "build": "yarn run clean && yarn run compile",
14
- "test": "mocha",
15
- "prepublishOnly": "yarn run build",
16
- "update-biome": "yarn add -D --exact @biomejs/biome && npx @biomejs/biome migrate --write"
17
- },
18
- "files": [
19
- "lib/**/*.js",
20
- "lib/**/*.d.ts",
21
- "lib/*.cjs"
22
- ],
23
- "author": {
24
- "name": "Borewit",
25
- "url": "https://github.com/Borewit"
26
- },
27
- "repository": {
28
- "type": "git",
29
- "url": "git+https://github.com/Borewit/win-guid.git"
30
- },
31
- "license": "MIT",
32
- "devDependencies": {
33
- "@types/chai": "^5.2.3",
34
- "@types/mocha": "^10.0.10",
35
- "biome": "^0.3.3",
36
- "chai": "^6.2.2",
37
- "del-cli": "^7.0.0",
38
- "mocha": "^11.7.5",
39
- "typescript": "^5.9.3"
40
- },
41
- "main": "index.js",
42
- "packageManager": "yarn@4.9.1",
43
- "keywords": [
44
- "GUID",
45
- "Windows",
46
- "COM"
47
- ]
48
- }
1
+ {
2
+ "name": "win-guid",
3
+ "version": "0.2.1",
4
+ "description": "Windows legacy GUID parser",
5
+ "type": "module",
6
+ "exports": "./lib/guid.js",
7
+ "scripts": {
8
+ "clean": "del-cli 'lib/**/*.js' 'lib/**/*.js.map' 'lib/**/*.d.ts' 'src/**/*.d.ts'",
9
+ "compile-src": "tsc -p lib",
10
+ "compile": "yarn run compile-src",
11
+ "format": "biome format",
12
+ "lint:ts": "biome check",
13
+ "build": "yarn run clean && yarn run compile",
14
+ "test": "mocha",
15
+ "prepublishOnly": "yarn run build",
16
+ "update-biome": "yarn add -D --exact @biomejs/biome && npx @biomejs/biome migrate --write"
17
+ },
18
+ "files": [
19
+ "lib/**/*.js",
20
+ "lib/**/*.d.ts",
21
+ "lib/*.cjs"
22
+ ],
23
+ "author": {
24
+ "name": "Borewit",
25
+ "url": "https://github.com/Borewit"
26
+ },
27
+ "repository": {
28
+ "type": "git",
29
+ "url": "git+https://github.com/Borewit/win-guid.git"
30
+ },
31
+ "license": "MIT",
32
+ "devDependencies": {
33
+ "@types/chai": "^5.2.3",
34
+ "@types/mocha": "^10.0.10",
35
+ "biome": "^0.3.3",
36
+ "chai": "^6.2.2",
37
+ "del-cli": "^7.0.0",
38
+ "mocha": "^11.7.5",
39
+ "typescript": "^5.9.3"
40
+ },
41
+ "packageManager": "yarn@4.9.1",
42
+ "keywords": [
43
+ "GUID",
44
+ "Windows",
45
+ "COM",
46
+ "CFBF",
47
+ "registry",
48
+ "UEFI",
49
+ "objectGUID",
50
+ "GPT",
51
+ "endianness",
52
+ "OLE",
53
+ "binary"
54
+ ]
55
+ }