shuffrand/dist/index.d.ts

Cryptographically secure randomizer and shuffler.

/**
 * ... (JSDoc for calculateStringEntropy) ...
 */
export declare function calculateStringEntropy(params?: CryptoStringParams): number;

export declare const Constants: {
    readonly MAX_SAFE_INT: number;
    readonly MIN_SAFE_INT: number;
    readonly MAX_SAFE_DOUBLE: 1000000000000000;
    readonly MIN_SAFE_DOUBLE: -1000000000000000;
    readonly UINT32_MAX_VALUE: 4294967295;
    readonly UINT32_RANGE: 4294967296;
    readonly MAX_FRACTIONAL_DIGITS: 15;
    readonly MIN_FRACTIONAL_DIGITS: 1;
    readonly MAX_ATTEMPTS_TO_GENERATE_NUM: 30;
    /**
     * String containing all digit characters (0-9).
     */
    readonly DIGITS: "0123456789";
    /**
     * String containing all lowercase English alphabet characters (a-z).
     */
    readonly LATIN_LOWERCASE_LETTERS: "abcdefghijklmnopqrstuvwxyz";
    /**
     * String containing all uppercase English alphabet characters (A-Z).
     */
    readonly LATIN_UPPERCASE_LETTERS: string;
    /**
     * String containing all English alphabet characters (a-z, A-Z).
     */
    readonly LATIN_LETTERS: string;
    /**
     * String containing all alphanumeric characters (a-z, A-Z, 0-9).
     */
    readonly ALPHANUMERIC_CHARS: string;
    /**
     * String containing all hexadecimal characters (0-9, a-f).
     */
    readonly HEX_CHARS: string;
};

/**
 * Generates a cryptographically secure random number within a specified range.
 *
 * @param {RandomParams} [rawParams={}] - The raw parameters for random number generation.
 * @param {number} [rawParams.lowerBound=0] - The lower bound (inclusive) of the random number.
 * @param {number} [rawParams.upperBound=2] - The upper bound (exclusive for doubles, inclusive for integers) of the random number.
 * @param {'integer'|'double'} [rawParams.typeOfNum='integer'] - The type of number to generate ('integer' (default) or 'double').
 * @param {'none'|'lower bound'|'upper bound'|'both'} [rawParams.exclusion='none'] - Specifies which bounds to exclude.
 * @param {number} [rawParams.maxFracDigits=3] - The maximum number of fractional digits for 'double' type numbers.
 * If specified, the generated double will be rounded to this many decimal places.
 * Must be a non-negative integer between 0 and 15. Defaults to `3`.
 * @returns {number} - A cryptographically secure random number.
 * @throws {TypeError} - If input parameters do not conform to the schema or if an invalid range is provided.
 */
export declare function cryptoRandom(rawParams?: RandomParams): number;

/**
 * Shuffles an array using the cryptographically secure Fisher–Yates algorithm.
 * Wikipedia.org/wiki/Fisher–Yates_shuffle
 *
 * @template T - The type of elements in the array.
 * @param {T[]} [arr=[]] - The array to shuffle. Defaults to an empty array if omitted.
 * @param {object} [options={}] - Optional parameters for shuffling.
 * @param {boolean} [options.isDestructive=false] - Whether to shuffle the array in place (destructive) or create a new shuffled array (non-destructive).
 * @param {boolean} [options.preventIdentical=false] - If true, and the initial shuffle results in an array identical to the original input,
 * the first and last elements will be swapped to guarantee a different result.
 * This introduces a statistical bias by excluding the original permutation. Do not use in cryptographic or
 * fairness-critical contexts where absolute unbiased randomness is required.
 * @param {number} [options.startIndex=0] - The starting index of the subarray to shuffle (inclusive).
 * Defaults to 0, shuffling from the beginning of the array.
 * Must be a non-negative integer within the array bounds.
 * If greater than or equal to `endIndex`, no shuffling occurs on the subarray.
 * @param {number} [options.endIndex=arr.length] - The ending index of the subarray to shuffle (exclusive).
 * Defaults to the array's length, shuffling to the end of the array.
 * Must be a non-negative integer within the array bounds (0 to arr.length).
 * If less than or equal to `startIndex`, no shuffling occurs on the subarray.
 * @returns {T[]} - The shuffled array.
 * @throws {TypeError} - If input parameters do not conform to the schema or if array serialization fails.
 * @since 1.0.0
 * @since 1.6.0 Added `startIndex` and `endIndex` for subarray shuffling.
 */
export declare function cryptoShuffle<T>(arr?: T[], options?: {
    isDestructive?: boolean;
    preventIdentical?: boolean;
    startIndex?: number;
    endIndex?: number;
}): T[];

/**
 * Generates a cryptographically secure random string of a specified length
 * from a given character set.
 *
 * @param {CryptoStringParams} [rawParams={}] - The raw parameters for random string generation.
 * @param {number} [rawParams.length=16] - The desired length of the random string.
 * @param {'alphanumeric'|'numeric'|'alpha'|'hex'|'uppercase'|'lowercase'|string} [rawParams.characterSet='alphanumeric'] - The character set to use.
 * @param {boolean} [rawParams.noRepeat=false] - If true, ensures no character appears more than once in the result.
 * @returns {string} - The cryptographically secure random string.
 * @throws {TypeError} - If input parameters are invalid.
 */
export declare function cryptoString(rawParams?: CryptoStringParams): string;

/**
 * Parameters for the cryptoString function.
 */
export declare interface CryptoStringParams {
    length?: number;
    characterSet?: 'alphanumeric' | 'numeric' | 'alpha' | 'hex' | 'uppercase' | 'lowercase' | string;
    /**
     * If true, ensures no character appears more than once in the result.
     * Defaults to `false`.
     */
    noRepeat?: boolean;
}

/**
 * Parameters for the cryptoRandom function.
 */
export declare interface RandomParams {
    lowerBound?: number;
    upperBound?: number;
    typeOfNum?: 'integer' | 'double';
    exclusion?: 'none' | 'lower bound' | 'upper bound' | 'both';
    maxFracDigits?: number;
}

/**
 * Parameters for the cryptoShuffle function.
 */
export declare interface ShuffleParams<T> {
    arr?: T[];
    isDestructive?: boolean;
    preventIdentical?: boolean;
    /**
     * The starting index of the subarray to shuffle (inclusive).
     * Defaults to 0, shuffling from the beginning of the array.
     * Must be a non-negative integer within the array bounds.
     * If greater than or equal to `endIndex`, no shuffling occurs on the subarray.
     * @since 1.6.0
     */
    startIndex?: number;
    /**
     * The ending index of the subarray to shuffle (exclusive).
     * Defaults to the array's length, shuffling to the end of the array.
     * Must be a non-negative integer within the array bounds (0 to arr.length).
     * If less than or equal to `startIndex`, no shuffling occurs on the subarray.
     * @since 1.6.0
     */
    endIndex?: number;
}

export { }