js-data-schema

@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 тип данных (допускает пустые значения);
• items схема элементов массива, фабрика или имя схемы;
• properties схема свойств объекта, фабрика или имя схемы;
• required исключает пустые значения;
• default значение по умолчанию или фабрика;

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, 0, 1, undefined, null]

Так как типы допускают пустые значения, рекомендуется использовать параметр required в определении схемы элемента, чтобы исключить такие значения из состава массива.

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

properties

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

{
  type: DataType.OBJECT, // тип данных
  properties: {
    name: {
      type: DataType.STRING // тип свойства "name"
    },
    age: {
      type: DataType.NUMBER // тип свойства "age"
    }
  }
}
// {
//   "name": "John",
//   "age": 27
// }

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

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

required

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

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

default

Значение по умолчанию можно указать в параметре default. Указанное значение будет использовано, если исходное значение оказалось пустым при разборе входящих данных.

{
  type: DataType.STRING, // тип данных
  default: 'N/A'         // значение по умолчанию
}

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

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

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

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

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

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

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

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

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

тип данных	пустые значения
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 (не требует установки).

Тесты

npm run test

Лицензия

MIT