@hkdigital/lib-core 0.5.16 → 0.5.17

package/dist/util/expect/values.d.ts

@@ -12,7 +12,7 @@ export function expect_notNull(value: any): void;
  */
 export function expect_true(value: any): void;
 /**
- * Expect a positive number
+ * Expect a positive number (greater than zero)
  *
  * @param {any} value
  */

package/dist/util/expect/values.js

@@ -23,12 +23,15 @@ export function expect_true(value) {
 export { expect_true as true };
 
 /**
- * Expect a positive number
+ * Expect a positive number (greater than zero)
  *
  * @param {any} value
  */
 export function expect_positiveNumber(value) {
-	const schema = v.pipe(v.number(), v.minValue(0));
+	const schema = v.pipe(
+		v.number(),
+		v.custom((val) => val > 0, 'Invalid value: Expected number > 0')
+	);
 	v.parse(schema, value);
 }
 

package/dist/util/random/bytes.js

@@ -27,6 +27,7 @@ export function randomBytes(length) {
     try {
       const { randomBytes: nodeRandomBytes } = require('crypto');
       return new Uint8Array(nodeRandomBytes(length));
+      // eslint-disable-next-line no-unused-vars
     } catch (error) {
       throw new Error('No secure random generator available');
     }
@@ -66,7 +67,9 @@ export function randomBytesBase64(length) {
  */
 export function randomBytesHex(length) {
   const bytes = randomBytes(length);
-  
+
   // Convert to hex string
-  return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
-}
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join(
+    ''
+  );
+}

package/dist/util/random/uuid.d.ts

@@ -0,0 +1,22 @@
+/**
+ * uuid.js
+ *
+ * @description
+ * Cross-platform UUID generation utilities using Web Crypto API
+ */
+/**
+ * Generate a cryptographically secure random UUID v4
+ * - Uses Web Crypto API (works in Node.js 16+ and all modern browsers)
+ * - Returns RFC 4122 compliant UUID v4 string
+ * - Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ *   where x is any hexadecimal digit and y is one of 8, 9, A, or B
+ *
+ * @returns {string} UUID v4 string (e.g., "a1b2c3d4-e5f6-4890-abcd-ef1234567890")
+ *
+ * @example
+ * import { randomUUID } from './uuid.js';
+ *
+ * const id = randomUUID();
+ * // Returns: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+ */
+export function randomUUID(): string;

package/dist/util/random/uuid.js

@@ -0,0 +1,59 @@
+/**
+ * uuid.js
+ *
+ * @description
+ * Cross-platform UUID generation utilities using Web Crypto API
+ */
+
+/**
+ * Generate a cryptographically secure random UUID v4
+ * - Uses Web Crypto API (works in Node.js 16+ and all modern browsers)
+ * - Returns RFC 4122 compliant UUID v4 string
+ * - Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ *   where x is any hexadecimal digit and y is one of 8, 9, A, or B
+ *
+ * @returns {string} UUID v4 string (e.g., "a1b2c3d4-e5f6-4890-abcd-ef1234567890")
+ *
+ * @example
+ * import { randomUUID } from './uuid.js';
+ *
+ * const id = randomUUID();
+ * // Returns: "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+ */
+export function randomUUID() {
+  // Try native crypto.randomUUID first (most efficient)
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+    // Modern browsers + Node.js 16.7.0+
+    return crypto.randomUUID();
+  }
+
+  // Fallback: Manual UUID v4 generation using crypto.getRandomValues
+  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+    // Generate 16 random bytes
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+
+    // Set version (4) and variant bits according to RFC 4122
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // Version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant 10
+
+    // Convert to UUID string format
+    const hex = Array.from(bytes, (byte) =>
+      byte.toString(16).padStart(2, '0')
+    ).join('');
+
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+  }
+
+  // Fallback for older Node.js environments
+  if (typeof require !== 'undefined') {
+    try {
+      const { randomUUID: nodeRandomUUID } = require('crypto');
+      return nodeRandomUUID();
+      // eslint-disable-next-line no-unused-vars
+    } catch (error) {
+      // Fall through to error
+    }
+  }
+
+  throw new Error('No secure random UUID generator available');
+}

package/dist/util/random.d.ts

@@ -1 +1,2 @@
 export * from "./random/bytes.js";
+export * from "./random/uuid.js";

package/dist/util/random.js

@@ -6,4 +6,5 @@
  * using the Web Crypto API for maximum compatibility.
  */
 
-export * from './random/bytes.js';
+export * from './random/bytes.js';
+export * from './random/uuid.js';

package/dist/util/unique/index.d.ts

@@ -44,16 +44,34 @@ export function randomAccessCode(): string;
  */
 export function generateClientSessionId(): string;
 /**
- * Generate an id that can used to identify a server
- * - Output format: <base58-time-based> + <random-chars>
- * - The ID will be generated only once,
+ * Get or generate an id that can be used to identify a client or server instance
+ * - Output format: <length-prefix><base58-time-based><random-chars>
+ * - Length prefix is the base58 encoded length of the time-based component
+ * - Higher entropy than the old serverId for global uniqueness
+ * - The ID is generated only once per session/boot and cached
  *
- * @param {number} [randomSize=8] - Number of random base58 characters
+ * @param {number} [randomSize=16] - Number of random base58 characters
  * @param {boolean} [reset=false] - Reset the previously generated id
  *
- * @returns {string} server id
+ * @returns {string} instance id
  */
-export function generateServerId(randomSize?: number, reset?: boolean): string;
+export function generateOrGetInstanceId(randomSize?: number, reset?: boolean): string;
+/**
+ * Generates and returns a new unique global id
+ * - The generated id is guaranteed to be globally unique across different
+ *   clients/servers/systems
+ * - Format: <length-prefix><instance-id><local-id>
+ * - Length prefix is the base58 encoded length of the instance ID + local ID
+ * - Optimized for high-frequency generation (thousands per second)
+ * - Instance ID provides ~94 bits of entropy (16 random base58 chars)
+ * - Local ID uses efficient counter mechanism for same-window uniqueness
+ *
+ * @param {number} [timeMs]
+ *   Custom time value to be used instead of Date.now()
+ *
+ * @returns {string} global id
+ */
+export function generateGlobalId(timeMs?: number): string;
 /**
  * Generates and returns a new unique local id
  * - The generated id is garanteed to be unique on the currently running
@@ -74,6 +92,23 @@ export function generateLocalId(timeMs?: number): string;
  * @returns {number} time based numerical that changes every 30 seconds
  */
 export function getTimeBasedNumber30s(timeMs?: number): number;
+/**
+ * Returns a time based base58 encoded string that changes every 30 seconds
+ *
+ * - Output length grows over time as the number increases
+ * - Starting from TIME_2025_01_01 (January 1, 2025)
+ * - After 1 month: ~3 characters
+ * - After 1 year: ~4 characters
+ * - After 5 years: ~4 characters
+ * - After 10 years: ~5 characters
+ * - After 100 years: ~6 characters
+ *
+ * @param {number} [timeMs=sinceMs()]
+ *   Custom time value to be used instead of sinceMs()
+ *
+ * @returns {string} base58 encoded time based value
+ */
+export function getTimeBasedNumber30sBase58(timeMs?: number): string;
 /**
  * Returns two character base58 encoded string that changes every 10
  * milliseconds

package/dist/util/unique/index.js

@@ -31,7 +31,7 @@ import { sinceMs } from '../time';
 /**
  * @type {{
  *   bootTimePrefix?:string,
- *   serverId?: string,
+ *   instanceId?: string,
  *   lastTimeBasedNumber?: number,
  *   lastTimeBasedValue58?: string,
  *   lastCountBasedNumber?: number
@@ -128,23 +128,52 @@ export function generateClientSessionId() {
 }
 
 /**
- * Generate an id that can used to identify a server
- * - Output format: <base58-time-based> + <random-chars>
- * - The ID will be generated only once,
+ * Get or generate an id that can be used to identify a client or server instance
+ * - Output format: <length-prefix><base58-time-based><random-chars>
+ * - Length prefix is the base58 encoded length of the time-based component
+ * - Higher entropy than the old serverId for global uniqueness
+ * - The ID is generated only once per session/boot and cached
  *
- * @param {number} [randomSize=8] - Number of random base58 characters
+ * @param {number} [randomSize=16] - Number of random base58 characters
  * @param {boolean} [reset=false] - Reset the previously generated id
  *
- * @returns {string} server id
+ * @returns {string} instance id
  */
-export function generateServerId(randomSize = 8, reset=false) {
-  if (!vars.serverId || reset) {
-    vars.serverId =
-      base58fromNumber(getTimeBasedNumber30s()) +
+export function generateOrGetInstanceId(randomSize = 16, reset = false) {
+  if (!vars.instanceId || reset) {
+    const timeBasedPart = getTimeBasedNumber30sBase58();
+    const lengthPrefix = base58fromNumber(timeBasedPart.length);
+
+    vars.instanceId =
+      lengthPrefix +
+      timeBasedPart +
       randomStringBase58(randomSize);
   }
 
-  return vars.serverId;
+  return vars.instanceId;
+}
+
+/**
+ * Generates and returns a new unique global id
+ * - The generated id is guaranteed to be globally unique across different
+ *   clients/servers/systems
+ * - Format: <length-prefix><instance-id><local-id>
+ * - Length prefix is the base58 encoded length of the instance ID + local ID
+ * - Optimized for high-frequency generation (thousands per second)
+ * - Instance ID provides ~94 bits of entropy (16 random base58 chars)
+ * - Local ID uses efficient counter mechanism for same-window uniqueness
+ *
+ * @param {number} [timeMs]
+ *   Custom time value to be used instead of Date.now()
+ *
+ * @returns {string} global id
+ */
+export function generateGlobalId(timeMs) {
+  const instanceId = generateOrGetInstanceId();
+  const localId = generateLocalId(timeMs);
+  const lengthPrefix = base58fromNumber(instanceId.length + localId.length);
+
+  return lengthPrefix + instanceId + localId;
 }
 
 /**
@@ -180,7 +209,7 @@ export function generateLocalId(timeMs) {
     // -- Same time stamp based number -> increment counter
 
     countBasedNumber = vars.lastCountBasedNumber =
-      vars.lastCountBasedNumber + 1;
+      (vars.lastCountBasedNumber ?? 0) + 1;
 
     // -- Use cached lastTimeBasedNumber
 
@@ -197,6 +226,7 @@ export function generateLocalId(timeMs) {
   const id =
     // idFormatPrefix
     bootTimePrefix() +
+    // @ts-ignore
     ALPHABET_BASE_58[timeBasedValue58.length] +
     timeBasedValue58 +
     countBasedValue58;
@@ -223,6 +253,26 @@ export function getTimeBasedNumber30s(timeMs) {
   return Math.floor(timeMs / 30000);
 }
 
+/**
+ * Returns a time based base58 encoded string that changes every 30 seconds
+ *
+ * - Output length grows over time as the number increases
+ * - Starting from TIME_2025_01_01 (January 1, 2025)
+ * - After 1 month: ~3 characters
+ * - After 1 year: ~4 characters
+ * - After 5 years: ~4 characters
+ * - After 10 years: ~5 characters
+ * - After 100 years: ~6 characters
+ *
+ * @param {number} [timeMs=sinceMs()]
+ *   Custom time value to be used instead of sinceMs()
+ *
+ * @returns {string} base58 encoded time based value
+ */
+export function getTimeBasedNumber30sBase58(timeMs) {
+  return base58fromNumber(getTimeBasedNumber30s(timeMs));
+}
+
 /**
  * Returns two character base58 encoded string that changes every 10
  * milliseconds

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.5.16",
+	"version": "0.5.17",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"