json-rest-api 1.0.14 → 1.0.16

package/plugins/core/lib/querying-writing/schema-helpers.js

@@ -1,6 +1,6 @@
 /**
  * Schema processing utilities for search and field dependencies
- * 
+ *
  * @description
  * This module provides utilities for:
  * - Marking search fields as indexed for database optimization
@@ -9,14 +9,14 @@
  * - Detecting circular dependencies in field definitions
  */
 
-import { RestApiValidationError } from '../../../../lib/rest-api-errors.js';
+import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
 
 /**
  * Marks all fields in a searchSchema as indexed for database optimization
- * 
+ *
  * @param {Object} searchSchema - Search schema object to process
  * @returns {void} Modifies the searchSchema in-place
- * 
+ *
  * @example
  * // Input: Search fields without index flags
  * const searchSchema = {
@@ -25,14 +25,14 @@ import { RestApiValidationError } from '../../../../lib/rest-api-errors.js';
  *   created_at: { type: 'datetime', filterOperator: '>=' }
  * };
  * ensureSearchFieldsAreIndexed(searchSchema);
- * 
+ *
  * // Output: All fields marked as indexed
  * // {
  * //   title: { type: 'string', filterOperator: 'contains', indexed: true },
  * //   status: { type: 'string', filterOperator: '=', indexed: true },
  * //   created_at: { type: 'datetime', filterOperator: '>=', indexed: true }
  * // }
- * 
+ *
  * @example
  * // Input: Virtual field for cross-table search
  * const searchSchema = {
@@ -48,13 +48,13 @@ import { RestApiValidationError } from '../../../../lib/rest-api-errors.js';
  *   }
  * };
  * ensureSearchFieldsAreIndexed(searchSchema);
- * 
+ *
  * // Output: Both regular and virtual fields indexed
  * // {
  * //   name: { ..., indexed: true },
  * //   author_name: { ..., indexed: true }  // Enables efficient JOIN
  * // }
- * 
+ *
  * @example
  * // Input: Already indexed or explicitly false
  * const searchSchema = {
@@ -62,50 +62,50 @@ import { RestApiValidationError } from '../../../../lib/rest-api-errors.js';
  *   username: { type: 'string', indexed: true }   // Already true
  * };
  * ensureSearchFieldsAreIndexed(searchSchema);
- * 
+ *
  * // Output: All forced to indexed: true
  * // {
  * //   email: { type: 'string', indexed: true },    // Overridden
  * //   username: { type: 'string', indexed: true }   // Unchanged
  * // }
- * 
+ *
  * @description
  * Used by:
  * - rest-api-plugin during scope initialization
  * - Applied to all searchSchema fields before storage setup
- * 
+ *
  * Purpose:
  * - Signals storage plugins which fields need database indexes
  * - Enables efficient filtering without full table scans
  * - Supports cross-table searches via indexed JOINs
  * - Improves query performance for filtered API requests
- * 
+ *
  * Data flow:
  * 1. Receives searchSchema object (or null)
  * 2. Iterates through each field definition
  * 3. Sets indexed: true on all fields
  * 4. Storage plugins use this flag for index creation
  */
-export function ensureSearchFieldsAreIndexed(searchSchema) {
-  if (!searchSchema) return;
-  
+export function ensureSearchFieldsAreIndexed (searchSchema) {
+  if (!searchSchema) return
+
   Object.keys(searchSchema).forEach(fieldName => {
-    const fieldDef = searchSchema[fieldName];
+    const fieldDef = searchSchema[fieldName]
     if (fieldDef && typeof fieldDef === 'object') {
       // Mark the field as indexed for cross-table search support
-      fieldDef.indexed = true;
+      fieldDef.indexed = true
     }
-  });
+  })
 }
 
 /**
  * Generates complete searchSchema by merging schema search definitions with explicit searchSchema
- * 
+ *
  * @param {Object} schema - Main resource schema with optional 'search' properties
  * @param {Object} explicitSearchSchema - Optional explicit searchSchema to merge
  * @returns {Object|null} Merged searchSchema or null if no search fields
  * @throws {RestApiValidationError} If same field defined in multiple places
- * 
+ *
  * @example
  * // Input: Simple search fields in schema
  * const schema = {
@@ -114,13 +114,13 @@ export function ensureSearchFieldsAreIndexed(searchSchema) {
  *   status: { type: 'string', search: { filterOperator: '=' } }  // Custom
  * };
  * const result = generateSearchSchemaFromSchema(schema, null);
- * 
+ *
  * // Output: Generated search schema
  * // {
  * //   title: { type: 'string', filterOperator: '=' },      // Default operator
  * //   status: { type: 'string', filterOperator: '=' }      // Specified operator
  * // }
- * 
+ *
  * @example
  * // Input: Multiple filters from one field
  * const schema = {
@@ -133,21 +133,21 @@ export function ensureSearchFieldsAreIndexed(searchSchema) {
  *   }
  * };
  * const result = generateSearchSchemaFromSchema(schema, null);
- * 
+ *
  * // Output: Two search fields from one database field
  * // {
- * //   published_after: { 
- * //     type: 'datetime', 
+ * //   published_after: {
+ * //     type: 'datetime',
  * //     actualField: 'published_at',      // Maps to real field
- * //     filterOperator: '>=' 
+ * //     filterOperator: '>='
  * //   },
- * //   published_before: { 
- * //     type: 'datetime', 
+ * //   published_before: {
+ * //     type: 'datetime',
  * //     actualField: 'published_at',      // Same field, different operator
- * //     filterOperator: '<=' 
+ * //     filterOperator: '<='
  * //   }
  * // }
- * 
+ *
  * @example
  * // Input: Merging with explicit searchSchema
  * const schema = {
@@ -158,14 +158,14 @@ export function ensureSearchFieldsAreIndexed(searchSchema) {
  *   age: { type: 'number', filterOperator: '>=' }
  * };
  * const result = generateSearchSchemaFromSchema(schema, explicitSearchSchema);
- * 
+ *
  * // Output: Combined from both sources
  * // {
  * //   email: { type: 'string', filterOperator: '=' },    // Explicit
  * //   age: { type: 'number', filterOperator: '>=' },     // Explicit
  * //   name: { type: 'string', filterOperator: '=' }      // From schema
  * // }
- * 
+ *
  * @example
  * // Input: Explicit searchSchema takes precedence
  * const schema = {
@@ -179,7 +179,7 @@ export function ensureSearchFieldsAreIndexed(searchSchema) {
  * // {
  * //   email: { type: 'string', filterOperator: 'contains' }  // Uses explicit definition
  * // }
- * 
+ *
  * @example
  * // Input: Virtual search fields
  * const schema = {
@@ -198,7 +198,7 @@ export function ensureSearchFieldsAreIndexed(searchSchema) {
  *     }
  *   }
  * };
- * 
+ *
  * // Output: Virtual field for cross-table search
  * // {
  * //   category_name: {
@@ -207,12 +207,12 @@ export function ensureSearchFieldsAreIndexed(searchSchema) {
  * //     virtualField: { ... join config ... }
  * //   }
  * // }
- * 
+ *
  * @description
  * Used by:
  * - rest-api-plugin during scope initialization
  * - Generates searchSchema from various sources
- * 
+ *
  * Purpose:
  * - Provides flexible search configuration options
  * - Enables virtual fields for cross-table searches
@@ -220,7 +220,7 @@ export function ensureSearchFieldsAreIndexed(searchSchema) {
  * - Merges search:true fields with explicit searchSchema
  * - Explicit searchSchema always takes precedence
  * - Allows storage plugins to optimize queries
- * 
+ *
  * Data flow:
  * 1. Starts with explicit searchSchema (if any)
  * 2. Processes schema fields with 'search' property
@@ -231,118 +231,118 @@ export function ensureSearchFieldsAreIndexed(searchSchema) {
  */
 export const generateSearchSchemaFromSchema = (schema, explicitSearchSchema) => {
   // Start with explicit searchSchema or empty object
-  const searchSchema = explicitSearchSchema ? {...explicitSearchSchema} : {};
-  
+  const searchSchema = explicitSearchSchema ? { ...explicitSearchSchema } : {}
+
   if (!schema) {
-    return Object.keys(searchSchema).length > 0 ? searchSchema : null;
+    return Object.keys(searchSchema).length > 0 ? searchSchema : null
   }
-  
+
   // Process schema fields with 'search' property
   Object.entries(schema).forEach(([fieldName, fieldDef]) => {
-    const effectiveSearch = fieldDef.search;
-    
+    const effectiveSearch = fieldDef.search
+
     if (effectiveSearch) {
       if (effectiveSearch === true) {
         // For belongsTo relationships, use the relationship name (as property) instead of the field name
-        const searchFieldName = (fieldDef.belongsTo && fieldDef.as) ? fieldDef.as : fieldName;
-        
+        const searchFieldName = (fieldDef.belongsTo && fieldDef.as) ? fieldDef.as : fieldName
+
         // Check if field already exists in explicit searchSchema
         if (searchSchema[searchFieldName]) {
           // Skip - explicit searchSchema takes precedence
           // This allows searchSchema to override fields marked with search:true
-          return;
+          return
         }
-        
+
         // Simple boolean - copy entire field definition (except search) and add filterOperator
-        const { search, ...fieldDefWithoutSearch } = fieldDef;
+        const { search, ...fieldDefWithoutSearch } = fieldDef
         const searchEntry = {
           ...fieldDefWithoutSearch,
           // Preserve existing filterOperator or default to '='
           filterOperator: fieldDefWithoutSearch.filterOperator || '='
-        };
-        
+        }
+
         // For belongsTo relationships, add metadata to map back to the actual field
         if (fieldDef.belongsTo && fieldDef.as) {
-          searchEntry.actualField = fieldName;  // Maps to the DB column
-          searchEntry.isRelationship = true;
-          searchEntry.targetResource = fieldDef.belongsTo;
+          searchEntry.actualField = fieldName  // Maps to the DB column
+          searchEntry.isRelationship = true
+          searchEntry.targetResource = fieldDef.belongsTo
         }
-        
-        searchSchema[searchFieldName] = searchEntry;
+
+        searchSchema[searchFieldName] = searchEntry
       } else if (typeof effectiveSearch === 'object') {
         // Check if search defines multiple filter fields
         const hasNestedFilters = Object.values(effectiveSearch).some(
           v => typeof v === 'object' && v.filterOperator
-        );
-        
+        )
+
         if (hasNestedFilters) {
           // Multiple filters from one field (like published_after/before)
           Object.entries(effectiveSearch).forEach(([filterName, filterDef]) => {
             // Check if filter already exists in explicit searchSchema
             if (searchSchema[filterName]) {
               // Skip - explicit searchSchema takes precedence
-              return;
+              return
             }
-            
+
             searchSchema[filterName] = {
               type: fieldDef.type,
               actualField: fieldName,
               ...filterDef
-            };
-          });
+            }
+          })
         } else {
           // For belongsTo relationships, use the relationship name (as property) instead of the field name
-          const searchFieldName = (fieldDef.belongsTo && fieldDef.as) ? fieldDef.as : fieldName;
-          
+          const searchFieldName = (fieldDef.belongsTo && fieldDef.as) ? fieldDef.as : fieldName
+
           // Check if field already exists in explicit searchSchema
           if (searchSchema[searchFieldName]) {
             // Skip - explicit searchSchema takes precedence
-            return;
+            return
           }
-          
+
           // Single filter with config
           const searchEntry = {
             type: fieldDef.type,
             ...effectiveSearch
-          };
-          
+          }
+
           // For belongsTo relationships, add metadata to map back to the actual field
           if (fieldDef.belongsTo && fieldDef.as) {
-            searchEntry.actualField = fieldName;  // Maps to the DB column
-            searchEntry.isRelationship = true;
-            searchEntry.targetResource = fieldDef.belongsTo;
+            searchEntry.actualField = fieldName  // Maps to the DB column
+            searchEntry.isRelationship = true
+            searchEntry.targetResource = fieldDef.belongsTo
           }
-          
-          searchSchema[searchFieldName] = searchEntry;
+
+          searchSchema[searchFieldName] = searchEntry
         }
       }
     }
-  });
-  
+  })
+
   // Handle _virtual search definitions
   if (schema._virtual?.search) {
     Object.entries(schema._virtual.search).forEach(([filterName, filterDef]) => {
       // Check if filter already exists in explicit searchSchema
       if (searchSchema[filterName]) {
         // Skip - explicit searchSchema takes precedence
-        return;
+        return
       }
-      
-      searchSchema[filterName] = filterDef;
-    });
+
+      searchSchema[filterName] = filterDef
+    })
   }
-  
-  return Object.keys(searchSchema).length > 0 ? searchSchema : null;
-};
+
+  return Object.keys(searchSchema).length > 0 ? searchSchema : null
+}
 
 /**
  * Generic topological sort for handling dependencies
- * 
+ *
  * @param {Array} items - Array of items to sort
  * @param {Function} getDependencies - Function that returns dependencies for an item
  * @returns {Array} Sorted array respecting dependencies
  * @throws {Error} If circular dependencies or unknown dependencies detected
- * 
+ *
  * @example
  * // Input: Simple dependency chain
  * const items = ['a', 'b', 'c'];
@@ -350,80 +350,80 @@ export const generateSearchSchemaFromSchema = (schema, explicitSearchSchema) =>
  * const sorted = topologicalSort(items, item => deps[item]);
  * // Output: ['c', 'b', 'a']
  * // c first (no deps), then b (depends on c), then a (depends on b)
- * 
+ *
  * @example
  * // Input: Circular dependency
  * const items = ['a', 'b'];
  * const deps = { a: ['b'], b: ['a'] };  // Circular!
  * topologicalSort(items, item => deps[item]);
  * // Throws: Error "Circular dependency detected: b"
- * 
+ *
  * @example
  * // Input: Unknown dependency
  * const items = ['a', 'b'];
  * const deps = { a: ['c'], b: [] };     // 'c' not in items
  * topologicalSort(items, item => deps[item]);
  * // Throws: Error "Unknown dependency 'c' for 'a'"
- * 
+ *
  * @description
  * Used by:
  * - sortFieldsByDependencies for ordering field operations
  * - Any code needing dependency-based ordering
- * 
+ *
  * Purpose:
  * - Orders items so dependencies come before dependents
  * - Detects circular dependencies early
  * - Validates all dependencies exist
  * - Uses depth-first search algorithm
  */
-export function topologicalSort(items, getDependencies) {
-  const sorted = [];
-  const visited = new Set();
-  const visiting = new Set();
-  
-  function visit(item) {
-    if (visited.has(item)) return;
-    
+export function topologicalSort (items, getDependencies) {
+  const sorted = []
+  const visited = new Set()
+  const visiting = new Set()
+
+  function visit (item) {
+    if (visited.has(item)) return
+
     if (visiting.has(item)) {
-      throw new Error(`Circular dependency detected: ${item}`);
+      throw new Error(`Circular dependency detected: ${item}`)
     }
-    
-    visiting.add(item);
-    
-    const dependencies = getDependencies(item) || [];
+
+    visiting.add(item)
+
+    const dependencies = getDependencies(item) || []
     for (const dep of dependencies) {
       if (!items.includes(dep)) {
-        throw new Error(`Unknown dependency '${dep}' for '${item}'`);
+        throw new Error(`Unknown dependency '${dep}' for '${item}'`)
       }
-      visit(dep);
+      visit(dep)
     }
-    
-    visiting.delete(item);
-    visited.add(item);
-    sorted.push(item);
+
+    visiting.delete(item)
+    visited.add(item)
+    sorted.push(item)
   }
-  
+
   for (const item of items) {
-    visit(item);
+    visit(item)
   }
-  
-  return sorted;
+
+  return sorted
 }
 
 /**
  * Sorts fields by their dependencies using topological sort
- * 
+ *
  * @param {Object} fields - Object with field definitions
  * @param {string} dependencyProperty - Property name containing dependencies
  * @returns {Array} Field names sorted by dependencies
  * @throws {Error} If circular dependencies or unknown fields detected
- * 
+ *
  * @example
  * // Input: Getter dependencies (fullName needs firstName and lastName)
  * const fields = {
  *   firstName: { getter: v => v.trim() },
  *   lastName: { getter: v => v.trim() },
- *   fullName: { 
+ *   fullName: {
  *     getter: (v, ctx) => `${ctx.attributes.firstName} ${ctx.attributes.lastName}`,
  *     runGetterAfter: ['firstName', 'lastName']
  *   }
@@ -431,7 +431,7 @@ export function topologicalSort(items, getDependencies) {
  * const sorted = sortFieldsByDependencies(fields, 'runGetterAfter');
  * // Output: ['firstName', 'lastName', 'fullName']
  * // Ensures firstName/lastName getters run before fullName
- * 
+ *
  * @example
  * // Input: Complex dependency chain
  * const fields = {
@@ -443,7 +443,7 @@ export function topologicalSort(items, getDependencies) {
  * const sorted = sortFieldsByDependencies(fields, 'runGetterAfter');
  * // Output: ['d', 'b', 'c', 'a']
  * // d first, then b/c (both need d), then a (needs b/c)
- * 
+ *
  * @example
  * // Input: Circular dependency error
  * const fields = {
@@ -452,38 +452,38 @@ export function topologicalSort(items, getDependencies) {
  * };
  * sortFieldsByDependencies(fields, 'runGetterAfter');
  * // Throws: Error "Circular dependency detected: a in runGetterAfter"
- * 
+ *
  * @description
  * Used by:
  * - Schema processing for getter/setter ordering
  * - Ensures dependent fields process after dependencies
- * 
+ *
  * Purpose:
  * - Orders field operations by dependencies
  * - Enables computed fields that depend on other fields
  * - Validates dependency graph is acyclic
  * - Provides clear error messages for debugging
- * 
+ *
  * Data flow:
  * 1. Extracts field names from object
  * 2. Calls topologicalSort with dependency function
  * 3. Returns ordered field names
  * 4. Enhances error messages with property name
  */
-export function sortFieldsByDependencies(fields, dependencyProperty) {
-  const fieldNames = Object.keys(fields);
-  
-  if (fieldNames.length === 0) return [];
-  
+export function sortFieldsByDependencies (fields, dependencyProperty) {
+  const fieldNames = Object.keys(fields)
+
+  if (fieldNames.length === 0) return []
+
   try {
     return topologicalSort(fieldNames, (fieldName) => {
-      const field = fields[fieldName];
-      return field[dependencyProperty] || [];
-    });
+      const field = fields[fieldName]
+      return field[dependencyProperty] || []
+    })
   } catch (error) {
     if (error.message.includes('Circular dependency')) {
-      throw new Error(`${error.message} in ${dependencyProperty}`);
+      throw new Error(`${error.message} in ${dependencyProperty}`)
     }
-    throw error;
+    throw error
   }
-}
+}