@alwatr/random 5.1.0

package/README.md

@@ -0,0 +1,212 @@
+# @alwatr/random
+
+A lightweight, high-performance utility library for generating random numbers, strings, UUIDs and more.
+
+## Installation
+
+```bash
+yarn add @alwatr/random
+# or
+npm install @alwatr/random
+```
+
+## Features
+
+- Cross-platform (Node.js and browsers)
+- TypeScript support with type safety
+- Zero dependencies (except for internal package tracer)
+- Uses cryptographic random when available
+- Comprehensive set of random utilities
+- Supports tree-shaking with individually exported functions
+
+## Usage
+
+```typescript
+import {
+  randNumber,
+  randInteger,
+  randFloat,
+  randString,
+  randStep,
+  randShuffle,
+  randPick,
+  randUuid,
+  randBoolean,
+  randColor,
+  randArray,
+  bytesToHex
+} from '@alwatr/random';
+
+// Get random number between 0 and 1
+console.log(randNumber()); // 0.7124123
+
+// Get random integer in range
+console.log(randInteger(1, 10)); // 7
+
+// Get random float in range
+console.log(randFloat(1, 10)); // 7.214124
+
+// Get random string with fixed length
+console.log(randString(6)); // "A1b2C3"
+
+// Get random string with variable length
+console.log(randString(3, 6)); // "X2fg"
+
+// Get random string with custom character set
+console.log(randString(5, undefined, '01')); // "10101"
+
+// Get random value with step
+console.log(randStep(0, 10, 2)); // 0, 2, 4, 6, 8, or 10
+
+// Shuffle an array
+const array = [1, 2, 3, 4, 5];
+console.log(randShuffle([...array])); // [3, 1, 5, 2, 4]
+
+// Pick a random item from array
+console.log(randPick(array)); // 3
+
+// Generate UUID
+console.log(randUuid()); // "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6"
+
+// Generate random boolean
+console.log(randBoolean()); // true or false (50% chance)
+console.log(randBoolean(0.8)); // true or false (80% chance of true)
+
+// Generate random color
+console.log(randColor()); // "#a1b2c3"
+
+// Convert bytes to hexadecimal string
+const bytes = new Uint8Array([10, 255, 0, 16]);
+console.log(bytesToHex(bytes)); // "0aff0010"
+```
+
+## API
+
+### `randNumber()`
+
+Returns a random float between 0 and 1 (not including 1). This is a direct wrapper around `Math.random()`.
+
+```ts
+const value = randNumber(); // 0.7124123
+```
+
+### `randInteger(min, max)`
+
+Returns a random integer between `min` and `max` (inclusive).
+
+```ts
+const value = randInteger(1, 10); // Between 1 and 10
+```
+
+### `randFloat(min, max)`
+
+Returns a random float between `min` and `max` (max not included).
+
+```ts
+const value = randFloat(1, 10); // Between 1 and 10 (float)
+```
+
+### `randString(min, max?, chars?)`
+
+Generates a random string with characters from the specified character set (defaults to alphanumeric set: `A-Z`, `a-z`, `0-9`).
+
+- With one argument: Returns a string of exactly that length
+- With two arguments: Returns a string with random length between min and max (inclusive)
+- With three arguments: Uses the provided character set instead of the default alphanumeric set
+
+```ts
+const fixedLength = randString(6); // "A1b2C3"
+const variableLength = randString(3, 6); // Random length between 3 and 6
+const binaryString = randString(8, undefined, '01'); // "10110010"
+const hexString = randString(6, 6, '0123456789abcdef'); // "a3f28c"
+```
+
+### `randStep(min, max, step)`
+
+Returns a random number between `min` and `max` with the specified step.
+
+```ts
+const value = randStep(0, 10, 2); // 0, 2, 4, 6, 8, or 10
+```
+
+### `randShuffle(array)`
+
+Shuffles an array in place using Fisher-Yates algorithm and returns it.
+
+```ts
+const array = [1, 2, 3, 4, 5];
+randShuffle(array); // [3, 1, 5, 2, 4]
+```
+
+### `randPick(array)`
+
+Returns a random element from an array.
+
+```ts
+const array = [1, 2, 3, 4, 5];
+const value = randPick(array); // One random element
+```
+
+### `randUuid()`
+
+Generates a random UUID v4. Uses `crypto.randomUUID()` when available, with a fallback implementation.
+
+```ts
+const id = randUuid(); // "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6"
+```
+
+### `randBoolean(probability?)`
+
+Generates a random boolean with the specified probability of being true (default is 0.5).
+
+```ts
+const value = randBoolean(); // true or false (50% chance)
+const mostlyTrue = randBoolean(0.8); // true or false (80% chance of true)
+```
+
+### `randColor()`
+
+Generates a random hex color string with 6 hexadecimal digits (representing RGB values).
+
+```ts
+const color = randColor(); // "#a1b2c3"
+```
+
+### `randArray(array, min?, max?)`
+
+Fills a typed array with random integer values within the specified range. The array is modified in place and also returned for chaining.
+
+```ts
+// Fill a Uint8Array with random values (0-255)
+randArray(new Uint8Array(10));
+
+// Fill with custom range
+randArray(new Uint16Array(5), 1000, 2000); // Values between 1000-2000
+
+// Also works with number arrays
+randArray(new Array<number>(8), -100, 100); // Values between -100 and 100
+```
+
+### `bytesToHex(bytes)`
+
+Converts a Uint8Array or number array into a hexadecimal string representation. Each byte is converted to a two-character hex string (padded with a leading zero if necessary) and concatenated together.
+
+```ts
+const bytes = new Uint8Array([10, 255, 0, 16]);
+const hex = bytesToHex(bytes); // "0aff0010"
+
+const array = [171, 205, 3];
+const hex2 = bytesToHex(array); // "abcd03"
+```
+
+## Sponsors
+
+The following companies, organizations, and individuals support Nanolib ongoing maintenance and development. Become a Sponsor to get your logo on our README and website.
+
+## Contributing
+
+Contributions are welcome! Please read our [contribution guidelines](https://github.com/Alwatr/.github/blob/next/CONTRIBUTING.md) before submitting a pull request.
+
+## License
+
+This project is licensed under the [AGPL-3.0 License](LICENSE).

package/dist/main.cjs

@@ -0,0 +1,132 @@
+/* @alwatr/random v5.1.0 */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/main.ts
+var main_exports = {};
+__export(main_exports, {
+  bytesToHex: () => bytesToHex,
+  randArray: () => randArray,
+  randBoolean: () => randBoolean,
+  randColor: () => randColor,
+  randFloat: () => randFloat,
+  randInteger: () => randInteger,
+  randNumber: () => randNumber,
+  randPick: () => randPick,
+  randShuffle: () => randShuffle,
+  randStep: () => randStep,
+  randString: () => randString,
+  randUuid: () => randUuid
+});
+module.exports = __toCommonJS(main_exports);
+var import_global_this = require("@alwatr/global-this");
+var import_package_tracer = require("@alwatr/package-tracer");
+var globalThis = (0, import_global_this.getGlobalThis)();
+__dev_mode__: import_package_tracer.packageTracer.add("@alwatr/random", "5.1.0");
+var hasCrypto = typeof globalThis.crypto !== "undefined";
+function bytesToHex(bytes) {
+  let result = "";
+  for (const byte of bytes) {
+    const hex = byte.toString(16);
+    result += hex.length === 1 ? "0" + hex : hex;
+  }
+  return result;
+}
+function randNumber() {
+  return Math.random();
+}
+function randFloat(min, max) {
+  return Math.random() * (max - min) + min;
+}
+function randInteger(min, max) {
+  return Math.floor(randFloat(min, max + 1));
+}
+function randString(minLength, maxLength = minLength, chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789") {
+  const length = maxLength === minLength ? minLength : randInteger(minLength, maxLength);
+  if (length <= 0) return "";
+  const charsLength = chars.length;
+  let result = "";
+  if (length <= 10) {
+    for (let i = 0; i < length; i++) {
+      result += chars.charAt(Math.floor(Math.random() * charsLength));
+    }
+    return result;
+  }
+  const resultArray = new Array(length);
+  for (let i = 0; i < length; i++) {
+    resultArray[i] = chars.charAt(Math.floor(Math.random() * charsLength));
+  }
+  return resultArray.join("");
+}
+function randStep(min, max, step) {
+  if (step === 0) {
+    return min;
+  }
+  const steps = Math.floor((max - min) / step);
+  return min + randInteger(0, steps) * step;
+}
+function randShuffle(array) {
+  for (let i = array.length - 1; i > 0; i--) {
+    const j = randInteger(0, i);
+    [array[i], array[j]] = [array[j], array[i]];
+  }
+  return array;
+}
+function randPick(array) {
+  if (array.length === 0) throw new Error("Cannot pick from empty array");
+  return array[randInteger(0, array.length - 1)];
+}
+function randArray(array, min = 0, max = 255) {
+  for (let i = array.length - 1; i >= 0; i--) {
+    array[i] = randInteger(min, max);
+  }
+  return array;
+}
+function randUuid() {
+  if (hasCrypto && globalThis.crypto?.randomUUID) {
+    return globalThis.crypto.randomUUID();
+  }
+  const bytes = randArray(new Uint8Array(16));
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 191 | 128;
+  return `${bytesToHex(bytes.subarray(0, 4))}-${bytesToHex(bytes.subarray(4, 6))}-${bytesToHex(bytes.subarray(6, 8))}-${bytesToHex(bytes.subarray(8, 10))}-${bytesToHex(bytes.subarray(10, 16))}`;
+}
+function randBoolean(probability = 0.5) {
+  return Math.random() < probability;
+}
+function randColor() {
+  const bytes = randArray(new Array(3));
+  return `#${bytesToHex(bytes)}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  bytesToHex,
+  randArray,
+  randBoolean,
+  randColor,
+  randFloat,
+  randInteger,
+  randNumber,
+  randPick,
+  randShuffle,
+  randStep,
+  randString,
+  randUuid
+});
+//# sourceMappingURL=main.cjs.map

package/dist/main.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/main.ts"],
+  "sourcesContent": ["import {getGlobalThis} from '@alwatr/global-this';\nimport {packageTracer} from '@alwatr/package-tracer';\n\nconst globalThis = getGlobalThis();\n\n__dev_mode__: packageTracer.add(__package_name__, __package_version__);\n\n// Use the native crypto module when available for better randomness\nconst hasCrypto = typeof globalThis.crypto !== 'undefined';\n\n/**\n * Converts a Uint8Array or number array into a hexadecimal string representation.\n * Each byte is converted to a two-character hex string (padded with a leading zero if necessary)\n * and concatenated together to form a single string.\n *\n * @param bytes - The array of bytes to convert to hexadecimal\n * @returns A hexadecimal string representation of the input bytes\n *\n * @example\n * ```ts\n * // Using with Uint8Array\n * const bytes = new Uint8Array([10, 255, 0, 16]);\n * bytesToHex(bytes); // Returns \"0aff0010\"\n *\n * // Using with number array\n * const array = [171, 205, 3];\n * bytesToHex(array); // Returns \"abcd03\"\n * ```\n */\nexport function bytesToHex(bytes: number[] | Uint8Array): string {\n  let result = '';\n  for (const byte of bytes) {\n    const hex = byte.toString(16);\n    result += hex.length === 1 ? '0' + hex : hex;\n  }\n  return result;\n}\n\n/**\n * Returns a float random number between 0 and 1 (1 not included).\n *\n * Example:\n *\n * ```js\n * console.log(randNumber()); // 0.7124123\n * ```\n */\nexport function randNumber(): number {\n  return Math.random();\n}\n\n/**\n * Generate a random float number between min and max (max not included).\n *\n * Example:\n *\n * ```js\n * console.log(randFloat(1, 10)); // somewhere between 1 and 10 (as float)\n * ```\n */\nexport function randFloat(min: number, max: number): number {\n  return Math.random() * (max - min) + min;\n}\n\n/**\n * Generate a random integer number between min and max (max included).\n *\n * Example:\n *\n * ```js\n * console.log(randInteger(1, 10)); // somewhere between 1 and 10\n * ```\n */\nexport function randInteger(min: number, max: number): number {\n  // Use Math.floor and add 1 to max for better distribution\n  return Math.floor(randFloat(min, max + 1));\n}\n\n/**\n * Generate a random string with specified length.\n * The string will contain only characters from the characters list.\n * The length of the string will be between min and max (max included).\n * If max not specified, the length will be set to min.\n *\n * Example:\n *\n *```js\n * console.log(randString(6)); // something like 'Aab1V2'\n * console.log(randString(3, 6)); // random length between 3 and 6\n * console.log(randString(5, undefined, '01')); // binary string like '10101'\n * ```\n */\nexport function randString(\n  minLength: number,\n  maxLength: number = minLength,\n  chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',\n): string {\n  const length = maxLength === minLength ? minLength : randInteger(minLength, maxLength);\n  if (length <= 0) return '';\n\n  const charsLength = chars.length;\n\n  let result = '';\n\n  // Small optimization for short strings\n  if (length <= 10) {\n    for (let i = 0; i < length; i++) {\n      result += chars.charAt(Math.floor(Math.random() * charsLength));\n    }\n    return result;\n  }\n  // else\n  // For longer strings, use array join for better performance\n  const resultArray = new Array(length);\n  for (let i = 0; i < length; i++) {\n    resultArray[i] = chars.charAt(Math.floor(Math.random() * charsLength));\n  }\n  return resultArray.join('');\n}\n\n/**\n * Generate a random integer between min and max with a step.\n *\n * Example:\n *\n * ```js\n * console.log(randStep(6, 10, 2)); // 6 or 8 or 10\n * ```\n */\nexport function randStep(min: number, max: number, step: number): number {\n  if (step === 0) {\n    return min; // Return min when step is 0 to avoid division by zero\n  }\n  const steps = Math.floor((max - min) / step);\n  return min + randInteger(0, steps) * step;\n}\n\n/**\n * Shuffle an array in place using Fisher-Yates shuffle algorithm and return it.\n *\n * Example:\n *\n * ```js\n * const array = [1, 2, 3, 4, 5];\n * randShuffle(array);\n * console.log(array); // [2, 4, 3, 1, 5] (randomized)\n * ```\n */\nexport function randShuffle<T>(array: T[]): T[] {\n  for (let i = array.length - 1; i > 0; i--) {\n    const j = randInteger(0, i);\n    [array[i], array[j]] = [array[j], array[i]];\n  }\n  return array;\n}\n\n/**\n * Choose a random item from an array.\n * Throws an error if the array is empty.\n *\n * Example:\n *\n * ```js\n * const array = [1, 2, 3, 4, 5];\n * console.log(randPick(array)); // one random element\n * ```\n */\nexport function randPick<T>(array: T[]): T {\n  if (array.length === 0) throw new Error('Cannot pick from empty array');\n  return array[randInteger(0, array.length - 1)];\n}\n\n/**\n * Fills a typed array with random integer values within the specified range.\n * The array is modified in place and also returned for chaining.\n *\n * @param array - The array to fill with random values (modified in place)\n * @param min - Minimum value (inclusive), defaults to 0\n * @param max - Maximum value (inclusive), defaults to 255\n * @returns The same array that was passed in (for chaining)\n *\n * @example\n * ```ts\n * // Fill a Uint8Array with random values (0-255)\n * randArray(new Uint8Array(10));\n *\n * // Fill with custom range\n * randArray(new Uint16Array(5), 1000, 2000); // Values between 1000-2000\n *\n * // Also works with number arrays\n * randArray(new Array<number>(8), -100, 100); // Values between -100 and 100\n * ```\n */\nexport function randArray<T extends number[] | Uint8Array | Uint16Array | Uint32Array>(array: T, min = 0, max = 255): T {\n  for (let i = array.length - 1; i >= 0; i--) {\n    array[i] = randInteger(min, max);\n  }\n  return array;\n}\n\n/**\n * Type alias for a UUID string.\n */\nexport type UUID = `${string}-${string}-${string}-${string}-${string}`;\n\n/**\n * Generate a random UUID (v4).\n *\n * Example:\n *\n * ```js\n * console.log(randUuid()); // \"a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6\"\n * ```\n */\nexport function randUuid(): UUID {\n  if (hasCrypto && globalThis.crypto?.randomUUID) {\n    return globalThis.crypto.randomUUID() as UUID;\n  }\n\n  // Fallback implementation\n  const bytes = randArray(new Uint8Array(16));\n  bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4\n  bytes[8] = (bytes[8] & 0xbf) | 0x80; // variant RFC4122\n\n  // prettier-ignore\n  return `${\n    bytesToHex(bytes.subarray(0, 4))\n  }-${\n    bytesToHex(bytes.subarray(4, 6))\n  }-${\n    bytesToHex(bytes.subarray(6, 8))\n  }-${\n    bytesToHex(bytes.subarray(8, 10))\n  }-${\n    bytesToHex(bytes.subarray(10, 16))\n  }` as UUID;\n}\n\n/**\n * Generate a random boolean with specified probability of being true.\n *\n * Example:\n *\n * ```js\n * console.log(randBoolean()); // 50% chance of true\n * console.log(randBoolean(0.8)); // 80% chance of true\n * ```\n */\nexport function randBoolean(probability = 0.5): boolean {\n  return Math.random() < probability;\n}\n\n/**\n * Generate a random hex color string.\n *\n * Example:\n *\n * ```js\n * console.log(randColor()); // \"#a1b2c3\"\n * ```\n */\nexport function randColor(): string {\n  const bytes = randArray(new Array<number>(3));\n  return `#${bytesToHex(bytes)}`;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAA4B;AAC5B,4BAA4B;AAE5B,IAAM,iBAAa,kCAAc;AAEjC,aAAc,qCAAc,IAAI,kBAAkB,OAAmB;AAGrE,IAAM,YAAY,OAAO,WAAW,WAAW;AAqBxC,SAAS,WAAW,OAAsC;AAC/D,MAAI,SAAS;AACb,aAAW,QAAQ,OAAO;AACxB,UAAM,MAAM,KAAK,SAAS,EAAE;AAC5B,cAAU,IAAI,WAAW,IAAI,MAAM,MAAM;AAAA,EAC3C;AACA,SAAO;AACT;AAWO,SAAS,aAAqB;AACnC,SAAO,KAAK,OAAO;AACrB;AAWO,SAAS,UAAU,KAAa,KAAqB;AAC1D,SAAO,KAAK,OAAO,KAAK,MAAM,OAAO;AACvC;AAWO,SAAS,YAAY,KAAa,KAAqB;AAE5D,SAAO,KAAK,MAAM,UAAU,KAAK,MAAM,CAAC,CAAC;AAC3C;AAgBO,SAAS,WACd,WACA,YAAoB,WACpB,QAAQ,kEACA;AACR,QAAM,SAAS,cAAc,YAAY,YAAY,YAAY,WAAW,SAAS;AACrF,MAAI,UAAU,EAAG,QAAO;AAExB,QAAM,cAAc,MAAM;AAE1B,MAAI,SAAS;AAGb,MAAI,UAAU,IAAI;AAChB,aAAS,IAAI,GAAG,IAAI,QAAQ,KAAK;AAC/B,gBAAU,MAAM,OAAO,KAAK,MAAM,KAAK,OAAO,IAAI,WAAW,CAAC;AAAA,IAChE;AACA,WAAO;AAAA,EACT;AAGA,QAAM,cAAc,IAAI,MAAM,MAAM;AACpC,WAAS,IAAI,GAAG,IAAI,QAAQ,KAAK;AAC/B,gBAAY,CAAC,IAAI,MAAM,OAAO,KAAK,MAAM,KAAK,OAAO,IAAI,WAAW,CAAC;AAAA,EACvE;AACA,SAAO,YAAY,KAAK,EAAE;AAC5B;AAWO,SAAS,SAAS,KAAa,KAAa,MAAsB;AACvE,MAAI,SAAS,GAAG;AACd,WAAO;AAAA,EACT;AACA,QAAM,QAAQ,KAAK,OAAO,MAAM,OAAO,IAAI;AAC3C,SAAO,MAAM,YAAY,GAAG,KAAK,IAAI;AACvC;AAaO,SAAS,YAAe,OAAiB;AAC9C,WAAS,IAAI,MAAM,SAAS,GAAG,IAAI,GAAG,KAAK;AACzC,UAAM,IAAI,YAAY,GAAG,CAAC;AAC1B,KAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;AAAA,EAC5C;AACA,SAAO;AACT;AAaO,SAAS,SAAY,OAAe;AACzC,MAAI,MAAM,WAAW,EAAG,OAAM,IAAI,MAAM,8BAA8B;AACtE,SAAO,MAAM,YAAY,GAAG,MAAM,SAAS,CAAC,CAAC;AAC/C;AAuBO,SAAS,UAAuE,OAAU,MAAM,GAAG,MAAM,KAAQ;AACtH,WAAS,IAAI,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK;AAC1C,UAAM,CAAC,IAAI,YAAY,KAAK,GAAG;AAAA,EACjC;AACA,SAAO;AACT;AAgBO,SAAS,WAAiB;AAC/B,MAAI,aAAa,WAAW,QAAQ,YAAY;AAC9C,WAAO,WAAW,OAAO,WAAW;AAAA,EACtC;AAGA,QAAM,QAAQ,UAAU,IAAI,WAAW,EAAE,CAAC;AAC1C,QAAM,CAAC,IAAK,MAAM,CAAC,IAAI,KAAQ;AAC/B,QAAM,CAAC,IAAK,MAAM,CAAC,IAAI,MAAQ;AAG/B,SAAO,GACL,WAAW,MAAM,SAAS,GAAG,CAAC,CAAC,CACjC,IACE,WAAW,MAAM,SAAS,GAAG,CAAC,CAAC,CACjC,IACE,WAAW,MAAM,SAAS,GAAG,CAAC,CAAC,CACjC,IACE,WAAW,MAAM,SAAS,GAAG,EAAE,CAAC,CAClC,IACE,WAAW,MAAM,SAAS,IAAI,EAAE,CAAC,CACnC;AACF;AAYO,SAAS,YAAY,cAAc,KAAc;AACtD,SAAO,KAAK,OAAO,IAAI;AACzB;AAWO,SAAS,YAAoB;AAClC,QAAM,QAAQ,UAAU,IAAI,MAAc,CAAC,CAAC;AAC5C,SAAO,IAAI,WAAW,KAAK,CAAC;AAC9B;",
+  "names": []
+}

package/dist/main.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Converts a Uint8Array or number array into a hexadecimal string representation.
+ * Each byte is converted to a two-character hex string (padded with a leading zero if necessary)
+ * and concatenated together to form a single string.
+ *
+ * @param bytes - The array of bytes to convert to hexadecimal
+ * @returns A hexadecimal string representation of the input bytes
+ *
+ * @example
+ * ```ts
+ * // Using with Uint8Array
+ * const bytes = new Uint8Array([10, 255, 0, 16]);
+ * bytesToHex(bytes); // Returns "0aff0010"
+ *
+ * // Using with number array
+ * const array = [171, 205, 3];
+ * bytesToHex(array); // Returns "abcd03"
+ * ```
+ */
+export declare function bytesToHex(bytes: number[] | Uint8Array): string;
+/**
+ * Returns a float random number between 0 and 1 (1 not included).
+ *
+ * Example:
+ *
+ * ```js
+ * console.log(randNumber()); // 0.7124123
+ * ```
+ */
+export declare function randNumber(): number;
+/**
+ * Generate a random float number between min and max (max not included).
+ *
+ * Example:
+ *
+ * ```js
+ * console.log(randFloat(1, 10)); // somewhere between 1 and 10 (as float)
+ * ```
+ */
+export declare function randFloat(min: number, max: number): number;
+/**
+ * Generate a random integer number between min and max (max included).
+ *
+ * Example:
+ *
+ * ```js
+ * console.log(randInteger(1, 10)); // somewhere between 1 and 10
+ * ```
+ */
+export declare function randInteger(min: number, max: number): number;
+/**
+ * Generate a random string with specified length.
+ * The string will contain only characters from the characters list.
+ * The length of the string will be between min and max (max included).
+ * If max not specified, the length will be set to min.
+ *
+ * Example:
+ *
+ *```js
+ * console.log(randString(6)); // something like 'Aab1V2'
+ * console.log(randString(3, 6)); // random length between 3 and 6
+ * console.log(randString(5, undefined, '01')); // binary string like '10101'
+ * ```
+ */
+export declare function randString(minLength: number, maxLength?: number, chars?: string): string;
+/**
+ * Generate a random integer between min and max with a step.
+ *
+ * Example:
+ *
+ * ```js
+ * console.log(randStep(6, 10, 2)); // 6 or 8 or 10
+ * ```
+ */
+export declare function randStep(min: number, max: number, step: number): number;
+/**
+ * Shuffle an array in place using Fisher-Yates shuffle algorithm and return it.
+ *
+ * Example:
+ *
+ * ```js
+ * const array = [1, 2, 3, 4, 5];
+ * randShuffle(array);
+ * console.log(array); // [2, 4, 3, 1, 5] (randomized)
+ * ```
+ */
+export declare function randShuffle<T>(array: T[]): T[];
+/**
+ * Choose a random item from an array.
+ * Throws an error if the array is empty.
+ *
+ * Example:
+ *
+ * ```js
+ * const array = [1, 2, 3, 4, 5];
+ * console.log(randPick(array)); // one random element
+ * ```
+ */
+export declare function randPick<T>(array: T[]): T;
+/**
+ * Fills a typed array with random integer values within the specified range.
+ * The array is modified in place and also returned for chaining.
+ *
+ * @param array - The array to fill with random values (modified in place)
+ * @param min - Minimum value (inclusive), defaults to 0
+ * @param max - Maximum value (inclusive), defaults to 255
+ * @returns The same array that was passed in (for chaining)
+ *
+ * @example
+ * ```ts
+ * // Fill a Uint8Array with random values (0-255)
+ * randArray(new Uint8Array(10));
+ *
+ * // Fill with custom range
+ * randArray(new Uint16Array(5), 1000, 2000); // Values between 1000-2000
+ *
+ * // Also works with number arrays
+ * randArray(new Array<number>(8), -100, 100); // Values between -100 and 100
+ * ```
+ */
+export declare function randArray<T extends number[] | Uint8Array | Uint16Array | Uint32Array>(array: T, min?: number, max?: number): T;
+/**
+ * Type alias for a UUID string.
+ */
+export type UUID = `${string}-${string}-${string}-${string}-${string}`;
+/**
+ * Generate a random UUID (v4).
+ *
+ * Example:
+ *
+ * ```js
+ * console.log(randUuid()); // "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6"
+ * ```
+ */
+export declare function randUuid(): UUID;
+/**
+ * Generate a random boolean with specified probability of being true.
+ *
+ * Example:
+ *
+ * ```js
+ * console.log(randBoolean()); // 50% chance of true
+ * console.log(randBoolean(0.8)); // 80% chance of true
+ * ```
+ */
+export declare function randBoolean(probability?: number): boolean;
+/**
+ * Generate a random hex color string.
+ *
+ * Example:
+ *
+ * ```js
+ * console.log(randColor()); // "#a1b2c3"
+ * ```
+ */
+export declare function randColor(): string;
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,UAAU,GAAG,MAAM,CAO/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,MAAkB,EAC7B,KAAK,SAAmE,GACvE,MAAM,CAsBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAM9C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,CAGzC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,SAAI,EAAE,GAAG,SAAM,GAAG,CAAC,CAKtH;AAED;;GAEG;AACH,MAAM,MAAM,IAAI,GAAG,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;AAEvE;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,IAAI,IAAI,CAsB/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,WAAW,SAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAGlC"}

package/dist/main.mjs

@@ -0,0 +1,97 @@
+/* @alwatr/random v5.1.0 */
+
+// src/main.ts
+import { getGlobalThis } from "@alwatr/global-this";
+import { packageTracer } from "@alwatr/package-tracer";
+var globalThis = getGlobalThis();
+__dev_mode__: packageTracer.add("@alwatr/random", "5.1.0");
+var hasCrypto = typeof globalThis.crypto !== "undefined";
+function bytesToHex(bytes) {
+  let result = "";
+  for (const byte of bytes) {
+    const hex = byte.toString(16);
+    result += hex.length === 1 ? "0" + hex : hex;
+  }
+  return result;
+}
+function randNumber() {
+  return Math.random();
+}
+function randFloat(min, max) {
+  return Math.random() * (max - min) + min;
+}
+function randInteger(min, max) {
+  return Math.floor(randFloat(min, max + 1));
+}
+function randString(minLength, maxLength = minLength, chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789") {
+  const length = maxLength === minLength ? minLength : randInteger(minLength, maxLength);
+  if (length <= 0) return "";
+  const charsLength = chars.length;
+  let result = "";
+  if (length <= 10) {
+    for (let i = 0; i < length; i++) {
+      result += chars.charAt(Math.floor(Math.random() * charsLength));
+    }
+    return result;
+  }
+  const resultArray = new Array(length);
+  for (let i = 0; i < length; i++) {
+    resultArray[i] = chars.charAt(Math.floor(Math.random() * charsLength));
+  }
+  return resultArray.join("");
+}
+function randStep(min, max, step) {
+  if (step === 0) {
+    return min;
+  }
+  const steps = Math.floor((max - min) / step);
+  return min + randInteger(0, steps) * step;
+}
+function randShuffle(array) {
+  for (let i = array.length - 1; i > 0; i--) {
+    const j = randInteger(0, i);
+    [array[i], array[j]] = [array[j], array[i]];
+  }
+  return array;
+}
+function randPick(array) {
+  if (array.length === 0) throw new Error("Cannot pick from empty array");
+  return array[randInteger(0, array.length - 1)];
+}
+function randArray(array, min = 0, max = 255) {
+  for (let i = array.length - 1; i >= 0; i--) {
+    array[i] = randInteger(min, max);
+  }
+  return array;
+}
+function randUuid() {
+  if (hasCrypto && globalThis.crypto?.randomUUID) {
+    return globalThis.crypto.randomUUID();
+  }
+  const bytes = randArray(new Uint8Array(16));
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 191 | 128;
+  return `${bytesToHex(bytes.subarray(0, 4))}-${bytesToHex(bytes.subarray(4, 6))}-${bytesToHex(bytes.subarray(6, 8))}-${bytesToHex(bytes.subarray(8, 10))}-${bytesToHex(bytes.subarray(10, 16))}`;
+}
+function randBoolean(probability = 0.5) {
+  return Math.random() < probability;
+}
+function randColor() {
+  const bytes = randArray(new Array(3));
+  return `#${bytesToHex(bytes)}`;
+}
+export {
+  bytesToHex,
+  randArray,
+  randBoolean,
+  randColor,
+  randFloat,
+  randInteger,
+  randNumber,
+  randPick,
+  randShuffle,
+  randStep,
+  randString,
+  randUuid
+};
+//# sourceMappingURL=main.mjs.map

package/dist/main.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/main.ts"],
+  "sourcesContent": ["import {getGlobalThis} from '@alwatr/global-this';\nimport {packageTracer} from '@alwatr/package-tracer';\n\nconst globalThis = getGlobalThis();\n\n__dev_mode__: packageTracer.add(__package_name__, __package_version__);\n\n// Use the native crypto module when available for better randomness\nconst hasCrypto = typeof globalThis.crypto !== 'undefined';\n\n/**\n * Converts a Uint8Array or number array into a hexadecimal string representation.\n * Each byte is converted to a two-character hex string (padded with a leading zero if necessary)\n * and concatenated together to form a single string.\n *\n * @param bytes - The array of bytes to convert to hexadecimal\n * @returns A hexadecimal string representation of the input bytes\n *\n * @example\n * ```ts\n * // Using with Uint8Array\n * const bytes = new Uint8Array([10, 255, 0, 16]);\n * bytesToHex(bytes); // Returns \"0aff0010\"\n *\n * // Using with number array\n * const array = [171, 205, 3];\n * bytesToHex(array); // Returns \"abcd03\"\n * ```\n */\nexport function bytesToHex(bytes: number[] | Uint8Array): string {\n  let result = '';\n  for (const byte of bytes) {\n    const hex = byte.toString(16);\n    result += hex.length === 1 ? '0' + hex : hex;\n  }\n  return result;\n}\n\n/**\n * Returns a float random number between 0 and 1 (1 not included).\n *\n * Example:\n *\n * ```js\n * console.log(randNumber()); // 0.7124123\n * ```\n */\nexport function randNumber(): number {\n  return Math.random();\n}\n\n/**\n * Generate a random float number between min and max (max not included).\n *\n * Example:\n *\n * ```js\n * console.log(randFloat(1, 10)); // somewhere between 1 and 10 (as float)\n * ```\n */\nexport function randFloat(min: number, max: number): number {\n  return Math.random() * (max - min) + min;\n}\n\n/**\n * Generate a random integer number between min and max (max included).\n *\n * Example:\n *\n * ```js\n * console.log(randInteger(1, 10)); // somewhere between 1 and 10\n * ```\n */\nexport function randInteger(min: number, max: number): number {\n  // Use Math.floor and add 1 to max for better distribution\n  return Math.floor(randFloat(min, max + 1));\n}\n\n/**\n * Generate a random string with specified length.\n * The string will contain only characters from the characters list.\n * The length of the string will be between min and max (max included).\n * If max not specified, the length will be set to min.\n *\n * Example:\n *\n *```js\n * console.log(randString(6)); // something like 'Aab1V2'\n * console.log(randString(3, 6)); // random length between 3 and 6\n * console.log(randString(5, undefined, '01')); // binary string like '10101'\n * ```\n */\nexport function randString(\n  minLength: number,\n  maxLength: number = minLength,\n  chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',\n): string {\n  const length = maxLength === minLength ? minLength : randInteger(minLength, maxLength);\n  if (length <= 0) return '';\n\n  const charsLength = chars.length;\n\n  let result = '';\n\n  // Small optimization for short strings\n  if (length <= 10) {\n    for (let i = 0; i < length; i++) {\n      result += chars.charAt(Math.floor(Math.random() * charsLength));\n    }\n    return result;\n  }\n  // else\n  // For longer strings, use array join for better performance\n  const resultArray = new Array(length);\n  for (let i = 0; i < length; i++) {\n    resultArray[i] = chars.charAt(Math.floor(Math.random() * charsLength));\n  }\n  return resultArray.join('');\n}\n\n/**\n * Generate a random integer between min and max with a step.\n *\n * Example:\n *\n * ```js\n * console.log(randStep(6, 10, 2)); // 6 or 8 or 10\n * ```\n */\nexport function randStep(min: number, max: number, step: number): number {\n  if (step === 0) {\n    return min; // Return min when step is 0 to avoid division by zero\n  }\n  const steps = Math.floor((max - min) / step);\n  return min + randInteger(0, steps) * step;\n}\n\n/**\n * Shuffle an array in place using Fisher-Yates shuffle algorithm and return it.\n *\n * Example:\n *\n * ```js\n * const array = [1, 2, 3, 4, 5];\n * randShuffle(array);\n * console.log(array); // [2, 4, 3, 1, 5] (randomized)\n * ```\n */\nexport function randShuffle<T>(array: T[]): T[] {\n  for (let i = array.length - 1; i > 0; i--) {\n    const j = randInteger(0, i);\n    [array[i], array[j]] = [array[j], array[i]];\n  }\n  return array;\n}\n\n/**\n * Choose a random item from an array.\n * Throws an error if the array is empty.\n *\n * Example:\n *\n * ```js\n * const array = [1, 2, 3, 4, 5];\n * console.log(randPick(array)); // one random element\n * ```\n */\nexport function randPick<T>(array: T[]): T {\n  if (array.length === 0) throw new Error('Cannot pick from empty array');\n  return array[randInteger(0, array.length - 1)];\n}\n\n/**\n * Fills a typed array with random integer values within the specified range.\n * The array is modified in place and also returned for chaining.\n *\n * @param array - The array to fill with random values (modified in place)\n * @param min - Minimum value (inclusive), defaults to 0\n * @param max - Maximum value (inclusive), defaults to 255\n * @returns The same array that was passed in (for chaining)\n *\n * @example\n * ```ts\n * // Fill a Uint8Array with random values (0-255)\n * randArray(new Uint8Array(10));\n *\n * // Fill with custom range\n * randArray(new Uint16Array(5), 1000, 2000); // Values between 1000-2000\n *\n * // Also works with number arrays\n * randArray(new Array<number>(8), -100, 100); // Values between -100 and 100\n * ```\n */\nexport function randArray<T extends number[] | Uint8Array | Uint16Array | Uint32Array>(array: T, min = 0, max = 255): T {\n  for (let i = array.length - 1; i >= 0; i--) {\n    array[i] = randInteger(min, max);\n  }\n  return array;\n}\n\n/**\n * Type alias for a UUID string.\n */\nexport type UUID = `${string}-${string}-${string}-${string}-${string}`;\n\n/**\n * Generate a random UUID (v4).\n *\n * Example:\n *\n * ```js\n * console.log(randUuid()); // \"a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6\"\n * ```\n */\nexport function randUuid(): UUID {\n  if (hasCrypto && globalThis.crypto?.randomUUID) {\n    return globalThis.crypto.randomUUID() as UUID;\n  }\n\n  // Fallback implementation\n  const bytes = randArray(new Uint8Array(16));\n  bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4\n  bytes[8] = (bytes[8] & 0xbf) | 0x80; // variant RFC4122\n\n  // prettier-ignore\n  return `${\n    bytesToHex(bytes.subarray(0, 4))\n  }-${\n    bytesToHex(bytes.subarray(4, 6))\n  }-${\n    bytesToHex(bytes.subarray(6, 8))\n  }-${\n    bytesToHex(bytes.subarray(8, 10))\n  }-${\n    bytesToHex(bytes.subarray(10, 16))\n  }` as UUID;\n}\n\n/**\n * Generate a random boolean with specified probability of being true.\n *\n * Example:\n *\n * ```js\n * console.log(randBoolean()); // 50% chance of true\n * console.log(randBoolean(0.8)); // 80% chance of true\n * ```\n */\nexport function randBoolean(probability = 0.5): boolean {\n  return Math.random() < probability;\n}\n\n/**\n * Generate a random hex color string.\n *\n * Example:\n *\n * ```js\n * console.log(randColor()); // \"#a1b2c3\"\n * ```\n */\nexport function randColor(): string {\n  const bytes = randArray(new Array<number>(3));\n  return `#${bytesToHex(bytes)}`;\n}\n"],
+  "mappings": "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",
+  "names": []
+}