json-rest-api 1.0.10 → 1.0.11

package/plugins/core/lib/querying/knex-cross-table-search.js

@@ -1,67 +1,23 @@
+// Cross-table search helper functions that enable filtering across related database tables
+  
 /**
- * Creates cross-table search helper functions that enable filtering across related database tables
+ * Validates that a field exists and is indexed for cross-table search
  * 
+ * @async
  * @param {Object} scopes - All registered hooked-api scopes containing schema and relationship definitions
  * @param {Object} log - Logger instance for debug and trace output
- * @returns {Object} Object containing validateCrossTableField, buildJoinChain, analyzeRequiredIndexes, and createRequiredIndexes functions
- * 
- * @example
- * // Input: API scopes with relationships defined
- * const scopes = {
- *   articles: { vars: { schemaInfo: { schema: articlesSchema, tableName: 'articles' } } },
- *   authors: { vars: { schemaInfo: { schema: authorsSchema, tableName: 'authors' } } },
- *   companies: { vars: { schemaInfo: { schema: companiesSchema, tableName: 'companies' } } }
- * };
- * 
- * const helpers = createCrossTableSearchHelpers(scopes, logger);
- * 
- * // Output: Object with helper functions
- * // {
- * //   validateCrossTableField: [Function],
- * //   buildJoinChain: [Function],
- * //   analyzeRequiredIndexes: [Function],
- * //   createRequiredIndexes: [Function]
- * // }
- * 
- * @description
- * Used by:
- * - rest-api-knex-plugin uses this during dataQuery to enable cross-table filtering
- * - Called when filter parameters reference fields from related tables (e.g., filter[author.name]=John)
- * 
- * Purpose:
- * - Enables powerful filtering across relationships without exposing SQL complexity to API consumers
- * - Automatically builds optimal JOIN chains based on schema relationships
- * - Prevents N+1 queries by using efficient SQL JOINs instead of multiple queries
- * 
- * Data flow:
- * 1. API receives filter like filter[author.company.name]=Acme
- * 2. rest-api-knex-plugin detects cross-table reference (contains dots)
- * 3. Calls buildJoinChain to construct SQL JOIN path from articles → authors → companies
- * 4. Adds JOINs to main query, enabling filtering on company name while querying articles
- * 5. Returns articles where author's company name matches 'Acme'
- */
-export const createCrossTableSearchHelpers = (scopes, log) => {
-  
-  /**
-   * Validates that a field exists and is indexed for cross-table search
-   * 
-   * @async
-   * @param {string} targetScopeName - The scope containing the field to validate
-   * @param {string} fieldName - The field name to check
-   * @param {Set<string>} [searchedScopes=new Set()] - Internal parameter to prevent circular references
-   * @returns {Promise<{targetSchema: Object, fieldDef: Object}>} The validated schema and field definition
-   * @throws {Error} If scope not found, field not found, field not indexed, or circular reference detected
+ * @param {string} targetScopeName - The scope containing the field to validate
+ * @param {string} fieldName - The field name to check
+ * @param {Set<string>} [searchedScopes=new Set()] - Internal parameter to prevent circular references
+ * @returns {Promise<void>}
+ * @throws {Error} If scope not found, field not found, field not indexed, or circular reference detected
    * 
    * @example
    * // Input: Validate indexed field
    * // Schema has: companies.name with indexed: true
-   * const result = await validateCrossTableField('companies', 'name');
+   * await validateCrossTableField(scopes, log, 'companies', 'name');
    * 
-   * // Output: Successfully returns schema and field definition
-   * // {
-   * //   targetSchema: { structure: { name: { type: 'string', indexed: true }, ... } },
-   * //   fieldDef: { type: 'string', indexed: true }
-   * // }
+   * // Output: Validation succeeds (no error thrown)
    * 
    * @example
    * // Input: Non-indexed field
@@ -88,7 +44,7 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
    * - Ensures performance by requiring indexes on searchable fields
    * - Part of the validation phase before expensive JOIN operations
    */
-  const validateCrossTableField = async (targetScopeName, fieldName, searchedScopes = new Set()) => {
+export const validateCrossTableField = async (scopes, log, targetScopeName, fieldName, searchedScopes = new Set()) => {
     log.trace('[VALIDATE] Starting validateCrossTableField:', { targetScopeName, fieldName, searchedScopes: Array.from(searchedScopes) });
     
     if (searchedScopes.has(targetScopeName)) {
@@ -96,21 +52,21 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
     }
     
     log.trace('[VALIDATE] Getting target schema for:', targetScopeName);
-    let targetSchema;
+    let targetSchemaInstance;
     try {
-      targetSchema = scopes[targetScopeName].vars.schemaInfo.schema;;
-      log.trace('[VALIDATE] Got target schema:', { scopeName: targetScopeName, schemaKeys: Object.keys(targetSchema || {}) });
+      targetSchemaInstance = scopes[targetScopeName].vars.schemaInfo.schemaInstance;;
+      log.trace('[VALIDATE] Got target schema:', { scopeName: targetScopeName, schemaKeys: Object.keys(targetSchemaInstance || {}) });
     } catch (error) {
       log.trace('[VALIDATE] Error getting target schema:', error.message);
       throw new Error(`Target scope '${targetScopeName}' not found`);
     }
     
-    if (!targetSchema) {
+    if (!targetSchemaInstance) {
       log.trace('[VALIDATE] Target schema is null/undefined');
       throw new Error(`Target scope '${targetScopeName}' has no schema`);
     }
     
-    const fieldDef = targetSchema.structure[fieldName];
+    const fieldDef = targetSchemaInstance.structure[fieldName];
     log.trace('[VALIDATE] Field lookup result:', { fieldName, fieldExists: !!fieldDef });
     if (!fieldDef) {
       throw new Error(`Field '${fieldName}' not found in scope '${targetScopeName}'`);
@@ -121,20 +77,20 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
       throw new Error(`Field '${targetScopeName}.${fieldName}' is not indexed. Add 'indexed: true' to allow cross-table search`);
     }
     
-    const result = { targetSchema, fieldDef };
     log.trace('[VALIDATE] Validation successful for field:', `${targetScopeName}.${fieldName}`);
-    return result;
   };
 
-  /**
-   * Builds a chain of SQL JOINs to reach a field in a related table
-   * 
-   * @async
-   * @param {string} fromScopeName - Starting scope (e.g., 'articles')
-   * @param {string} targetPath - Dot-separated path to target field (e.g., 'author.company.name')
-   * @param {Set<string>} [searchedScopes=new Set()] - Internal parameter to prevent circular references
-   * @returns {Promise<Object>} JOIN information for query builder
-   * @throws {Error} If path is invalid or relationships not properly configured
+/**
+ * Builds a chain of SQL JOINs to reach a field in a related table
+ * 
+ * @async
+ * @param {Object} scopes - All registered hooked-api scopes containing schema and relationship definitions
+ * @param {Object} log - Logger instance for debug and trace output
+ * @param {string} fromScopeName - Starting scope (e.g., 'articles')
+ * @param {string} targetPath - Dot-separated path to target field (e.g., 'author.company.name')
+ * @param {Set<string>} [searchedScopes=new Set()] - Internal parameter to prevent circular references
+ * @returns {Promise<Object>} JOIN information for query builder
+ * @throws {Error} If path is invalid or relationships not properly configured
    * 
    * @example
    * // Input: Simple belongsTo relationship
@@ -219,7 +175,7 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
    * 5. Returns complete JOIN information for SQL query builder
    * 6. Query builder adds these JOINs to enable filtering on related data
    */
-  const buildJoinChain = async (fromScopeName, targetPath, searchedScopes = new Set()) => {
+export const buildJoinChain = async (scopes, log, fromScopeName, targetPath, searchedScopes = new Set()) => {
     log.trace('[BUILD-JOIN] Starting buildJoinChain:', { fromScopeName, targetPath });
     
     const pathSegments = targetPath.split('.');
@@ -246,7 +202,7 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
       searchedScopes.add(currentScope);
       
       const schemaInfo = scopes[currentScope].vars.schemaInfo
-      const currentSchema = schemaInfo.schema;
+      const currentSchema = schemaInfo.schemaInstance;
       const currentRelationships = schemaInfo.schemaRelationships;
       
       let foundRelationship = null;
@@ -256,7 +212,7 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
       
       if (currentRelationships) {
         for (const [relName, relDef] of Object.entries(currentRelationships)) {
-          if (relDef.hasMany === targetScope) {
+          if (relDef.type === 'hasMany' && relDef.target === targetScope) {
             if (relDef.via) {
               const targetRelationships = scopes[targetScope].vars.schemaInfo.schemaRelationships;
               const viaRel = targetRelationships?.[relDef.via];
@@ -326,9 +282,9 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
         );
       }
       
-      const sourceSchema = scopes[currentScope].vars.schemaInfo.schema;
+      const sourceSchema = scopes[currentScope].vars.schemaInfo.schemaInstance;
       const sourceTableName = scopes[currentScope].vars.schemaInfo.tableName
-      const targetSchema = scopes[targetScope].vars.schemaInfo.schema;
+      const targetSchemaInstance = scopes[targetScope].vars.schemaInfo.schemaInstance;
       const targetTableName = scopes[targetScope].vars.schemaInfo.tableName
       
       if (relationshipType === 'manyToMany') {
@@ -346,7 +302,8 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
           isOneToMany: true,
           isPolymorphic: false,
           relationshipField: foreignKey,
-          relationshipType: 'manyToMany_pivot'
+          relationshipType: 'manyToMany_pivot',
+          targetScopeName: through
         });
         
         const targetAlias = `${through}_to_${targetScope}_${targetScope}`;
@@ -359,7 +316,8 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
           isOneToMany: false,
           isPolymorphic: false,
           relationshipField: otherKey,
-          relationshipType: 'manyToMany_target'
+          relationshipType: 'manyToMany_target',
+          targetScopeName: targetScope
         });
       } else {
         const joinAlias = `${currentScope}_to_${targetScope}_${targetScope}`;
@@ -384,7 +342,8 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
           isOneToMany: relationshipType === 'hasMany' || relationshipType === 'hasManyPolymorphic',
           isPolymorphic: relationshipType === 'hasManyPolymorphic',
           relationshipField,
-          relationshipType
+          relationshipType,
+          targetScopeName: targetScope
         });
       }
       
@@ -392,7 +351,7 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
     }
     
     const finalScope = relationshipPath[relationshipPath.length - 1];
-    await validateCrossTableField(finalScope, targetFieldName, searchedScopes);
+    await validateCrossTableField(scopes, log, finalScope, targetFieldName, searchedScopes);
     
     if (joinChain.length === 0) {
       throw new Error(`Invalid path '${targetPath}': no relationships to traverse`);
@@ -408,7 +367,8 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
         targetField: targetFieldName,
         isOneToMany: joinChain.some(j => j.isOneToMany),
         isMultiLevel: true,
-        joinChain
+        joinChain,
+        targetScopeName: finalScope
       };
     } else {
       return {
@@ -418,17 +378,20 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
         targetField: targetFieldName,
         joinCondition: lastJoin.joinCondition,
         isOneToMany: lastJoin.isOneToMany,
-        isPolymorphic: lastJoin.isPolymorphic
+        isPolymorphic: lastJoin.isPolymorphic,
+        targetScopeName: lastJoin.targetScopeName || finalScope
       };
     }
   };
 
-  /**
-   * Analyzes a search schema to identify which fields need database indexes
-   * 
-   * @param {string} scopeName - The scope being analyzed
-   * @param {Object} searchSchema - Search schema definition with filter fields
-   * @returns {Array<Object>} Array of required indexes with scope, field, and reason
+/**
+ * Analyzes a search schema to identify which fields need database indexes
+ * 
+ * @param {Object} scopes - All registered hooked-api scopes containing schema and relationship definitions
+ * @param {Object} log - Logger instance for debug and trace output
+ * @param {string} scopeName - The scope being analyzed
+ * @param {Object} searchSchema - Search schema definition with filter fields
+ * @returns {Array<Object>} Array of required indexes with scope, field, and reason
    * 
    * @example
    * // Input: Search schema with cross-table references
@@ -486,10 +449,10 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
    * - Output can be used to create indexes manually or automatically
    * - Prevents performance issues before queries are executed
    */
-  const analyzeRequiredIndexes = (scopeName, searchSchema) => {
+export const analyzeRequiredIndexes = (scopes, log, scopeName, schemaInfo) => {
     const requiredIndexes = [];
     
-    const schemaToAnalyze = searchSchema.structure || searchSchema;
+    const schemaToAnalyze = schemaInfo.searchSchemaStructure
     
     Object.entries(schemaToAnalyze).forEach(([filterKey, fieldDef]) => {
       if (fieldDef.actualField && fieldDef.actualField.includes('.')) {
@@ -518,13 +481,15 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
     return requiredIndexes;
   };
 
-  /**
-   * Creates database indexes for fields identified by analyzeRequiredIndexes
-   * 
-   * @async
-   * @param {Array<Object>} requiredIndexes - Index requirements from analyzeRequiredIndexes
-   * @param {Object} knex - Knex database connection instance
-   * @returns {Promise<Array<Object>>} Array of successfully created indexes
+/**
+ * Creates database indexes for fields identified by analyzeRequiredIndexes
+ * 
+ * @async
+ * @param {Object} scopes - All registered hooked-api scopes containing schema and relationship definitions
+ * @param {Object} log - Logger instance for debug and trace output
+ * @param {Array<Object>} requiredIndexes - Index requirements from analyzeRequiredIndexes
+ * @param {Object} knex - Knex database connection instance
+ * @returns {Promise<Array<Object>>} Array of successfully created indexes
    * 
    * @example
    * // Input: Required indexes from analysis
@@ -574,12 +539,11 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
    * - Improves query performance for cross-table searches
    * - Part of the database optimization phase
    */
-  const createRequiredIndexes = async (requiredIndexes, knex) => {
+export const createRequiredIndexes = async (scopes, log, requiredIndexes, knex) => {
     const createdIndexes = [];
     
     for (const indexInfo of requiredIndexes) {
       const { scope, field } = indexInfo;
-      const schema = scopes[scope].vars.schemaInfo.schema;
       const tableName = scopes[scope].vars.schemaInfo.tableName
       const indexName = `idx_${tableName}_${field}_search`;
       
@@ -599,11 +563,3 @@ export const createCrossTableSearchHelpers = (scopes, log) => {
     
     return createdIndexes;
   };
-
-  return {
-    validateCrossTableField,
-    buildJoinChain,
-    analyzeRequiredIndexes,
-    createRequiredIndexes
-  };
-};

package/plugins/core/lib/querying/knex-json-api-transformers-querying.js

@@ -1,5 +1,6 @@
 import { getForeignKeyFields as getForeignKeyFieldsFromUtils } from '../querying-writing/field-utils.js';
 import { RELATIONSHIPS_KEY, RELATIONSHIP_METADATA_KEY, ROW_NUMBER_KEY, COMPUTED_DEPENDENCIES_KEY, getSchemaStructure } from '../querying-writing/knex-constants.js';
+import { getUrlPrefix, buildResourceUrl, buildRelationshipUrl } from './url-helpers.js';
 
 /**
  * Transforms a flat database record into JSON:API resource format
@@ -74,11 +75,7 @@ import { RELATIONSHIPS_KEY, RELATIONSHIP_METADATA_KEY, ROW_NUMBER_KEY, COMPUTED_
 const toJsonApi = (scope, record, deps) => {
   if (!record) return null;
   
-  const { 
-    vars: { 
-      schemaInfo: { schema }
-    }
-  } = scope;
+  const schemaInstance = scope.vars.schemaInfo.schemaInstance
   
   const { context } = deps;
   const scopeName = context.scopeName;
@@ -87,7 +84,7 @@ const toJsonApi = (scope, record, deps) => {
   
   const { id, ...allAttributes } = record;
   
-  const foreignKeys = schema ? getForeignKeyFieldsFromUtils(schema) : new Set();
+  const foreignKeys = schemaInstance ? getForeignKeyFieldsFromUtils(schemaInstance) : new Set();
   
   const internalFields = new Set([
     RELATIONSHIPS_KEY,
@@ -187,10 +184,10 @@ const toJsonApi = (scope, record, deps) => {
 export const toJsonApiRecord = (scope, record, scopeName) => {
   const { 
     vars: { 
-      schemaInfo: { schema, schemaRelationships: relationships, idProperty }
+      schemaInfo: { schemaRelationships: relationships, idProperty }
     }
   } = scope;
-  
+    
   const polymorphicFields = new Set();
   try {
     Object.entries(relationships || {}).forEach(([relName, relDef]) => {
@@ -350,13 +347,13 @@ export const toJsonApiRecord = (scope, record, scopeName) => {
 export const buildJsonApiResponse = async (scope, records, included = [], isSingle = false, scopeName, context) => {
   const { 
     vars: { 
-      schemaInfo: { schema, schemaRelationships: relationships, idProperty }
+      schemaInfo: { schemaInstance: schemaInstance, schemaRelationships: relationships, idProperty }
     }
   } = scope;
   
   const idField = idProperty || 'id';
   
-  const schemaStructure = getSchemaStructure(schema);
+  const schemaStructure = getSchemaStructure(schemaInstance);
   
   const processedRecords = records.map(record => {
     const { [RELATIONSHIPS_KEY]: _relationships, ...cleanRecord } = record;
@@ -378,10 +375,9 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
               }
             };
             
-            const urlPrefix = scope.vars.publicBaseUrl || scope.vars.transport?.mountPath || '';
             relationshipObject.links = {
-              self: `${urlPrefix}/${scopeName}/${record[idField]}/relationships/${fieldDef.as}`,
-              related: `${urlPrefix}/${scopeName}/${record[idField]}/${fieldDef.as}`
+              self: buildRelationshipUrl(context, scope, scopeName, record[idField], fieldDef.as, true),
+              related: buildRelationshipUrl(context, scope, scopeName, record[idField], fieldDef.as, false)
             };
             
             jsonApiRecord.relationships[fieldDef.as] = relationshipObject;
@@ -390,10 +386,9 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
               data: null
             };
             
-            const urlPrefix = scope.vars.publicBaseUrl || scope.vars.transport?.mountPath || '';
             relationshipObject.links = {
-              self: `${urlPrefix}/${scopeName}/${record[idField]}/relationships/${fieldDef.as}`,
-              related: `${urlPrefix}/${scopeName}/${record[idField]}/${fieldDef.as}`
+              self: buildRelationshipUrl(context, scope, scopeName, record[idField], fieldDef.as, true),
+              related: buildRelationshipUrl(context, scope, scopeName, record[idField], fieldDef.as, false)
             };
             
             jsonApiRecord.relationships[fieldDef.as] = relationshipObject;
@@ -416,10 +411,9 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
             }
           };
           
-          const urlPrefix = scope.vars.publicBaseUrl || scope.vars.transport?.mountPath || '';
           relationshipObject.links = {
-            self: `${urlPrefix}/${scopeName}/${record[idField]}/relationships/${relName}`,
-            related: `${urlPrefix}/${scopeName}/${record[idField]}/${relName}`
+            self: buildRelationshipUrl(context, scope, scopeName, record[idField], relName, true),
+            related: buildRelationshipUrl(context, scope, scopeName, record[idField], relName, false)
           };
           
           jsonApiRecord.relationships[relName] = relationshipObject;
@@ -429,10 +423,9 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
             data: null
           };
           
-          const urlPrefix = scope.vars.publicBaseUrl || scope.vars.transport?.mountPath || '';
           relationshipObject.links = {
-            self: `${urlPrefix}/${scopeName}/${record[idField]}/relationships/${relName}`,
-            related: `${urlPrefix}/${scopeName}/${record[idField]}/${relName}`
+            self: buildRelationshipUrl(context, scope, scopeName, record[idField], relName, true),
+            related: buildRelationshipUrl(context, scope, scopeName, record[idField], relName, false)
           };
           
           jsonApiRecord.relationships[relName] = relationshipObject;
@@ -443,18 +436,18 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
     return jsonApiRecord;
   });
   
-  const urlPrefix = scope.vars.publicBaseUrl || scope.vars.transport?.mountPath || '';
+  const urlPrefix = context.urlPrefix || scope.vars.transport?.mountPath || '';
   const normalizedData = isSingle ? processedRecords[0] : processedRecords;
   
   if (normalizedData) {
     if (Array.isArray(normalizedData)) {
       normalizedData.forEach(item => {
         if (!item.links) item.links = {};
-        item.links.self = `${urlPrefix}/${scopeName}/${item.id}`;
+        item.links.self = buildResourceUrl(context, scope, scopeName, item.id);
       });
     } else {
       if (!normalizedData.links) normalizedData.links = {};
-      normalizedData.links.self = `${urlPrefix}/${scopeName}/${normalizedData.id}`;
+      normalizedData.links.self = buildResourceUrl(context, scope, scopeName, normalizedData.id);
     }
   }
 
@@ -465,7 +458,7 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
   if (included.length > 0) {
     included.forEach(item => {
       if (!item.links) item.links = {};
-      item.links.self = `${urlPrefix}/${item.type}/${item.id}`;
+      item.links.self = buildResourceUrl(context, scope, item.type, item.id);
     });
     
     response.included = included;
@@ -480,9 +473,10 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
   if (context?.returnMeta?.paginationLinks) {
     response.links = context.returnMeta.paginationLinks;
   } else {
+    const urlPrefix = getUrlPrefix(context, scope);
     response.links = {
       self: isSingle 
-        ? `${urlPrefix}/${scopeName}/${normalizedData.id}`
+        ? buildResourceUrl(context, scope, scopeName, normalizedData.id)
         : `${urlPrefix}/${scopeName}${context?.returnMeta?.queryString || ''}`
     };
   }

package/plugins/core/lib/querying/knex-pagination-helpers.js

@@ -99,11 +99,11 @@ export const calculatePaginationMeta = (total, page, pageSize) => {
  * 
  * // Output - complete URLs with all parameters preserved:
  * // {
- * //   self: '/api/v1/articles?filter[status]=published&sort=-created_at&page[number]=2&page[size]=20',
- * //   first: '/api/v1/articles?filter[status]=published&sort=-created_at&page[number]=1&page[size]=20',
- * //   last: '/api/v1/articles?filter[status]=published&sort=-created_at&page[number]=5&page[size]=20',
- * //   prev: '/api/v1/articles?filter[status]=published&sort=-created_at&page[number]=1&page[size]=20',
- * //   next: '/api/v1/articles?filter[status]=published&sort=-created_at&page[number]=3&page[size]=20'
+ * //   self: '/api/articles?filter[status]=published&sort=-created_at&page[number]=2&page[size]=20',
+ * //   first: '/api/articles?filter[status]=published&sort=-created_at&page[number]=1&page[size]=20',
+ * //   last: '/api/articles?filter[status]=published&sort=-created_at&page[number]=5&page[size]=20',
+ * //   prev: '/api/articles?filter[status]=published&sort=-created_at&page[number]=1&page[size]=20',
+ * //   next: '/api/articles?filter[status]=published&sort=-created_at&page[number]=3&page[size]=20'
  * // }
  * 
  * @example
@@ -137,33 +137,41 @@ export const calculatePaginationMeta = (total, page, pageSize) => {
  * 4. Added to response.links for client navigation
  */
 export const generatePaginationLinks = (urlPrefix, scopeName, queryParams, paginationMeta) => {
-  if (!urlPrefix) return null;
+  // Allow empty urlPrefix to generate relative links
+  // if (!urlPrefix) return null;
   
   const { page, pageCount, pageSize } = paginationMeta;
   const links = {};
   
   const otherParams = Object.entries(queryParams)
     .filter(([key]) => key !== 'page')
-    .map(([key, value]) => {
+    .flatMap(([key, value]) => {
       if (Array.isArray(value)) {
-        return value.map(v => `${key}=${encodeURIComponent(v)}`).join('&');
-      } else if (typeof value === 'object' && value !== null) {
+        return value.length === 0
+          ? []
+          : value.map((v) => `${key}=${encodeURIComponent(v)}`);
+      }
+      if (typeof value === 'object' && value !== null) {
         const parts = [];
         const processObject = (obj, prefix) => {
           Object.entries(obj).forEach(([k, v]) => {
             const newKey = prefix ? `${prefix}[${k}]` : `${key}[${k}]`;
             if (typeof v === 'object' && v !== null && !Array.isArray(v)) {
               processObject(v, newKey);
-            } else {
+            } else if (v !== undefined && v !== null && !(Array.isArray(v) && v.length === 0)) {
               parts.push(`${newKey}=${encodeURIComponent(v)}`);
             }
           });
         };
         processObject(value, key);
-        return parts.join('&');
+        return parts;
+      }
+      if (value === undefined || value === null) {
+        return [];
       }
-      return `${key}=${encodeURIComponent(value)}`;
+      return [`${key}=${encodeURIComponent(value)}`];
     })
+    .filter(Boolean)
     .join('&');
   
   const baseUrl = `${urlPrefix}/${scopeName}`;
@@ -420,33 +428,41 @@ export const parseCursor = (cursor) => {
  * 5. Client uses next link to fetch subsequent pages
  */
 export const generateCursorPaginationLinks = (urlPrefix, scopeName, queryParams, records, pageSize, hasMore, sortFields = ['id']) => {
-  if (!urlPrefix || !records.length) return null;
+  // Allow empty urlPrefix to generate relative links
+  if (!records.length) return null;
   
   const links = {};
   const baseUrl = `${urlPrefix}/${scopeName}`;
   
   const otherParams = Object.entries(queryParams)
     .filter(([key]) => key !== 'page')
-    .map(([key, value]) => {
+    .flatMap(([key, value]) => {
       if (Array.isArray(value)) {
-        return value.map(v => `${key}=${encodeURIComponent(v)}`).join('&');
-      } else if (typeof value === 'object' && value !== null) {
+        return value.length === 0
+          ? []
+          : value.map((v) => `${key}=${encodeURIComponent(v)}`);
+      }
+      if (typeof value === 'object' && value !== null) {
         const parts = [];
         const processObject = (obj, prefix) => {
           Object.entries(obj).forEach(([k, v]) => {
             const newKey = prefix ? `${prefix}[${k}]` : `${key}[${k}]`;
             if (typeof v === 'object' && v !== null && !Array.isArray(v)) {
               processObject(v, newKey);
-            } else {
+            } else if (v !== undefined && v !== null && !(Array.isArray(v) && v.length === 0)) {
               parts.push(`${newKey}=${encodeURIComponent(v)}`);
             }
           });
         };
         processObject(value, key);
-        return parts.join('&');
+        return parts;
       }
-      return `${key}=${encodeURIComponent(value)}`;
+      if (value === undefined || value === null) {
+        return [];
+      }
+      return [`${key}=${encodeURIComponent(value)}`];
     })
+    .filter(Boolean)
     .join('&');
   
   const queryPrefix = otherParams ? `?${otherParams}&` : '?';
@@ -541,4 +557,4 @@ export const buildCursorMeta = (records, pageSize, hasMore, sortFields = ['id'])
   }
   
   return meta;
-};
+};

package/plugins/core/lib/querying/knex-query-helpers-base.js

@@ -55,20 +55,55 @@
  * 4. Smaller result sets improve query performance
  * 5. JSON:API response includes only requested attributes
  */
-export const buildQuerySelection = (query, tableName, fieldsToSelect, useTablePrefix = false) => {
+export const buildQuerySelection = (
+  query,
+  tableName,
+  fieldsToSelect,
+  useTablePrefix = false,
+  options = {},
+) => {
+  const translateColumn = options.translateColumn;
+
+  const applyTranslation = (field, aliasForField) => {
+    if (translateColumn) {
+      const translated = translateColumn(field, aliasForField);
+      if (translated) {
+        return translated;
+      }
+    }
+
+    if (aliasForField) {
+      return `${aliasForField}.${field}`;
+    }
+    return field;
+  };
+
+  const targetAlias = useTablePrefix ? tableName : null;
+
   if (fieldsToSelect === '*') {
+    const translated = translateColumn ? translateColumn('*', targetAlias) : null;
+    if (translated) {
+      return query.select(translated);
+    }
     return useTablePrefix ? query.select(`${tableName}.*`) : query;
-  } else {
-    const fields = useTablePrefix 
-      ? fieldsToSelect.map(field => {
-          // Handle aliased fields (e.g., "user_id as id")
-          if (field.includes(' as ')) {
-            const [realField, alias] = field.split(' as ');
-            return `${tableName}.${realField.trim()} as ${alias.trim()}`;
-          }
-          return `${tableName}.${field}`;
-        })
-      : fieldsToSelect;
-    return query.select(fields);
   }
-};
+
+  const fieldsArray = Array.isArray(fieldsToSelect)
+    ? fieldsToSelect
+    : Array.from(fieldsToSelect || []);
+
+  const translatedFields = fieldsArray.map((field) => {
+    if (typeof field !== 'string') return field;
+
+    const aliasMatch = field.match(/\s+as\s+/i);
+    if (aliasMatch) {
+      const [source, alias] = field.split(/\s+as\s+/i);
+      const translatedSource = applyTranslation(source.trim(), targetAlias);
+      return `${translatedSource} as ${alias.trim()}`;
+    }
+
+    return applyTranslation(field.trim(), targetAlias);
+  });
+
+  return query.select(translatedFields);
+};