## @e22m4u/js-data-schema

JavaScript модуль для работы со схемой данных.

## Содержание

- [Установка](#установка)
- [Схема данных](#схема-данных)
- [Использование](#использование)
  - [Проверка данных](#проверка-данных)
  - [Парсинг данных](#парсинг-данных)
- [Пустые значения](#пустые-значения)
- [Тесты](#тесты)
- [Лицензия](#лицензия)

## Установка

```bash
npm install @e22m4u/js-data-schema
```

Модуль поддерживает ESM и CommonJS стандарты.

*ESM*

```js
import {DataValidator} from '@e22m4u/js-data-schema';
```

*CommonJS*

```js
const {DataValidator} = require('@e22m4u/js-data-schema');
```

### Схема данных

Схема данных позволяет указать допустимый тип значения, схему элементов
массива и схему свойств объекта. Схему можно использовать для проверки
входящих данных или для их преобразования к формату схемы.

Свойства схемы:

- `type` тип данных (допускает [пустые значения](#пустые-значения));
- `items` схема элементов массива, фабрика или имя схемы;
- `properties` схема свойств объекта, фабрика или имя схемы;
- `required` исключает *пустые значения*;

#### type

Параметр `type` определяет тип данных. При определении схемы можно использовать
константу или название типа в виде строки. Константы проверяются редакторами
кода, что позволяет избежать опечаток при вводе типа.

| константа          | значение    |
|--------------------|-------------|
| `DataType.ANY`     | `"any"`     |
| `DataType.STRING`  | `"string"`  |
| `DataType.NUMBER`  | `"number"`  |
| `DataType.BOOLEAN` | `"boolean"` |
| `DataType.ARRAY`   | `"array"`   |
| `DataType.OBJECT`  | `"object"`  |

#### items

Параметр `items` позволяет указать схему для элементов массива. Параметр можно
использовать только если явно указан тип `array`. В примере ниже схема массива
включает описание его элементов, которые должны соответствовать числовому типу.

```js
{
  type: DataType.ARRAY,
  items: {
    type: DataType.NUMBER
  }
}
// [-1, 0, 1, undefined, null]
```

Так как типы допускают [пустые значения](#пустые-значения), рекомендуется
использовать параметр `required` в определении схемы элемента, чтобы исключить
их из возможных значений массива.

```js
{
  type: DataType.ARRAY,
  items: {
    type: DataType.NUMBER,
    required: true // исключает undefined, null и 0
  }
}
// [-1, 1]
```

#### properties

Параметр `properties` позволяет указать схему каждого свойства объекта.
Параметр можно использовать, только если явно указан тип `object`. В примере
ниже используется схема объекта с двумя свойствами.

```js
{
  type: DataType.OBJECT,
  properties: {
    name: {
      type: DataType.STRING
    },
    age: {
      type: DataType.NUMBER
    }
  }
}
// {
//   "name": "John",
//   "age": 27
// }
```

Значения свойств могут быть обязательными. Для этого используется
параметр `required` в схеме соответствующего свойства. Если параметр
указан, то [пустые значения](#пустые-значения) будут вызывать ошибку
при проверке данного свойства.

```js
{
  type: DataType.OBJECT,
  properties: {
    name: {
      type: DataType.STRING,
      required: true // исключает undefined, null и ""
    },
    age: {
      type: DataType.NUMBER,
      required: true // исключает undefined, null и 0
    }
  }
}
```

#### required

Так как по умолчанию все типы допускают [пустые значения](#пустые-значения),
параметр `required` используется чтобы явно запретить такие значения
при проверке. Параметр можно использовать там, где указывается тип данных.

```js
{
  type: DataType.STRING, // допускает строки и пустые значения
  required: true         // исключает пустые значения
}
// "foo", "bar" ...
```

## Использование

Ниже приводятся примеры использования различных схем.

### Проверка данных

Проверка типа значения.

```js
import {DataValidator, DataType} from '@e22m4u/js-data-schema';

const validator = new DataValidator();

const schema = {
  type: DataType.STRING, // тип значения
};

// значение "str" соответствует схеме
validator.validate('str', schema); // OK

// undefined допускается (параметр "required" не указан)
validator.validate(undefined, schema); // OK

// 10 не является строкой
validator.validate(10, schema); // error: DataValidationError

// true не является строкой
validator.validate(true, schema); // error: DataValidationError
```

Проверка обязательного значения.

```js
import {DataValidator, DataType} from '@e22m4u/js-data-schema';

const validator = new DataValidator();

const schema = {
  type: DataType.NUMBER, // тип значения
  required: true,        // является обязательным
};

// значение 10 соответствует схеме
validator.validate(10, schema); // OK

// undefined не допускается (параметр "required")
validator.validate(undefined, schema); // error: DataValidationError

// 'str' не является числом
validator.validate('str', schema); // error: DataValidationError

// true не является числом
validator.validate(true, schema); // error: DataValidationError
```

Проверка элементов массива.

```js
import {DataValidator, DataType} from '@e22m4u/js-data-schema';

const validator = new DataValidator();

const schema = {
  type: DataType.ARRAY, // тип значения
  items: {
    type: DataType.NUMBER, // тип элемента
  },
};

// элементы массива соответствуют схеме
validator.validate([1, 2, 3], schema); // OK

// пустой массив также допускается
validator.validate([], schema); // OK

// 'str' не является массивом
validator.validate('str', schema); // error: DataValidationError

// элементы массива не соответствуют схеме (параметр "items")
validator.validate(['a', 'b'], schema); // error: DataValidationError

// объект не является массивом
validator.validate({foo: 'bar'}, schema); // error: DataValidationError
```

Проверка свойств объекта.

```js
import {DataValidator, DataType} from '@e22m4u/js-data-schema';

const validator = new DataValidator();

const schema = {
  type: DataType.OBJECT, // тип значения
  properties: {
    foo: { // схема свойства "foo"
      type: DataType.STRING, // тип свойства
      required: true,        // является обязательным
    },
    bar: { // схема свойства "bar"
      type: DataType.NUMBER, // тип свойства
    },
  },
};

// свойства объекта соответствуют схеме
validator.validate({foo: 'str', bar: 10}, schema); // OK

// обязательное свойство "foo" присутствует
validator.validate({foo: 'str'}, schema); // OK

// значение свойства "foo" не является строкой
validator.validate({foo: true}, schema); // error: DataValidationError

// массив не является объектом
validator.validate([1, 2, 3], schema); // error: DataValidationError
```

### Парсинг данных

Приведение типа согласно схеме.

```js
import {DataParser, DataType} from '@e22m4u/js-data-schema';

const parser = new DataParser();

const schema = {
  type: DataType.NUMBER, // тип значения
};

// приведение строки к числу
const result = parser.parse('10', schema);
console.log(result); // 10

// строка не является числом
parser.parse('10abc', schema); // error: DataParsingError
```

Разбор JSON строки согласно схеме массива.

```js
import {DataParser, DataType} from '@e22m4u/js-data-schema';

const parser = new DataParser();

const schema = {
  type: DataType.ARRAY, // тип значения
  items: {
    type: DataType.NUMBER, // тип элемента
  },
};

// приведение строки к массиву
const result = parser.parse('[1, 2, 3]', schema);
console.log(result);
// [1, 2, 3]

// элементы массива не соответствуют схеме
parser.parse('["str", true]', schema); // error: DataParsingError
```

Разбор JSON строки согласно схеме объекта.

```js
import {DataParser, DataType} from '@e22m4u/js-data-schema';

const parser = new DataParser();

const schema = {
  type: DataType.OBJECT, // тип значения
  properties: {
    foo: { // схема свойства "foo"
      type: DataType.STRING, // тип свойства
      required: true,        // является обязательным
    },
    bar: { // схема свойства "bar"
      type: DataType.NUMBER, // тип свойства
    },
  },
};

// приведение строки к объекту
const result = parser.parse(
  '{"foo": "str", "bar": 10}',
  schema,
);
console.log(result);
// {
//   "foo": "str",
//   "bar": 10
// }

// обязательное свойство "foo" отсутствует
parser.parse('{"bar": 10}', schema); // error: DataParsingError

// значение свойства "foo" не является строкой
parser.parse('{"foo": 10}', schema); // error: DataParsingError
```

## Пустые значения

Разные типы данных имеют свои наборы пустых значений. Эти наборы используются
для определения наличия полезной нагрузки в значении свойства. Например,
параметр `required` исключает пустые значения при проверке данных. 

| тип данных         | пустые значения            |
|--------------------|----------------------------|
| `DataType.ANY`     | *значения остальных типов* |
| `DataType.STRING`  | `undefined`, `null`, `""`  |
| `DataType.NUMBER`  | `undefined`, `null`, `0`   |
| `DataType.BOOLEAN` | `undefined`, `null`        |
| `DataType.ARRAY`   | `undefined`, `null`, `[]`  |
| `DataType.OBJECT`  | `undefined`, `null`, `{}`  |

Управление этими наборами осуществляется через специальный сервис, который предоставляет модуль
[@e22m4u/js-empty-values](https://www.npmjs.com/package/@e22m4u/js-empty-values)
(не требует установки).

## Тесты

```bash
npm run test
```

## Лицензия

MIT