@e22m4u/js-repository 0.0.41 → 0.1.0

package/README.md

@@ -1,6 +1,23 @@
 ## @e22m4u/js-repository
 
-Абстракция для работы с базами данных для Node.js
+Модуль для работы с базами данных для Node.js
+
+[API](https://e22m4u.github.io/js-repository/modules.html)
+
+- [Установка](#Установка)
+- [Описание](#Описание)
+- [Пример](#Пример)
+- [Схема](#Схема)
+- [Источник данных](#Источник-данных)
+- [Модель](#Модель)
+- [Свойства](#Свойства)
+- [Репозиторий](#Репозиторий)
+- [Фильтрация](#Фильтрация)
+- [Связи](#Связи)
+- [Расширение](#Расширение)
+- [TypeScript](#TypeScript)
+- [Тесты](#Тесты)
+- [Лицензия](#Лицензия)
 
 ## Установка
 
@@ -8,586 +25,510 @@
 npm install @e22m4u/js-repository
 ```
 
-Опционально устанавливаем адаптер. Например, если используется
-*MongoDB*, то для подключения потребуется добавить
-[адаптер mongodb](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter)
-как отдельную зависимость.
+Опционально устанавливаем адаптер.
 
-```bash
-npm install @e22m4u/js-repository-mongodb-adapter
-```
+|           | описание                                                                                                                       |
+|-----------|--------------------------------------------------------------------------------------------------------------------------------|
+| `memory`  | виртуальная база в памяти процесса (не требует установки)                                                                      |
+| `mongodb` | MongoDB - система управления NoSQL базами (*[установка](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter))* |
 
-**Список доступных адаптеров:**
+## Описание
 
-| адаптер   | описание                                                                                                                                        |
-|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------|
-| `memory`  | виртуальная база в памяти процесса (для разработки и тестирования)                                                                              |
-| `mongodb` | MongoDB - система управления NoSQL базами (*[требует установки](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter))* |
+Модуль позволяет объединить несколько баз данных в единую абстракцию «Схема».
 
-## Концепция
-
-Модуль позволяет спроектировать систему связанных данных, доступ к которым
-осуществляется посредством репозиториев. Каждый репозиторий имеет собственную
-модель данных, которая описывает структуру определенной коллекции в базе,
-а так же определяет связи к другим коллекциям.
+- *Источник данных* - определяет способ подключения к базе
+- *Модель* - описывает структуру документа и связи к другим моделям
+- *Репозиторий* - выполняет операции чтения и записи документов модели
 
 ```mermaid
-flowchart LR
-
-A[Datasource]-->B[Data Model]-->С[Repository];
+flowchart TD
+
+  A[Схема]
+  subgraph Базы данных
+    B[Источник данных 1]
+    C[Источник данных 2]
+  end
+  A-->B
+  A-->C
+
+  subgraph Коллекции
+    D[Модель A]
+    E[Модель Б]
+    F[Модель В]
+    G[Модель Г]
+  end
+  B-->D
+  B-->E
+  C-->F
+  C-->G
+
+  H[Репозиторий A]
+  I[Репозиторий Б]
+  J[Репозиторий В]
+  K[Репозиторий Г]
+  D-->H
+  E-->I
+  F-->J
+  G-->K
 ```
 
-## Использование
+## Пример
 
-Определения источников и моделей хранятся в экземпляре класса `Schema`,
-и первым шагом будет создание данного экземпляра.
+Определение источника данных, модели и добавление нового документа в коллекцию.
 
 ```js
 import {Schema} from '@e22m4u/js-repository';
+import {DataType} from '@e22m4u/js-repository';
 
+// создание экземпляра Schema
 const schema = new Schema();
+
+// определение источника "myMemory"
+schema.defineDatasource({
+  name: 'myMemory', // название нового источника
+  adapter: 'memory', // выбранный адаптер
+});
+
+// определение модели "country"
+schema.defineModel({
+  name: 'country', // название новой модели
+  datasource: 'myMemory', // выбранный источник
+  properties: { // свойства модели
+    name: DataType.STRING, // тип "string"
+    population: DataType.NUMBER, // тип "number"
+  },
+})
+
+// получение репозитория для модели "country"
+const countryRep = schema.getRepository('country');
+
+// добавление нового документа в коллекцию "country"
+const country = await countryRep.create({
+  name: 'Russia',
+  population: 143400000,
+});
+
+// вывод результата
+console.log(country);
+// {
+//   "id": 1,
+//   "name": "Russia",
+//   "population": 143400000,
+// }
 ```
 
-Интерфейс `Schema` содержит три основных метода:
+## Схема
+
+Экземпляр класса `Schema` хранит определения источников данных и моделей.
+
+**Методы**
 
 - `defineDatasource(datasourceDef: object): this` - добавить источник
 - `defineModel(modelDef: object): this` - добавить модель
 - `getRepository(modelName: string): Repository` - получить репозиторий
 
-### Источник данных
+**Примеры**
 
-Источник описывает способ подключения к базе и используемый адаптер.
-Если адаптер имеет настройки, то они передаются вместе с объектом
-определения источника методом `defineDatasource`, как это показано
-ниже.
+Импорт класса и создание экземпляра схемы.
 
 ```js
-schema.defineDatasource({
-  name: 'myMongo', // название нового источника
-  adapter: 'mongodb', // название выбранного адаптера
-  // настройки адаптера mongodb
-  host: '127.0.0.1',
-  port: 27017,
-  database: 'data'
-});
-```
-
-**Параметры источника:**
+import {Schema} from '@e22m4u/js-repository';
 
-- `name: string` уникальное название
-- `adapter: string` выбранный адаптер
+const schema = new Schema();
+```
 
-При желании можно использовать встроенный адаптер `memory`, который хранит
-данные в памяти процесса. У него нет специальных настроек, и он отлично
-подходит для тестов и прототипирования.
+Определение нового источника.
 
 ```js
 schema.defineDatasource({
-  name: 'myMemory', // название источника
+  name: 'myMemory', // название нового источника
   adapter: 'memory', // выбранный адаптер
 });
 ```
 
-### Модель данных
-
-Когда источники определены, можно перейти к описанию моделей данных.
-Модель может определять как структуру какого-либо объекта,
-так и являться отражением реальной коллекции базы.
-
-Представьте себе коллекцию торговых точек, у каждой из которых имеются
-координаты `lat` и `lng`. Мы можем заранее определить модель для
-объекта координат методом `defineModel` и использовать ее в других
-коллекциях.
+Определение новой модели.
 
 ```js
 schema.defineModel({
-  name: 'latLng', // название новой модели
-  properties: { // поля модели
-    lat: DataType.NUMBER, // поле широты
-    lng: DataType.NUMBER, // поле долготы
+  name: 'product', // название новой модели
+  datasource: 'myMemory', // выбранный источник
+  properties: { // свойства модели
+    name: DataType.STRING,
+    weight: DataType.NUMBER,
   },
 });
 ```
 
-**Параметры модели:**
-
-- `name: string` уникальное название (обязательно)
-- `datasource: string` выбранный источник данных
-- `properties: object` определения полей модели
-- `relations: object` определения связей модели
-
-Параметр `properties` принимает объект, ключи которого являются именами
-полей, а значением тип поля или объект с дополнительными параметрами.
+Получение репозитория по названию модели.
 
 ```js
-schema.defineModel({
-  name: 'latLng',
-  properties: {
-    lat: DataType.NUMBER, // краткое определение поля "lat"
-    lng: { // расширенное определение поля "lng"
-      type: DataType.NUMBER, // тип допустимого значения
-      required: true, // исключает null и undefined
-    },
-  },
-});
+const productRep = schema.getRepository('product');
 ```
 
-**Типы данных:**
+## Источник данных
+
+Источник хранит название выбранного адаптера и его настройки. Определить
+новый источник можно методом `defineDatasource` экземпляра схемы.
 
-- `DataType.ANY`
-- `DataType.STRING`
-- `DataType.NUMBER`
-- `DataType.BOOLEAN`
-- `DataType.ARRAY`
-- `DataType.OBJECT`
+**Параметры**
 
-Модель `latLng` всего лишь описывает структуру объекта координат, тогда
-как торговая точка должна иметь реальную таблицу в базе. По аналогии с
-предыдущим примером, добавим модель `place`, но дополнительно укажем
-источник данных в параметре `datasource`
+- `name: string` уникальное название
+- `adapter: string` выбранный адаптер
+- параметры адаптера (если имеются)
+
+**Примеры**
+
+Определение нового источника.
 
 ```js
-schema.defineModel({
-  name: 'place',
-  datasource: 'myMemory', // выбранный источник данных
-  properties: {
-    name: DataType.STRING, // поле для названия торговой точки
-    location: { // поле объекта координат
-      type: DataType.OBJECT, // допускать только объекты
-      model: 'latLng', // определение структуры объекта
-    },
-  },
+schema.defineDatasource({
+  name: 'myMemory', // название нового источника
+  adapter: 'memory', // выбранный адаптер
 });
 ```
 
-В примере выше мы использовали модель `latLng` как структуру допустимого
-значения поля `location`. Возможный документ данной коллекции может
-выглядеть так:
+Передача дополнительных параметров адаптера.
 
-```json
-{
-  "id": 1,
-  "name": "Burger King at Avenue Mall",
-  "location": {
-    "lat": 32.412891,
-    "lng": 34.7660061
-  }
-}
+```js
+schema.defineDatasource({
+  name: 'myMongodb',
+  adapter: 'mongodb',
+  // параметры адаптера "mongodb"
+  host: '127.0.0.1',
+  port: 27017,
+  database: 'myDatabase',
+});
 ```
 
-Стоит обратить внимание, что мы могли бы не объявлять параметр `properties`,
-при этом теряя возможность проверки данных перед записью в базу.
+## Модель
+
+Описывает структуру документа коллекции и связи к другим моделям. Определить
+новую модель можно методом `defineModel` экземпляра схемы.
+
+**Параметры**
+
+- `name: string` название модели (обязательно)
+- `base: string` название наследуемой модели
+- `tableName: string` название коллекции в базе
+- `datasource: string` выбранный источник данных
+- `properties: object` определения свойств (см. [Свойства](#Свойства))
+- `relations: object` определения связей (см. [Связи](#Связи))
+
+**Примеры**
+
+Определение модели со свойствами указанного типа.
 
 ```js
 schema.defineModel({
-  name: 'place',
-  adapter: 'myMemory',
-  // параметр "properties" не указан
+  name: 'user', // название новой модели
+  properties: { // свойства модели
+    name: DataType.STRING,
+    age: DataType.NUMBER,
+  },
 });
 ```
 
-**Параметры поля:**
+## Свойства
+
+Параметр `properties` находится в составе модели и принимает объект, ключи
+которого являются свойствами этой модели, а значением тип свойства или объект
+с дополнительными параметрами.
+
+**Тип данных**
+
+- `DataType.ANY` разрешено любое значение
+- `DataType.STRING` только значение типа `string`
+- `DataType.NUMBER` только значение типа `number`
+- `DataType.BOOLEAN` только значение типа `boolean`
+- `DataType.ARRAY` только значение типа `array`
+- `DataType.OBJECT` только значение типа `object`
+
+**Параметры**
 
 - `type: string` тип допустимого значения (обязательно)
 - `itemType: string` тип элемента массива (для `type: 'array'`)
 - `model: string` модель объекта (для `type: 'object'`)
-- `primaryKey: boolean` объявить поле первичным ключом
+- `primaryKey: boolean` объявить свойство первичным ключом
 - `columnName: string` переопределение названия колонки
 - `columnType: string` тип колонки (определяется адаптером)
-- `required: boolean` объявить поле обязательным
+- `required: boolean` объявить свойство обязательным
 - `default: any` значение по умолчанию
 
-### Репозиторий
+**Примеры**
 
-В отличие от `latLng`, модель `place` имеет источник данных с названием
-`myMemory`, который был объявлен ранее. Наличие источника позволяет получить
-репозиторий по названию модели.
+Краткое определение свойств модели.
 
 ```js
-const rep = schema.getRepository('place');
+schema.defineModel({
+  name: 'city',
+  properties: { // свойства модели
+    name: DataType.STRING, // тип свойства "string"
+    population: DataType.NUMBER, // тип свойства "number"
+  },
+});
 ```
 
-**Методы:**
-
-- `create(data, filter = undefined)`
-- `replaceById(id, data, filter = undefined)`
-- `replaceOrCreate(data, filter = undefined)`
-- `patch(data, where = undefined)`
-- `patchById(id, data, filter = 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)
-
-Создадим торговую точку методом `create` используя репозиторий из примера
-выше. Метод возвращает документ, который был записан в базу, включая присвоенный
-идентификатор.
+Расширенное определение свойств модели.
 
 ```js
-const place = await rep.create({
-  "name": "Burger King at Avenue Mall",
-  "location": {
-    "lat": 32.412891,
-    "lng": 34.7660061
+schema.defineModel({
+  name: 'city',
+  properties: { // свойства модели
+    name: {
+      type: DataType.STRING, // тип свойства "string" (обязательно)
+      required: true, // исключение значений undefined и null
+    },
+    population: {
+      type: DataType.NUMBER, // тип свойства "number" (обязательно)
+      default: 0, // значение по умолчанию
+    },
   },
 });
-
-console.log(place);
-// {
-//   "id": 1,
-//   "name": "Burger King at Avenue Mall",
-//   "location": {
-//     "lat": 32.412891,
-//     "lng": 34.7660061
-//   }
-// }
 ```
 
-#### replaceById(id, data, filter = undefined)
-
-Добавленный в базу документ можно полностью заменить зная его идентификатор.
-Воспользуемся методом `replaceById`, который перезапишет данные по значению
-первичного ключа.
+Фабричное значение по умолчанию. Возвращаемое значение функции будет
+определено в момент записи документа.
 
 ```js
-// {
-//   "id": 1,
-//   "name": "Burger King at Avenue Mall",
-//   "location": {
-//     "lat": 32.412891,
-//     "lng": 34.7660061
-//   }
-// }
-const result = rep.replaceById(place.id, {
-  name: 'Terminal 21 Shopping Mall',
-  address: 'Sukhumvit 19 Alley'
+schema.defineModel({
+  name: 'article',
+  properties: { // свойства модели
+    tags: {
+      type: DataType.ARRAY, // тип свойства "array" (обязательно)
+      itemType: DataType.STRING, // тип элемента "string"
+      default: () => [], // фабричное значение
+    },
+    createdAt: {
+      type: DataType.STRING, // тип свойства "string" (обязательно)
+      default: () => new Date().toISOString(), // фабричное значение
+    },
+  },
 });
-
-console.log(result);
-// {
-//   "id": 1,
-//   "name": "Terminal 21 Shopping Mall",
-//   "address": "Sukhumvit 19 Alley"
-// }
 ```
 
-#### patchById(id, data, filter = undefined)
+## Репозиторий
 
-В отличие от `replaceById`, данный метод не удаляет поля, которые
-не были переданы, что позволяет обновить только часть документа,
-не затрагивая другие данные.
+Выполняет операции чтения и записи документов определенной модели.
+Получить репозиторий можно методом `getRepository` экземпляра схемы.
 
-```js
-// {
-//   "id": 1,
-//   "name": "Terminal 21 Shopping Mall",
-//   "address": "Sukhumvit 19 Alley"
-// }
-const result = rep.patchById(place.id, {
-  address: 'Moo 6',
-  city: 'Pattaya',
-});
+**Методы**
 
-console.log(result);
-// {
-//   "id": 1,
-//   "name": "Terminal 21 Shopping Mall",
-//   "address": "Moo 6",
-//   "city": "Pattaya"
-// }
-```
+- `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)` подсчет всех документов или по условию
 
-## Пример
+**Аргументы**
 
-Создаем модель `user`
+- `id: number|string` идентификатор (первичный ключ)
+- `data: object` объект отражающий состав документа
+- `where: object` параметры выборки (см. [Фильтрация](#Фильтрация))
+- `filter: object` параметры возвращаемого результата (см. [Фильтрация](#Фильтрация))
 
-```js
-schema.defineModel({
-  name: 'user', // название модели
-  adapter: 'myMemory', // выбранный источник
-  properties: { // поля модели
-    name: 'string',
-    age: 'number',
-  },
-});
-```
+**Примеры**
 
-Получаем репозиторий модели `user`
+Получение репозитория по названию модели.
 
 ```js
-const userRep = schema.getRepository('user');
+const countryRep = schema.getRepository('country');
 ```
 
-Добавляем новую запись методом `create`
+Добавление нового документа в коллекцию.
 
 ```js
-const fedor = await userRep.create({
-  name: 'Fedor',
-  age: 24,
+const res = await countryRep.create({
+  name: 'Russia',
+  population: 143400000,
 });
 
-console.log(fedor);
+console.log(res);
 // {
-//   id: 1,
-//   name: 'Fedor',
-//   age: 24,
+//   "id": 1,
+//   "name": "Russia",
+//   "population": 143400000,
 // }
 ```
 
-Изменяем данные методом `patchById`
+Поиск документа по идентификатору.
 
 ```js
-const result = await userRep.patchById(
-  fedor.id,
-  {age: 30},
-);
+const res = await countryRep.findById(1);
 
-console.log(result);
+console.log(res);
 // {
-//   id: 1,
-//   name: 'Fedor',
-//   age: 30,
+//   "id": 1,
+//   "name": "Russia",
+//   "population": 143400000,
 // }
 ```
 
-Удаляем по идентификатору методом `deleteById`
+Удаление документа по идентификатору.
 
 ```js
-await userRep.deleteById(fedor.id); // true
+const res = await countryRep.deleteById(1);
+
+console.log(res); // true
 ```
 
-## Репозиторий
+## Фильтрация
 
-Выполняет операции чтения и записи определенной коллекции.
+Некоторые методы репозитория принимают объект настроек влияющий
+на возвращаемый результат. Максимально широкий набор таких настроек
+имеет первый параметр метода `find`, где ожидается объект содержащий
+набор опций указанных ниже.
 
-Методы:
+- `where: object` объект выборки
+- `order: string[]` указание порядка
+- `limit: number` ограничение количества документов
+- `skip: number` пропуск документов
+- `fields: string[]` выбор необходимых свойств модели
+- `include: object` включение связанных данных в результат
 
-- `create(data, filter = undefined)`
-- `replaceById(id, data, filter = undefined)`
-- `replaceOrCreate(data, filter = undefined)`
-- `patch(data, where = undefined)`
-- `patchById(id, data, filter = undefined)`
-- `find(filter = undefined)`
-- `findOne(filter = undefined)`
-- `findById(id, filter = undefined)`
-- `delete(where = undefined)`
-- `deleteById(id)`
-- `exists(id)`
-- `count(where = undefined)`
+### where
 
-Получение репозитория модели:
+Параметр принимает объект с условиями выборки и поддерживает широкий
+набор операторов сравнения.
 
-```js
-import {Schema} from '@e22m4u/js-repository';
+`{foo: 'bar'}` поиск по значению свойства `foo`  
+`{foo: {eq: 'bar'}}` оператор равенства `eq`  
+`{foo: {neq: 'bar'}}` оператор неравенства `neq`  
+`{foo: {gt: 5}}` оператор "больше" `gt`  
+`{foo: {lt: 10}}` оператор "меньше" `lt`  
+`{foo: {gte: 5}}` оператор "больше или равно" `gte`  
+`{foo: {lte: 10}}` оператор "меньше или равно" `lte`  
+`{foo: {inq: ['bar', 'baz']}}` равенство одного из значений `inq`  
+`{foo: {nin: ['bar', 'baz']}}` исключение значений массива `nin`  
+`{foo: {between: [5, 10]}}` оператор диапазона `between`  
+`{foo: {exists: true}}` оператор наличия значения `exists`  
+`{foo: {like: 'bar'}}` оператор поиска подстроки `like`  
+`{foo: {ilike: 'BaR'}}` регистронезависимая версия `ilike`  
+`{foo: {nlike: 'bar'}}` оператор исключения подстроки `nlike`  
+`{foo: {nilike: 'BaR'}}` регистронезависимая версия `nilike`  
+`{foo: {regexp: 'ba.+'}}` оператор регулярного выражения `regexp`  
+`{foo: {regexp: 'ba.+', flags: 'i'}}` флаги регулярного выражения
 
-const schema = new Schema();
-// создаем источник
-schema.defineDatasource({name: 'myDatasource', adapter: 'memory'});
-// создаем модель
-schema.defineModel({name: 'myModel', datasource: 'myDatasource'});
-// получаем репозиторий по названию модели
-const repositorty = schema.getRepository('myModel');
-```
+*i. Условия можно объединять операторами `and`, `or` и `nor`.*
 
-Переопределение конструктора:
+**Примеры**
 
-```js
-import {Schema} from '@e22m4u/js-repository';
-import {Repository} from '@e22m4u/js-repository';
-import {RepositoryRegistry} from '@e22m4u/js-repository';
+Применение условий выборки при подсчете документов.
 
-class MyRepository extends Repository {
-  /*...*/
-}
+```js
+const res = await rep.count({
+  authorId: 251,
+  publishedAt: {
+    lte: '2023-12-02T14:00:00.000Z',
+  },
+});
+```
 
-const schema = new Schema();
-schema.get(RepositoryRegistry).setRepositoryCtor(MyRepository);
-// теперь schema.getRepository(modelName) будет возвращать
-// экземпляр класса MyRepository
-```
-
-### Filter
-
-Большинство методов репозитория принимают объект `filter` для
-фильтрации возвращаемого ответа. Описание параметров объекта:
-
-- **where** *(условия выборки данных из базы)*  
-  примеры:  
-  `where: {foo: 'bar'}` поиск по значению поля `foo`  
-  `where: {foo: {eq: 'bar'}}` оператор равенства `eq`  
-  `where: {foo: {neq: 'bar'}}` оператор неравенства `neq`  
-  `where: {foo: {gt: 5}}` оператор "больше" `gt`  
-  `where: {foo: {lt: 10}}` оператор "меньше" `lt`  
-  `where: {foo: {gte: 5}}` оператор "больше или равно" `gte`  
-  `where: {foo: {lte: 10}}` оператор "меньше или равно" `lte`  
-  `where: {foo: {inq: ['bar', 'baz']}}` равенство одного из значений `inq`  
-  `where: {foo: {nin: ['bar', 'baz']}}` исключение значений массива `nin`  
-  `where: {foo: {between: [5, 10]}}` оператор диапазона `between`  
-  `where: {foo: {exists: true}}` оператор наличия значения `exists`  
-  `where: {foo: {like: 'bar'}}` оператор поиска подстроки `like`  
-  `where: {foo: {ilike: 'BaR'}}` регистронезависимая версия `ilike`  
-  `where: {foo: {nlike: 'bar'}}` оператор исключения подстроки `nlike`  
-  `where: {foo: {nilike: 'BaR'}}` регистронезависимая версия `nilike`  
-  `where: {foo: {regexp: 'ba.+'}}` оператор регулярного выражения `regexp`  
-  `where: {foo: {regexp: 'ba.+', flags: 'i'}}` флаги регулярного выражения
-
-
-- **order** *(упорядочить записи по полю)*  
-  примеры:  
-  `order: 'foo'` порядок по полю `foo`  
-  `order: 'foo ASC'` явное указание порядка  
-  `order: 'foo DESC'` инвертировать порядок  
-  `order: ['foo', 'bar ASC', 'baz DESC']` по нескольким полям
-
-
-- **limit** *(не более N записей)*  
-  примеры:  
-  `limit: 0` не ограничивать  
-  `limit: 14` не более 14-и
-
-
-- **skip** *(пропуск первых N записей)*  
-  примеры:  
-  `skip: 0` выборка без пропуска  
-  `skip: 10` пропустить 10 объектов выборки
-
-
-- **include** *(включение связанных данных в результат)*  
-  примеры:  
-  `include: 'foo'` включение связи `foo`  
-  `include: ['foo', 'bar']` включение `foo` и `bar`  
-  `include: {foo: 'bar'}` включение вложенной связи `foo`
+Применение оператора `or` при удалении документов.
 
-## Источник данных
+```js
+const res = await rep.delete({
+  or: [
+    {draft: true},
+    {title: {like: 'draft'}},
+  ],
+});
+```
 
-Определяет настройки и способ подключения к базе.
+### order
 
-Параметры:
+Параметр упорядочивает выборку по указанным свойствам модели. Обратное
+направление порядка можно задать постфиксом `DESC` в названии свойства.
 
-- `name: string` название нового источника
-- `adapter: string` выбранный адаптер базы данных
+**Примеры**
 
-Пример:
+Упорядочить по полю `createdAt`
 
 ```js
-schema.defineDatasource({
-  name: 'myDatasource',
-  adapter: 'memory',
+const res = await rep.find({
+  order: 'createdAt',
 });
 ```
 
-Адаптер может иметь параметры, которые передаются
-при определении источника.
+Упорядочить по полю `createdAt` в обратном порядке.
 
-Пример:
+```js
+const res = await rep.find({
+  order: 'createdAt DESC',
+});
+```
+
+Упорядочить по нескольким свойствам в разных направлениях.
 
 ```js
-schema.defineDatasource({
-  name: 'myDatasource',
-  adapter: 'mongodb',
-  // параметры адаптера:
-  host: '127.0.0.1',
-  port: 27017,
+const res = await rep.find({
+  order: [
+    'title',
+    'price ASC',
+    'featured DESC',
+  ],
 });
 ```
 
-## Модель
+*i. Направление порядка `ASC` указывать необязательно.*
 
-Описывает набор полей и связей к другим моделям.
+### include
 
-Параметры:
+Параметр включает связанные документы в результат вызываемого метода.
+Названия включаемых связей должны быть определены в текущей модели.
+(см. [Связи](#Связи))
 
-- `name: string` название новой модели
-- `datasource: string` выбранный источник данных
-- `properties: object` определения полей модели
-- `relations: object` определения связей модели
+**Примеры**
 
-Пример:
+Включение связи по названию.
 
 ```js
-schema.defineModel({
-  name: 'myModel',
-  datasource: 'myDatasource',
-  properties: {...}, // см. ниже
-  relations: {...}, // см. ниже
+const res = await rep.find({
+  include: 'city',
 });
 ```
 
-## Поля
-
-Параметр `properties` описывает набор полей и их настройки.
-
-Типы:
-
-- `string`  
-- `number`  
-- `boolean`  
-- `array`  
-- `object`  
-- `any`  
-
-Пример:
+Включение вложенных связей.
 
 ```js
-schema.defineModel({
-  // ...
-  properties: {
-    prop1: 'string',
-    prop2: 'number',
-    prop3: 'boolean',
-    prop4: 'array',
-    prop5: 'object',
-    prop6: 'any',
+const res = await rep.find({
+  include: {
+    city: 'country',
   },
 });
 ```
 
-Расширенные параметры:
+Включение нескольких связей массивом.
 
-- `type: string` тип хранимого значения
-- `itemType: string` тип элемента массива (для `type: 'array'`)
-- `model: string` модель объекта (для `type: 'object'`)
-- `primaryKey: boolean` объявить поле первичным ключом 
-- `columnName: string` переопределение названия колонки
-- `columnType: string` тип колонки (определяется адаптером)
-- `required: boolean` объявить поле обязательным
-- `default: any` значение по умолчанию для `undefined`
+```js
+const res = await rep.find({
+  include: [
+    'city',
+    'address',
+    'employees'
+  ],
+});
+```
 
-Пример:
+Использование фильтрации включаемых документов.
 
 ```js
-schema.defineModel({
-  // ...
-  properties: {
-    prop1: {
-      type: 'string',
-      primaryKey: true,
-    },
-    prop2: {
-      type: 'boolean',
-      required: true,
-    },
-    prop3: {
-      type: 'number',
-      default: 100,
-    },
-    prop3: {
-      type: 'string',
-      // фабричное значение
-      default: () => new Date().toISOString(),
-    },
-    prop4: {
-      type: 'array',
-      itemType: 'string',
-    },
-    prop5: {
-      type: 'object',
-      model: 'objectModel',
+const res = await rep.find({
+  include: {
+    relation: 'employees', // название связи
+    scope: { // фильтрация документов "employees"
+      where: {hidden: false}, // условия выборки
+      order: 'id', // порядок документов
+      limit: 10, // ограничение количества
+      skip: 5, // пропуск документов
+      fields: ['name', 'surname'], // только указанные поля
+      include: 'city', // включение связей для "employees"
     },
   },
 });
@@ -595,188 +536,237 @@ schema.defineModel({
 
 ## Связи
 
-Параметр `relations` описывает набор связей к другим моделям.
-
-Понятия:
+Параметр `relations` находится в составе определения модели и принимает
+объект, ключ которого является названием связи, а значением объект
+с параметрами.
 
-- источник связи  
-*- модель в которой определена данная связь*  
-- целевая модель  
-*- модель на которую ссылается источник связи*  
-
-Типы:
-
-- `belongsTo` - ссылка на целевую модель находится в источнике
-- `hasOne` - ссылка на источник находится в целевой модели (one-to-one)
-- `hasMany` - ссылка на источник находится в целевой модели (one-to-many)
-- `referencesMany` - массив ссылок на целевую модель находится в источнике
-
-Параметры:
+**Параметры**
 
 - `type: string` тип связи
-- `model: string` целевая модель
-- `foreignKey: string` поле для идентификатора цели
+- `model: string` название целевой модели
+- `foreignKey: string` свойство текущей модели для идентификатора цели
 - `polymorphic: boolean|string` объявить связь полиморфной*
-- `discriminator: string` поле для названия целевой модели (для `polymorphic: true`)
+- `discriminator: string` свойство текущей модели для названия целевой*
+
+*i. Полиморфный режим позволяет динамически определять целевую модель
+по ее названию, которое хранит документ в свойстве-дискриминаторе.*
 
-*i. Полиморфный режим `belongsTo` позволяет динамически определять цель связи,
-где имя целевой модели хранится в отдельном поле, рядом с `foreignKey`*
+**Тип связи**
 
-#### BelongsTo
+- `belongsTo` - текущая модель содержит свойство для идентификатора цели
+- `hasOne` - обратная сторона `belongsTo` по принципу "один к одному"
+- `hasMany` - обратная сторона `belongsTo` по принципу "один ко многим"
+- `referencesMany` - документ содержит массив с идентификаторами целевой модели
 
-Связь заказа к покупателю через поле `customerId`
+**Примеры**
+
+Объявление связи `belongsTo`
 
 ```js
 schema.defineModel({
-  // ...
+  name: 'user',
   relations: {
-    // ...
-    customer: {
-      type: 'belongsTo',
-      model: 'customer',
-      foreignKey: 'customerId', // опционально
+    role: { // название связи
+      type: RelationType.BELONGS_TO, // текущая модель ссылается на целевую
+      model: 'role', // название целевой модели
+      foreignKey: 'roleId', // внешний ключ (необязательно)
+      // если "foreignKey" не указан, то свойство внешнего
+      // ключа формируется согласно названию связи
+      // с добавлением постфикса "Id"
     },
   },
 });
 ```
 
-Полиморфная версия
+Объявление связи `hasMany`
 
 ```js
 schema.defineModel({
-  // ...
+  name: 'role',
   relations: {
-    // ...
-    customer: {
-      type: 'belongsTo',
-      polymorphic: true,
-      foreignKey: 'customerId', // опционально
-      discriminator: 'customerType', // опционально
+    users: { // название связи
+      type: RelationType.HAS_MANY, // целевая модель ссылается на текущую
+      model: 'user', // название целевой модели
+      foreignKey: 'roleId', // внешний ключ из целевой модели на текущую
     },
   },
 });
 ```
 
-#### HasOne (one-to-one)
-
-Связь покупателя к заказу, как обратная сторона `belongsTo`
+Объявление связи `referencesMany`
 
 ```js
 schema.defineModel({
-  // ...
+  name: 'article',
   relations: {
-    // ...
-    order: {
-      type: 'hasOne',
-      model: 'order',
-      foreignKey: 'customerId', // опционально
+    categories: { // название связи
+      type: RelationType.REFERENCES_MANY, // связь через массив идентификаторов
+      model: 'category', // название целевой модели
+      foreignKey: 'categoryIds', // внешний ключ (необязательно)
+      // если "foreignKey" не указан, то свойство внешнего
+      // ключа формируется согласно названию связи
+      // с добавлением постфикса "Ids"
     },
   },
 });
 ```
 
-Обратная сторона полиморфной версии `belongsTo`
+Полиморфная версия `belongsTo`
 
 ```js
 schema.defineModel({
-  // ...
+  name: 'file',
   relations: {
-    // ...
-    order: {
-      type: 'hasOne',
-      model: 'order',
-      polymorphic: 'customer', // имя связи целевой модели
+    reference: { // название связи
+      type: RelationType.BELONGS_TO, // текущая модель ссылается на целевую
+      // полиморфный режим позволяет хранить название целевой модели
+      // в свойстве-дискриминаторе, которое формируется согласно
+      // названию связи с постфиксом "Type", и в данном случае
+      // название целевой модели хранит "referenceType",
+      // а идентификатор документа "referenceId"
+      polymorphic: true,
     },
   },
 });
 ```
 
-Явное указание `foreignKey` и `discriminator`
+Полиморфная версия `belongsTo` с указанием свойств.
 
 ```js
 schema.defineModel({
-  // ...
+  name: 'file',
   relations: {
-    // ...
-    order: {
-      type: 'hasOne',
-      model: 'order',
-      polymorphic: true, // true вместо имени модели
-      foreignKey: 'customerId', // поле целевой модели 
-      discriminator: 'customerType', // поле целевой модели
+    reference: { // название связи
+      type: RelationType.BELONGS_TO, // текущая модель ссылается на целевую
+      polymorphic: true, // название целевой модели хранит дискриминатор
+      foreignKey: 'referenceId', // свойство для идентификатора цели
+      discriminator: 'referenceType', // свойство для названия целевой модели
     },
   },
-});
+})
 ```
 
-#### HasMany (one-to-many)
-
-Связь покупателя к заказам, как обратная сторона `belongsTo`
+Полиморфная версия `hasMany` с указанием названия связи целевой модели.
 
 ```js
 schema.defineModel({
-  // ...
+  name: 'letter',
   relations: {
-    // ...
-    orders: {
-      type: 'hasMany',
-      model: 'order',
-      foreignKey: 'customerId', // опционально
+    attachments: { // название связи
+      type: RelationType.HAS_MANY, // целевая модель ссылается на текущую
+      model: 'file', // название целевой модели
+      polymorphic: 'reference', // название полиморфной связи целевой модели
     },
   },
-});
+})
 ```
 
-Обратная сторона полиморфной версии `belongsTo`
+Полиморфная версия `hasMany` с указанием свойств целевой модели.
 
 ```js
 schema.defineModel({
-  // ...
+  name: 'letter',
   relations: {
-    // ...
-    orders: {
-      type: 'hasMany',
-      model: 'order',
-      polymorphic: 'customer', // имя связи целевой модели
+    attachments: { // название связи
+      type: RelationType.HAS_MANY, // целевая модель ссылается на текущую
+      model: 'file', // название целевой модели
+      polymorphic: true, // название текущей модели находится в дискриминаторе
+      foreignKey: 'referenceId', // свойство целевой модели для идентификатора
+      discriminator: 'referenceType', // свойство целевой модели для названия текущей
     },
   },
-});
+})
 ```
 
-Явное указание `foreignKey` и `discriminator`
+## Расширение
+
+Метод `getRepository` экземпляра схемы проверяет наличие существующего
+репозитория для указанной модели и возвращает его. В противном случае
+создается новый экземпляр, который будет сохранен для последующих
+обращений к методу.
 
 ```js
-schema.defineModel({
-  // ...
-  relations: {
-    // ...
-    orders: {
-      type: 'hasMany',
-      model: 'order',
-      polymorphic: true, // true вместо имени модели
-      foreignKey: 'customerId', // поле целевой модели 
-      discriminator: 'customerType', // поле целевой модели
-    },
-  },
-});
-```
+import {Schema} from '@e22m4u/js-repository';
+import {Repository} from '@e22m4u/js-repository';
 
-#### ReferencesMany
+// const schema = new Schema();
+// schema.defineDatasource ...
+// schema.defineModel ...
 
-Связь покупателя к заказам через поле `orderIds`
+const rep1 = schema.getRepository('model');
+const rep2 = schema.getRepository('model');
+console.log(rep1 === rep2); // true
+```
+
+Подмена стандартного конструктора репозитория выполняется методом
+`setRepositoryCtor` сервиса `RepositoryRegistry`, который находится
+в контейнере экземпляра схемы. После чего все новые репозитории будут
+создаваться указанным конструктором вместо стандартного.
 
 ```js
+import {Schema} from '@e22m4u/js-repository';
+import {Repository} from '@e22m4u/js-repository';
+import {RepositoryRegistry} from '@e22m4u/js-repository';
+
+class MyRepository extends Repository {
+  /*...*/
+}
+
+// const schema = new Schema();
+// schema.defineDatasource ...
+// schema.defineModel ...
+
+schema.get(RepositoryRegistry).setRepositoryCtor(MyRepository);
+const rep = schema.getRepository('model');
+console.log(rep instanceof MyRepository); // true
+```
+
+*i. Так как экземпляры репозитория кэшируется, то замену конструктора
+следует выполнять до обращения к методу `getRepository`.*
+
+## TypeScript
+
+Получение типизированного репозитория с указанием интерфейса модели.
+
+```ts
+import {Schema} from '@e22m4u/js-repository';
+import {DataType} from '@e22m4u/js-repository';
+import {RelationType} from '@e22m4u/js-repository';
+
+// const schema = new Schema();
+// schema.defineDatasource ...
+// schema.defineModel ...
+
+// определение модели "city"
 schema.defineModel({
-  // ...
+  name: 'city',
+  datasource: 'myDatasource',
+  properties: {
+    title: DataType.STRING,
+    timeZone: DataType.STRING,
+  },
   relations: {
-    // ...
-    orders: {
-      type: 'referencesMany',
-      model: 'order',
-      foreignKey: 'orderIds', // опционально
+    country: {
+      type: RelationType.BELONGS_TO,
+      model: 'country',
     },
   },
 });
+
+// определение интерфейса "city"
+interface City {
+  id: number;
+  title?: string;
+  timeZone?: string;
+  countryId?: number;
+  country?: Country;
+  // открыть свойства (опционально)
+  [property: string]: unknown;
+}
+
+// получаем репозиторий по названию модели
+// указывая ее тип и тип идентификатора
+const cityRep = schema.getRepository<City, number>('city');
 ```
 
 ## Тесты