@e22m4u/js-repository 0.0.38 → 0.0.39

package/README.md

@@ -2,26 +2,45 @@
 
 Абстракция для работы с базами данных для Node.js
 
-| адаптер | описание                                                                                                                                        |
-|---------|-------------------------------------------------------------------------------------------------------------------------------------------------|
-| memory  | виртуальная база в памяти процесса (для разработки и тестирования)                                                                              |
-| mongodb | MongoDB - система управления NoSQL базами данных (*[требует установки](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter))* |
-
 ## Установка
 
 ```bash
 npm install @e22m4u/js-repository
 ```
 
-Опционально устанавливаем адаптер, например [mongodb](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter)
+Опционально устанавливаем адаптер. Например, если используемой базой
+является *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))* |
+
+## Концепция
+
+Модуль позволяет спроектировать систему связанных данных, доступ к которым
+осуществляется посредством репозиториев. Каждый репозиторий имеет собственную
+модель, которая описывает структуру определенной коллекции в базе,
+а так же определяет связи к другим коллекциям.
 
-Создаем экземпляр класса `Schema`
+```mermaid
+flowchart LR
+
+A[Datasource]-->B[Model]-->С[Repository];
+```
+
+## Использование
+
+Определения источников и моделей хранятся в экземпляре класса `Schema`,
+и первым шагом будет создание данного экземпляра.
 
 ```js
 import {Schema} from '@e22m4u/js-repository';
@@ -29,7 +48,38 @@ import {Schema} from '@e22m4u/js-repository';
 const schema = new Schema();
 ```
 
-Создаем источник данных `myMemory`
+Интерфейс `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'
+});
+```
+
+Параметры источника:
+
+- `name: string` уникальное название
+- `adapter: string` выбранный адаптер
+
+При желании можно использовать встроенный адаптер `memory`, который хранит
+данные в памяти процесса. У него нет специальных настроек, и он отлично
+подходит для тестов и прототипирования.
 
 ```js
 schema.defineDatasource({
@@ -38,6 +88,127 @@ schema.defineDatasource({
 });
 ```
 
+#### Модель данных
+
+Когда источники определены, можно перейти к описанию моделей данных.
+Модель может определять как структуру какого-либо объекта,
+так и являться отражением реальной коллекции базы.
+
+Представьте себе коллекцию торговых точек, у каждой из которых имеются
+координаты `lat` и `lng`. Мы можем заранее определить модель для
+объекта координат методом `defineModel` и использовать ее в других
+коллекциях.
+
+```js
+schema.defineModel({
+  name: 'latLng', // название новой модели
+  properties: { // поля модели
+    lat: DataType.NUMBER, // поле широты
+    lng: DataType.NUMBER, // поле долготы
+  },
+});
+```
+
+Параметры модели:
+
+- `name: string` уникальное название (обязательно)
+- `datasource: string` выбранный источник данных
+- `properties: object` определения полей модели
+- `relations: object` определения связей модели
+
+Параметр `properties` принимает объект, ключи которого являются именами
+полей, а значением тип поля или объект с дополнительными параметрами.
+
+```js
+schema.defineModel({
+  name: 'latLng',
+  properties: {
+    lat: DataType.NUMBER, // краткое определение поля "lat"
+    lng: { // определение поля "lng" с параметром "required"
+      type: DataType.NUMBER,
+      required: true, // исключает null и undefined
+    },
+  },
+});
+```
+
+Типы данных:
+
+- `DataType.ANY`
+- `DataType.STRING`
+- `DataType.NUMBER`
+- `DataType.BOOLEAN`
+- `DataType.ARRAY`
+- `DataType.OBJECT`
+
+Модель `latLng` всего лишь описывает структуру объекта координат, тогда
+как торговая точка должна иметь реальную таблицу в базе. По аналогии с
+предыдущим примером, добавим модель `place`, но дополнительно укажем
+источник данных в параметре `datasource`
+
+```js
+schema.defineModel({
+  name: 'place',
+  datasource: 'myMemory', // выбранный источник данных
+  properties: {
+    name: DataType.STRING, // поле для названия торговой точки
+    location: { // поле объекта координат
+      type: DataType.OBJECT, // допускать только объекты
+      model: 'latLng', // определение структуры объекта
+    },
+  },
+});
+```
+
+В примере выше мы использовали модель `latLng` как структуру допустимого
+значения поля `location`. Возможный документ данной коллекции может
+выглядеть так:
+
+```json
+{
+  "id": 1,
+  "name": "Burger King at Avenue Mall",
+  "location": {
+    "lat": 32.412891,
+    "lng": 34.7660061
+  }
+}
+```
+
+Стоит обратить внимание, что мы могли бы не объявлять параметр `properties`,
+при этом теряя возможность проверки данных перед записью в базу.
+
+```js
+schema.defineModel({
+  name: 'place',
+  adapter: 'myMemory',
+  // параметр "properties" не указан
+});
+```
+
+Параметры поля:
+
+- `type: string` тип допустимого значения (обязательно)
+- `itemType: string` тип элемента массива (для `type: 'array'`)
+- `model: string` модель объекта (для `type: 'object'`)
+- `primaryKey: boolean` объявить поле первичным ключом
+- `columnName: string` переопределение названия колонки
+- `columnType: string` тип колонки (определяется адаптером)
+- `required: boolean` объявить поле обязательным
+- `default: any` значение по умолчанию
+
+#### Репозиторий
+
+В отличие от `latLng`, модель `place` имеет источник данных с названием
+`myMemory`, который был объявлен ранее. Наличие источника позволяет получить
+репозиторий по названию модели.
+
+```js
+const rep = schema.getRepository('place');
+```
+
+## Пример
+
 Создаем модель `user`
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-repository",
-  "version": "0.0.38",
+  "version": "0.0.39",
   "description": "Абстракция для работы с базами данных для Node.js",
   "type": "module",
   "main": "src/index.js",

package/src/filter/filter-clause.d.ts

@@ -237,11 +237,9 @@ export type NormalizedFieldsClause = string[];
  */
 export declare type IncludeClause =
   | string
-  | string[]
   | NestedIncludeClause
-  | NestedIncludeClause[]
   | NormalizedIncludeClause
-  | NormalizedIncludeClause[];
+  | IncludeClause[];
 
 /**
  * Nested include clause.