json-rest-api 1.0.6 → 1.0.8

package/plugins/core/lib/{knex-relationship-includes.js → querying/knex-relationship-includes.js}

@@ -1,85 +1,144 @@
 /**
- * @module relationship-includes
- * @description JSON:API relationship inclusion helpers for REST API Knex Plugin
+ * Provides utilities for loading related resources according to JSON:API specification
  * 
- * This module provides utilities for loading related resources according to the JSON:API
- * specification. It supports:
- * - Single-level includes (e.g., "author")
- * - Nested includes (e.g., "comments.author")  
- * - Many-to-one relationships (belongsTo)
- * - One-to-many relationships (hasMany)
- * - Polymorphic relationships (belongsToPolymorphic)
- * - Reverse polymorphic relationships (hasMany with via)
- * - Automatic deduplication of included resources
- * - Efficient batch loading to prevent N+1 queries
+ * @description
+ * This module implements the JSON:API include functionality, enabling compound documents
+ * that contain both primary data and related resources. It handles all relationship types
+ * and supports arbitrary nesting depths while preventing N+1 query problems.
  * 
- * @example <caption>Basic single-level include</caption>
+ * @example
+ * // Input: Simple include request
  * // GET /articles?include=author
- * // Loads all articles and their authors in 2 queries total
+ * // Records before:
+ * [
+ *   { id: 1, title: 'Article 1', author_id: 10 },
+ *   { id: 2, title: 'Article 2', author_id: 11 }
+ * ]
  * 
- * @example <caption>Multiple includes</caption>
- * // GET /articles?include=author,comments
- * // Loads articles, all authors, and all comments in 3 queries total
+ * // Result: 2 queries total (articles + authors)
+ * // Records after (with RELATIONSHIPS_KEY):
+ * [
+ *   { 
+ *     id: 1, 
+ *     title: 'Article 1', 
+ *     author_id: 10,
+ *     __$jsonrestapi_rel$__: {
+ *       author: { data: { type: 'users', id: '10' } }
+ *     }
+ *   }
+ * ]
+ * // Included resources:
+ * [
+ *   { type: 'users', id: '10', attributes: { name: 'John' } },
+ *   { type: 'users', id: '11', attributes: { name: 'Jane' } }
+ * ]
  * 
- * @example <caption>Nested includes</caption>
+ * @example
+ * // Input: Nested includes
  * // GET /articles?include=comments.author
- * // Loads articles, their comments, and comment authors in 3 queries total
+ * // Articles → Comments → Authors (3 queries total)
+ * 
+ * // Result: Comments loaded with their authors
+ * // Included array contains both comments AND their authors
+ * // No duplicate authors even if multiple comments by same person
+ * 
+ * @example  
+ * // Input: Polymorphic includes
+ * // GET /activities?include=trackable
+ * // Where trackable can be 'posts', 'photos', or 'videos'
  * 
- * @example <caption>Complex nested includes</caption>
- * // GET /articles?include=author,comments.author,comments.article
- * // Handles circular references automatically through deduplication
+ * // Groups by type and loads each type separately:
+ * // Query 1: SELECT * FROM posts WHERE id IN (1, 3, 5)
+ * // Query 2: SELECT * FROM photos WHERE id IN (2, 4)
+ * // Query 3: SELECT * FROM videos WHERE id IN (6)
  * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API Knex plugin uses this module to:
- * // 1. Implement JSON:API compound documents (main data + included resources)
- * // 2. Prevent N+1 query problems through batch loading strategies
- * // 3. Support arbitrarily deep relationship nesting (e.g., article.author.company.country)
- * // 4. Handle polymorphic relationships that can point to multiple types
- * // 5. Deduplicate included resources automatically (no duplicate authors if multiple articles have same author)
- * // 6. Apply sparse fieldsets to included resources for bandwidth optimization
- * // 7. Maintain referential integrity by only loading existing relationships
- * // 8. Use mutual recursion for elegant handling of complex include trees
- * // 9. Support both forward (belongsTo/hasMany) and reverse (via) relationships
+ * Used by:
+ * - rest-api-knex-plugin calls buildIncludedResources in dataGet and dataQuery
+ * - Called after primary records are fetched but before response assembly
+ * - Results go into the 'included' section of JSON:API response
+ * 
+ * Purpose:
+ * - Implements JSON:API compound documents with primary data and included resources
+ * - Prevents N+1 queries through batch loading (1 query per resource type)
+ * - Supports deep nesting like article.author.company.country.continent
+ * - Deduplicates resources automatically (each resource appears once)
+ * - Handles circular references through processedPaths tracking
+ * - Applies sparse fieldsets to reduce payload size
+ * 
+ * Data flow:
+ * 1. Parse include parameter into tree structure (author,comments.author)
+ * 2. For each relationship, determine type (belongsTo, hasMany, polymorphic)
+ * 3. Batch load all related records of same type in single query
+ * 4. Recursively process nested includes
+ * 5. Store all included resources in deduplication Map
+ * 6. Return array of unique included resources
  */
 
-import { getForeignKeyFields, buildFieldSelection } from './knex-field-helpers.js';
-import { toJsonApi } from './knex-json-api-helpers.js';
+import { buildFieldSelection } from '../querying-writing/knex-field-helpers.js';
+import { getForeignKeyFields } from '../querying-writing/field-utils.js';
+import { toJsonApiRecord } from './knex-json-api-transformers-querying.js';
 import { buildWindowedIncludeQuery, applyStandardIncludeConfig, buildOrderByClause } from './knex-window-queries.js';
-import { RELATIONSHIPS_KEY, RELATIONSHIP_METADATA_KEY, ROW_NUMBER_KEY, DEFAULT_QUERY_LIMIT } from '../utils/knex-constants.js';
-import { RestApiResourceError } from '../../../lib/rest-api-errors.js';
+import { RELATIONSHIPS_KEY, RELATIONSHIP_METADATA_KEY, ROW_NUMBER_KEY, COMPUTED_DEPENDENCIES_KEY, DEFAULT_QUERY_LIMIT } from '../querying-writing/knex-constants.js';
+import { RestApiResourceError } from '../../../../lib/rest-api-errors.js';
 
 /**
  * Groups records by their polymorphic type for efficient batch loading
  * 
- * Used when loading includes to minimize database queries. Instead of making
- * N queries (one per record), this groups records by type so we can make
- * one query per type.
- * 
  * @param {Array<Object>} records - Records containing polymorphic fields
  * @param {string} typeField - Name of the type field (e.g., 'commentable_type')
  * @param {string} idField - Name of the ID field (e.g., 'commentable_id')
  * @returns {Object<string, Array<number|string>>} Map of type to array of unique IDs
  * 
- * @example <caption>Basic grouping</caption>
+ * @example
+ * // Input: Comments with polymorphic commentable relationship
  * const records = [
  *   { id: 1, commentable_type: 'articles', commentable_id: 10 },
  *   { id: 2, commentable_type: 'videos', commentable_id: 20 },
- *   { id: 3, commentable_type: 'articles', commentable_id: 11 }
+ *   { id: 3, commentable_type: 'articles', commentable_id: 11 },
+ *   { id: 4, commentable_type: 'articles', commentable_id: 10 }  // Duplicate
  * ];
  * 
  * const grouped = groupByPolymorphicType(records, 'commentable_type', 'commentable_id');
- * // Returns: { articles: [10, 11], videos: [20] }
  * 
- * @example <caption>Handles null values</caption>
+ * // Output: IDs grouped by type, duplicates removed
+ * // {
+ * //   articles: [10, 11],  // Only unique IDs
+ * //   videos: [20]
+ * // }
+ * 
+ * @example
+ * // Input: Some records have null relationships
  * const records = [
  *   { id: 1, item_type: 'products', item_id: 1 },
- *   { id: 2, item_type: null, item_id: null },
- *   { id: 3, item_type: 'products', item_id: 2 }
+ *   { id: 2, item_type: null, item_id: null },      // Ignored
+ *   { id: 3, item_type: 'products', item_id: null }, // Ignored
+ *   { id: 4, item_type: 'categories', item_id: 5 }
  * ];
  * 
  * const grouped = groupByPolymorphicType(records, 'item_type', 'item_id');
- * // Returns: { products: [1, 2] }
- * // Null values are filtered out
+ * 
+ * // Output: Only records with both type AND id
+ * // {
+ * //   products: [1],
+ * //   categories: [5]
+ * // }
+ * 
+ * @description
+ * Used by:
+ * - loadPolymorphicBelongsTo uses this to group records before batch loading
+ * - Enables efficient loading with one query per type instead of per record
+ * 
+ * Purpose:
+ * - Minimizes database queries when loading polymorphic relationships
+ * - Instead of N queries (one per record), makes T queries (one per type)
+ * - Automatically deduplicates IDs within each type
+ * - Safely handles null/undefined values by filtering them out
+ * 
+ * Data flow:
+ * 1. Receives array of records with polymorphic fields
+ * 2. Groups records by their type field value
+ * 3. Collects unique IDs for each type
+ * 4. Returns map used for batch WHERE IN queries
  */
 export const groupByPolymorphicType = (records, typeField, idField) => {
   const grouped = {};
@@ -107,27 +166,63 @@ export const groupByPolymorphicType = (records, typeField, idField) => {
 /**
  * Parses the include parameter string into a tree structure
  * 
- * Converts comma-separated include strings with dot notation into a nested
- * object structure that makes it easier to process relationships hierarchically.
- * 
- * @param {string} includeParam - The include parameter value (e.g., "author,comments.author,comments.article")
+ * @param {string|Array<string>} includeParam - The include parameter value
  * @returns {Object} Nested object representing the include tree
  * 
- * @example <caption>Simple includes</caption>
- * parseIncludeTree('author,comments')
- * // Returns: { author: {}, comments: {} }
+ * @example
+ * // Input: Simple comma-separated includes
+ * const tree = parseIncludeTree('author,comments');
  * 
- * @example <caption>Nested includes</caption>
- * parseIncludeTree('comments.author,comments.article')
- * // Returns: { comments: { author: {}, article: {} } }
+ * // Output: Flat structure
+ * // {
+ * //   author: {},
+ * //   comments: {}
+ * // }
  * 
- * @example <caption>Mixed levels</caption>
- * parseIncludeTree('author,comments.author,publisher.country')
- * // Returns: {
+ * @example
+ * // Input: Nested includes with dot notation
+ * const tree = parseIncludeTree('comments.author,comments.replies');
+ * 
+ * // Output: Nested structure
+ * // {
+ * //   comments: {
+ * //     author: {},
+ * //     replies: {}
+ * //   }
+ * // }
+ * 
+ * @example
+ * // Input: Complex mixed-depth includes
+ * const tree = parseIncludeTree('author,comments.author,comments.replies.author,tags');
+ * 
+ * // Output: Multi-level nesting
+ * // {
  * //   author: {},
- * //   comments: { author: {} },
- * //   publisher: { country: {} }
+ * //   comments: {
+ * //     author: {},
+ * //     replies: {
+ * //       author: {}
+ * //     }
+ * //   },
+ * //   tags: {}
  * // }
+ * 
+ * @description
+ * Used by:
+ * - buildIncludedResources parses the include parameter before processing
+ * - processIncludes traverses this tree structure recursively
+ * 
+ * Purpose:
+ * - Converts flat string format into hierarchical structure for processing
+ * - Enables recursive traversal of relationship includes
+ * - Handles both string and pre-split array inputs
+ * - Empty values are filtered out automatically
+ * 
+ * Data flow:
+ * 1. Split comma-separated string into individual paths
+ * 2. For each path, split by dots to get nesting levels
+ * 3. Build nested object structure following the path
+ * 4. Return tree for recursive processing
  */
 export const parseIncludeTree = (includeParam) => {
   if (!includeParam) return {};
@@ -197,22 +292,18 @@ const loadRelationshipMetadata = async (scopes, records, scopeName) => {
         if (relDef.hasMany) {
           // Add empty relationship data - will be populated if explicitly included
           record[RELATIONSHIP_METADATA_KEY][relName] = { data: [] };
-        }
-      }
-      
-      // Process belongsToPolymorphic relationships from schema
-      for (const [fieldName, fieldDef] of Object.entries(schema)) {
-        if (fieldDef.belongsToPolymorphic && fieldDef.as) {
-          const { typeField, idField } = fieldDef.belongsToPolymorphic;
+        } else if (relDef.belongsToPolymorphic) {
+          // Process polymorphic relationships defined in relationships section
+          const { typeField, idField } = relDef.belongsToPolymorphic;
           const type = record[typeField];
           const id = record[idField];
           
           if (type && id) {
-            record[RELATIONSHIP_METADATA_KEY][fieldDef.as] = {
+            record[RELATIONSHIP_METADATA_KEY][relName] = {
               data: { type, id: String(id) }
             };
           } else {
-            record[RELATIONSHIP_METADATA_KEY][fieldDef.as] = { data: null };
+            record[RELATIONSHIP_METADATA_KEY][relName] = { data: null };
           }
         }
       }
@@ -288,8 +379,8 @@ export const loadBelongsTo = async (scope, deps) => {
         const relationshipObject = { data: null };
         
         // Add links if urlPrefix is configured
-        const urlPrefix = scopes[scopeName]?.vars?.resourceUrlPrefix;
-        if (urlPrefix && scopeName) {
+        const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+        if (scopeName) {
           relationshipObject.links = {
             self: `${urlPrefix}/${scopeName}/${record[idProperty]}/relationships/${includeName}`,
             related: `${urlPrefix}/${scopeName}/${record[idProperty]}/${includeName}`
@@ -322,6 +413,9 @@ export const loadBelongsTo = async (scope, deps) => {
     let query = knex(targetTableName).whereIn(targetIdProperty, uniqueIds);
     if (fieldSelectionInfo) {
       query = query.select(fieldSelectionInfo.fieldsToSelect);
+    } else if (targetIdProperty !== 'id') {
+      // If no field selection but custom idProperty, we need to alias it
+      query = query.select('*', `${targetIdProperty} as id`);
     }
     const targetRecords = await query;
     
@@ -331,7 +425,7 @@ export const loadBelongsTo = async (scope, deps) => {
     // Create lookup map
     const targetById = {};
     targetRecords.forEach(record => {
-      targetById[record[targetIdProperty]] = record;
+      targetById[record.id || record[targetIdProperty]] = record;
     });
     
     // Set relationships on original records
@@ -345,10 +439,10 @@ export const loadBelongsTo = async (scope, deps) => {
       
       if (targetRecord) {
         // Convert to JSON:API format
-        const jsonApiRecord = toJsonApi(
+        const jsonApiRecord = toJsonApiRecord(
           scopes[targetScope],
           targetRecord,
-          { context: { scopeName: targetScope, schemaInfo: scopes[targetScope].vars.schemaInfo, polymorphicFields: new Set() } }
+          targetScope
         );
 
         // Add relationships from metadata
@@ -357,12 +451,17 @@ export const loadBelongsTo = async (scope, deps) => {
           // Clean up the temporary property
           delete targetRecord[RELATIONSHIP_METADATA_KEY];
         }
+        
+        // Attach computed dependencies info if sparse fieldsets were used
+        if (fieldSelectionInfo?.computedDependencies) {
+          jsonApiRecord[COMPUTED_DEPENDENCIES_KEY] = fieldSelectionInfo.computedDependencies;
+        }
 
         const relationshipObject = { data: { type: targetScope, id: String(targetId) } };
         
         // Add links if urlPrefix is configured
-        const urlPrefix = scopes[scopeName]?.vars?.resourceUrlPrefix;
-        if (urlPrefix && scopeName) {
+        const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+        if (scopeName) {
           relationshipObject.links = {
             self: `${urlPrefix}/${scopeName}/${record[idProperty]}/relationships/${includeName}`,
             related: `${urlPrefix}/${scopeName}/${record[idProperty]}/${includeName}`
@@ -385,8 +484,8 @@ export const loadBelongsTo = async (scope, deps) => {
         const relationshipObject = { data: null };
         
         // Add links if urlPrefix is configured
-        const urlPrefix = scopes[scopeName]?.vars?.resourceUrlPrefix;
-        if (urlPrefix && scopeName) {
+        const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+        if (scopeName) {
           relationshipObject.links = {
             self: `${urlPrefix}/${scopeName}/${record[idProperty]}/relationships/${includeName}`,
             related: `${urlPrefix}/${scopeName}/${record[idProperty]}/${includeName}`
@@ -476,8 +575,12 @@ export const loadHasMany = async (scope, deps) => {
     
     // Handle many-to-many relationship
     const pivotTable = scopes[relDef.through].vars.schemaInfo.tableName 
-    const foreignKey = relDef.foreignKey || `${scopeName.slice(0, -1)}_id`;
-    const otherKey = relDef.otherKey || `${relDef.hasMany.slice(0, -1)}_id`;
+    const foreignKey = relDef.foreignKey;
+    const otherKey = relDef.otherKey;
+    
+    if (!foreignKey || !otherKey) {
+      throw new Error(`Missing foreignKey or otherKey in many-to-many relationship '${relName}' for scope '${scopeName}'`);
+    }
     const targetScope = relDef.hasMany;
     const targetTable = scopes[targetScope].vars.schemaInfo.tableName
     
@@ -499,8 +602,8 @@ export const loadHasMany = async (scope, deps) => {
         const relationshipObject = { data: [] };
         
         // Add links if urlPrefix is configured
-        const urlPrefix = scopes[scopeName]?.vars?.resourceUrlPrefix;
-        if (urlPrefix && scopeName) {
+        const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+        if (scopeName) {
           relationshipObject.links = {
             self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${includeName}`,
             related: `${urlPrefix}/${scopeName}/${record.id}/${includeName}`
@@ -556,18 +659,25 @@ export const loadHasMany = async (scope, deps) => {
         });
       }
       
+      const targetIdProperty = scopes[targetScope]?.vars?.schemaInfo?.idProperty || 'id';
       const windowQuery = knex
-        .select(`${targetTable}.*`)
-        .select(
+        .select(`${targetTable}.*`);
+      
+      // Add id alias if needed
+      if (targetIdProperty !== 'id') {
+        windowQuery.select(`${targetTable}.${targetIdProperty} as id`);
+      }
+      
+      windowQuery.select(
           knex.raw(
             'ROW_NUMBER() OVER (PARTITION BY pivot.?? ORDER BY ' + 
-            buildOrderByClause(relDef.include?.orderBy || ['id'], targetTable) + 
+            buildOrderByClause(relDef.include?.orderBy || [targetIdProperty], targetTable) + 
             ') as ' + ROW_NUMBER_KEY,
             [foreignKey]
           )
         )
         .from(targetTable)
-        .join(`${pivotTable} as pivot`, `${targetTable}.id`, 'pivot.' + otherKey)
+        .join(`${pivotTable} as pivot`, `${targetTable}.${targetIdProperty}`, 'pivot.' + otherKey)
         .whereIn(`pivot.${foreignKey}`, mainIds);
         
       
@@ -584,10 +694,14 @@ export const loadHasMany = async (scope, deps) => {
       
     } else {
       // Standard query without per-parent limits
-      let query = knex(targetTable).whereIn('id', targetIds);
+      const targetIdProperty = scopes[targetScope]?.vars?.schemaInfo?.idProperty || 'id';
+      let query = knex(targetTable).whereIn(targetIdProperty, targetIds);
       
       if (fieldSelectionInfo) {
         query = query.select(fieldSelectionInfo.fieldsToSelect);
+      } else if (targetIdProperty !== 'id') {
+        // If no field selection but custom idProperty, we need to alias it
+        query = query.select('*', `${targetIdProperty} as id`);
       }
       
       // Apply standard include config (global limits)
@@ -634,10 +748,10 @@ export const loadHasMany = async (scope, deps) => {
           // Add to included
           const resourceKey = `${targetScope}:${childRecord.id}`;
           if (!included.has(resourceKey)) {
-            const jsonApiRecord = toJsonApi(
+            const jsonApiRecord = toJsonApiRecord(
             scopes[targetScope],
             childRecord,
-            { context: { scopeName: targetScope, schemaInfo: scopes[targetScope].vars.schemaInfo, polymorphicFields: new Set() } }
+            targetScope
           );
             
             
@@ -648,6 +762,11 @@ export const loadHasMany = async (scope, deps) => {
               delete childRecord[RELATIONSHIP_METADATA_KEY];
             }
             
+            // Attach computed dependencies info if sparse fieldsets were used
+            if (fieldSelectionInfo?.computedDependencies) {
+              jsonApiRecord[COMPUTED_DEPENDENCIES_KEY] = fieldSelectionInfo.computedDependencies;
+            }
+            
             included.set(resourceKey, jsonApiRecord);
           }
           return { type: targetScope, id: String(childRecord.id) };
@@ -656,8 +775,8 @@ export const loadHasMany = async (scope, deps) => {
       const relationshipObject = { data: relData };
       
       // Add links if urlPrefix is configured
-      const urlPrefix = scopes[scopeName]?.vars?.resourceUrlPrefix;
-      if (urlPrefix && scopeName) {
+      const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+      if (scopeName) {
         relationshipObject.links = {
           self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${includeName}`,
           related: `${urlPrefix}/${scopeName}/${record.id}/${includeName}`
@@ -692,7 +811,11 @@ export const loadHasMany = async (scope, deps) => {
     // Handle regular one-to-many relationship
     const targetScope = relDef.hasMany;
     const targetTable = scopes[targetScope].vars.schemaInfo.tableName;
-    const foreignKey = relDef.foreignKey || `${scopeName.slice(0, -1)}_id`;
+    const foreignKey = relDef.foreignKey;
+    
+    if (!foreignKey) {
+      throw new Error(`Missing foreignKey in hasMany relationship '${relName}' for scope '${scopeName}'`);
+    }
     
     log.debug(`[INCLUDE] Loading ${targetScope} records with foreign key ${foreignKey}:`, { 
       whereIn: mainIds,
@@ -799,10 +922,10 @@ export const loadHasMany = async (scope, deps) => {
         // Add to included
         const resourceKey = `${targetScope}:${childRecord.id}`;
         if (!included.has(resourceKey)) {
-          const jsonApiRecord = toJsonApi(
+          const jsonApiRecord = toJsonApiRecord(
             scopes[targetScope],
             childRecord,
-            { context: { scopeName: targetScope, schemaInfo: scopes[targetScope].vars.schemaInfo, polymorphicFields: new Set() } }
+            targetScope
           );
           
           // Add relationships from metadata
@@ -812,6 +935,11 @@ export const loadHasMany = async (scope, deps) => {
             delete childRecord[RELATIONSHIP_METADATA_KEY];
           }
           
+          // Attach computed dependencies info if sparse fieldsets were used
+          if (fieldSelectionInfo?.computedDependencies) {
+            jsonApiRecord[COMPUTED_DEPENDENCIES_KEY] = fieldSelectionInfo.computedDependencies;
+          }
+          
           included.set(resourceKey, jsonApiRecord);
         }
         return { type: targetScope, id: String(childRecord.id) };
@@ -820,8 +948,8 @@ export const loadHasMany = async (scope, deps) => {
       const relationshipObject = { data: relData };
       
       // Add links if urlPrefix is configured
-      const urlPrefix = scopes[scopeName]?.vars?.resourceUrlPrefix;
-      if (urlPrefix && scopeName) {
+      const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+      if (scopeName) {
         relationshipObject.links = {
           self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${includeName}`,
           related: `${urlPrefix}/${scopeName}/${record.id}/${includeName}`
@@ -933,7 +1061,7 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
     
     // Build field selection for sparse fieldsets
     const targetScopeObject = scopes[targetType];
-    const targetIdProperty = targetScopeObject.vars.schemaInfo.idProperty;
+    // const targetIdProperty = targetScopeObject.vars.schemaInfo.idProperty;
     const fieldSelectionInfo = fields?.[targetType] ? 
       await buildFieldSelection(targetScopeObject, {
         context: {
@@ -950,9 +1078,13 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
     });
     
     // Query for this type
-    let query = knex(targetTable).whereIn('id', targetIds);
+    const targetIdProperty = scopes[targetType]?.vars?.schemaInfo?.idProperty || 'id';
+    let query = knex(targetTable).whereIn(targetIdProperty, targetIds);
     if (fieldSelectionInfo) {
       query = query.select(fieldSelectionInfo.fieldsToSelect);
+    } else if (targetIdProperty !== 'id') {
+      // If no field selection but custom idProperty, we need to alias it
+      query = query.select('*', `${targetIdProperty} as id`);
     }
     const targetRecords = await query;
     
@@ -977,10 +1109,10 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
           // Add to included
           const resourceKey = `${targetType}:${targetId}`;
           if (!included.has(resourceKey)) {
-            const jsonApiRecord = toJsonApi(
+            const jsonApiRecord = toJsonApiRecord(
               scopes[targetType],
               targetRecord,
-              { context: { scopeName: targetType, schemaInfo: scopes[targetType].vars.schemaInfo, polymorphicFields: new Set() } }
+              targetType
             );
             
             // Add relationships from metadata
@@ -990,6 +1122,11 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
               delete targetRecord[RELATIONSHIP_METADATA_KEY];
             }
             
+            // Attach computed dependencies info if sparse fieldsets were used
+            if (fieldSelectionInfo?.computedDependencies) {
+              jsonApiRecord[COMPUTED_DEPENDENCIES_KEY] = fieldSelectionInfo.computedDependencies;
+            }
+            
             included.set(resourceKey, jsonApiRecord);
           }
           
@@ -998,8 +1135,8 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
           };
           
           // Add links if urlPrefix is configured
-          const urlPrefix = scopes[scopeName]?.vars?.resourceUrlPrefix;
-          if (urlPrefix && scopeName) {
+          const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+          if (scopeName) {
             relationshipObject.links = {
               self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${relName}`,
               related: `${urlPrefix}/${scopeName}/${record.id}/${relName}`
@@ -1011,8 +1148,8 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
           const relationshipObject = { data: null };
           
           // Add links if urlPrefix is configured
-          const urlPrefix = scopes[scopeName]?.vars?.resourceUrlPrefix;
-          if (urlPrefix && scopeName) {
+          const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+          if (scopeName) {
             relationshipObject.links = {
               self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${relName}`,
               related: `${urlPrefix}/${scopeName}/${record.id}/${relName}`
@@ -1043,8 +1180,8 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
       const relationshipObject = { data: null };
       
       // Add links if urlPrefix is configured
-      const urlPrefix = scopes[scopeName]?.vars?.resourceUrlPrefix;
-      if (urlPrefix && scopeName) {
+      const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+      if (scopeName) {
         relationshipObject.links = {
           self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${relName}`,
           related: `${urlPrefix}/${scopeName}/${record.id}/${relName}`
@@ -1154,6 +1291,9 @@ export const loadReversePolymorphic = async (scope, deps) => {
     
   if (fieldSelectionInfo) {
     query = query.select(fieldSelectionInfo.fieldsToSelect);
+  } else if (targetIdProperty !== 'id') {
+    // If no field selection but custom idProperty, we need to alias it
+    query = query.select('*', `${targetIdProperty} as id`);
   }
   
   // Apply include configuration (limits, ordering, etc.)
@@ -1193,10 +1333,10 @@ export const loadReversePolymorphic = async (scope, deps) => {
       // Add to included
       const resourceKey = `${targetScope}:${childRecord.id}`;
       if (!included.has(resourceKey)) {
-        const jsonApiRecord = toJsonApi(
+        const jsonApiRecord = toJsonApiRecord(
           scopes[targetScope],
           childRecord,
-          { context: { scopeName: targetScope, schemaInfo: scopes[targetScope].vars.schemaInfo, polymorphicFields: new Set() } }
+          targetScope
         );
         
         // Add relationships from metadata
@@ -1206,6 +1346,11 @@ export const loadReversePolymorphic = async (scope, deps) => {
           delete childRecord[RELATIONSHIP_METADATA_KEY];
         }
         
+        // Attach computed dependencies info if sparse fieldsets were used
+        if (fieldSelectionInfo?.computedDependencies) {
+          jsonApiRecord[COMPUTED_DEPENDENCIES_KEY] = fieldSelectionInfo.computedDependencies;
+        }
+        
         included.set(resourceKey, jsonApiRecord);
       }
       return { type: targetScope, id: String(childRecord.id) };
@@ -1214,8 +1359,8 @@ export const loadReversePolymorphic = async (scope, deps) => {
     const relationshipObject = { data: relData };
     
     // Add links if urlPrefix is configured
-    const urlPrefix = scopes[scopeName]?.vars?.resourceUrlPrefix;
-    if (urlPrefix && scopeName) {
+    const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+    if (scopeName) {
       relationshipObject.links = {
         self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${includeName}`,
         related: `${urlPrefix}/${scopeName}/${record.id}/${includeName}`
@@ -1499,4 +1644,175 @@ export const buildIncludedResources = async (scope, deps) => {
     };
     throw enhancedError;
   }
+};
+
+/**
+ * Loads relationship identifiers for all hasMany relationships without fetching full related records.
+ * 
+ * ## Purpose
+ * This function ensures that all hasMany relationships (one-to-many, many-to-many, and polymorphic) 
+ * always return resource identifiers in the JSON:API response, even when the related resources 
+ * are not included via the ?include parameter.
+ * 
+ * ## Why this is needed
+ * 1. **JSON:API Consistency**: The JSON:API spec allows servers to include relationship identifiers
+ *    without including the full related resources. This provides a consistent API surface where
+ *    clients always know what relationships exist and their IDs.
+ * 
+ * 2. **Simplified Mode Support**: In simplified mode, relationship IDs are transformed into `_ids` 
+ *    arrays (e.g., `reviews_ids: ['1', '2', '3']`). Without this function, these arrays only 
+ *    appear when using ?include, creating an inconsistent API where fields appear/disappear.
+ * 
+ * 3. **Performance Balance**: Loading just IDs is much cheaper than loading full records. This gives
+ *    clients the ability to know what relationships exist without the cost of fetching all data.
+ * 
+ * ## What it does
+ * - Runs ONE query per relationship type (not per record) to fetch all related IDs
+ * - Populates the relationship data with resource identifiers: `{ type: 'resource', id: '123' }`
+ * - Handles all relationship types: one-to-many, many-to-many, and polymorphic
+ * - Works for both JSON:API and simplified modes (transformation happens elsewhere)
+ * 
+ * ## When it runs
+ * This runs after the main records are fetched but before includes are processed.
+ * If includes ARE specified, they will overwrite these IDs with full data.
+ * 
+ * @param {Array<Object>} records - The parent records to load relationships for
+ * @param {string} scopeName - The parent scope name (e.g., 'authors')
+ * @param {Object} scopes - All available scopes with their schemas
+ * @param {Object} knex - Knex instance for database queries
+ * @returns {Promise<void>} Modifies records in place by adding relationship data
+ */
+export const loadRelationshipIdentifiers = async (records, scopeName, scopes, knex) => {
+  if (!records.length) return;
+  
+  const schemaInfo = scopes[scopeName]?.vars?.schemaInfo;
+  if (!schemaInfo) return;
+  
+  const relationships = schemaInfo.schemaRelationships || {};
+  const recordIds = records.map(r => r.id);
+  
+  
+  // Process each hasMany relationship
+  for (const [relName, relDef] of Object.entries(relationships)) {
+    let idsMap = {};
+    
+    if (relDef.hasMany && !relDef.through && !relDef.via) {
+      // Regular one-to-many
+      // Example: publisher hasMany authors
+      const foreignKey = relDef.foreignKey;
+    
+    if (!foreignKey) {
+      throw new Error(`Missing foreignKey in hasMany relationship '${relName}' for scope '${scopeName}'`);
+    }
+      const targetScope = scopes[relDef.hasMany];
+      const targetTable = targetScope?.vars?.schemaInfo?.tableName || relDef.hasMany;
+      const targetIdProperty = targetScope?.vars?.schemaInfo?.idProperty || 'id';
+      
+      const results = await knex(targetTable)
+        .whereIn(foreignKey, recordIds)
+        .select(targetIdProperty !== 'id' ? `${targetIdProperty} as id` : 'id', foreignKey);
+      
+      results.forEach(row => {
+        const parentId = String(row[foreignKey]);
+        if (!idsMap[parentId]) idsMap[parentId] = [];
+        idsMap[parentId].push(String(row.id));
+      });
+      
+    } else if (relDef.hasMany && relDef.through) {
+      // Many-to-many with through
+      // Example: authors hasMany books through book_authors
+      const foreignKey = relDef.foreignKey;
+    
+    if (!foreignKey) {
+      throw new Error(`Missing foreignKey in hasMany relationship '${relName}' for scope '${scopeName}'`);
+    }
+      const otherKey = relDef.otherKey || `${relDef.hasMany.slice(0, -1)}_id`;
+      
+      // Get the actual table name from the pivot scope
+      const pivotScope = scopes[relDef.through];
+      const pivotTable = pivotScope?.vars?.schemaInfo?.tableName || relDef.through;
+      
+      const results = await knex(pivotTable)
+        .whereIn(foreignKey, recordIds)
+        .select(foreignKey, otherKey);
+      
+      results.forEach(row => {
+        const parentId = String(row[foreignKey]);
+        const childId = String(row[otherKey]);
+        if (!idsMap[parentId]) idsMap[parentId] = [];
+        idsMap[parentId].push(childId);
+      });
+      
+    } else if (relDef.manyToMany) {
+      // Many-to-many (alternate syntax)
+      // Example: { manyToMany: { through: 'article_tags', foreignKey: 'article_id', otherKey: 'tag_id' } }
+      const { through, foreignKey, otherKey } = relDef.manyToMany;
+      const fk = foreignKey;
+      const ok = otherKey;
+      
+      if (!fk || !ok) {
+        throw new Error(`Missing foreignKey or otherKey in manyToMany relationship '${relName}' for scope '${scopeName}'`);
+      }
+      
+      // Get the actual table name from the pivot scope
+      const pivotScope = scopes[through];
+      const pivotTable = pivotScope?.vars?.schemaInfo?.tableName || through;
+      
+      const results = await knex(pivotTable)
+        .whereIn(fk, recordIds)
+        .select(fk, ok);
+      
+      results.forEach(row => {
+        const parentId = String(row[fk]);
+        const childId = String(row[ok]);
+        if (!idsMap[parentId]) idsMap[parentId] = [];
+        idsMap[parentId].push(childId);
+      });
+      
+    } else if (relDef.hasMany && relDef.via) {
+      // Polymorphic reverse (via)
+      // Example: publishers hasMany reviews via reviewable (where reviews.reviewable_type = 'publishers')
+      const targetScope = relDef.hasMany;
+      const targetRelationships = scopes[targetScope]?.vars?.schemaInfo?.schemaRelationships;
+      const viaRel = targetRelationships?.[relDef.via];
+      
+      if (viaRel?.belongsToPolymorphic) {
+        const { typeField, idField } = viaRel.belongsToPolymorphic;
+        
+        // Get the actual table name
+        const targetTable = scopes[targetScope]?.vars?.schemaInfo?.tableName || targetScope;
+        const targetIdProperty = scopes[targetScope]?.vars?.schemaInfo?.idProperty || 'id';
+        
+        const results = await knex(targetTable)
+          .where(typeField, scopeName)
+          .whereIn(idField, recordIds)
+          .select(targetIdProperty !== 'id' ? `${targetIdProperty} as id` : 'id', idField);
+        
+        results.forEach(row => {
+          const parentId = String(row[idField]);
+          if (!idsMap[parentId]) idsMap[parentId] = [];
+          idsMap[parentId].push(String(row.id));
+        });
+      }
+    }
+    
+    // Apply the collected IDs to all records
+    if (Object.keys(idsMap).length > 0 || relDef.hasMany || relDef.manyToMany) {
+      records.forEach(record => {
+        if (!record[RELATIONSHIPS_KEY]) {
+          record[RELATIONSHIPS_KEY] = {};
+        }
+        
+        const ids = idsMap[String(record.id)] || [];
+        const targetType = relDef.hasMany || (relDef.manyToMany ? relName : null);
+        
+        record[RELATIONSHIPS_KEY][relName] = {
+          data: ids.map(id => ({ 
+            type: targetType, 
+            id 
+          }))
+        };
+      });
+    }
+  }
 };