@rogolev/value 0.0.1

package/.prettierignore

@@ -0,0 +1,4 @@
+**/.git
+**/.svn
+**/.hg
+**/node_modules

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# v0.0.1
+
+## Добавлено
+
+### Помощники для работы с типами данных
+
+- [array](./docs/helpers/array.md) — Создаёт массив из переданных значений, обрабатывая
+  ассоциативные массивы (объекты с ключами).
+- [empty](./docs/helpers/empty.md) — Проверяет, является ли переменная пустой.
+- [gettype](./docs/helpers/gettype.md) — Определяет тип переданного значения.
+- [is_array](./docs/helpers/is_array.md) — Проверяет, является ли переданное значение массивом
+  или ассоциативным массивом (объектом с ключами и значениями).
+- [is_assoc](./docs/helpers/is_assoc.md) — Проверяет, является ли значение ассоциативным
+  массивом.
+- [is_bigint](./docs/helpers/is_bigint.md) — Проверяет, является ли значение типом `bigint`.
+- [is_bool](./docs/helpers/is_bool.md) — Проверяет, является ли переданное значение логическим
+  типом (`boolean`).
+- [is_boolean](./docs/helpers/is_boolean.md) — Проверяет, является ли переданное значение
+  логическим типом (`boolean`).
+- [is_class](./docs/helpers/is_class.md) — Проверяет, является ли переданная переменная
+  классом.
+- [is_float](./docs/helpers/is_float.md) — Проверяет, является ли значение числом с плавающей
+  точкой.
+- [is_function](./docs/helpers/is_function.md) — Проверяет, что значение является функцией,
+  исключая классы.
+- [is_infinity](./docs/helpers/is_infinity.md) — Проверяет, является ли значение
+  бесконечностью (Infinity или -Infinity).
+- [is_int](./docs/helpers/is_int.md) — Проверяет, является ли значение целым числом.
+- [is_integer](./docs/helpers/is_integer.md) — Проверяет, является ли значение целым числом.
+- [is_list](./docs/helpers/is_list.md) — Проверяет, является ли значение списком.
+- [is_nan](./docs/helpers/is_nan.md) — Проверяет, является ли значение NaN.
+- [is_null](./docs/helpers/is_null.md) — Проверяет, является ли значение `null`.
+- [is_number](./docs/helpers/is_number.md) — Проверяет, является ли значение числом.
+- [is_numeric](./docs/helpers/is_numeric.md) — Проверяет, является ли значение числом или
+  числовой строкой.
+- [is_object](./docs/helpers/is_object.md) — Проверяет, является ли переданная переменная
+  объектом, созданным с использованием класса.
+- [is_scalar](./docs/helpers/is_scalar.md) — Проверяет, является ли значение скалярным.
+- [is_string](./docs/helpers/is_string.md) — Проверяет, является ли значение строкой.
+- [is_symbol](./docs/helpers/is_symbol.md) — Проверяет, является ли значение символом.
+- [is_undefined](./docs/helpers/is_undefined.md) — Проверяет, является ли значение
+  `undefined`.
+- [print](./docs/helpers/print.md) — Преобразует значение в строку и выводит его на консоль.
+- [print_type](./docs/helpers/print_type.md) — Преобразует значение в строку с указанием типа
+  и выводит его на консоль.
+- [settype](./docs/helpers/settype.md) — Преобразует значение в указанный тип.
+- [to_array](./docs/helpers/to_array.md) — Преобразует значение в массив.
+- [to_assoc](./docs/helpers/to_assoc.md) — Преобразует значение в ассоциативный массив.
+- [to_bool](./docs/helpers/to_bool.md) — Преобразует значение в логическое значение.
+- [to_boolean](./docs/helpers/to_bool.md) — Преобразует значение в логическое значение.
+- [to_float](./docs/helpers/to_float.md) — Преобразует значение в число с плавающей точкой.
+- [to_int](./docs/helpers/to_int.md) — Преобразует значение в целое число.
+- [to_integer](./docs/helpers/to_integer.md) — Преобразует значение в целое число.
+- [to_list](./docs/helpers/to_list.md) — Преобразует значение в список.
+- [to_object](./docs/helpers/to_object.md) — Преобразует значение в объект.
+- [to_string](./docs/helpers/to_string.md) — Преобразует значение в строку.

package/LICENSE

@@ -0,0 +1,41 @@
+MIT License
+
+Copyright (c) 2025 Роголев Дмитрий Александрович
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+# Перевод
+
+Лицензия MIT
+
+Авторское право (c) 2025 Роголев Дмитрий Александрович
+
+Настоящим предоставляется бесплатное разрешение любому лицу, получившему копию данного программного
+обеспечения и сопутствующей документации (в дальнейшем "Программное обеспечение"), использовать
+Программное обеспечение без ограничений, включая неограниченное право на использование, копирование,
+изменение, слияние, публикацию, распространение, сублицензирование и/или продажу копий Программного
+обеспечения, а также лицам, которым предоставляется данное Программное обеспечение, при соблюдении
+следующих условий:
+
+Вышеуказанное уведомление об авторских правах и данное разрешение должны быть включены во все копии
+или значимые части данного Программного обеспечения.
+
+ДАННОЕ ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ "КАК ЕСТЬ", БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ
+ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ГАРАНТИЯМИ ТОВАРНОЙ ПРИГОДНОСТИ, ПРИГОДНОСТИ ДЛЯ
+ОПРЕДЕЛЕННОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ. НИ В КОЕМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ
+ОТВЕТСТВЕННОСТИ ЗА КАКИЕ-ЛИБО ИСКИ, УЩЕРБ ИЛИ ДРУГИЕ ОБЯЗАТЕЛЬСТВА, НЕЗАВИСИМО ОТ ДЕЙСТВИЯ ДОГОВОРА,
+ДЕЛИКТА ИЛИ ИНАЧЕ, ВОЗНИКШИЕ ИЗ, ИЛИ В СВЯЗИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ИСПОЛЬЗОВАНИЕМ ИЛИ ИНЫМИ
+ДЕЙСТВИЯМИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.

package/README.md

@@ -0,0 +1,91 @@
+# value.js
+
+**value.js** — Библиотека для **JavaScript**, переосмысливающая типы данных и работу с ними.
+
+## Документация
+
+[Типы данных в value.js](./docs/types.md).
+
+[Помощники для работы с типами данных value.js](./docs/helpers.md)
+
+## Примеры использования
+
+```js
+import {
+    array,
+    is_array,
+    is_object,
+    is_class,
+    is_function,
+    is_int,
+    is_float,
+    gettype,
+} from '@rogolev/value.js';
+
+// Создаем ассоциативный массив - контейнер пар ключ-значение
+const assoc = array({ key1: 'value1', key2: 'value2', key3: 'value3' });
+
+console.log(assoc); // {key1: 'value1', key2: 'value2', key3: 'value3'}
+
+// Ассоциативные массивы создаются с помощью конструкции Object.create(null)
+console.log(Object.getPrototypeOf(assoc)); // null
+
+// Функция array добавляет итератор Symbol.iterator к ассоциативным массивам
+for (const [key, value] of assoc) {
+    console.log(key, value);
+}
+
+// Ассоциативные массивы являются массивами
+console.log(is_array(assoc)); // true
+
+// Списки являются массивами
+console.log(is_array([1, 2, 3])); // true
+
+class stdClass {}
+function MyFunction() {}
+
+const object = new stdClass();
+const objFunc = new MyFunction();
+
+// Экземпляры классов не являются массивами
+console.log(is_array(object)); // false
+
+// Экземпляр класса является объектом
+console.log(is_object(object)); // true
+
+// Экземпляр функции не является объектом
+console.log(is_object(objFunc)); // false
+
+// Класс является классом
+console.log(is_class(stdClass)); // true
+
+// Функция не является классом
+console.log(is_class(MyFunction)); // false
+
+// Функция является функцией
+console.log(is_function(MyFunction)); // true
+
+// Класс не является функцией
+console.log(is_function(stdClass)); // false
+
+// Целое число
+console.log(is_int(3)); // true
+
+// Число с плавающей точкой
+console.log(is_float(3.14)); // true
+
+// Получение типа
+console.log(gettype(stdClass)); // "class"
+```
+
+## Автор
+
+Роголев Дмитрий Александрович
+
+<drogolev@internet.ru>
+
+<https://github.com/dmitry-rogolev>
+
+## Лицензия
+
+Этот проект лицензируется на условиях лицензии MIT. Подробности см. в файле [LICENSE](./LICENSE).

package/babel.config.json

@@ -0,0 +1,20 @@
+{
+    "presets": [
+        [
+            "@babel/preset-env",
+            {
+                // Настройка целевых браузеров
+                "targets": "> 0.25%, not dead",
+
+                // Автоматически добавлять полифилы, где это необходимо
+                "useBuiltIns": "usage",
+
+                // Использование core-js версии 3 для полифилов
+                "corejs": 3,
+
+                // Преобразование модулей ES6 в CommonJS
+                "modules": "commonjs"
+            }
+        ]
+    ]
+}

package/docs/helpers/array.md

@@ -0,0 +1,80 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / array
+
+[Исходный код](../../src/helpers/array.mjs)
+
+# array
+
+`array` — Создаёт массив из переданных значений, обрабатывая ассоциативные массивы (объекты с
+ключами).
+
+## Сигнатура функции
+
+```ts
+function array(...values: any[]): Array<any> | Object;
+```
+
+## Описание
+
+Функция принимает произвольное количество аргументов и возвращает массив, содержащий переданные
+значения. Если среди переданных значений есть ассоциативные массивы (объекты, не являющиеся
+массивами и с ненулевым прототипом), они преобразуются:
+
+- Создаётся новый объект без прототипа.
+- Добавляются все свойства исходного объекта.
+- Добавляется итератор, позволяющий использовать объект в цикле `for-of` для получения пар
+  `[ключ, значение]`.
+
+Если передано только одно значение, и это массив, функция возвращает его напрямую.
+
+## Параметры
+
+- `values` (any[])
+
+    Один или несколько элементов, которые могут быть массивами, объектами или другими значениями.
+
+## Возвращаемое значение
+
+Массив, содержащий переданные значения, с преобразованием ассоциативных массивов. Если передано одно
+значение и это массив, возвращается он сам.
+
+## Примеры использования
+
+1. Простые массивы:
+
+    ```js
+    const result = array([1, 2, 3]);
+    console.log(result); // [1, 2, 3]
+    ```
+
+2. Ассоциативные массивы (объекты с ключами и значениями):
+
+    ```js
+    const result = array({ foo: 'bar', baz: 42 });
+    for (const [key, value] of result[0]) {
+        console.log(key, value);
+    }
+    // Вывод:
+    // foo bar
+    // baz 42
+    ```
+
+3. Смешанные значения:
+
+    ```js
+    const result = array([1, 2, 3], { foo: 'bar' }, 'hello');
+    console.log(result);
+    // Вывод: [[1, 2, 3], { foo: 'bar' }, 'hello']
+    ```
+
+4. Объекты, созданные без прототипа:
+
+    ```js
+    const noProtoObject = Object.create(null);
+    noProtoObject.foo = 'bar';
+    const result = array(noProtoObject);
+    for (const [key, value] of result[0]) {
+        console.log(key, value);
+    }
+    // Вывод:
+    // foo bar
+    ```

package/docs/helpers/empty.md

@@ -0,0 +1,77 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / empty
+
+[Исходный код](../../src/helpers/empty.mjs)
+
+# `empty`
+
+`empty` — Проверяет, является ли переменная пустой.
+
+## Сигнатура функции
+
+```ts
+function empty(value: any): boolean;
+```
+
+## Описание
+
+Функция `empty` используется для проверки, является ли переменная пустой. Пустыми считаются значения
+`null`, `undefined`, пустая строка, `0`, `false`, пустой массив и пустой объект (ассоциативный
+массив).
+
+## Параметры
+
+- `value` (any)
+
+    Переменная, которую необходимо проверить на пустоту.
+
+## Возвращаемое значение
+
+Функция возвращает:
+
+- `true`, если переменная пустая, и `false` в противном случае.
+
+## Примеры использования
+
+### Пример 1: Проверка пустых значений
+
+```js
+const result1 = empty(null);
+// Результат: true
+
+const result2 = empty(undefined);
+// Результат: true
+
+const result3 = empty('');
+// Результат: true
+
+const result4 = empty(0);
+// Результат: true
+
+const result5 = empty(false);
+// Результат: true
+
+const result6 = empty([]);
+// Результат: true
+
+const result7 = empty({});
+// Результат: true
+```
+
+### Пример 2: Проверка непустых значений
+
+```js
+const result1 = empty('example');
+// Результат: false
+
+const result2 = empty(123);
+// Результат: false
+
+const result3 = empty(true);
+// Результат: false
+
+const result4 = empty([1, 2, 3]);
+// Результат: false
+
+const result5 = empty({ key: 'value' });
+// Результат: false
+```

package/docs/helpers/gettype.md

@@ -0,0 +1,69 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / gettype
+
+[Исходный код](../../src/helpers/gettype.mjs)
+
+# `gettype`
+
+`gettype` — Определяет тип переданного значения.
+
+## Сигнатура функции
+
+```ts
+function gettype(value: any): string;
+```
+
+## Параметры
+
+- `value` (any)
+
+    Значение, тип которого необходимо определить.
+
+## Описание
+
+Функция `gettype` определяет тип переданного значения, используя различные проверки.
+
+Она выполняет следующие проверки:
+
+1. **Null**: Проверяет, является ли значение `null`.
+2. **NaN**: Проверяет, является ли значение `NaN`.
+3. **Undefined**: Проверяет, является ли значение `undefined`.
+4. **Infinity**: Проверяет, является ли значение бесконечностью.
+5. **Boolean**: Проверяет, является ли значение логическим.
+6. **Integer**: Проверяет, является ли значение целым числом.
+7. **BigInt**: Проверяет, является ли значение типом BigInt.
+8. **Float**: Проверяет, является ли значение числом с плавающей точкой.
+9. **String**: Проверяет, является ли значение строкой.
+10. **Symbol**: Проверяет, является ли значение символом.
+11. **Class**: Проверяет, является ли значение классом.
+12. **Function**: Проверяет, является ли значение функцией.
+13. **Array**: Проверяет, является ли значение массивом.
+14. **Object**: Проверяет, является ли значение объектом.
+
+Если значение не соответствует ни одному из этих типов, функция возвращает результат `typeof value`.
+
+## Возвращаемое значение
+
+Функция возвращает строку, представляющую тип значения.
+
+## Примеры использования
+
+### Пример 1: Проверка различных типов значений
+
+```js
+class MyClass {}
+
+gettype(null); // "null"
+gettype(NaN); // "NaN"
+gettype(undefined); // "undefined"
+gettype(Infinity); // "infinity"
+gettype(true); // "boolean"
+gettype(42); // "integer"
+gettype(BigInt(123456)); // "bigint"
+gettype(3.14); // "float"
+gettype('hello'); // "string"
+gettype(Symbol('symbol')); // "symbol"
+gettype(MyClass); // "class"
+gettype(() => {}); // "function"
+gettype([]); // "array"
+gettype(new MyClass()); // "object"
+```

package/docs/helpers/is_array.md

@@ -0,0 +1,105 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / is_array
+
+[Исходный код](../../src/helpers/is_array.mjs)
+
+# is_array
+
+`is_array` — Проверяет, является ли переданное значение массивом или ассоциативным массивом
+(объектом с ключами и значениями).
+
+## Сигнатура функции
+
+```ts
+function is_array(value: any): boolean;
+```
+
+## Описание
+
+В 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
+    ```

package/docs/helpers/is_assoc.md

@@ -0,0 +1,59 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / is_assoc
+
+[Исходный код](../../src/helpers/is_assoc.mjs)
+
+# `is_assoc`
+
+`is_assoc` — Проверяет, является ли значение ассоциативным массивом.
+
+## Сигнатура функции
+
+```ts
+function is_assoc(value: any): boolean;
+```
+
+## Параметры
+
+- `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
+```

package/docs/helpers/is_bigint.md

@@ -0,0 +1,57 @@
+[Главная](../../README.md) / [Помощники](../helpers.md) / is_bigint
+
+[Исходный код](../../src/helpers/is_bigint.mjs)
+
+# `is_bigint`
+
+`is_bigint` — Проверяет, является ли значение типом `bigint`.
+
+## Сигнатура функции
+
+```ts
+function is_bigint(value: any): boolean;
+```
+
+## Параметры
+
+- `value` (any)
+
+    Значение, которое необходимо проверить на принадлежность к типу `bigint`.
+
+## Описание
+
+Функция `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 (массив)
+```