@rogolev/value 0.0.3 → 0.0.4

package/src/helpers/string/natcompare.mjs

@@ -0,0 +1,107 @@
+import is_string from '../is_string.mjs';
+import is_digit_char from './is_digit_char.mjs';
+import is_whitespace_char from './is_whitespace_char.mjs';
+import natcompare_numeric from './natcompare_numeric.mjs';
+
+/**
+ * Сравнивает две строки в естественном порядке.
+ *
+ * ### Описание
+ *
+ * Функция `natcompare` используется для сравнения двух строк в естественном порядке.
+ * Она поддерживает строки с ведущими нулями и пробелами и игнорирует их при сравнении.
+ *
+ * ### Параметры
+ *
+ * - `a` (string): Первая строка для сравнения.
+ * - `b` (string): Вторая строка для сравнения.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает отрицательное значение, если `a` меньше `b`, ноль, если `a` равно `b`, и положительное значение, если `a` больше `b`.
+ *
+ * ### Примеры использования
+ *
+ * 1. Сравнение строк с числовыми значениями:
+ *
+ *    ```js
+ *    const result = natcompare('10', '2');
+ *    console.log(result); // 1
+ *    ```
+ *
+ * 2. Сравнение строк с ведущими нулями:
+ *
+ *    ```js
+ *    const result = natcompare('0010', '10');
+ *    console.log(result); // 0
+ *    ```
+ *
+ * @param {string} a Первая строка для сравнения.
+ * @param {string} b Вторая строка для сравнения.
+ * @returns {number} Возвращает отрицательное значение, если `a` меньше `b`, ноль, если `a` равно `b`, и положительное значение, если `a` больше `b`.
+ * @throws {TypeError} Если параметры не являются строками.
+ */
+export default function natcompare(a, b) {
+    if (!is_string(a)) {
+        throw new TypeError('Параметр "a" должен быть строкой.');
+    }
+
+    if (!is_string(b)) {
+        throw new TypeError('Параметр "b" должен быть строкой.');
+    }
+
+    a = a.trim();
+    b = b.trim();
+
+    let ia = 0;
+    let ib = 0;
+    let nza = 0;
+    let nzb = 0;
+
+    while (true) {
+        nza = 0;
+        nzb = 0;
+
+        let ca = a.charAt(ia);
+        let cb = b.charAt(ib);
+
+        while (is_whitespace_char(ca) || ca === '0') {
+            if (ca === '0') {
+                nza++;
+            } else {
+                nza = 0;
+            }
+            ca = a.charAt(++ia);
+        }
+
+        while (is_whitespace_char(cb) || cb === '0') {
+            if (cb === '0') {
+                nzb++;
+            } else {
+                nzb = 0;
+            }
+            cb = b.charAt(++ib);
+        }
+
+        if (is_digit_char(ca) && is_digit_char(cb)) {
+            const result = natcompare_numeric(a.slice(ia), b.slice(ib));
+
+            if (result !== 0) {
+                return result;
+            }
+        }
+
+        if (ca === '' && cb === '') {
+            return nza - nzb;
+        }
+
+        if (ca < cb) {
+            return -1;
+        } else if (ca > cb) {
+            return 1;
+        }
+
+        ia++;
+        ib++;
+    }
+}

package/src/helpers/string/natcompare_numeric.mjs

@@ -0,0 +1,131 @@
+import is_string from '../is_string.mjs';
+import is_digit_char from './is_digit_char.mjs';
+
+/**
+ * Сравнивает две строки, содержащие числовые значения, в естественном порядке.
+ *
+ * ### Описание
+ *
+ * Функция `natcompare_numeric` используется для сравнения двух строк, содержащих числовые значения, в естественном порядке.
+ * Она поддерживает строки с ведущими нулями и игнорирует их при сравнении.
+ *
+ * ### Параметры
+ *
+ * - `a` (string): Первая строка для сравнения.
+ * - `b` (string): Вторая строка для сравнения.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает отрицательное значение, если `a` меньше `b`, ноль, если `a` равно `b`, и положительное значение, если `a` больше `b`.
+ *
+ * ### Примеры использования
+ *
+ * 1. Сравнение строк с числовыми значениями:
+ *
+ *    ```js
+ *    const result = natcompare_numeric('10', '2');
+ *    console.log(result); // 1
+ *    ```
+ *
+ * 2. Сравнение строк с ведущими нулями:
+ *
+ *    ```js
+ *    const result = natcompare_numeric('0010', '10');
+ *    console.log(result); // 0
+ *    ```
+ *
+ * 3. Сравнение строк с пробелами:
+ *
+ *    ```js
+ *    const result = natcompare_numeric(' 10', '10');
+ *    console.log(result); // 0
+ *    ```
+ *
+ * 4. Сравнение строк с буквами и числами:
+ *
+ *    ```js
+ *    const result = natcompare_numeric('a10', 'a2');
+ *    console.log(result); // 1
+ *    ```
+ *
+ * 5. Сравнение строк с разными символами:
+ *
+ *    ```js
+ *    const result = natcompare_numeric('10-', '10+');
+ *    console.log(result); // 0
+ *    ```
+ *
+ * @param {string} a Первая строка для сравнения.
+ * @param {string} b Вторая строка для сравнения.
+ * @returns {number} Возвращает отрицательное значение, если `a` меньше `b`, ноль, если `a` равно `b`, и положительное значение, если `a` больше `b`.
+ * @throws {TypeError} Если параметры не являются строками.
+ */
+export default function natcompare_numeric(a, b) {
+    if (!is_string(a)) {
+        throw new TypeError('Параметр "a" должен быть строкой.');
+    }
+
+    if (!is_string(b)) {
+        throw new TypeError('Параметр "b" должен быть строкой.');
+    }
+
+    a = a.trim();
+    b = b.trim();
+
+    let result = 0;
+
+    let ia = 0;
+    let ib = 0;
+
+    // Пропускаем ведущие нули
+    while (ia < a.length && a[ia] === '0') {
+        ia++;
+    }
+    while (ib < b.length && b[ib] === '0') {
+        ib++;
+    }
+
+    // Сравниваем оставшиеся части строк
+    while (ia < a.length && ib < b.length) {
+        const ca = a[ia];
+        const cb = b[ib];
+
+        if (!is_digit_char(ca) && !is_digit_char(cb)) {
+            ia++;
+            ib++;
+            continue;
+        }
+
+        if (!is_digit_char(ca)) {
+            ia++;
+            continue;
+        }
+
+        if (!is_digit_char(cb)) {
+            ib++;
+            continue;
+        }
+
+        if (ca < cb) {
+            if (result === 0) {
+                result = -1;
+            }
+        } else if (ca > cb) {
+            if (result === 0) {
+                result = 1;
+            }
+        }
+
+        ia++;
+        ib++;
+    }
+
+    // Если одна строка длиннее другой, она считается больше
+    if (ia < a.length) {
+        return 1;
+    } else if (ib < b.length) {
+        return -1;
+    }
+
+    return result;
+}

package/tests/helpers/array/array_chunk.test.mjs

@@ -0,0 +1,49 @@
+import { expect, test, describe } from '@jest/globals';
+import { array_chunk } from '../../../index.mjs';
+
+describe('Функция array_chunk', () => {
+    test('Должна разбивать массив на части указанной длины', () => {
+        const array = [1, 2, 3, 4, 5];
+        const result = array_chunk(array, 2);
+        expect(result).toEqual([[1, 2], [3, 4], [5]]);
+    });
+
+    test('Должна возвращать пустой массив, если передан пустой массив', () => {
+        const array = [];
+        const result = array_chunk(array, 2);
+        expect(result).toEqual([]);
+    });
+
+    test('Должна разбивать ассоциативный массив на части указанной длины', () => {
+        const assoc = {
+            key1: 'value1',
+            key2: 'value2',
+            key3: 'value3',
+            key4: 'value4',
+            key5: 'value5',
+        };
+        const result = array_chunk(assoc, 2);
+        expect(result).toEqual([['value1', 'value2'], ['value3', 'value4'], ['value5']]);
+    });
+
+    test('Должна выбрасывать ошибку, если переданное значение не является массивом', () => {
+        expect(() => array_chunk('not an array', 2)).toThrow(TypeError);
+        expect(() => array_chunk('not an array', 2)).toThrow(
+            'Параметр "value" должен быть массивом.',
+        );
+    });
+
+    test('Должна выбрасывать ошибку, если длина не является целым числом', () => {
+        const array = [1, 2, 3];
+        expect(() => array_chunk(array, 'not an integer')).toThrow(TypeError);
+        expect(() => array_chunk(array, 'not an integer')).toThrow(
+            'Параметр "length" должен быть целым числом.',
+        );
+    });
+
+    test('Должна выбрасывать ошибку, если длина меньше 1', () => {
+        const array = [1, 2, 3];
+        expect(() => array_chunk(array, 0)).toThrow(Error);
+        expect(() => array_chunk(array, 0)).toThrow('Параметр "length" должен быть больше нуля.');
+    });
+});

package/tests/helpers/array/array_chunk_with_keys.test.mjs

@@ -0,0 +1,45 @@
+import { expect, test, describe } from '@jest/globals';
+import { array_chunk_with_keys } from '../../../index.mjs';
+
+describe('Функция array_chunk_with_keys', () => {
+    test('Должна разбивать ассоциативный массив на части указанной длины с сохранением ключей', () => {
+        const assoc = { a: 1, b: 2, c: 3, d: 4, e: 5 };
+        const result = array_chunk_with_keys(assoc, 2);
+        expect(result).toEqual([{ a: 1, b: 2 }, { c: 3, d: 4 }, { e: 5 }]);
+    });
+
+    test('Должна возвращать пустой массив, если передан пустой ассоциативный массив', () => {
+        const assoc = {};
+        const result = array_chunk_with_keys(assoc, 2);
+        expect(result).toEqual([]);
+    });
+
+    test('Должна разбивать обычный массив на части указанной длины с сохранением ключей', () => {
+        const array = [1, 2, 3, 4, 5];
+        const result = array_chunk_with_keys(array, 2);
+        expect(result).toEqual([{ 0: 1, 1: 2 }, { 2: 3, 3: 4 }, { 4: 5 }]);
+    });
+
+    test('Должна выбрасывать ошибку, если переданное значение не является массивом', () => {
+        expect(() => array_chunk_with_keys('not an array', 2)).toThrow(TypeError);
+        expect(() => array_chunk_with_keys('not an array', 2)).toThrow(
+            'Параметр "value" должен быть массивом.',
+        );
+    });
+
+    test('Должна выбрасывать ошибку, если длина не является целым числом', () => {
+        const assoc = { a: 1, b: 2, c: 3 };
+        expect(() => array_chunk_with_keys(assoc, 'not an integer')).toThrow(TypeError);
+        expect(() => array_chunk_with_keys(assoc, 'not an integer')).toThrow(
+            'Параметр "length" должен быть целым числом.',
+        );
+    });
+
+    test('Должна выбрасывать ошибку, если длина меньше 1', () => {
+        const assoc = { a: 1, b: 2, c: 3 };
+        expect(() => array_chunk_with_keys(assoc, 0)).toThrow(Error);
+        expect(() => array_chunk_with_keys(assoc, 0)).toThrow(
+            'Параметр "length" должен быть больше нуля.',
+        );
+    });
+});

package/tests/helpers/array/array_column.test.mjs

@@ -0,0 +1,87 @@
+import { expect, test, describe } from '@jest/globals';
+import { array_column } from '../../../index.mjs';
+
+describe('Функция array_column', () => {
+    test('Должна извлекать значения указанного столбца из массива объектов', () => {
+        const array = [
+            { id: 1, name: 'Alice' },
+            { id: 2, name: 'Bob' },
+            { id: 3, name: 'Charlie' },
+        ];
+        const result = array_column(array, 'name');
+        expect(result).toEqual(['Alice', 'Bob', 'Charlie']);
+    });
+
+    test('Должна возвращать пустой массив, если передан пустой массив', () => {
+        const array = [];
+        const result = array_column(array, 'name');
+        expect(result).toEqual([]);
+    });
+
+    test('Должна возвращать массив undefined, если ключ не найден в объектах', () => {
+        const array = [
+            { id: 1, name: 'Alice' },
+            { id: 2, name: 'Bob' },
+            { id: 3, name: 'Charlie' },
+        ];
+        const result = array_column(array, 'age');
+        expect(result).toEqual([undefined, undefined, undefined]);
+    });
+
+    test('Должна извлекать значения указанного столбца и использовать указанный ключ для индексации', () => {
+        const array = [
+            { id: 1, name: 'Alice' },
+            { id: 2, name: 'Bob' },
+            { id: 3, name: 'Charlie' },
+        ];
+        const result = array_column(array, 'name', 'id');
+        expect(result).toEqual({ 1: 'Alice', 2: 'Bob', 3: 'Charlie' });
+    });
+
+    test('Должна возвращать пустой объект, если передан пустой массив и указан индексный ключ', () => {
+        const array = [];
+        const result = array_column(array, 'name', 'id');
+        expect(result).toEqual({});
+    });
+
+    test('Должна возвращать объект с undefined значениями, если ключ не найден в объектах и указан индексный ключ', () => {
+        const array = [
+            { id: 1, name: 'Alice' },
+            { id: 2, name: 'Bob' },
+            { id: 3, name: 'Charlie' },
+        ];
+        const result = array_column(array, 'age', 'id');
+        expect(result).toEqual({ 1: undefined, 2: undefined, 3: undefined });
+    });
+
+    test('Должна выбрасывать ошибку, если переданное значение не является массивом', () => {
+        expect(() => array_column('not an array', 'name')).toThrow(TypeError);
+        expect(() => array_column('not an array', 'name')).toThrow(
+            'Параметр "value" должен быть списком.',
+        );
+    });
+
+    test('Должна выбрасывать ошибку, если ключ не является строкой или целым числом', () => {
+        const array = [
+            { id: 1, name: 'Alice' },
+            { id: 2, name: 'Bob' },
+            { id: 3, name: 'Charlie' },
+        ];
+        expect(() => array_column(array, {})).toThrow(TypeError);
+        expect(() => array_column(array, {})).toThrow(
+            'Параметр "column_key" должен быть строкой или целым числом.',
+        );
+    });
+
+    test('Должна выбрасывать ошибку, если индексный ключ не является строкой, целым числом или null', () => {
+        const array = [
+            { id: 1, name: 'Alice' },
+            { id: 2, name: 'Bob' },
+            { id: 3, name: 'Charlie' },
+        ];
+        expect(() => array_column(array, 'name', {})).toThrow(TypeError);
+        expect(() => array_column(array, 'name', {})).toThrow(
+            'Параметр "index_key" должен быть строкой или целым числом.',
+        );
+    });
+});

package/tests/helpers/array/array_combine.test.mjs

@@ -0,0 +1,41 @@
+import { expect, test, describe } from '@jest/globals';
+import { array_combine } from '../../../index.mjs';
+
+describe('Функция array_combine', () => {
+    test('Должна объединять два массива в ассоциативный массив', () => {
+        const keys = ['a', 'b', 'c'];
+        const values = [1, 2, 3];
+        const result = array_combine(keys, values);
+        expect(result).toEqual({ a: 1, b: 2, c: 3 });
+    });
+
+    test('Должна возвращать пустой объект, если переданы пустые массивы', () => {
+        const keys = [];
+        const values = [];
+        const result = array_combine(keys, values);
+        expect(result).toEqual({});
+    });
+
+    test('Должна выбрасывать ошибку, если переданное значение для ключей не является массивом', () => {
+        expect(() => array_combine('not an array', [1, 2, 3])).toThrow(TypeError);
+        expect(() => array_combine('not an array', [1, 2, 3])).toThrow(
+            'Параметр "keys" должен быть списком.',
+        );
+    });
+
+    test('Должна выбрасывать ошибку, если переданное значение для значений не является массивом', () => {
+        expect(() => array_combine(['a', 'b', 'c'], 'not an array')).toThrow(TypeError);
+        expect(() => array_combine(['a', 'b', 'c'], 'not an array')).toThrow(
+            'Параметр "values" должен быть списком.',
+        );
+    });
+
+    test('Должна выбрасывать ошибку, если количество ключей и значений не совпадает', () => {
+        const keys = ['a', 'b'];
+        const values = [1, 2, 3];
+        expect(() => array_combine(keys, values)).toThrow(Error);
+        expect(() => array_combine(keys, values)).toThrow(
+            'Количество элементов в списке ключей должно ровняться количеству элементов в списке значений.',
+        );
+    });
+});

package/tests/helpers/array/array_count_values.test.mjs

@@ -0,0 +1,40 @@
+import { expect, test, describe } from '@jest/globals';
+import { array_count_values } from '../../../index.mjs';
+
+describe('Функция array_count_values', () => {
+    test('Должна подсчитывать количество значений в массиве', () => {
+        const array = ['a', 'b', 'a', 'c', 'b', 'a'];
+        const result = array_count_values(array);
+        expect(result).toEqual({ a: 3, b: 2, c: 1 });
+    });
+
+    test('Должна возвращать пустой объект, если передан пустой массив', () => {
+        const array = [];
+        const result = array_count_values(array);
+        expect(result).toEqual({});
+    });
+
+    test('Должна корректно обрабатывать значения разных типов', () => {
+        const array = [1, '1', true, 'true', null, 'null', undefined, 'undefined'];
+        const result = array_count_values(array);
+        expect(result).toEqual({
+            1: 2,
+            true: 2,
+            null: 2,
+            undefined: 2,
+        });
+    });
+
+    test('Должна выбрасывать ошибку, если переданное значение не является массивом', () => {
+        expect(() => array_count_values('not an array')).toThrow(TypeError);
+        expect(() => array_count_values('not an array')).toThrow(
+            'Параметр "value" должен быть массивом.',
+        );
+    });
+
+    test('Должна корректно обрабатывать ассоциативные массивы', () => {
+        const assoc = { key1: 'a', key2: 'b', key3: 'a', key4: 'c' };
+        const result = array_count_values(assoc);
+        expect(result).toEqual({ a: 2, b: 1, c: 1 });
+    });
+});

package/tests/helpers/array/array_diff.test.mjs

@@ -0,0 +1,78 @@
+import { expect, test, describe } from '@jest/globals';
+import { array_diff } from '../../../index.mjs';
+
+describe('Функция array_diff', () => {
+    test('Должна возвращать элементы из первого массива, которые отсутствуют в других массивах', () => {
+        const original_array = [1, 2, 3];
+        const array1 = [1, 2];
+        const result = array_diff(original_array, array1);
+        expect(result).toEqual({ 2: 3 });
+    });
+
+    test('Должна возвращать пустой объект, если все элементы первого массива присутствуют в других массивах', () => {
+        const original_array = [1, 2];
+        const array1 = [1, 2];
+        const result = array_diff(original_array, array1);
+        expect(result).toEqual({});
+    });
+
+    test('Должна корректно обрабатывать пустые массивы', () => {
+        const original_array = [];
+        const array1 = [];
+        const result = array_diff(original_array, array1);
+        expect(result).toEqual({});
+    });
+
+    test('Должна выбрасывать ошибку, если переданное значение для original_array не является массивом', () => {
+        expect(() => array_diff('not an array')).toThrow(TypeError);
+        expect(() => array_diff('not an array')).toThrow(
+            'Параметр "original_array" должен быть массивом.',
+        );
+    });
+
+    test('Должна выбрасывать ошибку, если переданное значение для arrays не является массивом', () => {
+        expect(() => array_diff([], 'not an array')).toThrow(TypeError);
+        expect(() => array_diff([], 'not an array')).toThrow(
+            'Параметр "arrays" должен быть массивом.',
+        );
+    });
+
+    test('Должна корректно обрабатывать массивы с различными типами данных', () => {
+        const original_array = [1, '2', true];
+        const array1 = [1, 2, false];
+        const result = array_diff(original_array, array1);
+        expect(result).toEqual({ 1: '2', 2: true });
+    });
+
+    test('Должна корректно обрабатывать массивы с объектами', () => {
+        const original_array = [{ id: 1 }, { id: 2 }, { id: 3 }];
+        const array1 = [{ id: 1 }, { id: 2 }];
+        const result = array_diff(original_array, array1);
+        expect(result).toEqual({ 2: { id: 3 } });
+    });
+
+    test('Должна корректно обрабатывать ассоциативные массивы', () => {
+        const original_array = { a: 1, b: 2, c: 3 };
+        const array1 = { a: 1, b: 2 };
+        const result = array_diff(original_array, array1);
+        expect(result).toEqual({ c: 3 });
+    });
+
+    test('Должна корректно обрабатывать несколько массивов для сравнения', () => {
+        const original_array = [1, 2, 3, 4];
+        const array1 = [1, 2];
+        const array2 = [3];
+        const result = array_diff(original_array, array1, array2);
+        expect(result).toEqual({ 3: 4 });
+    });
+
+    test('Должна корректно обрабатывать массивы с вложенными структурами', () => {
+        const original_array = [
+            { id: 1, data: [1, 2] },
+            { id: 2, data: [3, 4] },
+        ];
+        const array1 = [{ id: 1, data: [1, 2] }];
+        const result = array_diff(original_array, array1);
+        expect(result).toEqual({ 1: { id: 2, data: [3, 4] } });
+    });
+});

package/tests/helpers/array/array_diff_assoc.test.mjs

@@ -0,0 +1,64 @@
+import { expect, test, describe } from '@jest/globals';
+import { array_diff_assoc } from '../../../index.mjs';
+
+describe('Функция array_diff_assoc', () => {
+    test('Должна возвращать элементы из первого массива, которые отсутствуют в других массивах', () => {
+        const original_array = { a: 1, b: 2, c: 3 };
+        const array1 = { a: 1, b: 2 };
+        const result = array_diff_assoc(original_array, array1);
+        expect(result).toEqual({ c: 3 });
+    });
+
+    test('Должна возвращать пустой объект, если все элементы первого массива присутствуют в других массивах', () => {
+        const original_array = { a: 1, b: 2 };
+        const array1 = { a: 1, b: 2 };
+        const result = array_diff_assoc(original_array, array1);
+        expect(result).toEqual({});
+    });
+
+    test('Должна корректно обрабатывать пустые массивы', () => {
+        const original_array = {};
+        const array1 = {};
+        const result = array_diff_assoc(original_array, array1);
+        expect(result).toEqual({});
+    });
+
+    test('Должна выбрасывать ошибку, если переданное значение для original_array не является массивом', () => {
+        expect(() => array_diff_assoc('not an array')).toThrow(TypeError);
+        expect(() => array_diff_assoc('not an array')).toThrow(
+            'Параметр "original_array" должен быть массивом.',
+        );
+    });
+
+    test('Должна выбрасывать ошибку, если переданное значение для arrays не является массивом', () => {
+        expect(() => array_diff_assoc([], 'not an array')).toThrow(TypeError);
+        expect(() => array_diff_assoc([], 'not an array')).toThrow(
+            'Параметр "arrays" должен быть массивом.',
+        );
+    });
+
+    test('Должна корректно обрабатывать массивы с различными типами данных', () => {
+        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);
+        expect(result).toEqual({ b: '2', c: true });
+    });
+
+    test('Должна корректно обрабатывать несколько массивов для сравнения', () => {
+        const original_array = { a: 1, b: 2, c: 3, d: 4 };
+        const array1 = { a: 1, b: 2 };
+        const array2 = { c: 3 };
+        const result = array_diff_assoc(original_array, array1, array2);
+        expect(result).toEqual({ d: 4 });
+    });
+
+    test('Должна корректно обрабатывать массивы с вложенными структурами', () => {
+        const original_array = {
+            a: { id: 1, data: [1, 2] },
+            b: { id: 2, data: [3, 4] },
+        };
+        const array1 = { a: { id: 1, data: [1, 2] } };
+        const result = array_diff_assoc(original_array, array1);
+        expect(result).toEqual({ b: { id: 2, data: [3, 4] } });
+    });
+});