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: DataType.ARRAY,
  items: {
    type: DataType.OBJECT,
    properties: {
      name: {
        type: DataType.STRING,
        required: true
      },
      age: {
        type: DataType.NUMBER
      }
    }
  }
}
// [
//   {
//     name: 'John',
//     age: 27,
//   },
//   {
//     name: 'Frank'
//   }
// ]

Свойства схемы (далее параметры):

• 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