@futdevpro/nts-dynamo 1.5.81 → 1.5.84

package/src/_services/dynamo-nts-db.service.ts

@@ -6,10 +6,194 @@ import {
   Dynamo_Metadata, Dynamo_DataParams, Dynamo_DataPropertyParams, Dynamo_Error 
 } from '@futdevpro/fsm-dynamo';
 
+/**
+ * @example 
+ * // by email: 
+ * { email: email }
+ * //
+ * @example 
+ * // or by id that is in list:
+ * { userIds: { $in: this.userId } }
+ * //
+ * @example 
+ * // or by number or Date that is Greater Than AND Less Than:
+ * { points: { $gt: 2, $lt: 14 } }
+ * // further tools (syntax matches with $gt):
+ * $eq:  // Matches values that are EQual to a specified value.
+ * $gte: // Matches values that are Greater Than OR Equal to a specified value.
+ * $lte: // Matches values that are Less Than or Equal to a specified value.
+ * $ne:  // Matches all values that are Not Equal to a specified value.
+ * $nin: // Matches None of the values specified IN an array.
+ * //
+ * @returns {T} data: T
+ */
+export type DynamoNTS_DBFilter<T> = DynamoNTS_DBFilterSimple<T> | DynamoNTS_DBFilterOR<T> |DynamoNTS_DBFilterNOR<T>;
+
+type DynamoNTS_DBFilterSimple<T> = {
+  [K in keyof T]?: T[K] | { 
+    /**
+     * Matches values that are includes the value; This works only when T[K] is an array!
+     */
+    $in?: any,
+    /**
+     * Matches values that are EQual to a specified value.
+     */
+    $eq?: T[K],
+    /**
+     * Matches values that are Greater Than a specified value.
+     */
+    $gt?: number | Date,
+    /**
+     * Matches values that are Greater Than OR Equal to a specified value.
+     */
+    $gte?: number | Date,
+    /**
+     * Matches values that are Less Than a specified value.
+     */
+    $lt?: number | Date,
+    /**
+     * Matches values that are Less Than or Equal to a specified value.
+     */
+    $lte?: number | Date,
+    /**
+     * Matches all values that are Not Equal to a specified value.
+     */
+    $ne?: T[K],
+    /**
+     * Matches None of the values specified IN an array.
+     */
+    $nin?: T[K],
+    /**
+     * Inverts the effect of a query expression and returns documents that do not match the query expression.
+     */
+    $not?: T[K] | {
+      $regex?: RegExp | string,
+    },
+    /**
+     * Performs a regular expression on the field's value, and selects documents that match the regular expression.
+     */
+    $exists?: boolean,
+    /**
+     * Selects documents if a field is of the specified type.
+     */
+    $type?: string,
+  };
+};
+
+type DynamoNTS_DBFilterOR<T> = {
+  /**
+   * Joins query clauses with a logical OR returns all documents that match the conditions of either clause.
+   */
+  $or: DynamoNTS_DBFilterSimple<T>[];
+}
+
+type DynamoNTS_DBFilterNOR<T> = {
+  /**
+   * Joins query clauses with a logical NOR returns all documents that fail to match both clauses.
+   */
+  $nor: DynamoNTS_DBFilterSimple<T>[];
+}
+
+/**
+ * @param update this uses the basic Mongoose updateOne
+ * @example
+ * // increase a specific value (here by 15): 
+ * { $inc: { popularity: 15 } }
+ * //
+ * @example 
+ * // or add element to a list:
+ * { $push: { reactions: this.newReaction }
+ * // or add multiple elements to a list
+ * { $push: { schedule: {$each: [ monday, tuesday, wednesday ] } } }
+ * //
+ * @example 
+ * // or all at once 
+ * {  
+ *   $inc: { popularity: this.newVote.amount }, 
+ *   emailVerified: true, 
+ *   $push: { reactions: this.newReaction } 
+ * }
+ * // further tools (syntax matches with $inc):
+ * $currentDate: // Sets the value of a field to current date, either as a Date or a Timestamp.
+ * $min:         // Only updates the field if the specified value is less than the existing field value.
+ * $max:         // Only updates the field if the specified value is greater than the existing field value.
+ * $mul:         // Multiplies the value of the field by the specified amount.
+ * $rename:      // Renames a field.
+ * $unset:       // Removes the specified field from a document. (set: "" to value)
+ * //
+ */
+export type DynamoNTS_DBUpdate<T> = {
+  /**
+   * Sets the value of a field to current date, either as a Date or a Timestamp.
+   */
+  $currentDate?: { [K in keyof T]?: boolean };
+  /**
+   * Increments the value of the field by the specified amount.
+   */
+  $inc?: { [K in keyof T]?: number };
+  /**
+   * Only updates the field if the specified value is less than the existing field value.
+   */
+  $min?: { [K in keyof T]?: number };
+  /**
+   * Only updates the field if the specified value is greater than the existing field value.
+   */
+  $max?: { [K in keyof T]?: number };
+  /**
+   * Multiplies the value of the field by the specified amount.
+   */
+  $mul?: { [K in keyof T]?: number };
+  /**
+   * Renames a field.
+   */
+  $rename?: { [K in keyof T]?: string };
+  /**
+   * Removes the specified field from a document. (set: "" to value)
+   */
+  $unset?: { [K in keyof T]?: string };
+  /**
+   * Sets the value of a field in a document.
+   */
+  $set?: { [K in keyof T]?: string };
+  /**
+   * Sets the value of a field if an update results in an insert of a document. Has no effect on update operations that modify existing documents.
+   */
+  $setOnInsert?: { [K in keyof T]?: T[K] };
+  /**
+   * Removes the first or last item of an array.
+   */
+
+  // array only operations
+  /**
+   * Removes the first or last item of an array.
+   */
+  $push?: { [K in keyof T]?: any | { $each?: T[K] } };
+  /**
+   * Removes the first or last item of an array.
+   */
+  $addToSet?: { [K in keyof T]?: any | { $each?: T[K] } };
+  /**
+   * Removes the first or last item of an array.
+   */
+  $pop?: { [K in keyof T]?: 1 | -1 };
+  /**
+   * Removes all array elements that match a specified query.
+   */
+  $pull?: { [K in keyof T]?: any | { $each?: T[K] } };
+  /**
+   * Removes all array elements that match a specified query.
+   */
+  $pullAll?: { [K in keyof T]?: any | { $each?: T[K] } };
+} extends DynamoNTS_DBSimpleUpdate<T> ? DynamoNTS_DBSimpleUpdate<T> : never;
+
+type DynamoNTS_DBSimpleUpdate<T> = {
+  [K in keyof T]?: T[K];
+};
+
 /**
  * 
  */
-export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U extends T = any> {
+export class DynamoNTS_DBService<T extends Dynamo_Metadata> {
   dataModel = mongoose.model(this.dataParams.dbName, this.getSchema());
 
   private depDataName: string;
@@ -269,15 +453,89 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
     return dataList;
   }
 
+  /**
+   * returns all data from database, 
+   * !!!: throws error if not found (errorCode on not found: NTS-DBS-GA1)
+   * 
+   * @returns dataList
+   */
+  async getAll(): Promise<T[]> {
+    let dataList: T[] = await this.dataModel.find({})
+    .then(res => {
+      return res as T[] ?? [];
+    }).catch(error => {
+      throw new Dynamo_Error({ 
+        status: 417, 
+        errorCode: 'NTS-DBS-GA0',
+        addECToUserMsg: true,
+        message: `get all ${this.dataParams.dbName} was unsuccessful (NTS DB)`, 
+        userMessage: this.defaultErrorUserMsg, 
+        error 
+      });
+    });
+
+    if (0 < dataList.length && typeof dataList[0]._id === 'object') {
+      dataList.forEach((data: T) => {
+        data._id = `˙${data._id}`;
+      });
+    }
+
+    return dataList as T[];
+  }
+
+  /**
+   * deleted data by id
+   * @param id id
+   */
+  async deleteDataById(id: string): Promise<void> {
+    await this.dataModel.findByIdAndDelete(id).catch(error => {
+      throw new Dynamo_Error({ 
+        status: 417, 
+        errorCode: 'NTS-DBS-DD0',
+        addECToUserMsg: true,
+        message: `delete ${this.dataParams.dbName} was unsuccessful (NTS DB)`,
+        userMessage: this.defaultErrorUserMsg,  
+        error 
+      });
+    });
+  }
+
+  /**
+   * deleted data by id
+   * @param dependencyId id
+   */
+  async deleteDataByDependencyId(dependencyId: string): Promise<void> {
+    if (!this.depDataName) {
+      throw new Dynamo_Error({ 
+        status: 501, 
+        errorCode: 'NTS-DBS-DDD0',
+        addECToUserMsg: true,
+        message: `dependencyDataIdKey not setted up for this db-service (${this.dataParams.dbName}) (NTS DB)`,
+        userMessage: this.defaultErrorUserMsg
+      });
+    }
+
+    await this.dataModel.deleteMany({ [this.depDataName]: dependencyId }).catch(error => {
+      throw new Dynamo_Error({ 
+        status: 417, 
+        errorCode: 'NTS-DBS-DDD1',
+        addECToUserMsg: true,
+        message: `delete ${this.dataParams.dbName} by ${this.depDataName} was unsuccessful (NTS DB)`, 
+        userMessage: this.defaultErrorUserMsg, 
+        error 
+      });
+    });
+  }
+
   /**
    * returns search result for searchBy object params
    * can use lists or xRange values for searchBy obj properties
    * 
-   * @param searchBy filter
+   * @param filterBy filter
    * @param narrowByDependencyIds id
    * @returns dataList
    */
-  async searchData(searchBy: F, narrowByDependencyIds?: string[]): Promise<T[]> {
+  async searchData(filterBy: DynamoNTS_DBFilter<T>, narrowByDependencyIds?: string[]): Promise<T[]> {
     const filter = {};
 
     if (0 < narrowByDependencyIds.length) {
@@ -296,45 +554,45 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
 
     await this.dataParams.modelParams.forEach((modelParam: Dynamo_DataPropertyParams) => {
       if (
-        (searchBy[modelParam.key] !== null && searchBy[modelParam.key] !== undefined) || 
-        searchBy[modelParam.key + 'Range']
+        (filterBy[modelParam.key] !== null && filterBy[modelParam.key] !== undefined) || 
+        filterBy[modelParam.key + 'Range']
       ) {
         if (modelParam.key.includes('Range') || modelParam.type.includes('[]')) {
           // inverz search filter (for Range and Array functions)
           if (modelParam.key.includes('Range')) {
             const searchParamKeyWithoutRange = modelParam.key.split('Range')[0];
             if (
-              searchBy[searchParamKeyWithoutRange] !== null && 
-              searchBy[searchParamKeyWithoutRange] !== undefined
+              filterBy[searchParamKeyWithoutRange] !== null && 
+              filterBy[searchParamKeyWithoutRange] !== undefined
             ) {
               filter[modelParam.key] = {
-                from: { $lte: searchBy[searchParamKeyWithoutRange] },
-                to: { $gte: searchBy[searchParamKeyWithoutRange] }
+                from: { $lte: filterBy[searchParamKeyWithoutRange] },
+                to: { $gte: filterBy[searchParamKeyWithoutRange] }
               };
             }
           } else {
             if (
-              searchBy[modelParam.key] !== null && 
-              searchBy[modelParam.key] !== undefined
+              filterBy[modelParam.key] !== null && 
+              filterBy[modelParam.key] !== undefined
             ) {
-              filter[modelParam.key] = { $in: searchBy[modelParam.key] };
+              filter[modelParam.key] = { $in: filterBy[modelParam.key] };
             }
           }
         } else {
           // basic search filter
-          if (searchBy[modelParam.key + 'Range']) {
-            if (searchBy[modelParam.key + 'Range'].from || searchBy[modelParam.key + 'Range'].to) {
+          if (filterBy[modelParam.key + 'Range']) {
+            if (filterBy[modelParam.key + 'Range'].from || filterBy[modelParam.key + 'Range'].to) {
               filter[modelParam.key] = {};
-              if (searchBy[modelParam.key + 'Range'].from) {
-                filter[modelParam.key].$gte = searchBy[modelParam.key + 'Range'].from;
+              if (filterBy[modelParam.key + 'Range'].from) {
+                filter[modelParam.key].$gte = filterBy[modelParam.key + 'Range'].from;
               }
-              if (searchBy[modelParam.key + 'Range'].to) {
-                filter[modelParam.key].$lte = searchBy[modelParam.key + 'Range'].to;
+              if (filterBy[modelParam.key + 'Range'].to) {
+                filter[modelParam.key].$lte = filterBy[modelParam.key + 'Range'].to;
               }
             }
-          } else if (searchBy[modelParam.key] !== null && searchBy[modelParam.key] !== undefined) {
-            if (searchBy[modelParam.key].lenght > 0) {
-              filter[modelParam.key] = { $in: searchBy[modelParam.key] };
+          } else if (filterBy[modelParam.key] !== null && filterBy[modelParam.key] !== undefined) {
+            if (filterBy[modelParam.key].lenght > 0) {
+              filter[modelParam.key] = { $in: filterBy[modelParam.key] };
             }
           }
         }
@@ -365,80 +623,6 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
     return dataList;
   }
 
-  /**
-   * returns all data from database, 
-   * !!!: throws error if not found (errorCode on not found: NTS-DBS-GA1)
-   * 
-   * @returns dataList
-   */
-  async getAll(): Promise<T[]> {
-    let dataList: T[] = await this.dataModel.find({})
-    .then(res => {
-      return res as T[] ?? [];
-    }).catch(error => {
-      throw new Dynamo_Error({ 
-        status: 417, 
-        errorCode: 'NTS-DBS-GA0',
-        addECToUserMsg: true,
-        message: `get all ${this.dataParams.dbName} was unsuccessful (NTS DB)`, 
-        userMessage: this.defaultErrorUserMsg, 
-        error 
-      });
-    });
-
-    if (0 < dataList.length && typeof dataList[0]._id === 'object') {
-      dataList.forEach((data: T) => {
-        data._id = `˙${data._id}`;
-      });
-    }
-
-    return dataList as T[];
-  }
-
-  /**
-   * deleted data by id
-   * @param id id
-   */
-  async deleteDataById(id: string): Promise<void> {
-    await this.dataModel.findByIdAndDelete(id).catch(error => {
-      throw new Dynamo_Error({ 
-        status: 417, 
-        errorCode: 'NTS-DBS-DD0',
-        addECToUserMsg: true,
-        message: `delete ${this.dataParams.dbName} was unsuccessful (NTS DB)`,
-        userMessage: this.defaultErrorUserMsg,  
-        error 
-      });
-    });
-  }
-
-  /**
-   * deleted data by id
-   * @param dependencyId id
-   */
-  async deleteDataByDependencyId(dependencyId: string): Promise<void> {
-    if (!this.depDataName) {
-      throw new Dynamo_Error({ 
-        status: 501, 
-        errorCode: 'NTS-DBS-DDD0',
-        addECToUserMsg: true,
-        message: `dependencyDataIdKey not setted up for this db-service (${this.dataParams.dbName}) (NTS DB)`,
-        userMessage: this.defaultErrorUserMsg
-      });
-    }
-
-    await this.dataModel.deleteMany({ [this.depDataName]: dependencyId }).catch(error => {
-      throw new Dynamo_Error({ 
-        status: 417, 
-        errorCode: 'NTS-DBS-DDD1',
-        addECToUserMsg: true,
-        message: `delete ${this.dataParams.dbName} by ${this.depDataName} was unsuccessful (NTS DB)`, 
-        userMessage: this.defaultErrorUserMsg, 
-        error 
-      });
-    });
-  }
-
   // ----------------------------------------------------------------------------------
   // ----------------------------------------------------------------------------------
   // ----------------------------------------------------------------------------------
@@ -448,7 +632,7 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
    * Find the data first by any of its parameters, 
    * !!!: throws error if not found (errorCode on not found: NTS-DBS-FO1)
    * 
-   * @param filter if you can, use unique parameters for find!
+   * @param filterBy if you can, use unique parameters for find!
    * 
    * @example 
    * // by email: 
@@ -470,15 +654,15 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
    * //
    * @returns {T} data: T
    */
-  async findOne(filter: F): Promise<T> {
-    let data: T = await this.dataModel.findOne(filter).then(res => {
+  async findOne(filterBy: DynamoNTS_DBFilter<T>): Promise<T> {
+    let data: T = await this.dataModel.findOne(filterBy).then(res => {
       return res as T ?? null;
     }).catch(error => {
       throw new Dynamo_Error({ 
         status: 417, 
         errorCode: 'NTS-DBS-FO0',
         addECToUserMsg: true,
-        message: `findOne ${this.dataParams.dbName} was unsuccessful (NTS DB) fliter: ${filter}`, 
+        message: `findOne ${this.dataParams.dbName} was unsuccessful (NTS DB) fliter: ${filterBy}`, 
         userMessage: this.defaultErrorUserMsg, 
         error 
       });
@@ -496,7 +680,7 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
    * Find the data first by any of its parameters, 
    * !!!: throws error if not found (errorCode on not found: NTS-DBS-F1)
    * 
-   * @param filter if you can, use unique parameters for find!
+   * @param filterBy if you can, use unique parameters for find!
    * 
    * @example 
    * // by email: 
@@ -518,8 +702,8 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
    * //
    * @returns {T[]} dataList: T[]
    */
-  async find(filter: F): Promise<T[]> {
-    let dataList: T[] = await this.dataModel.find(filter)
+  async find(filterBy: DynamoNTS_DBFilter<T>): Promise<T[]> {
+    let dataList: T[] = await this.dataModel.find(filterBy)
     .then(res => {
       return res as T[] ?? [];
     }).catch(error => {
@@ -548,7 +732,7 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
    * #MONGOOSE FUNCTION
    * Find the data first by any of its parameters
    * 
-   * @param filter if you can, use unique parameters for find!
+   * @param filterBy if you can, use unique parameters for find!
    * 
    * @example 
    * // by email: 
@@ -577,8 +761,8 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
    * //
    * @returns {T[]} dataList: T[]
    */
-  async findWithPaging(filter: F, page: number, pageSize: number, sort?: any): Promise<T[]> {
-    let dataList: T[] = await this.dataModel.find(filter)
+  async findWithPaging(filterBy: DynamoNTS_DBFilter<T>, page: number, pageSize: number, sort?: any): Promise<T[]> {
+    let dataList: T[] = await this.dataModel.find(filterBy)
                         .sort(sort)
                         .skip(page * pageSize)
                         .limit(pageSize)
@@ -614,7 +798,7 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
    * @param update update
    * @returns data
    */
-  async findByIdAndUpdate(id: string, update: U, modifier: string): Promise<T> {
+  async findByIdAndUpdate(id: string, update: DynamoNTS_DBUpdate<T>, modifier: string): Promise<T> {
     update.__lastModified = new Date();
     update.__lastModifiedBy = modifier;
 
@@ -690,11 +874,11 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
    * $unset:       // Removes the specified field from a document. (set: "" to value)
    * //
    */
-  async updateOne(updateBy: F, update: U, issuer: string): Promise<void> {
+  async updateOne(filterBy: DynamoNTS_DBFilter<T>, update: DynamoNTS_DBUpdate<T>, issuer: string): Promise<void> {
     update.__lastModified = new Date();
     update.__lastModifiedBy = issuer;
     
-    await this.dataModel.updateOne(updateBy, update).catch(error => {
+    await this.dataModel.updateOne(filterBy, update).catch(error => {
       throw new Dynamo_Error({
         status: 417, 
         errorCode: 'NTS-DBS-UO0',
@@ -757,11 +941,11 @@ export class DynamoNTS_DBService<T extends Dynamo_Metadata, F extends T = any, U
    * $unset:       // Removes the specified field from a document. (set: "" to value)
    * //
    */
-  async updateMany(updateBy: F, update: U, issuer: string): Promise<void> {
+  async updateMany(filterBy: DynamoNTS_DBFilter<T>, update: DynamoNTS_DBUpdate<T>, issuer: string): Promise<void> {
     update.__lastModified = new Date();
     update.__lastModifiedBy = issuer;
 
-    await this.dataModel.updateMany(updateBy, update).catch(error => {
+    await this.dataModel.updateMany(filterBy, update).catch(error => {
       throw new Dynamo_Error({ 
         status: 417, 
         errorCode: 'NTS-DBS-UM0',