@qrvey/filters 0.0.45 → 0.1.0

package/README.md

@@ -1 +1,63 @@
-# qrvey_filters
+# [@qrvey/filters](https://bitbucket.org/qrvey/qrvey_filters/wiki/Home) *0.1.0*
+
+> Helpers and logic for Filtering Data in Qrvey app
+
+## Release pipelines
+
+- Guide to run manual releases in Bitbucket: [RELEASE_PIPELINES.md](./RELEASE_PIPELINES.md)
+
+## Recommended consumption guide
+
+This package exposes **ESM + CommonJS**:
+
+- `import` (ESM) for modern bundlers and better tree shaking.
+- `require` (CommonJS) for legacy implementations.
+
+### 1) Recommended (ESM with tree shaking)
+
+Use named imports from the entrypoint or specific subpaths.
+
+```ts
+// Good: allows bundlers to remove unused exports
+import { FilterManager, FilterBuilder } from "@qrvey/filters";
+
+// Better for critical bundles: import only the module you need
+import { FilterManager } from "@qrvey/filters/classes/index";
+```
+
+### 2) Avoid for optimized bundles
+
+```ts
+// Avoid in frontend apps: can pull more code into the bundle
+import * as QrveyFilters from "@qrvey/filters";
+```
+
+### 3) CommonJS compatibility
+
+For Node projects or integrations that require CommonJS:
+
+```js
+const { FilterManager } = require("@qrvey/filters");
+const { FilterManager } = require("@qrvey/filters/classes/index");
+```
+
+### 4) Recommendations for consumer apps
+
+- Prefer `import` over `require` in frontend code.
+- Use subpaths (`@qrvey/filters/<module>`) on performance-critical paths.
+- Keep tree shaking enabled in your bundler (Webpack/Rollup/Vite in production mode).
+
+---
+
+<!-- MODULES_START -->
+
+## Modules
+
+| Module | Description | Subpath import | API docs |
+| ------ | ----------- | -------------- | -------- |
+| `classes` | Core classes: FilterBuilder, FilterManager, FilterAdapter, FilterSearcher, FilterValidation, FilterValues and FilterResources. | `@qrvey/filters/classes/index` | [docs](docs/classes/index.md) |
+| `helpers` | Stateless utility functions for filter adaptation, settings, ID generation, type resolution and condition handling. | `@qrvey/filters/helpers/index` | [docs](docs/helpers/index.md) |
+| `models` | TypeScript interfaces and types for FilterBuilder, FilterResources and FilterSearcher internals. | `@qrvey/filters/models/index` | [docs](docs/models/index.md) |
+| `resources` | Enums, constants and panel interfaces for filter functions, grouping, logic, operators, scopes, validators, values, visual options and the DEFAULT_FILTER. | `@qrvey/filters/resources/index` | [docs](docs/resources/index.md) |
+
+<!-- MODULES_END -->

package/dist/cjs/classes/FilterAdapter.js

@@ -5,72 +5,33 @@ const filter_adapt_helpers_1 = require("../helpers/filter-adapt.helpers");
 const filter_adapt_legacy_helpers_1 = require("../helpers/filter-adapt.legacy.helpers");
 const filter_adapt_logic_helpers_1 = require("../helpers/filter-adapt.logic.helpers");
 const filters_resources_1 = require("../resources/filters.resources");
-/**
- * Class to adapt the filters
- */
 class FilterAdapter {
     _filters;
     datasets;
     interactiveTable;
-    /**
-     * The Logic filters
-     */
     _logic;
-    /**
-     * The visual filters
-     */
     _visual;
-    /**
-     * The old Filter Data structure
-     */
     _legacyVisual;
-    /**
-     * Constructor
-     * @param _filters the collection of filters
-     * @param datasets the collection of datasets info
-     * @param interactiveTable table of interaction properties for each section
-     */
     constructor(_filters = [], datasets = [], interactiveTable) {
         this._filters = _filters;
         this.datasets = datasets;
         this.interactiveTable = interactiveTable;
         this.setFilters(Array.isArray(_filters) ? _filters : []);
     }
-    /**
-     *
-     */
     sync() {
         this.setVisual(this.filterToVisual());
         this.setLegacyVisual(this.filterToLegacyVisual());
         this.setLogic(this.filterToLogic());
     }
-    /**
-     * Generates a visual filter structure from the filter collection.
-     * @returns a visual Filter structure
-     */
     filterToLegacyVisual() {
         return (0, filter_adapt_legacy_helpers_1.filterToLegacyVisual)(this._filters, this.datasets, this.interactiveTable);
     }
-    /**
-     * Generates a logic filters structure from the filter collection.
-     * @returns the Logic Filters
-     */
     filterToLogic() {
         return (0, filter_adapt_logic_helpers_1.filterToLogic)(this._filters);
     }
-    /**
-     * Generates a visual filter structure from the filter collection.
-     * @returns a visual Filter structure
-     */
     filterToVisual() {
         return (0, filter_adapt_helpers_1.filterToVisual)(this._filters, this.datasets, this.interactiveTable);
     }
-    /**
-     * Generates the filter collection from the legacy filter
-     * @param legacyVisual the legacy filter
-     * @param interactiveTable the interactive table object
-     * @returns the filter collection
-     */
     static legacyVisualToFilter(legacyVisual, interactiveTable) {
         const filters = (0, filter_adapt_legacy_helpers_1.legacyVisualToFilter)(legacyVisual);
         const newInteractiveTable = (0, filter_adapt_legacy_helpers_1.legacyVisualToInteractiveTable)(legacyVisual, interactiveTable);
@@ -79,88 +40,48 @@ class FilterAdapter {
             interactiveTable: newInteractiveTable,
         };
     }
-    /**
-     * Gets the legacy filter version attribute
-     * @returns the legacy filter version
-     */
     get legacyVisual() {
         return {
             filters: this._legacyVisual,
             version: filters_resources_1.FILTER_VERSION_TYPE.UI_2,
         };
     }
-    /**
-     * Gets the filter logic version
-     * @returns the filter logic version
-     */
     get logic() {
         return {
             filters: this._logic,
             version: filters_resources_1.FILTER_VERSION_TYPE.LOGIC,
         };
     }
-    /**
-     * Gets the visual filter version
-     * @returns the visual filter version
-     */
     get visual() {
         return {
             filters: this._visual,
             version: filters_resources_1.FILTER_VERSION_TYPE.UI_3,
         };
     }
-    /**
-     * Gets the filter version 3
-     * @returns the filter version 3
-     */
     get filters() {
         return {
-            filters: this._filters ?? [],
+            filters: this._filters,
             version: filters_resources_1.FILTER_VERSION_TYPE.V3,
         };
     }
-    /**
-     * Sets the datasets atribute
-     * @param datasets the collection of dataset info
-     */
     setDatasets(datasets = []) {
         this.datasets = datasets;
         this.sync();
     }
-    /**
-     * Sets the collection of filters atribute
-     * @param filters the filters
-     */
     setFilters(filters) {
         this._filters = filters;
         this.sync();
     }
-    /**
-     * Sets the table of interactive table attribute
-     * @param interactiveTable table of interaction properties for each section
-     */
     setInteractiveTable(interactiveTable) {
         this.interactiveTable = interactiveTable;
         this.sync();
     }
-    /**
-     * Sets the filter legacy visual attribute
-     * @param legacyVisual the legacy visual filters
-     */
     setLegacyVisual(legacyVisual) {
         this._legacyVisual = legacyVisual;
     }
-    /**
-     * Sets the filter logic attribute
-     * @param logic the logic filters
-     */
     setLogic(logic) {
         this._logic = logic;
     }
-    /**
-     * Sets the filter visual attribute
-     * @param visual the visual filters
-     */
     setVisual(visual) {
         this._visual = visual;
     }

package/dist/cjs/classes/FilterBuilder.js

@@ -5,58 +5,30 @@ const utils_1 = require("@qrvey/utils");
 const FilterSearcher_1 = require("./FilterSearcher");
 const FilterValidation_1 = require("./FilterValidation");
 const FilterValues_1 = require("./FilterValues");
+const filter_builder_helpers_1 = require("../helpers/filter-builder.helpers");
 const filter_settings_helpers_1 = require("../helpers/filter-settings.helpers");
 const getFilterId_1 = require("../helpers/getFilterId");
 const getFilterType_1 = require("../helpers/getFilterType");
 const filter_operators_resources_1 = require("../resources/filter-operators.resources");
 const filters_resources_1 = require("../resources/filters.resources");
-const filter_builder_helpers_1 = require("../helpers/filter-builder.helpers");
-/**
- * Class to build new filters and manipulate ones.
- */
 class FilterBuilder {
     filters;
-    /**
-     * Instance to search filters
-     */
     searchEngine;
-    /**
-     * Constructor
-     * @param filters the collection of filters
-     */
-    constructor(filters = []) {
+    constructor(filters = [], searchEngine) {
         this.filters = filters;
-        this.searchEngine = new FilterSearcher_1.FilterSearcher(filters);
+        this.searchEngine = searchEngine ?? new FilterSearcher_1.FilterSearcher(filters);
         this.filters = (0, utils_1.objectCopy)(Array.isArray(filters) ? filters : []);
+        this.searchEngine.setFilters(this.filters);
     }
-    /**
-     * **************************************************************************************************
-     ****************************************** Adding **************************************************
-     ****************************************************************************************************
-     */
-    /**
-     * Adds various filter into the collection.
-     * Inserts them next to the last similar filter
-     * @param newFilters the filter to add
-     * @param inIndexes collection of indexes to add the new filters
-     * @param settings the settings object to setup this function
-     * @returns the new collection of filters
-     */
     addMultiple(newFilters, inIndexes, settings) {
         if ((0, utils_1.isEmpty)(newFilters))
             return { resulting: this.filters };
         const filters = (0, utils_1.objectCopy)(this.filters);
         const affected = [];
-        try {
-            newFilters.forEach((newFilter, index) => {
-                const affectedFilter = this.addSingle(newFilter, inIndexes?.[index], settings);
-                affected.push(affectedFilter.affected);
-            });
-        }
-        catch (_error) {
-            this.filters = filters;
-            return { resulting: filters };
-        }
+        newFilters.forEach((newFilter, index) => {
+            const affectedFilter = this.addSingle(newFilter, inIndexes?.[index], settings);
+            affected.push(affectedFilter.affected);
+        });
         this.sync();
         return {
             resulting: this.filters,
@@ -64,17 +36,6 @@ class FilterBuilder {
             original: filters,
         };
     }
-    /**
-     * Adds one filter into the collection.
-     * - Inserts it next to the last similar filter
-     * - If the new one is match with the last similar filter, the operator will change to OR
-     * - If the id is not provided, a new one is created.
-     * - If the inIndex nunber is provided, this will be the index where the filter is inserted
-     * @param filter the filter to add
-     * @param inIndex the index to add the new filter
-     * @param settings settings object to setup this function
-     * @returns the new collection of filters
-     */
     addSingle(filter, inIndex, settings) {
         if ((0, utils_1.isEmpty)(filter))
             return { resulting: this.filters };
@@ -117,12 +78,6 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * Adds one value from filter
-     * @param id the ID to search the filter to add value
-     * @param value the value to add
-     * @returns the new filter collection
-     */
     addValue(id, value) {
         const index = this.searchEngine.findIndexByParams({ id });
         if (index < 0)
@@ -138,28 +93,15 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * Adds various values on filter
-     * @param id the ID to search the filter to add value
-     * @param values the collection of value to add
-     * @returns the new filter collection
-     */
     addValues(id, values) {
         const index = this.searchEngine.findIndexByParams({ id });
         if ((0, utils_1.isEmpty)(values) || index < 0)
             return { resulting: this.filters };
-        const filters = (0, utils_1.objectCopy)(this.filters);
         const original = (0, utils_1.objectCopy)(this.filters[index]);
         let affected;
-        try {
-            values.forEach((value) => {
-                affected = this.addValue(id, value).affected;
-            });
-        }
-        catch (_error) {
-            this.filters = filters;
-            return { resulting: filters };
-        }
+        values.forEach((value) => {
+            affected = this.addValue(id, value).affected;
+        });
         this.sync();
         return {
             resulting: this.filters,
@@ -167,17 +109,6 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * **************************************************************************************************
-     **************************************** Deleting **************************************************
-     ****************************************************************************************************
-     */
-    /**
-     * Removes various filters by params
-     * @param params params to search the filters to delete
-     * @param settings settings for this function
-     * @returns the new collection of filters
-     */
     deleteByParams(params, settings) {
         const original = (0, utils_1.objectCopy)(this.filters);
         const affected = this.searchEngine.filterByParams(params, settings);
@@ -189,26 +120,15 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * Removes various filters from the collection
-     * @param ids a collection of ID to search filters to remove
-     * @returns the new filter collection
-     */
     deleteMultiple(ids) {
         if (!Array.isArray(ids))
             return { resulting: this.filters };
         const filters = (0, utils_1.objectCopy)(this.filters);
         const affected = [];
-        try {
-            ids.forEach((id) => {
-                const deleted = this.deleteSingle(id);
-                affected.push(deleted.affected);
-            });
-        }
-        catch (_error) {
-            this.filters = filters;
-            return { resulting: filters };
-        }
+        ids.forEach((id) => {
+            const deleted = this.deleteSingle(id);
+            affected.push(deleted.affected);
+        });
         this.sync();
         return {
             resulting: this.filters,
@@ -216,11 +136,6 @@ class FilterBuilder {
             original: filters,
         };
     }
-    /**
-     * Removes one filter from the collection
-     * @param id the ID to search the filter to remove
-     * @returns the new filter collection
-     */
     deleteSingle(id) {
         const index = this.searchEngine.findIndexByParams({ id });
         const original = { ...this.filters[index] };
@@ -235,12 +150,6 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * Removes one value from filter
-     * @param id the ID to search the filter to remove value
-     * @param index the index to search the value to remove
-     * @returns the new filter collection
-     */
     deleteValue(id, index) {
         if (!Number.isInteger(index))
             return { resulting: this.filters };
@@ -259,30 +168,16 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * Removes various values from filter
-     * @param id the ID to search the filter to remove value
-     * @param indexes the index collection to search the value to remove
-     * @returns the new filter collection
-     */
     deleteValues(id, indexes) {
         if (!Array.isArray(indexes))
             return { resulting: this.filters };
-        let sortedIndex = indexes.sort();
-        sortedIndex = indexes.reverse();
-        const filters = (0, utils_1.objectCopy)(this.filters);
+        const sortedIndex = indexes.sort().reverse();
         const original = this.searchEngine.findByParams({
             id,
         });
-        try {
-            sortedIndex.forEach((index) => {
-                this.deleteValue(id, index);
-            });
-        }
-        catch (_error) {
-            this.filters = filters;
-            return { resulting: filters };
-        }
+        sortedIndex.forEach((index) => {
+            this.deleteValue(id, index);
+        });
         this.sync();
         const affected = this.searchEngine.findByParams({ id });
         return {
@@ -291,18 +186,6 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * **************************************************************************************************
-     ****************************************** Editing *************************************************
-     ****************************************************************************************************
-     */
-    /**
-     * Edits various filters from the collection
-     * @param ids the collection of IDs to search filters to edit
-     * @param filters a collection of object with properties to edit
-     * @param settings settings object for the function
-     * @returns the new filter collection
-     */
     editMultiple(ids, filters, settings) {
         if (!Array.isArray(ids) ||
             !Array.isArray(filters) ||
@@ -310,16 +193,10 @@ class FilterBuilder {
             return { resulting: this.filters };
         const originalFilters = (0, utils_1.objectCopy)(this.filters);
         const editedFilters = [];
-        try {
-            ids.forEach((id, index) => {
-                const editedFilter = this.editSingle(id, filters[index], settings);
-                editedFilters.push(editedFilter.affected);
-            });
-        }
-        catch (_error) {
-            this.filters = originalFilters;
-            return { resulting: originalFilters };
-        }
+        ids.forEach((id, index) => {
+            const editedFilter = this.editSingle(id, filters[index], settings);
+            editedFilters.push(editedFilter.affected);
+        });
         this.sync();
         return {
             resulting: this.filters,
@@ -327,13 +204,6 @@ class FilterBuilder {
             original: originalFilters,
         };
     }
-    /**
-     * Edits one filter from the collection
-     * @param id the ID to search the filter to edit
-     * @param filter an object with properties to edit
-     * @param settings settings object for the function
-     * @returns the new filter collection
-     */
     editSingle(id, filter, settings) {
         if ((0, utils_1.isEmpty)(filter))
             return { resulting: this.filters };
@@ -356,13 +226,6 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * Edits one value from filter
-     * @param id the ID to search the filter to edit value
-     * @param value the value to edit
-     * @param index the value index to edit
-     * @returns the new filter collection
-     */
     editValue(id, value, index) {
         const filterIndex = this.searchEngine.findIndexByParams({ id });
         if ((0, utils_1.isEmpty)(value) ||
@@ -380,29 +243,16 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * Edits various values from filter
-     * @param id the ID to search the filter to edit value
-     * @param values the value collection to edit
-     * @param indexes the index collection to edit
-     * @returns the new filter collection
-     */
     editValues(id, values, indexes) {
         const filterIndex = this.searchEngine.findIndexByParams({ id });
         if ((0, utils_1.isEmpty)(values) || filterIndex < 0 || !Array.isArray(indexes))
             return { resulting: this.filters };
         const original = (0, utils_1.objectCopy)(this.filters);
         let finalAffectedFilter;
-        try {
-            values.forEach((value, index) => {
-                const affectedFilter = this.editValue(id, value, indexes[index]);
-                finalAffectedFilter = affectedFilter.affected;
-            });
-        }
-        catch (_error) {
-            this.filters = original;
-            return { resulting: original };
-        }
+        values.forEach((value, index) => {
+            const affectedFilter = this.editValue(id, value, indexes[index]);
+            finalAffectedFilter = affectedFilter.affected;
+        });
         this.sync();
         return {
             resulting: this.filters,
@@ -410,17 +260,6 @@ class FilterBuilder {
             original: original[filterIndex],
         };
     }
-    /**
-     * **************************************************************************************************
-     ****************************************** Merging *************************************************
-     ****************************************************************************************************
-     */
-    /**
-     * Merge the filter into the collection by some filter parameters
-     * @param filter the filter to merge
-     * @param settings the settings object to setup this function
-     * @returns the new filter collection
-     */
     mergeSingle(filter, settings) {
         if ((0, utils_1.isEmpty)(filter))
             return { resulting: this.filters };
@@ -433,7 +272,7 @@ class FilterBuilder {
             validator: filter.validator,
         });
         let original = filter;
-        let affected = filter;
+        let affected;
         if (filterIndex > -1) {
             original = (0, utils_1.objectCopy)(this.filters[filterIndex]);
             const { affected: affectedMergeFilter } = this.mergeValues(this.filters[filterIndex].id, filter.values);
@@ -449,27 +288,15 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * Merge the filters into the collection by some filter parameters
-     * @param filters the filter collection to merge
-     * @param settings the settings object to setup this function
-     * @returns the new filter collection
-     */
     mergeMultiple(filters, settings) {
         if (!Array.isArray(filters) || (0, utils_1.isEmpty)(filters))
             return { resulting: this.filters };
         const originalFilters = (0, utils_1.objectCopy)(this.filters);
         const mergedFilters = [];
-        try {
-            filters.forEach((filter) => {
-                const mergedFilter = this.mergeSingle(filter, settings);
-                mergedFilters.push(mergedFilter.affected);
-            });
-        }
-        catch (_error) {
-            this.filters = originalFilters;
-            return { resulting: originalFilters };
-        }
+        filters.forEach((filter) => {
+            const mergedFilter = this.mergeSingle(filter, settings);
+            mergedFilters.push(mergedFilter.affected);
+        });
         this.sync();
         return {
             resulting: this.filters,
@@ -477,12 +304,6 @@ class FilterBuilder {
             original: originalFilters,
         };
     }
-    /**
-     * Merge values from filter
-     * @param id the ID to search the filter to merge values
-     * @param values the value collection to merge
-     * @returns the new filter collection
-     */
     mergeValues(id, values) {
         const filterIndex = this.searchEngine.findIndexByParams({ id });
         if ((0, utils_1.isEmpty)(values) || filterIndex < 0)
@@ -521,17 +342,6 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * **************************************************************************************************
-     ****************************************** Others **************************************************
-     ****************************************************************************************************
-     */
-    /**
-     * Builds an filter structure based on given params
-     * @param filter the partial filter params
-     * @param settings the settings object to setup this function
-     * @returns the complete filter structure
-     */
     static createFilter(filter, settings) {
         const newSettings = (0, filter_settings_helpers_1.getFilterCreateSettings)(settings);
         const newFilter = {
@@ -565,14 +375,6 @@ class FilterBuilder {
         }
         return newFilter;
     }
-    /**
-     * Sets the given filters by param
-     * - Remove the filters by the sucesfull conditions and replace the given ones
-     * @param filters the filters to set
-     * @param params params to search the filters
-     * @param settings settings for this function
-     * @returns the new collection of filters
-     */
     replaceByParams(filters, params, settings) {
         const original = (0, utils_1.objectCopy)(this.filters);
         const newSettings = (0, filter_settings_helpers_1.getReplaceByParamsSettings)(settings);
@@ -592,33 +394,12 @@ class FilterBuilder {
             original,
         };
     }
-    /**
-     * Method to sync the Filter instances
-     */
     sync() {
         this.searchEngine.setFilters(this.filters);
     }
-    /**
-     * **************************************************************************************************
-     ****************************************** Getters *************************************************
-     ****************************************************************************************************
-     */
-    /**
-     * Gets the filter collection
-     * @returns the collection of filters of the context
-     */
     getFilters() {
         return this.filters;
     }
-    /**
-     * **************************************************************************************************
-     ****************************************** Setters *************************************************
-     ****************************************************************************************************
-     */
-    /**
-     * Sets the filters
-     * @param filters the new collection of filters to set
-     */
     setFilters(filters) {
         this.filters = (0, utils_1.objectCopy)(filters);
         this.sync();