@rogolev/value 0.0.3 → 0.0.5

package/src/helpers/array/array_key_to_lower_case.mjs

@@ -0,0 +1,71 @@
+import array from '../array.mjs';
+import is_array from '../is_array.mjs';
+import is_list from '../is_list.mjs';
+
+/**
+ * Преобразует ключи ассоциативного массива в нижний регистр.
+ *
+ * ### Описание
+ *
+ * Функция `array_key_to_lower_case` используется для преобразования всех ключей ассоциативного массива в нижний регистр.
+ * Если переданное значение не является массивом, функция выбрасывает ошибку типа `TypeError`.
+ * Если переданное значение является списком (обычным массивом), оно возвращается без изменений.
+ *
+ * ### Параметры
+ *
+ * - `value` (object): Ассоциативный массив, ключи которого необходимо преобразовать в нижний регистр.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает новый ассоциативный массив с ключами в нижнем регистре.
+ * Если переданное значение является списком, оно возвращается без изменений.
+ *
+ * ### Примеры использования
+ *
+ * 1. Преобразование ключей ассоциативного массива в нижний регистр:
+ *
+ *    ```js
+ *    const assoc = { Key1: 'value1', Key2: 'value2' };
+ *    const result = array_key_to_lower_case(assoc);
+ *    console.log(result); // { key1: 'value1', key2: 'value2' }
+ *    ```
+ *
+ * 2. Обработка списка (обычного массива):
+ *
+ *    ```js
+ *    const list = [1, 2, 3];
+ *    const result = array_key_to_lower_case(list);
+ *    console.log(result); // [1, 2, 3]
+ *    ```
+ *
+ * 3. Обработка значения, не являющегося массивом:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_key_to_lower_case('not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "array" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {object} value Ассоциативный массив, ключи которого необходимо преобразовать в нижний регистр.
+ * @returns {object} Возвращает новый ассоциативный массив с ключами в нижнем регистре.
+ * @throws {TypeError} Если переданное значение не является массивом.
+ */
+export default function array_key_to_lower_case(value) {
+    if (!is_array(value)) {
+        throw new TypeError('Параметр "array" должен быть массивом.');
+    }
+
+    if (is_list(value)) {
+        return value;
+    }
+
+    const result = array({});
+
+    for (const k in value) {
+        result[k.toLowerCase()] = value[k];
+    }
+
+    return result;
+}

package/src/helpers/array/array_key_to_upper_case.mjs

@@ -0,0 +1,71 @@
+import array from '../array.mjs';
+import is_array from '../is_array.mjs';
+import is_list from '../is_list.mjs';
+
+/**
+ * Преобразует ключи ассоциативного массива в верхний регистр.
+ *
+ * ### Описание
+ *
+ * Функция `array_key_to_upper_case` используется для преобразования всех ключей ассоциативного массива в верхний регистр.
+ * Если переданное значение не является массивом, функция выбрасывает ошибку типа `TypeError`.
+ * Если переданное значение является списком (обычным массивом), оно возвращается без изменений.
+ *
+ * ### Параметры
+ *
+ * - `value` (object): Ассоциативный массив, ключи которого необходимо преобразовать в верхний регистр.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает новый ассоциативный массив с ключами в верхнем регистре.
+ * Если переданное значение является списком, оно возвращается без изменений.
+ *
+ * ### Примеры использования
+ *
+ * 1. Преобразование ключей ассоциативного массива в верхний регистр:
+ *
+ *    ```js
+ *    const assoc = { key1: 'value1', key2: 'value2' };
+ *    const result = array_key_to_upper_case(assoc);
+ *    console.log(result); // { KEY1: 'value1', KEY2: 'value2' }
+ *    ```
+ *
+ * 2. Обработка списка (обычного массива):
+ *
+ *    ```js
+ *    const list = [1, 2, 3];
+ *    const result = array_key_to_upper_case(list);
+ *    console.log(result); // [1, 2, 3]
+ *    ```
+ *
+ * 3. Обработка значения, не являющегося массивом:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_key_to_upper_case('not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "array" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {object} value Ассоциативный массив, ключи которого необходимо преобразовать в верхний регистр.
+ * @returns {object} Возвращает новый ассоциативный массив с ключами в верхнем регистре.
+ * @throws {TypeError} Если переданное значение не является массивом.
+ */
+export default function array_key_to_upper_case(value) {
+    if (!is_array(value)) {
+        throw new TypeError('Параметр "array" должен быть массивом.');
+    }
+
+    if (is_list(value)) {
+        return value;
+    }
+
+    const result = array({});
+
+    for (const k in value) {
+        result[k.toUpperCase()] = value[k];
+    }
+
+    return result;
+}

package/src/helpers/array/array_keys.mjs

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

package/src/helpers/array/array_map.mjs

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

package/src/helpers/array/array_merge.mjs

@@ -0,0 +1,95 @@
+import array from '../array.mjs';
+import empty from '../empty.mjs';
+import is_array from '../is_array.mjs';
+import is_int from '../is_int.mjs';
+import is_list from '../is_list.mjs';
+
+/**
+ * Объединяет несколько массивов в один.
+ *
+ * ### Описание
+ *
+ * Функция `array_merge` используется для объединения нескольких массивов в один.
+ * Она поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+ *
+ * ### Параметры
+ *
+ * - `...arrays` (object): Массивы, которые необходимо объединить.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает новый массив, содержащий элементы всех переданных массивов.
+ * Если все переданные массивы являются обычными массивами, результатом будет обычный массив.
+ * Если хотя бы один из переданных массивов является ассоциативным массивом, результатом будет ассоциативный массив.
+ *
+ * ### Примеры использования
+ *
+ * 1. Объединение обычных массивов:
+ *
+ *    ```js
+ *    const array1 = [1, 2, 3];
+ *    const array2 = [4, 5, 6];
+ *    const result = array_merge(array1, array2);
+ *    console.log(result); // [1, 2, 3, 4, 5, 6]
+ *    ```
+ *
+ * 2. Объединение ассоциативных массивов:
+ *
+ *    ```js
+ *    const array1 = { a: 1, b: 2 };
+ *    const array2 = { c: 3, d: 4 };
+ *    const result = array_merge(array1, array2);
+ *    console.log(result); // { a: 1, b: 2, c: 3, d: 4 }
+ *    ```
+ *
+ * 3. Объединение обычных и ассоциативных массивов:
+ *
+ *    ```js
+ *    const array1 = [1, 2, 3];
+ *    const array2 = { a: 4, b: 5 };
+ *    const result = array_merge(array1, array2);
+ *    console.log(result); // { 0: 1, 1: 2, 2: 3, a: 4, b: 5 }
+ *    ```
+ *
+ * 4. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_merge('not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "arrays" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {...object} arrays Массивы, которые необходимо объединить.
+ * @returns {object} Возвращает новый массив, содержащий элементы всех переданных массивов.
+ * @throws {TypeError} Если хотя бы один из параметров не является массивом.
+ */
+export default function array_merge(...arrays) {
+    if (!arrays.every((arr) => is_array(arr))) {
+        throw new TypeError('Параметр "arrays" должен быть массивом.');
+    }
+
+    if (empty(arrays)) {
+        return [];
+    }
+
+    if (arrays.every((arr) => is_list(arr))) {
+        return [].concat(...arrays);
+    }
+
+    const result = array({});
+    let index = 0;
+
+    for (const arr of arrays) {
+        for (const [k, v] of Object.entries(arr)) {
+            if (is_int(Number(k))) {
+                result[index++] = v;
+            } else {
+                result[k] = v;
+            }
+        }
+    }
+
+    return result;
+}

package/src/helpers/array/array_merge_recursive.mjs

@@ -0,0 +1,153 @@
+import array from '../array.mjs';
+import empty from '../empty.mjs';
+import is_array from '../is_array.mjs';
+import is_int from '../is_int.mjs';
+import is_list from '../is_list.mjs';
+import is_null from '../is_null.mjs';
+
+/**
+ * Объединяет несколько массивов рекурсивно.
+ *
+ * ### Описание
+ *
+ * Функция `array_merge_recursive` используется для рекурсивного объединения нескольких массивов в один.
+ * Она поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+ *
+ * ### Параметры
+ *
+ * - `...arrays` (object): Массивы, которые необходимо объединить.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает новый массив, содержащий элементы всех переданных массивов.
+ * Если все переданные массивы являются обычными массивами, результатом будет обычный массив.
+ * Если хотя бы один из переданных массивов является ассоциативным массивом, результатом будет ассоциативный массив.
+ *
+ * ### Примеры использования
+ *
+ * 1. Объединение обычных массивов:
+ *
+ *    ```js
+ *    const array1 = [1, 2, 3];
+ *    const array2 = [4, 5, 6];
+ *    const result = array_merge_recursive(array1, array2);
+ *    console.log(result); // [1, 2, 3, 4, 5, 6]
+ *    ```
+ *
+ * 2. Объединение ассоциативных массивов:
+ *
+ *    ```js
+ *    const array1 = { a: 1, b: 2 };
+ *    const array2 = { b: 3, c: 4 };
+ *    const result = array_merge_recursive(array1, array2);
+ *    console.log(result); // { a: 1, b: [2, 3], c: 4 }
+ *    ```
+ *
+ * 3. Объединение обычных и ассоциативных массивов:
+ *
+ *    ```js
+ *    const array1 = [1, 2, 3];
+ *    const array2 = { a: 4, b: 5 };
+ *    const result = array_merge_recursive(array1, array2);
+ *    console.log(result); // { 0: 1, 1: 2, 2: 3, a: 4, b: 5 }
+ *    ```
+ *
+ * 4. Объединение вложенных массивов:
+ *
+ *    ```js
+ *    const array1 = { a: { b: 1 } };
+ *    const array2 = { a: { c: 2 } };
+ *    const result = array_merge_recursive(array1, array2);
+ *    console.log(result); // { a: { b: 1, c: 2 } }
+ *    ```
+ *
+ * 5. Объединение массивов с одинаковыми ключами:
+ *
+ *    ```js
+ *    const array1 = { a: { b: 1 } };
+ *    const array2 = { a: { b: 2 } };
+ *    const result = array_merge_recursive(array1, array2);
+ *    console.log(result); // { a: { b: [1, 2] } }
+ *    ```
+ *
+ * 6. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_merge_recursive('not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "arrays" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {...object} arrays Массивы, которые необходимо объединить.
+ * @returns {object} Возвращает новый массив, содержащий элементы всех переданных массивов.
+ * @throws {TypeError} Если хотя бы один из параметров не является массивом.
+ */
+export default function array_merge_recursive(...arrays) {
+    if (!arrays.every((arr) => is_array(arr))) {
+        throw new TypeError('Параметр "arrays" должен быть массивом.');
+    }
+
+    if (empty(arrays)) {
+        return [];
+    }
+
+    const result = arrays.every((arr) => is_list(arr)) ? [] : array({});
+
+    // Текущий индекс в массиве
+    let index = 0;
+
+    // Индекс первого массива с числовым ключом, записанный в результат.
+    let first_array_index = null;
+
+    // Перебираем переданные массивы.
+    for (const arr of arrays) {
+        for (const [k, v] of Object.entries(arr)) {
+            // Значение не является массивом, записываем его в результат и продолжаем итерацию.
+            //
+            // Если значение имеет числовой ключ, переиндексируем его.
+            if (!is_array(v)) {
+                if (is_int(Number(k))) {
+                    result[index++] = v;
+                } else if (k in result) {
+                    result[k] = [result[k], v];
+                } else {
+                    result[k] = v;
+                }
+
+                continue;
+            }
+
+            // Значение является массивом
+            //
+            // Массив имеет числовой ключ
+            if (is_int(Number(k))) {
+                // Если это первый массив с числовым ключом, сохраняем его индекс,
+                // иначе объединяем массив с первым массивом.
+                if (is_null(first_array_index)) {
+                    result[index] = v;
+                    first_array_index = index++;
+                } else {
+                    result[first_array_index] = array_merge_recursive(result[first_array_index], v);
+                }
+
+                continue;
+            }
+
+            // Массив имеет строковый ключ.
+            //
+            // Если массив с таким ключом уже был записан в результат, объединяем его с текущим массивом.
+            // Иначе записываем текущий массив в результат.
+            if (k in result && is_array(result[k])) {
+                result[k] = array_merge_recursive(result[k], v);
+
+                continue;
+            }
+
+            result[k] = v;
+        }
+    }
+
+    return result;
+}

package/src/helpers/array/array_pad.mjs

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