Коллекция рандомайзеров.

Библиотка javascript/typescript (ES6) для node.js.

• генератор случайных значений,
• генерация в заданном диапазоне,
• генерация со смещением вероятности в большую или меньшую сторону,
• генератор true/false,
• генератор строк,
• генератор email адресов,
• генератор даты и времени,
• тестирование генераторов.

Установка

npm install lib-random

или

yarn add lib-random

Начало работы

Можно импортировать методы как с отдельные функции:

import { random } from 'lib-random';

const randValue = random(1, 10);
print('Generated value is: ' + randValue);

или вызывать их как статические методы объекта:

import * as random from 'lib-random';

const randValue = random.randomBoolean();
print('Generated value is: ' + randValue);

Генератор случайных чисел

random(min, max, step = 1, offset = 0.5)

Отличия от стандартного генератора:

• работает в диапазоне значений,
• можно задать шаг,
• можно задать смещение,

От min до max с шагом step (по-умолчанию, 1) и смещением (по-умолчанию, 0.5).

Например вызов random(1, 10) выдаст число от 1 до 10.

Вызов random(1, 10, 5) выдаст число 5 или 10.

Вызов random(0, 1, 0.1) выдаст одно из чисел: 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.

Можно указывать отрицательные числа.

Смещение работает в диапазоне от 0 до 1. Чем ближе смещение к границе, тем чаще и с большей вероятностью сгенерированное число будет ближе к предельному (минимальному или максимальному) значению. Вероятность сокращает, но не исключает попадание числа в противоположные предельные значения.

Примеры

Кубик:

random(1, 6);

Проценты:

random(0, 100);

Температура:

random(-100, 100, 0.1);

От 0 до 10 без смещения:

random(0, 10);

На 10 генераций среднее значение 5.7, мин 1, макс 10.

От 0 до 10 со смещением в большую сторону:

random(0, 10, 1, 1);

На 10 генераций среднее значение 8.8, мин 5, макс 10

От 0 до 10 со смещением в меньшую сторону:

random(0, 10, 1, 0);

На 10 генераций среднее значение 3.4, мин 0, макс 8

Генератор последовательности чисел

generate(min, max, step = 1)

Возвращает массив последовательности чисел от min до max с шагом step (по-умолчанию, 1).

Например вызов generate(1, 10) выдаст массив чисел от 1 до 10:

[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

Вызов generate(0, 1, 0.1) выдаст:

[0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1]

Можно указывать отрицательные числа.

Генератор последовательности символов

generateString(min, max, step = 1)

Возвращает массив последовательности сиволов от min до max с шагом step (по-умолчанию, 1).

Например вызов generateString('A', 'F') выдаст массив символов от A до F:

['A', 'B', 'C', 'D', 'E', 'F']

Перемешивание

shuffle(array)

Перемешивает элементы массива случайным образом.

Вместо массива можно указать строку.

Возвращает новый массив, при этом старый не изменяется.

Список прочих методов

randomArray(n, callback)

Генератор массива заданной длины.

Аргумент n задает длину массива.

В аргумент callback можно передать функцию, которая будет заполнять массив элементами. На вход функции подается текущий элемент.

По-умолчанию массив заполняется значениями от 0 до заданной длины.

Если вы хотите создать пустой массив, можно использовать: randomArray(10, () => null).

Если вы хотите создать массив со значениями от 1, можно использовать: randomArray(10, (i) => i + 1).

Вы также можете заполнить массив случайными значениями, например: randomArray(10, () => random(1, 10)).

randomArrayValue(array)

Выбор одного случайного значения из переданных.

В аргумент array передется массив, например: randomArrayValue([1, 2, 3]).

randomBoolean()

Генерирует случайное значение true или false.

randomDatetime(min, max, format)

Генерирует случайную дату и время в заданном диапазоне.

Даты указываются в любом формате, который поддерживается js нативно. Даты возвращаются в заданном формате format, по-умолчанию YYYY-MM-DD HH:mm:ss.

Можно указывать только дату, без времени.

randomEmail({ min, max, string, domain })

Генератор email-адреса в правильном формате.

Атрибуты min и max задают размер имени почтового адреса, string задает символы, из которых адрес будет сгенерирован.

Атрибут domain позволяет задать почтовый домен. Если он не будет задан, то домен сгенерируется из букв английского алфавита.

Можно запускать с параметрами по-умолчанию: randomEmail()

randomName(...)

Сложный метод генерации псевдоимен.

Используется только как вспомогательный метод.

Вместо него можно использовать другие методы:

randomNames(words = 1)

Аргумент words задает число слов в имени.

На выходе отдается массив. Первым индексом идет признак рода имени:

• 0 - женский род,
• 1 - мужской род.

Чтобы получить строку с именем и фамилией, можно вызвать метод так: name = randomRuName(2); fullName = `${name[1]} ${name[2]}`.

randomNamesRu(words = 1)

Генератор псевдоимен с русскими буквами.

Слова генерируются в таком порядке: имя, фамилия, отчество.

randomNamesEn(words = 1)

Генератор псевдоимен с латинскими буквами.

Слова генерируются в таком порядке: фамилия, имя, второе имя и т.д.

randomString(min, max, string)

Генератор случайных строк.

От min до max символов.

Если аргумент max не задан, то число символов в строке будет равно min.

Аргумент string задает строку, из которой будут браться символы.

Например: randomSet(1, 10, 'abcdef').

Тестирование

tester(callback, args, iterations)

В callback передается функция генерации случайных числе.

В args в виде массива передается набор аргументов для функции. Или пустой массив, если аргументы не нужны.

В iterations указывается количество вызовов генератора.

По итогу составляется отчет:

{
  iterations: ...,
  total: ...,
  average: ...,
  max: ...,
  min: ...,
  time: ...,
}

• iterations - число итераций,
• total - общая сумма всех сгенерированных чисел,
• average - среднее значение,
• max - самое максимальное сгенерированное число,
• min - самое минимальное сгенерированное число,
• time - суммарно затраченное время, учитывается только время работы генератора, без обработки.

Пример запуска.

import { tester, random } from 'lib-random';

const params = {
  min: 1,
  max: 6,
  step: 1,
  offset: 0.5,
};

const report = tester(random, [min, max, step, offset], 10);

Пример запуска встроенного генератора js.

import { tester } from 'lib-random';

const report = tester(Math.random, [], 10);

Для проверки работы мы рекомендуем ставить небольшие значения итераций, от 10 до 100. Более высокие значения смазывают разброс и разница в генециях не будет заметна.

Для сравнения производительности по времени, лучше, наоборот, ставить большие значения, например 1000000 и выше, иначе просто не будет видно разницу по времени выполнения.

Похожим образом можно протестировать и сравнить любые генераторы.

Обработка ошибок

Все вызовы возвращают ошибки как есть, без дополнительных перехватов и обработки. Поэтому оборачиваем в try/catch самостоятельно.

async function customFunction(min, max) {
  try {
    const result = random.number(min, max);

    return { result };
  } catch (error) {
    return { error };
  }
}

Версии

0.2.1

Добавлены генераторы последовательности чисел и строк.

Поддержка

Больше интересных библиотек в репозитории.

Если библиотека понравилась, и вы хотите меня поддержать, не пожалейте поставить звездочку.

А сейчас просто обнимите своих родных и близких, скажите им, как вы их любите.

Лицензия

Лицензия MIT, 2025