fix(types): give ./main and the subpaths accurate type declarations

README.md

@@ -982,9 +982,9 @@ Full TypeScript definitions included for both custom and RFC UUID APIs:
 import { UUID } from "@cldmv/uuid";
 
 // Custom UUID specification (RFC-ready)
-const ta: string = UUID.TA();
-const tb: string = UUID.TB();
-const ia: string = UUID.IA(404);
+const ta: string = UUID.TA().toString();
+const tb: string = UUID.TB().toString();
+const ia: string = UUID.IA(404).toString();
 
 // Instance methods with proper types
 const uuid = new UUID(ta);
@@ -998,7 +998,7 @@ const category: string | null = uuid.getIssuerCategory();
 // Standard RFC UUIDs
 const v4: string = UUID.v4();
 const bytes: Uint8Array = UUID.parse(v4);
-const rfcVersion: number | null = UUID.version(v4);
+const rfcVersion: string | number | null = UUID.version(v4); // 4 here; "TA" / "TB" / "IA" for the custom variants
 ```
 
 ## Specification Documentation

package.json

@@ -12,6 +12,7 @@
 			"require": "./index.cjs"
 		},
 		"./main": {
+			"types": "./types/dist/uuid.d.mts",
 			"uuid-dev": {
 				"import": "./src/uuid.mjs"
 			},
@@ -22,27 +23,48 @@
 				"browser": "./src/lib/rng-browser.mjs",
 				"import": "./src/lib/rng.mjs"
 			},
-			"browser": "./dist/lib/rng-browser.mjs",
+			"browser": {
+				"types": "./types/dist/lib/rng-browser.d.mts",
+				"default": "./dist/lib/rng-browser.mjs"
+			},
+			"types": "./types/dist/lib/rng.d.mts",
 			"import": "./dist/lib/rng.mjs"
 		},
 		"./bytes": {
 			"uuid-dev": {
 				"browser": "./src/lib/bytes-browser.mjs",
 				"import": "./src/lib/bytes.mjs"
 			},
-			"browser": "./dist/lib/bytes-browser.mjs",
+			"browser": {
+				"types": "./types/dist/lib/bytes-browser.d.mts",
+				"default": "./dist/lib/bytes-browser.mjs"
+			},
+			"types": "./types/dist/lib/bytes.d.mts",
 			"import": "./dist/lib/bytes.mjs"
 		},
 		"./hash": {
 			"uuid-dev": {
 				"browser": "./src/lib/hash-browser.mjs",
 				"import": "./src/lib/hash.mjs"
 			},
-			"browser": "./dist/lib/hash-browser.mjs",
+			"browser": {
+				"types": "./types/dist/lib/hash-browser.d.mts",
+				"default": "./dist/lib/hash-browser.mjs"
+			},
+			"types": "./types/dist/lib/hash.d.mts",
 			"import": "./dist/lib/hash.mjs"
 		},
 		"./package.json": "./package.json"
 	},
+	"imports": {
+		"#bytes-type": {
+			"types": {
+				"browser": "./typings/bytes.d.mts",
+				"node": "./typings/bytes-node.d.mts",
+				"default": "./typings/bytes.d.mts"
+			}
+		}
+	},
 	"type": "module",
 	"engines": {
 		"node": ">=16.12.0"
@@ -53,10 +75,11 @@
 		"build:dist": "node -e \"const fs = require('fs'); const path = require('path'); fs.rmSync('dist', {recursive: true, force: true}); fs.mkdirSync('dist', {recursive: true}); fs.cpSync('src', 'dist', {recursive: true});\"",
 		"build:types": "node -e \"require('fs').rmSync('types', {recursive: true, force: true})\" && tsc --project .configs/tsconfig.dts.jsonc",
 		"demo": "node scripts/demo-custom-uuids.mjs",
-		"test": "node tests/run-vitest.mjs && npm run test:cjs",
+		"test": "node tests/run-vitest.mjs && npm run test:cjs && npm run test:types",
 		"test:cjs": "node --conditions=uuid-dev --test tests/cjs/entry.test.cjs",
+		"test:types": "npm run build && node --test tests/types/consumer.test.mjs",
 		"test:watch": "vitest --config .configs/vitest.config.mjs",
-		"coverage": "node tests/run-vitest.mjs --coverage-quiet && npm run test:cjs",
+		"coverage": "node tests/run-vitest.mjs --coverage-quiet && npm run test:cjs && npm run test:types",
 		"ci:coverage": "npm run coverage",
 		"fix:headers": "fix-headers --config .configs/fix-headers.json",
 		"types:build": "tsc -p .configs/tsconfig.dts.jsonc --noCheck",
@@ -112,13 +135,15 @@
 		"types/dist/",
 		"types/index.d.mts",
 		"types/index.d.mts.map",
+		"typings/",
 		"dist/"
 	],
 	"sideEffects": false,
 	"devDependencies": {
 		"@cldmv/configs": "^1.2.1",
 		"@cldmv/fix-headers": "^2.1.2",
 		"@cldmv/vitest-runner": "^1.2.0",
+		"@types/node": "^26.6.4",
 		"@vitest/coverage-v8": "^5.0.0",
 		"typescript": "^5.9.3",
 		"vitest": "^5.0.0"

src/lib/versions/rfc/utils.mjs

@@ -55,7 +55,7 @@ export function parse(uuid) {
 
 /**
  * Convert array of bytes to UUID string
- * @param {Uint8Array|Buffer|Array} bytes - 16-byte array
+ * @param {ArrayLike<number>} bytes - 16-byte array
  * @returns {string} UUID string with dashes
  * @example
  * stringify([110, 192, 189, 127, 17, 192, 67, 218, 151, 94, 42, 138, 217, 235, 174, 11]);

src/lib/versions/rfc/v1.mjs

@@ -24,13 +24,13 @@ import { stringify } from "./utils.mjs";
 
 /**
  * Create a version 1 (timestamp) UUID
- * @param {Object} options - Optional parameters
- * @param {Array} options.node - 6-byte node id (MAC address)
- * @param {number} options.clockseq - 14-bit clock sequence
- * @param {number} options.msecs - Timestamp in milliseconds since unix epoch
- * @param {number} options.nsecs - Additional 100-nanosecond intervals
- * @param {Uint8Array} options.buf - Buffer to write UUID into
- * @param {number} options.offset - Offset in buffer to start writing
+ * @param {object} [options] - Optional parameters
+ * @param {ArrayLike<number>} [options.node] - 6-byte node id (MAC address)
+ * @param {number} [options.clockseq] - 14-bit clock sequence
+ * @param {number} [options.msecs] - Timestamp in milliseconds since unix epoch
+ * @param {number} [options.nsecs] - Additional 100-nanosecond intervals
+ * @param {Uint8Array} [options.buf] - Buffer to write UUID into; when given, it is returned instead of a string
+ * @param {number} [options.offset] - Offset in buffer to start writing
  * @returns {string|Uint8Array} UUID string or buffer
  */
 export function v1(options = {}) {

src/lib/versions/rfc/v35.mjs

@@ -29,8 +29,8 @@ import { parse, stringify } from "./utils.mjs";
  * @param {string|Uint8Array} namespace - Namespace UUID
  * @param {number} versionByte - Version byte (0x30 for v3, 0x50 for v5)
  * @param {Function} hashFn - Isomorphic hash function (md5 or sha1), signature (namespaceBytes, name)
- * @param {Uint8Array} buf - Optional buffer to write into
- * @param {number} offset - Optional offset in buffer
+ * @param {Uint8Array} [buf] - Optional buffer to write into; when given, it is returned instead of a string
+ * @param {number} [offset] - Optional offset in buffer
  * @returns {string|Uint8Array} UUID string or buffer
  * @private
  */
@@ -67,8 +67,8 @@ function _v35(name, namespace, versionByte, hashFn, buf, offset) {
  * Create a version 3 (namespace with MD5) UUID
  * @param {string} name - Name to hash
  * @param {string|Uint8Array} namespace - Namespace UUID
- * @param {Uint8Array} buf - Optional buffer to write into
- * @param {number} offset - Optional offset in buffer
+ * @param {Uint8Array} [buf] - Optional buffer to write into; when given, it is returned instead of a string
+ * @param {number} [offset] - Optional offset in buffer
  * @returns {string|Uint8Array} UUID string or buffer
  */
 export function v3(name, namespace, buf, offset) {
@@ -79,8 +79,8 @@ export function v3(name, namespace, buf, offset) {
  * Create a version 5 (namespace with SHA-1) UUID
  * @param {string} name - Name to hash
  * @param {string|Uint8Array} namespace - Namespace UUID
- * @param {Uint8Array} buf - Optional buffer to write into
- * @param {number} offset - Optional offset in buffer
+ * @param {Uint8Array} [buf] - Optional buffer to write into; when given, it is returned instead of a string
+ * @param {number} [offset] - Optional offset in buffer
  * @returns {string|Uint8Array} UUID string or buffer
  */
 export function v5(name, namespace, buf, offset) {

src/lib/versions/rfc/v4.mjs

@@ -24,10 +24,10 @@ import { stringify } from "./utils.mjs";
 
 /**
  * Create a version 4 (random) UUID
- * @param {Object} options - Optional parameters
- * @param {Uint8Array} options.random - 16 random bytes
- * @param {Uint8Array} options.buf - Buffer to write UUID into
- * @param {number} options.offset - Offset in buffer to start writing
+ * @param {object} [options] - Optional parameters
+ * @param {Uint8Array} [options.random] - 16 random bytes
+ * @param {Uint8Array} [options.buf] - Buffer to write UUID into; when given, it is returned instead of a string
+ * @param {number} [options.offset] - Offset in buffer to start writing
  * @returns {string|Uint8Array} UUID string or buffer
  */
 export function v4(options = {}) {

src/lib/versions/rfc/v6.mjs

@@ -25,13 +25,13 @@ import { stringify } from "./utils.mjs";
 
 /**
  * Create a version 6 (timestamp, reordered) UUID
- * @param {Object} options - Optional parameters
- * @param {Array} options.node - 6-byte node id (MAC address)
- * @param {number} options.clockseq - 14-bit clock sequence
- * @param {number} options.msecs - Timestamp in milliseconds since unix epoch
- * @param {number} options.nsecs - Additional 100-nanosecond intervals
- * @param {Uint8Array} options.buf - Buffer to write UUID into
- * @param {number} options.offset - Offset in buffer to start writing
+ * @param {object} [options] - Optional parameters
+ * @param {ArrayLike<number>} [options.node] - 6-byte node id (MAC address)
+ * @param {number} [options.clockseq] - 14-bit clock sequence
+ * @param {number} [options.msecs] - Timestamp in milliseconds since unix epoch
+ * @param {number} [options.nsecs] - Additional 100-nanosecond intervals
+ * @param {Uint8Array} [options.buf] - Buffer to write UUID into; when given, it is returned instead of a string
+ * @param {number} [options.offset] - Offset in buffer to start writing
  * @returns {string|Uint8Array} UUID string or buffer
  */
 export function v6(options = {}) {

src/lib/versions/rfc/v7.mjs

@@ -25,10 +25,10 @@ import { stringify } from "./utils.mjs";
 
 /**
  * Create a version 7 (Unix Epoch time-based) UUID
- * @param {Object} options - Optional parameters
- * @param {number} options.msecs - Timestamp in milliseconds since unix epoch
- * @param {Uint8Array} options.buf - Buffer to write UUID into
- * @param {number} options.offset - Offset in buffer to start writing
+ * @param {object} [options] - Optional parameters
+ * @param {number} [options.msecs] - Timestamp in milliseconds since unix epoch
+ * @param {Uint8Array} [options.buf] - Buffer to write UUID into; when given, it is returned instead of a string
+ * @param {number} [options.offset] - Offset in buffer to start writing
  * @returns {string|Uint8Array} UUID string or buffer
  */
 export function v7(options = {}) {

src/lib/versions/rfc/v8.mjs

@@ -26,10 +26,10 @@ import { stringify } from "./utils.mjs";
 
 /**
  * Create a version 8 (custom/experimental) UUID
- * @param {Object} options - Optional parameters
- * @param {Uint8Array} options.data - Custom data to fill the UUID (16 bytes)
- * @param {Uint8Array} options.buf - Buffer to write UUID into
- * @param {number} options.offset - Offset in buffer to start writing
+ * @param {object} [options] - Optional parameters
+ * @param {Uint8Array} [options.data] - Custom data to fill the UUID (16 bytes)
+ * @param {Uint8Array} [options.buf] - Buffer to write UUID into; when given, it is returned instead of a string
+ * @param {number} [options.offset] - Offset in buffer to start writing
  * @returns {string|Uint8Array} UUID string or buffer
  * @example
  * // Generate with random data