@rogolev/value 0.0.3 → 0.0.5

package/docs/helpers/expect_null.md

@@ -0,0 +1,63 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect_null
+
+[Исходный код](../../src/helpers/expect_null.mjs)
+
+# expect_null
+
+`expect_null` — Проверяет, является ли значение null, и выбрасывает ошибку с указанным
+сообщением, если это не так.
+
+## Сигнатура функции
+
+```ts
+function expect_null(value: any, message: string = ''): boolean;
+```
+
+## Описание
+
+Функция `expect_null` используется для проверки, является ли переданное значение null. Если значение
+не является null, функция выбрасывает ошибку типа `TypeError` с указанным сообщением.
+
+## Параметры
+
+- `value` (any): Значение для проверки.
+- `message` (string): Сообщение об ошибке, если значение не является null. По умолчанию пустая
+  строка.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является null.
+
+## Примеры использования
+
+1. Проверка значения, являющегося null:
+
+    ```js
+    const value = null;
+    const result = expect_null(value);
+    console.log(result); // true
+    ```
+
+2. Проверка значения, не являющегося null:
+
+    ```js
+    try {
+        const result = expect_null(123, 'Значение должно быть null.');
+    } catch (e) {
+        console.error(e.message); // Значение должно быть null.
+    }
+    ```
+
+3. Проверка значения с использованием пользовательского сообщения об ошибке:
+
+    ```js
+    try {
+        const result = expect_null('not null', 'Ожидалось значение null.');
+    } catch (e) {
+        console.error(e.message); // Ожидалось значение null.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не является null или если параметр `message` не является строкой.

package/docs/helpers/expect_number.md

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

package/docs/helpers/expect_numeric.md

@@ -0,0 +1,63 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect_numeric
+
+[Исходный код](../../src/helpers/expect_numeric.mjs)
+
+# expect_numeric
+
+`expect_numeric` — Проверяет, является ли значение числовым, и выбрасывает ошибку с указанным
+сообщением, если это не так.
+
+## Сигнатура функции
+
+```ts
+function expect_numeric(value: any, message: string = ''): boolean;
+```
+
+## Описание
+
+Функция `expect_numeric` используется для проверки, является ли переданное значение числовым. Если
+значение не является числовым, функция выбрасывает ошибку типа `TypeError` с указанным сообщением.
+
+## Параметры
+
+- `value` (any): Значение для проверки.
+- `message` (string): Сообщение об ошибке, если значение не является числовым. По умолчанию пустая
+  строка.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является числовым.
+
+## Примеры использования
+
+1. Проверка значения, являющегося числовым:
+
+    ```js
+    const value = '123';
+    const result = expect_numeric(value);
+    console.log(result); // true
+    ```
+
+2. Проверка значения, не являющегося числовым:
+
+    ```js
+    try {
+        const result = expect_numeric('abc', 'Значение должно быть числовым.');
+    } catch (e) {
+        console.error(e.message); // Значение должно быть числовым.
+    }
+    ```
+
+3. Проверка значения с использованием пользовательского сообщения об ошибке:
+
+    ```js
+    try {
+        const result = expect_numeric({}, 'Ожидалось числовое значение.');
+    } catch (e) {
+        console.error(e.message); // Ожидалось числовое значение.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не является числовым или если параметр `message` не является строкой.

package/docs/helpers/expect_object.md

@@ -0,0 +1,64 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect_object
+
+[Исходный код](../../src/helpers/expect_object.mjs)
+
+# expect_object
+
+`expect_object` — Проверяет, является ли значение объектом, и выбрасывает ошибку с указанным
+сообщением, если это не так.
+
+## Сигнатура функции
+
+```ts
+function expect_object(value: any, message: string = ''): boolean;
+```
+
+## Описание
+
+Функция `expect_object` используется для проверки, является ли переданное значение объектом. Если
+значение не является объектом, функция выбрасывает ошибку типа `TypeError` с указанным сообщением.
+
+## Параметры
+
+- `value` (any): Значение для проверки.
+- `message` (string): Сообщение об ошибке, если значение не является объектом. По умолчанию пустая
+  строка.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является объектом.
+
+## Примеры использования
+
+1. Проверка значения, являющегося объектом:
+
+    ```js
+    class stdClass {}
+    const value = new stdClass();
+    const result = expect_object(value);
+    console.log(result); // true
+    ```
+
+2. Проверка значения, не являющегося объектом:
+
+    ```js
+    try {
+        const result = expect_object(123, 'Значение должно быть объектом.');
+    } catch (e) {
+        console.error(e.message); // Значение должно быть объектом.
+    }
+    ```
+
+3. Проверка значения с использованием пользовательского сообщения об ошибке:
+
+    ```js
+    try {
+        const result = expect_object('not an object', 'Ожидался объект.');
+    } catch (e) {
+        console.error(e.message); // Ожидался объект.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не является объектом или если параметр `message` не является строкой.

package/docs/helpers/expect_scalar.md

@@ -0,0 +1,63 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect_scalar
+
+[Исходный код](../../src/helpers/expect_scalar.mjs)
+
+# expect_scalar
+
+`expect_scalar` — Проверяет, является ли значение скалярным, и выбрасывает ошибку с указанным
+сообщением, если это не так.
+
+## Сигнатура функции
+
+```ts
+function expect_scalar(value: any, message: string = ''): boolean;
+```
+
+## Описание
+
+Функция `expect_scalar` используется для проверки, является ли переданное значение скалярным. Если
+значение не является скалярным, функция выбрасывает ошибку типа `TypeError` с указанным сообщением.
+
+## Параметры
+
+- `value` (any): Значение для проверки.
+- `message` (string): Сообщение об ошибке, если значение не является скалярным. По умолчанию пустая
+  строка.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является скалярным.
+
+## Примеры использования
+
+1. Проверка значения, являющегося скалярным:
+
+    ```js
+    const value = 123;
+    const result = expect_scalar(value);
+    console.log(result); // true
+    ```
+
+2. Проверка значения, не являющегося скалярным:
+
+    ```js
+    try {
+        const result = expect_scalar([1, 2, 3], 'Значение должно быть скалярным.');
+    } catch (e) {
+        console.error(e.message); // Значение должно быть скалярным.
+    }
+    ```
+
+3. Проверка значения с использованием пользовательского сообщения об ошибке:
+
+    ```js
+    try {
+        const result = expect_scalar({}, 'Ожидалось скалярное значение.');
+    } catch (e) {
+        console.error(e.message); // Ожидалось скалярное значение.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не является скалярным или если параметр `message` не является строкой.

package/docs/helpers/expect_string.md

@@ -0,0 +1,63 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect_string
+
+[Исходный код](../../src/helpers/expect_string.mjs)
+
+# expect_string
+
+`expect_string` — Проверяет, является ли значение строкой, и выбрасывает ошибку с указанным
+сообщением, если это не так.
+
+## Сигнатура функции
+
+```ts
+function expect_string(value: any, message: string = ''): boolean;
+```
+
+## Описание
+
+Функция `expect_string` используется для проверки, является ли переданное значение строкой. Если
+значение не является строкой, функция выбрасывает ошибку типа `TypeError` с указанным сообщением.
+
+## Параметры
+
+- `value` (any): Значение для проверки.
+- `message` (string): Сообщение об ошибке, если значение не является строкой. По умолчанию пустая
+  строка.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является строкой.
+
+## Примеры использования
+
+1. Проверка значения, являющегося строкой:
+
+    ```js
+    const value = 'Hello, world!';
+    const result = expect_string(value);
+    console.log(result); // true
+    ```
+
+2. Проверка значения, не являющегося строкой:
+
+    ```js
+    try {
+        const result = expect_string(123, 'Значение должно быть строкой.');
+    } catch (e) {
+        console.error(e.message); // Значение должно быть строкой.
+    }
+    ```
+
+3. Проверка значения с использованием пользовательского сообщения об ошибке:
+
+    ```js
+    try {
+        const result = expect_string({}, 'Ожидалась строка.');
+    } catch (e) {
+        console.error(e.message); // Ожидалась строка.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не является строкой или если параметр `message` не является строкой.

package/docs/helpers/expect_symbol.md

@@ -0,0 +1,63 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect_symbol
+
+[Исходный код](../../src/helpers/expect_symbol.mjs)
+
+# expect_symbol
+
+`expect_symbol` — Проверяет, является ли значение символом, и выбрасывает ошибку с указанным
+сообщением, если это не так.
+
+## Сигнатура функции
+
+```ts
+function expect_symbol(value: any, message: string = ''): boolean;
+```
+
+## Описание
+
+Функция `expect_symbol` используется для проверки, является ли переданное значение символом. Если
+значение не является символом, функция выбрасывает ошибку типа `TypeError` с указанным сообщением.
+
+## Параметры
+
+- `value` (any): Значение для проверки.
+- `message` (string): Сообщение об ошибке, если значение не является символом. По умолчанию пустая
+  строка.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является символом.
+
+## Примеры использования
+
+1. Проверка значения, являющегося символом:
+
+    ```js
+    const value = Symbol('example');
+    const result = expect_symbol(value);
+    console.log(result); // true
+    ```
+
+2. Проверка значения, не являющегося символом:
+
+    ```js
+    try {
+        const result = expect_symbol('not a symbol', 'Значение должно быть символом.');
+    } catch (e) {
+        console.error(e.message); // Значение должно быть символом.
+    }
+    ```
+
+3. Проверка значения с использованием пользовательского сообщения об ошибке:
+
+    ```js
+    try {
+        const result = expect_symbol(123, 'Ожидался символ.');
+    } catch (e) {
+        console.error(e.message); // Ожидался символ.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не является символом или если параметр `message` не является строкой.

package/docs/helpers/expect_undefined.md

@@ -0,0 +1,64 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / expect_undefined
+
+[Исходный код](../../src/helpers/expect_undefined.mjs)
+
+# expect_undefined
+
+`expect_undefined` — Проверяет, является ли значение undefined, и выбрасывает ошибку с
+указанным сообщением, если это не так.
+
+## Сигнатура функции
+
+```ts
+function expect_undefined(value: any, message: string = ''): boolean;
+```
+
+## Описание
+
+Функция `expect_undefined` используется для проверки, является ли переданное значение undefined.
+Если значение не является undefined, функция выбрасывает ошибку типа `TypeError` с указанным
+сообщением.
+
+## Параметры
+
+- `value` (any): Значение для проверки.
+- `message` (string): Сообщение об ошибке, если значение не является undefined. По умолчанию пустая
+  строка.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является undefined.
+
+## Примеры использования
+
+1. Проверка значения, являющегося undefined:
+
+    ```js
+    let value;
+    const result = expect_undefined(value);
+    console.log(result); // true
+    ```
+
+2. Проверка значения, не являющегося undefined:
+
+    ```js
+    try {
+        const result = expect_undefined(123, 'Значение должно быть undefined.');
+    } catch (e) {
+        console.error(e.message); // Значение должно быть undefined.
+    }
+    ```
+
+3. Проверка значения с использованием пользовательского сообщения об ошибке:
+
+    ```js
+    try {
+        const result = expect_undefined('not undefined', 'Ожидалось значение undefined.');
+    } catch (e) {
+        console.error(e.message); // Ожидалось значение undefined.
+    }
+    ```
+
+## Исключения
+
+- `TypeError`: Если значение не является undefined или если параметр `message` не является строкой.

package/docs/helpers/is_char.md

@@ -0,0 +1,84 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / is_char
+
+[Исходный код](../../src/helpers/is_char.mjs)
+
+# is_char
+
+`is_char` — Проверяет, является ли значение одиночным символом.
+
+## Сигнатура функции
+
+```ts
+function is_char(value: string): boolean;
+```
+
+## Описание
+
+Функция `is_char` используется для проверки, является ли переданное значение одиночным символом.
+Значение считается одиночным символом, если оно является строкой длиной в один символ.
+
+## Параметры
+
+- `value` (string): Значение для проверки.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значение является одиночным символом, иначе `false`.
+
+## Примеры использования
+
+1. Проверка одиночного символа:
+
+    ```js
+    const result = is_char('a');
+    console.log(result); // true
+    ```
+
+2. Проверка строки из нескольких символов:
+
+    ```js
+    const result = is_char('abc');
+    console.log(result); // false
+    ```
+
+3. Проверка пустой строки:
+
+    ```js
+    const result = is_char('');
+    console.log(result); // false
+    ```
+
+4. Проверка значения, не являющегося строкой:
+
+    ```js
+    const result = is_char(1);
+    console.log(result); // false
+    ```
+
+5. Проверка пробельного символа:
+
+    ```js
+    const result = is_char(' ');
+    console.log(result); // true
+    ```
+
+6. Проверка строки с пробелами:
+
+    ```js
+    const result = is_char(' a ');
+    console.log(result); // false
+    ```
+
+7. Проверка строки с числовыми значениями:
+
+    ```js
+    const result = is_char('123');
+    console.log(result); // false
+    ```
+
+8. Проверка одиночного числового символа:
+
+    ```js
+    const result = is_char('1');
+    console.log(result); // true
+    ```

package/docs/helpers/is_equal.md

@@ -0,0 +1,75 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / is_equal
+
+[Исходный код](../../src/helpers/is_equal.mjs)
+
+# is_equal
+
+`is_equal` — Проверяет, являются ли два значения равными.
+
+## Сигнатура функции
+
+```ts
+function is_equal(actual: any, expected: any, strict: boolean = false): boolean;
+```
+
+## Описание
+
+Функция `is_equal` используется для проверки равенства двух значений. Она поддерживает сравнение
+примитивных типов данных, а также объектов и массивов. Для объектов и массивов функция рекурсивно
+сравнивает их ключи и значения. Функция также поддерживает строгий режим сравнения, который
+учитывает типы значений.
+
+## Параметры
+
+- `actual` (any): Первое значение для сравнения.
+- `expected` (any): Второе значение для сравнения.
+- `strict` (boolean): Флаг строгого сравнения. По умолчанию `false`.
+
+## Возвращаемое значение
+
+Возвращает `true`, если значения равны, иначе `false`.
+
+## Примеры использования
+
+1. Проверка равенства чисел:
+
+    ```js
+    const result = is_equal(1, 1);
+    console.log(result); // true
+    ```
+
+2. Проверка равенства строк:
+
+    ```js
+    const result = is_equal('hello', 'hello');
+    console.log(result); // true
+    ```
+
+3. Проверка равенства объектов:
+
+    ```js
+    const obj1 = { a: 1, b: 2 };
+    const obj2 = { a: 1, b: 2 };
+    const result = is_equal(obj1, obj2);
+    console.log(result); // true
+    ```
+
+4. Проверка равенства массивов:
+
+    ```js
+    const arr1 = [1, 2, 3];
+    const arr2 = [1, 2, 3];
+    const result = is_equal(arr1, arr2);
+    console.log(result); // true
+    ```
+
+5. Проверка равенства с использованием строгого сравнения:
+
+    ```js
+    const result = is_equal(1, '1', true);
+    console.log(result); // false
+    ```
+
+## Исключения
+
+- `TypeError`: Если значения не являются объектами или массивами.