@rogolev/value 0.0.3 → 0.0.5

package/src/helpers/array/array_pop.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 array_key_last from './array_key_last.mjs';
+
+/**
+ * Удаляет и возвращает последний элемент массива.
+ *
+ * ### Описание
+ *
+ * Функция `array_pop` используется для удаления и возврата последнего элемента массива.
+ * Она поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+ *
+ * ### Параметры
+ *
+ * - `arr` (object): Исходный массив.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает последний элемент массива. Если массив пустой, возвращает `null`.
+ *
+ * ### Примеры использования
+ *
+ * 1. Удаление и возврат последнего элемента обычного массива:
+ *
+ *    ```js
+ *    const array = [1, 2, 3];
+ *    const result = array_pop(array);
+ *    console.log(result); // 3
+ *    console.log(array); // [1, 2]
+ *    ```
+ *
+ * 2. Удаление и возврат последнего элемента ассоциативного массива:
+ *
+ *    ```js
+ *    const array = { a: 1, b: 2, c: 3 };
+ *    const result = array_pop(array);
+ *    console.log(result); // 3
+ *    console.log(array); // { a: 1, b: 2 }
+ *    ```
+ *
+ * 3. Обработка пустого массива:
+ *
+ *    ```js
+ *    const array = [];
+ *    const result = array_pop(array);
+ *    console.log(result); // null
+ *    ```
+ *
+ * 4. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_pop('not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "arr" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @returns {any} Возвращает последний элемент массива. Если массив пустой, возвращает `null`.
+ * @throws {TypeError} Если параметр не является массивом.
+ */
+export default function array_pop(arr) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    if (empty(arr)) {
+        return null;
+    }
+
+    if (is_list(arr)) {
+        return arr.pop();
+    }
+
+    const last_key = array_key_last(arr);
+    const result = arr[last_key];
+    delete arr[last_key];
+
+    return result;
+}

package/src/helpers/array/array_product.mjs

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

package/src/helpers/array/array_push.mjs

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

package/src/helpers/array/array_rand.mjs

@@ -0,0 +1,129 @@
+import empty from '../empty.mjs';
+import is_array from '../is_array.mjs';
+import is_int from '../is_int.mjs';
+
+/**
+ * Возвращает один или несколько случайных ключей из массива.
+ *
+ * ### Описание
+ *
+ * Функция `array_rand` используется для получения одного или нескольких случайных ключей из массива.
+ * Она поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+ *
+ * ### Параметры
+ *
+ * - `arr` (object): Исходный массив.
+ * - `count` (number): Количество случайных ключей для возврата. По умолчанию `1`.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает один или несколько случайных ключей из массива. Если массив пустой, возвращает `null`.
+ *
+ * ### Примеры использования
+ *
+ * 1. Получение одного случайного ключа из обычного массива:
+ *
+ *    ```js
+ *    const array = [1, 2, 3, 4, 5];
+ *    const result = array_rand(array);
+ *    console.log(result); // Например, 2
+ *    ```
+ *
+ * 2. Получение одного случайного ключа из ассоциативного массива:
+ *
+ *    ```js
+ *    const array = { a: 1, b: 2, c: 3 };
+ *    const result = array_rand(array);
+ *    console.log(result); // Например, 'b'
+ *    ```
+ *
+ * 3. Получение нескольких случайных ключей из обычного массива:
+ *
+ *    ```js
+ *    const array = [1, 2, 3, 4, 5];
+ *    const result = array_rand(array, 3);
+ *    console.log(result); // Например, [0, 2, 4]
+ *    ```
+ *
+ * 4. Получение нескольких случайных ключей из ассоциативного массива:
+ *
+ *    ```js
+ *    const array = { a: 1, b: 2, c: 3, d: 4, e: 5 };
+ *    const result = array_rand(array, 3);
+ *    console.log(result); // Например, ['a', 'c', 'e']
+ *    ```
+ *
+ * 5. Обработка пустого массива:
+ *
+ *    ```js
+ *    const array = [];
+ *    const result = array_rand(array);
+ *    console.log(result); // null
+ *    ```
+ *
+ * 6. Обработка значений, не являющихся массивами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_rand('not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "arr" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * 7. Обработка значений параметра count, не являющихся целыми числами:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_rand([1, 2, 3], 'not a number');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "count" должен быть целым числом.
+ *    }
+ *    ```
+ *
+ * 8. Обработка значений параметра count, выходящих за пределы длины массива:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_rand([1, 2, 3], 5);
+ *    } catch (e) {
+ *        console.error(e.message); // Значение параметра "count" выходит за пределы длины массива.
+ *    }
+ *    ```
+ *
+ * @param {object} arr Исходный массив.
+ * @param {number} [count=1] Количество случайных ключей для возврата.
+ * @returns {any} Возвращает один или несколько случайных ключей из массива. Если массив пустой, возвращает `null`.
+ * @throws {TypeError} Если параметр не является массивом или если параметр count не является целым числом.
+ * @throws {Error} Если параметр count выходит за пределы длины массива.
+ */
+export default function array_rand(arr, count = 1) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    if (!is_int(count)) {
+        throw new TypeError('Параметр "count" должен быть целым числом.');
+    }
+
+    if (empty(arr)) {
+        return null;
+    }
+
+    const keys = Object.keys(arr);
+
+    if (count < 1 || count > keys.length) {
+        throw new Error('Значение параметра "count" выходит за пределы длины массива.');
+    }
+
+    const result = [];
+
+    while (count > 0) {
+        const rand_index = Math.floor(Math.random() * keys.length);
+        result.push(keys[rand_index]);
+        keys.splice(rand_index, 1);
+        count--;
+    }
+
+    return result.length === 1 ? result[0] : result;
+}

package/src/helpers/array/array_reduce.mjs

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

package/src/helpers/array/array_replace.mjs

@@ -0,0 +1,25 @@
+import array from '../array.mjs';
+import is_array from '../is_array.mjs';
+import is_list from '../is_list.mjs';
+
+export default function array_replace(arr, ...replacements) {
+    if (!is_array(arr)) {
+        throw new TypeError('Параметр "arr" должен быть массивом.');
+    }
+
+    if (!replacements.every((replacement) => is_array(replacement))) {
+        throw new TypeError('Параметр "replacements" должен быть массивом.');
+    }
+
+    const result = is_list(arr) ? Array.from(arr) : array(arr);
+
+    for (const replacement of replacements) {
+        for (const [k, v] of Object.entries(replacement)) {
+            if (k in result) {
+                result[k] = v;
+            }
+        }
+    }
+
+    return result;
+}

package/src/helpers/array/array_replace_recursive.mjs

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

package/src/helpers/array/array_reverse.mjs

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