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 исключает пустые значения;

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
    },
    age: {
      type: DataType.NUMBER
    }
  }
}
// {
//   "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" ...

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

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

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

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

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