json-rest-api 1.0.6 → 1.0.8

package/plugins/core/lib/relationship-processor.js

@@ -1,278 +0,0 @@
-/**
- * @module relationship-processor
- * @description Relationship processing functions for REST API plugin
- * 
- * This module handles the complex task of extracting relationship data from
- * JSON:API payloads and converting them into database operations. It bridges
- * the gap between JSON:API's relationship format and actual database foreign
- * keys and pivot tables.
- */
-
-import { RestApiValidationError } from '../../../lib/rest-api-errors.js';
-
-/**
- * Processes JSON:API relationship data from input records and converts them into database-ready foreign key updates
- * and many-to-many relationship operations.
- * 
- * This function is the central relationship processor that handles all types of relationships:
- * 1. **belongsTo (1:1)**: Converts relationship references to foreign key values
- * 2. **Polymorphic belongsTo**: Handles relationships that can point to multiple types
- * 3. **Many-to-many**: Collects relationship data for pivot table operations
- * 
- * The function analyzes the incoming JSON:API relationships block and the resource's schema
- * to determine how to process each relationship. It returns two objects:
- * - `belongsToUpdates`: Direct field updates for foreign keys
- * - `manyToManyRelationships`: Array of many-to-many operations to perform
- * 
- * @param {Object} scope - The scope object containing schema info
- * @param {Object} deps - Dependencies object
- * @param {Object} deps.context - Request context
- * @param {Object} deps.context.inputRecord - The JSON:API input record containing relationship data
- * @returns {Object} Object with belongsToUpdates and manyToManyRelationships arrays
- * @throws {RestApiValidationError} If polymorphic relationship type is invalid
- * 
- * @example
- * // Example 1: Processing a simple belongsTo relationship
- * const scope = api.resources['articles'];
- * const deps = {
- *   context: {
- *     inputRecord: {
- *       data: {
- *         type: 'articles',
- *         attributes: { title: 'My Article' },
- *         relationships: {
- *           author: {
- *             data: { type: 'users', id: '123' }
- *           }
- *         }
- *       }
- *     }
- *   }
- * };
- * const result = processRelationships(scope, deps);
- * // Returns:
- * // {
- * //   belongsToUpdates: { author_id: '123' },  // Foreign key extracted
- * //   manyToManyRelationships: []
- * // }
- * 
- * @example
- * // Example 2: Processing polymorphic relationships
- * const scope = api.resources['comments'];
- * const deps = {
- *   context: {
- *     inputRecord: {
- *       data: {
- *         type: 'comments',
- *         attributes: { text: 'Great!' },
- *         relationships: {
- *           commentable: {
- *             data: { type: 'posts', id: '456' }  // Can be 'posts' or 'videos'
- *           }
- *         }
- *       }
- *     }
- *   }
- * };
- * const result = processRelationships(scope, deps);
- * // Returns:
- * // {
- * //   belongsToUpdates: {
- * //     commentable_type: 'posts',  // Type field set
- * //     commentable_id: '456'       // ID field set
- * //   },
- * //   manyToManyRelationships: []
- * // }
- * 
- * @example
- * // Example 3: Processing many-to-many relationships
- * const scope = api.resources['articles'];
- * const deps = {
- *   context: {
- *     inputRecord: {
- *       data: {
- *         type: 'articles',
- *         attributes: { title: 'Tagged Article' },
- *         relationships: {
- *           tags: {
- *             data: [
- *               { type: 'tags', id: '10' },
- *               { type: 'tags', id: '20' },
- *               { type: 'tags', id: '30' }
- *             ]
- *           }
- *         }
- *       }
- *     }
- *   }
- * };
- * const result = processRelationships(scope, deps);
- * // Returns:
- * // {
- * //   belongsToUpdates: {},
- * //   manyToManyRelationships: [{
- * //     relName: 'tags',
- * //     relDef: {
- * //       through: 'article_tags',
- * //       foreignKey: 'article_id',
- * //       otherKey: 'tag_id'
- * //     },
- * //     relData: [
- * //       { type: 'tags', id: '10' },
- * //       { type: 'tags', id: '20' },
- * //       { type: 'tags', id: '30' }
- * //     ]
- * //   }]
- * // }
- * 
- * @example
- * // Example 4: Clearing relationships (setting to null)
- * const scope = api.resources['articles'];
- * const deps = {
- *   context: {
- *     inputRecord: {
- *       data: {
- *         type: 'articles',
- *         relationships: {
- *           author: {
- *             data: null  // Clear the author
- *           },
- *           tags: {
- *             data: []    // Clear all tags
- *           }
- *         }
- *       }
- *     }
- *   }
- * };
- * const result = processRelationships(scope, deps);
- * // Returns:
- * // {
- * //   belongsToUpdates: { author_id: null },  // Foreign key cleared
- * //   manyToManyRelationships: [{
- * //     relName: 'tags',
- * //     relDef: { ... },
- * //     relData: []  // Empty array will clear all pivot records
- * //   }]
- * // }
- * 
- * @example
- * // Example 5: Invalid polymorphic type throws error
- * const scope = api.resources['comments'];
- * const deps = {
- *   context: {
- *     inputRecord: {
- *       data: {
- *         relationships: {
- *           commentable: {
- *             data: { type: 'invalid_type', id: '123' }
- *           }
- *         }
- *       }
- *     }
- *   }
- * };
- * // Throws RestApiValidationError:
- * // "Invalid type 'invalid_type' for polymorphic relationship 'commentable'. Allowed types: posts, videos"
- * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API plugin uses this to:
- * // 1. Convert JSON:API relationships to database-ready foreign keys
- * // 2. Validate polymorphic relationships against allowed types
- * // 3. Prepare many-to-many operations for pivot table updates
- * // 4. Support both setting and clearing relationships (null/empty array)
- * // 5. Maintain data integrity by validating relationships before database writes
- * // 6. Abstract the complexity of different relationship types from storage plugins
- */
-export const processRelationships = (scope, deps) => {
-  // Extract values from scope
-  const { 
-    vars: { 
-      schemaInfo: { schemaStructure: schemaFields, schemaRelationships: relationships }
-    }
-  } = scope;
-  
-  // Extract values from deps
-  const { context } = deps;
-  const { inputRecord } = context;
-  const belongsToUpdates = {};
-  const manyToManyRelationships = [];
-  
-  if (!inputRecord.data.relationships) {
-    return { belongsToUpdates, manyToManyRelationships };
-  }
-  
-  for (const [relName, relData] of Object.entries(inputRecord.data.relationships)) {
-    const relDef = relationships?.[relName];
-    
-    // Find the schema field that defines this relationship
-    const schemaField = Object.entries(schemaFields).find(([fieldName, fieldDef]) => 
-      fieldDef.as === relName
-    );
-    
-    if (schemaField) {
-      const [fieldName, fieldDef] = schemaField;
-      
-      // Handle regular belongsTo (1:1)
-      if (fieldDef.belongsTo && !fieldDef.belongsToPolymorphic) {
-        if (relData.data === null) {
-          belongsToUpdates[fieldName] = null;
-        } else if (relData.data?.id) {
-          belongsToUpdates[fieldName] = relData.data.id;
-        }
-      }
-      // Handle polymorphic belongsTo
-      else if (fieldDef.belongsToPolymorphic) {
-        if (relData.data === null) {
-          const { typeField, idField } = fieldDef.belongsToPolymorphic;
-          belongsToUpdates[typeField] = null;
-          belongsToUpdates[idField] = null;
-        } else if (relData.data) {
-          const { type, id } = relData.data;
-          const { types, typeField, idField } = fieldDef.belongsToPolymorphic;
-          
-          // Validate type is allowed
-          if (!types.includes(type)) {
-            throw new RestApiValidationError(
-              `Invalid type '${type}' for polymorphic relationship '${relName}'. Allowed types: ${types.join(', ')}`,
-              { 
-                fields: [`data.relationships.${relName}.data.type`],
-                violations: [{
-                  field: `data.relationships.${relName}.data.type`,
-                  rule: 'polymorphic_type',
-                  message: `Type must be one of: ${types.join(', ')}`
-                }]
-              }
-            );
-          }
-          
-          belongsToUpdates[typeField] = type;
-          belongsToUpdates[idField] = id;
-        }
-      }
-    }
-    
-    // Check for many-to-many relationships defined in relationships object
-    if (relDef?.manyToMany && relData.data !== undefined) {
-      manyToManyRelationships.push({
-        relName,
-        relDef: relDef.manyToMany,  // Pass the manyToMany object, not the whole relationship
-        relData: relData.data || []  // null means empty array for many-to-many
-      });
-    }
-    // Also check for hasMany with through (alternative many-to-many syntax)
-    else if (relDef?.hasMany && relDef?.through && relData.data !== undefined) {
-      manyToManyRelationships.push({
-        relName,
-        relDef: {
-          through: relDef.through,
-          foreignKey: relDef.foreignKey,
-          otherKey: relDef.otherKey
-        },
-        relData: relData.data || []  // null means empty array for many-to-many
-      });
-    }
-  }
-  
-  return { belongsToUpdates, manyToManyRelationships };
-};

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

@@ -1,343 +0,0 @@
-/**
- * @module schemaHelpers
- * @description Schema helper functions for REST API plugin
- * 
- * This module provides utilities for processing and enhancing schemas,
- * particularly for search functionality. It ensures search fields are
- * properly indexed and generates comprehensive search schemas from
- * various configuration sources.
- */
-
-import { RestApiValidationError } from '../../../lib/rest-api-errors.js';
-
-/**
- * Automatically marks all fields in a searchSchema as indexed to enable efficient cross-table searches.
- * 
- * This function is essential for the cross-table search feature, which allows searching across
- * multiple related resources in a single query. By marking fields as indexed, it signals to
- * storage plugins (like Knex) that these fields should have database indexes created for
- * optimal query performance.
- * 
- * The function modifies the searchSchema in-place, adding `indexed: true` to each field
- * definition. This is typically called during scope initialization to prepare search fields
- * for efficient querying.
- * 
- * @param {Object} searchSchema - The searchSchema object to process
- * @returns {void} Modifies the searchSchema in-place
- * 
- * @example
- * // Example 1: Basic searchSchema indexing
- * const searchSchema = {
- *   title: { type: 'string', filterUsing: 'contains' },
- *   status: { type: 'string', filterUsing: '=' },
- *   created_at: { type: 'datetime', filterUsing: '>=' }
- * };
- * ensureSearchFieldsAreIndexed(searchSchema);
- * // After processing:
- * // {
- * //   title: { type: 'string', filterUsing: 'contains', indexed: true },
- * //   status: { type: 'string', filterUsing: '=', indexed: true },
- * //   created_at: { type: 'datetime', filterUsing: '>=', indexed: true }
- * // }
- * 
- * @example
- * // Example 2: Virtual fields for cross-table search
- * const searchSchema = {
- *   // Regular field
- *   name: { type: 'string', filterUsing: 'contains' },
- *   // Virtual field that searches in related table
- *   author_name: {
- *     type: 'string',
- *     filterUsing: 'contains',
- *     virtualField: {
- *       joinTo: 'users',
- *       joinOn: ['author_id', 'id'],
- *       searchField: 'name'
- *     }
- *   }
- * };
- * ensureSearchFieldsAreIndexed(searchSchema);
- * // Both fields are marked as indexed, enabling efficient joins
- * 
- * @example
- * // Example 3: Already indexed fields are not modified
- * const searchSchema = {
- *   email: { type: 'string', filterUsing: '=', indexed: false },  // Explicitly false
- *   username: { type: 'string', filterUsing: '=', indexed: true }  // Already true
- * };
- * ensureSearchFieldsAreIndexed(searchSchema);
- * // Results in:
- * // {
- * //   email: { type: 'string', filterUsing: '=', indexed: true },     // Overridden to true
- * //   username: { type: 'string', filterUsing: '=', indexed: true }   // Unchanged
- * // }
- * 
- * @example
- * // Example 4: Null or undefined searchSchema is safely handled
- * ensureSearchFieldsAreIndexed(null);      // No error, returns immediately
- * ensureSearchFieldsAreIndexed(undefined); // No error, returns immediately
- * ensureSearchFieldsAreIndexed({});        // Empty object remains empty
- * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API plugin uses this to:
- * // 1. Signal to storage plugins (like Knex) which fields need database indexes
- * // 2. Enable efficient filtering on search fields without full table scans
- * // 3. Support cross-table searches by ensuring join fields are indexed
- * // 4. Improve API response times for filtered queries
- * // 5. Allow storage plugins to create indexes automatically during migrations
- */
-export function ensureSearchFieldsAreIndexed(searchSchema) {
-  if (!searchSchema) return;
-  
-  Object.keys(searchSchema).forEach(fieldName => {
-    const fieldDef = searchSchema[fieldName];
-    if (fieldDef && typeof fieldDef === 'object') {
-      // Mark the field as indexed for cross-table search support
-      fieldDef.indexed = true;
-    }
-  });
-}
-
-/**
- * Generates a complete searchSchema by intelligently merging field definitions from the main schema
- * (fields with 'search' property) and an explicit searchSchema, with conflict detection.
- * 
- * This function is a cornerstone of the REST API's flexible search configuration. It allows
- * developers to define searchable fields in three ways:
- * 1. Inline in the schema with `search: true` or `search: { config }`
- * 2. In a separate explicit searchSchema
- * 3. As virtual fields in schema._virtual.search
- * 
- * The function performs intelligent merging while preventing conflicts that could lead to
- * ambiguous search behavior. It supports advanced search patterns like:
- * - Simple field searches with various operators (=, >, <, contains, etc.)
- * - Multiple filters from one field (e.g., date -> date_before, date_after)
- * - Virtual fields that don't exist in the database but map to searches
- * 
- * @param {Object} schema - The main resource schema that may contain fields with 'search' property
- * @param {Object} explicitSearchSchema - Optional explicit searchSchema to merge with
- * @returns {Object|null} The complete merged searchSchema, or null if no search fields defined
- * @throws {RestApiValidationError} If the same field is defined in multiple places
- * 
- * @example
- * // Example 1: Simple search fields in schema
- * const schema = {
- *   title: { type: 'string', search: true },              // Simple search
- *   content: { type: 'text' },                            // Not searchable
- *   status: { type: 'string', search: { filterUsing: '=' } }  // Custom operator
- * };
- * const searchSchema = generateSearchSchemaFromSchema(schema, null);
- * // Returns:
- * // {
- * //   title: { type: 'string', filterUsing: '=' },
- * //   status: { type: 'string', filterUsing: '=' }
- * // }
- * 
- * @example
- * // Example 2: Multiple filters from one field
- * const schema = {
- *   published_at: {
- *     type: 'datetime',
- *     search: {
- *       published_after: { filterUsing: '>=', type: 'datetime' },
- *       published_before: { filterUsing: '<=', type: 'datetime' }
- *     }
- *   }
- * };
- * const searchSchema = generateSearchSchemaFromSchema(schema, null);
- * // Returns:
- * // {
- * //   published_after: { 
- * //     type: 'datetime', 
- * //     actualField: 'published_at',  // Maps to real field
- * //     filterUsing: '>=' 
- * //   },
- * //   published_before: { 
- * //     type: 'datetime', 
- * //     actualField: 'published_at', 
- * //     filterUsing: '<=' 
- * //   }
- * // }
- * 
- * @example
- * // Example 3: Merging with explicit searchSchema
- * const schema = {
- *   name: { type: 'string', search: true }
- * };
- * const explicitSearchSchema = {
- *   email: { type: 'string', filterUsing: '=' },
- *   age: { type: 'number', filterUsing: '>=' }
- * };
- * const searchSchema = generateSearchSchemaFromSchema(schema, explicitSearchSchema);
- * // Returns:
- * // {
- * //   email: { type: 'string', filterUsing: '=' },    // From explicit
- * //   age: { type: 'number', filterUsing: '>=' },     // From explicit
- * //   name: { type: 'string', filterUsing: '=' }      // From schema
- * // }
- * 
- * @example
- * // Example 4: Conflict detection
- * const schema = {
- *   email: { type: 'string', search: true }
- * };
- * const explicitSearchSchema = {
- *   email: { type: 'string', filterUsing: 'contains' }
- * };
- * generateSearchSchemaFromSchema(schema, explicitSearchSchema);
- * // Throws RestApiValidationError:
- * // "Field 'email' is defined in both schema (with search: true) and explicit searchSchema."
- * 
- * @example
- * // Example 5: Virtual search fields
- * const schema = {
- *   title: { type: 'string' },
- *   _virtual: {
- *     search: {
- *       category_name: {
- *         type: 'string',
- *         filterUsing: 'contains',
- *         virtualField: {
- *           joinTo: 'categories',
- *           joinOn: ['category_id', 'id'],
- *           searchField: 'name'
- *         }
- *       }
- *     }
- *   }
- * };
- * const searchSchema = generateSearchSchemaFromSchema(schema, null);
- * // Returns:
- * // {
- * //   category_name: {
- * //     type: 'string',
- * //     filterUsing: 'contains',
- * //     virtualField: { ... }  // Virtual field config for cross-table search
- * //   }
- * // }
- * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API plugin uses this to:
- * // 1. Provide flexible search configuration without duplicating field definitions
- * // 2. Enable virtual fields that don't exist in the database (like category_name)
- * // 3. Support complex search patterns (date ranges, cross-table searches)
- * // 4. Validate search configuration at startup to catch errors early
- * // 5. Allow storage plugins to optimize queries based on search patterns
- * // 6. Enable API consumers to filter by related data without complex joins
- */
-export const generateSearchSchemaFromSchema = (schema, explicitSearchSchema) => {
-  // Start with explicit searchSchema or empty object
-  const searchSchema = explicitSearchSchema ? {...explicitSearchSchema} : {};
-  
-  if (!schema) {
-    return Object.keys(searchSchema).length > 0 ? searchSchema : null;
-  }
-  
-  // Process schema fields with 'search' property
-  Object.entries(schema).forEach(([fieldName, fieldDef]) => {
-    const effectiveSearch = fieldDef.search;
-    
-    if (effectiveSearch) {
-      if (effectiveSearch === true) {
-        // Check for conflicts with explicit searchSchema
-        if (searchSchema[fieldName]) {
-          throw new RestApiValidationError(
-            `Field '${fieldName}' is defined in both schema (with search: true) and explicit searchSchema. Remove one definition to avoid conflicts.`,
-            { 
-              fields: [fieldName],
-              violations: [{
-                field: fieldName,
-                rule: 'duplicate_search_field',
-                message: 'Field cannot be defined in both schema and searchSchema'
-              }]
-            }
-          );
-        }
-        
-        // Simple boolean - copy entire field definition (except search) and add filterUsing
-        const { search, ...fieldDefWithoutSearch } = fieldDef;
-        searchSchema[fieldName] = {
-          ...fieldDefWithoutSearch,
-          // Default filter behavior based on type
-          filterUsing: fieldDef.type === 'string' ? '=' : '='
-        };
-      } else if (typeof effectiveSearch === 'object') {
-        // Check if search defines multiple filter fields
-        const hasNestedFilters = Object.values(effectiveSearch).some(
-          v => typeof v === 'object' && v.filterUsing
-        );
-        
-        if (hasNestedFilters) {
-          // Multiple filters from one field (like published_after/before)
-          Object.entries(effectiveSearch).forEach(([filterName, filterDef]) => {
-            // Check for conflicts
-            if (searchSchema[filterName]) {
-              throw new RestApiValidationError(
-                `Field '${filterName}' is defined in both schema (with search) and explicit searchSchema. Remove one definition to avoid conflicts.`,
-                { 
-                  fields: [filterName],
-                  violations: [{
-                    field: filterName,
-                    rule: 'duplicate_search_field',
-                    message: 'Field cannot be defined in both schema and searchSchema'
-                  }]
-                }
-              );
-            }
-            
-            searchSchema[filterName] = {
-              type: fieldDef.type,
-              actualField: fieldName,
-              ...filterDef
-            };
-          });
-        } else {
-          // Check for conflicts
-          if (searchSchema[fieldName]) {
-            throw new RestApiValidationError(
-              `Field '${fieldName}' is defined in both schema (with search) and explicit searchSchema. Remove one definition to avoid conflicts.`,
-              { 
-                fields: [fieldName],
-                violations: [{
-                  field: fieldName,
-                  rule: 'duplicate_search_field',
-                  message: 'Field cannot be defined in both schema and searchSchema'
-                }]
-              }
-            );
-          }
-          
-          // Single filter with config
-          searchSchema[fieldName] = {
-            type: fieldDef.type,
-            ...effectiveSearch
-          };
-        }
-      }
-    }
-  });
-  
-  // Handle _virtual search definitions
-  if (schema._virtual?.search) {
-    Object.entries(schema._virtual.search).forEach(([filterName, filterDef]) => {
-      // Check for conflicts
-      if (searchSchema[filterName]) {
-        throw new RestApiValidationError(
-          `Field '${filterName}' is defined in both schema (_virtual.search) and explicit searchSchema. Remove one definition to avoid conflicts.`,
-          { 
-            fields: [filterName],
-            violations: [{
-              field: filterName,
-              rule: 'duplicate_search_field',
-              message: 'Field cannot be defined in both schema and searchSchema'
-            }]
-          }
-        );
-      }
-      
-      searchSchema[filterName] = filterDef;
-    });
-  }
-  
-  return Object.keys(searchSchema).length > 0 ? searchSchema : null;
-};