@rogolev/value 0.0.3 → 0.0.4

package/src/helpers/array/array_filter.mjs

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

package/src/helpers/array/array_flip.mjs

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

package/src/helpers/array/array_index_max.mjs

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

package/src/helpers/array/array_index_min.mjs

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

package/src/helpers/array/array_intersect.mjs

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

package/src/helpers/array/array_intersect_assoc.mjs

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

package/src/helpers/array/array_intersect_key.mjs

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

package/src/helpers/array/array_intersect_uassoc.mjs

@@ -0,0 +1,77 @@
+import array_uintersect_uassoc from './array_uintersect_uassoc.mjs';
+
+/**
+ * Вычисляет пересечение между массивами с использованием пользовательской функции сравнения ключей.
+ *
+ * ### Описание
+ *
+ * Функция `array_intersect_uassoc` используется для вычисления пересечения между массивами с использованием пользовательской функции сравнения ключей.
+ * Она возвращает массив, содержащий элементы из первого массива, которые присутствуют в других массивах.
+ *
+ * ### Параметры
+ *
+ * - `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_uassoc(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_uassoc(key_compare_func, original_array, array1);
+ *    console.log(result); // {}
+ *    ```
+ *
+ * 3. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_intersect_uassoc('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_uassoc(key_compare_func, original_array, array1);
+ *    console.log(result); // { a: 1 }
+ *    ```
+ *
+ * @param {function} key_compare_func Функция для сравнения ключей.
+ * @param {object} original_array Исходный массив.
+ * @param {...object} arrays Массивы для сравнения.
+ * @returns {object} Возвращает массив, содержащий элементы из первого массива, которые присутствуют в других массивах.
+ * @throws {TypeError} Если параметры не являются функциями или массивами.
+ */
+export default function array_intersect_uassoc(key_compare_func, original_array, ...arrays) {
+    return array_uintersect_uassoc(
+        (a, b) => JSON.stringify(a) === JSON.stringify(b),
+        key_compare_func,
+        original_array,
+        ...arrays,
+    );
+}