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();

// значение "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

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

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

const validator = new DataValidator();

// определение схемы
const schema = {
  type: DataType.NUMBER, // только числа
  required: true,        // <= исключает undefined, null
};

// значение 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

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

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

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

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

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

Приведение типа данных.

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: { // схема свойства "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 исключает пустые значения при проверке данных.

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

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

Тесты

npm run test

Лицензия

MIT