chore: updates README.md

README.md

@@ -221,13 +221,112 @@ const rep = schema.getRepository('place');
 - `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'}}` флаги регулярного выражения
+
+<!--
+```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
-// вызов метода `create` с передачей состава
-// нового документа первым параметром
 const result = await rep.create({
   name: 'Rick Sanchez',
   dimension: 'C-137',
@@ -244,6 +343,35 @@ console.log(result);
 // }
 ```
 
+Ограничение количества возвращаемых полей.
+
+```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` позволяет
 ограничивать количество возвращаемых данных, и разрешать связи к другим
 коллекциям (см. Связи).
@@ -1030,7 +1158,6 @@ schema.get(RepositoryRegistry).setRepositoryCtor(MyRepository);
 // экземпляр класса MyRepository
 ```
 
-<!--
 ### Filter
 
 Большинство методов репозитория принимают объект `filter` для