@e22m4u/js-repository 0.0.40 → 0.0.42

package/README.md

@@ -8,8 +8,8 @@
 npm install @e22m4u/js-repository
 ```
 
-Опционально устанавливаем адаптер. Например, если используемой базой
-является *MongoDB*, то для подключения потребуется добавить
+Опционально устанавливаем адаптер. Например, если используется
+*MongoDB*, то для подключения потребуется установить
 [адаптер mongodb](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter)
 как отдельную зависимость.
 
@@ -17,7 +17,7 @@ npm install @e22m4u/js-repository
 npm install @e22m4u/js-repository-mongodb-adapter
 ```
 
-Список доступных адаптеров:
+**Список доступных адаптеров:**
 
 | адаптер   | описание                                                                                                                                        |
 |-----------|-------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -28,13 +28,13 @@ npm install @e22m4u/js-repository-mongodb-adapter
 
 Модуль позволяет спроектировать систему связанных данных, доступ к которым
 осуществляется посредством репозиториев. Каждый репозиторий имеет собственную
-модель, которая описывает структуру определенной коллекции в базе,
+модель данных, которая описывает структуру определенной коллекции в базе,
 а так же определяет связи к другим коллекциям.
 
 ```mermaid
 flowchart LR
 
-A[Datasource]-->B[Model]-->С[Repository];
+A[Datasource]-->B[Data Model]-->С[Repository];
 ```
 
 ## Использование
@@ -54,7 +54,7 @@ const schema = new Schema();
 - `defineModel(modelDef: object): this` - добавить модель
 - `getRepository(modelName: string): Repository` - получить репозиторий
 
-#### Источник данных
+### Источник данных
 
 Источник описывает способ подключения к базе и используемый адаптер.
 Если адаптер имеет настройки, то они передаются вместе с объектом
@@ -72,7 +72,7 @@ schema.defineDatasource({
 });
 ```
 
-Параметры источника:
+**Параметры источника:**
 
 - `name: string` уникальное название
 - `adapter: string` выбранный адаптер
@@ -88,7 +88,7 @@ schema.defineDatasource({
 });
 ```
 
-#### Модель данных
+### Модель данных
 
 Когда источники определены, можно перейти к описанию моделей данных.
 Модель может определять как структуру какого-либо объекта,
@@ -109,7 +109,7 @@ schema.defineModel({
 });
 ```
 
-Параметры модели:
+**Параметры модели:**
 
 - `name: string` уникальное название (обязательно)
 - `datasource: string` выбранный источник данных
@@ -124,15 +124,15 @@ schema.defineModel({
   name: 'latLng',
   properties: {
     lat: DataType.NUMBER, // краткое определение поля "lat"
-    lng: { // определение поля "lng" с параметром "required"
-      type: DataType.NUMBER,
+    lng: { // расширенное определение поля "lng"
+      type: DataType.NUMBER, // тип допустимого значения
       required: true, // исключает null и undefined
     },
   },
 });
 ```
 
-Типы данных:
+**Типы данных:**
 
 - `DataType.ANY`
 - `DataType.STRING`
@@ -167,7 +167,7 @@ schema.defineModel({
 ```json
 {
   "id": 1,
-  "name": "Burger King at Avenue Mall",
+  "name": "Burger King",
   "location": {
     "lat": 32.412891,
     "lng": 34.7660061
@@ -186,7 +186,7 @@ schema.defineModel({
 });
 ```
 
-Параметры поля:
+**Параметры поля:**
 
 - `type: string` тип допустимого значения (обязательно)
 - `itemType: string` тип элемента массива (для `type: 'array'`)
@@ -197,7 +197,7 @@ schema.defineModel({
 - `required: boolean` объявить поле обязательным
 - `default: any` значение по умолчанию
 
-#### Репозиторий
+### Репозиторий
 
 В отличие от `latLng`, модель `place` имеет источник данных с названием
 `myMemory`, который был объявлен ранее. Наличие источника позволяет получить
@@ -207,6 +207,153 @@ schema.defineModel({
 const rep = schema.getRepository('place');
 ```
 
+**Методы:**
+
+- `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",
+  "location": {
+    "lat": 32.412891,
+    "lng": 34.7660061
+  },
+});
+
+console.log(place);
+// {
+//   "id": 1,
+//   "name": "Burger King",
+//   "location": {
+//     "lat": 32.412891,
+//     "lng": 34.7660061
+//   }
+// }
+```
+
+#### replaceById(id, data, filter = undefined)
+
+Добавленный в базу документ можно полностью заменить зная его идентификатор.
+Воспользуемся методом `replaceById`, который перезапишет данные по значению
+первичного ключа.
+
+```js
+// {
+//   "id": 1,
+//   "name": "Burger King",
+//   "location": {
+//     "lat": 32.412891,
+//     "lng": 34.7660061
+//   }
+// }
+const result = rep.replaceById(place.id, {
+  name: 'Starbucks',
+  address: 'Sukhumvit Alley'
+});
+
+console.log(result);
+// {
+//   "id": 1,
+//   "name": "Starbucks",
+//   "address": "Sukhumvit Alley"
+// }
+```
+
+#### replaceOrCreate(data, filter = undefined)
+
+Если вы знакомы с методом PUT в архитектуре REST, когда документ
+добавляется, если его не существовало, или же обновляется существующий,
+то `replaceOrCreate` работает схожим образом. Если параметр
+`data` передаваемый первым аргументом будет содержать идентификатор,
+то метод будет вести себя как `replaceById`, в противном случае будет
+создан новый документ.
+
+```js
+// {
+//   "id": 1,
+//   "name": "Starbucks",
+//   "address": "Sukhumvit Alley"
+// }
+const result = rep.replaceOrCreate({
+  id: 1,
+  name: 'Airport',
+  city: 'Antalya',
+  code: 'AYT'
+});
+
+console.log(result);
+// {
+//   "id": 1,
+//   "name": "Airport",
+//   "city": "Antalya"
+//   "code": "AYT"
+// }
+```
+
+В примере выше был передан первичный ключ `id` для поиска и
+замены существующего документа. Теперь рассмотрим создание 
+документа с новым идентификатором.
+
+```js
+const result = rep.replaceOrCreate({
+  name: 'Airport',
+  city: 'Bangkok',
+  code: 'BKK',
+});
+
+console.log(result);
+// {
+//   "id": 2,
+//   "name": "Airport",
+//   "city": "Bangkok",
+//   "code": "BKK"
+// }
+```
+
+#### patchById(id, data, filter = undefined)
+
+В отличие от `replaceById`, данный метод не удаляет поля, которые
+не были переданы, что позволяет обновить только часть документа,
+не затрагивая другие данные.
+
+```js
+// {
+//   "id": 2,
+//   "name": "Airport",
+//   "city": "Bangkok",
+//   "code": "BKK"
+// }
+const result = rep.patchById(place.id, {
+  city: 'Moscow',
+  code: 'SVO'
+});
+
+console.log(result);
+// {
+//   "id": 2,
+//   "name": "Airport",
+//   "city": "Moscow",
+//   "code": "SVO"
+// }
+```
+
 ## Пример
 
 Создаем модель `user`
@@ -275,6 +422,7 @@ await userRep.deleteById(fedor.id); // true
 - `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)`
@@ -573,7 +721,7 @@ schema.defineModel({
     order: {
       type: 'hasOne',
       model: 'order',
-      foreignKey: 'customerId', // опционально
+      foreignKey: 'customerId', // поле целевой модели
     },
   },
 });
@@ -625,7 +773,7 @@ schema.defineModel({
     orders: {
       type: 'hasMany',
       model: 'order',
-      foreignKey: 'customerId', // опционально
+      foreignKey: 'customerId', // поле целевой модели
     },
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-repository",
-  "version": "0.0.40",
+  "version": "0.0.42",
   "description": "Абстракция для работы с базами данных для Node.js",
   "type": "module",
   "main": "src/index.js",
@@ -37,21 +37,21 @@
     "@e22m4u/js-format": "0.0.7"
   },
   "devDependencies": {
-    "@commitlint/cli": "^17.7.1",
+    "@commitlint/cli": "^17.7.2",
     "@commitlint/config-conventional": "^17.7.0",
     "c8": "^8.0.1",
-    "chai": "^4.3.7",
+    "chai": "^4.3.10",
     "chai-as-promised": "^7.1.1",
     "chai-spies": "^1.0.0",
     "chai-subset": "^1.6.0",
-    "eslint": "^8.47.0",
+    "eslint": "^8.51.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-chai-expect": "^3.0.0",
     "eslint-plugin-jsdoc": "^46.8.2",
-    "eslint-plugin-mocha": "^10.1.0",
+    "eslint-plugin-mocha": "^10.2.0",
     "husky": "^8.0.3",
     "mocha": "^10.2.0",
-    "prettier": "^3.0.1",
+    "prettier": "^3.0.3",
     "typescript": "^5.2.2"
   }
 }

package/src/adapter/adapter.d.ts

@@ -52,6 +52,19 @@ export declare class Adapter extends Service {
     filter?: ItemFilterClause,
   ): Promise<ModelData>;
 
+  /**
+   * Patch.
+   *
+   * @param modelName
+   * @param modelData
+   * @param where
+   */
+  patch(
+    modelName: string,
+    modelData: ModelData,
+    where?: WhereClause,
+  ): Promise<number>;
+
   /**
    * Patch by id.
    *

package/src/adapter/adapter.js

@@ -78,6 +78,21 @@ export class Adapter extends Service {
     );
   }
 
+  /**
+   * Patch.
+   *
+   * @param {string} modelName
+   * @param {object} modelData
+   * @param {object|undefined} where
+   * @returns {Promise<number>}
+   */
+  patch(modelName, modelData, where = undefined) {
+    throw new NotImplementedError(
+      '%s.patch is not implemented.',
+      this.constructor.name,
+    );
+  }
+
   /**
    * Patch by id.
    *

package/src/adapter/builtin/memory-adapter.d.ts

@@ -52,6 +52,19 @@ export declare class MemoryAdapter extends Adapter {
     filter?: ItemFilterClause,
   ): Promise<ModelData>;
 
+  /**
+   * Patch.
+   *
+   * @param modelName
+   * @param modelData
+   * @param where
+   */
+  patch(
+    modelName: string,
+    modelData: ModelData,
+    where?: WhereClause,
+  ): Promise<number>;
+
   /**
    * Patch by id.
    *

package/src/adapter/builtin/memory-adapter.js

@@ -154,6 +154,47 @@ export class MemoryAdapter extends Adapter {
     ).convertColumnNamesToPropertyNames(modelName, tableData);
   }
 
+  /**
+   * Patch.
+   *
+   * @param {string} modelName
+   * @param {object} modelData
+   * @param {object|undefined} where
+   * @returns {Promise<number>}
+   */
+  async patch(modelName, modelData, where = undefined) {
+    const table = this._getTableOrCreate(modelName);
+    const tableItems = Array.from(table.values());
+    if (!tableItems.length) return 0;
+    let modelItems = tableItems.map(tableItem =>
+      this.getService(ModelDefinitionUtils).convertColumnNamesToPropertyNames(
+        modelName,
+        tableItem,
+      ),
+    );
+
+    if (where && typeof where === 'object')
+      modelItems = this.getService(WhereClauseTool).filter(modelItems, where);
+    const size = modelItems.length;
+
+    const pkPropName =
+      this.getService(ModelDefinitionUtils).getPrimaryKeyAsPropertyName(
+        modelName,
+      );
+    modelData = cloneDeep(modelData);
+    delete modelData[pkPropName];
+
+    modelItems.forEach(existingModelData => {
+      const mergedModelData = Object.assign({}, existingModelData, modelData);
+      const mergedTableData = this.getService(
+        ModelDefinitionUtils,
+      ).convertPropertyNamesToColumnNames(modelName, mergedModelData);
+      const idValue = existingModelData[pkPropName];
+      table.set(idValue, mergedTableData);
+    });
+    return size;
+  }
+
   /**
    * Patch by id.
    *