@nulledexp/translatable-criteria 1.2.0 → 2.0.0

package/dist/criteria/types/operator.types.d.ts

@@ -18,104 +18,110 @@ export declare enum FilterOperator {
     LIKE = "LIKE",
     /** Checks if a string value does not match a pattern. */
     NOT_LIKE = "NOT LIKE",
-    /** Checks if a value is within a set of specified values. */
-    IN = "IN",
-    /** Checks if a value is not within a set of specified values. */
-    NOT_IN = "NOT IN",
-    /** Checks if a value is NULL. */
-    IS_NULL = "IS NULL",
-    /** Checks if a value is NOT NULL. */
-    IS_NOT_NULL = "IS NOT NULL",
+    /** Checks if a string value matches a pattern (case-insensitive). */
+    ILIKE = "ILIKE",
+    /** Checks if a string value does not match a pattern (case-insensitive). */
+    NOT_ILIKE = "NOT_ILIKE",
     /** Checks if a string value contains a specific substring (often case-insensitive, depends on DB). */
     CONTAINS = "CONTAINS",
+    /** Checks if a string value does not contain a specific substring. */
+    NOT_CONTAINS = "NOT_CONTAINS",
     /** Checks if a string value starts with a specific substring. */
     STARTS_WITH = "STARTS_WITH",
     /** Checks if a string value ends with a specific substring. */
     ENDS_WITH = "ENDS_WITH",
-    /** Checks if a string value does not contain a specific substring. */
-    NOT_CONTAINS = "NOT_CONTAINS",
-    /**
-     * Checks if a field, representing a collection of values (e.g., MySQL SET type
-     * or a text field with comma-delimited values), contains a specific value.
-     * Expects a single value.
-     */
-    SET_CONTAINS = "SET_CONTAINS",
-    /**
-     * Checks if a field, representing a collection of values (e.g., MySQL SET type
-     * or a text field with comma-delimited values), does NOT contain a specific value.
-     * Expects a single value.
-     */
-    SET_NOT_CONTAINS = "SET_NOT_CONTAINS",
-    /**
-     * Checks if a field, representing a collection of values (e.g., MySQL SET type
-     * or a text field with comma-delimited values), contains AT LEAST ONE of the specified values.
-     * Expects an array of values.
-     */
-    SET_CONTAINS_ANY = "SET_CONTAINS_ANY",
-    /**
-     * Checks if a field, representing a collection of values (e.g., MySQL SET type
-     * or a text field with comma-delimited values), contains ALL of the specified values.
-     * Expects an array of values.
-     */
-    SET_CONTAINS_ALL = "SET_CONTAINS_ALL",
-    /**
-     * Checks if a value is within a specified range (inclusive).
-     * Expects an array or tuple of two values: [min, max].
-     */
+    /** Checks if a string value matches a regular expression pattern.
+     * The specific regex syntax may depend on the database. */
+    MATCHES_REGEX = "MATCHES_REGEX",
+    /** Checks if a value is within a set of specified values. */
+    IN = "IN",
+    /** Checks if a value is not within a set of specified values. */
+    NOT_IN = "NOT IN",
+    /** Checks if a value is NULL. */
+    IS_NULL = "IS_NULL",
+    /** Checks if a value is NOT NULL. */
+    IS_NOT_NULL = "IS_NOT_NULL",
+    /** Checks if a value is within a specified range (inclusive).
+     * Expects an array or tuple of two values: [min, max]. */
     BETWEEN = "BETWEEN",
-    /**
-     * Checks if a value is outside a specified range (inclusive).
-     * Expects an array or tuple of two values: [min, max].
-     */
+    /** Checks if a value is outside a specified range (inclusive).
+     * Expects an array or tuple of two values: [min, max]. */
     NOT_BETWEEN = "NOT_BETWEEN",
-    /**
-     * Checks if a string value matches a regular expression pattern.
-     * The specific regex syntax may depend on the database.
-     * Expects a string representing the regular expression.
-     */
-    MATCHES_REGEX = "MATCHES_REGEX",
-    /**
-     * Checks if a string value matches a pattern (case-insensitive).
-     * Expects a string for the pattern.
-     */
-    ILIKE = "ILIKE",
-    /**
-     * Checks if a string value does not match a pattern (case-insensitive).
-     * Expects a string for the pattern.
-     */
-    NOT_ILIKE = "NOT_ILIKE",
-    /**
-     * Checks if a JSON column contains a specific value or path.
-     * The specific implementation depends on the database (e.g., JSON_CONTAINS in MySQL, @> in PostgreSQL for JSONB).
-     */
+    /** Checks if the value at a specific JSON path is equal to a given primitive value.
+     * This is for simple key-value equality checks within a JSON object.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_PATH_VALUE_EQUALS, value: { 'status': 'published', 'views': 100 } } */
+    JSON_PATH_VALUE_EQUALS = "JSON_PATH_VALUE_EQUALS",
+    /** Checks if the value at a specific JSON path is NOT equal to a given primitive value.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_PATH_VALUE_NOT_EQUALS, value: { 'status': 'draft' } } */
+    JSON_PATH_VALUE_NOT_EQUALS = "JSON_PATH_VALUE_NOT_EQUALS",
+    /** Checks if a JSON document (or a value at a specific path within it) contains a specified JSON value.
+     * This maps directly to database functions like MySQL's `JSON_CONTAINS`.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_CONTAINS, value: { 'tags': 'tech', 'details.views': 100 } } */
     JSON_CONTAINS = "JSON_CONTAINS",
-    /**
-     * Checks if a JSON column does not contain a specific value or path.
-     * The specific implementation depends on the database.
-     */
+    /** Checks if a JSON document (or a value at a specific path within it) does NOT contain a specified JSON value.
+     * This maps directly to database functions like MySQL's `JSON_CONTAINS` with negation.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_NOT_CONTAINS, value: { 'tags': 'spam' } } */
     JSON_NOT_CONTAINS = "JSON_NOT_CONTAINS",
-    /**
-     * Checks if a column representing an array contains a specific element.
-     * The underlying column could be a native array type (e.g., PostgreSQL)
-     * or a JSON array (e.g., MySQL).
-     */
+    /** Checks if a JSON document (or a value at a specific path within it) contains AT LEAST ONE of the specified JSON values.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_CONTAINS_ANY, value: { 'tags': ['tech', 'news'] } } */
+    JSON_CONTAINS_ANY = "JSON_CONTAINS_ANY",
+    /** Checks if a JSON document (or a value at a specific path within it) does NOT contain AT LEAST ONE of the specified JSON values.
+     * (i.e., it contains none of them). */
+    JSON_NOT_CONTAINS_ANY = "JSON_NOT_CONTAINS_ANY",
+    /** Checks if a JSON document (or a value at a specific path within it) contains ALL of the specified JSON values.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_CONTAINS_ALL, value: { 'tags': ['tech', 'important'] } } */
+    JSON_CONTAINS_ALL = "JSON_CONTAINS_ALL",
+    /** Checks if a JSON document (or a value at a specific path within it) does NOT contain ALL of the specified JSON values.
+     * (i.e., it is missing at least one of them). */
+    JSON_NOT_CONTAINS_ALL = "JSON_NOT_CONTAINS_ALL",
+    /** Checks if an array contains a specific element.
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_CONTAINS_ELEMENT, value: 'tech' } */
     ARRAY_CONTAINS_ELEMENT = "ARRAY_CONTAINS_ELEMENT",
-    /**
-     * Checks if a column representing an array contains ALL elements from the provided array.
-     * The underlying column could be a native array type or a JSON array.
-     */
-    ARRAY_CONTAINS_ALL_ELEMENTS = "ARRAY_CONTAINS_ALL_ELEMENTS",
-    /**
-     * Checks if a column representing an array contains AT LEAST ONE element from the provided array.
-     * The underlying column could be a native array type or a JSON array.
-     */
+    /** Checks if an array does NOT contain a specific element.
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_NOT_CONTAINS_ELEMENT, value: 'finance' } */
+    ARRAY_NOT_CONTAINS_ELEMENT = "ARRAY_NOT_CONTAINS_ELEMENT",
+    /** Checks if an array contains AT LEAST ONE element from a given array.
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_CONTAINS_ANY_ELEMENT, value: ['tech', 'news'] } */
     ARRAY_CONTAINS_ANY_ELEMENT = "ARRAY_CONTAINS_ANY_ELEMENT",
-    /**
-     * Checks if a column representing an array is exactly equal to the provided array
-     * (order and elements must match).
-     * The underlying column could be a native array type or a JSON array.
-     */
-    ARRAY_EQUALS = "ARRAY_EQUALS"
+    /** Checks if an array does NOT contain AT LEAST ONE element from a given array.
+     * (i.e., it contains none of them). */
+    ARRAY_NOT_CONTAINS_ANY_ELEMENT = "ARRAY_NOT_CONTAINS_ANY_ELEMENT",
+    /** Checks if an array contains ALL elements from a given array.
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_CONTAINS_ALL_ELEMENTS, value: ['tech', 'important'] } */
+    ARRAY_CONTAINS_ALL_ELEMENTS = "ARRAY_CONTAINS_ALL_ELEMENTS",
+    /** Checks if an array does NOT contain ALL elements from a given array.
+     * (i.e., it is missing at least one of them). */
+    ARRAY_NOT_CONTAINS_ALL_ELEMENTS = "ARRAY_NOT_CONTAINS_ALL_ELEMENTS",
+    /** Checks if an array is equal to a given array (order-insensitive).
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_EQUALS, value: ['news', 'tech'] } */
+    ARRAY_EQUALS = "ARRAY_EQUALS",
+    /** Checks if an array is NOT equal to a given array (order-insensitive).
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_NOT_EQUALS, value: ['finance', 'sports'] } */
+    ARRAY_NOT_EQUALS = "ARRAY_NOT_EQUALS",
+    /** Checks if an array is exactly equal to a given array (order-sensitive).
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_EQUALS_STRICT, value: ['tech', 'news'] } */
+    ARRAY_EQUALS_STRICT = "ARRAY_EQUALS_STRICT",
+    /** Checks if an array is NOT exactly equal to a given array (order-sensitive).
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_NOT_EQUALS_STRICT, value: ['news', 'tech'] } */
+    ARRAY_NOT_EQUALS_STRICT = "ARRAY_NOT_EQUALS_STRICT",
+    /** Checks if a field, representing a collection of values (e.g., MySQL SET type
+     * or a text field with comma-delimited values), contains a specific value. */
+    SET_CONTAINS = "SET_CONTAINS",
+    /** Checks if a field, representing a collection of values (e.g., MySQL SET type
+     * or a text field with comma-delimited values), does NOT contain a specific value. */
+    SET_NOT_CONTAINS = "SET_NOT_CONTAINS",
+    /** Checks if a field, representing a collection of values (e.g., MySQL SET type
+     * or a text field with comma-delimited values), contains AT LEAST ONE of the specified values. */
+    SET_CONTAINS_ANY = "SET_CONTAINS_ANY",
+    /** Checks if a field, representing a collection of values, does NOT contain AT LEAST ONE of the specified values.
+     * (i.e., it contains none of them). */
+    SET_NOT_CONTAINS_ANY = "SET_NOT_CONTAINS_ANY",
+    /** Checks if a field, representing a collection of values (e.g., MySQL SET type
+     * or a text field with comma-delimited values), contains ALL of the specified values. */
+    SET_CONTAINS_ALL = "SET_CONTAINS_ALL",
+    /** Checks if a field, representing a collection of values, does NOT contain ALL of the specified values.
+     * (i.e., it is missing at least one of them). */
+    SET_NOT_CONTAINS_ALL = "SET_NOT_CONTAINS_ALL"
 }
 /**
  * Enumerates the logical operators used to combine filter conditions or groups.

package/dist/criteria/types/operator.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operator.types.d.ts","sourceRoot":"","sources":["../../../src/criteria/types/operator.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,cAAc;IACxB,2BAA2B;IAC3B,MAAM,MAAM;IACZ,6BAA6B;IAC7B,UAAU,OAAO;IACjB,iDAAiD;IACjD,YAAY,MAAM;IAClB,6DAA6D;IAC7D,sBAAsB,OAAO;IAC7B,8CAA8C;IAC9C,SAAS,MAAM;IACf,0DAA0D;IAC1D,mBAAmB,OAAO;IAC1B,wFAAwF;IACxF,IAAI,SAAS;IACb,yDAAyD;IACzD,QAAQ,aAAa;IACrB,6DAA6D;IAC7D,EAAE,OAAO;IACT,iEAAiE;IACjE,MAAM,WAAW;IACjB,iCAAiC;IACjC,OAAO,YAAY;IACnB,qCAAqC;IACrC,WAAW,gBAAgB;IAC3B,sGAAsG;IACtG,QAAQ,aAAa;IACrB,iEAAiE;IACjE,WAAW,gBAAgB;IAC3B,+DAA+D;IAC/D,SAAS,cAAc;IACvB,sEAAsE;IACtE,YAAY,iBAAiB;IAC7B;;;;OAIG;IACH,YAAY,iBAAiB;IAC7B;;;;OAIG;IACH,gBAAgB,qBAAqB;IACrC;;;;OAIG;IACH,gBAAgB,qBAAqB;IACrC;;;;OAIG;IACH,gBAAgB,qBAAqB;IACrC;;;OAGG;IACH,OAAO,YAAY;IACnB;;;OAGG;IACH,WAAW,gBAAgB;IAC3B;;;;OAIG;IACH,aAAa,kBAAkB;IAC/B;;;OAGG;IACH,KAAK,UAAU;IACf;;;OAGG;IACH,SAAS,cAAc;IACvB;;;OAGG;IACH,aAAa,kBAAkB;IAC/B;;;OAGG;IACH,iBAAiB,sBAAsB;IACvC;;;;OAIG;IACH,sBAAsB,2BAA2B;IACjD;;;OAGG;IACH,2BAA2B,gCAAgC;IAC3D;;;OAGG;IACH,0BAA0B,+BAA+B;IACzD;;;;OAIG;IACH,YAAY,iBAAiB;CAC9B;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,2EAA2E;IAC3E,GAAG,QAAQ;IACX,kFAAkF;IAClF,EAAE,OAAO;CACV"}
+{"version":3,"file":"operator.types.d.ts","sourceRoot":"","sources":["../../../src/criteria/types/operator.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,cAAc;IACxB,2BAA2B;IAC3B,MAAM,MAAM;IACZ,6BAA6B;IAC7B,UAAU,OAAO;IACjB,iDAAiD;IACjD,YAAY,MAAM;IAClB,6DAA6D;IAC7D,sBAAsB,OAAO;IAC7B,8CAA8C;IAC9C,SAAS,MAAM;IACf,0DAA0D;IAC1D,mBAAmB,OAAO;IAE1B,wFAAwF;IACxF,IAAI,SAAS;IACb,yDAAyD;IACzD,QAAQ,aAAa;IACrB,qEAAqE;IACrE,KAAK,UAAU;IACf,4EAA4E;IAC5E,SAAS,cAAc;IACvB,sGAAsG;IACtG,QAAQ,aAAa;IACrB,sEAAsE;IACtE,YAAY,iBAAiB;IAC7B,iEAAiE;IACjE,WAAW,gBAAgB;IAC3B,+DAA+D;IAC/D,SAAS,cAAc;IACvB;+DAC2D;IAC3D,aAAa,kBAAkB;IAE/B,6DAA6D;IAC7D,EAAE,OAAO;IACT,iEAAiE;IACjE,MAAM,WAAW;IACjB,iCAAiC;IACjC,OAAO,YAAY;IACnB,qCAAqC;IACrC,WAAW,gBAAgB;IAE3B;8DAC0D;IAC1D,OAAO,YAAY;IACnB;8DAC0D;IAC1D,WAAW,gBAAgB;IAE3B;;yIAEqI;IACrI,sBAAsB,2BAA2B;IACjD;2HACuH;IACvH,0BAA0B,+BAA+B;IACzD;;iIAE6H;IAC7H,aAAa,kBAAkB;IAC/B;;+GAE2G;IAC3G,iBAAiB,sBAAsB;IACvC;yHACqH;IACrH,iBAAiB,sBAAsB;IACvC;2CACuC;IACvC,qBAAqB,0BAA0B;IAC/C;8HAC0H;IAC1H,iBAAiB,sBAAsB;IACvC;qDACiD;IACjD,qBAAqB,0BAA0B;IAE/C;oGACgG;IAChG,sBAAsB,2BAA2B;IACjD;2GACuG;IACvG,0BAA0B,+BAA+B;IACzD;kHAC8G;IAC9G,0BAA0B,+BAA+B;IACzD;2CACuC;IACvC,8BAA8B,mCAAmC;IACjE;wHACoH;IACpH,2BAA2B,gCAAgC;IAC3D;qDACiD;IACjD,+BAA+B,oCAAoC;IACnE;oGACgG;IAChG,YAAY,iBAAiB;IAC7B;6GACyG;IACzG,gBAAgB,qBAAqB;IACrC;2GACuG;IACvG,mBAAmB,wBAAwB;IAC3C;+GAC2G;IAC3G,uBAAuB,4BAA4B;IACnD;kFAC8E;IAC9E,YAAY,iBAAiB;IAC7B;0FACsF;IACtF,gBAAgB,qBAAqB;IACrC;sGACkG;IAClG,gBAAgB,qBAAqB;IACrC;2CACuC;IACvC,oBAAoB,yBAAyB;IAC7C;6FACyF;IACzF,gBAAgB,qBAAqB;IACrC;qDACiD;IACjD,oBAAoB,yBAAyB;CAC9C;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,2EAA2E;IAC3E,GAAG,QAAQ;IACX,kFAAkF;IAClF,EAAE,OAAO;CACV"}

package/dist/criteria/types/operator.types.js

@@ -19,104 +19,110 @@ export var FilterOperator;
     FilterOperator["LIKE"] = "LIKE";
     /** Checks if a string value does not match a pattern. */
     FilterOperator["NOT_LIKE"] = "NOT LIKE";
-    /** Checks if a value is within a set of specified values. */
-    FilterOperator["IN"] = "IN";
-    /** Checks if a value is not within a set of specified values. */
-    FilterOperator["NOT_IN"] = "NOT IN";
-    /** Checks if a value is NULL. */
-    FilterOperator["IS_NULL"] = "IS NULL";
-    /** Checks if a value is NOT NULL. */
-    FilterOperator["IS_NOT_NULL"] = "IS NOT NULL";
+    /** Checks if a string value matches a pattern (case-insensitive). */
+    FilterOperator["ILIKE"] = "ILIKE";
+    /** Checks if a string value does not match a pattern (case-insensitive). */
+    FilterOperator["NOT_ILIKE"] = "NOT_ILIKE";
     /** Checks if a string value contains a specific substring (often case-insensitive, depends on DB). */
     FilterOperator["CONTAINS"] = "CONTAINS";
+    /** Checks if a string value does not contain a specific substring. */
+    FilterOperator["NOT_CONTAINS"] = "NOT_CONTAINS";
     /** Checks if a string value starts with a specific substring. */
     FilterOperator["STARTS_WITH"] = "STARTS_WITH";
     /** Checks if a string value ends with a specific substring. */
     FilterOperator["ENDS_WITH"] = "ENDS_WITH";
-    /** Checks if a string value does not contain a specific substring. */
-    FilterOperator["NOT_CONTAINS"] = "NOT_CONTAINS";
-    /**
-     * Checks if a field, representing a collection of values (e.g., MySQL SET type
-     * or a text field with comma-delimited values), contains a specific value.
-     * Expects a single value.
-     */
-    FilterOperator["SET_CONTAINS"] = "SET_CONTAINS";
-    /**
-     * Checks if a field, representing a collection of values (e.g., MySQL SET type
-     * or a text field with comma-delimited values), does NOT contain a specific value.
-     * Expects a single value.
-     */
-    FilterOperator["SET_NOT_CONTAINS"] = "SET_NOT_CONTAINS";
-    /**
-     * Checks if a field, representing a collection of values (e.g., MySQL SET type
-     * or a text field with comma-delimited values), contains AT LEAST ONE of the specified values.
-     * Expects an array of values.
-     */
-    FilterOperator["SET_CONTAINS_ANY"] = "SET_CONTAINS_ANY";
-    /**
-     * Checks if a field, representing a collection of values (e.g., MySQL SET type
-     * or a text field with comma-delimited values), contains ALL of the specified values.
-     * Expects an array of values.
-     */
-    FilterOperator["SET_CONTAINS_ALL"] = "SET_CONTAINS_ALL";
-    /**
-     * Checks if a value is within a specified range (inclusive).
-     * Expects an array or tuple of two values: [min, max].
-     */
+    /** Checks if a string value matches a regular expression pattern.
+     * The specific regex syntax may depend on the database. */
+    FilterOperator["MATCHES_REGEX"] = "MATCHES_REGEX";
+    /** Checks if a value is within a set of specified values. */
+    FilterOperator["IN"] = "IN";
+    /** Checks if a value is not within a set of specified values. */
+    FilterOperator["NOT_IN"] = "NOT IN";
+    /** Checks if a value is NULL. */
+    FilterOperator["IS_NULL"] = "IS_NULL";
+    /** Checks if a value is NOT NULL. */
+    FilterOperator["IS_NOT_NULL"] = "IS_NOT_NULL";
+    /** Checks if a value is within a specified range (inclusive).
+     * Expects an array or tuple of two values: [min, max]. */
     FilterOperator["BETWEEN"] = "BETWEEN";
-    /**
-     * Checks if a value is outside a specified range (inclusive).
-     * Expects an array or tuple of two values: [min, max].
-     */
+    /** Checks if a value is outside a specified range (inclusive).
+     * Expects an array or tuple of two values: [min, max]. */
     FilterOperator["NOT_BETWEEN"] = "NOT_BETWEEN";
-    /**
-     * Checks if a string value matches a regular expression pattern.
-     * The specific regex syntax may depend on the database.
-     * Expects a string representing the regular expression.
-     */
-    FilterOperator["MATCHES_REGEX"] = "MATCHES_REGEX";
-    /**
-     * Checks if a string value matches a pattern (case-insensitive).
-     * Expects a string for the pattern.
-     */
-    FilterOperator["ILIKE"] = "ILIKE";
-    /**
-     * Checks if a string value does not match a pattern (case-insensitive).
-     * Expects a string for the pattern.
-     */
-    FilterOperator["NOT_ILIKE"] = "NOT_ILIKE";
-    /**
-     * Checks if a JSON column contains a specific value or path.
-     * The specific implementation depends on the database (e.g., JSON_CONTAINS in MySQL, @> in PostgreSQL for JSONB).
-     */
+    /** Checks if the value at a specific JSON path is equal to a given primitive value.
+     * This is for simple key-value equality checks within a JSON object.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_PATH_VALUE_EQUALS, value: { 'status': 'published', 'views': 100 } } */
+    FilterOperator["JSON_PATH_VALUE_EQUALS"] = "JSON_PATH_VALUE_EQUALS";
+    /** Checks if the value at a specific JSON path is NOT equal to a given primitive value.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_PATH_VALUE_NOT_EQUALS, value: { 'status': 'draft' } } */
+    FilterOperator["JSON_PATH_VALUE_NOT_EQUALS"] = "JSON_PATH_VALUE_NOT_EQUALS";
+    /** Checks if a JSON document (or a value at a specific path within it) contains a specified JSON value.
+     * This maps directly to database functions like MySQL's `JSON_CONTAINS`.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_CONTAINS, value: { 'tags': 'tech', 'details.views': 100 } } */
     FilterOperator["JSON_CONTAINS"] = "JSON_CONTAINS";
-    /**
-     * Checks if a JSON column does not contain a specific value or path.
-     * The specific implementation depends on the database.
-     */
+    /** Checks if a JSON document (or a value at a specific path within it) does NOT contain a specified JSON value.
+     * This maps directly to database functions like MySQL's `JSON_CONTAINS` with negation.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_NOT_CONTAINS, value: { 'tags': 'spam' } } */
     FilterOperator["JSON_NOT_CONTAINS"] = "JSON_NOT_CONTAINS";
-    /**
-     * Checks if a column representing an array contains a specific element.
-     * The underlying column could be a native array type (e.g., PostgreSQL)
-     * or a JSON array (e.g., MySQL).
-     */
+    /** Checks if a JSON document (or a value at a specific path within it) contains AT LEAST ONE of the specified JSON values.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_CONTAINS_ANY, value: { 'tags': ['tech', 'news'] } } */
+    FilterOperator["JSON_CONTAINS_ANY"] = "JSON_CONTAINS_ANY";
+    /** Checks if a JSON document (or a value at a specific path within it) does NOT contain AT LEAST ONE of the specified JSON values.
+     * (i.e., it contains none of them). */
+    FilterOperator["JSON_NOT_CONTAINS_ANY"] = "JSON_NOT_CONTAINS_ANY";
+    /** Checks if a JSON document (or a value at a specific path within it) contains ALL of the specified JSON values.
+     * @example { field: 'metadata', operator: FilterOperator.JSON_CONTAINS_ALL, value: { 'tags': ['tech', 'important'] } } */
+    FilterOperator["JSON_CONTAINS_ALL"] = "JSON_CONTAINS_ALL";
+    /** Checks if a JSON document (or a value at a specific path within it) does NOT contain ALL of the specified JSON values.
+     * (i.e., it is missing at least one of them). */
+    FilterOperator["JSON_NOT_CONTAINS_ALL"] = "JSON_NOT_CONTAINS_ALL";
+    /** Checks if an array contains a specific element.
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_CONTAINS_ELEMENT, value: 'tech' } */
     FilterOperator["ARRAY_CONTAINS_ELEMENT"] = "ARRAY_CONTAINS_ELEMENT";
-    /**
-     * Checks if a column representing an array contains ALL elements from the provided array.
-     * The underlying column could be a native array type or a JSON array.
-     */
-    FilterOperator["ARRAY_CONTAINS_ALL_ELEMENTS"] = "ARRAY_CONTAINS_ALL_ELEMENTS";
-    /**
-     * Checks if a column representing an array contains AT LEAST ONE element from the provided array.
-     * The underlying column could be a native array type or a JSON array.
-     */
+    /** Checks if an array does NOT contain a specific element.
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_NOT_CONTAINS_ELEMENT, value: 'finance' } */
+    FilterOperator["ARRAY_NOT_CONTAINS_ELEMENT"] = "ARRAY_NOT_CONTAINS_ELEMENT";
+    /** Checks if an array contains AT LEAST ONE element from a given array.
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_CONTAINS_ANY_ELEMENT, value: ['tech', 'news'] } */
     FilterOperator["ARRAY_CONTAINS_ANY_ELEMENT"] = "ARRAY_CONTAINS_ANY_ELEMENT";
-    /**
-     * Checks if a column representing an array is exactly equal to the provided array
-     * (order and elements must match).
-     * The underlying column could be a native array type or a JSON array.
-     */
+    /** Checks if an array does NOT contain AT LEAST ONE element from a given array.
+     * (i.e., it contains none of them). */
+    FilterOperator["ARRAY_NOT_CONTAINS_ANY_ELEMENT"] = "ARRAY_NOT_CONTAINS_ANY_ELEMENT";
+    /** Checks if an array contains ALL elements from a given array.
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_CONTAINS_ALL_ELEMENTS, value: ['tech', 'important'] } */
+    FilterOperator["ARRAY_CONTAINS_ALL_ELEMENTS"] = "ARRAY_CONTAINS_ALL_ELEMENTS";
+    /** Checks if an array does NOT contain ALL elements from a given array.
+     * (i.e., it is missing at least one of them). */
+    FilterOperator["ARRAY_NOT_CONTAINS_ALL_ELEMENTS"] = "ARRAY_NOT_CONTAINS_ALL_ELEMENTS";
+    /** Checks if an array is equal to a given array (order-insensitive).
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_EQUALS, value: ['news', 'tech'] } */
     FilterOperator["ARRAY_EQUALS"] = "ARRAY_EQUALS";
+    /** Checks if an array is NOT equal to a given array (order-insensitive).
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_NOT_EQUALS, value: ['finance', 'sports'] } */
+    FilterOperator["ARRAY_NOT_EQUALS"] = "ARRAY_NOT_EQUALS";
+    /** Checks if an array is exactly equal to a given array (order-sensitive).
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_EQUALS_STRICT, value: ['tech', 'news'] } */
+    FilterOperator["ARRAY_EQUALS_STRICT"] = "ARRAY_EQUALS_STRICT";
+    /** Checks if an array is NOT exactly equal to a given array (order-sensitive).
+     * @example { field: 'tags', operator: FilterOperator.ARRAY_NOT_EQUALS_STRICT, value: ['news', 'tech'] } */
+    FilterOperator["ARRAY_NOT_EQUALS_STRICT"] = "ARRAY_NOT_EQUALS_STRICT";
+    /** Checks if a field, representing a collection of values (e.g., MySQL SET type
+     * or a text field with comma-delimited values), contains a specific value. */
+    FilterOperator["SET_CONTAINS"] = "SET_CONTAINS";
+    /** Checks if a field, representing a collection of values (e.g., MySQL SET type
+     * or a text field with comma-delimited values), does NOT contain a specific value. */
+    FilterOperator["SET_NOT_CONTAINS"] = "SET_NOT_CONTAINS";
+    /** Checks if a field, representing a collection of values (e.g., MySQL SET type
+     * or a text field with comma-delimited values), contains AT LEAST ONE of the specified values. */
+    FilterOperator["SET_CONTAINS_ANY"] = "SET_CONTAINS_ANY";
+    /** Checks if a field, representing a collection of values, does NOT contain AT LEAST ONE of the specified values.
+     * (i.e., it contains none of them). */
+    FilterOperator["SET_NOT_CONTAINS_ANY"] = "SET_NOT_CONTAINS_ANY";
+    /** Checks if a field, representing a collection of values (e.g., MySQL SET type
+     * or a text field with comma-delimited values), contains ALL of the specified values. */
+    FilterOperator["SET_CONTAINS_ALL"] = "SET_CONTAINS_ALL";
+    /** Checks if a field, representing a collection of values, does NOT contain ALL of the specified values.
+     * (i.e., it is missing at least one of them). */
+    FilterOperator["SET_NOT_CONTAINS_ALL"] = "SET_NOT_CONTAINS_ALL";
 })(FilterOperator || (FilterOperator = {}));
 /**
  * Enumerates the logical operators used to combine filter conditions or groups.

package/dist/criteria/types/operator.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"operator.types.js","sourceRoot":"","sources":["../../../src/criteria/types/operator.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAN,IAAY,cAmHX;AAnHD,WAAY,cAAc;IACxB,2BAA2B;IAC3B,8BAAY,CAAA;IACZ,6BAA6B;IAC7B,mCAAiB,CAAA;IACjB,iDAAiD;IACjD,oCAAkB,CAAA;IAClB,6DAA6D;IAC7D,+CAA6B,CAAA;IAC7B,8CAA8C;IAC9C,iCAAe,CAAA;IACf,0DAA0D;IAC1D,4CAA0B,CAAA;IAC1B,wFAAwF;IACxF,+BAAa,CAAA;IACb,yDAAyD;IACzD,uCAAqB,CAAA;IACrB,6DAA6D;IAC7D,2BAAS,CAAA;IACT,iEAAiE;IACjE,mCAAiB,CAAA;IACjB,iCAAiC;IACjC,qCAAmB,CAAA;IACnB,qCAAqC;IACrC,6CAA2B,CAAA;IAC3B,sGAAsG;IACtG,uCAAqB,CAAA;IACrB,iEAAiE;IACjE,6CAA2B,CAAA;IAC3B,+DAA+D;IAC/D,yCAAuB,CAAA;IACvB,sEAAsE;IACtE,+CAA6B,CAAA;IAC7B;;;;OAIG;IACH,+CAA6B,CAAA;IAC7B;;;;OAIG;IACH,uDAAqC,CAAA;IACrC;;;;OAIG;IACH,uDAAqC,CAAA;IACrC;;;;OAIG;IACH,uDAAqC,CAAA;IACrC;;;OAGG;IACH,qCAAmB,CAAA;IACnB;;;OAGG;IACH,6CAA2B,CAAA;IAC3B;;;;OAIG;IACH,iDAA+B,CAAA;IAC/B;;;OAGG;IACH,iCAAe,CAAA;IACf;;;OAGG;IACH,yCAAuB,CAAA;IACvB;;;OAGG;IACH,iDAA+B,CAAA;IAC/B;;;OAGG;IACH,yDAAuC,CAAA;IACvC;;;;OAIG;IACH,mEAAiD,CAAA;IACjD;;;OAGG;IACH,6EAA2D,CAAA;IAC3D;;;OAGG;IACH,2EAAyD,CAAA;IACzD;;;;OAIG;IACH,+CAA6B,CAAA;AAC/B,CAAC,EAnHW,cAAc,KAAd,cAAc,QAmHzB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,2EAA2E;IAC3E,8BAAW,CAAA;IACX,kFAAkF;IAClF,4BAAS,CAAA;AACX,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B"}
+{"version":3,"file":"operator.types.js","sourceRoot":"","sources":["../../../src/criteria/types/operator.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAN,IAAY,cA8HX;AA9HD,WAAY,cAAc;IACxB,2BAA2B;IAC3B,8BAAY,CAAA;IACZ,6BAA6B;IAC7B,mCAAiB,CAAA;IACjB,iDAAiD;IACjD,oCAAkB,CAAA;IAClB,6DAA6D;IAC7D,+CAA6B,CAAA;IAC7B,8CAA8C;IAC9C,iCAAe,CAAA;IACf,0DAA0D;IAC1D,4CAA0B,CAAA;IAE1B,wFAAwF;IACxF,+BAAa,CAAA;IACb,yDAAyD;IACzD,uCAAqB,CAAA;IACrB,qEAAqE;IACrE,iCAAe,CAAA;IACf,4EAA4E;IAC5E,yCAAuB,CAAA;IACvB,sGAAsG;IACtG,uCAAqB,CAAA;IACrB,sEAAsE;IACtE,+CAA6B,CAAA;IAC7B,iEAAiE;IACjE,6CAA2B,CAAA;IAC3B,+DAA+D;IAC/D,yCAAuB,CAAA;IACvB;+DAC2D;IAC3D,iDAA+B,CAAA;IAE/B,6DAA6D;IAC7D,2BAAS,CAAA;IACT,iEAAiE;IACjE,mCAAiB,CAAA;IACjB,iCAAiC;IACjC,qCAAmB,CAAA;IACnB,qCAAqC;IACrC,6CAA2B,CAAA;IAE3B;8DAC0D;IAC1D,qCAAmB,CAAA;IACnB;8DAC0D;IAC1D,6CAA2B,CAAA;IAE3B;;yIAEqI;IACrI,mEAAiD,CAAA;IACjD;2HACuH;IACvH,2EAAyD,CAAA;IACzD;;iIAE6H;IAC7H,iDAA+B,CAAA;IAC/B;;+GAE2G;IAC3G,yDAAuC,CAAA;IACvC;yHACqH;IACrH,yDAAuC,CAAA;IACvC;2CACuC;IACvC,iEAA+C,CAAA;IAC/C;8HAC0H;IAC1H,yDAAuC,CAAA;IACvC;qDACiD;IACjD,iEAA+C,CAAA;IAE/C;oGACgG;IAChG,mEAAiD,CAAA;IACjD;2GACuG;IACvG,2EAAyD,CAAA;IACzD;kHAC8G;IAC9G,2EAAyD,CAAA;IACzD;2CACuC;IACvC,mFAAiE,CAAA;IACjE;wHACoH;IACpH,6EAA2D,CAAA;IAC3D;qDACiD;IACjD,qFAAmE,CAAA;IACnE;oGACgG;IAChG,+CAA6B,CAAA;IAC7B;6GACyG;IACzG,uDAAqC,CAAA;IACrC;2GACuG;IACvG,6DAA2C,CAAA;IAC3C;+GAC2G;IAC3G,qEAAmD,CAAA;IACnD;kFAC8E;IAC9E,+CAA6B,CAAA;IAC7B;0FACsF;IACtF,uDAAqC,CAAA;IACrC;sGACkG;IAClG,uDAAqC,CAAA;IACrC;2CACuC;IACvC,+DAA6C,CAAA;IAC7C;6FACyF;IACzF,uDAAqC,CAAA;IACrC;qDACiD;IACjD,+DAA6C,CAAA;AAC/C,CAAC,EA9HW,cAAc,KAAd,cAAc,QA8HzB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,2EAA2E;IAC3E,8BAAW,CAAA;IACX,kFAAkF;IAClF,4BAAS,CAAA;AACX,CAAC,EALW,eAAe,KAAf,eAAe,QAK1B"}

package/dist/criteria/types/schema.types.d.ts

@@ -7,43 +7,115 @@
  */
 export type JoinRelationType = 'one_to_one' | 'one_to_many' | 'many_to_one' | 'many_to_many';
 /**
- * Describes the configuration for a joinable relation within a {@link CriteriaSchema}.
- * @template ValidAlias - A string literal type representing a valid alias for the join.
+ * Extracts a union type of all valid field names from a given {@link CriteriaSchema}.
+ * @template T - The {@link CriteriaSchema} from which to extract field names.
+ * @example type UserFields = FieldOfSchema<typeof UserSchema>; // "id" | "name" | "email"
  */
-export type SchemaJoins<ValidAlias extends string> = {
-    /** The alias used to refer to this join in criteria construction. */
-    alias: ValidAlias;
+export type FieldOfSchema<T extends CriteriaSchema> = T['fields'] extends ReadonlyArray<string> ? T['fields'][number] : never;
+/**
+ * Describes the configuration for a simple joinable relation (one-to-one, one-to-many, many-to-one).
+ * The `relation_field` is not strongly typed against the target schema at compile-time to avoid complex cross-schema dependencies.
+ * It will be validated at runtime when the schema is defined and when the join is processed.
+ * @template TFields - The readonly array of field names from the local schema.
+ * @template ValidAlias - A string literal type representing the alias for this specific relation.
+ */
+export type SchemaSimpleJoin<TFields extends ReadonlyArray<string>, ValidAlias extends string> = {
+    /** The alias for this specific relation, used to identify it in `.join()` calls. */
+    relation_alias: ValidAlias;
     /** The type of relationship this join represents (e.g., 'one_to_many'). */
-    relation_type: JoinRelationType;
+    relation_type: 'one_to_one' | 'one_to_many' | 'many_to_one';
+    /** The `source_name` of the schema that this relation targets. Used for robust validation. */
+    target_source_name: string;
+    /**
+     * The field name in the local schema used for the join condition.
+     * This field is strongly typed against the local schema's fields.
+     */
+    local_field: TFields[number];
+    /**
+     * The field name in the target schema (the related entity) used for the join condition.
+     * This field is a string and will be validated at runtime.
+     */
+    relation_field: string;
+    /**
+     * Optional metadata associated with this specific join configuration.
+     */
+    metadata?: {
+        [key: string]: any;
+    };
+};
+/**
+ * Describes the configuration for a many-to-many joinable relation (via a pivot table).
+ * The `relation_field.reference` is not strongly typed against the target schema at compile-time to avoid complex cross-schema dependencies.
+ * It will be validated at runtime when the schema is defined and when the join is processed.
+ * @template TFields - The readonly array of field names from the local schema.
+ * @template ValidAlias - A string literal type representing the alias for this specific relation.
+ */
+export type SchemaPivotJoin<TFields extends ReadonlyArray<string>, ValidAlias extends string> = {
+    /** The alias for this specific relation, used to identify it in `.join()` calls. */
+    relation_alias: ValidAlias;
+    /** The type of relationship this join represents (must be 'many_to_many'). */
+    relation_type: 'many_to_many';
+    /** The `source_name` of the schema that this relation targets. Used for robust validation. */
+    target_source_name: string;
+    /** The source name (table name) of the pivot table. */
+    pivot_source_name: string;
+    /** Configuration for the join field on the local side, referencing the pivot table. */
+    local_field: {
+        /** The field name in the pivot table that links to the local schema. */
+        pivot_field: string;
+        /**
+         * The field name in the local schema that the pivot table field references.
+         * This field is strongly typed against the local schema's fields.
+         */
+        reference: TFields[number];
+    };
+    /** Configuration for the join field on the related side, referencing the pivot table. */
+    relation_field: {
+        /** The field name in the pivot table that links to the related schema. */
+        pivot_field: string;
+        /**
+         * The field name in the related schema that the pivot table field references.
+         * This field is a string and will be validated at runtime.
+         */
+        reference: string;
+    };
     /**
      * Optional metadata associated with this specific join configuration.
-     * This allows for storing arbitrary, translator-specific information
-     * or hints directly within the schema definition for a join.
-     * For example, it could hold database-specific join hints or
-     * information about how to handle the join in a particular ORM.
      */
     metadata?: {
         [key: string]: any;
     };
 };
+/**
+ * Describes the configuration for a joinable relation within a {@link CriteriaSchema}.
+ * It is a union of simple and pivot join types.
+ * @template TFields - The readonly array of field names from the local schema.
+ * @template ValidAlias - A string literal type representing the alias for this specific relation.
+ */
+export type SchemaJoins<TFields extends ReadonlyArray<string>, ValidAlias extends string> = SchemaSimpleJoin<TFields, ValidAlias> | SchemaPivotJoin<TFields, ValidAlias>;
 /**
  * Represents the schema definition for an entity, used by the Criteria system.
- * It defines the entity's source name (e.g., table name), available aliases,
+ * It defines the entity's source name (e.g., table name), a single canonical alias,
  * fields, and joinable relations.
  * @template TFields - A readonly array of string literal types representing the entity's field names.
- * @template TAliases - A readonly array of string literal types representing the entity's valid aliases.
+ * @template TAliase - A string literal type for the entity's canonical alias.
  * @template TSourceName - A string literal type for the entity's source name.
- * @template JoinsAlias - A string literal type representing valid aliases for its joinable relations.
+ * @template Joins - A readonly array of `SchemaJoins` capturing the exact literal types of the relations.
  */
-export type CriteriaSchema<TFields extends ReadonlyArray<string> = ReadonlyArray<string>, TAliases extends ReadonlyArray<string> = ReadonlyArray<string>, TSourceName extends string = string, JoinsAlias extends string = string> = {
+export type CriteriaSchema<TFields extends ReadonlyArray<string> = ReadonlyArray<string>, TAliase extends string = string, TSourceName extends string = string, Joins extends ReadonlyArray<SchemaJoins<TFields, string>> = ReadonlyArray<SchemaJoins<TFields, string>>> = {
     /** The source name of the entity (e.g., database table name). */
     source_name: TSourceName;
-    /** An array of valid aliases that can be used to refer to this entity. */
-    alias: TAliases;
+    /** The canonical alias used to refer to this entity in queries. */
+    alias: TAliase;
     /** An array of field names available for this entity. */
     fields: TFields;
     /** An array of configurations for entities that can be joined from this entity. */
-    joins: ReadonlyArray<SchemaJoins<JoinsAlias>>;
+    relations: Joins;
+    /**
+     * The name of the field that uniquely identifies an entity of this schema.
+     * This field **must** be one of the names listed in the `fields` array.
+     */
+    identifier_field: TFields[number];
     /**
      * Optional metadata associated with the entire schema definition.
      * This can be used to store arbitrary, translator-specific information
@@ -57,29 +129,23 @@ export type CriteriaSchema<TFields extends ReadonlyArray<string> = ReadonlyArray
 };
 /**
  * A helper function to infer and preserve the literal types of a schema definition.
- * Use this when defining schemas to get strong typing for fields, aliases, etc.
- * @template TInput - The type of the schema object being passed.
- * @param {TInput} schema - The schema definition object.
- * @returns {TInput} The same schema object, with its literal types preserved.
- * @example
- * export const UserSchema = GetTypedCriteriaSchema({
- *   source_name: 'users_table',
- *   alias: ['user', 'u'],
- *   fields: ['id', 'name', 'email'],
- *   joins: [{ alias: 'posts', relation_type: 'one_to_many' }]
- * });
- */
-export declare function GetTypedCriteriaSchema<const TInput extends CriteriaSchema>(schema: TInput): TInput;
-/**
- * Extracts a union type of all valid field names from a given {@link CriteriaSchema}.
- * @template T - The {@link CriteriaSchema} from which to extract field names.
- * @example type UserFields = FieldOfSchema<typeof UserSchema>; // "id" | "name" | "email"
- */
-export type FieldOfSchema<T extends CriteriaSchema> = T['fields'] extends ReadonlyArray<string> ? T['fields'][number] : never;
-/**
- * Extracts a union type of all valid aliases from a given {@link CriteriaSchema}.
- * @template T - The {@link CriteriaSchema} from which to extract aliases.
- * @example type UserAliases = SelectedAliasOf<typeof UserSchema>; // "user" | "u"
+ * Use this when defining schemas to get strong typing for fields, aliases, and relations.
+ * This function also performs runtime validation for the schema structure.
+ * @template TFields - A readonly array of string literal types representing the entity's field names.
+ * @template TAliase - A string literal type for the entity's canonical alias.
+ * @template TSourceName - A string literal type for the entity's source name.
+ * @template Joins - A readonly array of `SchemaJoins` capturing the exact literal types of the relations.
+ * @param schema - The schema definition object.
+ * @returns The same schema object, with its literal types preserved for strong type inference.
  */
-export type SelectedAliasOf<T extends CriteriaSchema> = T['alias'] extends ReadonlyArray<string> ? T['alias'][number] : never;
+export declare function GetTypedCriteriaSchema<const TFields extends ReadonlyArray<string>, const TAliase extends string, const TSourceName extends string, const Joins extends ReadonlyArray<SchemaJoins<TFields, string>>>(schema: {
+    source_name: TSourceName;
+    alias: TAliase;
+    fields: TFields;
+    relations: Joins;
+    identifier_field: TFields[number];
+    metadata?: {
+        [key: string]: any;
+    };
+}): CriteriaSchema<TFields, TAliase, TSourceName, Joins>;
 //# sourceMappingURL=schema.types.d.ts.map