js-data-schema/README.md

@e22m4u/js-data-schema

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

Содержание

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

Установка

npm install @e22m4u/js-data-schema

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

ESM

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

CommonJS

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

Схема данных

Структура:

{
  type?: DataType;
  items?: DataSchemaObject | DataSchemaFactory | string;
  properties?: DataSchemaProperties | DataSchemaFactory | string;
  required?: boolean;
}

type

Параметр type определяет тип допустимых значений.

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

items

Параметр items позволяет указать схему для элементов массива. Параметр можно использовать, только если явно указан тип array текущей схемы.

{
  type: DataType.ARRAY,
  items: {
    type: DataType.NUMBER
  }
}
// [1, 2, 3]

properties

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

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

required

Параметр required позволяет запретить пустые значения.

{
  type: DataType.STRING,
  required: true
}
// запрещает '', undefined и null
// см. раздел «Пустые значения»

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

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

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

Проверка примитивных значений.

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

const schema = {
  type: DataType.STRING
};

const validator = new DataValidator();
validator.validate('str', schema); // OK
validator.validate(undefined, schema); // OK (пустое значение)

validator.validate(10, schema); // error: DataValidationError
validator.validate(true, schema); // error: DataValidationError

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

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

const schema = {
  type: DataType.NUMBER,
  required: true, // <= исключает 0, undefined и null (для типа number)
};

const validator = new DataValidator();
validator.validate(10, schema); // OK

validator.validate('str', schema); // error: DataValidationError
validator.validate(0, schema); // error: DataValidationError
validator.validate(true, schema); // error: DataValidationError

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

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

const schema = {
  type: DataType.ARRAY,
  items: {
    type: DataType.NUMBER,
  },
};

const validator = new DataValidator();
validator.validate([1, 2, 3], schema); // OK
validator.validate([], schema); // OK

validator.validate('str', schema); // error: DataValidationError
validator.validate(['a', 'b'], schema); // error: DataValidationError
validator.validate({foo: 'bar'}, schema); // error: DataValidationError

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

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

const schema = {
  type: DataType.OBJECT,
  properties: {
    foo: {
      type: DataType.STRING,
    },
    bar: {
      type: DataType.NUMBER,
    },
  },
};

const validator = new DataValidator();
validator.validate({foo: 'str', bar: 10}, schema); // OK
validator.validate({}, schema); // OK

validator.validate({foo: true}, schema); // error: DataValidationError
validator.validate([1, 2, 3], schema); // error: DataValidationError

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

Приведение строки к числу.

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 строки согласно схеме массива.

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 строки согласно схеме объекта.

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

const parser = new DataParser();

const schema = {
  type: DataType.OBJECT,
  properties: {
    foo: {
      type: DataType.STRING,
    },
    bar: {
      type: DataType.NUMBER,
    },
  },
};

const result = parser.parse(
  '{"foo": "str", "bar": 10}',
  schema,
);
console.log(result);
// {
//   "foo": "str",
//   "bar": 10
// }

// значения полей не соответствуют схеме
parser.parse('{"foo": true, "bar": "str"}', schema); // error: DataParsingError

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

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

тип	пустые значения
'any'	undefined, null
'string'	undefined, null, ''
'number'	undefined, null, 0
'boolean'	undefined, null
'array'	undefined, null, []
'object'	undefined, null, {}

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

Тесты

npm run test

Лицензия

MIT