@rogolev/value 0.0.3 → 0.0.5

package/docs/helpers/array/array_key_exists.md

@@ -0,0 +1,73 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / array_key_exists
+
+[Исходный код](../../../src/helpers/array/array_key_exists.mjs)
+
+# array_key_exists
+
+`array_key_exists` — Проверяет, существует ли указанный ключ в массиве.
+
+## Сигнатура функции
+
+```ts
+function array_key_exists(value: object, key: number | string): boolean;
+```
+
+## Описание
+
+Функция `array_key_exists` используется для проверки существования указанного ключа в массиве. Она
+возвращает `true`, если ключ существует в массиве, и `false` в противном случае.
+
+## Параметры
+
+- `value` (object): Исходный массив.
+- `key` (number | string): Ключ, который необходимо проверить.
+
+## Возвращаемое значение
+
+Возвращает `true`, если ключ существует в массиве, и `false` в противном случае.
+
+## Примеры использования
+
+1. Проверка существования ключа в обычном массиве:
+
+    ```js
+    const array = [1, 2, 3];
+    const result = array_key_exists(array, 1);
+    console.log(result); // true
+    ```
+
+2. Проверка существования ключа в ассоциативном массиве:
+
+    ```js
+    const array = { a: 1, b: 2, c: 3 };
+    const result = array_key_exists(array, 'b');
+    console.log(result); // true
+    ```
+
+3. Проверка отсутствия ключа в массиве:
+
+    ```js
+    const array = [1, 2, 3];
+    const result = array_key_exists(array, 5);
+    console.log(result); // false
+    ```
+
+4. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = array_key_exists('not an array', 1);
+    } catch (e) {
+        console.error(e.message); // Параметр "value" должен быть массивом.
+    }
+    ```
+
+5. Обработка значений ключа, не являющихся целыми числами или строками:
+
+    ```js
+    try {
+        const result = array_key_exists([1, 2, 3], {});
+    } catch (e) {
+        console.error(e.message); // Параметр "key" должен быть целым числом или строкой.
+    }
+    ```

package/docs/helpers/array/array_key_first.md

@@ -0,0 +1,62 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / array_key_first
+
+[Исходный код](../../../src/helpers/array/array_key_first.mjs)
+
+# array_key_first
+
+`array_key_first` — Возвращает первый ключ массива.
+
+## Сигнатура функции
+
+```ts
+function array_key_first(value: object): number | string | null;
+```
+
+## Описание
+
+Функция `array_key_first` используется для получения первого ключа массива. Она возвращает первый
+ключ для обычных массивов и ассоциативных массивов.
+
+## Параметры
+
+- `value` (object): Исходный массив.
+
+## Возвращаемое значение
+
+Возвращает первый ключ массива. Если массив пустой, возвращает `null`.
+
+## Примеры использования
+
+1. Получение первого ключа обычного массива:
+
+    ```js
+    const array = [1, 2, 3];
+    const result = array_key_first(array);
+    console.log(result); // 0
+    ```
+
+2. Получение первого ключа ассоциативного массива:
+
+    ```js
+    const array = { a: 1, b: 2, c: 3 };
+    const result = array_key_first(array);
+    console.log(result); // 'a'
+    ```
+
+3. Обработка пустого массива:
+
+    ```js
+    const array = [];
+    const result = array_key_first(array);
+    console.log(result); // null
+    ```
+
+4. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = array_key_first('not an array');
+    } catch (e) {
+        console.error(e.message); // Параметр "value" должен быть массивом.
+    }
+    ```

package/docs/helpers/array/array_key_last.md

@@ -0,0 +1,62 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / array_key_last
+
+[Исходный код](../../../src/helpers/array/array_key_last.mjs)
+
+# array_key_last
+
+`array_key_last` — Возвращает последний ключ массива.
+
+## Сигнатура функции
+
+```ts
+function array_key_last(value: object): number | string | null;
+```
+
+## Описание
+
+Функция `array_key_last` используется для получения последнего ключа массива. Она возвращает
+последний ключ для обычных массивов и ассоциативных массивов.
+
+## Параметры
+
+- `value` (object): Исходный массив.
+
+## Возвращаемое значение
+
+Возвращает последний ключ массива. Если массив пустой, возвращает `null`.
+
+## Примеры использования
+
+1. Получение последнего ключа обычного массива:
+
+    ```js
+    const array = [1, 2, 3];
+    const result = array_key_last(array);
+    console.log(result); // 2
+    ```
+
+2. Получение последнего ключа ассоциативного массива:
+
+    ```js
+    const array = { a: 1, b: 2, c: 3 };
+    const result = array_key_last(array);
+    console.log(result); // 'c'
+    ```
+
+3. Обработка пустого массива:
+
+    ```js
+    const array = [];
+    const result = array_key_last(array);
+    console.log(result); // null
+    ```
+
+4. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = array_key_last('not an array');
+    } catch (e) {
+        console.error(e.message); // Параметр "value" должен быть массивом.
+    }
+    ```

package/docs/helpers/array/array_key_to_lower_case.md

@@ -0,0 +1,57 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / array_key_to_lower_case
+
+[Исходный код](../../../src/helpers/array/array_key_to_lower_case.mjs)
+
+# array_key_to_lower_case
+
+`array_key_to_lower_case` — Преобразует ключи ассоциативного массива в нижний регистр.
+
+## Сигнатура функции
+
+```ts
+function array_key_to_lower_case(value: object): object;
+```
+
+## Описание
+
+Функция `array_key_to_lower_case` используется для преобразования всех ключей ассоциативного массива
+в нижний регистр. Если переданное значение не является массивом, функция выбрасывает ошибку типа
+`TypeError`. Если переданное значение является списком (обычным массивом), оно возвращается без
+изменений.
+
+## Параметры
+
+- `value` (object): Ассоциативный массив, ключи которого необходимо преобразовать в нижний регистр.
+
+## Возвращаемое значение
+
+Возвращает новый ассоциативный массив с ключами в нижнем регистре. Если переданное значение является
+списком, оно возвращается без изменений.
+
+## Примеры использования
+
+1. Преобразование ключей ассоциативного массива в нижний регистр:
+
+    ```js
+    const assoc = { Key1: 'value1', Key2: 'value2' };
+    const result = array_key_to_lower_case(assoc);
+    console.log(result); // { key1: 'value1', key2: 'value2' }
+    ```
+
+2. Обработка списка (обычного массива):
+
+    ```js
+    const list = [1, 2, 3];
+    const result = array_key_to_lower_case(list);
+    console.log(result); // [1, 2, 3]
+    ```
+
+3. Обработка значения, не являющегося массивом:
+
+    ```js
+    try {
+        const result = array_key_to_lower_case('not an array');
+    } catch (e) {
+        console.error(e.message); // Параметр "array" должен быть массивом.
+    }
+    ```

package/docs/helpers/array/array_key_to_upper_case.md

@@ -0,0 +1,57 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / array_key_to_upper_case
+
+[Исходный код](../../../src/helpers/array/array_key_to_upper_case.mjs)
+
+# array_key_to_upper_case
+
+`array_key_to_upper_case` — Преобразует ключи ассоциативного массива в верхний регистр.
+
+## Сигнатура функции
+
+```ts
+function array_key_to_upper_case(value: object): object;
+```
+
+## Описание
+
+Функция `array_key_to_upper_case` используется для преобразования всех ключей ассоциативного массива
+в верхний регистр. Если переданное значение не является массивом, функция выбрасывает ошибку типа
+`TypeError`. Если переданное значение является списком (обычным массивом), оно возвращается без
+изменений.
+
+## Параметры
+
+- `value` (object): Ассоциативный массив, ключи которого необходимо преобразовать в верхний регистр.
+
+## Возвращаемое значение
+
+Возвращает новый ассоциативный массив с ключами в верхнем регистре. Если переданное значение
+является списком, оно возвращается без изменений.
+
+## Примеры использования
+
+1. Преобразование ключей ассоциативного массива в верхний регистр:
+
+    ```js
+    const assoc = { key1: 'value1', key2: 'value2' };
+    const result = array_key_to_upper_case(assoc);
+    console.log(result); // { KEY1: 'value1', KEY2: 'value2' }
+    ```
+
+2. Обработка списка (обычного массива):
+
+    ```js
+    const list = [1, 2, 3];
+    const result = array_key_to_upper_case(list);
+    console.log(result); // [1, 2, 3]
+    ```
+
+3. Обработка значения, не являющегося массивом:
+
+    ```js
+    try {
+        const result = array_key_to_upper_case('not an array');
+    } catch (e) {
+        console.error(e.message); // Параметр "array" должен быть массивом.
+    }
+    ```

package/docs/helpers/array/array_keys.md

@@ -0,0 +1,62 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / array_keys
+
+[Исходный код](../../../src/helpers/array/array_keys.mjs)
+
+# array_keys
+
+`array_keys` — Возвращает массив ключей из переданного массива или объекта.
+
+## Сигнатура функции
+
+```ts
+function array_keys(value: object): array;
+```
+
+## Описание
+
+Функция `array_keys` используется для получения массива ключей из переданного массива или объекта.
+Она возвращает массив, содержащий все ключи переданного массива или объекта.
+
+## Параметры
+
+- `value` (object): Исходный массив или объект.
+
+## Возвращаемое значение
+
+Возвращает массив, содержащий все ключи переданного массива или объекта.
+
+## Примеры использования
+
+1. Получение ключей из обычного массива:
+
+    ```js
+    const array = [1, 2, 3];
+    const result = array_keys(array);
+    console.log(result); // ['0', '1', '2']
+    ```
+
+2. Получение ключей из ассоциативного массива:
+
+    ```js
+    const array = { a: 1, b: 2, c: 3 };
+    const result = array_keys(array);
+    console.log(result); // ['a', 'b', 'c']
+    ```
+
+3. Обработка пустого массива:
+
+    ```js
+    const array = [];
+    const result = array_keys(array);
+    console.log(result); // []
+    ```
+
+4. Обработка значений, не являющихся массивами или объектами:
+
+    ```js
+    try {
+        const result = array_keys('not an array');
+    } catch (e) {
+        console.error(e.message); // Параметр "value" должен быть массивом.
+    }
+    ```

package/docs/helpers/array/array_map.md

@@ -0,0 +1,69 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / array_map
+
+[Исходный код](../../../src/helpers/array/array_map.mjs)
+
+# array_map
+
+`array_map` — Применяет функцию обратного вызова к каждому элементу массива.
+
+## Сигнатура функции
+
+```ts
+function array_map(value: object, callback: function): object;
+```
+
+## Описание
+
+Функция `array_map` используется для применения функции обратного вызова к каждому элементу массива.
+Она возвращает новый массив, содержащий результаты применения функции обратного вызова к каждому
+элементу исходного массива.
+
+## Параметры
+
+- `value` (object): Исходный массив.
+- `callback` (function): Функция обратного вызова, применяемая к каждому элементу массива.
+
+## Возвращаемое значение
+
+Возвращает новый массив, содержащий результаты применения функции обратного вызова к каждому
+элементу исходного массива.
+
+## Примеры использования
+
+1. Применение функции обратного вызова к обычному массиву:
+
+    ```js
+    const array = [1, 2, 3];
+    const callback = (value) => value * 2;
+    const result = array_map(array, callback);
+    console.log(result); // [2, 4, 6]
+    ```
+
+2. Применение функции обратного вызова к ассоциативному массиву:
+
+    ```js
+    const array = { a: 1, b: 2, c: 3 };
+    const callback = (value) => value * 2;
+    const result = array_map(array, callback);
+    console.log(result); // { a: 2, b: 4, c: 6 }
+    ```
+
+3. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = array_map('not an array', (value) => value * 2);
+    } catch (e) {
+        console.error(e.message); // Параметр "value" должен быть массивом.
+    }
+    ```
+
+4. Обработка значений, не являющихся функциями:
+
+    ```js
+    try {
+        const result = array_map([1, 2, 3], 'not a function');
+    } catch (e) {
+        console.error(e.message); // Параметр "callback" должен быть функцией.
+    }
+    ```

package/docs/helpers/array/array_merge.md

@@ -0,0 +1,67 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / array_merge
+
+[Исходный код](../../../src/helpers/array/array_merge.mjs)
+
+# array_merge
+
+`array_merge` — Объединяет несколько массивов в один.
+
+## Сигнатура функции
+
+```ts
+function array_merge(...arrays: object[]): object;
+```
+
+## Описание
+
+Функция `array_merge` используется для объединения нескольких массивов в один. Она поддерживает как
+обычные массивы, так и ассоциативные массивы (объекты с ключами и значениями).
+
+## Параметры
+
+- `...arrays` (object[]): Массивы, которые необходимо объединить.
+
+## Возвращаемое значение
+
+Возвращает новый массив, содержащий элементы всех переданных массивов. Если все переданные массивы
+являются обычными массивами, результатом будет обычный массив. Если хотя бы один из переданных
+массивов является ассоциативным массивом, результатом будет ассоциативный массив.
+
+## Примеры использования
+
+1. Объединение обычных массивов:
+
+    ```js
+    const array1 = [1, 2, 3];
+    const array2 = [4, 5, 6];
+    const result = array_merge(array1, array2);
+    console.log(result); // [1, 2, 3, 4, 5, 6]
+    ```
+
+2. Объединение ассоциативных массивов:
+
+    ```js
+    const array1 = { a: 1, b: 2 };
+    const array2 = { c: 3, d: 4 };
+    const result = array_merge(array1, array2);
+    console.log(result); // { a: 1, b: 2, c: 3, d: 4 }
+    ```
+
+3. Объединение обычных и ассоциативных массивов:
+
+    ```js
+    const array1 = [1, 2, 3];
+    const array2 = { a: 4, b: 5 };
+    const result = array_merge(array1, array2);
+    console.log(result); // { 0: 1, 1: 2, 2: 3, a: 4, b: 5 }
+    ```
+
+4. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = array_merge('not an array');
+    } catch (e) {
+        console.error(e.message); // Параметр "arrays" должен быть массивом.
+    }
+    ```

package/docs/helpers/array/array_merge_recursive.md

@@ -0,0 +1,86 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / array_merge_recursive
+
+[Исходный код](../../../src/helpers/array/array_merge_recursive.mjs)
+
+# array_merge_recursive
+
+`array_merge_recursive` — Объединяет несколько массивов рекурсивно.
+
+## Сигнатура функции
+
+```ts
+function array_merge_recursive(...arrays: object[]): object;
+```
+
+## Описание
+
+Функция `array_merge_recursive` используется для рекурсивного объединения нескольких массивов в
+один. Она поддерживает как обычные массивы, так и ассоциативные массивы (объекты с ключами и
+значениями).
+
+## Параметры
+
+- `...arrays` (object[]): Массивы, которые необходимо объединить.
+
+## Возвращаемое значение
+
+Возвращает новый массив, содержащий элементы всех переданных массивов. Если все переданные массивы
+являются обычными массивами, результатом будет обычный массив. Если хотя бы один из переданных
+массивов является ассоциативным массивом, результатом будет ассоциативный массив.
+
+## Примеры использования
+
+1. Объединение обычных массивов:
+
+    ```js
+    const array1 = [1, 2, 3];
+    const array2 = [4, 5, 6];
+    const result = array_merge_recursive(array1, array2);
+    console.log(result); // [1, 2, 3, 4, 5, 6]
+    ```
+
+2. Объединение ассоциативных массивов:
+
+    ```js
+    const array1 = { a: 1, b: 2 };
+    const array2 = { b: 3, c: 4 };
+    const result = array_merge_recursive(array1, array2);
+    console.log(result); // { a: 1, b: [2, 3], c: 4 }
+    ```
+
+3. Объединение обычных и ассоциативных массивов:
+
+    ```js
+    const array1 = [1, 2, 3];
+    const array2 = { a: 4, b: 5 };
+    const result = array_merge_recursive(array1, array2);
+    console.log(result); // { 0: 1, 1: 2, 2: 3, a: 4, b: 5 }
+    ```
+
+4. Объединение вложенных массивов:
+
+    ```js
+    const array1 = { a: { b: 1 } };
+    const array2 = { a: { c: 2 } };
+    const result = array_merge_recursive(array1, array2);
+    console.log(result); // { a: { b: 1, c: 2 } }
+    ```
+
+5. Объединение массивов с одинаковыми ключами:
+
+    ```js
+    const array1 = { a: { b: 1 } };
+    const array2 = { a: { b: 2 } };
+    const result = array_merge_recursive(array1, array2);
+    console.log(result); // { a: { b: [1, 2] } }
+    ```
+
+6. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = array_merge_recursive('not an array');
+    } catch (e) {
+        console.error(e.message); // Параметр "arrays" должен быть массивом.
+    }
+    ```

package/docs/helpers/array/array_pad.md

@@ -0,0 +1,83 @@
+[Главная](../../../README.md) / [Помощники](../../helpers.md) / array_pad
+
+[Исходный код](../../../src/helpers/array/array_pad.mjs)
+
+# array_pad
+
+`array_pad` — Дополняет массив до заданной длины указанным значением.
+
+## Сигнатура функции
+
+```ts
+function array_pad(arr: object, length: number, value: any): object;
+```
+
+## Описание
+
+Функция `array_pad` используется для дополнения массива до заданной длины указанным значением. Если
+длина положительная, элементы добавляются в конец массива. Если длина отрицательная, элементы
+добавляются в начало массива.
+
+## Параметры
+
+- `arr` (object): Исходный массив.
+- `length` (number): Желаемая длина массива.
+- `value` (any): Значение для дополнения массива.
+
+## Возвращаемое значение
+
+Возвращает новый массив, дополненный до заданной длины указанным значением.
+
+## Примеры использования
+
+1. Дополнение массива до длины 5:
+
+    ```js
+    const array = [1, 2, 3];
+    const result = array_pad(array, 5, 0);
+    console.log(result); // [1, 2, 3, 0, 0]
+    ```
+
+2. Дополнение массива до длины -5:
+
+    ```js
+    const array = [1, 2, 3];
+    const result = array_pad(array, -5, 0);
+    console.log(result); // [0, 0, 1, 2, 3]
+    ```
+
+3. Возвращение массива без изменений, если длина меньше или равна текущей длине массива:
+
+    ```js
+    const array = [1, 2, 3];
+    const result = array_pad(array, 3, 0);
+    console.log(result); // [1, 2, 3]
+    ```
+
+4. Дополнение пустого массива:
+
+    ```js
+    const array = [];
+    const result = array_pad(array, 3, 0);
+    console.log(result); // [0, 0, 0]
+    ```
+
+5. Обработка значений, не являющихся массивами:
+
+    ```js
+    try {
+        const result = array_pad('not an array', 5, 0);
+    } catch (e) {
+        console.error(e.message); // Параметр "arr" должен быть массивом.
+    }
+    ```
+
+6. Обработка значений длины, не являющихся числами:
+
+    ```js
+    try {
+        const result = array_pad([1, 2, 3], 'not a number', 0);
+    } catch (e) {
+        console.error(e.message); // Параметр "length" должен быть целым числом.
+    }
+    ```