json-rest-api 1.0.10 → 1.0.13

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

@@ -81,6 +81,28 @@ import { buildWindowedIncludeQuery, applyStandardIncludeConfig, buildOrderByClau
 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';
 
+const translateSelectFieldsForAdapter = (fields, adapter) => {
+  if (!adapter || !fields) return fields;
+
+  const translateField = (field) => {
+    if (typeof field !== 'string') return field;
+
+    if (field === '*') return '*';
+
+    const aliasMatch = field.match(/\s+as\s+/i);
+    if (aliasMatch) {
+      const [source, alias] = field.split(/\s+as\s+/i);
+      const translatedSource = adapter.translateColumn(source.trim()) || source.trim();
+      return `${translatedSource} as ${alias.trim()}`;
+    }
+
+    const translated = adapter.translateColumn(field);
+    return translated || field;
+  };
+
+  return fields.map(translateField);
+};
+
 /**
  * Groups records by their polymorphic type for efficient batch loading
  * 
@@ -263,7 +285,7 @@ const loadRelationshipMetadata = async (scopes, records, scopeName) => {
     const schemaInfo = scopes[scopeName]?.vars?.schemaInfo;
     if (!schemaInfo) return;
 
-    const schema = schemaInfo.schema.structure || schemaInfo.schema;
+    const schema = schemaInfo.schemaInstance.structure || schemaInfo.schemaInstance;
     const relationships = schemaInfo.schemaRelationships || {};
 
     // Process each record
@@ -287,11 +309,14 @@ const loadRelationshipMetadata = async (scopes, records, scopeName) => {
         }
       }
 
-      // Process hasMany relationships
+      // Process hasMany, hasOne and manyToMany relationships
       for (const [relName, relDef] of Object.entries(relationships)) {
-        if (relDef.hasMany) {
+        if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
           // Add empty relationship data - will be populated if explicitly included
           record[RELATIONSHIP_METADATA_KEY][relName] = { data: [] };
+        } else if (relDef.type === 'hasOne') {
+          // hasOne expects a single object or null
+          record[RELATIONSHIP_METADATA_KEY][relName] = { data: null };
         } else if (relDef.belongsToPolymorphic) {
           // Process polymorphic relationships defined in relationships section
           const { typeField, idField } = relDef.belongsToPolymorphic;
@@ -379,7 +404,7 @@ export const loadBelongsTo = async (scope, deps) => {
         const relationshipObject = { data: null };
         
         // Add links if urlPrefix is configured
-        const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+        const urlPrefix = scopes[scopeName]?.vars?.returnBasePath || scopes[scopeName]?.vars?.mountPath || '';
         if (scopeName) {
           relationshipObject.links = {
             self: `${urlPrefix}/${scopeName}/${record[idProperty]}/relationships/${includeName}`,
@@ -395,16 +420,18 @@ export const loadBelongsTo = async (scope, deps) => {
     // Get target table info
     const targetTableName = scopes[targetScope].vars.schemaInfo.tableName
     const targetIdProperty = scopes[targetScope].vars.schemaInfo.idProperty 
-    const targetSchema = scopes[targetScope].vars.schemaInfo.schema;
+    const targetSchema = scopes[targetScope].vars.schemaInfo.schemaInstance;
     
     // Build field selection for sparse fieldsets
     const targetScopeObject = scopes[targetScope];
+    const storageAdapter = targetScopeObject.vars.storageAdapter;
     const fieldSelectionInfo = fields?.[targetScope] ? 
       await buildFieldSelection(targetScopeObject, {
         context: {
           scopeName: targetScope,
           queryParams: { fields: { [targetScope]: fields[targetScope] } },
-          schemaInfo: targetScopeObject.vars.schemaInfo
+          schemaInfo: targetScopeObject.vars.schemaInfo,
+          storageAdapter,
         }
       }) : 
       null;
@@ -412,7 +439,8 @@ export const loadBelongsTo = async (scope, deps) => {
     // Load the target records
     let query = knex(targetTableName).whereIn(targetIdProperty, uniqueIds);
     if (fieldSelectionInfo) {
-      query = query.select(fieldSelectionInfo.fieldsToSelect);
+      const selectFields = translateSelectFieldsForAdapter(fieldSelectionInfo.fieldsToSelect, storageAdapter);
+      query = query.select(selectFields);
     } else if (targetIdProperty !== 'id') {
       // If no field selection but custom idProperty, we need to alias it
       query = query.select('*', `${targetIdProperty} as id`);
@@ -460,7 +488,7 @@ export const loadBelongsTo = async (scope, deps) => {
         const relationshipObject = { data: { type: targetScope, id: String(targetId) } };
         
         // Add links if urlPrefix is configured
-        const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+        const urlPrefix = scopes[scopeName]?.vars?.returnBasePath || scopes[scopeName]?.vars?.mountPath || '';
         if (scopeName) {
           relationshipObject.links = {
             self: `${urlPrefix}/${scopeName}/${record[idProperty]}/relationships/${includeName}`,
@@ -484,7 +512,7 @@ export const loadBelongsTo = async (scope, deps) => {
         const relationshipObject = { data: null };
         
         // Add links if urlPrefix is configured
-        const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+        const urlPrefix = scopes[scopeName]?.vars?.returnBasePath || scopes[scopeName]?.vars?.mountPath || '';
         if (scopeName) {
           relationshipObject.links = {
             self: `${urlPrefix}/${scopeName}/${record[idProperty]}/relationships/${includeName}`,
@@ -554,11 +582,13 @@ export const loadHasMany = async (scope, deps) => {
   const { records, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields } = scope;
   const { scopes, log, knex, capabilities } = deps.context;
   try {
-    log.trace('[INCLUDE] Loading hasMany relationship:', { 
+    log.trace('[INCLUDE] Loading hasMany/manyToMany relationship:', { 
       scopeName, 
       includeName, 
       recordCount: records.length,
-      hasThrough: !!relDef.through 
+      relDef,
+      isManyToMany: relDef.type === 'manyToMany',
+      hasMany: relDef.type === 'hasMany' ? relDef.target : undefined
     });
   
   // Collect all parent IDs
@@ -570,18 +600,20 @@ export const loadHasMany = async (scope, deps) => {
   }
   
   
-  // Check if this is a many-to-many relationship (has through property)
-  if (relDef.through) {
+  // Check if this is a many-to-many relationship
+  if (relDef.type === 'manyToMany') {
     
     // Handle many-to-many relationship
-    const pivotTable = scopes[relDef.through].vars.schemaInfo.tableName 
+    const pivotTable = scopes[relDef.through].vars.schemaInfo.tableName;
     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;
+    
+    // For manyToMany, the target scope is the relationship name itself
+    const targetScope = includeName;
     const targetTable = scopes[targetScope].vars.schemaInfo.tableName
     
     log.debug(`[INCLUDE] Loading pivot records from ${pivotTable}:`, { 
@@ -602,7 +634,7 @@ export const loadHasMany = async (scope, deps) => {
         const relationshipObject = { data: [] };
         
         // Add links if urlPrefix is configured
-        const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+        const urlPrefix = scopes[scopeName]?.vars?.returnBasePath || scopes[scopeName]?.vars?.mountPath || '';
         if (scopeName) {
           relationshipObject.links = {
             self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${includeName}`,
@@ -624,15 +656,17 @@ export const loadHasMany = async (scope, deps) => {
     });
     
     // Step 3: Build field selection for sparse fieldsets
-    const targetSchema = scopes[targetScope].vars.schemaInfo.schema;
+    const targetSchema = scopes[targetScope].vars.schemaInfo.schemaInstance;
     const targetScopeObject = scopes[targetScope];
+    const storageAdapter = targetScopeObject.vars.storageAdapter;
     const targetIdProperty = targetScopeObject.vars.schemaInfo.idProperty;
     const fieldSelectionInfo = fields?.[targetScope] ? 
       await buildFieldSelection(targetScopeObject, {
         context: {
           scopeName: targetScope,
           queryParams: { fields: { [targetScope]: fields[targetScope] } },
-          schemaInfo: targetScopeObject.vars.schemaInfo
+          schemaInfo: targetScopeObject.vars.schemaInfo,
+          storageAdapter,
         }
       }) : 
       null;
@@ -698,7 +732,8 @@ export const loadHasMany = async (scope, deps) => {
       let query = knex(targetTable).whereIn(targetIdProperty, targetIds);
       
       if (fieldSelectionInfo) {
-        query = query.select(fieldSelectionInfo.fieldsToSelect);
+        const selectFields = translateSelectFieldsForAdapter(fieldSelectionInfo.fieldsToSelect, storageAdapter);
+        query = query.select(selectFields);
       } else if (targetIdProperty !== 'id') {
         // If no field selection but custom idProperty, we need to alias it
         query = query.select('*', `${targetIdProperty} as id`);
@@ -775,7 +810,7 @@ export const loadHasMany = async (scope, deps) => {
       const relationshipObject = { data: relData };
       
       // Add links if urlPrefix is configured
-      const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+      const urlPrefix = scopes[scopeName]?.vars?.returnBasePath || scopes[scopeName]?.vars?.mountPath || '';
       if (scopeName) {
         relationshipObject.links = {
           self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${includeName}`,
@@ -807,9 +842,9 @@ export const loadHasMany = async (scope, deps) => {
       }
     }
     
-  } else {
-    // Handle regular one-to-many relationship
-    const targetScope = relDef.hasMany;
+  } else if (relDef.type === 'hasMany') {
+    // Handle one-to-many relationship
+    const targetScope = relDef.target;
     const targetTable = scopes[targetScope].vars.schemaInfo.tableName;
     const foreignKey = relDef.foreignKey;
     
@@ -823,15 +858,17 @@ export const loadHasMany = async (scope, deps) => {
     });
     
     // Build field selection for sparse fieldsets
-    const targetSchema = scopes[targetScope].vars.schemaInfo.schema;
+    const targetSchema = scopes[targetScope].vars.schemaInfo.schemaInstance;
     const targetScopeObject = scopes[targetScope];
+    const storageAdapter = targetScopeObject.vars.storageAdapter;
     const targetIdProperty = targetScopeObject.vars.schemaInfo.idProperty;
     const fieldSelectionInfo = fields?.[targetScope] ? 
       await buildFieldSelection(targetScopeObject, {
         context: {
           scopeName: targetScope,
           queryParams: { fields: { [targetScope]: fields[targetScope] } },
-          schemaInfo: targetScopeObject.vars.schemaInfo
+          schemaInfo: targetScopeObject.vars.schemaInfo,
+          storageAdapter,
         }
       }) : 
       null;
@@ -843,12 +880,16 @@ export const loadHasMany = async (scope, deps) => {
     if (relDef.include?.strategy === 'window') {
       try {
         // Try to build window function query
+        const selectFields = fieldSelectionInfo
+          ? translateSelectFieldsForAdapter(fieldSelectionInfo.fieldsToSelect, storageAdapter)
+          : null;
+
         query = buildWindowedIncludeQuery(
           knex,
           targetTable,
           foreignKey,
           mainIds,
-          fieldSelectionInfo ? fieldSelectionInfo.fieldsToSelect : null,
+          selectFields,
           relDef.include || {},
           capabilities,
           targetScopeObject.vars  // Pass target scope vars
@@ -874,7 +915,8 @@ export const loadHasMany = async (scope, deps) => {
       query = knex(targetTable).whereIn(foreignKey, mainIds);
       
       if (fieldSelectionInfo) {
-        query = query.select(fieldSelectionInfo.fieldsToSelect);
+        const selectFieldsStd = translateSelectFieldsForAdapter(fieldSelectionInfo.fieldsToSelect, storageAdapter);
+        query = query.select(selectFieldsStd);
       }
       
       // Apply standard config with defaults
@@ -948,7 +990,7 @@ export const loadHasMany = async (scope, deps) => {
       const relationshipObject = { data: relData };
       
       // Add links if urlPrefix is configured
-      const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+      const urlPrefix = scopes[scopeName]?.vars?.returnBasePath || scopes[scopeName]?.vars?.mountPath || '';
       if (scopeName) {
         relationshipObject.links = {
           self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${includeName}`,
@@ -1001,6 +1043,134 @@ export const loadHasMany = async (scope, deps) => {
   }
 };
 
+/**
+ * Loads hasOne relationships (one-to-one)
+ * 
+ * Similar to hasMany but expects a single related record.
+ * For example, a user that has one profile.
+ * 
+ * @param {Object} scope - The hooked-api scope object
+ * @param {Object} deps - Dependencies object
+ */
+export const loadHasOne = async (scope, deps) => {
+  const { records, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields } = scope;
+  const { context: { scopes, log, knex, capabilities } } = deps;
+  
+  log = log?.child ? log.child({ method: 'loadHasOne' }) : console;
+  
+  if (!records || records.length === 0) {
+    log.trace('[INCLUDE] No records to load hasOne for');
+    return;
+  }
+  
+  // Get parent IDs
+  const idProperty = scopes[scopeName]?.vars?.schemaInfo?.idProperty || 'id';
+  const mainIds = [...new Set(records.map(r => r[idProperty]).filter(Boolean))];
+  
+  if (mainIds.length === 0) {
+    log.trace('[INCLUDE] No parent IDs found, skipping hasOne load');
+    return;
+  }
+  
+  const targetScope = relDef.target;
+  const targetTable = scopes[targetScope].vars.schemaInfo.tableName;
+  const foreignKey = relDef.foreignKey;
+  
+  if (!foreignKey) {
+    throw new Error(`Missing foreignKey in hasOne relationship '${includeName}' for scope '${scopeName}'`);
+  }
+  
+  log.debug(`[INCLUDE] Loading ${targetScope} records with foreign key ${foreignKey}:`, { 
+    whereIn: mainIds
+  });
+  
+  // Build query for hasOne - expects single result per parent
+  const targetSchema = scopes[targetScope].vars.schemaInfo.schemaInstance;
+  const targetScopeObject = scopes[targetScope];
+  const storageAdapter = targetScopeObject.vars.storageAdapter;
+  const targetIdProperty = targetScopeObject.vars.schemaInfo.idProperty;
+  
+  // Build field selection for sparse fieldsets
+  const fieldSelectionInfo = fields?.[targetScope] ? 
+    await buildFieldSelection(targetScopeObject, {
+      context: {
+        scopeName: targetScope,
+        queryParams: { fields: { [targetScope]: fields[targetScope] } },
+        schemaInfo: targetScopeObject.vars.schemaInfo,
+        storageAdapter,
+      }
+    }) : 
+    null;
+  
+  // Query related records
+  let query = knex(targetTable).whereIn(foreignKey, mainIds);
+  
+  if (fieldSelectionInfo?.fieldsToSelect) {
+    const selectFields = translateSelectFieldsForAdapter(fieldSelectionInfo.fieldsToSelect, storageAdapter);
+    query = query.select(selectFields);
+  }
+  
+  const relatedRecords = await query;
+  
+  // Create a map of parent ID to related record (should be one-to-one)
+  const relatedByParentId = {};
+  for (const related of relatedRecords) {
+    const parentId = related[foreignKey];
+    if (relatedByParentId[parentId]) {
+      log.warn(`[INCLUDE] Multiple records found for hasOne relationship '${includeName}' with ${foreignKey}=${parentId}`);
+    }
+    relatedByParentId[parentId] = related;
+  }
+  
+  // Process each parent record
+  for (const record of records) {
+    const recordId = record[idProperty];
+    const relatedRecord = relatedByParentId[recordId];
+    
+    if (!record[RELATIONSHIPS_KEY]) record[RELATIONSHIPS_KEY] = {};
+    
+    if (relatedRecord) {
+      // Transform to JSON:API format
+      const transformed = await toJsonApiRecord(
+        targetScopeObject,
+        { 
+          context: { 
+            record: relatedRecord,
+            scopeName: targetScope,
+            schemaInfo: targetScopeObject.vars.schemaInfo
+          } 
+        }
+      );
+      
+      // Set single object (not array) for hasOne
+      record[RELATIONSHIPS_KEY][includeName] = {
+        data: { type: targetScope, id: String(relatedRecord[targetIdProperty]) }
+      };
+      
+      // Add to included if not already there
+      const key = `${targetScope}:${relatedRecord[targetIdProperty]}`;
+      if (!included.has(key)) {
+        included.set(key, transformed);
+      }
+      
+      // Process nested includes if any
+      if (subIncludes && Object.keys(subIncludes).length > 0) {
+        const newPath = `${currentPath}.${includeName}`;
+        if (!processedPaths.has(newPath)) {
+          processedPaths.add(newPath);
+          await processIncludes(
+            { records: [relatedRecord], scopeName: targetScope, includeTree: subIncludes, included, processedPaths, currentPath: newPath, fields },
+            { context: { scopes, log, knex, capabilities } }
+          );
+        }
+      }
+    } else {
+      // No related record found
+      record[RELATIONSHIPS_KEY][includeName] = { data: null };
+    }
+  }
+};
+
 /**
  * Loads polymorphic belongsTo relationships
  * 
@@ -1062,12 +1232,14 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
     // Build field selection for sparse fieldsets
     const targetScopeObject = scopes[targetType];
     // const targetIdProperty = targetScopeObject.vars.schemaInfo.idProperty;
+    const storageAdapter = targetScopeObject.vars.storageAdapter;
     const fieldSelectionInfo = fields?.[targetType] ? 
       await buildFieldSelection(targetScopeObject, {
         context: {
           scopeName: targetType,
           queryParams: { fields: { [targetType]: fields[targetType] } },
-          schemaInfo: targetScopeObject.vars.schemaInfo
+          schemaInfo: targetScopeObject.vars.schemaInfo,
+          storageAdapter,
         }
       }) : 
       null;
@@ -1081,7 +1253,8 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
     const targetIdProperty = scopes[targetType]?.vars?.schemaInfo?.idProperty || 'id';
     let query = knex(targetTable).whereIn(targetIdProperty, targetIds);
     if (fieldSelectionInfo) {
-      query = query.select(fieldSelectionInfo.fieldsToSelect);
+      const selectFields = translateSelectFieldsForAdapter(fieldSelectionInfo.fieldsToSelect, storageAdapter);
+      query = query.select(selectFields);
     } else if (targetIdProperty !== 'id') {
       // If no field selection but custom idProperty, we need to alias it
       query = query.select('*', `${targetIdProperty} as id`);
@@ -1135,7 +1308,7 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
           };
           
           // Add links if urlPrefix is configured
-          const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+          const urlPrefix = scopes[scopeName]?.vars?.returnBasePath || scopes[scopeName]?.vars?.mountPath || '';
           if (scopeName) {
             relationshipObject.links = {
               self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${relName}`,
@@ -1148,7 +1321,7 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
           const relationshipObject = { data: null };
           
           // Add links if urlPrefix is configured
-          const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+          const urlPrefix = scopes[scopeName]?.vars?.returnBasePath || scopes[scopeName]?.vars?.mountPath || '';
           if (scopeName) {
             relationshipObject.links = {
               self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${relName}`,
@@ -1180,7 +1353,7 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
       const relationshipObject = { data: null };
       
       // Add links if urlPrefix is configured
-      const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+      const urlPrefix = scopes[scopeName]?.vars?.returnBasePath || scopes[scopeName]?.vars?.mountPath || '';
       if (scopeName) {
         relationshipObject.links = {
           self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${relName}`,
@@ -1244,7 +1417,7 @@ export const loadReversePolymorphic = async (scope, deps) => {
       recordCount: records.length 
     });
   
-  const targetScope = relDef.hasMany;
+  const targetScope = relDef.target;
   const viaRelName = relDef.via;
   
   // Get the polymorphic field info from target scope
@@ -1274,14 +1447,19 @@ export const loadReversePolymorphic = async (scope, deps) => {
   });
   
   // Build field selection for sparse fieldsets
-  const targetSchema = scopes[targetScope].vars.schemaInfo.schema;
+  const targetSchema = scopes[targetScope].vars.schemaInfo.schemaInstance;
   const targetScopeObject = scopes[targetScope];
+  const storageAdapter = targetScopeObject.vars.storageAdapter;
   const targetIdProperty = targetScopeObject.vars.schemaInfo.idProperty;
   const fieldSelectionInfo = fields?.[targetScope] ? 
-    await buildFieldSelection(
-      { scopeName: targetScope, queryParams: { fields: { [targetScope]: fields[targetScope] } }, schemaInfo: targetScopeObject.vars.schemaInfo },
-      { context: { scopes, log, knex } }
-    ) : 
+    await buildFieldSelection(targetScopeObject, {
+      context: {
+        scopeName: targetScope,
+        queryParams: { fields: { [targetScope]: fields[targetScope] } },
+        schemaInfo: targetScopeObject.vars.schemaInfo,
+        storageAdapter,
+      }
+    }) : 
     null;
   
   // Query for records pointing back to our scope
@@ -1290,7 +1468,8 @@ export const loadReversePolymorphic = async (scope, deps) => {
     .whereIn(idField, parentIds);
     
   if (fieldSelectionInfo) {
-    query = query.select(fieldSelectionInfo.fieldsToSelect);
+    const selectFields = translateSelectFieldsForAdapter(fieldSelectionInfo.fieldsToSelect, storageAdapter);
+    query = query.select(selectFields);
   } else if (targetIdProperty !== 'id') {
     // If no field selection but custom idProperty, we need to alias it
     query = query.select('*', `${targetIdProperty} as id`);
@@ -1359,7 +1538,7 @@ export const loadReversePolymorphic = async (scope, deps) => {
     const relationshipObject = { data: relData };
     
     // Add links if urlPrefix is configured
-    const urlPrefix = scopes[scopeName]?.vars?.publicBaseUrl || scopes[scopeName]?.vars?.mountPath || '';
+    const urlPrefix = scopes[scopeName]?.vars?.returnBasePath || scopes[scopeName]?.vars?.mountPath || '';
     if (scopeName) {
       relationshipObject.links = {
         self: `${urlPrefix}/${scopeName}/${record.id}/relationships/${includeName}`,
@@ -1386,7 +1565,7 @@ export const loadReversePolymorphic = async (scope, deps) => {
       scopeName,
       includeName,
       via: relDef?.via,
-      targetScope: relDef?.hasMany,
+      targetScope: relDef?.target,
       recordCount: records?.length || 0,
       error: error.message,
       stack: error.stack
@@ -1397,7 +1576,7 @@ export const loadReversePolymorphic = async (scope, deps) => {
       `Failed to load reverse polymorphic relationship '${includeName}' via '${relDef?.via}' for scope '${scopeName}': ${error.message}`
     );
     enhancedError.originalError = error;
-    enhancedError.context = { scopeName, includeName, via: relDef?.via, targetScope: relDef?.hasMany };
+    enhancedError.context = { scopeName, includeName, via: relDef?.via, targetScope: relDef?.target };
     throw enhancedError;
   }
 };
@@ -1443,7 +1622,7 @@ export const processIncludes = async (scope, deps) => {
       return;
     }
     
-    const { schema, schemaRelationships } = schemaInfo;
+    const { schemaInstance: schemaInstance, schemaRelationships } = schemaInfo;
     
     // Process each include
     for (const [includeName, subIncludes] of Object.entries(includeTree)) {
@@ -1461,7 +1640,7 @@ export const processIncludes = async (scope, deps) => {
       
       try {
         // Look for belongsTo relationships in schema fields
-        for (const [fieldName, fieldDef] of Object.entries(schema.structure || {})) {
+        for (const [fieldName, fieldDef] of Object.entries(schemaInstance.structure || {})) {
           if (fieldDef.as === includeName && fieldDef.belongsTo) {
             await loadBelongsTo(
               { records, scopeName, fieldName, fieldDef, includeName, subIncludes, included, processedPaths, currentPath, fields, idProperty },
@@ -1477,7 +1656,19 @@ export const processIncludes = async (scope, deps) => {
           const relDef = schemaRelationships[includeName];
           
           if (relDef) {
-            if (relDef.hasMany) {
+            if (relDef.type === 'hasOne') {
+              // Handle hasOne relationship
+              log.debug('[INCLUDE] About to call loadHasOne:', {
+                scopeName,
+                includeName,
+                target: relDef.target
+              });
+              await loadHasOne(
+                { records, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields },
+                { context: { scopes, log, knex, capabilities } }
+              );
+              handled = true;
+            } else if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
               // Check if it's a reverse polymorphic (via)
               if (relDef.via) {
                 await loadReversePolymorphic(
@@ -1485,6 +1676,13 @@ export const processIncludes = async (scope, deps) => {
                   { context: { scopes, log, knex, capabilities } }
                 );
               } else {
+                log.debug('[INCLUDE] About to call loadHasMany:', {
+                  scopeName,
+                  includeName,
+                  relDefKeys: Object.keys(relDef || {}),
+                  hasManyToMany: relDef.type === 'manyToMany',
+                  hasMany: relDef.type === 'hasMany' ? relDef.target : undefined
+                });
                 await loadHasMany(
                   { records, scopeName, includeName, relDef, subIncludes, included, processedPaths, currentPath, fields },
                   { context: { scopes, log, knex, capabilities } }
@@ -1516,7 +1714,7 @@ export const processIncludes = async (scope, deps) => {
         log.warn('[INCLUDE] Unknown relationship:', { 
           scopeName, 
           includeName,
-          availableFields: Object.keys(schema.structure || {}).filter(k => schema.structure[k].as),
+          availableFields: Object.keys(schemaInstance.structure || {}).filter(k => schemaInstance.structure[k].as),
           availableRelationships: Object.keys(schemaRelationships || {})
         });
       }
@@ -1659,9 +1857,9 @@ export const buildIncludedResources = async (scope, deps) => {
  *    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.
+ * 2. **Simplified Mode Support**: In simplified mode, relationship IDs are transformed into 
+ *    minimal objects (e.g., `reviews: [{id: '1'}, {id: '2'}, {id: '3'}]`). Without this function, 
+ *    these objects 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.
@@ -1696,7 +1894,7 @@ export const loadRelationshipIdentifiers = async (records, scopeName, scopes, kn
   for (const [relName, relDef] of Object.entries(relationships)) {
     let idsMap = {};
     
-    if (relDef.hasMany && !relDef.through && !relDef.via) {
+    if (relDef.type === 'hasMany' && !relDef.via) {
       // Regular one-to-many
       // Example: publisher hasMany authors
       const foreignKey = relDef.foreignKey;
@@ -1704,8 +1902,8 @@ export const loadRelationshipIdentifiers = async (records, scopeName, scopes, kn
     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 targetScope = scopes[relDef.target];
+      const targetTable = targetScope?.vars?.schemaInfo?.tableName || relDef.target;
       const targetIdProperty = targetScope?.vars?.schemaInfo?.idProperty || 'id';
       
       const results = await knex(targetTable)
@@ -1718,35 +1916,10 @@ export const loadRelationshipIdentifiers = async (records, scopeName, scopes, kn
         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;
+    } else if (relDef.type === 'manyToMany') {
+      // Many-to-many relationship
+      // Example: { type: 'manyToMany', through: 'article_tags', foreignKey: 'article_id', otherKey: 'tag_id' }
+      const { through, foreignKey, otherKey } = relDef;
       const fk = foreignKey;
       const ok = otherKey;
       
@@ -1769,10 +1942,10 @@ export const loadRelationshipIdentifiers = async (records, scopeName, scopes, kn
         idsMap[parentId].push(childId);
       });
       
-    } else if (relDef.hasMany && relDef.via) {
+    } else if (relDef.type === 'hasMany' && relDef.via) {
       // Polymorphic reverse (via)
       // Example: publishers hasMany reviews via reviewable (where reviews.reviewable_type = 'publishers')
-      const targetScope = relDef.hasMany;
+      const targetScope = relDef.target;
       const targetRelationships = scopes[targetScope]?.vars?.schemaInfo?.schemaRelationships;
       const viaRel = targetRelationships?.[relDef.via];
       
@@ -1797,14 +1970,16 @@ export const loadRelationshipIdentifiers = async (records, scopeName, scopes, kn
     }
     
     // Apply the collected IDs to all records
-    if (Object.keys(idsMap).length > 0 || relDef.hasMany || relDef.manyToMany) {
+    if (Object.keys(idsMap).length > 0 || relDef.type === 'hasMany' || relDef.type === '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);
+        // For manyToMany, the target type is the relationship name itself
+        // For hasMany/hasOne, the target type is specified in the target property
+        const targetType = (relDef.type === 'manyToMany') ? relName : relDef.target;
         
         record[RELATIONSHIPS_KEY][relName] = {
           data: ids.map(id => ({ 
@@ -1815,4 +1990,4 @@ export const loadRelationshipIdentifiers = async (records, scopeName, scopes, kn
       });
     }
   }
-};
+};