json-rest-api 1.0.7 → 1.0.8

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

@@ -1,87 +1,105 @@
-/**
- * @module knex-process-includes
- * @description Include processing orchestration for REST API Knex Plugin
- * 
- * This module handles the high-level orchestration of relationship includes,
- * coordinating with the relationship include helpers to load related resources
- * efficiently while respecting transactions and sparse fieldsets.
- */
-
 import { buildIncludedResources } from './knex-relationship-includes.js';
 
 /**
- * Processes the ?include= parameter to load related resources.
- * 
- * This function handles the JSON:API include parameter, which allows clients to
- * request related resources in a single request. It supports nested includes
- * (like 'comments.user') and uses efficient batch loading to avoid N+1 queries.
- * The function respects database transactions and sparse fieldsets for included
- * resources.
+ * Processes the ?include= parameter to load related resources efficiently
  * 
  * @param {Object} scope - The scope object for the primary resource
  * @param {Array<Object>} records - The primary records to load includes for
  * @param {Object} deps - Dependencies object containing log, scopes, knex, and context
  * @returns {Promise<Array<Object>>} Array of included resources in JSON:API format
  * 
- * @example <caption>Basic relationship includes</caption>
- * const scope = api.resources['articles'];
- * const articles = [{ id: 1, author_id: 10 }, { id: 2, author_id: 11 }];
+ * @example
+ * // Input: Articles with author relationship
+ * const articles = [
+ *   { id: 1, title: 'First Article', author_id: 10 },
+ *   { id: 2, title: 'Second Article', author_id: 11 },
+ *   { id: 3, title: 'Third Article', author_id: 10 }  // Same author as article 1
+ * ];
+ * 
  * const deps = {
- *   log, scopes, knex,
  *   context: { 
  *     scopeName: 'articles',
  *     queryParams: { include: ['author'] },
- *     schemaInfo: scope.vars.schemaInfo
+ *     schemaInfo: { idProperty: 'id' }
  *   }
  * };
+ * 
  * const included = await processIncludes(scope, articles, deps);
- * // Returns: [
- * //   { type: 'users', id: '10', attributes: {...} },
- * //   { type: 'users', id: '11', attributes: {...} }
+ * 
+ * // Output: Deduplicated authors (only 2, not 3)
+ * // [
+ * //   { type: 'users', id: '10', attributes: { name: 'Alice', email: 'alice@example.com' } },
+ * //   { type: 'users', id: '11', attributes: { name: 'Bob', email: 'bob@example.com' } }
  * // ]
  * 
- * @example <caption>Nested includes with dot notation</caption>
+ * @example
+ * // Input: Nested includes with dot notation
+ * const articles = [{ id: 1, title: 'Article', author_id: 10 }];
+ * 
  * const deps = {
- *   log, scopes, knex,
  *   context: {
- *     scopeName: 'articles',
- *     queryParams: { include: ['author', 'comments.user'] },
- *     schemaInfo: scope.vars.schemaInfo
+ *     queryParams: { 
+ *       include: ['author', 'comments.user'] // Load author AND comment users
+ *     }
  *   }
  * };
+ * 
  * const included = await processIncludes(scope, articles, deps);
- * // Loads authors, then comments for each article, 
- * // then users for each comment - all optimized to avoid N+1
  * 
- * @example <caption>With sparse fieldsets on included resources</caption>
+ * // Output: All related resources in flat array
+ * // [
+ * //   { type: 'users', id: '10', attributes: { name: 'Author' } },
+ * //   { type: 'comments', id: '1', attributes: { text: 'Great!' } },
+ * //   { type: 'comments', id: '2', attributes: { text: 'Nice!' } },
+ * //   { type: 'users', id: '20', attributes: { name: 'Commenter1' } },
+ * //   { type: 'users', id: '21', attributes: { name: 'Commenter2' } }
+ * // ]
+ * 
+ * @example
+ * // Input: With sparse fieldsets limiting included data
  * const deps = {
- *   log, scopes, knex,
  *   context: {
- *     scopeName: 'articles',
  *     queryParams: { 
  *       include: ['author'],
- *       fields: { users: 'name,email' }  // Only load name and email for users
- *     },
- *     schemaInfo: scope.vars.schemaInfo,
- *     transaction: trx  // Within a transaction
+ *       fields: { 
+ *         users: 'name'  // Only include name field for users
+ *       }
+ *     }
  *   }
  * };
+ * 
  * const included = await processIncludes(scope, articles, deps);
  * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API Knex plugin uses this to:
- * // 1. Implement JSON:API compound documents efficiently
- * // 2. Avoid N+1 query problems with batch loading
- * // 3. Support deep relationship includes (author.company.address)
- * // 4. Respect database transactions for consistency
- * // 5. Apply sparse fieldsets to included resources
- * // 6. Handle both belongsTo and hasMany relationships
+ * // Output: Users with only requested fields
+ * // [
+ * //   { type: 'users', id: '10', attributes: { name: 'Alice' } }
+ * //   // email field excluded due to sparse fieldset
+ * // ]
+ * 
+ * @description
+ * Used by:
+ * - rest-api-knex-plugin's dataGet method when includes are requested
+ * - rest-api-knex-plugin's dataQuery method for collection includes
+ * - Called after primary records are fetched but before response assembly
+ * 
+ * Purpose:
+ * - Implements JSON:API compound documents with primary data and includes
+ * - Prevents N+1 queries by batch loading all related resources
+ * - Handles complex nested includes like 'comments.author.company'
+ * - Automatically deduplicates included resources
+ * - Respects sparse fieldsets on included resources
+ * 
+ * Data flow:
+ * 1. Receives primary records and include directives
+ * 2. Parses include parameter (comma-separated, possibly nested with dots)
+ * 3. Delegates to buildIncludedResources for actual loading
+ * 4. Returns flat array of all included resources
+ * 5. These resources go into the 'included' section of JSON:API response
  */
 export const processIncludes = async (scope, records, deps) => {
   try {
     const { log, scopes, knex, context, api } = deps;
     
-    // Get scopeName from context
     const scopeName = context.scopeName;
     
     if (!scopeName) {
@@ -91,7 +109,6 @@ export const processIncludes = async (scope, records, deps) => {
       throw new Error('scopeName is undefined in context');
     }
     
-    // Get values from context
     const db = context.transaction || knex;
     const queryParams = context.queryParams;
     const idProperty = context.schemaInfo.idProperty;
@@ -129,7 +146,6 @@ export const processIncludes = async (scope, records, deps) => {
   } catch (error) {
     const { log, context } = deps || {};
     
-    // Log error with context
     if (log) {
       log.error('[PROCESS-INCLUDES] Error processing includes:', {
         scopeName: context?.scopeName,
@@ -142,7 +158,6 @@ export const processIncludes = async (scope, records, deps) => {
       console.error('[PROCESS-INCLUDES] Error processing includes:', error);
     }
     
-    // Re-throw with enhanced error message
     const enhancedError = new Error(
       `Failed to process includes${context?.scopeName ? ` for scope '${context.scopeName}'` : ''}: ${error.message}`
     );

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

@@ -0,0 +1,74 @@
+/**
+ * Builds the SELECT clause for a Knex query, handling field selection and table prefixing
+ * 
+ * @param {Object} query - The Knex query builder instance
+ * @param {string} tableName - The table name
+ * @param {Array<string>|string} fieldsToSelect - Fields to select or '*'
+ * @param {boolean} useTablePrefix - Whether to prefix fields with table name
+ * @returns {Object} The modified query builder
+ * 
+ * @example
+ * // Input: Basic query without specific fields
+ * const query = knex('articles');
+ * buildQuerySelection(query, 'articles', '*', false);
+ * 
+ * // Effect on query: No modification, Knex defaults to SELECT *
+ * // SQL generated: SELECT * FROM articles
+ * 
+ * @example
+ * // Input: Query with sparse fieldset
+ * const query = knex('articles');
+ * const fields = ['id', 'title', 'author_id'];
+ * buildQuerySelection(query, 'articles', fields, false);
+ * 
+ * // Effect on query: Adds select() with specific fields
+ * // SQL generated: SELECT id, title, author_id FROM articles
+ * // Response will only include these 3 fields, reducing payload size
+ * 
+ * @example
+ * // Input: Query with joins needing table prefixes
+ * const query = knex('articles')
+ *   .join('users', 'articles.author_id', 'users.id');
+ * const fields = ['id', 'title', 'created_at as published'];
+ * buildQuerySelection(query, 'articles', fields, true);
+ * 
+ * // Effect on query: Prefixes all fields with table name
+ * // SQL generated: SELECT articles.id, articles.title, articles.created_at as published
+ * // Prevents "column 'id' is ambiguous" errors since both tables have id
+ * 
+ * @description
+ * Used by:
+ * - knex-query-helpers.js calls this when building queries with sparse fieldsets
+ * - rest-api-knex-plugin uses this in dataQuery to optimize SELECT clauses
+ * - Called whenever fields parameter limits which attributes to return
+ * 
+ * Purpose:
+ * - Implements JSON:API sparse fieldsets by selecting only requested fields
+ * - Prevents ambiguous column errors in queries with joins
+ * - Reduces database transfer by not selecting unnecessary columns
+ * - Handles field aliases (e.g., "created_at as published")
+ * 
+ * Data flow:
+ * 1. Query parser extracts fields parameter (e.g., fields[articles]=title,author)
+ * 2. This function adds appropriate SELECT clause to query
+ * 3. Database returns only selected columns
+ * 4. Smaller result sets improve query performance
+ * 5. JSON:API response includes only requested attributes
+ */
+export const buildQuerySelection = (query, tableName, fieldsToSelect, useTablePrefix = false) => {
+  if (fieldsToSelect === '*') {
+    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);
+  }
+};