@e22m4u/js-repository 0.6.1 → 0.6.2

package/README.md

@@ -1050,27 +1050,14 @@ console.log(res); // true
 - `fields: string|string[]` выбор необходимых свойств модели;
 - `include: object` включение связанных данных в результат;
 
-**Примеры**
-
-Объект фильтрации позволяет комбинировать различные опции для построения
-сложных запросов. Представим, что нам нужно выбрать из коллекции новости
-для отображения на сайте по следующему набору критериев:
-
-- Заголовок должен содержать слово «Moscow» без учета регистра.
-- Дата публикации должна быть не ранее 15 октября 2025 года.
-- Новость должна содержать один из тегов «world» или «politic».
-- Новость не должна быть скрытой `hidden: false`.
-- Результат должен быть отсортирован по дате публикации.
-- Нужно пропустить первые 24 записи и выбрать следующие 12.
-- Выборка должна включать только поля `title`, `annotation` и `body`.
-- К каждой новости добавить связанные данные `author` и `category`.
+**Пример**
 
 ```js
 // для запроса используется метод репозитория "find"
 // с передачей объекта фильтрации первым аргументом
 const news = await newsRepository.find({
   where: {
-    title: {regexp: 'Moscow', flags: 'i'},
+    title: {like: '%Moscow%'},
     publishedAt: {gte: '2025-10-15T00:00:00.000Z'},
     tags: {inq: ['world', 'politic']},
     hidden: false,
@@ -1083,82 +1070,324 @@ const news = await newsRepository.find({
 })
 ```
 
-Пример получения профиля пользователя со списком его последних постов.
+### where
+
+Параметр принимает объект с условиями выборки и поддерживает следующий набор
+операторов сравнения.
 
-- Найти пользователя по уникальному имени в свойстве `username`.
-- Из данных пользователя вернуть только имя, URL аватара и биографию.
-- Включить в результат 5 *опубликованных* постов данного пользователя.
-- Для каждого поста вернуть только заголовок и дату создания.
-- К каждому посту также прикрепить данные о категории.
+- [Поиск по значению](#поиск-по-значению-сокращенная-форма)
+- [`eq`](#eq-строгое-равенство) (строгое равенство)
+- [`neq`](#neq-неравенство) (неравенство)
+- [`gt`](#gt-больше-чем) (больше чем)
+- [`lt`](#lt-меньше-чем) (меньше чем)
+- [`gte`](#gte-больше-или-равно) (больше или равно)
+- [`lte`](#lte-меньше-или-равно) (меньше или равно)
+- [`inq`](#inq-в-списке) (в списке)
+- [`nin`](#nin-не-в-списке) (не в списке)
+- [`between`](#between-диапазон) (диапазон)
+- [`exists`](#exists-наличие-свойства) (наличие свойства)
+- [`like`](#like-шаблон) (шаблон)
+- [`nlike`](#nlike-исключающий-шаблон) (исключающий шаблон)
+- [`ilike`](#ilike-регистронезависимый-шаблон) (регистронезависимый шаблон)
+- [`nilike`](#nilike-регистронезависимый-шаблон-исключения) (регистронезависимый шаблон исключения)
+- [`regexp`](#regexp-регулярное-выражение) (регулярное выражение)
+
+Условия можно объединять логическими операторами:
+
+- [`and`](#and-логическое-и) (логическое И)
+- [`or`](#or-логическое-или) (логическое ИЛИ)
+
+#### Поиск по значению (сокращенная форма)
+
+Находит документы, у которых значение указанного свойства в точности равно
+переданному значению. Это сокращенная запись для оператора `{eq: ...}`.
 
 ```js
-// для запроса используется метод "findOne"
-// и вложенные фильтры в опции "include"
-const userProfile = await userRepository.findOne({
-  where: {username: 'john.doe'},
-  fields: ['username', 'avatarUrl', 'bio'],
-  include: {
-    relation: 'posts',
-    scope: {
-      where: {status: 'published'},
-      order: 'createdAt DESC',
-      limit: 5,
-      fields: ['title', 'createdAt'],
-      include: 'category',
-    },
+// найдет все документы, где age равен 21
+const res = await rep.find({
+  where: {
+    age: 21,
   },
 });
 ```
 
-### where
+#### `eq` (строгое равенство)
 
-Параметр принимает объект с условиями выборки и поддерживает широкий
-набор операторов сравнения.
-
-`{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'}}` флаги регулярного выражения
-
-*i. Условия можно объединять операторами `and`, `or` и `nor`.*
+Находит документы, у которых значение свойства равно указанному.
 
-**Примеры**
+```js
+// найдет все документы, где age равен 21
+const res = await rep.find({
+  where: {
+    age: {eq: 21},
+  },
+});
+```
 
-Применение условий выборки при подсчете документов.
+#### `neq` (неравенство)
+
+Находит документы, у которых значение свойства не равно указанному.
 
 ```js
-const res = await rep.count({
-  authorId: 251,
-  publishedAt: {
-    lte: '2023-12-02T14:00:00.000Z',
+// найдет все документы, где age не равен 21
+const res = await rep.find({
+  where: {
+    age: {neq: 21},
   },
 });
 ```
 
-Применение оператора `or` при удалении документов.
+#### `gt` (больше чем)
+
+Находит документы, у которых значение свойства строго больше указанного.
 
 ```js
-const res = await rep.delete({
-  or: [
-    {draft: true},
-    {title: {like: 'draft'}},
-  ],
+// найдет документы, где age больше 30
+const res = await rep.find({
+  where: {
+    age: {gt: 30},
+  },
 });
 ```
 
+#### `lt` (меньше чем)
+
+Находит документы, у которых значение свойства строго меньше указанного.
+
+```js
+// найдет документы, где age меньше 30
+const res = await rep.find({
+  where: {
+    age: {lt: 30},
+  },
+});
+```
+
+#### `gte` (больше или равно)
+
+Находит документы, у которых значение свойства больше или равно указанному.
+
+```js
+// найдет документы, где age больше или равен 30
+const res = await rep.find({
+  where: {
+    age: {gte: 30},
+  },
+});
+```
+
+#### `lte` (меньше или равно)
+
+Находит документы, у которых значение свойства меньше или равно указанному.
+
+```js
+// найдет документы, где age меньше или равен 30
+const res = await rep.find({
+  where: {
+    age: {lte: 30},
+  },
+});
+```
+
+#### `inq` (в списке)
+
+Находит документы, у которых значение свойства совпадает с одним из значений
+в предоставленном массиве.
+
+```js
+// найдет документы, где name - 'John' или 'Mary'
+const res = await rep.find({
+  where: {
+    name: {inq: ['John', 'Mary']},
+  },
+});
+```
+
+#### `nin` (не в списке)
+
+Находит документы, у которых значение свойства отсутствует в предоставленном
+массиве.
+
+```js
+// найдет все документы, кроме тех, где name - 'John' или 'Mary'
+const res = await rep.find({
+  where: {
+    name: {nin: ['John', 'Mary']},
+  },
+});
+```
+
+#### `between` (диапазон)
+
+Находит документы, у которых значение свойства находится в указанном диапазоне
+(включая границы).
+
+```js
+// найдет документы, где age находится в диапазоне от 20 до 30 включительно
+const res = await rep.find({
+  where: {
+    age: {between: [20, 30]},
+  },
+});
+```
+
+#### `exists` (наличие свойства)
+
+Проверяет наличие или отсутствие свойства в документе. Не проверяет значение
+свойства.
+
+- `true` свойство должно существовать (даже если его значение `null`);
+- `false` свойство должно отсутствовать;
+
+```js
+// найдет документы, у которых есть свойство 'nickname'
+const res1 = await rep.find({
+  where: {
+    nickname: {exists: true},
+  },
+});
+
+// найдет документы, у которых нет свойства 'nickname'
+const res2 = await rep.find({
+  where: {
+    nickname: {exists: false},
+  },
+});
+```
+
+#### `like` (шаблон)
+
+Выполняет сопоставление с шаблоном, с учетом регистра (см. [подробнее](#операторы-сопоставления-с-шаблоном)).
+
+```js
+// найдет {name: 'John Doe'}, но не {name: 'john doe'}
+const res = await rep.find({
+  where: {
+    name: {like: 'John%'},
+  },
+});
+```
+
+#### `nlike` (исключающий шаблон)
+
+Находит документы, которые не соответствуют шаблону, с учетом регистра (см. [подробнее](#операторы-сопоставления-с-шаблоном)).
+
+```js
+// найдет все, кроме тех, что начинаются на 'John'
+const res = await rep.find({
+  where: {
+    name: {nlike: 'John%'},
+  },
+});
+```
+
+#### `ilike` (регистронезависимый шаблон)
+
+Выполняет сопоставление с шаблоном без учета регистра (см. [подробнее](#операторы-сопоставления-с-шаблоном)).
+
+```js
+// найдет {name: 'John Doe'} и {name: 'john doe'}
+const res = await rep.find({
+  where: {
+    name: {ilike: 'john%'},
+  },
+});
+```
+
+#### `nilike` (регистронезависимый шаблон исключения)
+
+Находит строки, которые не соответствуют шаблону, без учета регистра (см. [подробнее](#операторы-сопоставления-с-шаблоном)).
+
+```js
+// найдет все, кроме тех, что начинаются на 'John' или 'john'
+const res = await rep.find({
+  where: {
+    name: {nilike: 'john%'},
+  },
+});
+```
+
+#### `regexp` (регулярное выражение)
+
+Находит документы, у которых значение строкового свойства соответствует
+указанному регулярному выражению. Может быть передано в виде строки или
+объекта `RegExp`.
+
+```js
+// найдет документы, где name начинается с 'J'
+const res1 = await rep.find({
+  where: {
+    name: {regexp: '^J'},
+  },
+});
+
+// найдет документы, где name начинается с 'J' или 'j' (регистронезависимо)
+const res2 = await rep.find({
+  where: {
+    name: {regexp: '^j', flags: 'i'},
+  },
+});
+```
+
+#### `and` (логическое И)
+
+Объединяет несколько условий в массив, требуя, чтобы каждое условие было
+выполнено.
+
+```javascript
+// найдет документы, где surname равен 'Smith' И age равен 21
+const res = await rep.find({
+  where: {
+    and: [
+      {surname: 'Smith'},
+      {age: 21}
+    ],
+  },
+});
+```
+
+#### `or` (логическое ИЛИ)
+
+Объединяет несколько условий в массив, требуя, чтобы хотя бы одно из них было
+выполнено.
+
+```javascript
+// найдет документы, где name равен 'James' ИЛИ age больше 30
+const res = await rep.find({
+  where: {
+    or: [
+      {name: 'James'},
+      {age: {gt: 30}}
+    ],
+  },
+});
+```
+
+#### Операторы сопоставления с шаблоном
+
+Операторы `like`, `nlike`, `ilike`, `nilike` предназначены для фильтрации
+строковых свойств на основе сопоставления с шаблоном, подобно оператору
+`LIKE` в SQL. Они позволяют находить значения, которые соответствуют
+определённой структуре, используя специальные символы.
+
+**`%`** соответствует любой последовательности из нуля или более символов:
+
+- `'А%'` найдет все строки, начинающиеся на "А";  
+- `'%а'` найдет все строки, заканчивающиеся на "а";  
+- `'%слово%'` найдет все строки, содержащие "слово" в любом месте;
+
+**`_`** соответствует ровно одному любому символу:
+
+- `'к_т'` найдет "кот", "кит", но не "крот" или "кт";
+- `'кот_'` найдет "коты", "коту" и "кота", но не "кот" или "котов";
+
+Если нужно найти сами символы `%` или `_` как часть строки, их необходимо
+экранировать с помощью обратного слэша `\`:
+
+- `'100\%'` найдет строку "100%";
+- `'file\_name'` найдет строку "file_name";
+- `'path\\to'` найдет строку "path\to";
+
 ### order
 
 Параметр упорядочивает выборку по указанным свойствам модели. Обратное