@e22m4u/js-repository 0.5.7 → 0.6.0

package/README.md

@@ -19,6 +19,7 @@
   - [Регистрация глобальных трансформеров](#регистрация-глобальных-трансформеров)
   - [Локальные трансформеры](#локальные-трансформеры)
 - [Пустые значения](#пустые-значения)
+  - [Переопределение пустых значений](#переопределение-пустых-значений)
 - [Репозиторий](#репозиторий)
 - [Фильтрация](#фильтрация)
 - [Связи](#связи)
@@ -35,9 +36,9 @@ npm install @e22m4u/js-repository
 
 Опционально устанавливается нужный адаптер.
 
-|           | описание                                                                                                                       |
+| адаптер   | описание                                                                                                                       |
 |-----------|--------------------------------------------------------------------------------------------------------------------------------|
-| `memory`  | виртуальная база в памяти процесса (не требует установки)                                                                      |
+| `memory`  | Виртуальная база в памяти процесса (не требует установки)                                                                      |
 | `mongodb` | MongoDB - система управления NoSQL базами (*[установка](https://www.npmjs.com/package/@e22m4u/js-repository-mongodb-adapter))* |
 
 ## Импорт
@@ -907,6 +908,62 @@ dbs.defineModel({
 | `'array'`   | `undefined`, `null`, `[]` |
 | `'object'`  | `undefined`, `null`, `{}` |
 
+### Переопределение пустых значений
+
+Набор пустых значений для любого типа данных можно переопределить. Управление
+этими наборами осуществляется через специальный сервис, который предоставляет
+модуль
+[@e22m4u/js-empty-values](https://www.npmjs.com/package/@e22m4u/js-empty-values)
+(не требует установки).
+
+**EmptyValuesService**
+
+Для переопределения пустых значений необходимо получить экземпляр класса
+`EmptyValuesService` из контейнера схемы и вызвать метод, который принимает
+тип данных и массив новых значений.
+
+Интерфейс:
+
+```ts
+class EmptyValuesService {
+  /**
+   * Установить пустые значения
+   * для определенного типа данных.
+   * 
+   * @param dataType    Тип данных.
+   * @param emptyValues Массив новых пустых значений.
+   */
+  setEmptyValuesOf(
+    dataType: DataType,
+    emptyValues: unknown[],
+  ): this;
+}
+```
+
+**Пример**
+
+По умолчанию, для числовых свойств значение `0` считается пустым. Следующий
+пример демонстрирует, как изменить это поведение, оставив в качестве пустых
+значений только `undefined` и `null`.
+
+```js
+import {DataType} from '@e22m4u/js-repository';
+import {DatabaseSchema} from '@e22m4u/js-repository';
+import {EmptyValuesService} from '@e22m4u/js-empty-values';
+
+const dbs = new DatabaseSchema();
+
+// получение сервиса для работы с пустыми значениями
+const emptyValuesService = dbs.getService(EmptyValuesService);
+
+// переопределение пустых значений для типа DataType.NUMBER
+emptyValuesService.setEmptyValuesOf(DataType.NUMBER, [undefined, null]);
+```
+
+После этого, значение `0` для свойств типа `DataType.NUMBER` больше не будет
+считаться пустым и будет проходить проверки валидаторами, а также не будет
+заменяться значением по умолчанию.
+
 ## Репозиторий
 
 Выполняет операции чтения и записи документов определенной модели.
@@ -930,9 +987,9 @@ dbs.defineModel({
 **Аргументы**
 
 - `id: number|string` идентификатор (первичный ключ)
-- `data: object` объект отражающий состав документа
-- `where: object` параметры выборки (см. [Фильтрация](#Фильтрация))
-- `filter: object` параметры возвращаемого результата (см. [Фильтрация](#Фильтрация))
+- `data: object` данные документа (используется при записи)
+- `where: object` условия фильтрации (см. [Фильтрация](#Фильтрация))
+- `filter: object` параметры выборки (см. [Фильтрация](#Фильтрация))
 
 **Примеры**
 
@@ -986,12 +1043,72 @@ console.log(res); // true
 имеет первый параметр метода `find`, где ожидается объект содержащий
 набор опций указанных ниже.
 
-- `where: object` объект выборки
-- `order: string[]` указание порядка
-- `limit: number` ограничение количества документов
-- `skip: number` пропуск документов
-- `fields: string[]` выбор необходимых свойств модели
-- `include: object` включение связанных данных в результат
+- `where: object` условия фильтрации по свойствам документа;
+- `order: string|string[]` сортировка по указанным свойствам;
+- `limit: number` ограничение количества документов;
+- `skip: number` пропуск документов (пагинация);
+- `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'},
+    publishedAt: {gte: '2025-10-15T00:00:00.000Z'},
+    tags: {inq: ['world', 'politic']},
+    hidden: false,
+  },
+  order: 'publishedAt DESC',
+  limit: 12,
+  skip: 24,
+  fields: ['title', 'annotation', 'body'],
+  include: ['author', 'category'],
+})
+```
+
+Пример получения профиля пользователя со списком его последних постов.
+
+- Найти пользователя по уникальному имени в свойстве `username`.
+- Из данных пользователя вернуть только имя, URL аватара и биографию.
+- Включить в результат 5 *опубликованных* постов данного пользователя.
+- Для каждого поста вернуть только заголовок и дату создания.
+- К каждому посту также прикрепить данные о категории.
+
+```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',
+    },
+  },
+});
+```
 
 ### where
 
@@ -1013,8 +1130,8 @@ console.log(res); // true
 `{foo: {ilike: 'BaR'}}` регистронезависимая версия `ilike`  
 `{foo: {nlike: 'bar'}}` оператор исключения подстроки `nlike`  
 `{foo: {nilike: 'BaR'}}` регистронезависимая версия `nilike`  
-`{foo: {regexp: 'ba.+'}}` оператор регулярного выражения `regexp`  
-`{foo: {regexp: 'ba.+', flags: 'i'}}` флаги регулярного выражения
+`{foo: {regexp: '^ba.+'}}` оператор регулярного выражения `regexp`  
+`{foo: {regexp: '^ba.+', flags: 'i'}}` флаги регулярного выражения
 
 *i. Условия можно объединять операторами `and`, `or` и `nor`.*
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-repository",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "description": "Реализация репозитория для работы с базами данных в Node.js",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",
@@ -41,12 +41,12 @@
   "dependencies": {
     "@e22m4u/js-empty-values": "~0.1.2",
     "@e22m4u/js-format": "~0.2.0",
-    "@e22m4u/js-service": "~0.4.2"
+    "@e22m4u/js-service": "~0.4.3"
   },
   "devDependencies": {
     "@commitlint/cli": "~20.1.0",
     "@commitlint/config-conventional": "~20.0.0",
-    "@types/chai": "~5.2.2",
+    "@types/chai": "~5.2.3",
     "@types/chai-as-promised": "~8.0.2",
     "@types/chai-spies": "~1.0.6",
     "@types/mocha": "~10.0.10",
@@ -54,11 +54,11 @@
     "chai": "~6.2.0",
     "chai-as-promised": "~8.0.2",
     "chai-spies": "~1.1.0",
-    "esbuild": "~0.25.10",
-    "eslint": "~9.37.0",
+    "esbuild": "~0.25.11",
+    "eslint": "~9.38.0",
     "eslint-config-prettier": "~10.1.8",
     "eslint-plugin-chai-expect": "~3.1.0",
-    "eslint-plugin-jsdoc": "~61.0.0",
+    "eslint-plugin-jsdoc": "~61.1.5",
     "eslint-plugin-mocha": "~11.2.0",
     "husky": "~9.1.7",
     "mocha": "~11.7.4",
@@ -66,6 +66,6 @@
     "rimraf": "~6.0.1",
     "ts-node": "~10.9.2",
     "typescript": "~5.9.3",
-    "typescript-eslint": "~8.46.0"
+    "typescript-eslint": "~8.46.2"
   }
 }

package/src/filter/filter-clause.d.ts

@@ -1,19 +1,24 @@
+import {ModelData} from '../types.js';
+
 /**
  * Filter clause.
  */
-export declare type FilterClause = {
-  where?: WhereClause;
-  order?: OrderClause;
+export declare type FilterClause<M extends object = ModelData> = {
+  where?: WhereClause<M>;
+  order?: OrderClause<M>;
   limit?: number;
   skip?: number;
-  fields?: FieldsClause;
-  include?: IncludeClause;
+  fields?: FieldsClause<M>;
+  include?: IncludeClause<M>;
 };
 
 /**
  * Item filter clause.
  */
-export declare type ItemFilterClause = Pick<FilterClause, 'fields' | 'include'>;
+export declare type ItemFilterClause<M extends object = ModelData> = Pick<
+  FilterClause<M>,
+  'fields' | 'include'
+>;
 
 /**
  * Where clause.
@@ -42,10 +47,21 @@ export declare type ItemFilterClause = Pick<FilterClause, 'fields' | 'include'>;
  * {or: [...]}
  * ```
  */
-export declare type WhereClause =
-  & Partial<AndClause>
-  & Partial<OrClause>
-  & PropertiesClause;
+export declare type WhereClause<M extends object = ModelData> = Partial<
+  AndClause<M>
+> &
+  Partial<OrClause<M>> &
+  PropertiesClause<M>;
+
+/**
+ * Primitive values.
+ */
+export declare type PrimitiveValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined;
 
 /**
  * Properties clause.
@@ -59,16 +75,8 @@ export declare type WhereClause =
  * }
  * ```
  */
-export type PropertiesClause = {
-  [property: string]:
-    | OperatorClause
-    | string
-    | number
-    | boolean
-    | RegExp
-    | null
-    | undefined
-    | object;
+export declare type PropertiesClause<M extends object = ModelData> = {
+  [property in keyof M]?: OperatorClause | PrimitiveValue | RegExp;
 };
 
 /**
@@ -95,14 +103,14 @@ export type PropertiesClause = {
  * ```
  */
 export declare type OperatorClause = {
-  eq?: unknown;
-  neq?: unknown;
+  eq?: PrimitiveValue;
+  neq?: PrimitiveValue;
   gt?: string | number;
   gte?: string | number;
   lt?: string | number;
   lte?: string | number;
-  inq?: unknown[];
-  nin?: unknown[];
+  inq?: PrimitiveValue[];
+  nin?: PrimitiveValue[];
   between?: readonly [string | number, string | number];
   exists?: boolean;
   like?: string | RegExp;
@@ -123,8 +131,8 @@ export declare type OperatorClause = {
  * }
  * ```
  */
-export interface AndClause {
-  and: WhereClause[];
+export interface AndClause<M extends object = ModelData> {
+  and: WhereClause<M>[];
 }
 
 /**
@@ -137,10 +145,24 @@ export interface AndClause {
  * }
  * ```
  */
-export interface OrClause {
-  or: WhereClause[];
+export interface OrClause<M extends object = ModelData> {
+  or: WhereClause<M>[];
 }
 
+/**
+ * Order clause item.
+ *
+ * @example
+ * ```ts
+ * 'prop'
+ * 'prop ASC'
+ * 'prop DESC';
+ * ```
+ */
+export declare type OrderClauseItem<M extends object = ModelData> = {
+  [prop in keyof M]: prop | `${prop & string} ASC` | `${prop & string} DESC`;
+}[keyof M];
+
 /**
  * Order clause.
  *
@@ -153,7 +175,9 @@ export interface OrClause {
  * ['prop1 ASC', 'prop2 DESC'];
  * ```
  */
-export type OrderClause = string | string[];
+export declare type OrderClause<M extends object = ModelData> =
+  | OrderClauseItem<M>
+  | OrderClauseItem<M>[];
 
 /**
  * Fields.
@@ -164,7 +188,9 @@ export type OrderClause = string | string[];
  * ['prop1', 'prop2']
  * ```
  */
-export type FieldsClause = string | NormalizedFieldsClause;
+export declare type FieldsClause<M extends object = ModelData> =
+  | keyof M
+  | NormalizedFieldsClause<M>;
 
 /**
  * Normalized fields clause.
@@ -177,7 +203,8 @@ export type FieldsClause = string | NormalizedFieldsClause;
  * ]
  * ```
  */
-export type NormalizedFieldsClause = string[];
+export declare type NormalizedFieldsClause<M extends object = ModelData> =
+  (keyof M)[];
 
 /**
  * Include clause.
@@ -236,10 +263,11 @@ export type NormalizedFieldsClause = string[];
  * }
  * ```
  */
-export declare type IncludeClause =
-  | string
-  | NestedIncludeClause
-  | NormalizedIncludeClause
+export declare type IncludeClause<M extends object = ModelData> =
+  | keyof M
+  | (keyof M)[]
+  | NestedIncludeClause<M>
+  | NormalizedIncludeClause<M>
   | IncludeClause[];
 
 /**
@@ -286,8 +314,8 @@ export declare type IncludeClause =
  * }
  * ```
  */
-export declare type NestedIncludeClause = {
-  [property: string]: IncludeClause;
+export declare type NestedIncludeClause<M extends object = ModelData> = {
+  [property in keyof M]?: IncludeClause;
 };
 
 /**
@@ -315,7 +343,7 @@ export declare type NestedIncludeClause = {
  * }
  * ```
  */
-export declare type NormalizedIncludeClause = {
-  relation: string;
+export declare interface NormalizedIncludeClause<M extends object = ModelData> {
+  relation: keyof M;
   scope?: FilterClause;
-};
+}

package/src/repository/repository.d.ts

@@ -17,7 +17,7 @@ export declare class Repository<
   Data extends object = ModelData,
   IdType extends ModelId = ModelId,
   IdName extends string = typeof DEFAULT_PRIMARY_KEY_PROPERTY_NAME,
-  FlatData extends ModelData = Flatten<Data>,
+  FlatData extends object = Flatten<Data>,
 > extends Service {
   // it fixes unused generic bug
   private _Data?: Data;
@@ -56,7 +56,7 @@ export declare class Repository<
    */
   create(
     data: OptionalUnlessRequiredId<IdName, FlatData>,
-    filter?: ItemFilterClause,
+    filter?: ItemFilterClause<FlatData>,
   ): Promise<FlatData>;
 
   /**
@@ -68,8 +68,8 @@ export declare class Repository<
    */
   replaceById(
     id: IdType,
-    data: WithoutId<IdName, FlatData>,
-    filter?: ItemFilterClause,
+    data: WithoutId<FlatData, IdName>,
+    filter?: ItemFilterClause<FlatData>,
   ): Promise<FlatData>;
 
   /**
@@ -79,8 +79,8 @@ export declare class Repository<
    * @param filter
    */
   replaceOrCreate(
-    data: OptionalUnlessRequiredId<IdName, Data>,
-    filter?: ItemFilterClause,
+    data: OptionalUnlessRequiredId<IdName, FlatData>,
+    filter?: ItemFilterClause<FlatData>,
   ): Promise<FlatData>;
 
   /**
@@ -90,8 +90,8 @@ export declare class Repository<
    * @param where
    */
   patch(
-    data: PartialWithoutId<IdName, Data>,
-    where?: WhereClause,
+    data: PartialWithoutId<FlatData, IdName>,
+    where?: WhereClause<FlatData>,
   ): Promise<number>;
 
   /**
@@ -103,8 +103,8 @@ export declare class Repository<
    */
   patchById(
     id: IdType,
-    data: PartialWithoutId<IdName, Data>,
-    filter?: ItemFilterClause,
+    data: PartialWithoutId<FlatData, IdName>,
+    filter?: ItemFilterClause<FlatData>,
   ): Promise<FlatData>;
 
   /**
@@ -112,14 +112,14 @@ export declare class Repository<
    *
    * @param filter
    */
-  find(filter?: FilterClause): Promise<FlatData[]>;
+  find(filter?: FilterClause<FlatData>): Promise<FlatData[]>;
 
   /**
    * Find one.
    *
    * @param filter
    */
-  findOne(filter?: FilterClause): Promise<FlatData | undefined>;
+  findOne(filter?: FilterClause<FlatData>): Promise<FlatData | undefined>;
 
   /**
    * Find by id.
@@ -127,14 +127,14 @@ export declare class Repository<
    * @param id
    * @param filter
    */
-  findById(id: IdType, filter?: ItemFilterClause): Promise<FlatData>;
+  findById(id: IdType, filter?: ItemFilterClause<FlatData>): Promise<FlatData>;
 
   /**
    * Delete.
    *
    * @param where
    */
-  delete(where?: WhereClause): Promise<number>;
+  delete(where?: WhereClause<FlatData>): Promise<number>;
 
   /**
    * Delete by id.
@@ -155,27 +155,29 @@ export declare class Repository<
    *
    * @param where
    */
-  count(where?: WhereClause): Promise<number>;
+  count(where?: WhereClause<FlatData>): Promise<number>;
 }
 
 /**
  * Removes id field.
  */
-type WithoutId<IdName extends string, Data extends object> = Flatten<
-  Omit<Data, IdName>
->;
+export declare type WithoutId<
+  Data extends object,
+  IdName extends string = 'id',
+> = Flatten<Omit<Data, IdName>>;
 
 /**
  * Makes fields as optional and remove id field.
  */
-type PartialWithoutId<IdName extends string, Data extends object> = Flatten<
-  Partial<Omit<Data, IdName>>
->;
+export declare type PartialWithoutId<
+  Data extends object,
+  IdName extends string = 'id',
+> = Flatten<Partial<Omit<Data, IdName>>>;
 
 /**
  * Makes the required id field as optional.
  */
-type OptionalUnlessRequiredId<
+export declare type OptionalUnlessRequiredId<
   IdName extends string,
   Data extends object,
 > = Flatten<Data extends {[K in IdName]: any} ? PartialBy<Data, IdName> : Data>;

package/src/types.d.ts

@@ -14,9 +14,7 @@ export declare type PartialBy<T, K extends keyof T> = Omit<T, K> &
 /**
  * Model data.
  */
-export declare type ModelData = {
-  [property: string]: unknown;
-};
+export declare type ModelData = Record<string, unknown>;
 
 /**
  * Model id.