@alwatr/random/dist/main.d.ts

A lightweight utility library for generating random numbers, strings, UUIDs and more

/**
 * 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