json-rest-api 1.0.14 → 1.0.15

package/plugins/core/lib/querying/knex-window-queries.js

@@ -1,9 +1,9 @@
-import { RestApiResourceError } from '../../../../lib/rest-api-errors.js';
-import { ROW_NUMBER_KEY, DEFAULT_QUERY_LIMIT, DEFAULT_MAX_QUERY_LIMIT, DEFAULT_MAX_INCLUDE_LIMIT } from '../querying-writing/knex-constants.js';
+import { RestApiResourceError } from '../../../../lib/rest-api-errors.js'
+import { ROW_NUMBER_KEY, DEFAULT_QUERY_LIMIT, DEFAULT_MAX_QUERY_LIMIT, DEFAULT_MAX_INCLUDE_LIMIT } from '../querying-writing/knex-constants.js'
 
 /**
  * Builds a window function query for limited includes per parent record
- * 
+ *
  * @param {Object} knex - Knex instance
  * @param {string} tableName - Target table name
  * @param {string} foreignKey - Foreign key field
@@ -13,7 +13,7 @@ import { ROW_NUMBER_KEY, DEFAULT_QUERY_LIMIT, DEFAULT_MAX_QUERY_LIMIT, DEFAULT_M
  * @param {Object} capabilities - Database capabilities
  * @param {Object} scopeVars - Scope variables for defaults and limits
  * @returns {Object} Knex query
- * 
+ *
  * @example
  * // Input: Load max 3 comments per article, ordered by newest first
  * const query = buildWindowedIncludeQuery(
@@ -26,22 +26,22 @@ import { ROW_NUMBER_KEY, DEFAULT_QUERY_LIMIT, DEFAULT_MAX_QUERY_LIMIT, DEFAULT_M
  *   { windowFunctions: true },
  *   { queryDefaultLimit: 10 }
  * );
- * 
+ *
  * // Generated SQL:
  * // WITH _windowed AS (
  * //   SELECT id, text, created_at, article_id,
  * //          ROW_NUMBER() OVER (
- * //            PARTITION BY article_id 
+ * //            PARTITION BY article_id
  * //            ORDER BY created_at DESC
  * //          ) as __$jsonrestapi_rn$__
  * //   FROM comments
  * //   WHERE article_id IN (1, 2, 3)
  * // )
- * // SELECT * FROM _windowed 
+ * // SELECT * FROM _windowed
  * // WHERE __$jsonrestapi_rn$__ <= 3
- * 
+ *
  * // Result: Each article gets max 3 comments, not 3 total
- * 
+ *
  * @example
  * // Input: Database doesn't support window functions
  * const query = buildWindowedIncludeQuery(
@@ -53,23 +53,23 @@ import { ROW_NUMBER_KEY, DEFAULT_QUERY_LIMIT, DEFAULT_MAX_QUERY_LIMIT, DEFAULT_M
  *   { limit: 5 },
  *   { windowFunctions: false, dbInfo: { client: 'mysql', version: '5.7' } }
  * );
- * 
+ *
  * // Throws RestApiResourceError:
- * // "Include limits require window function support. Your database (mysql 5.7) 
- * //  does not support this feature. Window functions are supported in: 
+ * // "Include limits require window function support. Your database (mysql 5.7)
+ * //  does not support this feature. Window functions are supported in:
  * //  PostgreSQL 8.4+, MySQL 8.0+, MariaDB 10.2+, SQLite 3.25+, SQL Server 2005+"
- * 
+ *
  * @description
  * Used by:
  * - loadHasMany when strategy: 'window' and database supports window functions
  * - Enables per-parent limits for one-to-many relationships
- * 
+ *
  * Purpose:
  * - Solves the "N+1 limit" problem where you want X records per parent
  * - Without window functions, LIMIT 10 gives 10 total across all parents
  * - With window functions, each parent gets up to 10 related records
  * - Critical for consistent API responses with includes
- * 
+ *
  * Data flow:
  * 1. Creates subquery with ROW_NUMBER() partitioned by foreign key
  * 2. Numbers rows within each partition based on orderBy
@@ -87,104 +87,104 @@ export const buildWindowedIncludeQuery = (
   capabilities,
   scopeVars = {}
 ) => {
-  const { orderBy = [] } = includeConfig;
-  
+  const { orderBy = [] } = includeConfig
+
   // Apply defaults for limit
-  const effectiveLimit = includeConfig.limit ?? scopeVars.queryDefaultLimit ?? DEFAULT_QUERY_LIMIT;
-  
+  const effectiveLimit = includeConfig.limit ?? scopeVars.queryDefaultLimit ?? DEFAULT_QUERY_LIMIT
+
   // Validate against max
   if (scopeVars.queryMaxLimit && effectiveLimit > scopeVars.queryMaxLimit) {
     throw new RestApiResourceError({
       title: 'Include Limit Exceeds Maximum',
       detail: `Requested include limit (${effectiveLimit}) exceeds queryMaxLimit (${scopeVars.queryMaxLimit})`,
       status: 400
-    });
+    })
   }
-  
+
   // Check if window functions are supported
   if (!capabilities.windowFunctions) {
-    const { dbInfo } = capabilities;
+    const { dbInfo } = capabilities
     throw new RestApiResourceError(
       `Include limits require window function support. Your database (${dbInfo.client} ${dbInfo.version}) does not support this feature. ` +
-      `Window functions are supported in: PostgreSQL 8.4+, MySQL 8.0+, MariaDB 10.2+, SQLite 3.25+, SQL Server 2005+`,
+      'Window functions are supported in: PostgreSQL 8.4+, MySQL 8.0+, MariaDB 10.2+, SQLite 3.25+, SQL Server 2005+',
       {
         subtype: 'unsupported_operation',
         database: dbInfo.client,
         version: dbInfo.version,
         requiredFeature: 'window_functions'
       }
-    );
+    )
   }
-  
+
   // Build the window function query
   // This creates a subquery that partitions by the foreign key and numbers rows
   const subquery = knex(tableName)
     .select('*')
     .select(
       knex.raw(
-        'ROW_NUMBER() OVER (PARTITION BY ?? ORDER BY ' + 
-        buildOrderByClause(orderBy) + 
+        'ROW_NUMBER() OVER (PARTITION BY ?? ORDER BY ' +
+        buildOrderByClause(orderBy) +
         ') as ' + ROW_NUMBER_KEY,
         [foreignKey]
       )
     )
-    .whereIn(foreignKey, parentIds);
-  
+    .whereIn(foreignKey, parentIds)
+
   // Apply field selection if specified
   if (fieldsToSelect !== '*' && Array.isArray(fieldsToSelect)) {
     // Include the foreign key and row number in selection
-    const fieldsWithFK = [...new Set([...fieldsToSelect, foreignKey, ROW_NUMBER_KEY])];
-    subquery.select(fieldsWithFK);
+    const fieldsWithFK = [...new Set([...fieldsToSelect, foreignKey, ROW_NUMBER_KEY])]
+    subquery.select(fieldsWithFK)
   }
-  
+
   // Wrap in outer query to filter by row number
   const query = knex
     .select('*')
     .from(subquery.as('_windowed'))
-    .where(ROW_NUMBER_KEY, '<=', effectiveLimit);
-  
-  return query;
-};
+    .where(ROW_NUMBER_KEY, '<=', effectiveLimit)
+
+  return query
+}
 
 /**
  * Builds ORDER BY clause from array of sort fields
- * 
+ *
  * @param {Array<string>} orderBy - Array of field names, prefix with '-' for DESC
  * @param {string} tablePrefix - Optional table name to prefix fields
  * @returns {string} SQL ORDER BY clause
- * 
+ *
  * @example
  * // Input: Simple ascending sort
  * const clause = buildOrderByClause(['name', 'created_at']);
  * // Output: "name ASC, created_at ASC"
- * 
+ *
  * @example
  * // Input: Mixed ascending/descending with '-' prefix
  * const clause = buildOrderByClause(['name', '-created_at', 'status']);
  * // Output: "name ASC, created_at DESC, status ASC"
- * 
+ *
  * @example
  * // Input: With table prefix for joins
  * const clause = buildOrderByClause(['-updated_at', 'title'], 'articles');
  * // Output: "articles.updated_at DESC, articles.title ASC"
- * 
+ *
  * @example
  * // Input: Empty array (default to id)
  * const clause = buildOrderByClause([]);
  * // Output: "id ASC"
- * 
+ *
  * @description
  * Used by:
  * - buildWindowedIncludeQuery for PARTITION BY ordering
  * - applyStandardIncludeConfig for regular ORDER BY
  * - Query builders that need consistent sort syntax
- * 
+ *
  * Purpose:
  * - Converts API sort syntax (with '-' prefix) to SQL ORDER BY
  * - Handles table prefixing for queries with joins
  * - Provides default ordering by id when none specified
  * - Ensures consistent sort behavior across the API
- * 
+ *
  * Data flow:
  * 1. Receives array of sort fields from API parameters
  * 2. Detects DESC sorts by '-' prefix
@@ -193,27 +193,27 @@ export const buildWindowedIncludeQuery = (
  */
 export const buildOrderByClause = (orderBy, tablePrefix) => {
   if (!orderBy || orderBy.length === 0) {
-    const defaultField = tablePrefix ? `${tablePrefix}.id` : 'id';
-    return `${defaultField} ASC`; // Default ordering
+    const defaultField = tablePrefix ? `${tablePrefix}.id` : 'id'
+    return `${defaultField} ASC` // Default ordering
   }
-  
+
   return orderBy.map(field => {
-    const isDesc = field.startsWith('-');
-    const fieldName = isDesc ? field.substring(1) : field;
-    const qualifiedField = tablePrefix ? `${tablePrefix}.${fieldName}` : fieldName;
-    return `${qualifiedField} ${isDesc ? 'DESC' : 'ASC'}`;
-  }).join(', ');
-};
+    const isDesc = field.startsWith('-')
+    const fieldName = isDesc ? field.substring(1) : field
+    const qualifiedField = tablePrefix ? `${tablePrefix}.${fieldName}` : fieldName
+    return `${qualifiedField} ${isDesc ? 'DESC' : 'ASC'}`
+  }).join(', ')
+}
 
 /**
  * Applies standard (non-windowed) include configuration to a query
- * 
+ *
  * @param {Object} query - Knex query builder instance
  * @param {Object} includeConfig - Include configuration object
  * @param {Object} scopeVars - Scope variables with defaults and limits
  * @param {Object} log - Logger instance
  * @returns {Object} Modified query builder
- * 
+ *
  * @example
  * // Input: Basic include with limit and ordering
  * let query = knex('comments').whereIn('article_id', [1, 2, 3]);
@@ -223,11 +223,11 @@ export const buildOrderByClause = (orderBy, tablePrefix) => {
  *   { queryDefaultLimit: 100, queryMaxLimit: 1000 },
  *   logger
  * );
- * 
+ *
  * // Result: Query modified with:
  * // ORDER BY created_at DESC, id ASC
  * // LIMIT 20
- * 
+ *
  * @example
  * // Input: No explicit limit, uses defaults
  * let query = knex('tags');
@@ -237,12 +237,12 @@ export const buildOrderByClause = (orderBy, tablePrefix) => {
  *   { queryDefaultLimit: 50, queryMaxLimit: 500 },
  *   logger
  * );
- * 
+ *
  * // Result: Uses default limit
  * // ORDER BY name ASC
  * // LIMIT 50
  * // Log: "Using default limit"
- * 
+ *
  * @example
  * // Input: Limit exceeds maximum
  * let query = knex('reviews');
@@ -250,12 +250,12 @@ export const buildOrderByClause = (orderBy, tablePrefix) => {
  *   query,
  *   { limit: 5000 },  // Exceeds max
  *   { queryMaxLimit: 1000, maxIncludeLimit: 500 },
- *   logger  
+ *   logger
  * );
- * 
+ *
  * // Result: Clamped to effective maximum
  * // LIMIT 500 (min of maxIncludeLimit and queryMaxLimit)
- * 
+ *
  * @example
  * // Input: Explicitly disable limit
  * let query = knex('categories');
@@ -265,23 +265,23 @@ export const buildOrderByClause = (orderBy, tablePrefix) => {
  *   { queryDefaultLimit: 100 },
  *   logger
  * );
- * 
+ *
  * // Result: No LIMIT clause added
  * // Log: "No limit applied to include query (explicitly disabled)"
- * 
+ *
  * @description
  * Used by:
  * - loadHasMany when window functions not available or not requested
  * - loadReversePolymorphic for standard relationship queries
  * - Any include loader that needs consistent limit/order handling
- * 
+ *
  * Purpose:
  * - Provides fallback when window functions unavailable
  * - Applies consistent ordering based on API sort syntax
  * - Enforces limit hierarchy: explicit > default > max
  * - Respects both queryMaxLimit and maxIncludeLimit
  * - Logs decisions for debugging
- * 
+ *
  * Data flow:
  * 1. Applies ORDER BY for each field in orderBy array
  * 2. Determines effective limit from explicit/default/max values
@@ -290,39 +290,39 @@ export const buildOrderByClause = (orderBy, tablePrefix) => {
  * 5. Logs the reasoning for the applied limit
  */
 export const applyStandardIncludeConfig = (query, includeConfig, scopeVars, log) => {
-  const { orderBy = [] } = includeConfig;
-  
+  const { orderBy = [] } = includeConfig
+
   // Apply ordering
   orderBy.forEach(field => {
-    const desc = field.startsWith('-');
-    const column = desc ? field.substring(1) : field;
-    query = query.orderBy(column, desc ? 'desc' : 'asc');
-  });
-  
+    const desc = field.startsWith('-')
+    const column = desc ? field.substring(1) : field
+    query = query.orderBy(column, desc ? 'desc' : 'asc')
+  })
+
   // Apply limit with defaults
-  const requestedLimit = includeConfig.limit;
-  const defaultLimit = scopeVars.queryDefaultLimit ?? DEFAULT_QUERY_LIMIT;
-  const limit = requestedLimit ?? defaultLimit;
-  
+  const requestedLimit = includeConfig.limit
+  const defaultLimit = scopeVars.queryDefaultLimit ?? DEFAULT_QUERY_LIMIT
+  const limit = requestedLimit ?? defaultLimit
+
   // Allow explicit null/false to mean no limit
   if (limit !== null && limit !== false) {
-    const maxInclude = scopeVars.maxIncludeLimit || DEFAULT_MAX_INCLUDE_LIMIT;
-    const maxQuery = scopeVars.queryMaxLimit || DEFAULT_MAX_QUERY_LIMIT;
-    const effectiveMax = Math.min(maxInclude, maxQuery);
-    const effectiveLimit = Math.min(limit, effectiveMax);
-    
-    query = query.limit(effectiveLimit);
-    
+    const maxInclude = scopeVars.maxIncludeLimit || DEFAULT_MAX_INCLUDE_LIMIT
+    const maxQuery = scopeVars.queryMaxLimit || DEFAULT_MAX_QUERY_LIMIT
+    const effectiveMax = Math.min(maxInclude, maxQuery)
+    const effectiveLimit = Math.min(limit, effectiveMax)
+
+    query = query.limit(effectiveLimit)
+
     log.debug('Applied include limit:', {
       requested: requestedLimit,
       default: defaultLimit,
       effective: effectiveLimit,
       maxAllowed: effectiveMax,
       note: requestedLimit !== undefined ? 'Using explicit limit' : 'Using default limit'
-    });
+    })
   } else {
-    log.debug('No limit applied to include query (explicitly disabled)');
+    log.debug('No limit applied to include query (explicitly disabled)')
   }
-  
-  return query;
-};
+
+  return query
+}

package/plugins/core/lib/querying/url-helpers.js

@@ -1,80 +1,80 @@
 /**
  * URL Helper Functions
- * 
+ *
  * Centralized functions for URL generation to avoid code duplication
  * and support flexible URL prefix override capabilities.
  */
 
 /**
  * Get the complete URL prefix, handling all calculation and override logic
- * 
+ *
  * Priority order:
  * 1. context.urlPrefixOverride - Explicit override (from hooks or middleware)
  * 2. context.urlPrefix - Pre-calculated URL prefix
  * 3. Calculate from request if provided
  * 4. scope.vars.transport?.mountPath - Fallback to mount path
  * 5. '' - Empty string as final fallback
- * 
+ *
  * @param {Object} context - Request context (may have urlPrefixOverride or urlPrefix)
  * @param {Object} scope - Scope/resource object with transport vars
  * @param {Object} req - Optional Express request object for auto-calculation
  * @returns {string} The final URL prefix to use
- * 
+ *
  * @example
  * // With full context
  * const urlPrefix = getUrlPrefix(context, scope);
- * 
+ *
  * @example
  * // With request object for auto-calculation
  * const urlPrefix = getUrlPrefix({}, api, req);
  */
-export function getUrlPrefix(context, scope, req = null) {
+export function getUrlPrefix (context, scope, req = null) {
   // Priority 1: Explicit override
   if (context?.urlPrefixOverride) {
-    return context.urlPrefixOverride;
+    return context.urlPrefixOverride
   }
-  
+
   // Priority 2: Pre-calculated urlPrefix
   if (context?.urlPrefix) {
-    return context.urlPrefix;
+    return context.urlPrefix
   }
-  
+
   // Priority 3: Calculate from request if provided
   if (req) {
-    const protocol = req.get?.('x-forwarded-proto') || req.protocol || 'http';
-    const host = req.get?.('x-forwarded-host') || req.get?.('host');
-    const mountPath = scope?.vars?.transport?.mountPath || '';
-    
+    const protocol = req.get?.('x-forwarded-proto') || req.protocol || 'http'
+    const host = req.get?.('x-forwarded-host') || req.get?.('host')
+    const mountPath = scope?.vars?.transport?.mountPath || ''
+
     if (host) {
-      return `${protocol}://${host}${mountPath}`;
+      return `${protocol}://${host}${mountPath}`
     }
   }
-  
+
   // Priority 4: Fallback to mount path
-  return scope?.vars?.transport?.mountPath || '';
+  return scope?.vars?.transport?.mountPath || ''
 }
 
 /**
  * Build a complete resource URL
- * 
+ *
  * @param {Object} context - Request context
  * @param {Object} scope - Scope containing transport vars
  * @param {string} scopeName - Resource type name
  * @param {string} id - Resource ID
  * @returns {string} Complete resource URL
- * 
+ *
  * @example
  * const url = buildResourceUrl(context, scope, 'books', '123');
  * // Returns: "https://api.example.com/api/books/123"
  */
-export function buildResourceUrl(context, scope, scopeName, id) {
-  const urlPrefix = getUrlPrefix(context, scope);
-  return `${urlPrefix}/${scopeName}/${id}`;
+export function buildResourceUrl (context, scope, scopeName, id) {
+  const urlPrefix = getUrlPrefix(context, scope)
+  return `${urlPrefix}/${scopeName}/${id}`
 }
 
 /**
  * Build a relationship URL
- * 
+ *
  * @param {Object} context - Request context
  * @param {Object} scope - Scope containing transport vars
  * @param {string} scopeName - Resource type name
@@ -82,38 +82,38 @@ export function buildResourceUrl(context, scope, scopeName, id) {
  * @param {string} relationshipName - Name of the relationship
  * @param {boolean} isRelationshipEndpoint - If true, builds /relationships/ URL
  * @returns {string} Complete relationship URL
- * 
+ *
  * @example
  * // For relationship linkage endpoint
  * buildRelationshipUrl(context, scope, 'books', '1', 'author', true);
  * // Returns: "https://api.example.com/api/books/1/relationships/author"
- * 
+ *
  * // For related resource endpoint
  * buildRelationshipUrl(context, scope, 'books', '1', 'author', false);
  * // Returns: "https://api.example.com/api/books/1/author"
  */
-export function buildRelationshipUrl(context, scope, scopeName, id, relationshipName, isRelationshipEndpoint = false) {
-  const urlPrefix = getUrlPrefix(context, scope);
+export function buildRelationshipUrl (context, scope, scopeName, id, relationshipName, isRelationshipEndpoint = false) {
+  const urlPrefix = getUrlPrefix(context, scope)
   if (isRelationshipEndpoint) {
-    return `${urlPrefix}/${scopeName}/${id}/relationships/${relationshipName}`;
+    return `${urlPrefix}/${scopeName}/${id}/relationships/${relationshipName}`
   }
-  return `${urlPrefix}/${scopeName}/${id}/${relationshipName}`;
+  return `${urlPrefix}/${scopeName}/${id}/${relationshipName}`
 }
 
 /**
  * Build a collection URL with optional query string
- * 
+ *
  * @param {Object} context - Request context
  * @param {Object} scope - Scope containing transport vars
  * @param {string} scopeName - Resource type name
  * @param {string} queryString - Optional query string (with leading ?)
  * @returns {string} Complete collection URL
- * 
+ *
  * @example
  * buildCollectionUrl(context, scope, 'books', '?page[size]=10');
  * // Returns: "https://api.example.com/api/books?page[size]=10"
  */
-export function buildCollectionUrl(context, scope, scopeName, queryString = '') {
-  const urlPrefix = getUrlPrefix(context, scope);
-  return `${urlPrefix}/${scopeName}${queryString}`;
-}
+export function buildCollectionUrl (context, scope, scopeName, queryString = '') {
+  const urlPrefix = getUrlPrefix(context, scope)
+  return `${urlPrefix}/${scopeName}${queryString}`
+}