@grandom/pick/RandomPick/index.d.ts

A configurable, flexible, seedable, and overall great random picker.

import { RandomGenerator } from '@grandom/core';
export interface PickStringOptions<T = undefined> {
    /**
     * Filters the input string by character.
     *
     * @param character The specific character to filter from the input string.
     * @returns Whether to keep the specific character in the pick pool.
     */
    filter?: (character: string) => boolean;
    /**
     * The fallback value, when the string is empty, or all characters
     * of the string are filtered out from the pick pool.
     *
     * @default undefined
     */
    fallback?: T;
}
export interface PickArrayOptions<T = any, F = undefined> {
    /**
     * Filters the input array by element.
     *
     * @param element The specific element to filter from the input array.
     * @returns Whether to keep the specific element in the pick pool.
     */
    filter?: (element: T) => boolean;
    /**
     * The fallback value, when the array is empty, or all elements
     * of the array are filtered out from the pick pool.
     *
     * @default undefined
     */
    fallback?: F;
}
export interface PickObjectOptions<T = any, F = undefined> {
    /**
     * Filters the input object by entry.
     *
     * @param entry The specific entry to filter from the input object.
     * @returns Whether to keep the specific entry in the pick pool.
     */
    filter?: (entry: T) => boolean;
    /**
     * The fallback value, when the object is empty, or all entries
     * of the object are filtered out from the pick pool.
     *
     * @default undefined
     */
    fallback?: F;
}
export default class RandomPick extends RandomGenerator {
    /**
     * Picks a random string (character) from the input string and returns it.
     *
     * @param string The string to pick from.
     */
    pick(string: string): string;
    /**
     * Picks a random string (character) from the input string and returns it.
     *
     * @param string The string to pick from.
     * @param options Pick options (filtering and fallback).
     */
    pick<T = undefined>(string: string, options: PickStringOptions<T>): string | T;
    /**
     * Picks one, or multiple random strings (characters)
     * from the input string and returns it.
     *
     * @param string The string to pick from.
     * @param count The count (length) of the returned string.
     */
    pick(string: string, count: number): string;
    /**
     * Picks one, or multiple random strings (characters)
     * from the input string and returns it.
     *
     * @param string The string to pick from.
     * @param count The count (length) of the returned string.
     * @param options Pick options (filtering and fallback).
     */
    pick<T = undefined>(string: string, count: number, options: PickStringOptions<T>): string | T;
    /**
     * Picks a random element from the input array and returns it.
     *
     * @param array The array to pick from.
     */
    pick<T>(array: ArrayLike<T>): T;
    /**
     * Picks a random element from the input array and returns it.
     *
     * @param array The array to pick from.
     * @param options Pick options (filtering and fallback).
     */
    pick<T, F = undefined>(array: ArrayLike<T>, options: PickArrayOptions<T, F>): T | F;
    /**
     * Picks one, or multiple random elements from
     * the input array and returns it.
     *
     * @param array The array to pick from.
     * @param count The count (length) of elements of the returned array.
     */
    pick<T>(array: ArrayLike<T>, count: number): T[];
    /**
     * Picks one, or multiple random elements from
     * the input array and returns it.
     *
     * @param array The array to pick from.
     * @param count The count (length) of elements of the returned array.
     * @param options Pick options (filtering and fallback).
     */
    pick<T, F = undefined>(array: ArrayLike<T>, count: number, options: PickArrayOptions<T, F>): T[] | F;
    /**
     * Picks a random entry from the input object and returns it.
     *
     * @param object The object to pick from.
     */
    pick<T extends Record<string, any>>(object: T): [keyof T, T[keyof T]];
    /**
     * Picks a random entry from the input object and returns it.
     *
     * @param object The object to pick from.
     * @param options Pick options (filtering and fallback).
     */
    pick<T extends Record<string, any>, F = undefined>(object: T, options: PickObjectOptions<T, F>): [keyof T, T[keyof T]] | F;
    /**
     * Picks one, or multiple random entries from
     * the input object and returns it.
     *
     * @param object The object to pick from.
     * @param count The count (length) of entries of the returned array.
     */
    pick<T extends Record<string, any>>(object: T, count: number): Array<[keyof T, T[keyof T]]>;
    /**
     * Picks one, or multiple random entries from
     * the input object and returns it.
     *
     * @param object The object to pick from.
     * @param count The count (length) of entries of the returned array.
     * @param options Pick options (filtering and fallback).
     */
    pick<T extends Record<string, any>, F = undefined>(object: T, count: number, options: PickObjectOptions<T, F>): Array<[keyof T, T[keyof T]]> | F;
    private _pickString;
    private _pickArray;
    private _pickObject;
}