@zengrid/core 1.0.1

package/dist/src/features/filtering/filter-optimizer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Filter Optimizer using Bloom Filter
+ *
+ * Provides fast filter membership checks to skip expensive scans.
+ */
+/**
+ * FilterOptimizer - Quick filter membership tests using Bloom Filter
+ *
+ * Uses probabilistic Bloom Filter to quickly determine if a value
+ * definitely does NOT exist, avoiding expensive column scans.
+ *
+ * @example
+ * ```typescript
+ * const optimizer = new FilterOptimizer();
+ *
+ * // Index column with 1 million values
+ * optimizer.indexColumn(0, products);
+ *
+ * // Quick check before expensive scan
+ * if (!optimizer.mightContain(0, 'iPhone')) {
+ *   return []; // Definitely not in column - skip scan
+ * }
+ *
+ * // Bloom filter says it might exist - do actual scan
+ * const results = grid.scan(0, value => value.includes('iPhone'));
+ * ```
+ */
+export declare class FilterOptimizer {
+    private columnFilters;
+    private columnStats;
+    /**
+     * Index column values for quick membership tests
+     *
+     * @param col - Column index
+     * @param values - All values in the column
+     * @param falsePositiveRate - Desired false positive rate (default 0.01 = 1%)
+     */
+    indexColumn(col: number, values: any[], falsePositiveRate?: number): void;
+    /**
+     * Quick check if value might exist in column
+     *
+     * - Returns false: value definitely DOES NOT exist
+     * - Returns true: value MIGHT exist (needs actual check)
+     *
+     * @param col - Column index
+     * @param value - Value to check
+     * @returns true if value might exist, false if definitely doesn't
+     */
+    mightContain(col: number, value: string): boolean;
+    /**
+     * Check if column is indexed
+     *
+     * @param col - Column index
+     * @returns true if column has bloom filter
+     */
+    isIndexed(col: number): boolean;
+    /**
+     * Get false positive rate for a column
+     *
+     * @param col - Column index
+     * @returns Estimated false positive rate
+     */
+    getFalsePositiveRate(col: number): number | null;
+    /**
+     * Get statistics about indexed column
+     *
+     * @param col - Column index
+     */
+    getStats(col: number): {
+        uniqueValues: number;
+        falsePositiveRate: number;
+    } | null;
+    /**
+     * Clear filter for a column
+     *
+     * @param col - Column index
+     */
+    clearColumn(col: number): void;
+    /**
+     * Clear all filters
+     */
+    clearAll(): void;
+    /**
+     * Get all indexed columns
+     *
+     * @returns Array of column indices
+     */
+    getIndexedColumns(): number[];
+    /**
+     * Get memory usage estimate (in bytes)
+     *
+     * Bloom filters are very space-efficient.
+     * For 10,000 unique values with 1% false positive rate:
+     * - Optimal size: ~1.2 KB
+     *
+     * @param col - Column index
+     * @returns Estimated memory usage in bytes
+     */
+    getMemoryUsage(col: number): number | null;
+}
+//# sourceMappingURL=filter-optimizer.d.ts.map

package/dist/src/features/filtering/filter-optimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-optimizer.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/features/filtering/filter-optimizer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,aAAa,CAAuC;IAC5D,OAAO,CAAC,WAAW,CAA+E;IAElG;;;;;;OAMG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,iBAAiB,GAAE,MAAa,GAAG,IAAI;IAsB/E;;;;;;;;;OASG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAKjD;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI/B;;;;;OAKG;IACH,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKhD;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,GAAG,IAAI;IAIR;;;;OAIG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK9B;;OAEG;IACH,QAAQ,IAAI,IAAI;IAKhB;;;;OAIG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAI7B;;;;;;;;;OASG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAW3C"}

package/dist/src/features/filtering/filter-query-parser.d.ts

@@ -0,0 +1,69 @@
+import type { FilterQuery, FilterExpression, FilterModel } from '../../types';
+/**
+ * FilterQueryParser - Parses SQL-like filter queries
+ *
+ * Converts SQL-like syntax to FilterExpression for both backend and frontend use
+ *
+ * Supported operators:
+ * - Comparison: =, !=, <, >, <=, >=
+ * - String: LIKE, NOT LIKE
+ * - Range: BETWEEN, NOT BETWEEN
+ * - List: IN, NOT IN
+ * - Null: IS NULL, IS NOT NULL
+ * - Logic: AND, OR, NOT, ( )
+ *
+ * @example
+ * ```typescript
+ * const parser = new FilterQueryParser();
+ *
+ * // Simple query
+ * parser.parse({ sql: "age > 18" });
+ *
+ * // Parameterized query (recommended)
+ * parser.parse({
+ *   sql: "age > :minAge AND status = :status",
+ *   params: { minAge: 18, status: 'active' }
+ * });
+ *
+ * // Complex query
+ * parser.parse({
+ *   sql: "age BETWEEN :min AND :max AND (name LIKE :search OR email LIKE :search)",
+ *   params: { min: 18, max: 65, search: '%john%' }
+ * });
+ * ```
+ */
+export declare class FilterQueryParser {
+    /**
+     * Set column name to index mapping
+     * Required for converting SQL field names to column indices
+     */
+    setColumnMapping(_mapping: Record<string, number>): void;
+    /**
+     * Parse SQL-like filter query into FilterExpression
+     */
+    parse(query: FilterQuery): FilterExpression;
+    /**
+     * Bind named parameters (:paramName) to their values
+     * Converts to positional placeholders (?)
+     */
+    private bindNamedParameters;
+    /**
+     * Extract positional parameters from SQL
+     * Converts literal values to ? placeholders
+     */
+    private extractPositionalParameters;
+    /**
+     * Check if a value is part of a SQL keyword
+     */
+    private isPartOfKeyword;
+    /**
+     * Convert SQL query to FilterModels (for frontend filtering)
+     * This is a simplified conversion - complex queries may not convert perfectly
+     */
+    parseToModels(query: FilterQuery, columnNames: string[]): FilterModel[];
+    /**
+     * Convert SQL operator to FilterOperator
+     */
+    private sqlOperatorToFilterOperator;
+}
+//# sourceMappingURL=filter-query-parser.d.ts.map

package/dist/src/features/filtering/filter-query-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-query-parser.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/features/filtering/filter-query-parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAkB,MAAM,aAAa,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,iBAAiB;IAI5B;;;OAGG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAKxD;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,gBAAgB;IAoB3C;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAyBnC;;OAEG;IACH,OAAO,CAAC,eAAe;IAKvB;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE;IAYvE;;OAEG;IACH,OAAO,CAAC,2BAA2B;CAepC"}

package/dist/src/features/filtering/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Filtering system for ZenGrid
+ */
+export { FilterCompiler } from './filter-compiler';
+export type { FilterPredicate } from './filter-compiler';
+export { ColumnFilter } from './column-filter';
+export type { ColumnFilterOptions } from './column-filter';
+export { FilterManager } from './filter-manager';
+export type { FilterManagerOptions } from './filter-manager';
+export { FilterAutocomplete } from './filter-autocomplete';
+export { FilterOptimizer } from './filter-optimizer';
+export { SubstringFilter } from './substring-filter';
+export { FilterCache } from './filter-cache';
+export { FilterIndexManager } from './filter-index-manager';
+export { RangeFilterOptimizer } from './range-filter-optimizer';
+export type { StandardFilterOperator, CustomOperator, FieldFilterCondition, FieldFilterGroup, FieldFilterState, } from './types';
+export { FilterExportManager } from './filter-export-manager';
+export type { FilterExportManagerOptions } from './filter-export-manager';
+export * from './adapters';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/features/filtering/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/features/filtering/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGhE,YAAY,EACV,sBAAsB,EACtB,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAG1E,cAAc,YAAY,CAAC"}

package/dist/src/features/filtering/range-filter-optimizer.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Range Filter Optimizer using Segment Tree
+ *
+ * Provides O(log n) range queries for BETWEEN, MIN, MAX operations
+ * instead of O(n) linear scans.
+ */
+/**
+ * Range query result
+ */
+interface RangeQueryResult {
+    /** Matching row indices */
+    rows: number[];
+    /** Statistics */
+    stats: {
+        min: number;
+        max: number;
+        sum: number;
+        avg: number;
+        count: number;
+    };
+}
+/**
+ * RangeFilterOptimizer - Fast range queries with Segment Tree
+ *
+ * Optimizes BETWEEN, MIN, MAX queries using segment trees.
+ * Provides O(log n) queries instead of O(n) scans.
+ *
+ * @example
+ * ```typescript
+ * const optimizer = new RangeFilterOptimizer();
+ *
+ * // Index column with numeric values
+ * optimizer.indexColumn(0, values);
+ *
+ * // Query: price BETWEEN 100 AND 500
+ * const result = optimizer.queryRange(0, 100, 500);
+ * // O(log n) instead of O(n)
+ * ```
+ */
+export declare class RangeFilterOptimizer {
+    private columnIndexes;
+    /**
+     * Index a numeric column for range queries
+     *
+     * @param col - Column index
+     * @param values - Array of numeric values (one per row)
+     */
+    indexColumn(col: number, values: number[]): void;
+    /**
+     * Query rows within a range (BETWEEN operator)
+     *
+     * @param col - Column index
+     * @param min - Minimum value (inclusive)
+     * @param max - Maximum value (inclusive)
+     * @returns Query result with matching rows and statistics
+     */
+    queryRange(col: number, min: number, max: number): RangeQueryResult | null;
+    /**
+     * Get MIN value in a range of rows
+     *
+     * @param col - Column index
+     * @param startRow - Start row index
+     * @param endRow - End row index
+     * @returns Minimum value in range
+     */
+    getMin(col: number, startRow: number, endRow: number): number | null;
+    /**
+     * Get MAX value in a range of rows
+     *
+     * @param col - Column index
+     * @param startRow - Start row index
+     * @param endRow - End row index
+     * @returns Maximum value in range
+     */
+    getMax(col: number, startRow: number, endRow: number): number | null;
+    /**
+     * Get SUM of values in a range of rows
+     *
+     * @param col - Column index
+     * @param startRow - Start row index
+     * @param endRow - End row index
+     * @returns Sum of values in range
+     */
+    getSum(col: number, startRow: number, endRow: number): number | null;
+    /**
+     * Update a single value in the index
+     *
+     * @param col - Column index
+     * @param row - Row index
+     * @param value - New value
+     */
+    update(col: number, row: number, value: number): void;
+    /**
+     * Rebuild sorted indices after multiple updates
+     *
+     * @param col - Column index
+     */
+    rebuildSortedIndices(col: number): void;
+    /**
+     * Check if column is indexed
+     *
+     * @param col - Column index
+     * @returns true if column has range index
+     */
+    isIndexed(col: number): boolean;
+    /**
+     * Clear index for a column
+     *
+     * @param col - Column index
+     */
+    clearColumn(col: number): void;
+    /**
+     * Clear all indexes
+     */
+    clearAll(): void;
+    /**
+     * Get statistics about indexed columns
+     */
+    getStats(): {
+        indexedColumns: number;
+        totalValues: number;
+        memoryEstimateMB: number;
+    };
+    /**
+     * Binary search for leftmost position where value >= target
+     */
+    private binarySearchLeft;
+    /**
+     * Binary search for rightmost position where value <= target
+     */
+    private binarySearchRight;
+    /**
+     * Calculate statistics for matching rows
+     */
+    private calculateRangeStats;
+}
+export {};
+//# sourceMappingURL=range-filter-optimizer.d.ts.map

package/dist/src/features/filtering/range-filter-optimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"range-filter-optimizer.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/features/filtering/range-filter-optimizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA8BH;;GAEG;AACH,UAAU,gBAAgB;IACxB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf,iBAAiB;IACjB,KAAK,EAAE;QACL,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,aAAa,CAA2C;IAEhE;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAyChD;;;;;;;OAOG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAmC1E;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOpE;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOpE;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOpE;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAiBrD;;;;OAIG;IACH,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAUvC;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI/B;;;;OAIG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI9B;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACH,QAAQ,IAAI;QACV,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;KAC1B;IAoBD;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAwBxB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAwBzB;;OAEG;IACH,OAAO,CAAC,mBAAmB;CA2B5B"}

package/dist/src/features/filtering/substring-filter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Substring Filter using Suffix Array
+ *
+ * Provides fast substring search ("contains") filtering for grid columns.
+ */
+/**
+ * SubstringFilter - Fast substring search using Suffix Array
+ *
+ * Indexes column values for O(m log n) substring search instead of O(n*m) linear scan.
+ *
+ * @example
+ * ```typescript
+ * const filter = new SubstringFilter();
+ *
+ * // Index column 0 with product names
+ * filter.indexColumn(0, [
+ *   'Apple iPhone 14',
+ *   'Samsung Galaxy S23',
+ *   'Microsoft Surface Pro'
+ * ]);
+ *
+ * // Find all rows containing "phone" (matches "iPhone")
+ * const rows = filter.filterBySubstring(0, 'phone');
+ * // [0] - Row 0 contains "phone" in "iPhone"
+ * ```
+ */
+export declare class SubstringFilter {
+    private columnIndexes;
+    private columnMaps;
+    /**
+     * Index all values in a column for substring search
+     *
+     * @param col - Column index
+     * @param values - All values in the column
+     */
+    indexColumn(col: number, values: any[]): void;
+    /**
+     * Find all rows where column value contains the substring
+     *
+     * @param col - Column index
+     * @param substring - Substring to search for
+     * @returns Array of row indices that match
+     */
+    filterBySubstring(col: number, substring: string): number[];
+    /**
+     * Check if any row in the column contains the substring
+     *
+     * @param col - Column index
+     * @param substring - Substring to check
+     * @returns true if at least one row contains the substring
+     */
+    contains(col: number, substring: string): boolean;
+    /**
+     * Count how many rows contain the substring
+     *
+     * @param col - Column index
+     * @param substring - Substring to count
+     * @returns Number of rows containing the substring
+     */
+    count(col: number, substring: string): number;
+    /**
+     * Get statistics for a column index
+     *
+     * @param col - Column index
+     * @returns Statistics or null if not indexed
+     */
+    getStats(col: number): {
+        rowCount: number;
+        totalChars: number;
+        textLength: number;
+        suffixCount: number;
+        memoryBytes: number;
+        hasLCP: boolean;
+    } | null;
+    /**
+     * Clear index for a column
+     *
+     * @param col - Column index
+     */
+    clearColumn(col: number): void;
+    /**
+     * Clear all indexes
+     */
+    clearAll(): void;
+    /**
+     * Binary search to find which row a position belongs to
+     */
+    private findRowIndex;
+}
+//# sourceMappingURL=substring-filter.d.ts.map

package/dist/src/features/filtering/substring-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"substring-filter.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/features/filtering/substring-filter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,aAAa,CAAuC;IAC5D,OAAO,CAAC,UAAU,CAAuC;IAEzD;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI;IAiC7C;;;;;;OAMG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IAyB3D;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAKjD;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAI7C;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM;;;;;;;;IAapB;;;;OAIG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAM9B;;OAEG;IACH,QAAQ,IAAI,IAAI;IAQhB;;OAEG;IACH,OAAO,CAAC,YAAY;CAoBrB"}

package/dist/src/features/filtering/types.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Field-Based Filter Types
+ *
+ * This module defines a new field-based filtering system that uses
+ * field names instead of column indices, making it easier for backends
+ * to consume filter parameters without complex mapping logic.
+ */
+/**
+ * Standard filter operators
+ * Short, backend-friendly identifiers that map to common database operations
+ */
+export type StandardFilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'in' | 'notIn' | 'between' | 'isNull' | 'isNotNull' | 'regex';
+/**
+ * Custom operator definition
+ * Allows registration of domain-specific operators
+ *
+ * @example
+ * ```typescript
+ * const fuzzyOperator: CustomOperator = {
+ *   id: 'fuzzy',
+ *   label: 'Fuzzy Match',
+ *   valueCount: 1,
+ *   predicate: (cellValue, filterValue) => {
+ *     return levenshtein(cellValue, filterValue) < 3;
+ *   },
+ *   sqlTemplate: "SIMILARITY(?, ?) > 0.7",
+ *   graphqlKey: '_similar',
+ *   restSuffix: '_fuzzy'
+ * };
+ * ```
+ */
+export interface CustomOperator {
+    /**
+     * Unique operator identifier
+     */
+    id: string;
+    /**
+     * Human-readable label for UI
+     */
+    label: string;
+    /**
+     * Number of values required
+     * - 0: no values (e.g., isNull)
+     * - 1: single value (e.g., equals, contains)
+     * - 2: two values (e.g., between)
+     * - 'array': array of values (e.g., in)
+     */
+    valueCount: 0 | 1 | 2 | 'array';
+    /**
+     * Frontend predicate function for filtering rows
+     * @param cellValue - The value from the cell
+     * @param filterValue - The filter value(s)
+     * @returns true if row matches filter
+     */
+    predicate: (cellValue: any, filterValue: any) => boolean;
+    /**
+     * SQL template for backend queries
+     * Use ? for value placeholders
+     * @example "SIMILARITY(?, ?) > 0.7"
+     */
+    sqlTemplate: string;
+    /**
+     * GraphQL key for the operator
+     * @example "_similar" for Hasura, "similar" for Prisma
+     */
+    graphqlKey?: string;
+    /**
+     * REST suffix for query params
+     * @example "_fuzzy" results in "name_fuzzy=value"
+     */
+    restSuffix?: string;
+}
+/**
+ * Field-based filter condition
+ *
+ * This is the NEW format sent to backends, using field names
+ * instead of column indices.
+ *
+ * @example
+ * ```typescript
+ * // Simple condition
+ * { field: 'age', operator: 'gt', value: 18 }
+ *
+ * // Between condition
+ * { field: 'price', operator: 'between', value: 100, valueTo: 500 }
+ *
+ * // In condition
+ * { field: 'status', operator: 'in', value: ['active', 'pending'] }
+ *
+ * // Null check
+ * { field: 'deletedAt', operator: 'isNull' }
+ * ```
+ */
+export interface FieldFilterCondition {
+    /**
+     * Field name from ColumnDef.field
+     */
+    field: string;
+    /**
+     * Filter operator
+     */
+    operator: StandardFilterOperator | string;
+    /**
+     * Filter value
+     * - undefined for isNull/isNotNull
+     * - single value for most operators
+     * - array for 'in'/'notIn'
+     */
+    value?: any;
+    /**
+     * Secondary value for 'between' operator
+     */
+    valueTo?: any;
+}
+/**
+ * Filter group with logic operator
+ *
+ * Allows combining multiple conditions with AND/OR logic
+ * and supports nesting for complex queries.
+ *
+ * @example
+ * ```typescript
+ * // Simple AND group
+ * {
+ *   logic: 'AND',
+ *   conditions: [
+ *     { field: 'age', operator: 'gt', value: 18 },
+ *     { field: 'status', operator: 'eq', value: 'active' }
+ *   ]
+ * }
+ *
+ * // Nested groups: (age > 18 AND status = 'active') OR (role = 'admin')
+ * {
+ *   logic: 'OR',
+ *   groups: [
+ *     {
+ *       logic: 'AND',
+ *       conditions: [
+ *         { field: 'age', operator: 'gt', value: 18 },
+ *         { field: 'status', operator: 'eq', value: 'active' }
+ *       ]
+ *     },
+ *     {
+ *       logic: 'AND',
+ *       conditions: [
+ *         { field: 'role', operator: 'eq', value: 'admin' }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+export interface FieldFilterGroup {
+    /**
+     * Logic operator between conditions/groups
+     */
+    logic: 'AND' | 'OR';
+    /**
+     * Filter conditions in this group
+     */
+    conditions: FieldFilterCondition[];
+    /**
+     * Nested filter groups for complex queries
+     */
+    groups?: FieldFilterGroup[];
+}
+/**
+ * Complete filter state in field-based format
+ *
+ * This is the top-level filter state that gets exported to backends.
+ *
+ * @example
+ * ```typescript
+ * const filterState: FieldFilterState = {
+ *   root: {
+ *     logic: 'AND',
+ *     conditions: [
+ *       { field: 'age', operator: 'gt', value: 18 },
+ *       { field: 'status', operator: 'eq', value: 'active' }
+ *     ]
+ *   },
+ *   activeFields: ['age', 'status'],
+ *   timestamp: Date.now()
+ * };
+ * ```
+ */
+export interface FieldFilterState {
+    /**
+     * Root filter group
+     * null if no filters are active
+     */
+    root: FieldFilterGroup | null;
+    /**
+     * Quick access to all active field names
+     * Useful for UI highlighting
+     */
+    activeFields: string[];
+    /**
+     * Timestamp of last filter change
+     * Useful for caching and tracking updates
+     */
+    timestamp: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/features/filtering/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../packages/core/src/features/filtering/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAE9B,IAAI,GACJ,KAAK,GAGL,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GAGL,UAAU,GACV,aAAa,GACb,YAAY,GACZ,UAAU,GAGV,IAAI,GACJ,OAAO,GACP,SAAS,GAGT,QAAQ,GACR,WAAW,GAGX,OAAO,CAAC;AAEZ;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,UAAU,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;IAEhC;;;;;OAKG;IACH,SAAS,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,KAAK,OAAO,CAAC;IAEzD;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAAC;IAE1C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,GAAG,CAAC;IAEZ;;OAEG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB;;OAEG;IACH,UAAU,EAAE,oBAAoB,EAAE,CAAC;IAEnC;;OAEG;IACH,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAE9B;;;OAGG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB"}