@kyneta/random 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Duane Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+//#region src/index.d.ts
+/**
+ * Generate a random hex string from `n` cryptographically random bytes.
+ */
+declare function randomHex(byteCount: number): string;
+/**
+ * Generate a random peer ID — a 16-character hex string.
+ *
+ * Used as keys in CRDT version vectors, so must be unique
+ * but does not require cryptographic unpredictability.
+ */
+declare function randomPeerId(): string;
+//#endregion
+export { randomHex, randomPeerId };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;AAOA;;iBAAgB,SAAA,CAAU,SAAA;;;AAiB1B;;;;iBAAgB,YAAA,CAAA"}

package/dist/index.js

@@ -0,0 +1,25 @@
+//#region src/index.ts
+/**
+* Generate a random hex string from `n` cryptographically random bytes.
+*/
+function randomHex(byteCount) {
+	if (byteCount === 0) return "";
+	const bytes = new Uint8Array(byteCount);
+	crypto.getRandomValues(bytes);
+	let hex = "";
+	for (let i = 0; i < bytes.length; i++) hex += (bytes[i] ?? 0).toString(16).padStart(2, "0");
+	return hex;
+}
+/**
+* Generate a random peer ID — a 16-character hex string.
+*
+* Used as keys in CRDT version vectors, so must be unique
+* but does not require cryptographic unpredictability.
+*/
+function randomPeerId() {
+	return randomHex(8);
+}
+//#endregion
+export { randomHex, randomPeerId };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// Avoids crypto.randomUUID() which is restricted to secure contexts\n// (HTTPS or localhost) and throws on plain HTTP over LAN addresses.\n// crypto.getRandomValues() has no such restriction.\n\n/**\n * Generate a random hex string from `n` cryptographically random bytes.\n */\nexport function randomHex(byteCount: number): string {\n  if (byteCount === 0) return \"\"\n  const bytes = new Uint8Array(byteCount)\n  crypto.getRandomValues(bytes)\n  let hex = \"\"\n  for (let i = 0; i < bytes.length; i++) {\n    hex += (bytes[i] ?? 0).toString(16).padStart(2, \"0\")\n  }\n  return hex\n}\n\n/**\n * Generate a random peer ID — a 16-character hex string.\n *\n * Used as keys in CRDT version vectors, so must be unique\n * but does not require cryptographic unpredictability.\n */\nexport function randomPeerId(): string {\n  return randomHex(8)\n}\n"],"mappings":";;;;AAOA,SAAgB,UAAU,WAA2B;AACnD,KAAI,cAAc,EAAG,QAAO;CAC5B,MAAM,QAAQ,IAAI,WAAW,UAAU;AACvC,QAAO,gBAAgB,MAAM;CAC7B,IAAI,MAAM;AACV,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,IAChC,SAAQ,MAAM,MAAM,GAAG,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI;AAEtD,QAAO;;;;;;;;AAST,SAAgB,eAAuB;AACrC,QAAO,UAAU,EAAE"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kyneta/random",
+  "version": "1.5.0",
+  "description": "Secure-context-free random ID primitives for the kyneta monorepo",
+  "author": "Duane Johnson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halecraft/kyneta",
+    "directory": "packages/random"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./src": "./src/index.ts",
+    "./src/*": "./src/*"
+  },
+  "devDependencies": {
+    "tsdown": "^0.21.9",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "verify logic",
+    "verify": "verify"
+  }
+}

package/src/__tests__/random.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest"
+import { randomHex, randomPeerId } from "../index.js"
+
+describe("randomHex", () => {
+  it("returns a string of length 2n", () => {
+    for (const n of [1, 4, 8, 16, 32]) {
+      expect(randomHex(n).length).toBe(n * 2)
+    }
+  })
+
+  it("contains only lowercase hex characters", () => {
+    for (let i = 0; i < 20; i++) {
+      expect(randomHex(16)).toMatch(/^[0-9a-f]+$/)
+    }
+  })
+
+  it("returns empty string for zero bytes", () => {
+    expect(randomHex(0)).toBe("")
+  })
+
+  it("produces distinct values across 100 calls", () => {
+    const ids = new Set<string>()
+    for (let i = 0; i < 100; i++) {
+      ids.add(randomHex(8))
+    }
+    expect(ids.size).toBe(100)
+  })
+})
+
+describe("randomPeerId", () => {
+  it("returns a 16-char hex string", () => {
+    expect(randomPeerId()).toMatch(/^[0-9a-f]{16}$/)
+  })
+})

package/src/index.ts

@@ -0,0 +1,27 @@
+// Avoids crypto.randomUUID() which is restricted to secure contexts
+// (HTTPS or localhost) and throws on plain HTTP over LAN addresses.
+// crypto.getRandomValues() has no such restriction.
+
+/**
+ * Generate a random hex string from `n` cryptographically random bytes.
+ */
+export function randomHex(byteCount: number): string {
+  if (byteCount === 0) return ""
+  const bytes = new Uint8Array(byteCount)
+  crypto.getRandomValues(bytes)
+  let hex = ""
+  for (let i = 0; i < bytes.length; i++) {
+    hex += (bytes[i] ?? 0).toString(16).padStart(2, "0")
+  }
+  return hex
+}
+
+/**
+ * Generate a random peer ID — a 16-character hex string.
+ *
+ * Used as keys in CRDT version vectors, so must be unique
+ * but does not require cryptographic unpredictability.
+ */
+export function randomPeerId(): string {
+  return randomHex(8)
+}