feat: Migrate to modern FilterCondition syntax in types and core

Copilot · hotlong · Copilot · commit cdd675e39f3d · 2026-01-22T11:45:36.000Z
- Replace FilterExpression array syntax with FilterCondition object syntax
- Update UnifiedQuery to use Filter (FilterCondition) type
- Implement filter translation from new object syntax to legacy array format
- Update all API types to use new Filter type
- Add operator mapping: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $contains, etc.

Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/packages/drivers/sdk/src/index.ts b/packages/drivers/sdk/src/index.ts
@@ -48,7 +48,7 @@ import {
     MetadataApiResponse,
     ObjectQLError,
     ApiErrorCode,
-    FilterExpression
+    Filter
 } from '@objectql/types';
 
 /**
@@ -391,7 +391,7 @@ export class DataApiClient implements IDataApiClient {
         );
     }
 
-    async count(objectName: string, filters?: FilterExpression): Promise<DataApiCountResponse> {
+    async count(objectName: string, filters?: Filter): Promise<DataApiCountResponse> {
         return this.request<DataApiCountResponse>(
             'GET',
             `${this.dataPath}/${objectName}`,
diff --git a/packages/foundation/core/src/repository.ts b/packages/foundation/core/src/repository.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ObjectQLContext, IObjectQL, ObjectConfig, Driver, UnifiedQuery, ActionContext, HookAPI, RetrievalHookContext, MutationHookContext, UpdateHookContext, ValidationContext, ValidationError, ValidationRuleResult, FormulaContext, FilterExpression } from '@objectql/types';
+import { ObjectQLContext, IObjectQL, ObjectConfig, Driver, UnifiedQuery, ActionContext, HookAPI, RetrievalHookContext, MutationHookContext, UpdateHookContext, ValidationContext, ValidationError, ValidationRuleResult, FormulaContext, Filter } from '@objectql/types';
 import type { ObjectStackKernel } from '@objectstack/runtime';
 import type { QueryAST, FilterNode, SortNode } from '@objectstack/spec';
 import { Validator } from './validator';
@@ -43,16 +43,119 @@ export class ObjectRepository {
     }
 
     /**
-     * Translates ObjectQL FilterExpression to ObjectStack FilterNode format
+     * Translates ObjectQL Filter (FilterCondition) to ObjectStack FilterNode format
+     * 
+     * Converts modern object-based syntax to legacy array-based syntax:
+     * Input:  { age: { $gte: 18 }, $or: [{ status: "active" }, { role: "admin" }] }
+     * Output: [["age", ">=", 18], "or", [["status", "=", "active"], "or", ["role", "=", "admin"]]]
      */
-    private translateFilters(filters?: FilterExpression[]): FilterNode | undefined {
-        if (!filters || filters.length === 0) {
+    private translateFilters(filters?: Filter): FilterNode | undefined {
+        if (!filters || Object.keys(filters).length === 0) {
             return undefined;
         }
 
-        // FilterExpression[] is already compatible with FilterNode format
-        // Just pass through as-is
-        return filters as FilterNode;
+        return this.convertFilterToNode(filters);
+    }
+
+    /**
+     * Recursively converts FilterCondition to FilterNode array format
+     */
+    private convertFilterToNode(filter: Filter): FilterNode {
+        const nodes: any[] = [];
+        
+        // Process logical operators first
+        if (filter.$and) {
+            const andNodes = filter.$and.map(f => this.convertFilterToNode(f));
+            nodes.push(...this.interleaveWithOperator(andNodes, 'and'));
+        }
+        
+        if (filter.$or) {
+            const orNodes = filter.$or.map(f => this.convertFilterToNode(f));
+            if (nodes.length > 0) {
+                nodes.push('and');
+            }
+            nodes.push(...this.interleaveWithOperator(orNodes, 'or'));
+        }
+        
+        if (filter.$not) {
+            // NOT operator: convert to array of negated conditions
+            // This is a simplification - proper implementation would need driver support
+            const notNode = this.convertFilterToNode(filter.$not);
+            if (nodes.length > 0) {
+                nodes.push('and');
+            }
+            // Wrap in array to indicate it's a NOT group
+            nodes.push(['not', notNode]);
+        }
+        
+        // Process field conditions
+        for (const [field, value] of Object.entries(filter)) {
+            if (field.startsWith('$')) {
+                continue; // Skip logical operators (already processed)
+            }
+            
+            if (nodes.length > 0) {
+                nodes.push('and');
+            }
+            
+            // Handle field value
+            if (value === null || value === undefined) {
+                nodes.push([field, '=', value]);
+            } else if (typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
+                // Explicit operators
+                for (const [op, opValue] of Object.entries(value)) {
+                    if (nodes.length > 0 && nodes[nodes.length - 1] !== 'and') {
+                        nodes.push('and');
+                    }
+                    
+                    const legacyOp = this.mapOperatorToLegacy(op);
+                    nodes.push([field, legacyOp, opValue]);
+                }
+            } else {
+                // Implicit equality
+                nodes.push([field, '=', value]);
+            }
+        }
+        
+        return nodes.length === 1 ? nodes[0] : nodes;
+    }
+    
+    /**
+     * Interleaves filter nodes with a logical operator
+     */
+    private interleaveWithOperator(nodes: FilterNode[], operator: string): any[] {
+        if (nodes.length === 0) return [];
+        if (nodes.length === 1) return [nodes[0]];
+        
+        const result: any[] = [nodes[0]];
+        for (let i = 1; i < nodes.length; i++) {
+            result.push(operator, nodes[i]);
+        }
+        return result;
+    }
+    
+    /**
+     * Maps modern $-prefixed operators to legacy format
+     */
+    private mapOperatorToLegacy(operator: string): string {
+        const mapping: Record<string, string> = {
+            '$eq': '=',
+            '$ne': '!=',
+            '$gt': '>',
+            '$gte': '>=',
+            '$lt': '<',
+            '$lte': '<=',
+            '$in': 'in',
+            '$nin': 'nin',
+            '$contains': 'contains',
+            '$startsWith': 'startswith',
+            '$endsWith': 'endswith',
+            '$null': 'is_null',
+            '$exist': 'is_not_null',
+            '$between': 'between',
+        };
+        
+        return mapping[operator] || operator.replace('$', '');
     }
 
     /**
diff --git a/packages/foundation/types/src/api.ts b/packages/foundation/types/src/api.ts
@@ -13,7 +13,7 @@
  * These types enable frontend applications to make type-safe API calls.
  */
 
-import { UnifiedQuery, FilterExpression } from './query';
+import { UnifiedQuery, Filter } from './query';
 import { ObjectConfig } from './object';
 import { FieldConfig } from './field';
 import { ActionConfig } from './action';
@@ -142,8 +142,8 @@ export interface DataApiItemResponse<T = unknown> extends DataApiResponse<T> {
  * Query parameters for GET /api/data/:object (list records)
  */
 export interface DataApiListParams {
-    /** Filter expression (can be FilterExpression array or JSON string) */
-    filter?: FilterExpression | string;
+    /** Filter expression (can be Filter object or JSON string) */
+    filter?: Filter | string;
     /** Fields to return (array or comma-separated string) */
     fields?: string[] | string;
     /** Sort criteria - array of [field, direction] tuples */
@@ -184,7 +184,7 @@ export interface DataApiUpdateRequest {
  */
 export interface DataApiBulkUpdateRequest {
     /** Filter criteria to select records to update */
-    filters: FilterExpression;
+    filters: Filter;
     /** Data to update */
     data: Record<string, unknown>;
 }
@@ -194,7 +194,7 @@ export interface DataApiBulkUpdateRequest {
  */
 export interface DataApiBulkDeleteRequest {
     /** Filter criteria to select records to delete */
-    filters: FilterExpression;
+    filters: Filter;
 }
 
 /**
@@ -461,7 +461,7 @@ export interface IDataApiClient {
      * @param objectName - Name of the object
      * @param filters - Filter criteria
      */
-    count(objectName: string, filters?: FilterExpression): Promise<DataApiCountResponse>;
+    count(objectName: string, filters?: Filter): Promise<DataApiCountResponse>;
 }
 
 /**
diff --git a/packages/foundation/types/src/query.ts b/packages/foundation/types/src/query.ts
@@ -6,8 +6,21 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export type FilterCriterion = [string, string, any];
-export type FilterExpression = FilterCriterion | 'and' | 'or' | FilterExpression[];
+import type { FilterCondition } from '@objectstack/spec';
+
+/**
+ * Modern Query Filter using @objectstack/spec FilterCondition
+ * 
+ * Supports MongoDB/Prisma-style object-based syntax:
+ * - Implicit equality: { field: value }
+ * - Explicit operators: { field: { $eq: value, $gt: 10 } }
+ * - Logical operators: { $and: [...], $or: [...], $not: {...} }
+ * - String operators: { name: { $contains: "text" } }
+ * - Range operators: { age: { $between: [18, 65] } }
+ * - Set operators: { status: { $in: ["active", "pending"] } }
+ * - Null checks: { field: { $null: true } }
+ */
+export type Filter = FilterCondition;
 
 export type AggregateFunction = 'count' | 'sum' | 'avg' | 'min' | 'max';
 
@@ -17,15 +30,33 @@ export interface AggregateOption {
     alias?: string; // Optional: rename the result field
 }
 
+/**
+ * Unified Query Interface
+ * 
+ * Provides a consistent query API across all ObjectQL drivers.
+ */
 export interface UnifiedQuery {
+    /** Field selection - specify which fields to return */
     fields?: string[];
-    filters?: FilterExpression[];
+    
+    /** Filter conditions using modern FilterCondition syntax */
+    filters?: Filter;
+    
+    /** Sort order - array of [field, direction] tuples */
     sort?: [string, 'asc' | 'desc'][];
+    
+    /** Pagination - number of records to skip */
     skip?: number;
+    
+    /** Pagination - maximum number of records to return */
     limit?: number;
+    
+    /** Relation expansion - load related records */
     expand?: Record<string, UnifiedQuery>;
     
-    // === Aggregation Support ===
+    /** Aggregation - group by fields */
     groupBy?: string[];
+    
+    /** Aggregation - aggregate functions to apply */
     aggregate?: AggregateOption[];
 }
