|
|
@@ -0,0 +1,1706 @@
|
|
|
+## @e22m4u/js-repository
|
|
|
+
|
|
|
+Абстракция для работы с базами данных для Node.js
|
|
|
+
|
|
|
+<!--
|
|
|
+
|
|
|
+- [Установка](#Установка)
|
|
|
+- [Введение](#Введение)
|
|
|
+- [Пример](#Пример)
|
|
|
+- [Источник данных](#Источник-данных)
|
|
|
+- [Модель данных](#Модель-данных)
|
|
|
+- [Репозиторий](#Репозиторий)
|
|
|
+- [Фильтрация](#Фильтрация)
|
|
|
+- [Связи](#Связи)
|
|
|
+- [Тесты](#Тесты)
|
|
|
+
|
|
|
+## Установка
|
|
|
+
|
|
|
+```bash
|
|
|
+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))* |
|
|
|
+
|
|
|
+## Введение
|
|
|
+
|
|
|
+Модуль позволяет объединить несколько источников данных в единую систему данных с помощью источников
|
|
|
+и моделей. Источник описывает способ подключения к базе и место хранения данных,
|
|
|
+а модель структуру документа и связи между коллекциями. Непосредственно чтение
|
|
|
+и запись осуществляется репозиториями, которые можно получить после объявления
|
|
|
+моделей.
|
|
|
+
|
|
|
+```mermaid
|
|
|
+flowchart LR
|
|
|
+
|
|
|
+A[Источник данных]-->B[Модель A]-->D[Репозиторий А]
|
|
|
+A[Источник данных]-->C[Модель Б]-->E[Репозиторий Б]
|
|
|
+```
|
|
|
+
|
|
|
+## Пример
|
|
|
+
|
|
|
+Перед началом работы с коллекцией нужно определить источник и модель данных.
|
|
|
+Определения хранятся в экземпляре класса `Schema`, и первым шагом будет
|
|
|
+создание данного экземпляра.
|
|
|
+
|
|
|
+```js
|
|
|
+import {Schema} from '@e22m4u/js-repository';
|
|
|
+
|
|
|
+const schema = new Schema();
|
|
|
+```
|
|
|
+
|
|
|
+Интерфейс `Schema` имеет три основных метода:
|
|
|
+
|
|
|
+- `defineDatasource(datasourceDef: object): this` - добавить источник
|
|
|
+- `defineModel(modelDef: object): this` - добавить модель
|
|
|
+- `getRepository(modelName: string): Repository` - получить репозиторий
|
|
|
+
|
|
|
+Далее определяется источник и выбранный адаптер. Количество источников
|
|
|
+зависит от числа используемых баз данных.
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineDatasource({
|
|
|
+ name: 'myMemory', // название нового источника
|
|
|
+ adapter: 'memory', // выбранный адаптер
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+Теперь добавим модель отражающую структуру документа. Представим
|
|
|
+коллекцию `city` с двумя полями, где строковое поле `name` в качестве
|
|
|
+названия города, и `population` как численность населения.
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ name: 'city', // название модели
|
|
|
+ datasource: 'myMemory', // выбранный источник
|
|
|
+ properties: {
|
|
|
+ name: DataType.STRING, // поле типа "string"
|
|
|
+ population: DataType.NUMBER, // поле типа "number"
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+Модель гарантирует, что тип указанных полей будет проверен перед записью
|
|
|
+в коллекцию. Осталось получить репозиторий данной модели для чтения и записи
|
|
|
+документов.
|
|
|
+
|
|
|
+```js
|
|
|
+// получаем репозиторий модели "city"
|
|
|
+const cityRep = schema.getRepository('city');
|
|
|
+
|
|
|
+// добавляем новый документ
|
|
|
+const city = await cityRep.create({
|
|
|
+ name: 'Moscow',
|
|
|
+ population: 11980000,
|
|
|
+});
|
|
|
+
|
|
|
+// выводим результат
|
|
|
+console.log(city);
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "name": "Moscow",
|
|
|
+// "population": 11980000
|
|
|
+// }
|
|
|
+```
|
|
|
+
|
|
|
+Последующие обращения к методу `getRepository` с названием модели
|
|
|
+`city` будут возвращать все тот же экземпляр репозитория данной
|
|
|
+модели по принципу «одиночки».
|
|
|
+
|
|
|
+## Источник данных
|
|
|
+
|
|
|
+Каждый источник имеет свое уникальное название и выбранный адаптер.
|
|
|
+Экземпляр класса `Schema` имеет метод `defineDatasource` с помощью
|
|
|
+которого объявляется новый источник.
|
|
|
+
|
|
|
+```js
|
|
|
+import {Schema} from '@e22m4u/js-repository';
|
|
|
+
|
|
|
+const schema = new Schema();
|
|
|
+
|
|
|
+schema.defineDatasource({
|
|
|
+ name: 'datasource1', // название нового источника
|
|
|
+ adapter: 'memory', // выбранный адаптер
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+Если адаптер имеет параметры, то они передаются с объектом определения
|
|
|
+источника.
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineDatasource({
|
|
|
+ name: 'datasource2',
|
|
|
+ adapter: 'mongodb',
|
|
|
+ // настройки адаптера "mongodb"
|
|
|
+ host: '127.0.0.1',
|
|
|
+ port: 27017,
|
|
|
+ database: 'data'
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+Параметры источника:
|
|
|
+
|
|
|
+- `name: string` уникальное название
|
|
|
+- `adapter: string` выбранный адаптер
|
|
|
+- параметры адаптера (если имеются)
|
|
|
+
|
|
|
+**Адаптер «memory»**
|
|
|
+
|
|
|
+Встроенный адаптер `memory` хранит данные в памяти процесса, не требует
|
|
|
+установки и отлично подходит для тестов и прототипирования.
|
|
|
+
|
|
|
+```js
|
|
|
+import {Schema} from '@e22m4u/js-repository';
|
|
|
+
|
|
|
+const schema = new Schema();
|
|
|
+
|
|
|
+schema.defineDatasource({
|
|
|
+ name: 'myMemory',
|
|
|
+ adapter: 'memory', // адаптер "memory"
|
|
|
+});
|
|
|
+
|
|
|
+schema.defineModel({
|
|
|
+ name: 'fruit',
|
|
|
+ datasource: 'myMemory',
|
|
|
+ properties: {
|
|
|
+ name: DataType.STRING,
|
|
|
+ description: DataType.STRING,
|
|
|
+ },
|
|
|
+});
|
|
|
+
|
|
|
+const fruitRep = schema.getRepository('fruit');
|
|
|
+
|
|
|
+const pineapple = fruitRep.create({
|
|
|
+ name: 'Pineapple',
|
|
|
+ description: 'A tropical fruit'
|
|
|
+});
|
|
|
+
|
|
|
+console.log(pineapple);
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "name": "Pineapple",
|
|
|
+// "description": "A tropical fruit"
|
|
|
+// }
|
|
|
+```
|
|
|
+
|
|
|
+Адаптер `memory` использует автоинкрементные идентификаторы типа `number`,
|
|
|
+но может принимать и строковые ключи, если их значение явно указано
|
|
|
+в документе.
|
|
|
+
|
|
|
+```js
|
|
|
+// ...
|
|
|
+
|
|
|
+const banana = fruitRep.create({
|
|
|
+ id: 'fruit-1', // ключ типа "string"
|
|
|
+ name: 'Banana',
|
|
|
+ description: 'An edible fruit'
|
|
|
+});
|
|
|
+
|
|
|
+console.log(banana);
|
|
|
+// {
|
|
|
+// "id": "fruit-1",
|
|
|
+// "name": 'Banana',
|
|
|
+// "description": "An edible fruit"
|
|
|
+// }
|
|
|
+```
|
|
|
+
|
|
|
+## Модель данных
|
|
|
+
|
|
|
+Модель описывает структуру документа определенной коллекции. Экземпляр
|
|
|
+класса `Schema` имеет метод `defineModel` с помощью которого объявляется
|
|
|
+новая модель.
|
|
|
+
|
|
|
+```js
|
|
|
+import {Schema} from '@e22m4u/js-repository';
|
|
|
+
|
|
|
+const schema = new Schema();
|
|
|
+
|
|
|
+// объявление модели "region"
|
|
|
+schema.defineModel({
|
|
|
+ name: 'region', // название модели
|
|
|
+ properties: { // поля модели
|
|
|
+ name: DataType.STRING,
|
|
|
+ population: DataType.NUMBER,
|
|
|
+ },
|
|
|
+});
|
|
|
+
|
|
|
+// документ "region" может выглядеть так
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "name": "Asia",
|
|
|
+// "population": 4753079727
|
|
|
+// }
|
|
|
+```
|
|
|
+
|
|
|
+Параметры модели:
|
|
|
+
|
|
|
+- `name: string` название модели (обязательно)
|
|
|
+- `base: string` название наследуемой модели
|
|
|
+- `tableName: string` название коллекции в базе
|
|
|
+- `datasource: string` выбранный источник данных
|
|
|
+- `properties: object` определения полей модели
|
|
|
+- `relations: object` определения связей (см. [Связи](#Связи))
|
|
|
+
|
|
|
+**Название модели**
|
|
|
+
|
|
|
+Название должно быть уникальным, так как оно используется для
|
|
|
+определения связей и соответствует названию коллекции в базе.
|
|
|
+При необходимости можно явно задать название коллекции параметром
|
|
|
+`tableName`, если оно не соответствует названию модели.
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ name: 'city', // название модели
|
|
|
+ tableName: 'CITIES', // название коллекции
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+**Источник данных**
|
|
|
+
|
|
|
+Если модель отражает реальную коллекцию базы, а не является частью другой,
|
|
|
+то указав название источника в параметре `datasource` можно получить
|
|
|
+репозиторий модели методом `getRepository` по ее названию.
|
|
|
+
|
|
|
+```js
|
|
|
+// модель "city"
|
|
|
+schema.defineModel({
|
|
|
+ name: 'city',
|
|
|
+ datasource: 'myDatasource', // выбранный источник
|
|
|
+});
|
|
|
+
|
|
|
+// репозиторий модели "city"
|
|
|
+const cityRep = schema.getRepository('city');
|
|
|
+// await cityRep.create({name: 'St. Petersburg'});
|
|
|
+// ...
|
|
|
+```
|
|
|
+
|
|
|
+Параметры поля:
|
|
|
+
|
|
|
+- `type: string` тип допустимого значения (обязательно)
|
|
|
+- `itemType: string` тип элемента массива (для `type: 'array'`)
|
|
|
+- `model: string` модель объекта (для `type: 'object'`)
|
|
|
+- `primaryKey: boolean` объявить поле первичным ключом
|
|
|
+- `columnName: string` переопределение названия колонки
|
|
|
+- `columnType: string` тип колонки (определяется адаптером)
|
|
|
+- `required: boolean` объявить поле обязательным
|
|
|
+- `default: any` значение по умолчанию
|
|
|
+
|
|
|
+Типы данных:
|
|
|
+
|
|
|
+- `DataType.ANY` разрешено любое значение
|
|
|
+- `DataType.STRING` только значение типа `string`
|
|
|
+- `DataType.NUMBER` только значение типа `number`
|
|
|
+- `DataType.BOOLEAN` только значение типа `boolean`
|
|
|
+- `DataType.ARRAY` только значение типа `array`
|
|
|
+- `DataType.OBJECT` только значение типа `object`
|
|
|
+
|
|
|
+**Поля документа**
|
|
|
+
|
|
|
+Параметр `properties` принимает объект, ключи которого являются именами
|
|
|
+полей, а значением тип поля или объект с дополнительными параметрами.
|
|
|
+Эти настройки используются для проверки данных перед сохранением в базу
|
|
|
+и установки значений по умолчанию (если имеются).
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ name: 'city',
|
|
|
+ properties: {
|
|
|
+ name: DataType.STRING, // поле "name" типа "string"
|
|
|
+ population: { // поле "population" типа "number"
|
|
|
+ type: DataType.NUMBER,
|
|
|
+ default: 0, // значение по умолчанию
|
|
|
+ },
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+Когда требуется указать значение по умолчанию, установить флаг `required`
|
|
|
+или объявить более сложный тип допустимого значения, то вместо базового
|
|
|
+определения используется объект с расширенными настройками.
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ name: 'place',
|
|
|
+ properties: {
|
|
|
+ // базовое определение поля "name"
|
|
|
+ name: DataType.STRING,
|
|
|
+ // расширенное определение поля "location"
|
|
|
+ // с дополнительными параметрами "model"
|
|
|
+ // и "required"
|
|
|
+ location: {
|
|
|
+ type: DataType.OBJECT,
|
|
|
+ model: 'latLng',
|
|
|
+ required: true,
|
|
|
+ },
|
|
|
+ // расширенное определение поля "keywords"
|
|
|
+ // с дополнительными параметрами "itemType"
|
|
|
+ // и "default"
|
|
|
+ keywords: {
|
|
|
+ type: DataType.ARRAY,
|
|
|
+ itemType: DataType.STRING,
|
|
|
+ default: () => [],
|
|
|
+ },
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+**Наследование**
|
|
|
+
|
|
|
+Модель может наследовать поля и связи используя параметр `base`, куда
|
|
|
+передается название базовой модели. При этом наследуемые настройки можно
|
|
|
+переопределять не затрагивая родителя.
|
|
|
+
|
|
|
+```js
|
|
|
+// модель "area"
|
|
|
+schema.defineModel({
|
|
|
+ name: 'area',
|
|
|
+ properties: {
|
|
|
+ name: DataType.STRING,
|
|
|
+ population: DataType.NUMBER,
|
|
|
+ },
|
|
|
+});
|
|
|
+
|
|
|
+// модель "city"
|
|
|
+schema.defineModel({
|
|
|
+ name: 'city',
|
|
|
+ base: 'area', // базовая модель
|
|
|
+ properties: {
|
|
|
+ timezone: DataType.STRING,
|
|
|
+ },
|
|
|
+});
|
|
|
+
|
|
|
+// документ "city" может выглядеть так
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "name": "Moscow", <= унаследовано
|
|
|
+// "population": 11980000, <= унаследовано
|
|
|
+// "timezone": "Europe/Moscow"
|
|
|
+// }
|
|
|
+```
|
|
|
+
|
|
|
+## Репозиторий
|
|
|
+
|
|
|
+Объявление модели имеет необязательный параметр `datasource`,
|
|
|
+который указывает на источник хранения данных. Наличие источника
|
|
|
+позволяет получить репозиторий по названию такой модели. Репозиторий,
|
|
|
+в свою очередь, предоставляет интерфейс для чтения и записи данных
|
|
|
+этой модели.
|
|
|
+
|
|
|
+```js
|
|
|
+import {Schema} from '@e22m4u/js-repository';
|
|
|
+
|
|
|
+const schema = new Schema();
|
|
|
+
|
|
|
+// объявление источника "myMemory"
|
|
|
+schema.defineDatasource({
|
|
|
+ name: 'myMemory',
|
|
|
+ adapter: 'memory',
|
|
|
+});
|
|
|
+
|
|
|
+// объявление модели "city"
|
|
|
+schema.defineModel({
|
|
|
+ name: 'city',
|
|
|
+ datasource: 'myMemory', // источник данных
|
|
|
+ properties: {
|
|
|
+ name: DataType.STRING,
|
|
|
+ population: DataType.NUMBER,
|
|
|
+ },
|
|
|
+});
|
|
|
+
|
|
|
+// получение репозитория модели "city"
|
|
|
+const cityRep = schema.getRepository('city');
|
|
|
+
|
|
|
+// записываем новый документ "city"
|
|
|
+const city = await cityRep.create({
|
|
|
+ name: 'Moscow',
|
|
|
+ population: 11980000
|
|
|
+});
|
|
|
+
|
|
|
+// выводим результат
|
|
|
+console.log(city);
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "name": "Moscow",
|
|
|
+// "population": 11980000
|
|
|
+// }
|
|
|
+```
|
|
|
+
|
|
|
+#### Методы
|
|
|
+
|
|
|
+- `create(data, filter = undefined)` добавить новый документ
|
|
|
+- `replaceById(id, 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)` подсчет всех документов или по условию
|
|
|
+
|
|
|
+#### Параметры
|
|
|
+
|
|
|
+- `id` идентификатор (первичный ключ)
|
|
|
+- `data` объект отражающий состав документа
|
|
|
+- `where` параметры выборки (см. Фильтрация)
|
|
|
+- `filter` параметры возвращаемого результата (см. Фильтрация)
|
|
|
+
|
|
|
+## Фильтрация
|
|
|
+
|
|
|
+Некоторые методы репозитория опционально принимают параметр `where` для
|
|
|
+условий выборки и/или параметр `filter` управляющий возвращаемым значением.
|
|
|
+
|
|
|
+### where
|
|
|
+
|
|
|
+Рассмотрим применение параметра `where` на примере метода `patch`, который
|
|
|
+выполняет поиск и обновление документов по определенному условию.
|
|
|
+
|
|
|
+Сигнатура метода `patch(data, where = undefined)` указывает на два параметра,
|
|
|
+где первый принимает объект данных, а второй является опциональным объектом
|
|
|
+выборки.
|
|
|
+
|
|
|
+```js
|
|
|
+// вызов метода `patch`
|
|
|
+await rep.patch(
|
|
|
+ // обновить значения полей
|
|
|
+ // "hidden" и "updatedAt"
|
|
|
+ {
|
|
|
+ hidden: true,
|
|
|
+ updatedAt: new Date().toISOString(),
|
|
|
+ },
|
|
|
+ // только в тех документах, где поле "type"
|
|
|
+ // равно значению "article", а "publishedAt"
|
|
|
+ // содержит дату более раннюю, чем указана
|
|
|
+ // в операторе "lte"
|
|
|
+ {
|
|
|
+ type: 'article',
|
|
|
+ publishedAt: {
|
|
|
+ lte: '2023-12-02T14:00:00.000Z',
|
|
|
+ }
|
|
|
+ },
|
|
|
+);
|
|
|
+```
|
|
|
+
|
|
|
+Второй аргумент метода `patch` предыдущего листинга содержит условия
|
|
|
+выборки по которым будет выполнен поиск и обновление документов. Полный
|
|
|
+список возможных операторов сравнения приводится ниже.
|
|
|
+
|
|
|
+`{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'}}` флаги регулярного выражения
|
|
|
+
|
|
|
+### filter
|
|
|
+
|
|
|
+Методы репозитория асинхронны и возвращают `Promise` с некоторым значением.
|
|
|
+Параметр `filter` позволяет влиять на это значение более широким образом,
|
|
|
+чем просто ограничение для затрагиваемых данных. Ниже представлен список
|
|
|
+опциональных полей объекта `filter`, одним из которых является `where`
|
|
|
+(рассматривался ранее).
|
|
|
+
|
|
|
+- `where` объект выборки
|
|
|
+- `order` указание порядка
|
|
|
+- `limit` ограничение количества документов
|
|
|
+- `skip` пропуск документов
|
|
|
+- `fields` выбор необходимых полей документа
|
|
|
+- `include` включение связанных данных в результат (см. Связи)
|
|
|
+
|
|
|
+#### order
|
|
|
+
|
|
|
+Документы могут быть отсортированы по указанным полям и в нужном
|
|
|
+направлении, где `ASC` - по умолчанию, и `DESC` - в обратном порядке.
|
|
|
+
|
|
|
+```js
|
|
|
+// на примере метода "find"
|
|
|
+const result = await rep.find({
|
|
|
+ // упорядочить по полю "featured"
|
|
|
+ order: 'featured',
|
|
|
+ // по полю "featured" в обратном порядке
|
|
|
+ order: 'featured DESC',
|
|
|
+ // по нескольким полям в разных направлениях
|
|
|
+ order: ['featured ASC', 'publishedAt DESC', 'id'],
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+#### limit и skip
|
|
|
+
|
|
|
+При использовании метода `find` может потребоваться комбинация параметров
|
|
|
+`limit` и `skip` для механизма пагинации.
|
|
|
+
|
|
|
+```js
|
|
|
+// первый параметр метода `find` принимает
|
|
|
+// объект настроек возвращаемого результата
|
|
|
+const result = await rep.find({
|
|
|
+ limit: 12, // вернуть не более 14и документов
|
|
|
+ skip: 24, // пропустить 24 документа выборки
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+#### fields
|
|
|
+
|
|
|
+Сократить объем документа можно параметром `fields` указав необходимый
|
|
|
+набор полей.
|
|
|
+
|
|
|
+```js
|
|
|
+// на примере метода "find"
|
|
|
+const result = await rep.find({
|
|
|
+ // включить в результат только поле "title"
|
|
|
+ fields: 'title',
|
|
|
+ // или поле "title", "createdAt" и "featured"
|
|
|
+ fields: ['title', 'createdAt', 'featured'],
|
|
|
+ // первичный ключ указывать не обязательно
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+## Связи
|
|
|
+
|
|
|
+WIP
|
|
|
+
|
|
|
+```js
|
|
|
+// коллекция имеет три документа
|
|
|
+// [
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "type": "city",
|
|
|
+// "name": "Bangkok",
|
|
|
+// "hidden": true
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 2,
|
|
|
+// "type": "country",
|
|
|
+// "name": "Thailand",
|
|
|
+// "hidden": true
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 3,
|
|
|
+// "type": "city",
|
|
|
+// "name": "Moscow",
|
|
|
+// "hidden": true
|
|
|
+// }
|
|
|
+// ]
|
|
|
+
|
|
|
+// вызов метода `patch` с передачей
|
|
|
+// значений для обновляемых полей
|
|
|
+const result = await rep.patch({
|
|
|
+ hidden: false,
|
|
|
+ updatedAt: new Date().toISOString(),
|
|
|
+});
|
|
|
+
|
|
|
+// вывод количество затронутых документов
|
|
|
+console.log(result);
|
|
|
+// 3
|
|
|
+```
|
|
|
+
|
|
|
+#### create(data, filter = undefined)
|
|
|
+
|
|
|
+Добавляет новый документ в коллекцию и возвращает его.
|
|
|
+
|
|
|
+```js
|
|
|
+const result = await rep.create({
|
|
|
+ name: 'Rick Sanchez',
|
|
|
+ dimension: 'C-137',
|
|
|
+ age: 67,
|
|
|
+});
|
|
|
+
|
|
|
+// вывод результата
|
|
|
+console.log(result);
|
|
|
+// {
|
|
|
+// id: 1, <= определено базой данных
|
|
|
+// name: 'Rick Sanchez',
|
|
|
+// dimension: 'C-137',
|
|
|
+// age: 67
|
|
|
+// }
|
|
|
+```
|
|
|
+
|
|
|
+Ограничение количества возвращаемых полей.
|
|
|
+
|
|
|
+```js
|
|
|
+const result = await rep.create(
|
|
|
+ // состав нового документа
|
|
|
+ {
|
|
|
+ name: 'Rick Sanchez',
|
|
|
+ dimension: 'C-137',
|
|
|
+ age: 67,
|
|
|
+ },
|
|
|
+ // параметры возвращаемого результата
|
|
|
+ {
|
|
|
+ fields: [
|
|
|
+ 'name',
|
|
|
+ 'age',
|
|
|
+ ]
|
|
|
+ }
|
|
|
+);
|
|
|
+
|
|
|
+// вывод результата
|
|
|
+console.log(result);
|
|
|
+// {
|
|
|
+// id: 1,
|
|
|
+// name: 'Rick Sanchez',
|
|
|
+// age: 67
|
|
|
+// }
|
|
|
+
|
|
|
+```
|
|
|
+
|
|
|
+Использование второго параметра `filter` метода `create` позволяет
|
|
|
+ограничивать количество возвращаемых данных, и разрешать связи к другим
|
|
|
+коллекциям (см. Связи).
|
|
|
+
|
|
|
+```js
|
|
|
+// подготовка состава для нового документа
|
|
|
+const data = {
|
|
|
+ name: 'Rick Sanchez',
|
|
|
+ dimension: 'C-137',
|
|
|
+ age: 67,
|
|
|
+ biographyId: 59, // связь "biography" (см. belongsTo)
|
|
|
+ pictureIds: [345, 346], // связь "pictures" (см. referencesMany)
|
|
|
+}
|
|
|
+
|
|
|
+// подготовка параметра "filter"
|
|
|
+const filter = {
|
|
|
+ // "fields" - если определено, то результат
|
|
|
+ // будут включать только указанные поля
|
|
|
+ fields: [
|
|
|
+ 'name',
|
|
|
+ 'biographyId'
|
|
|
+ 'pictureIds',
|
|
|
+ ],
|
|
|
+ // "include" - включение в результат
|
|
|
+ // связанных документов (см. Связи)
|
|
|
+ include: [
|
|
|
+ 'biography',
|
|
|
+ 'pictures',
|
|
|
+ ],
|
|
|
+}
|
|
|
+
|
|
|
+// вызов метода `create` и вывод результата
|
|
|
+const result = await rep.create(data, filter);
|
|
|
+console.log(result);
|
|
|
+// {
|
|
|
+// "name": "Rick Sanchez",
|
|
|
+// "biographyId": 59,
|
|
|
+// "biography": { <= разрешение связи
|
|
|
+// "id": 59,
|
|
|
+// "annotation": "This article is about Rick Sanchez",
|
|
|
+// "body": "He is a genius scientist whose ..."
|
|
|
+// }
|
|
|
+// "pictureIds": [345, 346],
|
|
|
+// "pictures": [ <= разрешение связи
|
|
|
+// {
|
|
|
+// "id": 345,
|
|
|
+// "mime": "image/jpeg",
|
|
|
+// "file": "/uploads/rick345.jpg"
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 346,
|
|
|
+// "mime": "image/jpeg",
|
|
|
+// "file": "/uploads/rick346.jpg"
|
|
|
+// }
|
|
|
+// ],
|
|
|
+// }
|
|
|
+//
|
|
|
+// поля "age" и "dimension" исключены
|
|
|
+// из результата опцией "fields"
|
|
|
+//
|
|
|
+// документы "biography" и "pictures"
|
|
|
+// встроены в результат опцией "include"
|
|
|
+```
|
|
|
+
|
|
|
+#### replaceById(id, data, filter = undefined)
|
|
|
+
|
|
|
+Заменяет существующий документ по идентификатору и возвращает его. Если
|
|
|
+идентификатор не найден, то выбрасывает исключение.
|
|
|
+
|
|
|
+```js
|
|
|
+// документ с идентификатором 12
|
|
|
+// имеет следующую структуру
|
|
|
+// {
|
|
|
+// id: 12,
|
|
|
+// name: 'Rick Sanchez',
|
|
|
+// dimension: 'C-137',
|
|
|
+// age: 67
|
|
|
+// }
|
|
|
+
|
|
|
+// вызов метода `replaceById` с передачей
|
|
|
+// идентификатора и нового состава
|
|
|
+const result = await rep.replaceById(12, {
|
|
|
+ name: 'Morty Smith',
|
|
|
+ kind: 'a young teenage boy',
|
|
|
+ age: 14,
|
|
|
+});
|
|
|
+
|
|
|
+// вывод результата
|
|
|
+console.log(result);
|
|
|
+// {
|
|
|
+// id: 12,
|
|
|
+// name: 'Morty Smith', <= обновлено
|
|
|
+// kind: 'a young teenage boy', <= новое поле
|
|
|
+// age: 14 <= обновлено
|
|
|
+// }
|
|
|
+//
|
|
|
+// поле "dimension" удалено, так как
|
|
|
+// не передавалось с новым составом
|
|
|
+```
|
|
|
+
|
|
|
+Использование третьего параметра `filter` метода `replaceById` позволяет
|
|
|
+ограничивать количество возвращаемых данных, и разрешать связи к другим
|
|
|
+коллекциям (см. Связи).
|
|
|
+
|
|
|
+```js
|
|
|
+// подготовка состава для заменяемого документа
|
|
|
+const data = {
|
|
|
+ name: 'Morty Smith',
|
|
|
+ kind: 'a young teenage boy',
|
|
|
+ age: 14,
|
|
|
+ biographyId: 61, // связь "biography" (см. belongsTo)
|
|
|
+ pictureIds: [347, 348], // связь "pictures" (см. referencesMany)
|
|
|
+}
|
|
|
+
|
|
|
+// подготовка параметра "filter"
|
|
|
+const filter = {
|
|
|
+ // "fields" - если определено, то результат
|
|
|
+ // будут включать только указанные поля
|
|
|
+ fields: [
|
|
|
+ 'name',
|
|
|
+ 'biographyId'
|
|
|
+ 'pictureIds',
|
|
|
+ ],
|
|
|
+ // "include" - включение в результат
|
|
|
+ // связанных документов (см. Связи)
|
|
|
+ include: [
|
|
|
+ 'biography',
|
|
|
+ 'pictures',
|
|
|
+ ],
|
|
|
+}
|
|
|
+
|
|
|
+// вызов метода `replaceById` и вывод результата
|
|
|
+const result = await rep.replaceById(12, data, filter);
|
|
|
+console.log(result);
|
|
|
+// {
|
|
|
+// "name": "Morty Smith",
|
|
|
+// "biographyId": 61, <= новое поле
|
|
|
+// "biography": { <= разрешение связи
|
|
|
+// "id": 61,
|
|
|
+// "annotation": "This article is about Morty Smith",
|
|
|
+// "body": "Currently, Morty is 14 years old ..."
|
|
|
+// },
|
|
|
+// "pictureIds": [347, 348], <= новое поле
|
|
|
+// "picture": [ <= разрешение связи
|
|
|
+// {
|
|
|
+// "id": 347,
|
|
|
+// "mime": "image/jpeg",
|
|
|
+// "file": "/uploads/morty347.jpg"
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 348,
|
|
|
+// "mime": "image/jpeg",
|
|
|
+// "file": "/uploads/morty348.jpg"
|
|
|
+// }
|
|
|
+// ]
|
|
|
+// }
|
|
|
+//
|
|
|
+// поля "kind" и "age" записаны в документ,
|
|
|
+// но исключены из результата опцией "fields"
|
|
|
+//
|
|
|
+// документы "biography" и "pictures"
|
|
|
+// встроены в результат опцией "include"
|
|
|
+```
|
|
|
+
|
|
|
+#### patchById(id, data, filter = undefined)
|
|
|
+
|
|
|
+Частично обновляет существующий документ по идентификатору и возвращает его.
|
|
|
+Если идентификатор не найден, то выбрасывает исключение.
|
|
|
+
|
|
|
+```js
|
|
|
+// документ с идентификатором 24
|
|
|
+// имеет следующую структуру
|
|
|
+// {
|
|
|
+// "id": 24,
|
|
|
+// "type": "airport",
|
|
|
+// "name": "Domodedovo Airport",
|
|
|
+// "code": "DME"
|
|
|
+// }
|
|
|
+
|
|
|
+// вызов метода `patchById` с передачей
|
|
|
+// идентификатора и новых значений
|
|
|
+// обновляемых полей
|
|
|
+const result = await rep.patchById(24, {
|
|
|
+ name: 'Sheremetyevo Airport',
|
|
|
+ code: 'SVO',
|
|
|
+ featured: true,
|
|
|
+});
|
|
|
+
|
|
|
+// вывод результата
|
|
|
+console.log(result);
|
|
|
+// {
|
|
|
+// "id": 24,
|
|
|
+// "type": "airport",
|
|
|
+// "name": "Sheremetyevo Airport", <= обновлено
|
|
|
+// "code": "SVO", <= обновлено
|
|
|
+// "featured": true <= новое поле
|
|
|
+// }
|
|
|
+```
|
|
|
+
|
|
|
+Использование третьего параметра `filter` метода `patchById` позволяет
|
|
|
+ограничивать количество возвращаемых данных, и разрешать связи к другим
|
|
|
+коллекциям (см. Связи).
|
|
|
+
|
|
|
+```js
|
|
|
+// подготовка обновляемых данных
|
|
|
+const data = {
|
|
|
+ name: 'Sheremetyevo Airport',
|
|
|
+ code: 'SVO',
|
|
|
+ featured: true,
|
|
|
+ cityId: 231, // связь "city" (см. belongsTo)
|
|
|
+ companyIds: [513, 514], // связь "companies" (см. referencesMany)
|
|
|
+}
|
|
|
+
|
|
|
+// подготовка параметра `filter`
|
|
|
+const filter = {
|
|
|
+ // "fields" - если определено, то результат
|
|
|
+ // будут включать только указанные поля
|
|
|
+ fields: [
|
|
|
+ 'name',
|
|
|
+ 'cityId',
|
|
|
+ 'companyIds',
|
|
|
+ ],
|
|
|
+ // "include" - включение в результат
|
|
|
+ // связанных документов (см. Связи)
|
|
|
+ include: [
|
|
|
+ 'city',
|
|
|
+ 'companies',
|
|
|
+ ],
|
|
|
+}
|
|
|
+
|
|
|
+// вызов метода `patchById` и вывод результата
|
|
|
+const result = await rep.patchById(24, data, filter);
|
|
|
+console.log(result);
|
|
|
+// {
|
|
|
+// "id": 24,
|
|
|
+// "name": "Sheremetyevo Airport", <= обновлено
|
|
|
+// "cityId": 231, <= новое поле
|
|
|
+// "city": { <= разрешение связи
|
|
|
+// "id": 231,
|
|
|
+// "name": "Moscow"
|
|
|
+// },
|
|
|
+// "companyIds": [513, 514], <= новое поле
|
|
|
+// "companies": [ <= разрешение связи
|
|
|
+// {
|
|
|
+// "id": 513,
|
|
|
+// "name": "S7 Airlines"
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 514,
|
|
|
+// "name": "Aeroflot Airlines"
|
|
|
+// },
|
|
|
+// ]
|
|
|
+// }
|
|
|
+//
|
|
|
+// поля "code" и "featured" обновлены,
|
|
|
+// но исключены из ответа опцией "fields"
|
|
|
+//
|
|
|
+// документы "city" и "companies"
|
|
|
+// встроены в результат опцией "include"
|
|
|
+```
|
|
|
+
|
|
|
+#### patch(data, where = undefined)
|
|
|
+
|
|
|
+Обновляет документы и возвращает их число. Используется для
|
|
|
+обновления нескольких документов согласно условиям выборки,
|
|
|
+или всей коллекции сразу.
|
|
|
+
|
|
|
+```js
|
|
|
+// коллекция имеет три документа
|
|
|
+// [
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "type": "city",
|
|
|
+// "name": "Bangkok",
|
|
|
+// "hidden": true
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 2,
|
|
|
+// "type": "country",
|
|
|
+// "name": "Thailand",
|
|
|
+// "hidden": true
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 3,
|
|
|
+// "type": "city",
|
|
|
+// "name": "Moscow",
|
|
|
+// "hidden": true
|
|
|
+// }
|
|
|
+// ]
|
|
|
+
|
|
|
+// вызов метода `patch` с передачей
|
|
|
+// значений для обновляемых полей
|
|
|
+const result = await rep.patch({
|
|
|
+ hidden: false,
|
|
|
+ updatedAt: new Date().toISOString(),
|
|
|
+});
|
|
|
+
|
|
|
+// вывод количество затронутых документов
|
|
|
+console.log(result);
|
|
|
+// 3
|
|
|
+
|
|
|
+// просмотр коллекции методом `find`
|
|
|
+// для проверки изменений
|
|
|
+const docs = await rep.find();
|
|
|
+console.log(docs);
|
|
|
+// [
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "type": "city",
|
|
|
+// "name": "Bangkok",
|
|
|
+// "hidden": false, <= обновлено
|
|
|
+// "updatedAt": "2023-12-02T14:00:00.000Z" <= новое поле
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 2,
|
|
|
+// "type": "country",
|
|
|
+// "name": "Thailand",
|
|
|
+// "hidden": false, <= обновлено
|
|
|
+// "updatedAt": "2023-12-02T14:00:00.000Z" <= новое поле
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 3,
|
|
|
+// "type": "city",
|
|
|
+// "name": "Moscow",
|
|
|
+// "hidden": false, <= обновлено
|
|
|
+// "updatedAt": "2023-12-02T14:00:00.000Z" <= новое поле
|
|
|
+// }
|
|
|
+// ]
|
|
|
+```
|
|
|
+
|
|
|
+Использование второго параметра `where` метода `patch` позволяет
|
|
|
+определить условия выборки обновляемых документов.
|
|
|
+
|
|
|
+```js
|
|
|
+// вызов метода `patch` с передачей
|
|
|
+// условий выборки вторым параметром
|
|
|
+const result = await rep.patch(
|
|
|
+ // новые значения полей
|
|
|
+ {
|
|
|
+ hidden: false,
|
|
|
+ updatedAt: new Date().toISOString(),
|
|
|
+ },
|
|
|
+ // условия выборки
|
|
|
+ {
|
|
|
+ type: 'city', // только если "type" равен "city"
|
|
|
+ hidden: true, // и "hidden" имеет значение true
|
|
|
+ }
|
|
|
+);
|
|
|
+
|
|
|
+// вывод количества затронутых документов
|
|
|
+console.log(result);
|
|
|
+// 2
|
|
|
+
|
|
|
+// по условиям выборки обновлено
|
|
|
+// только 2 документа из 3-х
|
|
|
+```
|
|
|
+
|
|
|
+#### find(filter = undefined)
|
|
|
+
|
|
|
+Возвращает все документы коллекции или согласно условию.
|
|
|
+
|
|
|
+```js
|
|
|
+// вызов метода `find` без аргументов
|
|
|
+// возвращает все документы коллекции
|
|
|
+const result = await rep.find();
|
|
|
+console.log(result);
|
|
|
+// [
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "type": "article",
|
|
|
+// "title": "The Forgotten Ship",
|
|
|
+// "publishedAt": "2023-12-02T08:00:00.000Z",
|
|
|
+// "featured": true
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 2,
|
|
|
+// "type": "article",
|
|
|
+// "title": "A Giant Bellows",
|
|
|
+// "publishedAt": "2023-12-02T12:00:00.000Z",
|
|
|
+// "featured": false
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 3,
|
|
|
+// "type": "letter",
|
|
|
+// "title": "Hundreds of bottles",
|
|
|
+// "publishedAt": null,
|
|
|
+// "featured": false
|
|
|
+// }
|
|
|
+// ]
|
|
|
+```
|
|
|
+
|
|
|
+Фильтрация результата (опционально).
|
|
|
+
|
|
|
+```js
|
|
|
+// первый параметр может принимать
|
|
|
+// объект cо следующими настройками
|
|
|
+const result = await rep.find({
|
|
|
+ // "where" - фильтрация выборки по условию, где
|
|
|
+ // указанные поля должны содержать определенные
|
|
|
+ // значения (см. Фильтрация)
|
|
|
+ where: {type: 'article', featured: true},
|
|
|
+ where: {title: {like: 'the forgotten'}},
|
|
|
+ where: {publishedAt: {lte: '2023-12-02T21:00:00.000Z'}},
|
|
|
+
|
|
|
+ // "order" - сортировка по указанному полю может
|
|
|
+ // принимать постфикс DESC для обратного порядка
|
|
|
+ order: 'featured',
|
|
|
+ order: 'publishedAt DESC',
|
|
|
+ order: ['publishedAt DESC', 'featured ASC', 'id'],
|
|
|
+
|
|
|
+ // "limit" - ограничение результата
|
|
|
+ // "skip" - пропуск документов
|
|
|
+ limit: 10,
|
|
|
+ skip: 10,
|
|
|
+
|
|
|
+ // "fields" - если определено, то результат
|
|
|
+ // будет включать только указанные поля
|
|
|
+ fields: 'title',
|
|
|
+ fields: ['title', 'featured'],
|
|
|
+
|
|
|
+ // "include" - включить в результат связанные
|
|
|
+ // документы (см. Связи)
|
|
|
+ include: 'author',
|
|
|
+ include: {author: 'role'},
|
|
|
+ include: ['author', 'categories'],
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+#### findOne(filter = undefined)
|
|
|
+
|
|
|
+Возвращает первый найденный документ или `undefined`
|
|
|
+
|
|
|
+```js
|
|
|
+// коллекция имеет три документа
|
|
|
+// [
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "type": "article",
|
|
|
+// "title": "The Forgotten Ship",
|
|
|
+// "publishedAt": "2023-12-02T08:00:00.000Z",
|
|
|
+// "featured": true
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 2,
|
|
|
+// "type": "article",
|
|
|
+// "title": "A Giant Bellows",
|
|
|
+// "publishedAt": "2023-12-02T12:00:00.000Z",
|
|
|
+// "featured": false
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 3,
|
|
|
+// "type": "letter",
|
|
|
+// "title": "Hundreds of bottles",
|
|
|
+// "publishedAt": null,
|
|
|
+// "featured": false
|
|
|
+// }
|
|
|
+// ]
|
|
|
+
|
|
|
+// вызов метода `findOne` без аргументов
|
|
|
+// возвращает первый документ коллекции
|
|
|
+const result = await rep.findOne();
|
|
|
+console.log(result);
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "type": "article",
|
|
|
+// "title": "The Forgotten Ship",
|
|
|
+// "publishedAt": "2023-12-02T08:00:00.000Z",
|
|
|
+// "featured": true
|
|
|
+// }
|
|
|
+```
|
|
|
+
|
|
|
+Фильтрация результата (опционально).
|
|
|
+
|
|
|
+```js
|
|
|
+// первый параметр метода `find` принимает
|
|
|
+// объект настроек возвращаемого результата
|
|
|
+const result = await rep.findOne({
|
|
|
+ // "where" - фильтрация выборки по условию, где
|
|
|
+ // указанные поля должны содержать определенные
|
|
|
+ // значения (см. Фильтрация)
|
|
|
+ where: {type: 'article', featured: true},
|
|
|
+ where: {title: {like: 'the forgotten'}},
|
|
|
+ where: {publishedAt: {lte: '2023-12-02T21:00:00.000Z'}},
|
|
|
+
|
|
|
+ // "order" - сортировка по указанному полю может
|
|
|
+ // принимать постфикс DESC для обратного порядка
|
|
|
+ order: 'featured',
|
|
|
+ order: 'publishedAt DESC',
|
|
|
+ order: ['publishedAt DESC', 'featured ASC', 'id'],
|
|
|
+
|
|
|
+ // "skip" - пропуск документов
|
|
|
+ skip: 10,
|
|
|
+
|
|
|
+ // "fields" - если определено, то результат
|
|
|
+ // будет включать только указанные поля
|
|
|
+ fields: 'title',
|
|
|
+ fields: ['title', 'featured'],
|
|
|
+
|
|
|
+ // "include" - включить в результат связанные
|
|
|
+ // документы (см. Связи)
|
|
|
+ include: 'author',
|
|
|
+ include: {author: 'role'},
|
|
|
+ include: ['author', 'categories'],
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+#### findById(id, filter = undefined)
|
|
|
+
|
|
|
+Поиск документа по идентификатору. Возвращает найденный документ
|
|
|
+или выбрасывает исключение.
|
|
|
+
|
|
|
+```js
|
|
|
+// коллекция содержит три документа
|
|
|
+// [
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "title": "The Forgotten Ship",
|
|
|
+// "featured": true
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 2,
|
|
|
+// "title": "A Giant Bellows",
|
|
|
+// "featured": false
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 3,
|
|
|
+// "title": "Hundreds of bottles",
|
|
|
+// "featured": false
|
|
|
+// }
|
|
|
+// ]
|
|
|
+
|
|
|
+// вызов метода `findById` с передачей
|
|
|
+// идентификатора искомого документа
|
|
|
+const result = await rep.findById(2);
|
|
|
+console.log(result);
|
|
|
+// {
|
|
|
+// "id": 2,
|
|
|
+// "title": "A Giant Bellows",
|
|
|
+// "featured": false
|
|
|
+// }
|
|
|
+```
|
|
|
+
|
|
|
+Использование параметра `filter` (опционально).
|
|
|
+
|
|
|
+```js
|
|
|
+// второй параметр метода `findById` принимает
|
|
|
+// объект настроек возвращаемого результата
|
|
|
+const result = await rep.findById(2, {
|
|
|
+ // "fields" - если определено, то результат
|
|
|
+ // будут включать только указанные поля
|
|
|
+ fields: 'title',
|
|
|
+ fields: ['title', 'featured'],
|
|
|
+
|
|
|
+ // "include" - включить в результат связанные
|
|
|
+ // документы (см. Связи)
|
|
|
+ include: 'author',
|
|
|
+ include: {author: 'role'},
|
|
|
+ include: ['author', 'categories'],
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+#### delete(where = undefined)
|
|
|
+
|
|
|
+Удаляет все документы коллекции или согласно условию. Возвращает количество
|
|
|
+удаленных документов.
|
|
|
+
|
|
|
+```js
|
|
|
+// коллекция имеет три документа
|
|
|
+// [
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "title": "The Forgotten Ship",
|
|
|
+// "featured": true
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 2,
|
|
|
+// "title": "A Giant Bellows",
|
|
|
+// "featured": false
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 3,
|
|
|
+// "title": "Hundreds of bottles",
|
|
|
+// "featured": false
|
|
|
+// }
|
|
|
+// ]
|
|
|
+
|
|
|
+// вызов метода `delete` без аргументов
|
|
|
+// удалит все содержимое коллекции
|
|
|
+const result = await rep.delete();
|
|
|
+console.log(result);
|
|
|
+// 3
|
|
|
+
|
|
|
+// просмотр коллекции методом `find`
|
|
|
+// для проверки изменений
|
|
|
+const docs = await rep.find();
|
|
|
+console.log(docs);
|
|
|
+// []
|
|
|
+```
|
|
|
+
|
|
|
+Условия выборки (опционально).
|
|
|
+
|
|
|
+```js
|
|
|
+// первый параметр метода `delete`
|
|
|
+// принимает условия выборки
|
|
|
+const result = await rep.delete({
|
|
|
+ title: {
|
|
|
+ like: 'bellows', // оператор "like" проверяет поле "title"
|
|
|
+ }, // на содержание подстроки "bellows"
|
|
|
+ featured: false, // значение поля "featured" должно быть false
|
|
|
+ // см. Фильтрация
|
|
|
+});
|
|
|
+
|
|
|
+// вывод результата
|
|
|
+console.log(result);
|
|
|
+// 1
|
|
|
+```
|
|
|
+
|
|
|
+#### deleteById(id)
|
|
|
+
|
|
|
+Удаляет документ по идентификатору. Возвращает `true` в случае успеха
|
|
|
+или `false` если не найден.
|
|
|
+
|
|
|
+```js
|
|
|
+// коллекция имеет три документа
|
|
|
+// [
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "title": "The Forgotten Ship"
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 2,
|
|
|
+// "title": "A Giant Bellows"
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 3,
|
|
|
+// "title": "Hundreds of bottles"
|
|
|
+// }
|
|
|
+// ]
|
|
|
+
|
|
|
+// вызов метода `deleteById` с передачей
|
|
|
+// идентификатора удаляемого документа
|
|
|
+const result = await rep.deleteById(2);
|
|
|
+
|
|
|
+// вывод результата
|
|
|
+console.log(result);
|
|
|
+// true
|
|
|
+
|
|
|
+// просмотр коллекции методом `find`
|
|
|
+// для проверки изменений
|
|
|
+const docs = await rep.find();
|
|
|
+console.log(docs);
|
|
|
+// [
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "title": "The Forgotten Ship"
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 3,
|
|
|
+// "title": "Hundreds of bottles"
|
|
|
+// }
|
|
|
+// ]
|
|
|
+```
|
|
|
+
|
|
|
+#### exists(id)
|
|
|
+
|
|
|
+Проверка существования документа по идентификатору. Возвращает `true`
|
|
|
+если найден, в противном случае `false`.
|
|
|
+
|
|
|
+```js
|
|
|
+// коллекция имеет три документа
|
|
|
+// [
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "title": "The Forgotten Ship"
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 2,
|
|
|
+// "title": "A Giant Bellows"
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 3,
|
|
|
+// "title": "Hundreds of bottles"
|
|
|
+// }
|
|
|
+// ]
|
|
|
+
|
|
|
+// вызов метода `exists` с передачей
|
|
|
+// существующего идентификатора
|
|
|
+const result1 = await rep.exists(2);
|
|
|
+console.log(result1);
|
|
|
+// true
|
|
|
+
|
|
|
+// результат проверки несуществующего
|
|
|
+// идентификатора
|
|
|
+const result2 = await rep.exists(10);
|
|
|
+console.log(result2);
|
|
|
+// false
|
|
|
+```
|
|
|
+
|
|
|
+#### count(where = undefined)
|
|
|
+
|
|
|
+Подсчет количества документов и возврат их числа.
|
|
|
+
|
|
|
+```js
|
|
|
+// коллекция имеет три документа
|
|
|
+// [
|
|
|
+// {
|
|
|
+// "id": 1,
|
|
|
+// "title": "The Forgotten Ship",
|
|
|
+// "featured": true
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 2,
|
|
|
+// "title": "A Giant Bellows",
|
|
|
+// "featured": false
|
|
|
+// },
|
|
|
+// {
|
|
|
+// "id": 3,
|
|
|
+// "title": "Hundreds of bottles",
|
|
|
+// "featured": false
|
|
|
+// }
|
|
|
+// ]
|
|
|
+
|
|
|
+// вызов метода `count` без аргументов
|
|
|
+// возвращает общее число документов
|
|
|
+const result = await rep.count();
|
|
|
+console.log(result);
|
|
|
+// 3
|
|
|
+```
|
|
|
+
|
|
|
+Условия выборки (опционально).
|
|
|
+
|
|
|
+```js
|
|
|
+// первый параметр метода `count`
|
|
|
+// принимает условия выборки
|
|
|
+const result = await rep.count({
|
|
|
+ featured: { // оператор "neq" проверяет поле "featured"
|
|
|
+ neq: true, // на неравенство значению true
|
|
|
+ }
|
|
|
+ // см. Фильтрация
|
|
|
+});
|
|
|
+
|
|
|
+// вывод результата
|
|
|
+console.log(result);
|
|
|
+// 2
|
|
|
+```
|
|
|
+
|
|
|
+## Расширение
|
|
|
+
|
|
|
+При использовании метода `getRepository` выполняется проверка на
|
|
|
+наличие существующего экземпляра репозитория для нужной модели.
|
|
|
+При первичном запросе создается новый экземпляр, который будет
|
|
|
+сохранен для повторных обращений к методу.
|
|
|
+
|
|
|
+```js
|
|
|
+import {Schema} from '@e22m4u/js-repository';
|
|
|
+import {Repository} from '@e22m4u/js-repository';
|
|
|
+
|
|
|
+// const schema = new Schema();
|
|
|
+// schema.defineDatasource ...
|
|
|
+// schema.defineModel ...
|
|
|
+
|
|
|
+const rep1 = schema.getRepository('myModel');
|
|
|
+const rep2 = schema.getRepository('myModel');
|
|
|
+console.log(rep1 === rep2); // true
|
|
|
+```
|
|
|
+
|
|
|
+Если требуется изменить или расширить поведение репозитория, то
|
|
|
+перед его созданием можно переопределить его конструктор методом
|
|
|
+`setRepositoryCtor`. После чего, все создаваемые репозитории будут
|
|
|
+использовать уже пользовательский конструктор вместо стандартного.
|
|
|
+
|
|
|
+```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.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`
|
|
|
+
|
|
|
+## Связи
|
|
|
+
|
|
|
+Параметр `relations` описывает набор связей к другим моделям.
|
|
|
+
|
|
|
+Понятия:
|
|
|
+
|
|
|
+- источник связи
|
|
|
+*- модель в которой определена данная связь*
|
|
|
+- целевая модель
|
|
|
+*- модель на которую ссылается источник связи*
|
|
|
+
|
|
|
+Типы:
|
|
|
+
|
|
|
+- `belongsTo` - ссылка на целевую модель находится в источнике
|
|
|
+- `hasOne` - ссылка на источник находится в целевой модели (one-to-one)
|
|
|
+- `hasMany` - ссылка на источник находится в целевой модели (one-to-many)
|
|
|
+- `referencesMany` - массив ссылок на целевую модель находится в источнике
|
|
|
+
|
|
|
+Параметры:
|
|
|
+
|
|
|
+- `type: string` тип связи
|
|
|
+- `model: string` целевая модель
|
|
|
+- `foreignKey: string` поле для идентификатора цели
|
|
|
+- `polymorphic: boolean|string` объявить связь полиморфной*
|
|
|
+- `discriminator: string` поле для названия целевой модели (для `polymorphic: true`)
|
|
|
+
|
|
|
+*i. Полиморфный режим `belongsTo` позволяет динамически определять цель связи,
|
|
|
+где имя целевой модели хранится в отдельном поле, рядом с `foreignKey`*
|
|
|
+
|
|
|
+#### BelongsTo
|
|
|
+
|
|
|
+Связь заказа к покупателю через поле `customerId`
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ // ...
|
|
|
+ relations: {
|
|
|
+ // ...
|
|
|
+ customer: {
|
|
|
+ type: 'belongsTo',
|
|
|
+ model: 'customer',
|
|
|
+ foreignKey: 'customerId', // опционально
|
|
|
+ },
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+Полиморфная версия
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ // ...
|
|
|
+ relations: {
|
|
|
+ // ...
|
|
|
+ customer: {
|
|
|
+ type: 'belongsTo',
|
|
|
+ polymorphic: true,
|
|
|
+ foreignKey: 'customerId', // опционально
|
|
|
+ discriminator: 'customerType', // опционально
|
|
|
+ },
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+#### HasOne (one-to-one)
|
|
|
+
|
|
|
+Связь покупателя к заказу, как обратная сторона `belongsTo`
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ // ...
|
|
|
+ relations: {
|
|
|
+ // ...
|
|
|
+ order: {
|
|
|
+ type: 'hasOne',
|
|
|
+ model: 'order',
|
|
|
+ foreignKey: 'customerId', // поле целевой модели
|
|
|
+ },
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+Обратная сторона полиморфной версии `belongsTo`
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ // ...
|
|
|
+ relations: {
|
|
|
+ // ...
|
|
|
+ order: {
|
|
|
+ type: 'hasOne',
|
|
|
+ model: 'order',
|
|
|
+ polymorphic: 'customer', // имя связи целевой модели
|
|
|
+ },
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+Явное указание `foreignKey` и `discriminator`
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ // ...
|
|
|
+ relations: {
|
|
|
+ // ...
|
|
|
+ order: {
|
|
|
+ type: 'hasOne',
|
|
|
+ model: 'order',
|
|
|
+ polymorphic: true, // true вместо имени модели
|
|
|
+ foreignKey: 'customerId', // поле целевой модели
|
|
|
+ discriminator: 'customerType', // поле целевой модели
|
|
|
+ },
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+#### HasMany (one-to-many)
|
|
|
+
|
|
|
+Связь покупателя к заказам, как обратная сторона `belongsTo`
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ // ...
|
|
|
+ relations: {
|
|
|
+ // ...
|
|
|
+ orders: {
|
|
|
+ type: 'hasMany',
|
|
|
+ model: 'order',
|
|
|
+ foreignKey: 'customerId', // поле целевой модели
|
|
|
+ },
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+Обратная сторона полиморфной версии `belongsTo`
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ // ...
|
|
|
+ relations: {
|
|
|
+ // ...
|
|
|
+ orders: {
|
|
|
+ type: 'hasMany',
|
|
|
+ model: 'order',
|
|
|
+ polymorphic: 'customer', // имя связи целевой модели
|
|
|
+ },
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+Явное указание `foreignKey` и `discriminator`
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ // ...
|
|
|
+ relations: {
|
|
|
+ // ...
|
|
|
+ orders: {
|
|
|
+ type: 'hasMany',
|
|
|
+ model: 'order',
|
|
|
+ polymorphic: true, // true вместо имени модели
|
|
|
+ foreignKey: 'customerId', // поле целевой модели
|
|
|
+ discriminator: 'customerType', // поле целевой модели
|
|
|
+ },
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+#### ReferencesMany
|
|
|
+
|
|
|
+Связь покупателя к заказам через поле `orderIds`
|
|
|
+
|
|
|
+```js
|
|
|
+schema.defineModel({
|
|
|
+ // ...
|
|
|
+ relations: {
|
|
|
+ // ...
|
|
|
+ orders: {
|
|
|
+ type: 'referencesMany',
|
|
|
+ model: 'order',
|
|
|
+ foreignKey: 'orderIds', // опционально
|
|
|
+ },
|
|
|
+ },
|
|
|
+});
|
|
|
+```
|
|
|
+
|
|
|
+-->
|
|
|
+
|
|
|
+## Тесты
|
|
|
+
|
|
|
+```bash
|
|
|
+npm run test
|
|
|
+```
|
|
|
+
|
|
|
+## Лицензия
|
|
|
+
|
|
|
+MIT
|
e22m4u