json-rest-api 1.0.6 → 1.0.8

package/plugins/core/lib/{simplified-helpers.js → querying-writing/simplified-helpers.js}

@@ -1,34 +1,30 @@
 /**
- * @module simplifiedHelpers
- * @description Transformation functions for converting between simplified and JSON:API formats
+ * Transformation functions for simplified API mode
  * 
- * This module enables the REST API's "simplified mode" feature, which provides a more
- * developer-friendly alternative to the verbose JSON:API format. It allows APIs to
- * accept and return plain JavaScript objects while still maintaining JSON:API
- * compliance internally.
+ * @description
+ * This module enables "simplified mode" - a developer-friendly alternative
+ * to verbose JSON:API format. It allows APIs to:
+ * - Accept plain JavaScript objects as input
+ * - Return flat response objects instead of nested JSON:API
+ * - Automatically convert between formats transparently
+ * - Maintain JSON:API compliance internally
  */
 
-import { RestApiValidationError } from '../../../lib/rest-api-errors.js';
+import { RestApiValidationError } from '../../../../lib/rest-api-errors.js';
 
 /**
- * Transforms a simplified plain JavaScript object into a JSON:API compliant format.
- * 
- * This function is crucial for the REST API's "simplified mode" feature, which allows
- * developers to work with familiar plain objects instead of the verbose JSON:API format.
- * It intelligently converts plain objects into properly structured JSON:API documents
- * by analyzing the schema to determine what fields are attributes vs relationships.
- * 
- * @param {Object} scope - The scope object containing the input data to transform
- * @param {Object} scope.inputRecord - The input object to transform (plain object or already JSON:API)
- * @param {Object} deps - The dependencies object
- * @param {Object} deps.context - The context object containing configuration
- * @param {string} deps.context.scopeName - The resource type name (e.g., 'articles', 'users')
- * @param {Object} deps.context.schemaStructure - The resource schema defining field types and relationships
- * @param {Object} deps.context.schemaRelationships - The relationships configuration for the resource
- * @returns {Object} A properly formatted JSON:API document
+ * Transforms simplified plain object into JSON:API format
+ * 
+ * @param {Object} scope - Scope containing input data
+ * @param {Object} scope.inputRecord - Plain object or JSON:API document
+ * @param {Object} deps - Dependencies with context
+ * @param {string} deps.context.scopeName - Resource type name
+ * @param {Object} deps.context.schemaStructure - Schema with field definitions
+ * @param {Object} deps.context.schemaRelationships - Relationship configurations
+ * @returns {Object} JSON:API formatted document
  * 
  * @example
- * // Example 1: Simple object with attributes only
+ * // Input: Simple object with only attributes
  * const input = {
  *   id: '123',
  *   title: 'My Article',
@@ -36,9 +32,10 @@ import { RestApiValidationError } from '../../../lib/rest-api-errors.js';
  * };
  * const result = transformSimplifiedToJsonApi(
  *   { inputRecord: input },
- *   { context: { scopeName: 'articles', schemaStructure: schema, schemaRelationships: relationships } }
+ *   { context: { scopeName: 'articles', schemaStructure: schema } }
  * );
- * // Returns:
+ * 
+ * // Output: Proper JSON:API structure
  * // {
  * //   data: {
  * //     type: 'articles',
@@ -51,7 +48,7 @@ import { RestApiValidationError } from '../../../lib/rest-api-errors.js';
  * // }
  * 
  * @example
- * // Example 2: Object with belongsTo relationship (using foreign key name)
+ * // Input: Object with foreign key (traditional way)
  * const schema = {
  *   title: { type: 'string' },
  *   author_id: { 
@@ -63,22 +60,19 @@ import { RestApiValidationError } from '../../../lib/rest-api-errors.js';
  * const input = {
  *   id: '456',
  *   title: 'Another Article',
- *   author_id: 789 // Original way: using foreign key name
+ *   author_id: 789                      // Using foreign key name
  * };
- * const result = transformSimplifiedToJsonApi(
- *   { inputRecord: input },
- *   { context: { scopeName: 'articles', schemaStructure: schema, schemaRelationships: relationships } }
- * );
- * // Returns:
+ * 
+ * // Output: Foreign key becomes relationship
  * // {
  * //   data: {
  * //     type: 'articles',
  * //     id: '456',
  * //     attributes: {
- * //       title: 'Another Article'
+ * //       title: 'Another Article'       // author_id removed
  * //     },
  * //     relationships: {
- * //       author: {
+ * //       author: {                      // Uses 'as' name
  * //         data: { type: 'users', id: '789' }
  * //       }
  * //     }
@@ -86,28 +80,16 @@ import { RestApiValidationError } from '../../../lib/rest-api-errors.js';
  * // }
  *
  * @example
- * // Example 3: Object with belongsTo relationship (using 'as' alias - NEW desired behavior)
- * const schema = {
- *   title: { type: 'string' },
- *   author_id: {
- *     type: 'number',
- *     belongsTo: 'users',
- *     as: 'author'
- *   }
- * };
+ * // Input: Object with relationship alias (preferred way)
  * const input = {
  *   id: '456',
  *   title: 'Another Article',
- *   author: 789 // NEW way: using the 'as' alias
+ *   author: 789                         // Using 'as' alias directly
  * };
- * const result = transformSimplifiedToJsonApi(
- *   { inputRecord: input },
- *   { context: { scopeName: 'articles', schemaStructure: schema, schemaRelationships: relationships } }
- * );
- * // Returns the same JSON:API structure as above
+ * // Output: Same JSON:API structure as above
  *
  * @example
- * // Example 4: Object with many-to-many relationship
+ * // Input: Many-to-many relationship
  * const relationships = {
  *   tags: {
  *     manyToMany: {
@@ -120,13 +102,10 @@ import { RestApiValidationError } from '../../../lib/rest-api-errors.js';
  * };
  * const input = {
  *   title: 'Tagged Article',
- *   tags: ['10', '20', '30']  // Array of tag IDs
+ *   tags: ['10', '20', '30']            // Array of IDs
  * };
- * const result = transformSimplifiedToJsonApi(
- *   { inputRecord: input },
- *   { context: { scopeName: 'articles', schemaStructure: schema, schemaRelationships: relationships } }
- * );
- * // Returns:
+ * 
+ * // Output: Array becomes relationship data array
  * // {
  * //   data: {
  * //     type: 'articles',
@@ -146,7 +125,7 @@ import { RestApiValidationError } from '../../../lib/rest-api-errors.js';
  * // }
  * 
  * @example
- * // Example 5: Already JSON:API formatted - returns as-is
+ * // Input: Already JSON:API formatted
  * const input = {
  *   data: {
  *     type: 'articles',
@@ -154,19 +133,27 @@ import { RestApiValidationError } from '../../../lib/rest-api-errors.js';
  *     attributes: { title: 'Already formatted' }
  *   }
  * };
- * const result = transformSimplifiedToJsonApi(
- *   { inputRecord: input },
- *   { context: { scopeName: 'articles', schemaStructure: schema, schemaRelationships: relationships } }
- * );
- * // Returns the same object unchanged
- * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API plugin uses this to:
- * // 1. Accept familiar plain objects from API consumers (better DX)
- * // 2. Automatically convert foreign keys to proper relationships
- * // 3. Support both simple and JSON:API formats in the same endpoint
- * // 4. Reduce boilerplate in client applications
- * // 5. Maintain JSON:API compliance internally for consistency
+ * // Output: Returned unchanged (detected by data.type)
+ * 
+ * @description
+ * Used by:
+ * - rest-api-plugin for POST/PUT/PATCH when simplified: true
+ * - Processes input before validation and storage
+ * 
+ * Purpose:
+ * - Provides developer-friendly plain object API
+ * - Automatically detects and converts relationships
+ * - Supports both foreign key and alias notation
+ * - Maintains JSON:API compliance internally
+ * - Allows gradual migration from simple to JSON:API
+ * 
+ * Data flow:
+ * 1. Checks if already JSON:API (has data.type)
+ * 2. Extracts ID from input object
+ * 3. Processes belongsTo relationships from schema
+ * 4. Processes hasMany/manyToMany from relationships
+ * 5. Remaining fields become attributes
+ * 6. Builds proper JSON:API document structure
  */
 export const transformSimplifiedToJsonApi = (scope, deps) => {
   // Extract needed values from scope and deps
@@ -267,29 +254,18 @@ export const transformSimplifiedToJsonApi = (scope, deps) => {
 };
 
 /**
- * Transforms a JSON:API formatted response into a simplified plain JavaScript object.
- * 
- * This function reverses the work of transformSimplifiedToJsonApi, converting verbose
- * JSON:API documents back into simple, flat JavaScript objects that are easier to work
- * with in application code. It handles both single resources and collections, and can
- * optionally expand included resources inline.
- * 
- * The transformation process:
- * 1. Flattens attributes directly onto the result object
- * 2. Converts belongsTo relationships back to foreign key fields (e.g., author -> author_id)
- * 3. Extracts many-to-many relationship IDs into arrays (e.g., tags -> tags_ids)
- * 4. Optionally expands included resources inline for convenient access
- * 
- * @param {Object} scope - The scope object containing the JSON:API response
- * @param {Object} scope.record - The JSON:API response to transform
- * @param {Object} deps - The dependencies object
- * @param {Object} deps.context - The context object containing configuration
- * @param {Object} deps.context.schemaStructure - The resource schema for mapping relationships back to fields
- * @param {Object} deps.context.schemaRelationships - The relationships configuration
- * @returns {Object|Array} Simplified object(s) - single object or array depending on input
+ * Transforms JSON:API response into simplified plain object
+ * 
+ * @param {Object} scope - Scope containing JSON:API response
+ * @param {Object} scope.record - JSON:API document to transform
+ * @param {Object} deps - Dependencies with context
+ * @param {Object} deps.context.schemaStructure - Schema for mapping relationships
+ * @param {Object} deps.context.schemaRelationships - Relationship configurations
+ * @param {Object} deps.context.scopes - All scopes for nested transformations
+ * @returns {Object|Object[]} Simplified object or array of objects
  * 
  * @example
- * // Example 1: Single resource with attributes
+ * // Input: Single resource JSON:API
  * const jsonApi = {
  *   data: {
  *     type: 'articles',
@@ -302,17 +278,18 @@ export const transformSimplifiedToJsonApi = (scope, deps) => {
  * };
  * const result = transformJsonApiToSimplified(
  *   { record: jsonApi },
- *   { context: { schemaStructure: schema, schemaRelationships: relationships } }
+ *   { context: { schemaStructure: schema } }
  * );
- * // Returns:
+ * 
+ * // Output: Flattened object
  * // {
  * //   id: '123',
- * //   title: 'My Article',
+ * //   title: 'My Article',        // Attributes flattened
  * //   content: 'Content here'
  * // }
  * 
  * @example
- * // Example 2: Resource with belongsTo relationship
+ * // Input: Resource with belongsTo relationship
  * const schema = {
  *   title: { type: 'string' },
  *   author_id: { type: 'number', belongsTo: 'users', as: 'author' }
@@ -329,19 +306,16 @@ export const transformSimplifiedToJsonApi = (scope, deps) => {
  *     }
  *   }
  * };
- * const result = transformJsonApiToSimplified(
- *   { record: jsonApi },
- *   { context: { schemaStructure: schema, schemaRelationships: relationships } }
- * );
- * // Returns:
+ * 
+ * // Output: Relationship becomes foreign key
  * // {
  * //   id: '456',
  * //   title: 'Article with Author',
- * //   author_id: '789'  // Foreign key restored
+ * //   author_id: '789'              // Restored from relationship
  * // }
  * 
  * @example
- * // Example 3: Collection of resources
+ * // Input: Collection response
  * const jsonApi = {
  *   data: [
  *     {
@@ -354,20 +328,23 @@ export const transformSimplifiedToJsonApi = (scope, deps) => {
  *       id: '2',
  *       attributes: { title: 'Second Article' }
  *     }
- *   ]
+ *   ],
+ *   meta: { total: 2 },
+ *   links: { next: '/articles?page=2' }
  * };
- * const result = transformJsonApiToSimplified(
- *   { record: jsonApi },
- *   { context: { schemaStructure: schema, schemaRelationships: relationships } }
- * );
- * // Returns:
- * // [
- * //   { id: '1', title: 'First Article' },
- * //   { id: '2', title: 'Second Article' }
- * // ]
+ * 
+ * // Output: Preserves meta and links
+ * // {
+ * //   data: [
+ * //     { id: '1', title: 'First Article' },
+ * //     { id: '2', title: 'Second Article' }
+ * //   ],
+ * //   meta: { total: 2 },
+ * //   links: { next: '/articles?page=2' }
+ * // }
  *
  * @example
- * // Example 4: Resource with included data expanded
+ * // Input: With included resources
  * const jsonApi = {
  *   data: {
  *     type: 'articles',
@@ -389,7 +366,7 @@ export const transformSimplifiedToJsonApi = (scope, deps) => {
  *     {
  *       type: 'authors',
  *       id: '75',
- *       attributes: { name: 'Jane Smith', bio: 'Expert developer' }
+ *       attributes: { name: 'Jane Smith' }
  *     },
  *     {
  *       type: 'chapters',
@@ -403,78 +380,96 @@ export const transformSimplifiedToJsonApi = (scope, deps) => {
  *     }
  *   ]
  * };
- * const result = transformJsonApiToSimplified(
- *   { record: jsonApi },
- *   { context: { schemaStructure: schema, schemaRelationships: relationships } }
- * );
- * // Returns:
+ * 
+ * // Output: Expands included resources
  * // {
  * //   id: '400',
  * //   title: 'JavaScript Guide',
  * //   author_id: '75',
- * //   author: {  // Expanded from included
+ * //   author: {                    // Expanded from included
  * //     id: '75',
- * //     name: 'Jane Smith',
- * //     bio: 'Expert developer'
+ * //     name: 'Jane Smith'
  * //   },
  * //   chapters_ids: ['1001', '1002'],
- * //   chapters: [ // Expanded array from included
+ * //   chapters: [                  // Expanded array
  * //     { id: '1001', number: 1, title: 'Introduction' },
  * //     { id: '1002', number: 2, title: 'Basics' }
  * //   ]
  * // }
  *
- * @private
+ * @description
+ * Used by:
+ * - rest-api-plugin for GET/QUERY when simplified: true
+ * - Transforms responses before sending to client
+ * 
+ * Purpose:
+ * - Provides cleaner response format for clients
+ * - Restores foreign keys from relationships
+ * - Expands included resources for convenience
+ * - Maintains compatibility with collection metadata
+ * - Handles both single and array responses
+ * 
+ * Data flow:
+ * 1. Detects array vs single resource
+ * 2. For arrays, preserves meta/links at root
+ * 3. Calls transformSingleJsonApiToSimplified for each
+ * 4. Returns simplified structure
  */
 export const transformJsonApiToSimplified = (scope, deps) => {
   // Extract needed values from scope and deps
   const jsonApi = scope.record;
   const schema = deps.context.schemaStructure;
   const relationships = deps.context.schemaRelationships;
+  const scopes = deps.context.scopes;
 
   if (!jsonApi?.data) return jsonApi;
 
   // Handle array response (QUERY)
   if (Array.isArray(jsonApi.data)) {
-    return jsonApi.data.map(item =>
+    const simplifiedData = jsonApi.data.map(item =>
       transformSingleJsonApiToSimplified(
         { data: item, included: jsonApi.included },
-        { context: { schemaStructure: schema, schemaRelationships: relationships } }
+        { context: { schemaStructure: schema, schemaRelationships: relationships, scopes } }
       )
     );
+    
+    // For query results, return object with data, meta, and links
+    const result = { data: simplifiedData };
+    
+    // Add meta if present
+    if (jsonApi.meta) {
+      result.meta = jsonApi.meta;
+    }
+    
+    // Add links if present
+    if (jsonApi.links) {
+      result.links = jsonApi.links;
+    }
+    
+    return result;
   }
 
-  // Handle single response
+  // Handle single response (no change for single resources)
   return transformSingleJsonApiToSimplified(
     { data: jsonApi.data, included: jsonApi.included },
-    { context: { schemaStructure: schema, schemaRelationships: relationships } }
+    { context: { schemaStructure: schema, schemaRelationships: relationships, scopes } }
   );
 };
 
 /**
- * Transforms a single JSON:API resource object into a simplified format.
+ * Transforms single JSON:API resource into simplified format
  * 
- * This is the workhorse function that handles the actual transformation logic for
- * individual resources. It's used by transformJsonApiToSimplified for both single
- * resources and each item in a collection.
- * 
- * The transformation includes:
- * - Flattening the id and attributes onto the root object
- * - Converting relationship references back to foreign key fields
- * - Extracting many-to-many relationship IDs into _ids arrays
- * - Expanding included related resources when available
- * 
- * @param {Object} scope - The scope object containing the data
+ * @param {Object} scope - Scope with data and included resources
  * @param {Object} scope.data - Single JSON:API resource object
- * @param {Array} scope.included - Array of included resources from JSON:API response
- * @param {Object} deps - The dependencies object
- * @param {Object} deps.context - The context object containing configuration
- * @param {Object} deps.context.schemaStructure - Resource schema for field mappings
- * @param {Object} deps.context.schemaRelationships - Relationships configuration
+ * @param {Array} scope.included - Array of included resources
+ * @param {Object} deps - Dependencies with context
+ * @param {Object} deps.context.schemaStructure - Resource schema
+ * @param {Object} deps.context.schemaRelationships - Relationship configs
+ * @param {Object} deps.context.scopes - All scopes for recursion
  * @returns {Object} Simplified plain object
  * 
  * @example
- * // Example 1: Basic transformation with relationships
+ * // Input: Basic resource with relationships
  * const data = {
  *   type: 'comments',
  *   id: '100',
@@ -499,19 +494,20 @@ export const transformJsonApiToSimplified = (scope, deps) => {
  * };
  * const result = transformSingleJsonApiToSimplified(
  *   { data: data, included: null },
- *   { context: { schemaStructure: schema, schemaRelationships: {} } }
+ *   { context: { schemaStructure: schema } }
  * );
- * // Returns:
+ * 
+ * // Output: Flattened with foreign keys restored
  * // {
  * //   id: '100',
  * //   text: 'Great article!',
  * //   created_at: '2024-01-15',
- * //   author_id: '50',    // Restored from relationships.author
- * //   article_id: '200'   // Restored from relationships.article
+ * //   author_id: '50',          // From relationships.author
+ * //   article_id: '200'         // From relationships.article
  * // }
  * 
  * @example
- * // Example 2: Many-to-many relationships become ID arrays
+ * // Input: Many-to-many relationships
  * const data = {
  *   type: 'articles',
  *   id: '300',
@@ -529,19 +525,16 @@ export const transformJsonApiToSimplified = (scope, deps) => {
  * const relationships = {
  *   tags: { manyToMany: { via: 'article_tags' } }
  * };
- * const result = transformSingleJsonApiToSimplified(
- *   { data: data, included: null },
- *   { context: { schemaStructure: {}, schemaRelationships: relationships } }
- * );
- * // Returns:
+ * 
+ * // Output: Array of IDs with _ids suffix
  * // {
  * //   id: '300',
  * //   title: 'My Article',
- * //   tags_ids: ['1', '2', '3']  // Array of IDs with _ids suffix
+ * //   tags_ids: ['1', '2', '3']   // Relationship name + _ids
  * // }
  * 
  * @example
- * // Example 3: Expanding included resources
+ * // Input: With included resources (recursive expansion)
  * const data = {
  *   type: 'books',
  *   id: '400',
@@ -562,7 +555,12 @@ export const transformJsonApiToSimplified = (scope, deps) => {
  *   {
  *     type: 'authors',
  *     id: '75',
- *     attributes: { name: 'Jane Smith', bio: 'Expert developer' }
+ *     attributes: { name: 'Jane Smith' },
+ *     relationships: {
+ *       company: {
+ *         data: { type: 'companies', id: '5' }
+ *       }
+ *     }
  *   },
  *   {
  *     type: 'chapters',
@@ -575,27 +573,47 @@ export const transformJsonApiToSimplified = (scope, deps) => {
  *     attributes: { number: 2, title: 'Basics' }
  *   }
  * ];
- * const result = transformSingleJsonApiToSimplified(
- *   { data: data, included: included },
- *   { context: { schemaStructure: schema, schemaRelationships: relationships } }
- * );
- * // Returns:
+ * 
+ * // Output: Recursively expanded (note author.company_id)
  * // {
  * //   id: '400',
  * //   title: 'JavaScript Guide',
  * //   author_id: '75',
- * //   author: {  // Expanded from included
+ * //   author: {                    // Expanded and transformed
  * //     id: '75',
  * //     name: 'Jane Smith',
- * //     bio: 'Expert developer'
+ * //     company_id: '5'            // Author's relationships processed!
  * //   },
  * //   chapters_ids: ['1001', '1002'],
- * //   chapters: [  // Expanded array from included
+ * //   chapters: [
  * //     { id: '1001', number: 1, title: 'Introduction' },
  * //     { id: '1002', number: 2, title: 'Basics' }
  * //   ]
  * // }
  * 
+ * @description
+ * Used by:
+ * - transformJsonApiToSimplified for each resource
+ * - Calls itself recursively for included resources
+ * 
+ * Purpose:
+ * - Core transformation logic for single resources
+ * - Restores foreign keys from relationships
+ * - Creates _ids arrays for to-many relationships
+ * - Recursively expands and transforms included data
+ * - Handles polymorphic relationships
+ * 
+ * Data flow:
+ * 1. Copies ID and attributes to result
+ * 2. Processes each relationship:
+ *    - BelongsTo: restores foreign key field
+ *    - Polymorphic: restores type and ID fields
+ *    - HasMany/ManyToMany: creates _ids array
+ * 3. If included data exists:
+ *    - Finds matching included resources
+ *    - Recursively transforms them (preserving their relationships!)
+ *    - Adds transformed objects/arrays to result
+ * 
  * @private
  */
 export const transformSingleJsonApiToSimplified = (scope, deps) => {
@@ -604,6 +622,7 @@ export const transformSingleJsonApiToSimplified = (scope, deps) => {
   const included = scope.included;
   const schema = deps.context.schemaStructure;
   const relationships = deps.context.schemaRelationships;
+  const scopes = deps.context.scopes;
 
   const simplified = {};
 
@@ -628,8 +647,16 @@ export const transformSingleJsonApiToSimplified = (scope, deps) => {
         }
       }
 
-      // Handle many-to-many (just IDs, not nested)
+      // Check if this is a polymorphic relationship from the relationships config
       const rel = relationships?.[relName];
+      if (rel?.belongsToPolymorphic && relData.data) {
+        // For polymorphic relationships, restore both the type and id fields
+        const { typeField, idField } = rel.belongsToPolymorphic;
+        simplified[typeField] = relData.data.type;
+        simplified[idField] = relData.data.id;
+      }
+
+      // Handle many-to-many (just IDs, not nested)
       if (rel?.hasMany || rel?.manyToMany) {
         if (relData.data && Array.isArray(relData.data)) {
           simplified[`${relName}_ids`] = relData.data.map(item => item.id);
@@ -644,18 +671,31 @@ export const transformSingleJsonApiToSimplified = (scope, deps) => {
         if (Array.isArray(relData.data)) {
           const nestedData = relData.data.map(findIncluded).filter(Boolean);
           if (nestedData.length > 0) {
-            simplified[relName] = nestedData.map(item => ({
-              id: item.id,
-              ...item.attributes
-            }));
+            simplified[relName] = nestedData.map(item => {
+              // For each included record, transform it recursively to restore its relationship fields
+              const itemSimplified = transformSingleJsonApiToSimplified(
+                { data: item, included: null },
+                { context: { 
+                  schemaStructure: scopes?.[item.type]?.vars?.schemaInfo?.schema || {},
+                  schemaRelationships: scopes?.[item.type]?.vars?.schemaInfo?.schemaRelationships || {},
+                  scopes
+                } }
+              );
+              return itemSimplified;
+            });
           }
         } else {
           const nestedData = findIncluded(relData.data);
           if (nestedData) {
-            simplified[relName] = {
-              id: nestedData.id,
-              ...nestedData.attributes
-            };
+            // Transform the single included record to restore its relationship fields
+            simplified[relName] = transformSingleJsonApiToSimplified(
+              { data: nestedData, included: null },
+              { context: { 
+                schemaStructure: scopes?.[nestedData.type]?.vars?.schemaInfo?.schema || {},
+                schemaRelationships: scopes?.[nestedData.type]?.vars?.schemaInfo?.schemaRelationships || {},
+                scopes
+              } }
+            );
           }
         }
       }