@rogolev/value 0.0.1

package/src/helpers/to_array.mjs

@@ -0,0 +1,118 @@
+import array from './array.mjs';
+import is_array from './is_array.mjs';
+import is_null from './is_null.mjs';
+import is_undefined from './is_undefined.mjs';
+
+/**
+ * Приводит значение переменной к массиву.
+ *
+ * ### Описание
+ *
+ * Функция `to_array` используется для преобразования различных типов данных в массив. Если значение
+ * уже является массивом (тип `Array` или ассоциативный массив), возвращается оно же. Объекты
+ * (экземпляры классов) преобразуются в массив с одним элементом.
+ *
+ * #### Примечание
+ *
+ * Функция `to_array` для объектов (ассоциативных массивов) возвращает результат
+ * работы функции `array`, которая создает объект-контейнер пар ключ-значение
+ * (ассоциативный массив) с помощью конструкции `Object.create(null)`,
+ * копирует все видимые пары в этот контейнер, а также добавляет итератор
+ * `Symbol.iterator` для перебора контейнера в цикле `for-of`.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Переменная, значение которой необходимо привести к массиву.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает массив, содержащий переданное значение. Если значение уже является массивом, возвращается оно же.
+ *
+ * ### Примеры использования
+ *
+ * 1. Преобразование строки в массив:
+ *
+ *    ```js
+ *    const result = to_array('example');
+ *    // Результат: ["example"]
+ *    ```
+ *
+ * 2. Преобразование числа в массив:
+ *
+ *    ```js
+ *    const result = to_array(123);
+ *    // Результат: [123]
+ *    ```
+ *
+ * 3. Преобразование массива (без изменений):
+ *
+ *    ```js
+ *    const result = to_array([1, 2, 3]);
+ *    // Результат: [1, 2, 3]
+ *    ```
+ *
+ * 4. Преобразование объекта в массив:
+ *
+ * Функция `to_array` для объектов (ассоциативных массивов) возвращает
+ * результат работы функции `array`, которая создает объект-контейнер
+ * пар ключ-значение (ассоциативный массив) с помощью конструкции
+ * `Object.create(null)`, копирует все видимые пары в этот контейнер,
+ * а также добавляет итератор `Symbol.iterator` для перебора контейнера
+ * в цикле `for-of`.
+ *
+ *    ```js
+ *    const result = to_array({ key: 'value' });
+ *    // Результат: { key: "value" }
+ *
+ *    const proto = Object.getPrototypeOf(result);
+ *    // Результат: null
+ *
+ *    for (const [key, value] of result) {
+ *        console.log(key, value);
+ *    }
+ *    // Результат: 'key', 'value'
+ *    ```
+ *
+ * 5. Преобразование экземпляра класса в массив:
+ *
+ *    ```js
+ *    class MyClass {}
+ *
+ *    const instance = new MyClass();
+ *    const result = to_array(instance);
+ *    // Результат: [instance]
+ *    ```
+ *
+ * 6. Преобразование null:
+ *
+ *    ```js
+ *    const result = to_array(null);
+ *    // Результат: []
+ *    ```
+ *
+ * 7. Преобразование undefined:
+ *
+ *    ```js
+ *    const result = to_array(undefined);
+ *    // Результат: []
+ *    ```
+ *
+ * @param {any} value Переменная, значение которой необходимо привести к массиву.
+ * @returns {Array|Object} Возвращает приведенное к массиву значение переменной `value`.
+ */
+export default function to_array(value) {
+    if (is_null(value) || is_undefined(value)) {
+        return [];
+    }
+
+    if (Array.isArray(value)) {
+        return value;
+    }
+
+    if (is_array(value)) {
+        return array(value);
+    }
+
+    return [value];
+}

package/src/helpers/to_assoc.mjs

@@ -0,0 +1,98 @@
+import is_array from './is_array.mjs';
+import is_null from './is_null.mjs';
+import is_undefined from './is_undefined.mjs';
+
+/**
+ * Преобразует значение в ассоциативный массив.
+ *
+ * ### Описание
+ *
+ * Функция `to_assoc` используется для преобразования различных типов данных в ассоциативный массив.
+ * Если значение уже является объектом, возвращается оно же. Массивы преобразуются в объекты с
+ * индексами в качестве ключей.
+ *
+ * #### Примечание
+ *
+ * Функция `to_assoc` для массивов возвращает объект, где ключами являются индексы элементов массива.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Значение, которое необходимо преобразовать в ассоциативный массив.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает объект, представляющий ассоциативный массив. Если значение уже является объектом, возвращается оно же.
+ *
+ * ### Примеры использования
+ *
+ * 1. Преобразование строки в ассоциативный массив:
+ *
+ *    ```js
+ *    const result = to_assoc('example');
+ *    // Результат: { 0: 'example' }
+ *    ```
+ *
+ * 2. Преобразование числа в ассоциативный массив:
+ *
+ *    ```js
+ *    const result = to_assoc(123);
+ *    // Результат: { 0: 123 }
+ *    ```
+ *
+ * 3. Преобразование массива в ассоциативный массив:
+ *
+ *    ```js
+ *    const result = to_assoc([1, 2, 3]);
+ *    // Результат: { 0: 1, 1: 2, 2: 3 }
+ *    ```
+ *
+ * 4. Преобразование ассоциативного массива (без изменений):
+ *
+ *    ```js
+ *    const result = to_assoc({ key: 'value' });
+ *    // Результат: { key: 'value' }
+ *    ```
+ *
+ * 5. Преобразование экземпляра класса в ассоциативный массив:
+ *
+ *    ```js
+ *    class MyClass {}
+ *
+ *    const instance = new MyClass();
+ *    const result = to_assoc(instance);
+ *    // Результат: { 0: instance }
+ *    ```
+ *
+ * 6. Преобразование null:
+ *
+ *    ```js
+ *    const result = to_assoc(null);
+ *    // Результат: {}
+ *    ```
+ *
+ * 7. Преобразование undefined:
+ *
+ *    ```js
+ *    const result = to_assoc(undefined);
+ *    // Результат: {}
+ *    ```
+ *
+ * @param {any} value Значение, которое необходимо преобразовать.
+ * @returns {Object} Возвращает объект, представляющий ассоциативный массив.
+ */
+export default function to_assoc(value) {
+    if (is_null(value) || is_undefined(value)) {
+        return {};
+    }
+
+    if (Array.isArray(value)) {
+        return { ...value };
+    }
+
+    if (is_array(value)) {
+        return value;
+    }
+
+    return { 0: value };
+}

package/src/helpers/to_bool.mjs

@@ -0,0 +1,68 @@
+import is_array from './is_array.mjs';
+
+/**
+ * Приводит значение переменной к логическому типу.
+ *
+ * ### Описание
+ *
+ * Функция `to_bool` используется для преобразования различных типов данных в логическое значение.
+ * Если значение является пустым массивом, функция возвращает `false`.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Переменная, значение которой необходимо привести к логическому типу.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает логическое значение, соответствующее переданному значению.
+ *
+ * ### Примеры использования
+ *
+ * 1. Преобразование пустого массива в `false`:
+ *
+ *    ```js
+ *    const result = to_bool([]);
+ *    // Результат: false
+ *    ```
+ *
+ * 2. Преобразование пустого ассоциативного массива в `false`:
+ *
+ *    ```js
+ *    const result = to_bool({});
+ *    // Результат: false
+ *    ```
+ *
+ * 3. Преобразование непустого массива в `true`:
+ *
+ *    ```js
+ *    const result = to_bool([1, 2, 3]);
+ *    // Результат: true
+ *    ```
+ *
+ * 4. Преобразование других значений:
+ *
+ *    ```js
+ *    const result1 = to_bool('example');
+ *    // Результат: true
+ *
+ *    const result2 = to_bool(123);
+ *    // Результат: true
+ *
+ *    const result3 = to_bool(null);
+ *    // Результат: false
+ *
+ *    const result4 = to_bool(undefined);
+ *    // Результат: false
+ *    ```
+ *
+ * @param {any} value Переменная, значение которой необходимо привести к логическому типу.
+ * @returns {boolean} Возвращает приведенное к логическому типу значение переменной `value`.
+ */
+export default function to_bool(value) {
+    if (is_array(value) && Object.keys(value).length === 0) {
+        return false;
+    }
+
+    return Boolean(value);
+}

package/src/helpers/to_boolean.mjs

@@ -0,0 +1,64 @@
+import to_bool from './to_bool.mjs';
+
+/**
+ * Приводит значение переменной к логическому типу.
+ *
+ * ### Описание
+ *
+ * Функция `to_boolean` является синонимом функции `to_bool` и используется для преобразования различных типов данных в логическое значение.
+ * Если значение является пустым массивом, функция возвращает `false`.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Переменная, значение которой необходимо привести к логическому типу.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает логическое значение, соответствующее переданному значению.
+ *
+ * ### Примеры использования
+ *
+ * 1. Преобразование пустого массива в `false`:
+ *
+ *    ```js
+ *    const result = to_boolean([]);
+ *    // Результат: false
+ *    ```
+ *
+ * 2. Преобразование пустого ассоциативного массива в `false`:
+ *
+ *    ```js
+ *    const result = to_boolean({});
+ *    // Результат: false
+ *    ```
+ *
+ * 3. Преобразование непустого массива в `true`:
+ *
+ *    ```js
+ *    const result = to_boolean([1, 2, 3]);
+ *    // Результат: true
+ *    ```
+ *
+ * 4. Преобразование других значений:
+ *
+ *    ```js
+ *    const result1 = to_boolean('example');
+ *    // Результат: true
+ *
+ *    const result2 = to_boolean(123);
+ *    // Результат: true
+ *
+ *    const result3 = to_boolean(null);
+ *    // Результат: false
+ *
+ *    const result4 = to_boolean(undefined);
+ *    // Результат: false
+ *    ```
+ *
+ * @param {any} value Переменная, значение которой необходимо привести к логическому типу.
+ * @returns {boolean} Возвращает приведенное к логическому типу значение переменной `value`.
+ */
+export default function to_boolean(value) {
+    return to_bool(value);
+}

package/src/helpers/to_float.mjs

@@ -0,0 +1,72 @@
+import is_float from './is_float.mjs';
+import is_int from './is_int.mjs';
+import is_string from './is_string.mjs';
+import to_bool from './to_bool.mjs';
+
+/**
+ * Приводит значение переменной к числу с плавающей точкой.
+ *
+ * ### Описание
+ *
+ * Функция `to_float` используется для преобразования различных типов данных в число с плавающей точкой. Если значение не является числом или строкой, функция возвращает `1` для истинных значений и `0` для ложных значений.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Переменная, значение которой необходимо привести к числу с плавающей точкой.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает число с плавающей точкой, соответствующее переданному значению.
+ *
+ * ### Примеры использования
+ *
+ * 1. Преобразование строки в число с плавающей точкой:
+ *
+ *    ```js
+ *    const result = to_float('123.45');
+ *    // Результат: 123.45
+ *    ```
+ *
+ * 2. Преобразование целого числа в число с плавающей точкой:
+ *
+ *    ```js
+ *    const result = to_float(123);
+ *    // Результат: 123.0
+ *    ```
+ *
+ * 3. Преобразование булевых значений:
+ *
+ *    ```js
+ *    const result1 = to_float(true);
+ *    // Результат: 1.0
+ *
+ *    const result2 = to_float(false);
+ *    // Результат: 0.0
+ *    ```
+ *
+ * 4. Преобразование других значений:
+ *
+ *    ```js
+ *    const result1 = to_float(null);
+ *    // Результат: 0.0
+ *
+ *    const result2 = to_float(undefined);
+ *    // Результат: 0.0
+ *
+ *    const result3 = to_float('example');
+ *    // Результат: 0.0
+ *    ```
+ *
+ * @param {any} value Переменная, значение которой необходимо привести к числу с плавающей точкой.
+ * @returns {number} Возвращает приведенное к числу с плавающей точкой значение переменной `value`.
+ */
+export default function to_float(value) {
+    if (!is_int(value) && !is_float(value) && !is_string(value)) {
+        return Number(to_bool(value));
+    }
+
+    const result = parseFloat(value);
+
+    return Number.isNaN(result) ? 0 : result;
+}

package/src/helpers/to_int.mjs

@@ -0,0 +1,93 @@
+import to_bool from './to_bool.mjs';
+import is_float from './is_float.mjs';
+import is_int from './is_int.mjs';
+import is_string from './is_string.mjs';
+
+/**
+ * Приводит значение переменной к целому числу.
+ *
+ * ### Описание
+ *
+ * Функция `to_int` используется для преобразования различных типов данных в целое число. Если значение не является числом или строкой, функция возвращает `1` для истинных значений и `0` для ложных значений.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Переменная, значение которой необходимо привести к целому числу.
+ *
+ * - `base` (number)
+ *      Основание системы счисления для преобразования строки в число. По умолчанию `10`.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает целое число, соответствующее переданному значению.
+ *
+ * ### Примеры использования
+ *
+ * 1. Преобразование строки в целое число:
+ *
+ *    ```js
+ *    const result = to_int('123');
+ *    // Результат: 123
+ *    ```
+ *
+ * 2. Преобразование числа с плавающей точкой в целое число:
+ *
+ *    ```js
+ *    const result = to_int(123.45);
+ *    // Результат: 123
+ *    ```
+ *
+ * 3. Преобразование булевых значений:
+ *
+ *    ```js
+ *    const result1 = to_int(true);
+ *    // Результат: 1
+ *
+ *    const result2 = to_int(false);
+ *    // Результат: 0
+ *    ```
+ *
+ * 4. Преобразование других значений:
+ *
+ *    ```js
+ *    const result1 = to_int(null);
+ *    // Результат: 0
+ *
+ *    const result2 = to_int(undefined);
+ *    // Результат: 0
+ *
+ *    const result3 = to_int('example');
+ *    // Результат: 0
+ *    ```
+ *
+ * 5. Преобразование строки с основанием системы счисления:
+ *
+ *    ```js
+ *    const result1 = to_int('10', 2);
+ *    // Результат: 2
+ *
+ *    const result2 = to_int('A', 16);
+ *    // Результат: 10
+ *
+ *    const result3 = to_int('7', 8);
+ *    // Результат: 7
+ *    ```
+ *
+ * @param {any} value Переменная, значение которой необходимо привести к целому числу.
+ * @param {number} [base=10] Основание системы счисления для преобразования строки в число.
+ * @returns {number} Возвращает приведенное к целому числу значение переменной `value`.
+ */
+export default function to_int(value, base = 10) {
+    if (!is_int(base)) {
+        throw new TypeError('Параметр "base" должен быть целым числом.');
+    }
+
+    if (!is_int(value) && !is_float(value) && !is_string(value)) {
+        return Number(to_bool(value));
+    }
+
+    const result = parseInt(value, base);
+
+    return Number.isNaN(result) ? 0 : result;
+}

package/src/helpers/to_integer.mjs

@@ -0,0 +1,81 @@
+import to_int from './to_int.mjs';
+
+/**
+ * Приводит значение переменной к целому числу.
+ *
+ * ### Описание
+ *
+ * Функция `to_integer` является синонимом функции `to_int` и используется для преобразования различных типов данных в целое число.
+ * Если значение не является числом или строкой, функция возвращает `1` для истинных значений и `0` для ложных значений.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Переменная, значение которой необходимо привести к целому числу.
+ *
+ * - `base` (number)
+ *      Основание системы счисления для преобразования строки в число. По умолчанию `10`.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает целое число, соответствующее переданному значению.
+ *
+ * ### Примеры использования
+ *
+ * 1. Преобразование строки в целое число:
+ *
+ *    ```js
+ *    const result = to_integer('123');
+ *    // Результат: 123
+ *    ```
+ *
+ * 2. Преобразование числа с плавающей точкой в целое число:
+ *
+ *    ```js
+ *    const result = to_integer(123.45);
+ *    // Результат: 123
+ *    ```
+ *
+ * 3. Преобразование булевых значений:
+ *
+ *    ```js
+ *    const result1 = to_integer(true);
+ *    // Результат: 1
+ *
+ *    const result2 = to_integer(false);
+ *    // Результат: 0
+ *    ```
+ *
+ * 4. Преобразование других значений:
+ *
+ *    ```js
+ *    const result1 = to_integer(null);
+ *    // Результат: 0
+ *
+ *    const result2 = to_integer(undefined);
+ *    // Результат: 0
+ *
+ *    const result3 = to_integer('example');
+ *    // Результат: 0
+ *    ```
+ *
+ * 5. Преобразование строки с основанием системы счисления:
+ *
+ *    ```js
+ *    const result1 = to_integer('10', 2);
+ *    // Результат: 2
+ *
+ *    const result2 = to_integer('A', 16);
+ *    // Результат: 10
+ *
+ *    const result3 = to_integer('7', 8);
+ *    // Результат: 7
+ *    ```
+ *
+ * @param {any} value Переменная, значение которой необходимо привести к целому числу.
+ * @param {number} [base=10] Основание системы счисления для преобразования строки в число.
+ * @returns {number} Возвращает приведенное к целому числу значение переменной `value`.
+ */
+export default function to_integer(value, base = 10) {
+    return to_int(value, base);
+}

package/src/helpers/to_list.mjs

@@ -0,0 +1,56 @@
+import is_array from './is_array.mjs';
+import is_null from './is_null.mjs';
+import is_undefined from './is_undefined.mjs';
+
+/**
+ * Преобразует значение в список.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Значение, которое необходимо преобразовать.
+ *
+ * ### Описание
+ *
+ * Функция `to_list` преобразует переданное значение в список.
+ *
+ * Она выполняет следующие проверки:
+ *
+ * 1. **Null и Undefined**: Возвращает пустой массив для значений `null` и `undefined`.
+ * 2. **Array**: Возвращает исходный массив, если он передан.
+ * 3. **Object**: Возвращает массив значений объекта, если передан ассоциативный массив.
+ * 4. **Примитивы и другие типы**: Возвращает массив, содержащий переданное значение.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает массив, представляющий список значений.
+ *
+ * ### Примеры использования
+ *
+ * ```js
+ * to_list(null); // []
+ * to_list(undefined); // []
+ * to_list([1, 2, 3]); // [1, 2, 3]
+ * to_list({ key: 'value' }); // ['value']
+ * to_list('example'); // ['example']
+ * to_list(123); // [123]
+ * ```
+ *
+ * @param {any} value Значение, которое необходимо преобразовать.
+ * @returns {Array} Возвращает массив, представляющий список значений.
+ */
+export default function to_list(value) {
+    if (is_null(value) || is_undefined(value)) {
+        return [];
+    }
+
+    if (Array.isArray(value)) {
+        return value;
+    }
+
+    if (is_array(value)) {
+        return Object.values(value);
+    }
+
+    return [value];
+}