@e22m4u/js-repository 0.6.3 → 0.6.5

package/README.md

@@ -1,6 +1,11 @@
 ## @e22m4u/js-repository
 
-Реализация паттерна «Репозиторий» для работы с базами данных в Node.js
+![npm version](https://badge.fury.io/js/@e22m4u%2Fjs-repository.svg)
+![license](https://img.shields.io/badge/license-mit-blue.svg)
+
+Реализация паттерна «Репозиторий» для работы с базами данных.
+
+## Содержание
 
 - [Установка](#установка)
 - [Импорт](#импорт)
@@ -21,8 +26,27 @@
 - [Пустые значения](#пустые-значения)
   - [Переопределение пустых значений](#переопределение-пустых-значений)
 - [Репозиторий](#репозиторий)
+  - [create](#repositorycreate)
+  - [replaceById](#repositoryreplacebyid)
+  - [replaceOrCreate](#repositoryreplaceorcreate)
+  - [patchById](#repositorypatchbyid)
+  - [patch](#repositorypatch)
+  - [find](#repositoryfind)
+  - [findOne](#repositoryfindone)
+  - [findById](#repositoryfindbyid)
+  - [delete](#repositorydelete)
+  - [deleteById](#repositorydeletebyid)
+  - [exists](#repositoryexists)
+  - [count](#repositorycount)
 - [Фильтрация](#фильтрация)
 - [Связи](#связи)
+  - [Belongs To](#belongs-to)
+  - [Has One](#has-one)
+  - [Has Many](#has-many)
+  - [References Many](#references-many)
+  - [Belongs To (полиморфная)](#belongs-to-полиморфная-версия)
+  - [Has One (полиморфная)](#has-one-полиморфная-версия)
+  - [Has Many (полиморфная)](#has-many-полиморфная-версия)
 - [Расширение](#расширение)
 - [TypeScript](#typescript)
 - [Тесты](#тесты)
@@ -36,10 +60,10 @@ npm install @e22m4u/js-repository
 
 Опционально устанавливается нужный адаптер.
 
-| адаптер   | описание                                                                                                                       |
-|-----------|--------------------------------------------------------------------------------------------------------------------------------|
-| `memory`  | Виртуальная база в памяти процесса (не требует установки)                                                                      |
-| `mongodb` | MongoDB - система управления NoSQL базами (*[установка](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter))* |
+| адаптер   | описание                                        | установка                                                                  |
+|-----------|-------------------------------------------------|----------------------------------------------------------------------------|
+| `memory`  | Виртуальная база в памяти процесса              | *встроенный*                                                               |
+| `mongodb` | MongoDB - документо-ориентированная база данных | [npm](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter) |
 
 ## Импорт
 
@@ -68,7 +92,7 @@ const {DatabaseSchema} = require('@e22m4u/js-repository');
 «один к одному», «один ко многим» и другие типы отношений между моделями.
 
 Непосредственно чтение и запись данных производится с помощью *репозитория*,
-который имеет каждая модель с объявленным *источником данных*. Репозиторий
+который есть у каждой модели с объявленным *источником данных*. Репозиторий
 может фильтровать запрашиваемые документы, выполнять валидацию свойств
 согласно определению модели, и встраивать связанные данные в результат
 выборки.
@@ -111,7 +135,18 @@ flowchart TD
 
 ## Пример
 
-Объявление источника данных, модели и добавление нового документа в коллекцию.
+Пример демонстрирует создание экземпляра схемы, объявление источника данных
+и модели `country`. После чего, с помощью репозитория данной модели, в коллекцию
+добавляется новый документ (страна), который выводится в консоль.
+
+```
+   Страна (country)
+┌─────────────────────────┐
+│  id: 1                  │
+│  name: "Russia"         │
+│  population: 143400000  │
+└─────────────────────────┘
+```
 
 ```js
 import {DataType} from '@e22m4u/js-repository';
@@ -120,18 +155,18 @@ import {DatabaseSchema} from '@e22m4u/js-repository';
 // создание экземпляра DatabaseSchema
 const dbs = new DatabaseSchema();
 
-// объявление источника "myMemory"
+// объявление источника "myDb"
 dbs.defineDatasource({
-  name: 'myMemory', // название нового источника
+  name: 'myDb',      // название нового источника
   adapter: 'memory', // выбранный адаптер
 });
 
 // объявление модели "country"
 dbs.defineModel({
-  name: 'country', // название новой модели
-  datasource: 'myMemory', // выбранный источник
-  properties: { // свойства модели
-    name: DataType.STRING, // тип "string"
+  name: 'country',    // название новой модели
+  datasource: 'myDb', // выбранный источник
+  properties: {       // свойства модели
+    name: DataType.STRING,       // тип "string"
     population: DataType.NUMBER, // тип "number"
   },
 })
@@ -154,6 +189,81 @@ console.log(country);
 // }
 ```
 
+В следующем блоке определяется модель `city` со связью `belongsTo` к модели
+`country` из примера выше. Затем создается новый документ города, связанный
+с ранее созданной страной. После создания нового документа, выполняется запрос
+на извлечение данного города с включением связанной страны.
+
+```
+   Страна (country)                  Город (city)
+┌─────────────────────────┐       ┌─────────────────────────┐
+│  id: 1  <───────────────│───┐   │  id: 1                  │
+│  name: "Russia"         │   │   │  name: "Moscow"         │
+│  population: 143400000  │   └───│─ countryId: 1           │
+└─────────────────────────┘       └─────────────────────────┘
+```
+
+```js
+// объявление модели "city" со связью к "country"
+dbs.defineModel({
+  name: 'city',
+  datasource: 'myDb',
+  properties: {
+    name: DataType.STRING,
+    countryId: DataType.NUMBER,
+    // внешний ключ "countryId" указывать не обязательно,
+    // но для проверки типа значения перед записью в базу
+    // рекомендуется, так как адаптер "memory" по умолчанию
+    // создает числовые идентификаторы
+  },
+  relations: {
+    // определение связи "country" позволит автоматически включать
+    // связанные документы с помощью опции "include" при запросах
+    // из данной коллекции через методы репозитория
+    country: {
+      type: RelationType.BELONGS_TO, // тип связи: принадлежит к...
+      model: 'country',              // название целевой модели
+      foreignKey: 'countryId',       // поле с внешним ключом (не обязательно)
+      // если внешний ключ соответствует `relationName` + `Id`,
+      // то указывать опцию `foreignKey` не обязательно
+    },
+  },
+});
+
+// получение репозитория для модели "city"
+const cityRep = dbs.getRepository('city');
+
+// создание нового города и его привязка к стране через country.id
+const city = await cityRep.create({
+  name: 'Moscow',
+  countryId: country.id, // использование id созданной ранее страны
+});
+
+console.log(city);
+// {
+//   id: 1,
+//   name: 'Moscow',
+//   countryId: 1,
+// }
+
+// извлечение города по идентификатору с включением связанной страны
+const cityWithCountry = await cityRep.findById(city.id, {
+  include: 'country',
+});
+
+console.log(cityWithCountry);
+// {
+//   id: 1,
+//   name: 'Moscow',
+//   countryId: 1,
+//   country: {
+//     id: 1,
+//     name: 'Russia',
+//     population: 143400000
+//   }
+// }
+```
+
 ## Схема
 
 Экземпляр класса `DatabaseSchema` хранит определения источников данных и моделей.
@@ -178,7 +288,7 @@ const dbs = new DatabaseSchema();
 
 ```js
 dbs.defineDatasource({
-  name: 'myMemory', // название нового источника
+  name: 'myDb', // название нового источника
   adapter: 'memory', // выбранный адаптер
 });
 ```
@@ -188,7 +298,7 @@ dbs.defineDatasource({
 ```js
 dbs.defineModel({
   name: 'product', // название новой модели
-  datasource: 'myMemory', // выбранный источник
+  datasource: 'myDb', // выбранный источник
   properties: { // свойства модели
     name: DataType.STRING,
     weight: DataType.NUMBER,
@@ -220,16 +330,16 @@ const productRep = dbs.getRepository('product');
 
 ```js
 dbs.defineDatasource({
-  name: 'myMemory', // название нового источника
+  name: 'myDb', // название нового источника
   adapter: 'memory', // выбранный адаптер
 });
 ```
 
-Передача дополнительных параметров адаптера.
+Передача дополнительных параметров на примере MongoDB адаптера *([установка](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter))*.
 
 ```js
 dbs.defineDatasource({
-  name: 'myMongodb',
+  name: 'myDb',
   adapter: 'mongodb',
   // параметры адаптера "mongodb"
   host: '127.0.0.1',
@@ -298,8 +408,8 @@ dbs.defineModel({
 
 Если значением параметра `unique` является `true` или `'strict'`, то выполняется
 строгая проверка на уникальность. В этом режиме [пустые значения](#Пустые-значения)
-так же подлежат проверке, где `null` и `undefined` не могут повторяться более одного
-раза.
+так же подлежат проверке, где `null` и `undefined` также считаются значениями,
+которые должны быть уникальными.
 
 Режим `'sparse'` проверяет только значения с полезной нагрузкой, исключая
 [пустые значения](#Пустые-значения), список которых отличается в зависимости
@@ -395,8 +505,8 @@ dbs.defineModel({
 
 Валидаторы указанные ниже находятся в разработке:
 
-- `isLowerCase` проверка регистра (только прописные буквы);
-- `isUpperCase` проверка регистра (только строчные буквы);
+- `isLowerCase` проверка регистра (только строчные буквы);
+- `isUpperCase` проверка регистра (только прописные буквы);
 - `isEmail` проверка формата электронного адреса;
 
 **Примеры**
@@ -493,7 +603,7 @@ import {Errorf} from '@e22m4u/js-format';
 import {PropertyValidatorRegistry} from '@e22m4u/js-repository';
 
 // получение экземпляра сервиса
-const pvr = dbs.get(PropertyValidatorRegistry);
+const pvr = dbs.getService(PropertyValidatorRegistry);
 
 // регулярные выражения для разных версий UUID
 const uuidRegex = {
@@ -762,7 +872,7 @@ dbs.defineModel({
 import {PropertyTransformerRegistry} from '@e22m4u/js-repository';
 
 // получение экземпляра сервиса
-const ptr = dbs.get(PropertyTransformerRegistry);
+const ptr = dbs.getService(PropertyTransformerRegistry);
 
 // регистрация глобального трансформера "stripTags"
 ptr.addTransformer('stripTags', (value, options, context) => {
@@ -891,13 +1001,13 @@ dbs.defineModel({
 
 ## Пустые значения
 
-Разные типы свойств имеют свои наборы пустых значений. Эти наборы
-используются для определения наличия полезной нагрузки в значении
-свойства. Например, параметр `default` в определении свойства
-устанавливает значение по умолчанию, только если входящее значение
-является пустым. Параметр `required` исключает пустые значения
-выбрасывая ошибку. А параметр `unique` в режиме `sparse` наоборот
-допускает дублирование пустых значений уникального свойства.
+Разные типы свойств имеют свои наборы пустых значений. Эти наборы используются
+для определения наличия полезной нагрузки в значении свойства. Например,
+параметр `default` в определении свойства устанавливает значение по умолчанию,
+только если входящее значение является пустым. Параметр `required` исключает
+пустые значения выбрасывая ошибку. А параметр `unique` в режиме `sparse`
+наоборот допускает дублирование пустых значений уникального свойства,
+поскольку они не участвуют в проверке.
 
 | тип         | пустые значения           |
 |-------------|---------------------------|
@@ -966,23 +1076,23 @@ emptyValuesService.setEmptyValuesOf(DataType.NUMBER, [undefined, null]);
 
 ## Репозиторий
 
-Выполняет операции чтения и записи документов определенной модели.
-Получить репозиторий можно методом `getRepository` экземпляра `DatabaseSchema`.
+Репозиторий выполняет операции чтения и записи данных определенной модели.
+Он выступает в роли посредника между бизнес-логикой приложения и базой данных.
 
 **Методы**
 
-- `create(data, filter = undefined)` добавить новый документ
-- `replaceById(id, data, filter = undefined)` заменить весь документ
-- `replaceOrCreate(data, filter = undefined)` заменить или создать новый
-- `patchById(id, data, filter = undefined)` частично обновить документ
-- `patch(data, where = undefined)` обновить все документы или по условию
-- `find(filter = undefined)` найти все документы или по условию
-- `findOne(filter = undefined)` найти первый документ или по условию
-- `findById(id, filter = undefined)` найти документ по идентификатору
-- `delete(where = undefined)` удалить все документы или по условию
-- `deleteById(id)` удалить документ по идентификатору
-- `exists(id)` проверить существование по идентификатору
-- `count(where = undefined)` подсчет всех документов или по условию
+- [`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) удалить все документы или по условию;
+- [`deleteById(id)`](#repositorydeletebyid) удалить документ по идентификатору;
+- [`exists(id)`](#repositoryexists) проверить существование по идентификатору;
+- [`count(where = undefined)`](#repositorycount) подсчет всех документов или по условию;
 
 **Аргументы**
 
@@ -991,49 +1101,472 @@ emptyValuesService.setEmptyValuesOf(DataType.NUMBER, [undefined, null]);
 - `where: object` условия фильтрации (см. [Фильтрация](#Фильтрация))
 - `filter: object` параметры выборки (см. [Фильтрация](#Фильтрация))
 
+**Получение репозитория**
+
+Получить репозиторий можно с помощью метода `getRepository()` экземпляра
+`DatabaseSchema`. В качестве аргумента метод принимает название модели.
+Обязательным условием является наличие у модели определенного [источника данных](#источник-данных) (`datasource`), так как репозиторий напрямую взаимодействует
+с базой данных через указанный в источнике адаптер.
+
+```js
+// объявление источника
+dbs.defineDatasource({
+  name: 'myDatasource',
+  adapter: 'memory', // адаптер
+});
+
+// объявление модели
+dbs.defineModel({
+  name: 'myModel',
+  datasource: 'myDatasource',
+  // properties: { ... },
+  // relations: { ... }
+});
+
+// получение репозитория модели
+const modelRep = dbs.getRepository('myModel');
+```
+
+При первом вызове `getRepository('myModel')` будет создан и сохранен новый
+экземпляр репозитория. Все последующие вызовы с тем же названием модели будут
+возвращать уже существующий экземпляр.
+
+### repository.create
+
+Создает новый документ в коллекции на основе переданных данных. Возвращает
+созданный документ с присвоенным идентификатором.
+
+Сигнатура:
+
+```ts
+create(
+  data: WithOptionalId<FlatData, IdName>,
+  filter?: ItemFilterClause<FlatData>,
+): Promise<FlatData>;
+```
+
 **Примеры**
 
-Получение репозитория по названию модели.
+Создание нового документа.
 
 ```js
-const countryRep = dbs.getRepository('country');
+const newProduct = await productRep.create({
+  name: 'Laptop',
+  price: 1200,
+});
+console.log(newProduct);
+// {
+//   id: 1,
+//   name: 'Laptop',
+//   price: 1200,
+// }
 ```
 
-Добавление нового документа в коллекцию.
+Создание документа с возвратом определенных полей.
 
 ```js
-const res = await countryRep.create({
-  name: 'Russia',
-  population: 143400000,
+const product = await productRep.create(
+  {name: 'Mouse', price: 25},
+  {fields: ['id', 'name']},
+);
+console.log(product);
+// {
+//   id: 2,
+//   name: 'Mouse',
+// }
+```
+
+Создание документа с включением связанных данных в результат.
+
+```js
+// предполагается, что модель Product имеет связь "category"
+// (опция "include" влияет только на возвращаемый результат)
+const product = await productRep.create(
+  {name: 'Keyboard', price: 75, categoryId: 10},
+  {include: 'category'},
+);
+console.log(product);
+// {
+//   id: 3,
+//   name: 'Keyboard',
+//   price: 75,
+//   categoryId: 10,
+//   category: {id: 10, name: 'Electronics'}
+// }
+```
+
+### repository.replaceById
+
+Полностью заменяет существующий документ по его идентификатору. Все предыдущие
+данные документа, кроме идентификатора, удаляются. Поля, которые не были
+переданы в `data`, будут отсутствовать в итоговом документе (если для них
+не задано значение по умолчанию).
+
+Сигнатура:
+
+```ts
+replaceById(
+  id: IdType,
+  data: WithoutId<FlatData, IdName>,
+  filter?: ItemFilterClause<FlatData>,
+): Promise<FlatData>;
+```
+
+**Примеры**
+
+Замена документа по идентификатору.
+
+```js
+// исходный документ
+// {
+//   id: 1,
+//   name: 'Laptop',
+//   price: 1200,
+//   inStock: true
+// }
+
+const updatedProduct = await productRep.replaceById(1, {
+  name: 'Laptop Pro',
+  price: 1500,
 });
+console.log(updatedProduct);
+// {
+//   id: 1,
+//   name: 'Laptop Pro',
+//   price: 1500
+// }
+// свойство "inStock" удалено
+```
+
+### repository.replaceOrCreate
+
+Заменяет существующий документ, если в переданных данных присутствует
+идентификатор, который уже существует в коллекции. В противном случае,
+если идентификатор не указан или не найден, создает новый документ.
+
+Сигнатура:
+
+```ts
+replaceOrCreate(
+  data: WithOptionalId<FlatData, IdName>,
+  filter?: ItemFilterClause<FlatData>,
+): Promise<FlatData>;
+```
+
+**Примеры**
 
-console.log(res);
+Создание нового документа, если `id: 3` не существует.
+
+```js
+const product = await productRep.replaceOrCreate({
+  id: 3,
+  name: 'Keyboard',
+  price: 75,
+});
+console.log(product);
 // {
-//   "id": 1,
-//   "name": "Russia",
-//   "population": 143400000,
+//   id: 3,
+//   name: 'Keyboard',
+//   price: 75,
 // }
 ```
 
-Поиск документа по идентификатору.
+Замена существующего документа с `id: 1`.
 
 ```js
-const res = await countryRep.findById(1);
+const updatedProduct = await productRep.replaceOrCreate({
+  id: 1,
+  name: 'Laptop Pro',
+  price: 1500,
+});
+console.log(updatedProduct);
+// {
+//   id: 1,
+//   name: 'Laptop Pro',
+//   price: 1500,
+// }
+```
+
+### repository.patchById
+
+Частично обновляет существующий документ по его идентификатору, изменяя
+только переданные поля. Остальные поля документа остаются без изменений.
 
-console.log(res);
+Сигнатура:
+
+```ts
+patchById(
+  id: IdType,
+  data: PartialWithoutId<FlatData, IdName>,
+  filter?: ItemFilterClause<FlatData>,
+): Promise<FlatData>;
+```
+
+**Примеры**
+
+Частичное обновление документа по идентификатору.
+
+```js
+// исходный документ с id: 1
+// {
+//   id: 1,
+//   name: 'Laptop Pro',
+//   price: 1500
+// }
+
+const updatedProduct = await productRep.patchById(1, {
+  price: 1450,
+});
+console.log(updatedProduct);
 // {
-//   "id": 1,
-//   "name": "Russia",
-//   "population": 143400000,
+//   id: 1,
+//   name: 'Laptop Pro',
+//   price: 1450
 // }
 ```
 
-Удаление документа по идентификатору.
+### repository.patch
+
+Частично обновляет один или несколько документов, соответствующих условиям
+`where`. Изменяются только переданные поля, остальные остаются без изменений.
+Возвращает количество обновленных документов. Если `where` не указан,
+обновляет все документы в коллекции.
+
+Сигнатура:
+
+```ts
+patch(
+  data: PartialWithoutId<FlatData, IdName>,
+  where?: WhereClause<FlatData>,
+): Promise<number>;
+```
+
+**Примеры**
+
+Обновление документов по условию.
+
+```js
+// обновит все товары с ценой меньше 30
+const updatedCount = await productRep.patch(
+  {inStock: false},
+  {price: {lt: 30}},
+);
+```
+
+Обновление всех документов.
+
+```js
+// добавит или обновит поле updatedAt для всех документов
+const totalCount = await productRep.patch({
+  updatedAt: new Date(),
+});
+```
+
+### repository.find
+
+Находит все документы, соответствующие условиям фильтрации, и возвращает их
+в виде массива. Если фильтр не указан, возвращает все документы коллекции.
+
+Сигнатура:
+
+```ts
+find(filter?: FilterClause<FlatData>): Promise<FlatData[]>;
+```
+
+**Примеры**
+
+Поиск всех документов.
+
+```js
+const allProducts = await productRep.find();
+```
+
+Поиск документов по условию `where`.
+
+```js
+const cheapProducts = await productRep.find({
+  where: {price: {lt: 100}},
+});
+```
+
+Поиск с сортировкой и ограничением выборки.
+
+```js
+const latestProducts = await productRep.find({
+  order: 'createdAt DESC',
+  limit: 10,
+});
+```
+
+### repository.findOne
+
+Находит первый документ, соответствующий условиям фильтрации. Возвращает
+`undefined`, если документы не найдены.
+
+Сигнатура:
+
+```ts
+findOne(
+  filter?: FilterClause<FlatData>,
+): Promise<FlatData | undefined>;
+```
+
+**Примеры**
+
+Поиск одного документа по условию.
+
+```js
+const expensiveProduct = await productRep.findOne({
+  where: {price: {gt: 1000}},
+  order: 'price DESC',
+});
+```
+
+Обработка случая, когда документ не найден.
 
 ```js
-const res = await countryRep.deleteById(1);
+const product = await productRep.findOne({
+  where: {name: 'Non-existent Product'},
+});
+if (!product) {
+  console.log('Product not found.');
+}
+```
+
+### repository.findById
+
+Находит один документ по его уникальному идентификатору. Если документ не
+найден, выбрасывается ошибка.
 
-console.log(res); // true
+Сигнатура:
+
+```ts
+findById(
+  id: IdType,
+  filter?: ItemFilterClause<FlatData>,
+): Promise<FlatData>;
+```
+
+**Примеры**
+
+Поиск документа по `id`.
+
+```js
+try {
+  const product = await productRep.findById(1);
+  console.log(product);
+} catch (error) {
+  console.error('Product with id 1 is not found.');
+}
+```
+
+Поиск документа с включением связанных данных.
+
+```js
+const product = await productRep.findById(1, {
+  include: 'category',
+});
+```
+
+### repository.delete
+
+Удаляет один или несколько документов, соответствующих условиям `where`.
+Возвращает количество удаленных документов. Если `where` не указан, удаляет
+все документы в коллекции.
+
+Сигнатура:
+
+```ts
+delete(where?: WhereClause<FlatData>): Promise<number>;
+```
+
+**Примеры**
+
+Удаление документов по условию.
+
+```js
+const deletedCount = await productRep.delete({
+  inStock: false,
+});
+```
+
+Удаление всех документов.
+
+```js
+const totalCount = await productRep.delete();
+```
+
+### repository.deleteById
+
+Удаляет один документ по его уникальному идентификатору. Возвращает `true`,
+если документ был найден и удален, в противном случае `false`.
+
+Сигнатура:
+
+```ts
+deleteById(id: IdType): Promise<boolean>;
+```
+
+**Примеры**
+
+Удаление документа по `id`.
+
+```js
+const wasDeleted = await productRep.deleteById(1);
+if (wasDeleted) {
+  console.log('The document was deleted.');
+} else {
+  console.log('No document found to delete.');
+}
+```
+
+### repository.exists
+
+Проверяет существование документа с указанным идентификатором. Возвращает
+`true`, если документ существует, иначе `false`.
+
+Сигнатура:
+
+```ts
+exists(id: IdType): Promise<boolean>;
+```
+
+**Примеры**
+
+Проверка существования документа по `id`.
+
+```js
+const productExists = await productRep.exists(1);
+if (productExists) {
+  console.log('A document with id 1 exists.');
+}
+```
+
+### repository.count
+
+Подсчитывает количество документов, соответствующих условиям `where`. Если
+`where` не указан, возвращает общее количество документов в коллекции.
+
+Сигнатура:
+
+```ts
+count(where?: WhereClause<FlatData>): Promise<number>;
+```
+
+**Примеры**
+
+Подсчет документов по условию.
+
+```js
+const cheapCount = await productRep.count({
+  price: {lt: 100},
+});
+```
+
+Подсчет всех документов.
+
+```js
+const totalCount = await productRep.count();
 ```
 
 ## Фильтрация
@@ -1488,6 +2021,28 @@ const res = await rep.find({
 в методах репозитория. Ниже приводится пример автоматического разрешения
 связи при использовании метода `findById`.
 
+```
+         Роль (role)
+      ┌────────────────────┐
+      │  id: 3  <──────────│────┐
+      │  name: 'Manager'   │    │
+      └────────────────────┘    │
+                                │
+     Пользователь (user)        │
+  ┌────────────────────────┐    │
+  │  id: 1                 │    │
+  │  name: 'John Doe'      │    │
+  │  roleId: 3   ──────────│────┘
+  │  cityId: 24  ──────────│────┐
+  └────────────────────────┘    │
+                                │
+         Город (city)           │
+      ┌────────────────────┐    │
+      │  id: 24  <─────────│────┘
+      │  name: 'Moscow'    │
+      └────────────────────┘
+```
+
 ```js
 // запрос документа коллекции "users",
 // включая связанные данные (role и city)
@@ -1519,8 +2074,11 @@ console.log(user);
 связи можно будет использовать в опции `include` методах репозитория.
 
 ```js
-import {DataType} from '@e22m4u/js-repository';
-import {RelationType} from '@e22m4u/js-repository';
+import {
+  DataType,
+  RelationType,
+  DatabaseSchema,
+} from '@e22m4u/js-repository';
 
 dbs.defineModel({
   name: 'user',
@@ -1560,12 +2118,29 @@ dbs.defineModel({
 *i. Полиморфный режим позволяет динамически определять целевую модель
 по ее названию, которое хранит документ в свойстве-дискриминаторе.*
 
-**Типы связи**
+### Типы связей
+
+- [Belongs To](#belongs-to)  
+  Текущая модель ссылается на целевую по идентификатору.  
+  `type: "belongsTo"` или `type: RelationType.BELONGS_TO`  
+  
+- [Has One](#has-one)  
+  Обратная сторона `belongsTo` по принципу *"один к одному"*.  
+  `type: "hasOne"` или `type: RelationType.HAS_ONE`  
 
-- `belongsTo` - текущая модель ссылается на целевую по идентификатору;
-- `hasOne` - обратная сторона `belongsTo` по принципу "один к одному";
-- `hasMany` - обратная сторона `belongsTo` по принципу "один ко многим";
-- `referencesMany` - модель ссылается через массив идентификаторов;
+- [Has Many](#has-many)  
+  Обратная сторона `belongsTo` по принципу *"один ко многим"*.  
+  `type: "hasMany"` или `type: RelationType.HAS_MANY`  
+
+- [References Many](#references-many)  
+  Текущая модель ссылается на целевую через массив идентификаторов.  
+  `type: "referencesMany"` или `type: RelationType.REFERENCES_MANY`  
+
+Полиморфные версии:
+
+- [Belongs To (полиморфная)](#belongs-to-полиморфная-версия)
+- [Has One (полиморфная)](#has-one-полиморфная-версия)
+- [Has Many (полиморфная)](#has-many-полиморфная-версия)
 
 Параметр `type` в определении связи принимает строку с названием типа. Чтобы исключить опечатку, рекомендуется использовать константы объекта `RelationType`
 указанные ниже.
@@ -1575,9 +2150,25 @@ dbs.defineModel({
 - `RelationType.HAS_MANY`
 - `RelationType.REFERENCES_MANY`
 
-**Примеры**
+#### Belongs To
+
+Текущая модель ссылается на целевую по идентификатору.
+
+```
+    Текущая (user)                  Целевая (role)
+┌─────────────────────────┐       ┌─────────────────────────┐
+│   id: 1                 │   ┌───│─> id: 5                 │
+│   roleId: 5  ───────────│───┤   │   ...                   │
+│   ...                   │   │   └─────────────────────────┘
+└─────────────────────────┘   │ 
+┌─────────────────────────┐   │   
+│   id: 2                 │   │
+│   roleId: 5  ───────────│───┘   
+│   ...                   │       
+└─────────────────────────┘       
+```
 
-Объявление связи `belongsTo`.
+Определение связи:
 
 ```js
 dbs.defineModel({
@@ -1595,24 +2186,191 @@ dbs.defineModel({
 });
 ```
 
-Объявление связи `hasMany`.
+Пример:
+
+```js
+import {
+  DataType,
+  RelationType,
+  DatabaseSchema,
+} from '@e22m4u/js-repository';
+
+const dbs = new DatabaseSchema();
+
+// источник данных
+dbs.defineDatasource({
+  name: 'myDb',
+  adapter: 'memory',
+});
+
+// модель роли
+dbs.defineModel({
+  name: 'role',
+  datasource: 'myDb',
+  properties: {
+    name: DataType.STRING,
+  },
+});
+
+// модель пользователя
+dbs.defineModel({
+  name: 'user',
+  datasource: 'myDb',
+  properties: {
+    name: DataType.STRING,
+    roleId: DataType.NUMBER, // не обязательно
+  },
+  relations: {
+    role: {
+      type: RelationType.BELONGS_TO,
+      model: 'role',
+      foreignKey: 'roleId', // не обязательно
+    },
+  },
+});
+
+// создание роли
+const roleRep = dbs.getRepository('role');
+const role = await roleRep.create({
+  id: 5,
+  name: 'Manager',
+});
+console.log(role);
+// {
+//   id: 5,
+//   name: 'manager'
+// }
+
+// создание пользователя
+const userRep = dbs.getRepository('user');
+const user = await userRep.create({
+  id: 1,
+  name: 'John Doe',
+  roleId: role.id,
+});
+console.log(user);
+// {
+//   id: 1,
+//   name: 'John Doe',
+//   roleId: 5
+// }
+
+// извлечение пользователя и связанной роли (опция "include")
+const userWithRole = await userRep.findById(user.id, {include: 'role'});
+console.log(userWithRole);
+// {
+//   id: 1,
+//   name: 'John Doe',
+//   roleId: 5,
+//   role: {
+//     id: 5,
+//     name: 'Manager'
+//   }
+// }
+```
+
+#### Has One
+
+Обратная сторона `belongsTo` по принципу *"один к одному"*.
+
+```
+    Текущая (profile)               Целевая (user)
+┌─────────────────────────┐       ┌─────────────────────────┐
+│   id: 5  <──────────────│───┐   │   id: 1                 │
+│   ...                   │   └───│── profileId: 5          │
+└─────────────────────────┘       │   ...                   │
+                                  └─────────────────────────┘
+```
+
+Определение связи:
+
+```js
+// dbs.defineModel({
+//   name: 'user',
+//   relations: {
+//     profile: {
+//       type: RelationType.BELONGS_TO,
+//       model: 'profile',
+//     },
+//   },
+// });
+
+dbs.defineModel({
+  name: 'profile',
+  relations: {
+    user: { // название связи
+      type: RelationType.HAS_ONE, // целевая модель ссылается на текущую
+      model: 'user', // название целевой модели
+      foreignKey: 'profileId', // внешний ключ из целевой модели на текущую
+    },
+  },
+});
+```
+
+#### Has Many
+
+Обратная сторона `belongsTo` по принципу *"один ко многим"*.
+
+```
+    Текущая (role)                  Целевая (user)
+┌─────────────────────────┐       ┌─────────────────────────┐
+│   id: 5  <──────────────│───┐   │   id: 1                 │
+│   ...                   │   ├───│── roleId: 5             │
+└─────────────────────────┘   │   │   ...                   │
+                              │   └─────────────────────────┘
+                              │   ┌─────────────────────────┐
+                              │   │   id: 2                 │
+                              └───│── roleId: 5             │
+                                  │   ...                   │
+                                  └─────────────────────────┘
+```
+
+Определение связи:
 
 ```js
+// dbs.defineModel({
+//   name: 'user',
+//   relations: {
+//     role: {
+//       type: RelationType.BELONGS_TO,
+//       model: 'role',
+//     },
+//   },
+// });
+
 dbs.defineModel({
   name: 'role',
   relations: {
     users: { // название связи
       type: RelationType.HAS_MANY, // целевая модель ссылается на текущую
       model: 'user', // название целевой модели
-      foreignKey: 'roleId', // внешний ключ из целевой модели на текущую
+      foreignKey: 'roleId', // внешний ключ целевой модели
     },
   },
 });
 ```
 
-Объявление связи `referencesMany`.
+#### References Many
+
+Текущая модель ссылается на целевую через массив идентификаторов.
+
+```
+    Текущая (article)                 Целевая (category)
+┌─────────────────────────┐       ┌─────────────────────────┐
+│   id: 1                 │   ┌───│─> id: 5                 │
+│   categoryIds: [5, 6] ──│───┤   │   ...                   │
+│   ...                   │   │   └─────────────────────────┘
+└─────────────────────────┘   │   ┌─────────────────────────┐
+                              └───│─> id: 6                 │
+                                  │   ...                   │
+                                  └─────────────────────────┘
+```
+
+Определение связи:
 
 ```js
+// dbs.defineModel({name: 'category', ...
+
 dbs.defineModel({
   name: 'article',
   relations: {
@@ -1628,7 +2386,27 @@ dbs.defineModel({
 });
 ```
 
-Полиморфная версия `belongsTo`.
+#### Belongs To (полиморфная версия)
+
+Текущая модель ссылается на целевую по идентификатору. Название целевой модели
+определяется свойством-дискриминатором.
+
+```
+    Текущая (file)               ┌──────> Целевая 1 (letter)
+┌─────────────────────────────┐  │    ┌─────────────────────────┐
+│   id: 1                     │  │ ┌──│─> id: 10                │
+│   referenceType: 'letter'  ─│──┘ │  │   ...                   │
+│   referenceId: 10  ─────────│────┘  └─────────────────────────┘
+└─────────────────────────────┘
+                                 ┌──────> Целевая 2 (user)
+┌─────────────────────────────┐  │    ┌─────────────────────────┐
+│   id: 2                     │  │ ┌──│─> id: 5                 │
+│   referenceType: 'user'  ───│──┘ │  │   ...                   │
+│   referenceId: 5  ──────────│────┘  └─────────────────────────┘
+└─────────────────────────────┘
+```
+
+Определение связи:
 
 ```js
 dbs.defineModel({
@@ -1647,7 +2425,7 @@ dbs.defineModel({
 });
 ```
 
-Полиморфная версия `belongsTo` с указанием свойств.
+Определение связи с указанием свойств:
 
 ```js
 dbs.defineModel({
@@ -1663,9 +2441,104 @@ dbs.defineModel({
 });
 ```
 
-Полиморфная версия `hasMany` с указанием названия связи целевой модели.
+#### Has One (полиморфная версия)
+
+Обратная сторона полиморфная связи `belongsTo` по принципу *"один к одному"*.
+
+```
+    Текущая (company)  <───────┐      Целевая (license)
+┌─────────────────────────┐    │  ┌─────────────────────────┐
+│   id: 10  <─────────────│──┐ │  │   id: 1                 │
+│   ...                   │  │ └──│── ownerType: 'company'  │
+└─────────────────────────┘  └────│── ownerId: 10           │
+                                  └─────────────────────────┘
+```
+
+Определение связи с указанием названия связи целевой модели:
+
+```js
+// dbs.defineModel({
+//   name: 'license',
+//   relations: {
+//     owner: {
+//       type: RelationType.BELONGS_TO,
+//       polymorphic: true,
+//     },
+//   },
+// });
+
+dbs.defineModel({
+  name: 'company',
+  relations: {
+    license: { // название связи
+      type: RelationType.HAS_ONE, // целевая модель ссылается на текущую
+      model: 'license', // название целевой модели
+      polymorphic: 'owner', // название полиморфной связи целевой модели
+    },
+  },
+});
+```
+
+Определение связи с указанием свойств целевой модели:
+
+```js
+// dbs.defineModel({
+//   name: 'license',
+//   relations: {
+//     owner: {
+//       type: RelationType.BELONGS_TO,
+//       polymorphic: true,
+//       foreignKey: 'ownerId',
+//       discriminator: 'ownerType',
+//     },
+//   },
+// });
+
+dbs.defineModel({
+  name: 'company',
+  relations: {
+    license: { // название связи
+      type: RelationType.HAS_ONE, // целевая модель ссылается на текущую
+      model: 'license', // название целевой модели
+      polymorphic: true, // название текущей модели находится в дискриминаторе
+      foreignKey: 'ownerId', // свойство целевой модели для идентификатора
+      discriminator: 'ownerType', // свойство целевой модели для названия текущей
+    },
+  },
+});
+```
+
+#### Has Many (полиморфная версия)
+
+Обратная сторона полиморфная связи `belongsTo` по принципу *"один ко многим"*.
+
+```
+    Текущая (letter)  <─────────┐      Целевая (file)
+┌──────────────────────────┐    │  ┌────────────────────────────┐
+│   id: 10  <──────────────│──┐ │  │   id: 1                    │
+│   ...                    │  │ ├──│── referenceType: 'letter'  │
+└──────────────────────────┘  ├─│──│── referenceId: 10          │
+                              │ │  └────────────────────────────┘
+                              │ │  ┌────────────────────────────┐
+                              │ │  │   id: 2                    │
+                              │ └──│── referenceType: 'letter'  │
+                              └────│── referenceId: 10          │
+                                   └────────────────────────────┘
+```
+
+Определение связи с указанием названия связи целевой модели:
 
 ```js
+// dbs.defineModel({
+//   name: 'file',
+//   relations: {
+//     reference: {
+//       type: RelationType.BELONGS_TO,
+//       polymorphic: true,
+//     },
+//   },
+// });
+
 dbs.defineModel({
   name: 'letter',
   relations: {
@@ -1678,9 +2551,21 @@ dbs.defineModel({
 });
 ```
 
-Полиморфная версия `hasMany` с указанием свойств целевой модели.
+Определение связи с указанием свойств целевой модели:
 
 ```js
+// dbs.defineModel({
+//   name: 'file',
+//   relations: {
+//     reference: {
+//       type: RelationType.BELONGS_TO,
+//       polymorphic: true,
+//       foreignKey: 'referenceId',
+//       discriminator: 'referenceType',
+//     },
+//   },
+// });
+
 dbs.defineModel({
   name: 'letter',
   relations: {
@@ -1733,7 +2618,7 @@ class MyRepository extends Repository {
 // dbs.defineDatasource ...
 // dbs.defineModel ...
 
-dbs.get(RepositoryRegistry).setRepositoryCtor(MyRepository);
+dbs.getService(RepositoryRegistry).setRepositoryCtor(MyRepository);
 const rep = dbs.getRepository('model');
 console.log(rep instanceof MyRepository); // true
 ```
@@ -1752,7 +2637,6 @@ import {DatabaseSchema} from '@e22m4u/js-repository';
 
 // const dbs = new DatabaseSchema();
 // dbs.defineDatasource ...
-// dbs.defineModel ...
 
 // определение модели "city"
 dbs.defineModel({
@@ -1762,12 +2646,6 @@ dbs.defineModel({
     name: DataType.STRING,
     timeZone: DataType.STRING,
   },
-  relations: {
-    country: {
-      type: RelationType.BELONGS_TO,
-      model: 'country',
-    },
-  },
 });
 
 // определение интерфейса "city"
@@ -1775,15 +2653,26 @@ interface City {
   id: number;
   name?: string;
   timeZone?: string;
-  countryId?: number;
-  country?: Country;
 }
 
-// получаем репозиторий по названию модели
-// указывая ее тип и тип идентификатора
-const cityRep = dbs.getRepository<City, number>('city');
+// при получении репозитория нужной модели
+// можно указать тип документов
+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