e22m4u/js-data-schema: JavaScript модуль для работы со схемой данных @ 0a25ab264931ab80979a25e0d67e867944ed9958

@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, 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

Примеры

Определение типа значения.

{
  type: DataType.STRING // только строки
}

// допустимо:
//   'str'
//   ''
//   undefined
//   null

Исключение пустых значений.

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

// допустимо:
//   'str'

// исключено:
//   ''
//   undefined
//   null

Определение схемы для элементов массива.

{
  type: DataType.ARRAY,
  items: { // схема элементов
    type: DataType.NUMBER // только числа
  }
}

// допустимо:
//   [1, 2, 3]
//   [undefined, null]
//   []
//   undefined
//   null

Исключение пустых значений для массива и его элементов.

{
  type: DataType.ARRAY,
  items: { // схема элементов
    type: DataType.NUMBER, // допускает только числа
    required: true         // исключает пустые значения
  },
  required: true // массив является обязательным
}

// допустимо:
//   [1, 2, 3]
//   []

// исключено:
//   [undefined, null]
//   undefined
//   null

Определение схемы для свойств объекта.

{
  type: DataType.OBJECT,
  items: {
    foo: { // схема свойства foo
      type: DataType.STRING // только строки
    },
    bar: { // схема свойства bar
      type: DataType.NUMBER // только числа
    }
  }
}

// допустимо:
//   {foo: 'str', bar: 10}
//   {foo: null, bar: null}
//   {}
//   undefined
//   null

Исключение пустых значений для объекта и его свойств.

{
  type: DataType.OBJECT,
  properties: {
    foo: { // схема свойства foo
      type: DataType.STRING, // допускает только строки
      required: true         // исключает пустые значения
    },
    bar: { // схема свойства bar
      type: DataType.NUMBER  // допускает только числа
    }
  },
  required: true // объект является обязательным
}

// допустимо:
//   {foo: 'str', bar: 10}
//   {foo: 'str'}

// исключено:
//   {foo: '', bar: 10}
//   {foo: null}
//   {}
//   undefined
//   null

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

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

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

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

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

тип	пустые значения
`'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

README.md 12 KB History Raw