@rogolev/value 0.0.3 → 0.0.5

package/docs/helpers/array/in_array.md

@@ -0,0 +1,65 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / in_array
+
+[Исходный код](../../../src/helpers/array/in_array.mjs)
+
+# in_array
+
+`in_array` — Проверяет, существует ли значение в массиве.
+
+## Сигнатура функции
+
+```ts
+function in_array(arr: object, value: any, strict: boolean = false): boolean;
+```
+
+## Описание
+
+Функция `in_array` используется для проверки, существует ли значение в массиве. Она поддерживает как
+обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями). Функция может
+работать в строгом режиме, сравнивая значения с учетом типа.
+
+## Параметры
+
+- `arr` (object): Исходный массив.
+- `value` (any): Значение для поиска.
+- `strict` (boolean): Флаг строгого сравнения. По умолчанию `false`.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение существует в массиве, иначе `false`.
+
+## Примеры использования
+
+1. Проверка значения в обычном массиве:
+
+    ```js
+    const array = [1, 2, 3, 4, 5];
+    const result = in_array(array, 3);
+    console.log(result); // true
+    ```
+
+2. Проверка значения в ассоциативном массиве:
+
+    ```js
+    const array = { a: 1, b: 2, c: 3 };
+    const result = in_array(array, 2);
+    console.log(result); // true
+    ```
+
+3. Проверка значения с использованием строгого сравнения:
+
+    ```js
+    const array = [1, '2', 3];
+    const result = in_array(array, 2, true);
+    console.log(result); // false
+    ```
+
+4. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = in_array('not an array', 1);
+    } catch (e) {
+        console.error(e.message); // Параметр "arr" должен быть массивом.
+    }
+    ```

package/docs/helpers/array/natsort.md

@@ -0,0 +1,60 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / natsort
+
+[Исходный код](../../../src/helpers/array/natsort.mjs)
+
+# natsort
+
+`natsort` — Сортирует массив в естественном порядке.
+
+## Сигнатура функции
+
+```ts
+function natsort(arr: object, getter: function = (entry) => entry[1]): array;
+```
+
+## Описание
+
+Функция `natsort` используется для сортировки массива в естественном порядке. Она поддерживает как
+обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями). Функция принимает
+необязательный параметр `getter`, который используется для получения значения для сравнения.
+
+## Параметры
+
+- `arr` (object): Исходный массив.
+- `getter` (function): Функция для получения значения для сравнения. По умолчанию
+  `(entry) => entry[1]`.
+
+## Возвращаемое значение
+
+Возвращает новый массив, отсортированный в естественном порядке.
+
+## Примеры использования
+
+1. Сортировка обычного массива:
+
+    ```js
+    const array = [10, 2, 30, 4];
+    const result = natsort(array);
+    console.log(result); // [2, 4, 10, 30]
+    ```
+
+2. Сортировка ассоциативного массива:
+
+    ```js
+    const array = { a: 10, b: 2, c: 30, d: 4 };
+    const result = natsort(array);
+    console.log(result); // [['b', 2], ['d', 4], ['a', 10], ['c', 30]]
+    ```
+
+3. Сортировка массива с использованием функции `getter`:
+
+    ```js
+    const array = [{ value: 10 }, { value: 2 }, { value: 30 }, { value: 4 }];
+    const result = natsort(array, (entry) => entry[1].value);
+    console.log(result); // [{ value: 2 }, { value: 4 }, { value: 10 }, { value: 30 }]
+    ```
+
+## Исключения
+
+- `TypeError`: Если параметр `arr` не является массивом.
+- `TypeError`: Если параметр `getter` не является функцией.

package/docs/helpers/array/range.md

@@ -0,0 +1,76 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / range
+
+[Исходный код](../../../src/helpers/array/range.mjs)
+
+# range
+
+`range` — Генерирует массив значений от start до end с шагом step.
+
+## Сигнатура функции
+
+```ts
+function range(start: string | number, end: string | number, step: number = 1): Array<any>;
+```
+
+## Описание
+
+Функция `range` используется для генерации массива значений от начального значения до конечного с
+заданным шагом. Она поддерживает как числовые значения, так и строки. Шаг не может быть равен нулю.
+
+## Параметры
+
+- `start` (string | number): Начальное значение (строка или число).
+- `end` (string | number): Конечное значение (строка или число).
+- `step` (number): Шаг между значениями. По умолчанию `1`.
+
+## Возвращаемое значение
+
+Возвращает массив значений от start до end с шагом step.
+
+## Примеры использования
+
+1. Генерация числового диапазона:
+
+    ```js
+    const result = range(1, 5);
+    console.log(result); // [1, 2, 3, 4, 5]
+    ```
+
+2. Генерация диапазона с отрицательным шагом:
+
+    ```js
+    const result = range(5, 1, -1);
+    console.log(result); // [5, 4, 3, 2, 1]
+    ```
+
+3. Генерация диапазона строк:
+
+    ```js
+    const result = range('a', 'e');
+    console.log(result); // ['a', 'b', 'c', 'd', 'e']
+    ```
+
+4. Обработка значений с преобразованием типов:
+
+    ```js
+    const result = range('1', 5);
+    console.log(result); // [1, 2, 3, 4, 5]
+    ```
+
+5. Обработка пустых строк:
+
+    ```js
+    const result = range('', 3);
+    console.log(result); // [0, 1, 2, 3]
+    ```
+
+6. Обработка строк и чисел:
+
+    ```js
+    const result = range('1', '5');
+    console.log(result); // [1, 2, 3, 4, 5]
+    ```
+
+## Исключения
+
+- `TypeError`: Если параметры имеют неверный тип или значение.

package/docs/helpers/array/shuffle.md

@@ -0,0 +1,74 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / shuffle
+
+[Исходный код](../../../src/helpers/array/shuffle.mjs)
+
+# shuffle
+
+`shuffle` — Перемешивает элементы массива в случайном порядке.
+
+## Сигнатура функции
+
+```ts
+function shuffle(arr: object): Array<any>;
+```
+
+## Описание
+
+Функция `shuffle` используется для перемешивания элементов массива в случайном порядке. Она
+поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+
+## Параметры
+
+- `arr` (object): Исходный массив.
+
+## Возвращаемое значение
+
+Возвращает новый массив с элементами в случайном порядке.
+
+## Примеры использования
+
+1. Перемешивание обычного массива:
+
+    ```js
+    const array = [1, 2, 3, 4, 5];
+    const result = shuffle(array);
+    console.log(result); // [3, 1, 5, 2, 4] (пример)
+    ```
+
+2. Перемешивание ассоциативного массива:
+
+    ```js
+    const array = { a: 1, b: 2, c: 3 };
+    const result = shuffle(array);
+    console.log(result); // [['b', 2], ['a', 1], ['c', 3]] (пример)
+    ```
+
+3. Обработка пустого массива:
+
+    ```js
+    const array = [];
+    const result = shuffle(array);
+    console.log(result); // []
+    ```
+
+4. Обработка массива с одним элементом:
+
+    ```js
+    const array = [1];
+    const result = shuffle(array);
+    console.log(result); // [1]
+    ```
+
+5. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = shuffle('not an array');
+    } catch (e) {
+        console.error(e.message); // Параметр "arr" должен быть массивом.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если параметр не является массивом.

package/docs/helpers/array/sort.md

@@ -0,0 +1,79 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / sort
+
+[Исходный код](../../../src/helpers/array/sort.mjs)
+
+# sort
+
+`sort` — Сортирует элементы массива с использованием функции сравнения.
+
+## Сигнатура функции
+
+```ts
+function sort(arr: object, compare_func: function = (a, b) => a[1] - b[1]): Array<any>;
+```
+
+## Описание
+
+Функция `sort` используется для сортировки элементов массива с использованием функции сравнения. Она
+поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+
+## Параметры
+
+- `arr` (object): Исходный массив.
+- `compare_func` (function): Функция сравнения, используемая для сортировки. По умолчанию
+  `(a, b) => a[1] - b[1]`.
+
+## Возвращаемое значение
+
+Возвращает новый массив с отсортированными элементами.
+
+## Примеры использования
+
+1. Сортировка обычного массива:
+
+    ```js
+    const array = [5, 3, 1, 4, 2];
+    const result = sort(array);
+    console.log(result); // [1, 2, 3, 4, 5]
+    ```
+
+2. Сортировка ассоциативного массива:
+
+    ```js
+    const array = { a: 3, b: 1, c: 2 };
+    const result = sort(array);
+    console.log(result); // [['b', 1], ['c', 2], ['a', 3]]
+    ```
+
+3. Сортировка с использованием пользовательской функции сравнения:
+
+    ```js
+    const array = [5, 3, 1, 4, 2];
+    const result = sort(array, (a, b) => b[1] - a[1]);
+    console.log(result); // [5, 4, 3, 2, 1]
+    ```
+
+4. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = sort('not an array');
+    } catch (e) {
+        console.error(e.message); // Параметр "arr" должен быть массивом.
+    }
+    ```
+
+5. Обработка значений параметра compare_func, не являющихся функцией:
+
+    ```js
+    try {
+        const result = sort([1, 2, 3], 'not a function');
+    } catch (e) {
+        console.error(e.message); // Параметр "compare_func" должен быть функцией.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если параметр не является массивом или если параметр compare_func не является
+  функцией.

package/docs/helpers/expect.md

@@ -0,0 +1,58 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect
+
+[Исходный код](../../src/helpers/expect.mjs)
+
+# expect
+
+`expect` — Функция, создающая новый экземпляр класса `Expect` для проверки значений.
+
+## Сигнатура функции
+
+```ts
+function expect(actual: any): Expect;
+```
+
+## Описание
+
+Функция `expect` используется для создания нового экземпляра класса `Expect`, который предоставляет
+методы для проверки различных свойств и типов значений. Она принимает одно значение, которое будет
+проверяться методами класса `Expect`.
+
+## Параметры
+
+- `actual` (any): Значение, которое будет проверяться методами класса `Expect`.
+
+## Возвращаемое значение
+
+Возвращает новый экземпляр класса `Expect`.
+
+## Примеры использования
+
+1. Создание экземпляра класса `Expect` и проверка значения:
+
+    ```js
+    expect(5).toBe(5); // true
+    ```
+
+2. Проверка значения, являющегося массивом:
+
+    ```js
+    expect([1, 2, 3]).toBeArray(); // true
+    ```
+
+3. Проверка значения, являющегося BigInt:
+
+    ```js
+    expect(123n).toBeBigInt(); // true
+    ```
+
+4. Проверка значения, являющегося объектом:
+
+    ```js
+    class stdClass {}
+    expect(new stdClass()).toBeObject(); // true
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не соответствует ожидаемому типу или значению.

package/docs/helpers/expect_array.md

@@ -0,0 +1,63 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect_array
+
+[Исходный код](../../src/helpers/expect_array.mjs)
+
+# expect_array
+
+`expect_array` — Проверяет, является ли значение массивом, и выбрасывает ошибку с указанным
+сообщением, если это не так.
+
+## Сигнатура функции
+
+```ts
+function expect_array(arr: any, message: string = ''): boolean;
+```
+
+## Описание
+
+Функция `expect_array` используется для проверки, является ли переданное значение массивом. Если
+значение не является массивом, функция выбрасывает ошибку типа `TypeError` с указанным сообщением.
+
+## Параметры
+
+- `arr` (any): Значение для проверки.
+- `message` (string): Сообщение об ошибке, если значение не является массивом. По умолчанию пустая
+  строка.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является массивом.
+
+## Примеры использования
+
+1. Проверка значения, являющегося массивом:
+
+    ```js
+    const array = [1, 2, 3];
+    const result = expect_array(array);
+    console.log(result); // true
+    ```
+
+2. Проверка значения, не являющегося массивом:
+
+    ```js
+    try {
+        const result = expect_array('not an array', 'Значение должно быть массивом.');
+    } catch (e) {
+        console.error(e.message); // Значение должно быть массивом.
+    }
+    ```
+
+3. Проверка значения с использованием пользовательского сообщения об ошибке:
+
+    ```js
+    try {
+        const result = expect_array(123, 'Ожидался массив.');
+    } catch (e) {
+        console.error(e.message); // Ожидался массив.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не является массивом или если параметр `message` не является строкой.

package/docs/helpers/expect_assoc.md

@@ -0,0 +1,65 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect_assoc
+
+[Исходный код](../../src/helpers/expect_assoc.mjs)
+
+# expect_assoc
+
+`expect_assoc` — Проверяет, является ли значение ассоциативным массивом, и выбрасывает ошибку
+с указанным сообщением, если это не так.
+
+## Сигнатура функции
+
+```ts
+function expect_assoc(arr: any, message: string = ''): boolean;
+```
+
+## Описание
+
+Функция `expect_assoc` используется для проверки, является ли переданное значение ассоциативным
+массивом. Если значение не является ассоциативным массивом, функция выбрасывает ошибку типа
+`TypeError` с указанным сообщением.
+
+## Параметры
+
+- `arr` (any): Значение для проверки.
+- `message` (string): Сообщение об ошибке, если значение не является ассоциативным массивом. По
+  умолчанию пустая строка.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является ассоциативным массивом.
+
+## Примеры использования
+
+1. Проверка значения, являющегося ассоциативным массивом:
+
+    ```js
+    const assoc = { a: 1, b: 2, c: 3 };
+    const result = expect_assoc(assoc);
+    console.log(result); // true
+    ```
+
+2. Проверка значения, не являющегося ассоциативным массивом:
+
+    ```js
+    try {
+        const result = expect_assoc([1, 2, 3], 'Значение должно быть ассоциативным массивом.');
+    } catch (e) {
+        console.error(e.message); // Значение должно быть ассоциативным массивом.
+    }
+    ```
+
+3. Проверка значения с использованием пользовательского сообщения об ошибке:
+
+    ```js
+    try {
+        const result = expect_assoc(123, 'Ожидался ассоциативный массив.');
+    } catch (e) {
+        console.error(e.message); // Ожидался ассоциативный массив.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не является ассоциативным массивом или если параметр `message` не
+  является строкой.

package/docs/helpers/expect_bigint.md

@@ -0,0 +1,63 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect_bigint
+
+[Исходный код](../../src/helpers/expect_bigint.mjs)
+
+# expect_bigint
+
+`expect_bigint` — Проверяет, является ли значение BigInt, и выбрасывает ошибку с указанным
+сообщением, если это не так.
+
+## Сигнатура функции
+
+```ts
+function expect_bigint(value: any, message: string = ''): boolean;
+```
+
+## Описание
+
+Функция `expect_bigint` используется для проверки, является ли переданное значение BigInt. Если
+значение не является BigInt, функция выбрасывает ошибку типа `TypeError` с указанным сообщением.
+
+## Параметры
+
+- `value` (any): Значение для проверки.
+- `message` (string): Сообщение об ошибке, если значение не является BigInt. По умолчанию пустая
+  строка.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является BigInt.
+
+## Примеры использования
+
+1. Проверка значения, являющегося BigInt:
+
+    ```js
+    const value = 123n;
+    const result = expect_bigint(value);
+    console.log(result); // true
+    ```
+
+2. Проверка значения, не являющегося BigInt:
+
+    ```js
+    try {
+        const result = expect_bigint(123, 'Значение должно быть BigInt.');
+    } catch (e) {
+        console.error(e.message); // Значение должно быть BigInt.
+    }
+    ```
+
+3. Проверка значения с использованием пользовательского сообщения об ошибке:
+
+    ```js
+    try {
+        const result = expect_bigint('123', 'Ожидался BigInt.');
+    } catch (e) {
+        console.error(e.message); // Ожидался BigInt.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не является BigInt или если параметр `message` не является строкой.

package/docs/helpers/expect_bool.md

@@ -0,0 +1,65 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect_bool
+
+[Исходный код](../../src/helpers/expect_bool.mjs)
+
+# expect_bool
+
+`expect_bool` — Проверяет, является ли значение логическим типом, и выбрасывает ошибку с
+указанным сообщением, если это не так.
+
+## Сигнатура функции
+
+```ts
+function expect_bool(value: any, message: string = ''): boolean;
+```
+
+## Описание
+
+Функция `expect_bool` используется для проверки, является ли переданное значение логическим типом.
+Если значение не является логическим типом, функция выбрасывает ошибку типа `TypeError` с указанным
+сообщением.
+
+## Параметры
+
+- `value` (any): Значение для проверки.
+- `message` (string): Сообщение об ошибке, если значение не является логическим типом. По умолчанию
+  пустая строка.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является логическим типом.
+
+## Примеры использования
+
+1. Проверка значения, являющегося логическим типом:
+
+    ```js
+    const value = true;
+    const result = expect_bool(value);
+    console.log(result); // true
+    ```
+
+2. Проверка значения, не являющегося логическим типом:
+
+    ```js
+    try {
+        const result = expect_bool(123, 'Значение должно быть логическим типом.');
+    } catch (e) {
+        console.error(e.message); // Значение должно быть логическим типом.
+    }
+    ```
+
+3. Проверка значения с использованием пользовательского сообщения об ошибке:
+
+    ```js
+    try {
+        const result = expect_bool('true', 'Ожидался логический тип.');
+    } catch (e) {
+        console.error(e.message); // Ожидался логический тип.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не является логическим типом или если параметр `message` не является
+  строкой.