feat(filters): add OperatorType.custom for custom backend service (#…

…1526)

* feat(filters): add `OperatorType.custom` for backend service custom
- adding a `OperatorType.custom` so that the users can use BUT the developers will have to implement their own code to go with it. This operator does nothing by itself unless the developers implement some code to go with it. It was only added to provide an easy way for the users to choose a valid operator.
- typically the developers will have to provide his own code implementation, typically a backend service (it could be by extending and overriding the OData/GraphQL service with their own usage).
- it was added because of this Satck Overflow [question](https://stackoverflow.com/questions/78471412/angular-slickgrid-filter)

packages/common/src/enums/operatorString.type.ts

@@ -1 +1 @@
-export type OperatorString = '' | '<>' | '!=' | '=' | '==' | '>' | '>=' | '<' | '<=' | '*' | 'a*' | '*z' | 'EQ' | 'GE' | 'GT' | 'NE' | 'LE' | 'LT' | 'IN' | 'NIN' | 'NOT_IN' | 'IN_CONTAINS' | 'NIN_CONTAINS' | 'NOT_IN_CONTAINS' | 'NOT_CONTAINS' | 'Not_Contains' | 'CONTAINS' | 'Contains' | 'EndsWith' | 'StartsWith' | 'RangeInclusive' | 'RangeExclusive' | 'IN_COLLECTION' | 'NOT_IN_COLLECTION';
+export type OperatorString = '' | '<>' | '!=' | '=' | '==' | '>' | '>=' | '<' | '<=' | '*' | 'Custom' | 'a*' | '*z' | 'EQ' | 'GE' | 'GT' | 'NE' | 'LE' | 'LT' | 'IN' | 'NIN' | 'NOT_IN' | 'IN_CONTAINS' | 'NIN_CONTAINS' | 'NOT_IN_CONTAINS' | 'NOT_CONTAINS' | 'Not_Contains' | 'CONTAINS' | 'Contains' | 'EndsWith' | 'StartsWith' | 'RangeInclusive' | 'RangeExclusive' | 'IN_COLLECTION' | 'NOT_IN_COLLECTION';

packages/common/src/enums/operatorType.enum.ts

@@ -2,42 +2,48 @@ export enum OperatorType {
   /** value is empty */
   empty = '',
 
-  /** value contains in x (search for substring in the string) */
+  /**
+   * Custom filter operator, this operator will not do anything unless the developer (you) has an implementation associated with the usage of this custom operator.
+   * In other words, without any implementation (typically a backend service) this operator does nothing by itself and only exists to provide a way for developers to customize their backend service filtering.
+   */
+  custom = 'Custom',
+
+  /** value contains in X (search for substring in the string) */
   contains = 'Contains',
 
-  /** value not contains x (inversed of contains) */
+  /** value is NOT contained in X (inversed of "Contains") */
   notContains = 'Not_Contains',
 
-  /** value less than x */
+  /** value less than X */
   lessThan = 'LT',
 
-  /** value less than or equal to x */
+  /** value less than or equal to X */
   lessThanOrEqual = 'LE',
 
-  /** value greater than x */
+  /** value greater than X */
   greaterThan = 'GT',
 
-  /** value great than or equal to x */
+  /** value great than or equal to X */
   greaterThanOrEqual = 'GE',
 
-  /** value not equal to x */
+  /** value is NOT equal to X */
   notEqual = 'NE',
 
-  /** value equal to x */
+  /** value equal to X */
   equal = 'EQ',
 
   /** String ends with value */
   endsWith = 'EndsWith',
 
   /**
-   * Search in an inclusive range of values that is greater or equal to search value 1 and is smaller or equal to value 2
-   * For example the search term of "5..10" will return any values that are greater or equal to 5 and smaller or equal to 10
+   * Search in an inclusive range of values that is greater or equal to search value X and is smaller or equal to value Y
+   * For example the search term of "5..10" will return any values that are greater or equal to 5 and smaller or equal to 10 (the values 5 and 10 are included)
    */
   rangeInclusive = 'RangeInclusive',
 
   /**
-   * Search in an inclusive range of values that is greater then search value 1 and is smaller then value 2
-   * For example the search term of "5..10" will return any values that is greater then 5 and smaller then 10
+   * Search in an exclusive range of values that is greater then search value X and is smaller then value Y
+   * For example the search term of "5..10" will return any values that is greater then 5 and smaller then 10 (the values 5 and 10 are NOT to be included)
    */
   rangeExclusive = 'RangeExclusive',
 
@@ -47,22 +53,22 @@ export enum OperatorType {
   /** Find an equal match inside a collection */
   in = 'IN',
 
-  /** Inverse (Not In) of an equal match inside a collection */
+  /** Find a value that is NOT an equal match inside a collection (inversed operator of "IN") */
   notIn = 'NOT_IN',
 
   /**
-   * Find a substring contained inside a collection, note that it has to be a CSV string.
-   * For example, this condition would return True with "IN_CONTAINS":: value='Task2,Task3', collection=['Task2','Task3']
-   * This would have returned False with "IN" because 'Task2' does not equal 'Task2,Task3'. However 'Task2' is contained in 'Task2,Task3'
+   * Find a substring contained inside a collection, note that the input must be a formatted CSV string input.
+   * For example, this condition would return `true` with `"IN_CONTAINS"`:: value='Task2' (or 'Task2,Task3'), collection=['Task2','Task3','Task4]
+   * However, this would have returned `false` with "IN" because 'Task2' does not equal to the entire collection 'Task2,Task3,Task4'.
    */
   inContains = 'IN_CONTAINS',
 
-  /** Inversed (Not In) of substring contained inside a collection */
+  /** Find a substring that is NOT contained inside a collection (inversed operator of "IN_CONTAINS") */
   notInContains = 'NOT_IN_CONTAINS',
 
   /** Find a value from within a collection inside another collection */
   inCollection = 'IN_COLLECTION',
 
-  /** Inversed (Not In) of looking for a value from a collection inside another collection */
+  /** Find a value that is NOT within a collection inside another collection (inversed operator of "IN_COLLECTION") */
   notInCollection = 'NOT_IN_COLLECTION'
 }