chore: updates README.md

README.md

@@ -223,8 +223,7 @@ const rep = schema.getRepository('place');
 
 #### create(data, filter = undefined)
 
-Добавляет новый документ в коллекцию.  
-Возвращает добавленный документ.  
+Добавляет новый документ в коллекцию и возвращает его.
 
 ```js
 // вызываем метод `create` с передачей состава
@@ -235,7 +234,7 @@ const person = await rep.create({
   age: 67,
 });
 
-// выводим добавленный документ
+// выводим результат
 console.log(person);
 // {
 //   id: 1,
@@ -257,8 +256,7 @@ const result = await rep.create(data, {
   fields: ['name', 'age'],
 
   // "include" - включить в результат связанные
-  // документы по имени связи, которая определена
-  // в модели данного репозитория
+  // документы (см. Связанные документы)
   include: 'son',
   include: {son: 'hobbies'},
   include: ['son', 'daughter'],
@@ -267,8 +265,8 @@ const result = await rep.create(data, {
 
 #### replaceById(id, data, filter = undefined)
 
-Заменяет существующий документ.  
-Возвращает затронутый документ.  
+Заменяет существующий документ по идентификатору и возвращает его. Если
+идентификатор не найден, то выбрасывает исключение.
 
 ```js
 // документ с идентификатором 1 имеет
@@ -302,13 +300,12 @@ console.log(person);
 
 #### patch(data, where = undefined)
 
-Частично обновляет документы коллекции.  
-Возвращает число затронутых документов.  
+Обновляет документы и возвращает их число. Используется для
+обновления нескольких документов согласно условиям выборки,
+или всей коллекции сразу.
 
 ```js
-// перед выполнением метода `patch`
-// содержание коллекции имеет состав
-// из двух документов
+// коллекция имеет два документа
 // [
 //   {
 //     "id": 1,
@@ -322,8 +319,8 @@ console.log(person);
 //   }
 // ]
 
-// первым аргументом передаем объект
-// с данными для обновления
+// вызываем метод `patch` с передачей
+// значений для обновляемых полей
 const result = await rep.patch({
   type: 'city',
   updatedAt: new Date().toISOString(),
@@ -334,8 +331,8 @@ const result = await rep.patch({
 console.log(result);
 // 2
 
-// методом `find` просматриваем содержимое
-// коллекции для проверки изменений
+// методом `find` просматриваем коллекцию
+// для проверки изменений
 const docs = await rep.find();
 console.log(docs);
 // [
@@ -354,15 +351,15 @@ console.log(docs);
 // ]
 ```
 
-Использование параметра `where`
+Условия выборки обновляемых документов.
 
 ```js
-// второй параметр опционально принимает
-// условие выборки обновляемых документов
+// второй параметр метода `patch` принимает
+// условия выборки (опционально)
 const result = await rep.patch(data, {
   type: 'city',          // поле "type" должно иметь значение "city"
   description: {         // оператор "like" проверяет поле "description"
-    like: 'the capital', // на наличие подстроки "the capital" в его значении
+    like: 'the capital', // на наличие подстроки "the capital"
   },
   updatedAt: {                      // оператор "lt" проверяет значение поля
     lt: '2023-12-02T21:00:00.000Z', // "updatedAt" на наличие более ранней даты,
@@ -373,34 +370,42 @@ const result = await rep.patch(data, {
 
 #### 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"
+//   "name": "Sheremetyevo Airport", <= значение обновлено
+//   "code": "SVO", <= значение обновлено
+//   "featured": true <= добавлено новое поле
 // }
 ```
 
 #### find(filter = undefined)
 
-Поиск по коллекции репозитория.  
-Возвращает найденные документы в виде массива.
+Возвращает все документы коллекции, или использует условия выборки.
 
 ```js
 // вызов метода `find` без аргументов
@@ -426,25 +431,24 @@ console.log(result);
 Фильтрация результата в параметре `filter`
 
 ```js
-// первый параметр опционально принимает
-// объект описывающий параметры выборки
+// первый параметр принимает объект
+// c настройками выборки (опционально)
 const result = await rep.find({
   // "where" - фильтрация выборки по условию, где
-  // указанные поля документа должны содержать
-  // определенные значения
+  // указанные поля должны содержать определенные
+  // значения (см. Фильтрация)
   where: {type: 'article', published: true},
   where: {description: {like: 'breaking news'}},
   where: {publishedAt: {lte: '2023-12-02T21:00:00.000Z'}},
 
   // "order" - сортировка по указанному полю может
-  // принимать постфикс ASC или DESC указывающий
-  // направление порядка (прим. 'id DESC')
+  // принимать постфикс DESC для обратного порядка
   order: 'foo',
   order: 'bar DESC',
   order: ['foo', 'bar DESC'],
 
-  // "limit" - ограничение выборки числом документов
-  // "skip" - пропуск указанного числа документов
+  // "limit" - ограничение результата
+  // "skip" - пропуск документов
   limit: 10,
   skip: 10,
 
@@ -454,8 +458,7 @@ const result = await rep.find({
   fields: ['title', 'published'],
 
   // "include" - включить в результат связанные
-  // документы по имени связи, которая определена
-  // в модели данной коллекции
+  // документы (см. Связанные документы)
   include: 'author',
   include: {author: 'city'},
   include: ['author', 'categories'],
@@ -464,8 +467,7 @@ const result = await rep.find({
 
 #### findOne(filter = undefined)
 
-Поиск первого документа коллекции.  
-Возвращает найденный документ или `undefined`  
+Возвращает первый найденный документ или `undefined`  
 
 ```js
 // [