@e22m4u/js-repository 0.5.0 → 0.5.1

package/README.md

@@ -33,7 +33,7 @@
 npm install @e22m4u/js-repository
 ```
 
-Опционально устанавливаем адаптер.
+Опционально устанавливается нужный адаптер.
 
 |           | описание                                                                                                                       |
 |-----------|--------------------------------------------------------------------------------------------------------------------------------|
@@ -651,7 +651,8 @@ dbs.defineModel({
 
 Трансформеры используются для модификации значения свойства перед проверкой
 типа и передачей данных в базу. Трансформеры позволяют автоматически очищать
-или приводить данные к нужному формату.
+или приводить данные к нужному формату. [Пустые значения](#Пустые-значения)
+не передаются в трансформеры, так как не имеют полезной нагрузки.
 
 ### Глобальные трансформеры
 
@@ -1136,31 +1137,101 @@ const res = await rep.find({
 
 ## Связи
 
-Параметр `relations` находится в определении модели и принимает
-объект, ключ которого является названием связи, а значением объект
-с параметрами.
+Связи позволяют описывать отношения между моделями, что дает возможность
+автоматически встраивать связанные данные с помощью опции `include`
+в методах репозитория. Ниже приводится пример автоматического разрешения
+связи при использовании метода `findById`.
 
-**Параметры**
+```js
+// запрос документа коллекции "users",
+// включая связанные данные (role и city)
+const user = await userRep.findById(1, {
+  include: ['role', 'city'],
+});
+
+console.log(user);
+// {
+//   id: 1,
+//   name: 'John Doe',
+//   roleId: 3,
+//   role: {
+//     id: 3,
+//     name: 'Manager'
+//   },
+//   cityId: 24,
+//   city: {
+//     id: 24,
+//     name: 'Moscow'
+//   }
+// }
+```
+
+### Определение связи
+
+Свойство `relations` в определении модели принимает объект, ключи которого
+являются названиями связей, а значения их параметрами. В дальнейшем название
+связи можно будет использовать в опции `include` методах репозитория.
+
+```js
+import {DataType} from '@e22m4u/js-repository';
+import {RelationType} from '@e22m4u/js-repository';
+
+dbs.defineModel({
+  name: 'user',
+  datasource: 'memory',
+  properties: {
+    name: DataType.STRING,
+  },
+  relations: {
+    // связь role -> параметры
+    role: {
+      type: RelationType.BELONGS_TO,
+      model: 'role',
+    },
+    // связь city -> параметры
+    city: {
+      type: RelationType.BELONGS_TO,
+      model: 'city',
+    },
+  },
+});
+```
+
+**Основные параметры**
+
+- `type: string` тип связи (обязательно);
+- `model: string` название целевой модели (обязательно для некоторых типов);
+- `foreignKey: string` свойство текущей модели для идентификатора цели;
 
-- `type: string` тип связи
-- `model: string` название целевой модели
-- `foreignKey: string` свойство текущей модели для идентификатора цели
-- `polymorphic: boolean|string` объявить связь полиморфной*
-- `discriminator: string` свойство текущей модели для названия целевой*
+*i. Для типов Belongs To и References Many значение параметра `foreignKey`
+можно опустить, так как генерируется автоматически по названию связи.*
+
+**Полиморфный режим**
+
+- `polymorphic: boolean|string` объявление полиморфной связи;
+- `discriminator: string` свойство текущей модели для названия цели;
 
 *i. Полиморфный режим позволяет динамически определять целевую модель
 по ее названию, которое хранит документ в свойстве-дискриминаторе.*
 
-**Тип связи**
+**Типы связи**
+
+- `belongsTo` - текущая модель ссылается на целевую по идентификатору;
+- `hasOne` - обратная сторона `belongsTo` по принципу "один к одному";
+- `hasMany` - обратная сторона `belongsTo` по принципу "один ко многим";
+- `referencesMany` - модель ссылается через массив идентификаторов;
+
+Параметр `type` в определении связи принимает строку с названием типа. Чтобы исключить опечатку, рекомендуется использовать константы объекта `RelationType`
+указанные ниже.
 
-- `belongsTo` - текущая модель содержит свойство для идентификатора цели
-- `hasOne` - обратная сторона `belongsTo` по принципу "один к одному"
-- `hasMany` - обратная сторона `belongsTo` по принципу "один ко многим"
-- `referencesMany` - документ содержит массив с идентификаторами целевой модели
+- `RelationType.BELONGS_TO`
+- `RelationType.HAS_ONE`
+- `RelationType.HAS_MANY`
+- `RelationType.REFERENCES_MANY`
 
 **Примеры**
 
-Объявление связи `belongsTo`
+Объявление связи `belongsTo`.
 
 ```js
 dbs.defineModel({
@@ -1178,7 +1249,7 @@ dbs.defineModel({
 });
 ```
 
-Объявление связи `hasMany`
+Объявление связи `hasMany`.
 
 ```js
 dbs.defineModel({
@@ -1193,7 +1264,7 @@ dbs.defineModel({
 });
 ```
 
-Объявление связи `referencesMany`
+Объявление связи `referencesMany`.
 
 ```js
 dbs.defineModel({
@@ -1211,7 +1282,7 @@ dbs.defineModel({
 });
 ```
 
-Полиморфная версия `belongsTo`
+Полиморфная версия `belongsTo`.
 
 ```js
 dbs.defineModel({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-repository",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Реализация репозитория для работы с базами данных в Node.js",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",

package/src/definition/model/properties/property-definition.d.ts

@@ -7,8 +7,8 @@ import {PropertyTransformOptions} from './property-transformer/index.js';
  * Full property definition.
  */
 export declare type FullPropertyDefinition = {
-  type: DataType;
-  itemType?: DataType;
+  type: `${DataType}`;
+  itemType?: `${DataType}`;
   itemModel?: string;
   model?: string;
   primaryKey?: boolean;
@@ -18,7 +18,7 @@ export declare type FullPropertyDefinition = {
   default?: unknown;
   validate?: PropertyValidateOptions;
   transform?: PropertyTransformOptions;
-  unique?: boolean | PropertyUniqueness;
+  unique?: boolean | `${PropertyUniqueness}`;
 };
 
 /**

package/src/definition/model/relations/relation-definition.d.ts

@@ -35,7 +35,7 @@ export declare type RelationDefinition =
  * @example Required options only.
  * ```
  * {
- *   type: RelationType.BELONGS_TO,
+ *   type: 'belongsTo',
  *   model: 'model',
  * }
  * ```
@@ -43,14 +43,14 @@ export declare type RelationDefinition =
  * @example Verbose definition.
  * ```
  * {
- *   type: RelationType.BELONGS_TO,
+ *   type: 'belongsTo',
  *   model: 'model',
  *   foreignKey: 'modelId',
  * }
  * ```
  */
 export declare type BelongsToDefinition = {
-  type: RelationType.BELONGS_TO;
+  type: `${RelationType.BELONGS_TO}`;
   polymorphic?: false;
   model: string;
   foreignKey?: string;
@@ -62,7 +62,7 @@ export declare type BelongsToDefinition = {
  * @example Required fields only.
  * ```
  * {
- *   type: RelationType.BELONGS_TO,
+ *   type: 'belongsTo',
  *   polymorphic: true,
  * }
  * ```
@@ -70,7 +70,7 @@ export declare type BelongsToDefinition = {
  * @example Verbose definition.
  * ```
  * {
- *   type: RelationType.BELONGS_TO,
+ *   type: 'belongsTo',
  *   polymorphic: true,
  *   foreignKey: 'referenceId',
  *   discriminator: 'referenceType',
@@ -78,7 +78,7 @@ export declare type BelongsToDefinition = {
  * ```
  */
 export declare type PolyBelongsToDefinition = {
-  type: RelationType.BELONGS_TO;
+  type: `${RelationType.BELONGS_TO}`;
   polymorphic: true;
   foreignKey?: string;
   discriminator?: string;
@@ -90,14 +90,14 @@ export declare type PolyBelongsToDefinition = {
  * @example
  * ```ts
  * {
- *   type: RelationType.HAS_ONE,
+ *   type: 'hasOne',
  *   model: 'model',
  *   foreignKey: 'modelId',
  * }
  * ```
  */
 export declare type HasOneDefinition = {
-  type: RelationType.HAS_ONE;
+  type: `${RelationType.HAS_ONE}`;
   model: string;
   foreignKey: string;
   polymorphic?: false;
@@ -110,14 +110,14 @@ export declare type HasOneDefinition = {
  * @example
  * ```ts
  * {
- *   type: RelationType.HAS_ONE,
+ *   type: 'hasOne',
  *   model: 'model',
  *   polymorphic: 'reference',
  * }
  * ```
  */
 export declare type PolyHasOneDefinitionWithTargetRelationName = {
-  type: RelationType.HAS_ONE;
+  type: `${RelationType.HAS_ONE}`;
   model: string;
   polymorphic: string;
   foreignKey?: undefined;
@@ -130,7 +130,7 @@ export declare type PolyHasOneDefinitionWithTargetRelationName = {
  * @example
  * ```
  * {
- *   type: RelationType.HAS_ONE,
+ *   type: 'hasOne',
  *   model: 'model',
  *   polymorphic: true,
  *   foreignKey: 'referenceId',
@@ -139,7 +139,7 @@ export declare type PolyHasOneDefinitionWithTargetRelationName = {
  * ```
  */
 export declare type PolyHasOneDefinitionWithTargetKeys = {
-  type: RelationType.HAS_ONE;
+  type: `${RelationType.HAS_ONE}`;
   model: string;
   polymorphic: true;
   foreignKey: string;
@@ -152,14 +152,14 @@ export declare type PolyHasOneDefinitionWithTargetKeys = {
  * @example
  * ```ts
  * {
- *   type: RelationType.HAS_MANY,
+ *   type: 'hasMany',
  *   model: 'model',
  *   foreignKey: 'modelId',
  * }
  * ```
  */
 export declare type HasManyDefinition = {
-  type: RelationType.HAS_MANY;
+  type: `${RelationType.HAS_MANY}`;
   model: string;
   foreignKey: string;
   polymorphic?: false;
@@ -172,14 +172,14 @@ export declare type HasManyDefinition = {
  * @example
  * ```ts
  * {
- *   type: RelationType.HAS_MANY,
+ *   type: 'hasMany',
  *   model: 'model',
  *   polymorphic: 'reference',
  * }
  * ```
  */
 export declare type PolyHasManyDefinitionWithTargetRelationName = {
-  type: RelationType.HAS_MANY;
+  type: `${RelationType.HAS_MANY}`;
   model: string;
   polymorphic: string;
   foreignKey?: undefined;
@@ -192,7 +192,7 @@ export declare type PolyHasManyDefinitionWithTargetRelationName = {
  * @example
  * ```
  * {
- *   type: RelationType.HAS_MANY,
+ *   type: 'hasMany',
  *   model: 'model',
  *   polymorphic: true,
  *   foreignKey: 'referenceId',
@@ -201,7 +201,7 @@ export declare type PolyHasManyDefinitionWithTargetRelationName = {
  * ```
  */
 export declare type PolyHasManyDefinitionWithTargetKeys = {
-  type: RelationType.HAS_MANY;
+  type: `${RelationType.HAS_MANY}`;
   model: string;
   polymorphic: true;
   foreignKey: string;
@@ -214,7 +214,7 @@ export declare type PolyHasManyDefinitionWithTargetKeys = {
  * @example Required options only.
  * ```
  * {
- *   type: RelationType.REFERENCES_MANY,
+ *   type: 'referencesMany',
  *   model: 'model',
  * }
  * ```
@@ -222,14 +222,14 @@ export declare type PolyHasManyDefinitionWithTargetKeys = {
  * @example Verbose definition.
  * ```
  * {
- *   type: RelationType.REFERENCES_MANY,
+ *   type: 'referencesMany',
  *   model: 'model',
  *   foreignKey: 'modelIds',
  * }
  * ```
  */
 export declare type ReferencesManyDefinition = {
-  type: RelationType.REFERENCES_MANY;
+  type: `${RelationType.REFERENCES_MANY}`;
   model: string;
   foreignKey?: string;
   discriminator?: undefined;