@rogolev/value 0.0.3 → 0.0.5

package/src/helpers/array/array_walk.mjs

@@ -0,0 +1,95 @@
+import is_array from '../is_array.mjs';
+import is_function from '../is_function.mjs';
+
+/**
+ * Применяет пользовательскую функцию к каждому элементу массива.
+ *
+ * ### Описание
+ *
+ * Функция `array_walk` используется для применения пользовательской функции к каждому элементу массива.
+ * Она поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+ *
+ * ### Параметры
+ *
+ * - `arr` (object): Исходный массив.
+ * - `callback` (function): Функция, которая будет применена к каждому элементу массива.
+ * - `arg` (any): Дополнительный аргумент, который будет передан в функцию обратного вызова. По умолчанию `null`.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true` после успешного выполнения функции для всех элементов массива.
+ *
+ * ### Примеры использования
+ *
+ * 1. Применение функции к каждому элементу обычного массива:
+ *
+ *    ```js
+ *    const array = [1, 2, 3];
+ *    array_walk(array, (value, key) => {
+ *        console.log(`Ключ: ${key}, Значение: ${value}`);
+ *    });
+ *    // Вывод:
+ *    // Ключ: 0, Значение: 1
+ *    // Ключ: 1, Значение: 2
+ *    // Ключ: 2, Значение: 3
+ *    ```
+ *
+ * 2. Применение функции к каждому элементу ассоциативного массива:
+ *
+ *    ```js
+ *    const array = { a: 1, b: 2, c: 3 };
+ *    array_walk(array, (value, key) => {
+ *        console.log(`Ключ: ${key}, Значение: ${value}`);
+ *    });
+ *    // Вывод:
+ *    // Ключ: a, Значение: 1
+ *    // Ключ: b, Значение: 2
+ *    // Ключ: c, Значение: 3
+ *    ```
+ *
+ * 3. Применение функции с дополнительным аргументом:
+ *
+ *    ```js
+ *    const array = [1, 2, 3];
+ *    array_walk(array, (value, key, arg) => {
+ *        console.log(`Ключ: ${key}, Значение: ${value}, Аргумент: ${arg}`);
+ *    }, 'дополнительный аргумент');
+ *    // Вывод:
+ *    // Ключ: 0, Значение: 1, Аргумент: дополнительный аргумент
+ *    // Ключ: 1, Значение: 2, Аргумент: дополнительный аргумент
+ *    // Ключ: 2, Значение: 3, Аргумент: дополнительный аргумент
+ *    ```
+ *
+ * 4. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        array_walk('not an array', (value, key) => {
+ *            console.log(`Ключ: ${key}, Значение: ${value}`);
+ *        });
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "arr" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @param {function} callback Функция, которая будет применена к каждому элементу массива.
+ * @param {any} [arg=null] Дополнительный аргумент, который будет передан в функцию обратного вызова.
+ * @returns {boolean} Возвращает `true` после успешного выполнения функции для всех элементов массива.
+ * @throws {TypeError} Если параметры не являются массивом или функцией.
+ */
+export default function array_walk(arr, callback, arg = null) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    if (!is_function(callback)) {
+        throw new TypeError('Параметр "callback" должен быть функцией.');
+    }
+
+    for (const [k, v] of Object.entries(arr)) {
+        callback(v, k, arg);
+    }
+
+    return true;
+}

package/src/helpers/array/array_walk_recursive.mjs

@@ -0,0 +1,104 @@
+import is_array from '../is_array.mjs';
+import is_function from '../is_function.mjs';
+
+/**
+ * Применяет пользовательскую функцию к каждому элементу массива рекурсивно.
+ *
+ * ### Описание
+ *
+ * Функция `array_walk_recursive` используется для применения пользовательской функции к каждому элементу массива рекурсивно.
+ * Она поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+ *
+ * ### Параметры
+ *
+ * - `arr` (object): Исходный массив.
+ * - `callback` (function): Функция, которая будет применена к каждому элементу массива.
+ * - `arg` (any): Дополнительный аргумент, который будет передан в функцию обратного вызова. По умолчанию `null`.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true` после успешного выполнения функции для всех элементов массива.
+ *
+ * ### Примеры использования
+ *
+ * 1. Применение функции к каждому элементу обычного массива:
+ *
+ *    ```js
+ *    const array = [1, 2, [3, 4], 5];
+ *    array_walk_recursive(array, (value, key) => {
+ *        console.log(`Ключ: ${key}, Значение: ${value}`);
+ *    });
+ *    // Вывод:
+ *    // Ключ: 0, Значение: 1
+ *    // Ключ: 1, Значение: 2
+ *    // Ключ: 0, Значение: 3
+ *    // Ключ: 1, Значение: 4
+ *    // Ключ: 3, Значение: 5
+ *    ```
+ *
+ * 2. Применение функции к каждому элементу ассоциативного массива:
+ *
+ *    ```js
+ *    const array = { a: 1, b: { c: 2, d: 3 }, e: 4 };
+ *    array_walk_recursive(array, (value, key) => {
+ *        console.log(`Ключ: ${key}, Значение: ${value}`);
+ *    });
+ *    // Вывод:
+ *    // Ключ: a, Значение: 1
+ *    // Ключ: c, Значение: 2
+ *    // Ключ: d, Значение: 3
+ *    // Ключ: e, Значение: 4
+ *    ```
+ *
+ * 3. Применение функции с дополнительным аргументом:
+ *
+ *    ```js
+ *    const array = [1, 2, [3, 4], 5];
+ *    array_walk_recursive(array, (value, key, arg) => {
+ *        console.log(`Ключ: ${key}, Значение: ${value}, Аргумент: ${arg}`);
+ *    }, 'дополнительный аргумент');
+ *    // Вывод:
+ *    // Ключ: 0, Значение: 1, Аргумент: дополнительный аргумент
+ *    // Ключ: 1, Значение: 2, Аргумент: дополнительный аргумент
+ *    // Ключ: 0, Значение: 3, Аргумент: дополнительный аргумент
+ *    // Ключ: 1, Значение: 4, Аргумент: дополнительный аргумент
+ *    // Ключ: 3, Значение: 5, Аргумент: дополнительный аргумент
+ *    ```
+ *
+ * 4. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        array_walk_recursive('not an array', (value, key) => {
+ *            console.log(`Ключ: ${key}, Значение: ${value}`);
+ *        });
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "arr" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @param {function} callback Функция, которая будет применена к каждому элементу массива.
+ * @param {any} [arg=null] Дополнительный аргумент, который будет передан в функцию обратного вызова.
+ * @returns {boolean} Возвращает `true` после успешного выполнения функции для всех элементов массива.
+ * @throws {TypeError} Если параметры не являются массивом или функцией.
+ */
+export default function array_walk_recursive(arr, callback, arg = null) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    if (!is_function(callback)) {
+        throw new TypeError('Параметр "callback" должен быть функцией.');
+    }
+
+    for (const [k, v] of Object.entries(arr)) {
+        if (is_array(v)) {
+            array_walk_recursive(v, callback, arg);
+        } else {
+            callback(v, k, arg);
+        }
+    }
+
+    return true;
+}

package/src/helpers/array/count.mjs

@@ -0,0 +1,57 @@
+import is_array from '../is_array.mjs';
+
+/**
+ * Возвращает количество элементов в массиве или ассоциативном массиве.
+ *
+ * ### Описание
+ *
+ * Функция `count` используется для подсчета количества элементов в массиве или ассоциативном массиве (объекте с ключами и значениями).
+ * Она поддерживает как обычные массивы, так и ассоциативные массивы.
+ *
+ * ### Параметры
+ *
+ * - `arr` (object): Исходный массив или ассоциативный массив.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает количество элементов в массиве или ассоциативном массиве.
+ *
+ * ### Примеры использования
+ *
+ * 1. Подсчет элементов в обычном массиве:
+ *
+ *    ```js
+ *    const array = [1, 2, 3, 4, 5];
+ *    const result = count(array);
+ *    console.log(result); // 5
+ *    ```
+ *
+ * 2. Подсчет элементов в ассоциативном массиве:
+ *
+ *    ```js
+ *    const array = { a: 1, b: 2, c: 3 };
+ *    const result = count(array);
+ *    console.log(result); // 3
+ *    ```
+ *
+ * 3. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        const result = count('not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "arr" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {object} arr Исходный массив или ассоциативный массив.
+ * @returns {number} Возвращает количество элементов в массиве или ассоциативном массиве.
+ * @throws {TypeError} Если параметр не является массивом или ассоциативным массивом.
+ */
+export default function count(arr) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    return Object.keys(arr).length;
+}

package/src/helpers/array/in_array.mjs

@@ -0,0 +1,67 @@
+import is_null from '../is_null.mjs';
+import array_search from './array_search.mjs';
+
+/**
+ * Проверяет, существует ли значение в массиве.
+ *
+ * ### Описание
+ *
+ * Функция `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" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @param {any} value Значение для поиска.
+ * @param {boolean} [strict=false] Флаг строгого сравнения.
+ * @returns {boolean} Возвращает `true`, если значение существует в массиве, иначе `false`.
+ * @throws {TypeError} Если параметр не является массивом или если параметр strict не является логическим значением.
+ */
+export default function in_array(arr, value, strict = false) {
+    return !is_null(array_search(arr, value, strict));
+}

package/src/helpers/array/natsort.mjs

@@ -0,0 +1,62 @@
+import is_function from '../is_function.mjs';
+import natcompare from '../string/natcompare.mjs';
+import to_string from '../to_string.mjs';
+import sort from './sort.mjs';
+
+/**
+ * Сортирует массив в естественном порядке.
+ *
+ * ### Описание
+ *
+ * Функция `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 }]
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @param {function} [getter=(entry) => entry[1]] Функция для получения значения для сравнения.
+ * @returns {array} Новый массив, отсортированный в естественном порядке.
+ * @throws {TypeError} Если параметр `arr` не является массивом.
+ * @throws {TypeError} Если параметр `getter` не является функцией.
+ */
+export default function natsort(arr, getter = (entry) => entry[1]) {
+    if (!is_function(getter)) {
+        throw new TypeError('Параметр "getter" должен быть функцией.');
+    }
+
+    return sort(arr, (a, b) => natcompare(to_string(getter(a)), to_string(getter(b))));
+}

package/src/helpers/array/range.mjs

@@ -0,0 +1,121 @@
+import is_float from '../is_float.mjs';
+import is_int from '../is_int.mjs';
+import is_nan from '../is_nan.mjs';
+import is_string from '../is_string.mjs';
+import to_float from '../to_float.mjs';
+
+/**
+ * Генерирует массив значений от start до end с шагом step.
+ *
+ * ### Описание
+ *
+ * Функция `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]
+ *    ```
+ *
+ * @param {string|number} start Начальное значение (строка или число).
+ * @param {string|number} end Конечное значение (строка или число).
+ * @param {number} [step=1] Шаг между значениями.
+ * @returns {Array} Массив значений от start до end с шагом step.
+ * @throws {TypeError} Если параметры имеют неверный тип или значение.
+ */
+export default function range(start, end, step = 1) {
+    if (!is_string(start) && !is_int(start) && !is_float(start)) {
+        throw new TypeError('Параметр "start" должен быть строкой или числом.');
+    }
+
+    if (!is_string(end) && !is_int(end) && !is_float(end)) {
+        throw new TypeError('Параметр "end" должен быть строкой или числом.');
+    }
+
+    if (!is_int(step) && !is_float(step)) {
+        throw new TypeError('Параметр "step" должен быть числом.');
+    }
+
+    if (step === 0) {
+        throw new TypeError('Параметр "step" не может быть равен нулю.');
+    }
+
+    if (start < end && step < 0) {
+        throw new TypeError('Параметр "step" должен быть больше нуля при start <= end.');
+    }
+
+    step = Math.abs(step);
+
+    if (start === '') {
+        start = 0;
+    }
+
+    if (end === '') {
+        end = 0;
+    }
+
+    if (is_string(start) && (is_int(end) || is_float(end))) {
+        start = is_nan(to_float(start)) ? 0 : to_float(start);
+    }
+
+    if ((is_int(start) || is_float(start)) && is_string(end)) {
+        end = is_nan(to_float(end)) ? 0 : to_float(end);
+    }
+
+    let next;
+
+    if ((is_int(start) || is_float(start)) && (is_int(end) || is_float(end))) {
+        next = start < end ? (value) => (value += step) : (value) => (value -= step);
+    } else {
+        next =
+            start < end ?
+                (value) => String.fromCharCode(value.charCodeAt(0) + step)
+            :   (value) => String.fromCharCode(value.charCodeAt(0) - step);
+    }
+
+    const result = [];
+
+    let value = is_string(start) ? start.at(0) : start;
+
+    do {
+        result.push(value);
+        value = next(value);
+    } while (start < end ? value <= end : value >= end);
+
+    return result;
+}

package/src/helpers/array/shuffle.mjs

@@ -0,0 +1,73 @@
+import is_array from '../is_array.mjs';
+import is_list from '../is_list.mjs';
+import array_rand from './array_rand.mjs';
+
+/**
+ * Перемешивает элементы массива в случайном порядке.
+ *
+ * ### Описание
+ *
+ * Функция `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]] (пример)
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @returns {array} Новый массив с элементами в случайном порядке.
+ * @throws {TypeError} Если параметр не является массивом.
+ */
+export default function shuffle(arr) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    const count = Object.keys(arr).length;
+
+    if (count === 0 || count === 1) {
+        return arr;
+    }
+
+    const rand_keys = array_rand(arr, count);
+
+    if (is_list(arr)) {
+        const rand_values = [];
+
+        for (const key of rand_keys) {
+            rand_values.push(arr[key]);
+        }
+
+        return rand_values;
+    }
+
+    const result = [];
+
+    for (const key of rand_keys) {
+        result.push([key, arr[key]]);
+    }
+
+    return result;
+}

package/src/helpers/array/sort.mjs

@@ -0,0 +1,69 @@
+import is_array from '../is_array.mjs';
+import is_function from '../is_function.mjs';
+import is_list from '../is_list.mjs';
+
+/**
+ * Сортирует элементы массива с использованием функции сравнения.
+ *
+ * ### Описание
+ *
+ * Функция `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]
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @param {function} [compare_func=(a, b) => a[1] - b[1]] Функция сравнения, используемая для сортировки.
+ * @returns {array} Новый массив с отсортированными элементами.
+ * @throws {TypeError} Если параметр не является массивом или если параметр compare_func не является функцией.
+ */
+export default function sort(arr, compare_func = (a, b) => a[1] - b[1]) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    if (!is_function(compare_func)) {
+        throw new TypeError('Параметр "compare_func" должен быть функцией.');
+    }
+
+    const result = Object.entries(arr).sort(compare_func);
+
+    if (is_list(arr)) {
+        return result.map(([, v]) => v);
+    }
+
+    return result;
+}