json-rest-api 1.0.6 → 1.0.8

package/plugins/core/lib/{knex-query-helpers.js → querying/knex-query-helpers.js}

@@ -1,56 +1,28 @@
 /**
- * @module knex-query-helpers
- * @description Knex query filter hooks for complex SQL query building
- * 
- * This module contains three separate hooks for filtering queries:
- * 1. polymorphicFiltersHook - Handles polymorphic relationship filters
- * 2. crossTableFiltersHook - Handles filters requiring JOINs
- * 3. basicFiltersHook - Handles basic filters on the main table
- * 
- * These hooks are designed to run in this specific order to ensure
- * proper field qualification when JOINs are present. They implement
- * sophisticated query building patterns to handle complex filtering
- * scenarios while maintaining SQL injection safety and performance.
- * 
- * Why this is useful upstream:
- * - Enables filtering on polymorphic relationships (e.g., find all comments on posts by John)
- * - Supports cross-table filtering without N+1 queries
- * - Automatically adds JOINs based on filter requirements
- * - Handles field qualification to prevent ambiguous column errors
- * - Provides extensible hook system for custom filter logic
- * - Maintains SQL injection safety through parameterized queries
- */
-
-/**
- * Hook 1: Polymorphic Filters Hook
- * 
- * Processes filters that target polymorphic relationships, where a single
- * relationship can point to different types of resources. This hook adds
- * conditional JOINs for each possible type and applies OR conditions to
- * search across all of them. Must run first to establish JOINs before
- * other hooks process their filters.
+ * Processes filters that target polymorphic relationships where a single relationship can point to different types of resources
  * 
  * @param {Object} hookParams - Hook parameters containing context
  * @param {Object} dependencies - Dependencies injected by the plugin
  * 
- * @example <caption>Polymorphic filter in searchSchema</caption>
- * // Find comments where the commentable item has 'JavaScript' in the title
- * searchSchema: {
+ * @example
+ * // Input: Search schema with polymorphic filter
+ * const searchSchema = {
  *   commentable_title: {
  *     type: 'string',
- *     polymorphicField: 'commentable',  // The polymorphic relationship
+ *     polymorphicField: 'commentable',  // Points to the polymorphic relationship
  *     targetFields: {
  *       posts: 'title',      // When commentable_type='posts', search posts.title
- *       videos: 'title',     // When commentable_type='videos', search videos.title
+ *       videos: 'title',     // When commentable_type='videos', search videos.title  
  *       articles: 'headline' // When commentable_type='articles', search articles.headline
  *     },
- *     filterUsing: 'like'
+ *     filterOperator: 'like'
  *   }
- * }
+ * };
  * 
- * @example <caption>Generated SQL for polymorphic search</caption>
- * // For filter: { commentable_title: 'JavaScript' }
- * // Generates:
+ * // Filter request: { commentable_title: 'JavaScript' }
+ * 
+ * // Result: Adds conditional LEFT JOINs and WHERE conditions
+ * // SQL generated:
  * // LEFT JOIN posts ON comments.commentable_type = 'posts' AND comments.commentable_id = posts.id
  * // LEFT JOIN videos ON comments.commentable_type = 'videos' AND comments.commentable_id = videos.id
  * // LEFT JOIN articles ON comments.commentable_type = 'articles' AND comments.commentable_id = articles.id
@@ -60,13 +32,44 @@
  * //   (comments.commentable_type = 'articles' AND articles.headline LIKE '%JavaScript%')
  * // )
  * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API Knex plugin uses this to:
- * // 1. Enable filtering on polymorphic relationships without knowing the type
- * // 2. Search across multiple tables with a single filter parameter
- * // 3. Support complex queries like "find all comments on content by John"
- * // 4. Handle conditional JOINs that only match when type is correct
- * // 5. Maintain query performance by using indexed type/id columns
+ * @example
+ * // Input: Complex polymorphic filter with cross-table paths
+ * const searchSchema = {
+ *   commentable_author: {
+ *     type: 'string',
+ *     polymorphicField: 'commentable',
+ *     targetFields: {
+ *       posts: 'author.name',     // Search post author's name
+ *       videos: 'creator.name'    // Search video creator's name
+ *     }
+ *   }
+ * };
+ * 
+ * // Result: Creates nested JOINs for each polymorphic type
+ * // LEFT JOIN posts ON comments.commentable_type = 'posts' AND comments.commentable_id = posts.id
+ * // LEFT JOIN users AS posts_author ON posts.author_id = posts_author.id
+ * // LEFT JOIN videos ON comments.commentable_type = 'videos' AND comments.commentable_id = videos.id
+ * // LEFT JOIN users AS videos_creator ON videos.creator_id = videos_creator.id
+ * 
+ * @description
+ * Used by:
+ * - rest-api-knex-plugin calls this hook first during query building
+ * - Must run before other filter hooks to establish JOINs
+ * - Applied when searchSchema contains polymorphicField definitions
+ * 
+ * Purpose:
+ * - Enables filtering on polymorphic relationships without knowing the concrete type
+ * - Searches across multiple tables with a single filter parameter
+ * - Supports queries like "find all comments on content containing 'JavaScript'"
+ * - Uses conditional JOINs that only match when type field equals expected value
+ * - Maintains performance by leveraging indexed type/id columns
+ * 
+ * Data flow:
+ * 1. Identifies filters with polymorphicField in searchSchema
+ * 2. For each polymorphic type, adds conditional LEFT JOIN
+ * 3. Builds OR conditions checking type field and target field together
+ * 4. Sets hasJoins flag for subsequent hooks
+ * 5. Returns modified query with polymorphic search capabilities
  */
 export const polymorphicFiltersHook = async (hookParams, dependencies) => {
   const { log, scopes, knex } = dependencies;
@@ -263,7 +266,7 @@ export const polymorphicFiltersHook = async (hookParams, dependencies) => {
                 finalAlias = `${finalAlias}_${pathParts[i]}`;
               }
 
-              const operator = searchInfo.fieldDef.filterUsing || '=';
+              const operator = searchInfo.fieldDef.filterOperator || '=';
               if (operator === 'like') {
                 this.where(`${finalAlias}.${fieldName}`, 'like', `%${searchInfo.filterValue}%`);
               } else {
@@ -271,7 +274,7 @@ export const polymorphicFiltersHook = async (hookParams, dependencies) => {
               }
             } else {
               // Direct field
-              const operator = searchInfo.fieldDef.filterUsing || '=';
+              const operator = searchInfo.fieldDef.filterOperator || '=';
               if (operator === 'like') {
                 this.where(`${baseAlias}.${targetFieldPath}`, 'like', `%${searchInfo.filterValue}%`);
               } else {
@@ -286,66 +289,96 @@ export const polymorphicFiltersHook = async (hookParams, dependencies) => {
 };
 
 /**
- * Hook 2: Cross-Table Filters Hook
- * 
- * Processes filters that require JOINs to access fields in related tables.
- * This hook handles dot-notation field paths (e.g., 'author.name') by building
- * the necessary JOIN chain and applying filters on the joined tables. It also
- * handles DISTINCT when one-to-many JOINs are detected to prevent duplicate results.
- * Must run after polymorphic but before basic to ensure hasJoins flag is set.
+ * Processes filters that require JOINs to access fields in related tables using dot notation
  * 
  * @param {Object} hookParams - Hook parameters containing context
  * @param {Object} dependencies - Dependencies injected by the plugin
  * 
- * @example <caption>Cross-table filter with actualField</caption>
- * // Find articles where the author's name contains 'Smith'
- * searchSchema: {
+ * @example
+ * // Input: Simple cross-table filter
+ * const searchSchema = {
  *   author_name: {
  *     type: 'string',
- *     actualField: 'author.name',  // Dot notation for cross-table access
- *     filterUsing: 'like'
+ *     actualField: 'author.name',  // Dot notation indicates JOIN needed
+ *     filterOperator: 'like'
  *   }
- * }
- * // Generates:
+ * };
+ * 
+ * // Filter request: { author_name: 'Smith' }
+ * // Query before: SELECT * FROM articles
+ * 
+ * // Result: Adds JOIN and qualified WHERE
+ * // Query after:
+ * // SELECT * FROM articles
  * // LEFT JOIN users AS articles_author ON articles.author_id = articles_author.id
  * // WHERE articles_author.name LIKE '%Smith%'
  * 
- * @example <caption>Multi-field search across tables with likeOneOf</caption>
- * searchSchema: {
+ * @example
+ * // Input: Multi-field search across tables
+ * const searchSchema = {
  *   search: {
  *     type: 'string',
- *     likeOneOf: [
- *       'title',           // Search in articles.title
- *       'content',         // Search in articles.content
- *       'author.name',     // Search in joined users.name
- *       'category.title'   // Search in joined categories.title
- *     ]
+ *     oneOf: [
+ *       'title',           // Local field
+ *       'content',         // Local field
+ *       'author.name',     // Requires JOIN to users
+ *       'category.title'   // Requires JOIN to categories
+ *     ],
+ *     filterOperator: 'like'
  *   }
- * }
- * // For filter: { search: 'JavaScript' }
- * // Generates multiple JOINs and OR conditions across all fields
+ * };
+ * 
+ * // Filter request: { search: 'JavaScript' }
  * 
- * @example <caption>Deep nested relationships</caption>
- * searchSchema: {
+ * // Result: Multiple JOINs and OR conditions
+ * // SELECT DISTINCT * FROM articles
+ * // LEFT JOIN users AS articles_author ON articles.author_id = articles_author.id
+ * // LEFT JOIN categories AS articles_category ON articles.category_id = articles_category.id
+ * // WHERE (
+ * //   articles.title LIKE '%JavaScript%' OR
+ * //   articles.content LIKE '%JavaScript%' OR
+ * //   articles_author.name LIKE '%JavaScript%' OR
+ * //   articles_category.title LIKE '%JavaScript%'
+ * // )
+ * 
+ * @example
+ * // Input: Deep nested relationships (3 levels)
+ * const searchSchema = {
  *   company_country: {
  *     type: 'string',
- *     actualField: 'author.company.country.name',  // 3-level deep
- *     filterUsing: '='
+ *     actualField: 'author.company.country.name'
  *   }
- * }
- * // Generates chain of JOINs:
+ * };
+ * 
+ * // Filter request: { company_country: 'USA' }
+ * 
+ * // Result: Chain of JOINs following relationships
+ * // SELECT * FROM articles
  * // LEFT JOIN users AS articles_author ON articles.author_id = articles_author.id
  * // LEFT JOIN companies AS articles_author_company ON articles_author.company_id = articles_author_company.id
  * // LEFT JOIN countries AS articles_author_company_country ON articles_author_company.country_id = articles_author_company_country.id
+ * // WHERE articles_author_company_country.name = 'USA'
  * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API Knex plugin uses this to:
- * // 1. Enable filtering on related table fields without manual JOINs
- * // 2. Support deep relationship traversal with dot notation
- * // 3. Automatically detect and handle one-to-many JOINs with DISTINCT
- * // 4. Build optimized JOIN chains with proper aliasing
- * // 5. Enable powerful search across multiple related tables
- * // 6. Maintain clean API design - clients don't need to know about JOINs
+ * @description
+ * Used by:
+ * - rest-api-knex-plugin calls this hook second during query building
+ * - Runs after polymorphicFiltersHook but before basicFiltersHook
+ * - Applied when filters contain dot notation in actualField or oneOf
+ * 
+ * Purpose:
+ * - Enables filtering on related table fields without manual JOIN writing
+ * - Automatically builds JOIN chains from dot notation paths
+ * - Detects one-to-many relationships and adds DISTINCT to prevent duplicates
+ * - Creates unique aliases to avoid naming conflicts
+ * - Validates that target fields are indexed for performance
+ * 
+ * Data flow:
+ * 1. Scans filters for dot notation in actualField or oneOf arrays
+ * 2. For each cross-table reference, builds JOIN chain via buildJoinChain
+ * 3. Applies JOINs to query with proper aliasing
+ * 4. Adds DISTINCT if any one-to-many JOINs detected
+ * 5. Applies WHERE conditions using qualified field names
+ * 6. Sets hasJoins flag for basicFiltersHook to use
  */
 export const crossTableFiltersHook = async (hookParams, dependencies) => {
   const { log, scopes, knex, crossTableSearchHelpers } = dependencies;
@@ -390,12 +423,12 @@ export const crossTableFiltersHook = async (hookParams, dependencies) => {
       fieldPathMap.set(fieldDef.actualField, `${joinInfo.joinAlias}.${joinInfo.targetField}`);
     }
 
-    // Check likeOneOf for cross-table references
-    if (fieldDef.likeOneOf && Array.isArray(fieldDef.likeOneOf)) {
-      for (const field of fieldDef.likeOneOf) {
+    // Check oneOf for cross-table references
+    if (fieldDef.oneOf && Array.isArray(fieldDef.oneOf)) {
+      for (const field of fieldDef.oneOf) {
         if (field.includes('.')) {
           hasCrossTableFilters = true;
-          log.trace('[JOIN-DETECTION] Cross-table likeOneOf field found', { filterKey, field, scopeName });
+          log.trace('[JOIN-DETECTION] Cross-table oneOf field found', { filterKey, field, scopeName });
           const joinInfo = await crossTableSearchHelpers.buildJoinChain(scopeName, field);
           if (!joinMap.has(joinInfo.joinAlias)) {
             joinMap.set(joinInfo.joinAlias, joinInfo);
@@ -418,20 +451,66 @@ export const crossTableFiltersHook = async (hookParams, dependencies) => {
       joinInfo.joinChain.forEach((join) => {
         const joinKey = `${join.joinAlias}:${join.joinCondition}`;
         if (!appliedJoins.has(joinKey)) {
-          const [leftSide, rightSide] = join.joinCondition.split(' = ');
-          query.leftJoin(`${join.targetTableName} as ${join.joinAlias}`, function() {
-            this.on(leftSide, rightSide);
-          });
+          // Check if this is a polymorphic join with AND condition
+          if (join.isPolymorphic && join.joinCondition.includes(' AND ')) {
+            query.leftJoin(`${join.targetTableName} as ${join.joinAlias}`, function() {
+              // Parse polymorphic condition: type_field = 'value' AND id_field = parent.id
+              const parts = join.joinCondition.split(' AND ');
+              const [typeCondition, idCondition] = parts;
+              
+              // Extract the type field and value from first part
+              const typeMatch = typeCondition.match(/(.+?)\s*=\s*'(.+?)'/);
+              if (typeMatch) {
+                const typeField = typeMatch[1].trim();
+                const typeValue = typeMatch[2];
+                this.on(typeField, db.raw('?', [typeValue]));
+              }
+              
+              // Extract the id fields from second part
+              const idMatch = idCondition.match(/(.+?)\s*=\s*(.+)/);
+              if (idMatch) {
+                this.andOn(idMatch[1].trim(), idMatch[2].trim());
+              }
+            });
+          } else {
+            const [leftSide, rightSide] = join.joinCondition.split(' = ');
+            query.leftJoin(`${join.targetTableName} as ${join.joinAlias}`, function() {
+              this.on(leftSide, rightSide);
+            });
+          }
           appliedJoins.add(joinKey);
         }
       });
     } else {
       const joinKey = `${joinInfo.joinAlias}:${joinInfo.joinCondition}`;
       if (!appliedJoins.has(joinKey)) {
-        const [leftSide, rightSide] = joinInfo.joinCondition.split(' = ');
-        query.leftJoin(`${joinInfo.targetTableName} as ${joinInfo.joinAlias}`, function() {
-          this.on(leftSide, rightSide);
-        });
+        // Check if this is a polymorphic join with AND condition
+        if (joinInfo.isPolymorphic && joinInfo.joinCondition.includes(' AND ')) {
+          query.leftJoin(`${joinInfo.targetTableName} as ${joinInfo.joinAlias}`, function() {
+            // Parse polymorphic condition: type_field = 'value' AND id_field = parent.id
+            const parts = joinInfo.joinCondition.split(' AND ');
+            const [typeCondition, idCondition] = parts;
+            
+            // Extract the type field and value from first part
+            const typeMatch = typeCondition.match(/(.+?)\s*=\s*'(.+?)'/);
+            if (typeMatch) {
+              const typeField = typeMatch[1].trim();
+              const typeValue = typeMatch[2];
+              this.on(typeField, db.raw('?', [typeValue]));
+            }
+            
+            // Extract the id fields from second part
+            const idMatch = idCondition.match(/(.+?)\s*=\s*(.+)/);
+            if (idMatch) {
+              this.andOn(idMatch[1].trim(), idMatch[2].trim());
+            }
+          });
+        } else {
+          const [leftSide, rightSide] = joinInfo.joinCondition.split(' = ');
+          query.leftJoin(`${joinInfo.targetTableName} as ${joinInfo.joinAlias}`, function() {
+            this.on(leftSide, rightSide);
+          });
+        }
         appliedJoins.add(joinKey);
       }
     }
@@ -466,27 +545,72 @@ export const crossTableFiltersHook = async (hookParams, dependencies) => {
       // Skip non-cross-table and polymorphic filters
       if (fieldDef.polymorphicField) continue;
       if (!fieldDef.actualField?.includes('.') &&
-          !fieldDef.likeOneOf?.some(f => f.includes('.'))) {
+          !fieldDef.oneOf?.some(f => f.includes('.'))) {
         continue;
       }
 
       // Process cross-table filters
       switch (true) {
-        case fieldDef.likeOneOf && Array.isArray(fieldDef.likeOneOf):
+        case fieldDef.oneOf && Array.isArray(fieldDef.oneOf): {
+          const operator = fieldDef.filterOperator || '=';
+          
+          // Handle split search terms
+          let searchTerms = [filterValue];
+          if (fieldDef.splitBy && typeof filterValue === 'string') {
+            searchTerms = filterValue.split(fieldDef.splitBy).filter(term => term.trim());
+          }
+          
           this.where(function() {
-            fieldDef.likeOneOf.forEach((field, index) => {
-              const dbField = fieldPathMap.get(field) ||
-                             (!field.includes('.') && joinMap.size > 0 ? `${tableName}.${field}` : field);
-              const condition = `%${filterValue}%`;
-
-              if (index === 0) {
-                this.where(dbField, 'like', condition);
-              } else {
-                this.orWhere(dbField, 'like', condition);
-              }
-            });
+            if (fieldDef.matchAll && searchTerms.length > 1) {
+              // AND logic - all terms must match
+              searchTerms.forEach(term => {
+                this.andWhere(function() {
+                  fieldDef.oneOf.forEach((field, index) => {
+                    const dbField = fieldPathMap.get(field) ||
+                                   (!field.includes('.') && joinMap.size > 0 ? `${tableName}.${field}` : field);
+                    
+                    if (operator === 'like') {
+                      const condition = `%${term}%`;
+                      if (index === 0) {
+                        this.where(dbField, 'like', condition);
+                      } else {
+                        this.orWhere(dbField, 'like', condition);
+                      }
+                    } else {
+                      if (index === 0) {
+                        this.where(dbField, operator, term);
+                      } else {
+                        this.orWhere(dbField, operator, term);
+                      }
+                    }
+                  });
+                });
+              });
+            } else {
+              // OR logic for single term or matchAll=false
+              fieldDef.oneOf.forEach((field, index) => {
+                const dbField = fieldPathMap.get(field) ||
+                               (!field.includes('.') && joinMap.size > 0 ? `${tableName}.${field}` : field);
+                
+                if (operator === 'like') {
+                  const condition = `%${filterValue}%`;
+                  if (index === 0) {
+                    this.where(dbField, 'like', condition);
+                  } else {
+                    this.orWhere(dbField, 'like', condition);
+                  }
+                } else {
+                  if (index === 0) {
+                    this.where(dbField, operator, filterValue);
+                  } else {
+                    this.orWhere(dbField, operator, filterValue);
+                  }
+                }
+              });
+            }
           });
           break;
+        }
 
         case fieldDef.applyFilter && typeof fieldDef.applyFilter === 'function':
           fieldDef.applyFilter.call(this, this, filterValue);
@@ -498,7 +622,7 @@ export const crossTableFiltersHook = async (hookParams, dependencies) => {
             dbField = fieldPathMap.get(dbField) || dbField;
           }
 
-          const operator = fieldDef.filterUsing || '=';
+          const operator = fieldDef.filterOperator || '=';
 
           switch (operator) {
             case 'like':
@@ -529,94 +653,145 @@ export const crossTableFiltersHook = async (hookParams, dependencies) => {
 };
 
 /**
- * Hook 3: Basic Filters Hook
- * 
- * Processes filters that apply directly to fields on the main table.
- * This hook handles standard filtering operations like equality, LIKE,
- * IN, BETWEEN, etc. It automatically qualifies field names with the table
- * name when JOINs are present to prevent ambiguous column errors.
- * Must run last to ensure all JOINs have been established.
+ * Processes filters that apply directly to fields on the main table
  * 
  * @param {Object} hookParams - Hook parameters containing context
  * @param {Object} dependencies - Dependencies injected by the plugin
  * 
- * @example <caption>Basic equality filter</caption>
- * searchSchema: {
+ * @example
+ * // Input: Basic equality filter
+ * const searchSchema = {
  *   status: {
  *     type: 'string',
- *     filterUsing: '='  // Exact match
+ *     filterOperator: '='  // Default is '=' if not specified
  *   }
- * }
- * // For filter: { status: 'published' }
- * // Generates: WHERE articles.status = 'published'
+ * };
+ * 
+ * // Filter request: { status: 'published' }
+ * // Query before: SELECT * FROM articles
  * 
- * @example <caption>LIKE filter for partial matches</caption>
- * searchSchema: {
+ * // Result: Adds qualified WHERE clause
+ * // Query after: SELECT * FROM articles WHERE articles.status = 'published'
+ * 
+ * @example
+ * // Input: LIKE filter for partial text matching
+ * const searchSchema = {
  *   title: {
  *     type: 'string',
- *     filterUsing: 'like'
+ *     filterOperator: 'like'
+ *   },
+ *   content: {
+ *     type: 'string',
+ *     filterOperator: 'like'
  *   }
- * }
- * // For filter: { title: 'JavaScript' }
- * // Generates: WHERE articles.title LIKE '%JavaScript%'
+ * };
  * 
- * @example <caption>Multi-field OR search with likeOneOf</caption>
- * searchSchema: {
+ * // Filter request: { title: 'JavaScript', content: 'async' }
+ * 
+ * // Result: Multiple LIKE conditions
+ * // WHERE articles.title LIKE '%JavaScript%' 
+ * // AND articles.content LIKE '%async%'
+ * 
+ * @example
+ * // Input: Multi-field OR search with oneOf
+ * const searchSchema = {
  *   search: {
  *     type: 'string',
- *     likeOneOf: ['title', 'content', 'summary']
+ *     oneOf: ['title', 'content', 'summary'],
+ *     filterOperator: 'like',
+ *     splitBy: ' ',        // Split search terms by space
+ *     matchAll: true       // All terms must match somewhere
  *   }
- * }
- * // For filter: { search: 'API' }
- * // Generates: WHERE (
- * //   articles.title LIKE '%API%' OR 
- * //   articles.content LIKE '%API%' OR 
- * //   articles.summary LIKE '%API%'
+ * };
+ * 
+ * // Filter request: { search: 'REST API' }
+ * 
+ * // Result: Each term must match in at least one field
+ * // WHERE (
+ * //   (articles.title LIKE '%REST%' OR articles.content LIKE '%REST%' OR articles.summary LIKE '%REST%')
+ * //   AND
+ * //   (articles.title LIKE '%API%' OR articles.content LIKE '%API%' OR articles.summary LIKE '%API%')
  * // )
  * 
- * @example <caption>Advanced filters - IN and BETWEEN</caption>
- * searchSchema: {
+ * @example
+ * // Input: Advanced operators - IN and BETWEEN
+ * const searchSchema = {
  *   category_id: {
  *     type: 'array',
- *     filterUsing: 'in'
+ *     filterOperator: 'in'
+ *   },
+ *   price: {
+ *     type: 'array',
+ *     filterOperator: 'between'
  *   },
- *   created_at: {
+ *   tags: {
  *     type: 'array',
- *     filterUsing: 'between'
+ *     filterOperator: 'in'
  *   }
- * }
- * // For filters: { 
+ * };
+ * 
+ * // Filter request: { 
  * //   category_id: [1, 2, 3],
- * //   created_at: ['2024-01-01', '2024-12-31']
+ * //   price: [10.00, 99.99],
+ * //   tags: ['javascript', 'nodejs']
  * // }
- * // Generates:
+ * 
+ * // Result: IN and BETWEEN clauses
  * // WHERE articles.category_id IN (1, 2, 3)
- * // AND articles.created_at BETWEEN '2024-01-01' AND '2024-12-31'
+ * // AND articles.price BETWEEN 10.00 AND 99.99  
+ * // AND articles.tags IN ('javascript', 'nodejs')
  * 
- * @example <caption>Custom filter function</caption>
- * searchSchema: {
+ * @example
+ * // Input: Custom filter function
+ * const searchSchema = {
  *   has_comments: {
  *     type: 'boolean',
  *     applyFilter: function(query, value) {
- *       if (value) {
+ *       if (value === true) {
  *         query.whereExists(function() {
  *           this.select('id')
  *               .from('comments')
  *               .whereRaw('comments.article_id = articles.id');
  *         });
+ *       } else if (value === false) {
+ *         query.whereNotExists(function() {
+ *           this.select('id')
+ *               .from('comments')
+ *               .whereRaw('comments.article_id = articles.id');
+ *         });
  *       }
  *     }
  *   }
- * }
- * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API Knex plugin uses this to:
- * // 1. Implement standard SQL filtering operations safely
- * // 2. Automatically qualify fields to prevent ambiguous column errors
- * // 3. Support multiple filter operators (=, like, in, between, etc.)
- * // 4. Enable multi-field OR searches with likeOneOf
- * // 5. Allow custom filter logic through applyFilter functions
- * // 6. Maintain SQL injection safety through Knex query builder
+ * };
+ * 
+ * // Filter request: { has_comments: true }
+ * 
+ * // Result: Subquery to check existence
+ * // WHERE EXISTS (
+ * //   SELECT id FROM comments WHERE comments.article_id = articles.id
+ * // )
+ * 
+ * @description
+ * Used by:
+ * - rest-api-knex-plugin calls this hook last during query building
+ * - Runs after all JOINs have been established by previous hooks
+ * - Handles all non-cross-table, non-polymorphic filters
+ * 
+ * Purpose:
+ * - Implements standard SQL filtering operations safely via Knex
+ * - Always qualifies field names with table name to prevent ambiguity
+ * - Supports various operators: =, like, in, between, and custom
+ * - Enables multi-field OR searches with optional term splitting
+ * - Handles null values appropriately (using whereNull)
+ * - Allows custom filter logic via applyFilter functions
+ * 
+ * Data flow:
+ * 1. Skips filters already handled by polymorphic/cross-table hooks
+ * 2. Qualifies all field names with table name (e.g., articles.title)
+ * 3. Applies appropriate WHERE clause based on filterOperator
+ * 4. For oneOf filters, creates OR conditions across specified fields
+ * 5. For custom filters, delegates to applyFilter function
+ * 6. Returns query with all basic filters applied
  */
 export const basicFiltersHook = async (hookParams, dependencies) => {
   const { log, scopes, knex } = dependencies;
@@ -629,7 +804,17 @@ export const basicFiltersHook = async (hookParams, dependencies) => {
   const tableName = hookParams.context?.knexQuery?.tableName;
   const db = hookParams.context?.knexQuery?.db || knex;
 
+  log.trace('[DEBUG basicFiltersHook] Called with:', {
+    scopeName,
+    hasFilters: !!filters,
+    filters,
+    hasSearchSchema: !!searchSchema,
+    searchSchemaKeys: searchSchema ? Object.keys(searchSchema.structure || {}) : [],
+    tableName
+  });
+
   if (!filters || !searchSchema) {
+    log.trace('[DEBUG basicFiltersHook] Returning early - no filters or searchSchema');
     return;
   }
 
@@ -643,33 +828,83 @@ export const basicFiltersHook = async (hookParams, dependencies) => {
   query.where(function() {
     for (const [filterKey, filterValue] of Object.entries(filters)) {
       const fieldDef = searchSchema.structure[filterKey];
-      if (!fieldDef) continue;
+      if (!fieldDef) {
+        log.trace(`[DEBUG basicFiltersHook] No field definition for filter key: ${filterKey}`);
+        continue;
+      }
+      log.trace(`[DEBUG basicFiltersHook] Processing filter: ${filterKey} = ${filterValue}, fieldDef:`, fieldDef);
 
       // Skip if this is a cross-table filter
       if (fieldDef.actualField?.includes('.') ||
-          fieldDef.likeOneOf?.some(f => f.includes('.')) ||
+          fieldDef.oneOf?.some(f => f.includes('.')) ||
           fieldDef.polymorphicField) {
+        log.trace(`[DEBUG basicFiltersHook] Skipping filter ${filterKey} - is cross-table or polymorphic`);
         continue;
       }
 
       // Process basic filters
       switch (true) {
-        case fieldDef.likeOneOf && Array.isArray(fieldDef.likeOneOf):
+        case fieldDef.oneOf && Array.isArray(fieldDef.oneOf): {
           // Multi-field OR search
+          const operator = fieldDef.filterOperator || '=';
+          
+          // Handle split search terms
+          let searchTerms = [filterValue];
+          if (fieldDef.splitBy && typeof filterValue === 'string') {
+            searchTerms = filterValue.split(fieldDef.splitBy).filter(term => term.trim());
+          }
+          
           this.where(function() {
-            fieldDef.likeOneOf.forEach((field, index) => {
-              // Always qualify field names
-              const dbField = qualifyField(field);
-              const condition = `%${filterValue}%`;
-
-              if (index === 0) {
-                this.where(dbField, 'like', condition);
-              } else {
-                this.orWhere(dbField, 'like', condition);
-              }
-            });
+            if (fieldDef.matchAll && searchTerms.length > 1) {
+              // AND logic - all terms must match
+              searchTerms.forEach(term => {
+                this.andWhere(function() {
+                  fieldDef.oneOf.forEach((field, index) => {
+                    // Always qualify field names
+                    const dbField = qualifyField(field);
+                    
+                    if (operator === 'like') {
+                      const condition = `%${term}%`;
+                      if (index === 0) {
+                        this.where(dbField, 'like', condition);
+                      } else {
+                        this.orWhere(dbField, 'like', condition);
+                      }
+                    } else {
+                      if (index === 0) {
+                        this.where(dbField, operator, term);
+                      } else {
+                        this.orWhere(dbField, operator, term);
+                      }
+                    }
+                  });
+                });
+              });
+            } else {
+              // OR logic for single term or matchAll=false
+              fieldDef.oneOf.forEach((field, index) => {
+                // Always qualify field names
+                const dbField = qualifyField(field);
+                
+                if (operator === 'like') {
+                  const condition = `%${filterValue}%`;
+                  if (index === 0) {
+                    this.where(dbField, 'like', condition);
+                  } else {
+                    this.orWhere(dbField, 'like', condition);
+                  }
+                } else {
+                  if (index === 0) {
+                    this.where(dbField, operator, filterValue);
+                  } else {
+                    this.orWhere(dbField, operator, filterValue);
+                  }
+                }
+              });
+            }
           });
           break;
+        }
 
         case fieldDef.applyFilter && typeof fieldDef.applyFilter === 'function':
           // Custom filter
@@ -682,7 +917,8 @@ export const basicFiltersHook = async (hookParams, dependencies) => {
           // Always qualify field names
           const dbField = qualifyField(actualField);
 
-          const operator = fieldDef.filterUsing || '=';
+          const operator = fieldDef.filterOperator || '=';
+          log.trace(`[DEBUG basicFiltersHook] Applying filter: ${dbField} ${operator} ${filterValue}`);
 
           switch (operator) {
             case 'like':