@rogolev/value 0.0.3 → 0.0.5

package/src/helpers/array/array_search.mjs

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

package/src/helpers/array/array_shift.mjs

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

package/src/helpers/array/array_slice.mjs

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

package/src/helpers/array/array_splice.mjs

@@ -0,0 +1,218 @@
+import array from '../array.mjs';
+import empty from '../empty.mjs';
+import is_array from '../is_array.mjs';
+import is_assoc from '../is_assoc.mjs';
+import is_int from '../is_int.mjs';
+import is_list from '../is_list.mjs';
+import is_null from '../is_null.mjs';
+import array_push from './array_push.mjs';
+
+/**
+ * Удаляет элементы из массива и, при необходимости, добавляет новые элементы на их место.
+ *
+ * ### Описание
+ *
+ * Функция `array_splice` используется для удаления элементов из массива и добавления новых элементов на их место.
+ * Она поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+ *
+ * ### Параметры
+ *
+ * - `arr` (object): Исходный массив.
+ * - `offset` (number): Смещение, с которого начинается удаление.
+ * - `length` (number|null): Количество удаляемых элементов. Если не указано, удаляются все элементы до конца массива.
+ * - `replacements` (object): Элементы для добавления на место удаленных.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает массив удаленных элементов.
+ *
+ * ### Примеры использования
+ *
+ * 1. Удаление элементов из обычного массива:
+ *
+ *    ```js
+ *    const array = [1, 2, 3, 4, 5];
+ *    const result = array_splice(array, 1, 2);
+ *    console.log(result); // [2, 3]
+ *    console.log(array); // [1, 4, 5]
+ *    ```
+ *
+ * 2. Удаление элементов из ассоциативного массива:
+ *
+ *    ```js
+ *    const array = { a: 1, b: 2, c: 3, d: 4, e: 5 };
+ *    const result = array_splice(array, 1, 2);
+ *    console.log(result); // { b: 2, c: 3 }
+ *    console.log(array); // { a: 1, d: 4, e: 5 }
+ *    ```
+ *
+ * 3. Добавление элементов в обычный массив:
+ *
+ *    ```js
+ *    const array = [1, 2, 3];
+ *    const result = array_splice(array, 1, 0, [4, 5]);
+ *    console.log(result); // []
+ *    console.log(array); // [1, 4, 5, 2, 3]
+ *    ```
+ *
+ * 4. Добавление элементов в ассоциативный массив:
+ *
+ *    ```js
+ *    const array = { a: 1, b: 2, c: 3 };
+ *    const result = array_splice(array, 1, 0, { d: 4, e: 5 });
+ *    console.log(result); // {}
+ *    console.log(array); // { a: 1, d: 4, e: 5, b: 2, c: 3 }
+ *    ```
+ *
+ * 5. Замена элементов в обычном массиве:
+ *
+ *    ```js
+ *    const array = [1, 2, 3];
+ *    const result = array_splice(array, 1, 2, [4, 5]);
+ *    console.log(result); // [2, 3]
+ *    console.log(array); // [1, 4, 5]
+ *    ```
+ *
+ * 6. Замена элементов в ассоциативном массиве:
+ *
+ *    ```js
+ *    const array = { a: 1, b: 2, c: 3 };
+ *    const result = array_splice(array, 1, 2, { d: 4, e: 5 });
+ *    console.log(result); // { b: 2, c: 3 }
+ *    console.log(array); // { a: 1, d: 4, e: 5 }
+ *    ```
+ *
+ * 7. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_splice('not an array', 1, 2);
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "arr" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @param {number} offset Смещение, с которого начинается удаление.
+ * @param {number|null} [length=null] Количество удаляемых элементов.
+ * @param {object} [replacements=[]] Элементы для добавления на место удаленных.
+ * @returns {object} Возвращает массив удаленных элементов.
+ * @throws {TypeError} Если параметры не являются массивом, целым числом или null.
+ */
+export default function array_splice(arr, offset, length = null, ...replacements) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    if (!is_int(offset)) {
+        throw new TypeError('Параметр "offset" должен быть целым числом.');
+    }
+
+    if (!is_int(length) && !is_null(length)) {
+        throw new TypeError('Параметр "length" должен быть целым числом.');
+    }
+
+    if (empty(replacements) && !is_null(length) && length === 0) {
+        return is_list(arr) ? [] : array({});
+    }
+
+    const count = Object.keys(arr).length;
+
+    if (offset < 0) {
+        offset = count + offset;
+    }
+
+    // if (is_list(arr)) {
+    //     if (is_null(length)) {
+    //         length = count;
+    //     } else if (length < 0) {
+    //         length = count + length - offset;
+    //     }
+
+    //     return arr.splice(offset, length, ...replacements);
+    // }
+
+    let end = count;
+
+    if (!is_null(length)) {
+        if (length > 0) {
+            end = offset + length;
+        } else if (length < 0) {
+            end = count + length;
+        } else {
+            end = offset;
+        }
+    }
+
+    // Удаленные пары ключ-значение исходного массива.
+    const result = {};
+
+    // Временный массив.
+    // Нужен для того, чтобы элементы исходного массива имели ожидаемые позиции.
+    const tmp = {};
+
+    // Текущая позиция в исходном массиве.
+    let index = 0;
+
+    //
+    // Исходный массив рассматривается как список пар ключ-значение,
+    // где ключами являются не индексы, а позиция пары в массиве.
+    //
+    // Например, список будет иметь вид:
+    //
+    //  0  1  2 - это не индексы, а позиция в массиве.
+    // [1, 2, 3]
+    //
+    // или
+    //
+    // -3 -2 -1 - позиция в массиве c обратной стороны.
+    // [1, 2, 3]
+    //
+    // Ассоциативный массив:
+    //
+    //      0            1           2       -  позиция в массиве.
+    // { foo: 'bar', baz: 'bax', ban: 'bam' }
+    //
+    for (const [k, v] of Object.entries(arr)) {
+        // Если текущая позиция совпадает с начальной позицией для удаления
+        // и если переданы элементы для вставки, добавляем их в конец временного массива.
+        if (index === offset && !empty(replacements)) {
+            for (const replacement of replacements) {
+                if (is_assoc(replacement)) {
+                    Object.assign(tmp, replacement);
+                } else if (is_list(replacement)) {
+                    array_push(tmp, ...replacement);
+                } else {
+                    array_push(tmp, replacement);
+                }
+            }
+        }
+
+        // Если текущая позиция входит в диапазон элементов для удаления,
+        // записывает пару ключ-значение в результирующий массив.
+        // Иначе записываем пару ключ-значение во временный массив.
+        if (index >= offset && index < end) {
+            result[k] = v;
+        } else {
+            is_int(Number(k)) ? array_push(tmp, v) : (tmp[k] = v);
+        }
+
+        index++;
+    }
+
+    // Очищаем исходный массив.
+    for (const k in arr) {
+        delete arr[k];
+    }
+
+    // Копируем все свойства из временного массива в исходный.
+    for (const [k, v] of Object.entries(tmp)) {
+        arr[k] = v;
+    }
+
+    if (is_list(arr)) {
+        return Object.values(result);
+    }
+
+    return result;
+}

package/src/helpers/array/array_sum.mjs

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

package/src/helpers/array/array_udiff.mjs

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