@e22m4u/js-repository 0.6.5 → 0.8.0

package/README.md

@@ -15,14 +15,6 @@
 - [Источник данных](#источник-данных)
 - [Модель](#модель)
 - [Свойства](#свойства)
-- [Валидаторы](#валидаторы)
-  - [Глобальные валидаторы](#глобальные-валидаторы)
-  - [Регистрация глобальных валидаторов](#регистрация-глобальных-валидаторов)
-  - [Локальные валидаторы](#локальные-валидаторы)
-- [Трансформеры](#трансформеры)
-  - [Глобальные трансформеры](#глобальные-трансформеры)
-  - [Регистрация глобальных трансформеров](#регистрация-глобальных-трансформеров)
-  - [Локальные трансформеры](#локальные-трансформеры)
 - [Пустые значения](#пустые-значения)
   - [Переопределение пустых значений](#переопределение-пустых-значений)
 - [Репозиторий](#репозиторий)
@@ -48,7 +40,6 @@
   - [Has One (полиморфная)](#has-one-полиморфная-версия)
   - [Has Many (полиморфная)](#has-many-полиморфная-версия)
 - [Расширение](#расширение)
-- [TypeScript](#typescript)
 - [Тесты](#тесты)
 - [Лицензия](#лицензия)
 
@@ -86,15 +77,14 @@ const {DatabaseSchema} = require('@e22m4u/js-repository');
 Модуль позволяет абстрагироваться от различных интерфейсов баз данных,
 представляя их как именованные *источники данных*, подключаемые к *моделям*.
 *Модель* же описывает таблицу базы, колонки которой являются свойствами
-модели. Свойства модели могут иметь определенный *тип* допустимого значения,
-набор *валидаторов* и *трансформеров*, через которые проходят данные перед
-записью в базу. Кроме того, *модель* может определять классические связи
-«один к одному», «один ко многим» и другие типы отношений между моделями.
+модели. Свойства модели могут иметь определенный *тип* допустимого значения.
+Кроме того, *модель* может определять классические связи «один к одному»,
+«один ко многим» и другие типы отношений между моделями.
 
-Непосредственно чтение и запись данных производится с помощью *репозитория*,
+Непосредственно чтение и запись данных производятся с помощью *репозитория*,
 который есть у каждой модели с объявленным *источником данных*. Репозиторий
 может фильтровать запрашиваемые документы, выполнять валидацию свойств
-согласно определению модели, и встраивать связанные данные в результат
+согласно определению модели и встраивать связанные данные в результат
 выборки.
 
 - *Источник данных* - определяет способ подключения к базе
@@ -266,17 +256,36 @@ console.log(cityWithCountry);
 
 ## Схема
 
-Экземпляр класса `DatabaseSchema` хранит определения источников данных и моделей.
+Экземпляр класса `DatabaseSchema` хранит определения источников данных
+и моделей.
 
 **Методы**
 
-- `defineDatasource(datasourceDef: object): this` - добавить источник
-- `defineModel(modelDef: object): this` - добавить модель
-- `getRepository(modelName: string): Repository` - получить репозиторий
+Добавить источник
 
-**Примеры**
+- `defineDatasource(datasourceDef)`
+  - `datasourceDef: object`: определение источника;
+  - результат: `this`;
+
+Добавить модель:
+
+- `defineModel(modelDef)`
+  - `modelDef: object`: определение модели;
+  - результат: `this`;
+
+Получить репозиторий
+
+- `getRepository(modelName)`
+  - `modelName: string` имя модели;
+  - результат: `Repository`;
+
+**Пример**
+
+Ниже приводится пошаговый пример настройки модели `product` и получения
+экземпляра репозитория, с помощью которого можно управлять данными этой
+коллекции.
 
-Импорт класса и создание экземпляра схемы.
+1\. Импорт класса и создание экземпляра схемы.
 
 ```js
 import {DatabaseSchema} from '@e22m4u/js-repository';
@@ -284,7 +293,7 @@ import {DatabaseSchema} from '@e22m4u/js-repository';
 const dbs = new DatabaseSchema();
 ```
 
-Определение нового источника.
+2\. Определение нового источника.
 
 ```js
 dbs.defineDatasource({
@@ -293,7 +302,7 @@ dbs.defineDatasource({
 });
 ```
 
-Определение новой модели.
+3\. Определение новой модели.
 
 ```js
 dbs.defineModel({
@@ -306,7 +315,7 @@ dbs.defineModel({
 });
 ```
 
-Получение репозитория по названию модели.
+4\. Получение репозитория по названию модели.
 
 ```js
 const productRep = dbs.getRepository('product');
@@ -379,7 +388,7 @@ dbs.defineModel({
 ## Свойства
 
 Параметр `properties` находится в определении модели и принимает объект, ключи
-которого являются свойствами этой модели, а значением тип свойства или объект
+которого являются свойствами этой модели, а значениями тип свойства или объект
 с дополнительными параметрами.
 
 **Тип данных**
@@ -401,20 +410,20 @@ dbs.defineModel({
 - `columnType: string` тип колонки (определяется адаптером)
 - `required: boolean` объявить свойство обязательным
 - `default: any` значение по умолчанию
-- `validate: string | Function | array | object` см. [Валидаторы](#Валидаторы)
 - `unique: boolean | string` проверять значение на уникальность
 
 **Параметр `unique`**
 
-Если значением параметра `unique` является `true` или `'strict'`, то выполняется
-строгая проверка на уникальность. В этом режиме [пустые значения](#Пустые-значения)
-так же подлежат проверке, где `null` и `undefined` также считаются значениями,
-которые должны быть уникальными.
+Если значением параметра `unique` является `true` или `'strict'`,
+то выполняется строгая проверка на уникальность. В этом режиме
+[пустые значения](#Пустые-значения) так же подлежат проверке,
+где `null` и `undefined` также считаются значениями, которые
+должны быть уникальными.
 
-Режим `'sparse'` проверяет только значения с полезной нагрузкой, исключая
-[пустые значения](#Пустые-значения), список которых отличается в зависимости
-от типа свойства. Например, для типа `string` пустым значением будет `undefined`,
-`null` и `''` (пустая строка).
+Режим `'sparse'` проверяет только значения с полезной нагрузкой,
+исключая [пустые значения](#Пустые-значения), список которых отличается
+в зависимости от типа свойства. Например, для типа `string` пустыми
+значениями будут `undefined`, `null` и `''` (пустая строка).
 
 - `unique: true | 'strict'` строгая проверка на уникальность
 - `unique: 'sparse'` исключить из проверки [пустые значения](#Пустые-значения)
@@ -483,522 +492,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, '-');
-      },
-    },
-  },
-});
-```
-
-
 ## Пустые значения
 
 Разные типы свойств имеют свои наборы пустых значений. Эти наборы используются
@@ -1029,26 +522,15 @@ dbs.defineModel({
 **EmptyValuesService**
 
 Для переопределения пустых значений необходимо получить экземпляр класса
-`EmptyValuesService` из контейнера схемы и вызвать метод, который принимает
-тип данных и массив новых значений.
-
-Интерфейс:
-
-```ts
-class EmptyValuesService {
-  /**
-   * Установить пустые значения
-   * для определенного типа данных.
-   * 
-   * @param dataType    Тип данных.
-   * @param emptyValues Массив новых пустых значений.
-   */
-  setEmptyValuesOf(
-    dataType: DataType,
-    emptyValues: unknown[],
-  ): this;
-}
-```
+`EmptyValuesService` из контейнера схемы и вызвать метод `setEmptyValuesOf`,
+который принимает тип данных и массив новых значений.
+
+Сигнатура:
+
+- `setEmptyValuesOf(dataType, emptyValues)`
+  - `dataType: DataType`: строковый литерал типа;
+  - `emptyValues: *[]`: массив новых значений;
+  - результат: `this`;
 
 **Пример**
 
@@ -1071,8 +553,8 @@ emptyValuesService.setEmptyValuesOf(DataType.NUMBER, [undefined, null]);
 ```
 
 После этого, значение `0` для свойств типа `DataType.NUMBER` больше не будет
-считаться пустым и будет проходить проверки валидаторами, а также не будет
-заменяться значением по умолчанию.
+считаться пустым и будет проходить проверку с опцией `required`, а также
+не будет заменяться значением по умолчанию.
 
 ## Репозиторий
 
@@ -1081,24 +563,24 @@ emptyValuesService.setEmptyValuesOf(DataType.NUMBER, [undefined, null]);
 
 **Методы**
 
-- [`create(data, filter = undefined)`](#repositorycreate) создать новый документ;
-- [`replaceById(id, data, filter = undefined)`](#repositoryreplacebyid) заменить документ полностью;
-- [`replaceOrCreate(data, filter = undefined)`](#repositoryreplaceorcreate) заменить или создать новый;
-- [`patchById(id, data, filter = undefined)`](#repositorypatchbyid) обновить документ частично;
-- [`patch(data, where = undefined)`](#repositorypatch) обновить все документы или по условию;
-- [`find(filter = undefined)`](#repositoryfind) найти все документы или по условию;
-- [`findOne(filter = undefined)`](#repositoryfindone) найти первый документ или по условию;
-- [`findById(id, filter = undefined)`](#repositoryfindbyid) найти документ по идентификатору;
-- [`delete(where = undefined)`](#repositorydelete) удалить все документы или по условию;
+- [`create(data, [filter])`](#repositorycreate) создать новый документ;
+- [`replaceById(id, data, [filter])`](#repositoryreplacebyid) заменить документ полностью;
+- [`replaceOrCreate(data, [filter])`](#repositoryreplaceorcreate) заменить или создать новый;
+- [`patchById(id, data, [filter])`](#repositorypatchbyid) обновить документ частично;
+- [`patch(data, [where])`](#repositorypatch) обновить все документы или по условию;
+- [`find([filter])`](#repositoryfind) найти все документы или по условию;
+- [`findOne([filter])`](#repositoryfindone) найти первый документ или по условию;
+- [`findById(id, [filter])`](#repositoryfindbyid) найти документ по идентификатору;
+- [`delete([where])`](#repositorydelete) удалить все документы или по условию;
 - [`deleteById(id)`](#repositorydeletebyid) удалить документ по идентификатору;
 - [`exists(id)`](#repositoryexists) проверить существование по идентификатору;
-- [`count(where = undefined)`](#repositorycount) подсчет всех документов или по условию;
+- [`count([where])`](#repositorycount) подсчет всех документов или по условию;
 
 **Аргументы**
 
 - `id: number|string` идентификатор (первичный ключ)
 - `data: object` данные документа (используется при записи)
-- `where: object` условия фильтрации (см. [Фильтрация](#Фильтрация))
+- `where: object` условия выборки (см. [`where`](#where))
 - `filter: object` параметры выборки (см. [Фильтрация](#Фильтрация))
 
 **Получение репозитория**
@@ -1138,12 +620,10 @@ const modelRep = dbs.getRepository('myModel');
 
 Сигнатура:
 
-```ts
-create(
-  data: WithOptionalId<FlatData, IdName>,
-  filter?: ItemFilterClause<FlatData>,
-): Promise<FlatData>;
-```
+- `create(data, [filter])`
+  - `data: object`: данные нового документа;
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object>`;
 
 **Примеры**
 
@@ -1204,13 +684,11 @@ console.log(product);
 
 Сигнатура:
 
-```ts
-replaceById(
-  id: IdType,
-  data: WithoutId<FlatData, IdName>,
-  filter?: ItemFilterClause<FlatData>,
-): Promise<FlatData>;
-```
+- `replaceById(id, data, [filter])`
+  - `id: number|string`: идентификатор документа;
+  - `data: object`: новые данные;
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object>`;
 
 **Примеры**
 
@@ -1246,12 +724,10 @@ console.log(updatedProduct);
 
 Сигнатура:
 
-```ts
-replaceOrCreate(
-  data: WithOptionalId<FlatData, IdName>,
-  filter?: ItemFilterClause<FlatData>,
-): Promise<FlatData>;
-```
+- `replaceOrCreate(data, [filter])`
+  - `data: object`: данные документа;
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object>`;
 
 **Примеры**
 
@@ -1294,13 +770,11 @@ console.log(updatedProduct);
 
 Сигнатура:
 
-```ts
-patchById(
-  id: IdType,
-  data: PartialWithoutId<FlatData, IdName>,
-  filter?: ItemFilterClause<FlatData>,
-): Promise<FlatData>;
-```
+- `patchById(id, data, [filter])`
+  - `id: number|string`: идентификатор обновляемого документа;
+  - `data: object`: новые данные;
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object>`;
 
 **Примеры**
 
@@ -1334,12 +808,10 @@ console.log(updatedProduct);
 
 Сигнатура:
 
-```ts
-patch(
-  data: PartialWithoutId<FlatData, IdName>,
-  where?: WhereClause<FlatData>,
-): Promise<number>;
-```
+- `patch(data, [where])`
+  - `data: object`: новые данные;
+  - `where?: object`: условия выборки (см. [`where`](#where));
+  - результат: `Promise<number>`;
 
 **Примеры**
 
@@ -1369,9 +841,9 @@ const totalCount = await productRep.patch({
 
 Сигнатура:
 
-```ts
-find(filter?: FilterClause<FlatData>): Promise<FlatData[]>;
-```
+- `find([filter])`
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object[]>`;
 
 **Примеры**
 
@@ -1405,11 +877,9 @@ const latestProducts = await productRep.find({
 
 Сигнатура:
 
-```ts
-findOne(
-  filter?: FilterClause<FlatData>,
-): Promise<FlatData | undefined>;
-```
+- `findOne([filter])`
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object|undefined>`;
 
 **Примеры**
 
@@ -1440,12 +910,10 @@ if (!product) {
 
 Сигнатура:
 
-```ts
-findById(
-  id: IdType,
-  filter?: ItemFilterClause<FlatData>,
-): Promise<FlatData>;
-```
+- `findById(id, [filter])`
+  - `id: number|string`: идентификатор документа;
+  - `filter?: object`: настройки выборки (см. [Фильтрация](#фильтрация));
+  - результат: `Promise<object|undefined>`;
 
 **Примеры**
 
@@ -1476,9 +944,9 @@ const product = await productRep.findById(1, {
 
 Сигнатура:
 
-```ts
-delete(where?: WhereClause<FlatData>): Promise<number>;
-```
+- `delete([where])`
+  - `where?: object`: условия выборки (см. [`where`](#where));
+  - результат: `Promise<number>`;
 
 **Примеры**
 
@@ -1503,9 +971,15 @@ const totalCount = await productRep.delete();
 
 Сигнатура:
 
-```ts
-deleteById(id: IdType): Promise<boolean>;
-```
+- `deleteById(id)`
+  - `id: number|string`: идентификатор документа;
+  - результат: `Promise<boolean>`;
+
+Результат:
+
+- `Promise<boolean>`: логическое значение;
+  - `true`: документ был найден и удален;
+  - `false`: документ не найден;
 
 **Примеры**
 
@@ -1527,9 +1001,15 @@ if (wasDeleted) {
 
 Сигнатура:
 
-```ts
-exists(id: IdType): Promise<boolean>;
-```
+- `exists(id)`
+  - `id: number|string`: идентификатор документа;
+  - результат: `Promise<boolean>`;
+
+Результат:
+
+- `Promise<boolean>`: логическое значение;
+  - `true`: документ с таким идентификатором найден;
+  - `false`: идентификатор не найден;
 
 **Примеры**
 
@@ -1549,9 +1029,9 @@ if (productExists) {
 
 Сигнатура:
 
-```ts
-count(where?: WhereClause<FlatData>): Promise<number>;
-```
+- `count([where])`
+  - `where?: object`: условия выборки (см. [`where`](#where));
+  - результат: `Promise<number>`;
 
 **Примеры**
 
@@ -1571,10 +1051,10 @@ const totalCount = await productRep.count();
 
 ## Фильтрация
 
-Некоторые методы репозитория принимают объект настроек влияющий
-на возвращаемый результат. Максимально широкий набор таких настроек
-имеет первый параметр метода `find`, где ожидается объект содержащий
-набор опций указанных ниже.
+Некоторые методы репозитория принимают объект настроек возвращаемого
+результата. Максимально широкий набор таких настроек имеет первый
+параметр метода `find`, где ожидается объект, содержащий набор
+опций указанных ниже.
 
 - `where: object` условия фильтрации по свойствам документа;
 - `order: string|string[]` сортировка по указанным свойствам;
@@ -2443,7 +1923,7 @@ dbs.defineModel({
 
 #### Has One (полиморфная версия)
 
-Обратная сторона полиморфная связи `belongsTo` по принципу *"один к одному"*.
+Обратная сторона полиморфной связи `belongsTo` по принципу *"один к одному"*.
 
 ```
     Текущая (company)  <───────┐      Целевая (license)
@@ -2510,7 +1990,7 @@ dbs.defineModel({
 
 #### Has Many (полиморфная версия)
 
-Обратная сторона полиморфная связи `belongsTo` по принципу *"один ко многим"*.
+Обратная сторона полиморфной связи `belongsTo` по принципу *"один ко многим"*.
 
 ```
     Текущая (letter)  <─────────┐      Целевая (file)
@@ -2623,56 +2103,9 @@ const rep = dbs.getRepository('model');
 console.log(rep instanceof MyRepository); // true
 ```
 
-*i. Так как экземпляры репозитория кэшируется, то замену конструктора
+*i. Так как экземпляры репозитория кэшируются, то замену конструктора
 следует выполнять до обращения к методу `getRepository`.*
 
-## TypeScript
-
-Получение типизированного репозитория с указанием интерфейса модели.
-
-```ts
-import {DataType} from '@e22m4u/js-repository';
-import {RelationType} from '@e22m4u/js-repository';
-import {DatabaseSchema} from '@e22m4u/js-repository';
-
-// const dbs = new DatabaseSchema();
-// dbs.defineDatasource ...
-
-// определение модели "city"
-dbs.defineModel({
-  name: 'city',
-  datasource: 'myDatasource',
-  properties: {
-    name: DataType.STRING,
-    timeZone: DataType.STRING,
-  },
-});
-
-// определение интерфейса "city"
-interface City {
-  id: number;
-  name?: string;
-  timeZone?: string;
-}
-
-// при получении репозитория нужной модели
-// можно указать тип документов
-const cityRep = dbs.getRepository<City>('city');
-
-// теперь, методы репозитория возвращают
-// тип City вместо Record<string, unknown>
-const city: City = await cityRep.create({
-  name: 'Moscow',
-  timeZone: 'Europe/Moscow',
-});
-```
-
-Для определения моделей с помощью TypeScript классов,
-рекомендуется использовать специальную версию данного модуля
-[@e22m4u/ts-repository](https://www.npmjs.com/package/@e22m4u/ts-repository),
-поставляемую с набором TypeScript декораторов и дополнительных
-инструментов для работы в TypeScript окружении.
-
 ## Тесты
 
 ```bash