@rogolev/value 0.0.3 → 0.0.4

package/src/helpers/array/array_intersect_ukey.mjs

@@ -0,0 +1,72 @@
+import array_uintersect_uassoc from './array_uintersect_uassoc.mjs';
+
+/**
+ * Вычисляет пересечение между массивами с использованием пользовательской функции сравнения для ключей.
+ *
+ * ### Описание
+ *
+ * Функция `array_intersect_ukey` используется для вычисления пересечения между массивами с использованием пользовательской функции сравнения для ключей.
+ * Она возвращает массив, содержащий элементы из первого массива, которые присутствуют в других массивах.
+ *
+ * ### Параметры
+ *
+ * - `key_compare_func` (function): Функция для сравнения ключей.
+ * - `original_array` (array): Исходный массив.
+ * - `...arrays` (array): Массивы для сравнения.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает массив, содержащий элементы из первого массива, которые присутствуют в других массивах.
+ *
+ * ### Примеры использования
+ *
+ * 1. Сравнение массивов с использованием пользовательской функции сравнения ключей:
+ *
+ *    ```js
+ *    const key_compare_func = (a, b) => a === b;
+ *    const original_array = { a: 1, b: 2, c: 3 };
+ *    const array1 = { a: 1, b: 2 };
+ *    const array2 = { b: 2, c: 3 };
+ *    const result = array_intersect_ukey(key_compare_func, original_array, array1, array2);
+ *    console.log(result); // { a: 1, b: 2, c: 3 }
+ *    ```
+ *
+ * 2. Обработка пустых массивов:
+ *
+ *    ```js
+ *    const key_compare_func = (a, b) => a === b;
+ *    const original_array = {};
+ *    const array1 = {};
+ *    const result = array_intersect_ukey(key_compare_func, original_array, array1);
+ *    console.log(result); // {}
+ *    ```
+ *
+ * 3. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_intersect_ukey('not a function', 'not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "key_compare_func" должен быть функцией.
+ *    }
+ *    ```
+ *
+ * 4. Сравнение массивов с различными типами данных:
+ *
+ *    ```js
+ *    const key_compare_func = (a, b) => a === b;
+ *    const original_array = { a: 1, b: '2', c: true };
+ *    const array1 = { a: 1, b: 2, d: false };
+ *    const result = array_intersect_ukey(key_compare_func, original_array, array1);
+ *    console.log(result); // { a: 1, b: '2' }
+ *    ```
+ *
+ * @param {function} key_compare_func Функция для сравнения ключей.
+ * @param {object} original_array Исходный массив.
+ * @param {...object} arrays Массивы для сравнения.
+ * @returns {object} Возвращает массив, содержащий элементы из первого массива, которые присутствуют в других массивах.
+ * @throws {TypeError} Если параметры не являются функциями или массивами.
+ */
+export default function array_intersect_ukey(key_compare_func, original_array, ...arrays) {
+    return array_uintersect_uassoc(() => true, key_compare_func, original_array, ...arrays);
+}

package/src/helpers/array/array_key_exists.mjs

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

package/src/helpers/array/array_key_first.mjs

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

package/src/helpers/array/array_key_last.mjs

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

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;
+}