@e22m4u/js-repository 0.6.4 → 0.7.0

package/README.md

@@ -15,14 +15,6 @@
 - [Источник данных](#источник-данных)
 - [Модель](#модель)
 - [Свойства](#свойства)
-- [Валидаторы](#валидаторы)
-  - [Глобальные валидаторы](#глобальные-валидаторы)
-  - [Регистрация глобальных валидаторов](#регистрация-глобальных-валидаторов)
-  - [Локальные валидаторы](#локальные-валидаторы)
-- [Трансформеры](#трансформеры)
-  - [Глобальные трансформеры](#глобальные-трансформеры)
-  - [Регистрация глобальных трансформеров](#регистрация-глобальных-трансформеров)
-  - [Локальные трансформеры](#локальные-трансформеры)
 - [Пустые значения](#пустые-значения)
   - [Переопределение пустых значений](#переопределение-пустых-значений)
 - [Репозиторий](#репозиторий)
@@ -86,10 +78,9 @@ const {DatabaseSchema} = require('@e22m4u/js-repository');
 Модуль позволяет абстрагироваться от различных интерфейсов баз данных,
 представляя их как именованные *источники данных*, подключаемые к *моделям*.
 *Модель* же описывает таблицу базы, колонки которой являются свойствами
-модели. Свойства модели могут иметь определенный *тип* допустимого значения,
-набор *валидаторов* и *трансформеров*, через которые проходят данные перед
-записью в базу. Кроме того, *модель* может определять классические связи
-«один к одному», «один ко многим» и другие типы отношений между моделями.
+модели. Свойства модели могут иметь определенный *тип* допустимого значения.
+Кроме того, *модель* может определять классические связи «один к одному»,
+«один ко многим» и другие типы отношений между моделями.
 
 Непосредственно чтение и запись данных производится с помощью *репозитория*,
 который есть у каждой модели с объявленным *источником данных*. Репозиторий
@@ -401,7 +392,6 @@ dbs.defineModel({
 - `columnType: string` тип колонки (определяется адаптером)
 - `required: boolean` объявить свойство обязательным
 - `default: any` значение по умолчанию
-- `validate: string | Function | array | object` см. [Валидаторы](#Валидаторы)
 - `unique: boolean | string` проверять значение на уникальность
 
 **Параметр `unique`**
@@ -483,522 +473,6 @@ dbs.defineModel({
 });
 ```
 
-## Валидаторы
-
-Валидаторы используются для проверки значения свойства перед записью в базу.
-Проверка значения валидатором выполняется сразу после проверки типа, указанного
-в определении свойства модели. [Пустые значения](#пустые-значения) пропускают
-проверку валидаторами, так как не имеют полезной нагрузки.
-
-### Глобальные валидаторы
-
-Модуль поставляется с набором глобальных валидаторов:
-
-- `regexp` проверка по регулярному выражению,  
-  *параметр: `string | RegExp` - регулярное выражение;*
-
-- `maxLength` максимальная длина строки или массива,  
-  *параметр: `number` - максимальная длина;*
-
-- `minLength` минимальная длина строки или массива,  
-  *параметр: `number` - минимальная длина;*
-
-Валидаторы указанные ниже находятся в разработке:
-
-- `isLowerCase` проверка регистра (только строчные буквы);
-- `isUpperCase` проверка регистра (только прописные буквы);
-- `isEmail` проверка формата электронного адреса;
-
-**Примеры**
-
-Использование глобального валидатора.
-
-```js
-dbs.defineModel({
-  name: 'user',
-  properties: {
-    email: {
-      type: DataType.STRING,
-      validate: 'isEmail',
-    },
-  },
-});
-```
-
-Использование глобальных валидаторов в виде массива.
-
-```js
-dbs.defineModel({
-  name: 'user',
-  properties: {
-    email: {
-      type: DataType.STRING,
-      validate: [
-        'isEmail',
-        'isLowerCase',
-      ],
-    },
-  },
-});
-```
-
-Использование глобальных валидаторов с передачей аргументов.
-
-```js
-dbs.defineModel({
-  name: 'user',
-  properties: {
-    name: {
-      type: DataType.STRING,
-      validate: {
-        minLength: 2,
-        maxLength: 24,
-        regexp: /^[a-zA-Z-']+$/,
-      },
-    },
-  },
-});
-```
-
-Глобальные валидаторы без параметров могут принимать любые аргументы.
-
-```js
-dbs.defineModel({
-  name: 'user',
-  properties: {
-    email: {
-      type: DataType.STRING,
-      validate: {
-        maxLength: 100,
-        // так как валидатор "isEmail" не имеет параметров,
-        // его определение допускает передачу любого значения
-        // в качестве аргумента
-        isEmail: true,
-      },
-    },
-  },
-});
-```
-
-### Регистрация глобальных валидаторов
-
-Валидатором является функция, в которую передается значение соответствующего
-поля перед записью в базу. Если во время проверки функция возвращает `false`,
-то выбрасывается стандартная ошибка. Подмена стандартной ошибки возможна
-с помощью выброса пользовательской ошибки непосредственно внутри проверяющей
-функции.
-
-Регистрация глобального валидатора выполняется методом `addValidator` сервиса
-`PropertyValidatorRegistry`, который принимает название валидатора и функцию
-для проверки значения.
-
-**Примеры**
-
-Регистрация глобального валидатора для проверки формата UUID.
-
-```js
-import {createError} from 'http-errors';
-import {format} from '@e22m4u/js-format';
-import {Errorf} from '@e22m4u/js-format';
-import {PropertyValidatorRegistry} from '@e22m4u/js-repository';
-
-// получение экземпляра сервиса
-const pvr = dbs.getService(PropertyValidatorRegistry);
-
-// регулярные выражения для разных версий UUID
-const uuidRegex = {
-  any: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
-  v4: /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
-};
-
-// регистрация глобального валидатора "isUuid",
-// принимающего объект настроек со свойством "version"
-pvr.addValidator('isUuid', (value, options, context) => {
-  // value   - проверяемое значение;
-  // options - параметры валидатора;
-  // context - информация о проверяемом свойстве;
-  console.log(options);
-  // {
-  //   version: 'v4'
-  // }
-  console.log(context);
-  // {
-  //   validatorName: 'isUuid',
-  //   modelName: 'device',
-  //   propName: 'deviceId'
-  // }
-
-  // пустые значения не передаются в валидаторы
-  // (условие ниже никогда не сработает)
-  if (typeof value !== 'string') return false;
-  // поиск регулярного выражения для указанной
-  // версии UUID (из параметров валидатора)
-  const version = options?.version || 'any';
-  const regex = uuidRegex[version];
-  // если регулярное выражение не найдено,
-  // то выбрасывается внутренняя ошибка
-  if (!regex)
-    throw new Errorf(
-      'Invalid UUID version %v specified for validator.',
-      version,
-    );
-  // при неудачной проверке выбрасывается
-  // ошибка 400 BadRequest
-  if (!regex.test(value)) {
-    const versionString = version !== 'any' ? ` (version ${version})` : '';
-    throw createError(400, format(
-      'The property %v of the model %v must be a valid UUID%s.',
-      context.propName,
-      context.modelName,
-      versionString,
-    ));
-  }
-  // при успешной проверке возвращается true,
-  // в противном случае выбрасывается стандартная
-  // ошибка проверки
-  return true;
-});
-```
-
-Использование глобального валидатора в определении свойства.
-
-```js
-// определение модели "device"
-dbs.defineModel({
-  name: 'device',
-  properties: {
-    deviceId: {
-      type: DataType.STRING,
-      required: true,
-      validate: {
-        // значение {version: 'v4'} будет передаваться
-        // вторым аргументом в функцию-валидатор
-        isUuid: {version: 'v4'},
-      },
-    },
-  },
-});
-```
-
-### Локальные валидаторы
-
-Функция-валидатор может быть передана непосредственно в определении свойства
-без предварительной регистрации. Для этого достаточно передать функцию
-в параметр `validate` в качестве значения или элемента массива наряду
-с другими валидаторами.
-
-**Примеры**
-
-Использование локального валидатора для проверки сложности пароля.
-
-```js
-// валидатор `passwordStrength` проверяет сложность пароля
-function passwordStrength(value, options, context) {
-  // value   - проверяемое значение;
-  // options - не используется;
-  // context - информация о свойстве;
-  console.log(context);
-  // {
-  //   validatorName: 'passwordStrength',
-  //   modelName: 'user',
-  //   propName: 'password'
-  // }
-  const errors = [];
-  if (value.length < 8)
-    errors.push('must be at least 8 characters long');
-  if (!/\d/.test(value))
-    errors.push('must contain at least one number');
-  if (!/[a-zA-Z]/.test(value))
-    errors.push('must contain at least one letter');
-  // если одно из условий сработало,
-  // то выбрасывается ошибка
-  if (errors.length > 0)
-    throw createError(400, format(
-      'Value of the property %v of the model %v %s.',
-      context.propName,
-      context.modelName,
-      errors.join(', '),
-    ));
-  // при успешной проверке возвращается true,
-  // в противном случае выбрасывается стандартная
-  // ошибка проверки
-  return true;
-}
-
-// определение модели "user"
-dbs.defineModel({
-  name: 'user',
-  properties: {
-    password: {
-      type: DataType.STRING,
-      required: true,
-      validate: passwordStrength, // <=
-      // или
-      // validate: [passwordStrength, ...]
-    },
-  },
-});
-```
-
-Использование анонимной функции-валидатора для проверки слага.
-
-```js
-// определение модели "article"
-dbs.defineModel({
-  name: 'article',
-  properties: {
-    slug: {
-      type: DataType.STRING,
-      validate: (value) => {
-        const re = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-        return re.test(value);
-      },
-    },
-  },
-});
-```
-
-## Трансформеры
-
-Трансформеры используются для модификации значения свойства перед проверкой
-типа и передачей данных в базу. Трансформеры позволяют автоматически очищать
-или приводить данные к нужному формату. [Пустые значения](#Пустые-значения)
-не передаются в трансформеры, так как не имеют полезной нагрузки.
-
-### Глобальные трансформеры
-
-Модуль поставляется с набором глобальных трансформеров:
-
-- `trim` удаление пробельных символов с начала и конца строки;
-- `toUpperCase` перевод строки в верхний регистр;
-- `toLowerCase` перевод строки в нижний регистр;
-
-Трансформеры указанные ниже находятся в разработке:
-
-- `cut` усечение строки или массива до указанной длины,  
-  *параметр: `number` - максимальная длина;*
-
-- `truncate` усечение строки с добавлением троеточия,  
-  *параметр: `number` - максимальная длина;*
-
-- `capitalize` перевод первой буквы каждого слова в верхний регистр,  
-  *параметр: `{firstWordOnly?: boolean}`;*
-
-**Примеры**
-
-Использование глобального трансформера.
-
-```js
-dbs.defineModel({
-  name: 'user',
-  properties: {
-    username: {
-      type: DataType.STRING,
-      transform: 'toLowerCase',
-    },
-  },
-});
-```
-
-Использование глобальных трансформеров в виде массива.
-
-```js
-dbs.defineModel({
-  name: 'user',
-  properties: {
-    firstName: {
-      type: DataType.STRING,
-      transform: [
-        'trim',
-        'capitalize',
-      ],
-    },
-  },
-});
-```
-
-Использование глобальных трансформеров с передачей аргументов.
-
-```js
-dbs.defineModel({
-  name: 'article',
-  properties: {
-    annotation: {
-      type: DataType.STRING,
-      transform: {
-        truncate: 200,
-        capitalize: {firstWordOnly: true},
-      },
-    },
-  },
-});
-```
-
-Глобальные трансформеры без параметров могут принимать любые аргументы.
-
-```js
-dbs.defineModel({
-  name: 'user',
-  properties: {
-    firstName: {
-      type: DataType.STRING,
-      transform: {
-        cut: 60,
-        // так как трансформер "trim" не имеет параметров,
-        // его определение допускает передачу любого значения
-        // в качестве аргумента
-        trim: true,
-      },
-    },
-  },
-});
-```
-
-### Регистрация глобальных трансформеров
-
-Трансформером является функция, которая принимает значение свойства и возвращает
-новое значение. Функция может быть как синхронной, так и асинхронной (возвращать
-`Promise`).
-
-Регистрация глобального трансформера выполняется методом `addTransformer`
-сервиса `PropertyTransformerRegistry`, который принимает название трансформера
-и саму функцию.
-
-**Примеры**
-
-Регистрация глобального трансформера для удаления HTML-тегов.
-
-```js
-import {PropertyTransformerRegistry} from '@e22m4u/js-repository';
-
-// получение экземпляра сервиса
-const ptr = dbs.getService(PropertyTransformerRegistry);
-
-// регистрация глобального трансформера "stripTags"
-ptr.addTransformer('stripTags', (value, options, context) => {
-  // value   - трансформируемое значение;
-  // options - настройки трансформера (если переданы);
-  // context - информация о свойстве;
-  console.log(context);
-  // {
-  //   transformerName: 'stripTags',
-  //   modelName: 'comment',
-  //   propName: 'text'
-  // }
-  
-  if (typeof value !== 'string')
-    return value; // возвращаем как есть, если не строка
-  
-  return value.replace(/<[^>]*>?/gm, '');
-});
-```
-
-Использование глобального трансформера в определении модели.
-
-```js
-dbs.defineModel({
-  name: 'comment',
-  properties: {
-    text: {
-      type: DataType.STRING,
-      transform: 'stripTags',
-    },
-  },
-});
-```
-
-### Локальные трансформеры
-
-Функция-трансформер может быть передана непосредственно в определении свойства без предварительной регистрации. Для этого достаточно передать функцию в параметр `transform` в качестве значения или элемента массива.
-
-**Примеры**
-
-Использование локального трансформера для нормализации имен.
-
-```js
-// функция для нормализации имени
-function normalizeName(value, options, context) {
-  // value   - трансформируемое значение
-  // options - не используется
-  // context - информация о свойстве
-  if (!value || typeof value !== 'string') return value;
-  return value
-    .trim()        // удаление пробелов в начале и конце
-    .toLowerCase() // перевод к нижнему регистру
-    .split(' ')    // разделение на слова
-    // перевод к верхнему регистру первой буквы каждого слова
-    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(' ');    // сборка массива в строку
-}
-
-// определение модели "user"
-dbs.defineModel({
-  name: 'user',
-  properties: {
-    firstName: {
-      type: DataType.STRING,
-      transform: normalizeName, // <=
-    },
-    lastName: {
-      type: DataType.STRING,
-      transform: normalizeName, // <=
-    },
-  },
-});
-```
-
-Использование локального асинхронного трансформера для хэширования пароля.
-
-```js
-import * as bcrypt from 'bcrypt';
-
-// асинхронная функция для хеширования значения
-async function hash(value, options, context) {
-  // value   - трансформируемое значение
-  // options - не используется
-  // context - информация о свойстве
-  console.log(context);
-  // {
-  //   transformerName: 'hash',
-  //   modelName: 'user',
-  //   propName: 'password'
-  // }
-  const saltRounds = 10;
-  return bcrypt.hash(value, saltRounds);
-}
-
-// определение модели "user"
-dbs.defineModel({
-  name: 'user',
-  properties: {
-    password: {
-      type: DataType.STRING,
-      transform: hash, // <=
-      // или
-      // transform: [hash, ...]
-    },
-  },
-});
-```
-
-Использование анонимной функции-трансформера для коррекции слага.
-
-```js
-dbs.defineModel({
-  name: 'article',
-  properties: {
-    slug: {
-      type: DataType.STRING,
-      transform: (value) => {
-        if (typeof value !== 'string') return value;
-        return value.toLowerCase().replace(/\s+/g, '-');
-      },
-    },
-  },
-});
-```
-
-
 ## Пустые значения
 
 Разные типы свойств имеют свои наборы пустых значений. Эти наборы используются
@@ -1071,8 +545,8 @@ emptyValuesService.setEmptyValuesOf(DataType.NUMBER, [undefined, null]);
 ```
 
 После этого, значение `0` для свойств типа `DataType.NUMBER` больше не будет
-считаться пустым и будет проходить проверки валидаторами, а также не будет
-заменяться значением по умолчанию.
+считаться пустым и будет проходить проверку с опцией `required`, а также
+не будет заменяться значением по умолчанию.
 
 ## Репозиторий
 
@@ -1571,7 +1045,7 @@ const totalCount = await productRep.count();
 
 ## Фильтрация
 
-Некоторые методы репозитория принимают объект настроек влияющий
+Некоторые методы репозитория принимают объект настроек, влияющий
 на возвращаемый результат. Максимально широкий набор таких настроек
 имеет первый параметр метода `find`, где ожидается объект содержащий
 набор опций указанных ниже.