@rogolev/value 0.0.3 → 0.0.5

package/src/constants.mjs

@@ -1,14 +1,83 @@
-export const TYPE_NULL = 'null';
-export const TYPE_NAN = 'NaN';
-export const TYPE_UNDEFINED = 'undefined';
-export const TYPE_INFINITY = 'infinity';
-export const TYPE_BOOLEAN = 'boolean';
-export const TYPE_INTEGER = 'integer';
-export const TYPE_BIGINT = 'bigint';
-export const TYPE_FLOAT = 'float';
-export const TYPE_STRING = 'string';
-export const TYPE_SYMBOL = 'symbol';
-export const TYPE_CLASS = 'class';
-export const TYPE_FUNCTION = 'function';
-export const TYPE_ARRAY = 'array';
-export const TYPE_OBJECT = 'object';
+/**
+ * Константа, представляющая значение null.
+ * @type {string}
+ */
+export const TYPE_NULL = 'null';
+
+/**
+ * Константа, представляющая значение NaN (Not-a-Number).
+ * @type {string}
+ */
+export const TYPE_NAN = 'NaN';
+
+/**
+ * Константа, представляющая значение undefined.
+ * @type {string}
+ */
+export const TYPE_UNDEFINED = 'undefined';
+
+/**
+ * Константа, представляющая значение Infinity.
+ * @type {string}
+ */
+export const TYPE_INFINITY = 'infinity';
+
+/**
+ * Константа, представляющая тип boolean.
+ * @type {string}
+ */
+export const TYPE_BOOLEAN = 'boolean';
+
+/**
+ * Константа, представляющая тип integer (целое число).
+ * @type {string}
+ */
+export const TYPE_INTEGER = 'integer';
+
+/**
+ * Константа, представляющая тип bigint (большое целое число).
+ * @type {string}
+ */
+export const TYPE_BIGINT = 'bigint';
+
+/**
+ * Константа, представляющая тип float (число с плавающей запятой).
+ * @type {string}
+ */
+export const TYPE_FLOAT = 'float';
+
+/**
+ * Константа, представляющая тип string (строка).
+ * @type {string}
+ */
+export const TYPE_STRING = 'string';
+
+/**
+ * Константа, представляющая тип symbol (символ).
+ * @type {string}
+ */
+export const TYPE_SYMBOL = 'symbol';
+
+/**
+ * Константа, представляющая тип class (класс).
+ * @type {string}
+ */
+export const TYPE_CLASS = 'class';
+
+/**
+ * Константа, представляющая тип function (функция).
+ * @type {string}
+ */
+export const TYPE_FUNCTION = 'function';
+
+/**
+ * Константа, представляющая тип array (массив).
+ * @type {string}
+ */
+export const TYPE_ARRAY = 'array';
+
+/**
+ * Константа, представляющая тип object (объект).
+ * @type {string}
+ */
+export const TYPE_OBJECT = 'object';

package/src/helpers/array/array_chunk.mjs

@@ -0,0 +1,102 @@
+import is_array from '../is_array.mjs';
+import is_int from '../is_int.mjs';
+
+/**
+ * Разбивает массив на части указанной длины.
+ *
+ * ### Описание
+ *
+ * Функция `array_chunk` используется для разбивки массива на части указанной длины.
+ * Если переданное значение не является массивом, функция выбрасывает ошибку типа `TypeError`.
+ * Если длина не является целым числом или меньше 1, функция выбрасывает соответствующую ошибку.
+ *
+ * ### Параметры
+ *
+ * - `value` (array): Массив, который необходимо разбить на части.
+ * - `length` (number): Длина каждой части.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает новый массив, содержащий части исходного массива.
+ *
+ * ### Примеры использования
+ *
+ * 1. Разбивка массива на части указанной длины:
+ *
+ *    ```js
+ *    const array = [1, 2, 3, 4, 5];
+ *    const result = array_chunk(array, 2);
+ *    console.log(result); // [[1, 2], [3, 4], [5]]
+ *    ```
+ *
+ * 2. Обработка пустого массива:
+ *
+ *    ```js
+ *    const array = [];
+ *    const result = array_chunk(array, 2);
+ *    console.log(result); // []
+ *    ```
+ *
+ * 3. Обработка ассоциативного массива:
+ *
+ *    ```js
+ *    const assoc = { key1: 'value1', key2: 'value2', key3: 'value3', key4: 'value4' };
+ *    const result = array_chunk(assoc, 2);
+ *    console.log(result); // [['value1', 'value2'], ['value3', 'value4']]
+ *    ```
+ *
+ * 4. Обработка значения, не являющегося массивом:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_chunk('not an array', 2);
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "value" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * 5. Обработка некорректной длины:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_chunk([1, 2, 3], 'not an integer');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "length" должен быть целым числом.
+ *    }
+ *
+ *    try {
+ *        const result = array_chunk([1, 2, 3], 0);
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "length" должен быть больше нуля.
+ *    }
+ *    ```
+ *
+ * @param {array} value Массив, который необходимо разбить на части.
+ * @param {number} length Длина каждой части.
+ * @returns {array} Возвращает новый массив, содержащий части исходного массива.
+ * @throws {TypeError} Если переданное значение не является массивом.
+ * @throws {TypeError} Если длина не является целым числом.
+ * @throws {Error} Если длина меньше 1.
+ */
+export default function array_chunk(value, length) {
+    if (!is_array(value)) {
+        throw new TypeError('Параметр "value" должен быть массивом.');
+    }
+
+    if (!is_int(length)) {
+        throw new TypeError('Параметр "length" должен быть целым числом.');
+    }
+
+    if (length < 1) {
+        throw new Error('Параметр "length" должен быть больше нуля.');
+    }
+
+    const result = [];
+    const values = Object.values(value);
+
+    while (values.length) {
+        result.push(values.splice(0, length));
+    }
+
+    return result;
+}

package/src/helpers/array/array_chunk_with_keys.mjs

@@ -0,0 +1,102 @@
+import is_array from '../is_array.mjs';
+import is_int from '../is_int.mjs';
+
+/**
+ * Разбивает массив на части указанной длины с сохранением ключей.
+ *
+ * ### Описание
+ *
+ * Функция `array_chunk_with_keys` используется для разбивки массива на части указанной длины с сохранением ключей.
+ * Если переданное значение не является массивом, функция выбрасывает ошибку типа `TypeError`.
+ * Если длина не является целым числом или меньше 1, функция выбрасывает соответствующую ошибку.
+ *
+ * ### Параметры
+ *
+ * - `value` (array): Массив, который необходимо разбить на части.
+ * - `length` (number): Длина каждой части.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает новый массив, содержащий части исходного массива с сохранением ключей.
+ *
+ * ### Примеры использования
+ *
+ * 1. Разбивка ассоциативного массива на части указанной длины с сохранением ключей:
+ *
+ *    ```js
+ *    const assoc = { a: 1, b: 2, c: 3, d: 4, e: 5 };
+ *    const result = array_chunk_with_keys(assoc, 2);
+ *    console.log(result); // [{ a: 1, b: 2 }, { c: 3, d: 4 }, { e: 5 }]
+ *    ```
+ *
+ * 2. Обработка пустого ассоциативного массива:
+ *
+ *    ```js
+ *    const assoc = {};
+ *    const result = array_chunk_with_keys(assoc, 2);
+ *    console.log(result); // []
+ *    ```
+ *
+ * 3. Разбивка обычного массива на части указанной длины с сохранением ключей:
+ *
+ *    ```js
+ *    const array = [1, 2, 3, 4, 5];
+ *    const result = array_chunk_with_keys(array, 2);
+ *    console.log(result); // [{ 0: 1, 1: 2 }, { 2: 3, 3: 4 }, { 4: 5 }]
+ *    ```
+ *
+ * 4. Обработка значения, не являющегося массивом:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_chunk_with_keys('not an array', 2);
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "value" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * 5. Обработка некорректной длины:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_chunk_with_keys([1, 2, 3], 'not an integer');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "length" должен быть целым числом.
+ *    }
+ *
+ *    try {
+ *        const result = array_chunk_with_keys([1, 2, 3], 0);
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "length" должен быть больше нуля.
+ *    }
+ *    ```
+ *
+ * @param {array} value Массив, который необходимо разбить на части.
+ * @param {number} length Длина каждой части.
+ * @returns {array} Возвращает новый массив, содержащий части исходного массива с сохранением ключей.
+ * @throws {TypeError} Если переданное значение не является массивом.
+ * @throws {TypeError} Если длина не является целым числом.
+ * @throws {Error} Если длина меньше 1.
+ */
+export default function array_chunk_with_keys(value, length) {
+    if (!is_array(value)) {
+        throw new TypeError('Параметр "value" должен быть массивом.');
+    }
+
+    if (!is_int(length)) {
+        throw new TypeError('Параметр "length" должен быть целым числом.');
+    }
+
+    if (length < 1) {
+        throw new Error('Параметр "length" должен быть больше нуля.');
+    }
+
+    const result = [];
+    const entries = Object.entries(value);
+
+    while (entries.length) {
+        result.push(Object.fromEntries(entries.splice(0, length)));
+    }
+
+    return result;
+}

package/src/helpers/array/array_column.mjs

@@ -0,0 +1,131 @@
+import array from '../array.mjs';
+import is_int from '../is_int.mjs';
+import is_list from '../is_list.mjs';
+import is_null from '../is_null.mjs';
+import is_string from '../is_string.mjs';
+
+/**
+ * Извлекает значения указанного столбца из массива объектов.
+ *
+ * ### Описание
+ *
+ * Функция `array_column` используется для извлечения значений указанного столбца из массива объектов.
+ * Если переданное значение не является списком, функция выбрасывает ошибку типа `TypeError`.
+ * Если ключ столбца или индексный ключ не являются строкой или целым числом, функция выбрасывает соответствующую ошибку.
+ *
+ * ### Параметры
+ *
+ * - `value` (array): Массив объектов, из которого необходимо извлечь значения.
+ * - `column_key` (string | number): Ключ столбца, значения которого необходимо извлечь.
+ * - `index_key` (string | number | null): Ключ, который будет использоваться для индексации возвращаемого массива (по умолчанию `null`).
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает массив значений указанного столбца. Если указан индексный ключ, возвращает объект с индексированными значениями.
+ *
+ * ### Примеры использования
+ *
+ * 1. Извлечение значений указанного столбца из массива объектов:
+ *
+ *    ```js
+ *    const array = [
+ *        { id: 1, name: 'Alice' },
+ *        { id: 2, name: 'Bob' },
+ *        { id: 3, name: 'Charlie' },
+ *    ];
+ *    const result = array_column(array, 'name');
+ *    console.log(result); // ['Alice', 'Bob', 'Charlie']
+ *    ```
+ *
+ * 2. Извлечение значений указанного столбца с использованием индексного ключа:
+ *
+ *    ```js
+ *    const array = [
+ *        { id: 1, name: 'Alice' },
+ *        { id: 2, name: 'Bob' },
+ *        { id: 3, name: 'Charlie' },
+ *    ];
+ *    const result = array_column(array, 'name', 'id');
+ *    console.log(result); // { 1: 'Alice', 2: 'Bob', 3: 'Charlie' }
+ *    ```
+ *
+ * 3. Обработка пустого массива:
+ *
+ *    ```js
+ *    const array = [];
+ *    const result = array_column(array, 'name');
+ *    console.log(result); // []
+ *    ```
+ *
+ * 4. Обработка значения, не являющегося массивом:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_column('not an array', 'name');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "value" должен быть списком.
+ *    }
+ *    ```
+ *
+ * 5. Обработка некорректного ключа столбца:
+ *
+ *    ```js
+ *    const array = [
+ *        { id: 1, name: 'Alice' },
+ *        { id: 2, name: 'Bob' },
+ *        { id: 3, name: 'Charlie' },
+ *    ];
+ *    try {
+ *        const result = array_column(array, {});
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "column_key" должен быть строкой или целым числом.
+ *    }
+ *    ```
+ *
+ * 6. Обработка некорректного индексного ключа:
+ *
+ *    ```js
+ *    const array = [
+ *        { id: 1, name: 'Alice' },
+ *        { id: 2, name: 'Bob' },
+ *        { id: 3, name: 'Charlie' },
+ *    ];
+ *    try {
+ *        const result = array_column(array, 'name', {});
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "index_key" должен быть строкой или целым числом.
+ *    }
+ *    ```
+ *
+ * @param {array} value Массив объектов, из которого необходимо извлечь значения.
+ * @param {string | number} column_key Ключ столбца, значения которого необходимо извлечь.
+ * @param {string | number | null} [index_key=null] Ключ, который будет использоваться для индексации возвращаемого массива.
+ * @returns {array | object} Возвращает массив значений указанного столбца. Если указан индексный ключ, возвращает объект с индексированными значениями.
+ * @throws {TypeError} Если переданное значение не является списком.
+ * @throws {TypeError} Если ключ столбца или индексный ключ не являются строкой или целым числом.
+ */
+export default function array_column(value, column_key, index_key = null) {
+    if (!is_list(value)) {
+        throw new TypeError('Параметр "value" должен быть списком.');
+    }
+
+    if (!is_string(column_key) && !is_int(column_key)) {
+        throw new TypeError('Параметр "column_key" должен быть строкой или целым числом.');
+    }
+
+    if (!is_null(index_key) && !is_string(index_key) && !is_int(index_key)) {
+        throw new TypeError('Параметр "index_key" должен быть строкой или целым числом.');
+    }
+
+    if (is_null(index_key)) {
+        return Object.values(value).map((model) => model[column_key]);
+    }
+
+    const result = array({});
+
+    for (const model of value) {
+        result[model[index_key]] = model[column_key];
+    }
+
+    return result;
+}

package/src/helpers/array/array_combine.mjs

@@ -0,0 +1,26 @@
+import array from '../array.mjs';
+import is_list from '../is_list.mjs';
+
+export default function array_combine(keys, values) {
+    if (!is_list(keys)) {
+        throw new TypeError('Параметр "keys" должен быть списком.');
+    }
+
+    if (!is_list(values)) {
+        throw new TypeError('Параметр "values" должен быть списком.');
+    }
+
+    if (keys.length !== values.length) {
+        throw new Error(
+            'Количество элементов в списке ключей должно ровняться количеству элементов в списке значений.',
+        );
+    }
+
+    const result = array({});
+
+    for (let i = 0; i < keys.length; i++) {
+        result[keys[i]] = values[i];
+    }
+
+    return result;
+}

package/src/helpers/array/array_count_values.mjs

@@ -0,0 +1,82 @@
+import array from '../array.mjs';
+import is_array from '../is_array.mjs';
+
+/**
+ * Подсчитывает количество значений в массиве.
+ *
+ * ### Описание
+ *
+ * Функция `array_count_values` используется для подсчета количества значений в массиве.
+ * Если переданное значение не является массивом, функция выбрасывает ошибку типа `TypeError`.
+ *
+ * ### Параметры
+ *
+ * - `value` (array): Массив значений, которые необходимо подсчитать.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает объект, где ключи представляют уникальные значения из массива, а значения представляют количество их вхождений.
+ *
+ * ### Примеры использования
+ *
+ * 1. Подсчет количества значений в массиве:
+ *
+ *    ```js
+ *    const array = ['a', 'b', 'a', 'c', 'b', 'a'];
+ *    const result = array_count_values(array);
+ *    console.log(result); // { a: 3, b: 2, c: 1 }
+ *    ```
+ *
+ * 2. Обработка пустого массива:
+ *
+ *    ```js
+ *    const array = [];
+ *    const result = array_count_values(array);
+ *    console.log(result); // {}
+ *    ```
+ *
+ * 3. Обработка значений разных типов:
+ *
+ *    ```js
+ *    const array = [1, '1', true, 'true', null, 'null', undefined, 'undefined'];
+ *    const result = array_count_values(array);
+ *    console.log(result); // { 1: 2, true: 2, null: 2, undefined: 2 }
+ *    ```
+ *
+ * 4. Обработка значения, не являющегося массивом:
+ *
+ *    ```js
+ *    try {
+ *        const result = array_count_values('not an array');
+ *    } catch (e) {
+ *        console.error(e.message); // Параметр "value" должен быть массивом.
+ *    }
+ *    ```
+ *
+ * 5. Обработка ассоциативных массивов:
+ *
+ *    ```js
+ *    const assoc = { key1: 'a', key2: 'b', key3: 'a', key4: 'c' };
+ *    const result = array_count_values(assoc);
+ *    console.log(result); // { a: 2, b: 1, c: 1 }
+ *    ```
+ *
+ * @param {object} value Массив значений, которые необходимо подсчитать.
+ * @returns {object} Возвращает объект, где ключи представляют уникальные значения из массива, а значения представляют количество их вхождений.
+ * @throws {TypeError} Если переданное значение не является массивом.
+ */
+export default function array_count_values(value) {
+    if (!is_array(value)) {
+        throw new TypeError('Параметр "value" должен быть массивом.');
+    }
+
+    const result = array({});
+
+    for (const k in value) {
+        const v = String(value[k]);
+
+        v in result ? result[v]++ : (result[v] = 1);
+    }
+
+    return result;
+}

package/src/helpers/array/array_diff.mjs

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

package/src/helpers/array/array_diff_assoc.mjs

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