@rogolev/value 0.0.1

package/src/helpers/is_array.mjs

@@ -0,0 +1,128 @@
+/**
+ * Проверяет, является ли переданное значение массивом или ассоциативным массивом (объектом с ключами и значениями).
+ *
+ * ### Описание
+ *
+ * В JavaScript массивы и объекты имеют разные структуры и предназначения:
+ *
+ * - Массивы (Array) являются упорядоченными коллекциями элементов, которые могут быть индексированы.
+ * - Объекты (Object) содержат пары "ключ-значение", которые могут быть неупорядоченными.
+ *
+ * Эта функция проверяет, является ли переданное значение обычным массивом (например, `[1, 2, 3]`),
+ * либо ассоциативным массивом (объектом с парами "ключ-значение", например, `{foo: 'bar'}`).
+ *
+ * ### Алгоритм работы функции
+ *
+ * 1. Сначала проверяется, является ли переданное значение обычным массивом с помощью встроенного метода `Array.isArray(value)`. Если это массив, функция сразу возвращает `true`.
+ *
+ * 2. Если переменная не является массивом, то выполняются дополнительные проверки:
+ *
+ *    - Проверяется, что значение не равно `null` (так как `null` в JavaScript также является объектом, но не является ни массивом, ни объектом с парами "ключ-значение").
+ *    - Проверяется, что значение является объектом JavaScript (с помощью `typeof value === 'object'`).
+ *    - Проверяется, что прототип объекта совпадает с `Object.prototype` (это объект, от которого наследуются все объекты в JavaScript) или является `null` (это означает, что объект был создан с помощью `Object.create(null)` и не имеет прототипа).
+ *    - Исключаются массивоподобные объекты (например, `arguments`, `NodeList`), путем проверки, что свойство `length` не является собственным свойством объекта.
+ *    - Дополнительно проверяется, что объект является простым (его конструктор равен `Object`), а также исключаются встроенные объекты (`Math`, `JSON`, `Reflect`, `Intl`), для которых функция возвращает `true`.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Проверяемая переменная.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если переменная является обычным массивом (`Array`), ассоциативным массивом (объектом с парами "ключ-значение"), ассоциативным массивом, созданным с помощью `Object.create(null)`. В остальных случаях функция возвращает `false`.
+ *
+ * ### Примеры использования
+ *
+ * 1. Простые массивы:
+ *
+ *    ```js
+ *    is_array([1, 2, 3]); // true
+ *    is_array([]); // true
+ *    ```
+ *
+ * 2. Ассоциативные массивы (объекты с ключами и значениями):
+ *
+ *    ```js
+ *    is_array({ foo: 'bar', baz: 42 }); // true
+ *    is_array({ '0': 'a', '1': 'b' }); // true
+ *    ```
+ *
+ * 3. Объекты, созданные без прототипа:
+ *
+ *    ```js
+ *    const noProtoObject = Object.create(null);
+ *    noProtoObject.foo = 'bar';
+ *    is_array(noProtoObject); // true
+ *    ```
+ *
+ * 4. Примитивы и невалидные значения:
+ *
+ *    ```js
+ *    is_array(null);         // false
+ *    is_array(undefined);    // false
+ *    is_array(42);           // false
+ *    is_array('hello');      // false
+ *    ```
+ *
+ * 5. Специальные объекты:
+ *
+ *    ```js
+ *    is_array(new Map());    // false
+ *    is_array(new Set());    // false
+ *    is_array(() => {});     // false
+ *    ```
+ *
+ * 6. Классы и их экземпляры:
+ *
+ *    ```js
+ *    class MyClass {}
+ *    const instance = new MyClass();
+ *    is_array(instance); // false
+ *    ```
+ *
+ * @param {any} value Проверяемая переменная.
+ * @returns {boolean} Возвращает `true`, если значение является массивом или ассоциативным массивом, иначе `false`.
+ */
+export default function is_array(value) {
+    // Для массивов (Array) возвращаем `true` по умолчанию.
+    if (Array.isArray(value)) {
+        return true;
+    }
+
+    // Далее работаем только с объектами.
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+
+    // Если у переданного объекта отсутствует прототип, то это означает,
+    // что объект является контейнером пар ключ-значение без встроенных методов,
+    // наследуемых от прототипа Object.prototype.
+    // Такой контейнер можно создать с помощью конструкции `Object.create(null)`
+    // или с помощью функции `array({})`.
+    if (Object.getPrototypeOf(value) === null) {
+        return true;
+    }
+
+    // Исключаем встроенные объекты Math, JSON, Reflect, Intl, для которых
+    // функция возвращает `true`.
+    if ([Math, JSON, Reflect, Intl].includes(value)) {
+        return false;
+    }
+
+    // Если у объекта присутствует свойство `length`, то это означает, что
+    // передан массивоподобный объект, например `arguments`.
+    // С точки зрения данной функции, данные объекты считать
+    // ассоциативными массивами нельзя.
+    if (Object.hasOwn(value, 'length')) {
+        return false;
+    }
+
+    // Если прототип переданного объекта - `Object.prototype`, то передан
+    // обычный объект.
+    if (Object.getPrototypeOf(value) === Object.prototype) {
+        return true;
+    }
+
+    return false;
+}

package/src/helpers/is_assoc.mjs

@@ -0,0 +1,51 @@
+import is_array from './is_array.mjs';
+
+/**
+ * Проверяет, является ли значение ассоциативным массивом.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Значение, которое необходимо проверить.
+ *
+ * ### Описание
+ *
+ * Функция `is_assoc` проверяет, является ли переданное значение ассоциативным массивом.
+ *
+ * Она использует метод `is_array` для проверки значения и убеждается, что значение не является обычным массивом.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значение является ассоциативным массивом, и `false` в противном случае.
+ *
+ * ### Примеры использования
+ *
+ * #### Пример 1: Проверка ассоциативных массивов
+ *
+ * ```js
+ * is_assoc({ foo: 'bar' }); // true
+ * is_assoc({}); // true
+ * ```
+ *
+ * #### Пример 2: Проверка обычных массивов
+ *
+ * ```js
+ * is_assoc([]); // false
+ * is_assoc([1, 2, 3]); // false
+ * ```
+ *
+ * #### Пример 3: Проверка значений других типов
+ *
+ * ```js
+ * is_assoc('string'); // false (строка)
+ * is_assoc(42); // false (число)
+ * is_assoc(null); // false
+ * is_assoc(undefined); // false
+ * ```
+ *
+ * @param {any} value Значение, которое необходимо проверить.
+ * @returns {boolean} Возвращает `true`, если значение является ассоциативным массивом, и `false` в противном случае.
+ */
+export default function is_assoc(value) {
+    return is_array(value) && !Array.isArray(value);
+}

package/src/helpers/is_bigint.mjs

@@ -0,0 +1,47 @@
+/**
+ * Проверяет, является ли значение типом `bigint`.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Значение, которое необходимо проверить.
+ *
+ * ### Описание
+ *
+ * Функция `is_bigint` проверяет, является ли переданное значение типом `bigint`.
+ *
+ * 1. Проверяется, что значение имеет тип `bigint`.
+ *
+ * Функция возвращает `false` для значений других типов, таких как числа, строки, объекты или массивы.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значение является типом `bigint`, и `false` в противном случае.
+ *
+ * ### Примеры использования
+ *
+ * #### Пример 1: Проверка значений типа bigint
+ *
+ * ```js
+ * is_bigint(BigInt(123456)); // true
+ * is_bigint(BigInt(-123456)); // true
+ * ```
+ *
+ * #### Пример 2: Проверка значений других типов
+ *
+ * ```js
+ * is_bigint(42); // false (число)
+ * is_bigint('42'); // false (строка)
+ * is_bigint(true); // false (логическое значение)
+ * is_bigint(null); // false
+ * is_bigint(undefined); // false
+ * is_bigint({}); // false (объект)
+ * is_bigint([]); // false (массив)
+ * ```
+ *
+ * @param {any} value Значение, которое необходимо проверить.
+ * @returns {boolean} Возвращает `true`, если значение является типом bigint, и `false` в противном случае.
+ */
+export default function is_bigint(value) {
+    return typeof value === 'bigint';
+}

package/src/helpers/is_bool.mjs

@@ -0,0 +1,43 @@
+/**
+ * Проверяет, является ли переданное значение логическим типом (`boolean`).
+ *
+ * ### Описание
+ *
+ * В JavaScript логическое значение может быть только двумя состояниями: `true` или `false`.
+ * Функция проверяет тип переданного значения с использованием оператора `typeof`.
+ * Если значение является примитивом типа `boolean`, функция возвращает `true`.
+ * Для всех других типов (включая объекты, строки, числа, `null`, `undefined` и другие) функция вернёт `false`.
+ *
+ * #### Примечание
+ *
+ * - Функция возвращает `false` для объектов типа `Boolean`, созданных с помощью конструктора `new Boolean()`.
+ * - Возвращает `false` для массивов, объектов и других типов данных, отличных от `boolean`.
+ *
+ * ### Параметры
+ *
+ * - `value` (any):
+ *      Проверяемая переменная.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значение `value` является логическим (`boolean`), иначе `false`.
+ *
+ * ### Примеры использования
+ *
+ * ```js
+ * is_bool(true);   // Возвращает: true
+ * is_bool(false);  // Возвращает: true
+ * is_bool(0);      // Возвращает: false
+ * is_bool('true'); // Возвращает: false
+ * is_bool(null);   // Возвращает: false
+ * is_bool([]);     // Возвращает: false
+ * is_bool({});     // Возвращает: false
+ * is_bool(new Boolean(true)); // Возвращает: false
+ * ```
+ *
+ * @param {any} value Проверяемая переменная.
+ * @returns {boolean} Возвращает `true`, если значение является логическим, иначе `false`.
+ */
+export default function is_bool(value) {
+    return typeof value === 'boolean';
+}

package/src/helpers/is_boolean.mjs

@@ -0,0 +1,43 @@
+/**
+ * Проверяет, является ли переданное значение логическим типом (`boolean`).
+ *
+ * ### Описание
+ *
+ * В JavaScript логическое значение может быть только двумя состояниями: `true` или `false`.
+ * Функция проверяет тип переданного значения с использованием оператора `typeof`.
+ * Если значение является примитивом типа `boolean`, функция возвращает `true`.
+ * Для всех других типов (включая объекты, строки, числа, `null`, `undefined` и другие) функция вернёт `false`.
+ *
+ * #### Примечание
+ *
+ * - Функция возвращает `false` для объектов типа `Boolean`, созданных с помощью конструктора `new Boolean()`.
+ * - Возвращает `false` для массивов, объектов и других типов данных, отличных от `boolean`.
+ *
+ * ### Параметры
+ *
+ * - `value` (any):
+ *      Проверяемая переменная.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значение `value` является логическим (`boolean`), иначе `false`.
+ *
+ * ### Примеры использования
+ *
+ * ```js
+ * is_boolean(true);   // Возвращает: true
+ * is_boolean(false);  // Возвращает: true
+ * is_boolean(0);      // Возвращает: false
+ * is_boolean('true'); // Возвращает: false
+ * is_boolean(null);   // Возвращает: false
+ * is_boolean([]);     // Возвращает: false
+ * is_boolean({});     // Возвращает: false
+ * is_boolean(new Boolean(true)); // Возвращает: false
+ * ```
+ *
+ * @param {any} value Проверяемая переменная.
+ * @returns {boolean} Возвращает `true`, если значение является логическим, иначе `false`.
+ */
+export default function is_boolean(value) {
+    return typeof value === 'boolean';
+}

package/src/helpers/is_class.mjs

@@ -0,0 +1,87 @@
+/**
+ * Проверяет, является ли переданная переменная классом.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Проверяемая переменная.
+ *
+ * ### Описание
+ *
+ * В JavaScript классы являются функциями, но с уникальным поведением.
+ *
+ * Для определения класса функция проверяет:
+ *
+ * 1. Что переданная переменная является функцией.
+ * 2. Что строковое представление функции начинается с `class `.
+ *
+ * #### Примечание
+ *
+ * Конструкторы функций, созданные с помощью `function`, не будут распознаны как классы.
+ *
+ * Для примера:
+ *
+ * ```js
+ * function Foo() {}
+ * is_class(Foo); // Возвращает: false
+ * ```
+ *
+ * В отличие от классов, которые выглядят так:
+ *
+ * ```js
+ * class MyClass {}
+ * is_class(MyClass); // Возвращает: true
+ * ```
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значение является классом, иначе `false`.
+ *
+ * ### Примеры использования
+ *
+ * 1. Классы:
+ *
+ * ```js
+ * class MyClass {}
+ * is_class(MyClass); // true
+ * ```
+ *
+ * 2. Функции-конструкторы:
+ *
+ * ```js
+ * function MyFunction() {}
+ * is_class(MyFunction); // false
+ * ```
+ *
+ * 3. Объекты и примитивы:
+ *
+ * ```js
+ * is_class({}); // false
+ * is_class([]); // false
+ * is_class(null); // false
+ * is_class(42); // false
+ * ```
+ *
+ * @param {any} value Проверяемая переменная.
+ * @returns {boolean} Возвращает `true`, если значение является классом, иначе `false`.
+ */
+export default function is_class(value) {
+    // Проверяем, является ли значение функцией
+    if (typeof value !== 'function') {
+        return false;
+    }
+
+    // Проверяем, не является ли значение классом, используя строковое представление функции
+    if (typeof value.toString === 'function') {
+        return /^class\s/.test(value.toString());
+    }
+
+    // Если у функции нет прототипа, значит это стрелочная функция или метод
+    if (!value.prototype) {
+        return false;
+    }
+
+    // Строковое представление может быть изменено в разных средах выполнения
+    // или при минификации кода, поэтому проводим дополнительную проверку.
+    return !Object.getOwnPropertyDescriptor(value, 'prototype')?.writable;
+}

package/src/helpers/is_float.mjs

@@ -0,0 +1,67 @@
+/**
+ * Проверяет, является ли значение числом с плавающей точкой.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Значение для проверки.
+ *
+ * ### Описание
+ *
+ * Функция `is_float` проверяет, является ли переданное значение числом с дробной частью, которое отличается от целого числа.
+ *
+ * Она работает следующим образом:
+ *
+ * 1. Проверяет, что значение имеет тип `number`.
+ * 2. Исключает значения `NaN`, которые также относятся к типу `number`, но не считаются числовыми значениями.
+ * 3. Проверяет, что у числа есть дробная часть, проверяя остаток от деления на `1` (`value % 1 !== 0`).
+ *
+ * Значения, которые не являются числами или числа без дробной части, не считаются числами с плавающей точкой.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значение является числом с плавающей точкой, иначе `false`.
+ *
+ * ### Примеры использования
+ *
+ * #### Числа с плавающей точкой
+ *
+ * ```js
+ * is_float(3.14);    // true
+ * is_float(-0.5);    // true
+ * is_float(0.1 + 0.2); // true
+ * ```
+ *
+ * #### Целые числа
+ *
+ * ```js
+ * is_float(0);       // false
+ * is_float(42);      // false
+ * is_float(-100);    // false
+ * ```
+ *
+ * #### Нечисловые значения
+ *
+ * ```js
+ * is_float('3.14');  // false
+ * is_float(NaN);     // false
+ * is_float(null);    // false
+ * is_float(undefined); // false
+ * is_float(true);    // false
+ * is_float({});      // false
+ * is_float([]);      // false
+ * ```
+ *
+ * #### Специальные значения
+ *
+ * ```js
+ * is_float(Infinity);   // false
+ * is_float(-Infinity);  // false
+ * ```
+ *
+ * @param {any} value Значение для проверки.
+ * @returns {boolean} Возвращает `true`, если значение является числом с плавающей точкой, иначе `false`.
+ */
+export default function is_float(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value % 1 !== 0;
+}

package/src/helpers/is_function.mjs

@@ -0,0 +1,74 @@
+/**
+ * Проверяет, что значение является функцией, исключая классы.
+ *
+ * ### Параметры
+ *
+ * - `value` (any):
+ *      Проверяемое значение. Может быть любым типом данных.
+ *
+ * ### Описание
+ *
+ * Функция проверяет, является ли переданное значение функцией, исключая классы.
+ * В JavaScript функции и классы оба являются типом `function`, но классы имеют особый синтаксис и поведение.
+ * Функция `is_function` различает их, проверяя, не начинается ли строковое представление функции с `class`, что указывает на то, что это класс, а не обычная функция.
+ * Если значение является функцией (но не классом), функция возвращает `true`.
+ * Для всех остальных типов данных (включая классы, объекты, примитивы) функция возвращает `false`.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если переданное значение является функцией (но не классом).
+ * Возвращает `false`, если переданное значение является классом или любым другим типом данных.
+ *
+ * ### Примеры использования
+ *
+ * Пример 1: обычная функция
+ *
+ * ```js
+ * function test() {}
+ * is_function(test); // Возвращает: true
+ * ```
+ *
+ * Пример 2: класс
+ *
+ * ```js
+ * class MyClass {}
+ * is_function(MyClass); // Возвращает: false
+ * ```
+ *
+ * Пример 3: объект
+ *
+ * ```js
+ * const obj = {};
+ * is_function(obj); // Возвращает: false
+ * ```
+ *
+ * Пример 4: примитив
+ *
+ * ```js
+ * is_function(42); // Возвращает: false
+ * is_function('hello'); // Возвращает: false
+ * ```
+ *
+ * @param {any} value - Проверяемое значение.
+ * @returns {boolean} Возвращает `true`, если значение является функцией, иначе `false`.
+ */
+export default function is_function(value) {
+    // Проверяем, является ли значение функцией
+    if (typeof value !== 'function') {
+        return false;
+    }
+
+    // Проверяем, не является ли значение классом, используя строковое представление функции
+    if (typeof value.toString === 'function') {
+        return !/^class\s/.test(value.toString());
+    }
+
+    // Если у функции нет прототипа, значит это стрелочная функция или метод
+    if (!value.prototype) {
+        return true;
+    }
+
+    // Строковое представление может быть изменено в разных средах выполнения
+    // или при минификации кода, поэтому проводим дополнительную проверку.
+    return Boolean(Object.getOwnPropertyDescriptor(value, 'prototype')?.writable);
+}

package/src/helpers/is_infinity.mjs

@@ -0,0 +1,52 @@
+/**
+ * Проверяет, является ли значение бесконечностью (Infinity или -Infinity).
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Значение, которое необходимо проверить.
+ *
+ * ### Описание
+ *
+ * Функция `is_infinity` проверяет, является ли переданное значение бесконечностью (Infinity или -Infinity).
+ *
+ * Она проверяет, равно ли значение `Number.POSITIVE_INFINITY` или `Number.NEGATIVE_INFINITY`.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значение является бесконечностью, и `false` в противном случае.
+ *
+ * ### Примеры использования
+ *
+ * #### Пример 1: Проверка значения Infinity
+ *
+ * ```js
+ * is_infinity(Infinity); // true
+ * is_infinity(-Infinity); // true
+ * ```
+ *
+ * #### Пример 2: Проверка числовых значений
+ *
+ * ```js
+ * is_infinity(42); // false
+ * is_infinity(3.14); // false
+ * is_infinity(NaN); // false
+ * ```
+ *
+ * #### Пример 3: Проверка значений других типов
+ *
+ * ```js
+ * is_infinity('Infinity'); // false (строка)
+ * is_infinity(true); // false (логическое значение)
+ * is_infinity(null); // false
+ * is_infinity(undefined); // false
+ * is_infinity({}); // false (объект)
+ * is_infinity([]); // false (массив)
+ * ```
+ *
+ * @param {any} value Значение, которое необходимо проверить.
+ * @returns {boolean} Возвращает `true`, если значение является бесконечностью, и `false` в противном случае.
+ */
+export default function is_infinity(value) {
+    return value === Number.POSITIVE_INFINITY || value === Number.NEGATIVE_INFINITY;
+}

package/src/helpers/is_int.mjs

@@ -0,0 +1,57 @@
+/**
+ * Проверяет, является ли значение целым числом.
+ *
+ * ### Параметры
+ *
+ * - `value` (any)
+ *      Значение, которое нужно проверить.
+ *
+ * ### Описание
+ *
+ * Функция `is_int` определяет, является ли переданное значение целым числом.
+ *
+ * Она выполняет следующие проверки:
+ *
+ * 1. **Тип значения**: Убеждается, что `value` имеет тип `number`.
+ * 2. **Конечность числа**: Проверяет, что значение не является `Infinity` или `NaN` с помощью `Number.isFinite(value)`.
+ * 3. **Целочисленность**: Убедится, что остаток от деления числа на 1 равен нулю (`value % 1 === 0`).
+ *
+ * Если значение соответствует всем этим условиям, оно считается целым числом.
+ *
+ * ### Возвращаемое значение
+ *
+ * Возвращает `true`, если значение является целым числом, иначе `false`.
+ *
+ * ### Примеры использования
+ *
+ * ```js
+ * // Проверка целых чисел
+ * is_int(42);       // true
+ * is_int(0);        // true
+ * is_int(-123);     // true
+ *
+ * // Проверка дробных чисел
+ * is_int(3.14);     // false
+ * is_int(-0.001);   // false
+ *
+ * // Некорректные типы данных
+ * is_int('42');     // false (строка)
+ * is_int(true);     // false (логическое значение)
+ * is_int(null);     // false (null)
+ * is_int(undefined);// false (undefined)
+ *
+ * // Бесконечные и некорректные числовые значения
+ * is_int(Infinity); // false (бесконечность)
+ * is_int(-Infinity);// false (отрицательная бесконечность)
+ * is_int(NaN);      // false (не число)
+ *
+ * // Проверка типа bigint
+ * is_int(BigInt(123456)); // false
+ * ```
+ *
+ * @param {any} value Значение для проверки.
+ * @returns {boolean} Возвращает `true`, если значение является целым числом, иначе `false`.
+ */
+export default function is_int(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value % 1 === 0;
+}