json-rest-api 1.0.21 → 1.0.22

package/audit/evidence/code/critical-pass1/json-rest-api__plugins__core__lib__querying__knex-process-includes.js.txt

@@ -0,0 +1,167 @@
+     1	import { buildIncludedResources } from './knex-relationship-includes.js'
+     2	
+     3	/**
+     4	 * Processes the ?include= parameter to load related resources efficiently
+     5	 *
+     6	 * @param {Object} scope - The scope object for the primary resource
+     7	 * @param {Array<Object>} records - The primary records to load includes for
+     8	 * @param {Object} deps - Dependencies object containing log, scopes, knex, and context
+     9	 * @returns {Promise<Array<Object>>} Array of included resources in JSON:API format
+    10	 *
+    11	 * @example
+    12	 * // Input: Articles with author relationship
+    13	 * const articles = [
+    14	 *   { id: 1, title: 'First Article', author_id: 10 },
+    15	 *   { id: 2, title: 'Second Article', author_id: 11 },
+    16	 *   { id: 3, title: 'Third Article', author_id: 10 }  // Same author as article 1
+    17	 * ];
+    18	 *
+    19	 * const deps = {
+    20	 *   context: {
+    21	 *     scopeName: 'articles',
+    22	 *     queryParams: { include: ['author'] },
+    23	 *     schemaInfo: { idProperty: 'id' }
+    24	 *   }
+    25	 * };
+    26	 *
+    27	 * const included = await processIncludes(scope, articles, deps);
+    28	 *
+    29	 * // Output: Deduplicated authors (only 2, not 3)
+    30	 * // [
+    31	 * //   { type: 'users', id: '10', attributes: { name: 'Alice', email: 'alice@example.com' } },
+    32	 * //   { type: 'users', id: '11', attributes: { name: 'Bob', email: 'bob@example.com' } }
+    33	 * // ]
+    34	 *
+    35	 * @example
+    36	 * // Input: Nested includes with dot notation
+    37	 * const articles = [{ id: 1, title: 'Article', author_id: 10 }];
+    38	 *
+    39	 * const deps = {
+    40	 *   context: {
+    41	 *     queryParams: {
+    42	 *       include: ['author', 'comments.user'] // Load author AND comment users
+    43	 *     }
+    44	 *   }
+    45	 * };
+    46	 *
+    47	 * const included = await processIncludes(scope, articles, deps);
+    48	 *
+    49	 * // Output: All related resources in flat array
+    50	 * // [
+    51	 * //   { type: 'users', id: '10', attributes: { name: 'Author' } },
+    52	 * //   { type: 'comments', id: '1', attributes: { text: 'Great!' } },
+    53	 * //   { type: 'comments', id: '2', attributes: { text: 'Nice!' } },
+    54	 * //   { type: 'users', id: '20', attributes: { name: 'Commenter1' } },
+    55	 * //   { type: 'users', id: '21', attributes: { name: 'Commenter2' } }
+    56	 * // ]
+    57	 *
+    58	 * @example
+    59	 * // Input: With sparse fieldsets limiting included data
+    60	 * const deps = {
+    61	 *   context: {
+    62	 *     queryParams: {
+    63	 *       include: ['author'],
+    64	 *       fields: {
+    65	 *         users: 'name'  // Only include name field for users
+    66	 *       }
+    67	 *     }
+    68	 *   }
+    69	 * };
+    70	 *
+    71	 * const included = await processIncludes(scope, articles, deps);
+    72	 *
+    73	 * // Output: Users with only requested fields
+    74	 * // [
+    75	 * //   { type: 'users', id: '10', attributes: { name: 'Alice' } }
+    76	 * //   // email field excluded due to sparse fieldset
+    77	 * // ]
+    78	 *
+    79	 * @description
+    80	 * Used by:
+    81	 * - rest-api-knex-plugin's dataGet method when includes are requested
+    82	 * - rest-api-knex-plugin's dataQuery method for collection includes
+    83	 * - Called after primary records are fetched but before response assembly
+    84	 *
+    85	 * Purpose:
+    86	 * - Implements JSON:API compound documents with primary data and includes
+    87	 * - Prevents N+1 queries by batch loading all related resources
+    88	 * - Handles complex nested includes like 'comments.author.company'
+    89	 * - Automatically deduplicates included resources
+    90	 * - Respects sparse fieldsets on included resources
+    91	 *
+    92	 * Data flow:
+    93	 * 1. Receives primary records and include directives
+    94	 * 2. Parses include parameter (comma-separated, possibly nested with dots)
+    95	 * 3. Delegates to buildIncludedResources for actual loading
+    96	 * 4. Returns flat array of all included resources
+    97	 * 5. These resources go into the 'included' section of JSON:API response
+    98	 */
+    99	export const processIncludes = async (scope, records, deps) => {
+   100	  try {
+   101	    const { log, scopes, knex, context, api } = deps
+   102	
+   103	    const scopeName = context.scopeName
+   104	
+   105	    if (!scopeName) {
+   106	      log.error('[PROCESS-INCLUDES] scopeName is undefined in context!', {
+   107	        contextKeys: Object.keys(context || {})
+   108	      })
+   109	      throw new Error('scopeName is undefined in context')
+   110	    }
+   111	
+   112	    const db = context.transaction || knex
+   113	    const queryParams = context.queryParams
+   114	    const idProperty = context.schemaInfo.idProperty
+   115	
+   116	    if (!queryParams.include) {
+   117	      return []
+   118	    }
+   119	
+   120	    log.debug('[PROCESS-INCLUDES] Processing includes:', queryParams.include)
+   121	
+   122	    const includeResult = await buildIncludedResources(
+   123	      {
+   124	        records,
+   125	        scopeName,
+   126	        includeParam: queryParams.include,
+   127	        fields: queryParams.fields || {},
+   128	        idProperty
+   129	      },
+   130	      {
+   131	        context: {
+   132	          scopes,
+   133	          log,
+   134	          knex: db,
+   135	          capabilities: api?.knex?.capabilities
+   136	        }
+   137	      }
+   138	    )
+   139	
+   140	    log.debug('[PROCESS-INCLUDES] Include result:', {
+   141	      includedCount: includeResult.included.length,
+   142	      types: [...new Set(includeResult.included.map(r => r.type))]
+   143	    })
+   144	
+   145	    return includeResult.included
+   146	  } catch (error) {
+   147	    const { log, context } = deps || {}
+   148	
+   149	    if (log) {
+   150	      log.error('[PROCESS-INCLUDES] Error processing includes:', {
+   151	        scopeName: context?.scopeName,
+   152	        recordCount: records?.length || 0,
+   153	        includeParam: context?.queryParams?.include,
+   154	        error: error.message,
+   155	        stack: error.stack
+   156	      })
+   157	    } else {
+   158	      console.error('[PROCESS-INCLUDES] Error processing includes:', error)
+   159	    }
+   160	
+   161	    const enhancedError = new Error(
+   162	      `Failed to process includes${context?.scopeName ? ` for scope '${context.scopeName}'` : ''}: ${error.message}`
+   163	    )
+   164	    enhancedError.originalError = error
+   165	    throw enhancedError
+   166	  }
+   167	}

package/audit/evidence/code/critical-pass1/json-rest-api__plugins__core__lib__querying__knex-query-helpers-base.js.txt

@@ -0,0 +1,109 @@
+     1	/**
+     2	 * Builds the SELECT clause for a Knex query, handling field selection and table prefixing
+     3	 *
+     4	 * @param {Object} query - The Knex query builder instance
+     5	 * @param {string} tableName - The table name
+     6	 * @param {Array<string>|string} fieldsToSelect - Fields to select or '*'
+     7	 * @param {boolean} useTablePrefix - Whether to prefix fields with table name
+     8	 * @returns {Object} The modified query builder
+     9	 *
+    10	 * @example
+    11	 * // Input: Basic query without specific fields
+    12	 * const query = knex('articles');
+    13	 * buildQuerySelection(query, 'articles', '*', false);
+    14	 *
+    15	 * // Effect on query: No modification, Knex defaults to SELECT *
+    16	 * // SQL generated: SELECT * FROM articles
+    17	 *
+    18	 * @example
+    19	 * // Input: Query with sparse fieldset
+    20	 * const query = knex('articles');
+    21	 * const fields = ['id', 'title', 'author_id'];
+    22	 * buildQuerySelection(query, 'articles', fields, false);
+    23	 *
+    24	 * // Effect on query: Adds select() with specific fields
+    25	 * // SQL generated: SELECT id, title, author_id FROM articles
+    26	 * // Response will only include these 3 fields, reducing payload size
+    27	 *
+    28	 * @example
+    29	 * // Input: Query with joins needing table prefixes
+    30	 * const query = knex('articles')
+    31	 *   .join('users', 'articles.author_id', 'users.id');
+    32	 * const fields = ['id', 'title', 'created_at as published'];
+    33	 * buildQuerySelection(query, 'articles', fields, true);
+    34	 *
+    35	 * // Effect on query: Prefixes all fields with table name
+    36	 * // SQL generated: SELECT articles.id, articles.title, articles.created_at as published
+    37	 * // Prevents "column 'id' is ambiguous" errors since both tables have id
+    38	 *
+    39	 * @description
+    40	 * Used by:
+    41	 * - knex-query-helpers.js calls this when building queries with sparse fieldsets
+    42	 * - rest-api-knex-plugin uses this in dataQuery to optimize SELECT clauses
+    43	 * - Called whenever fields parameter limits which attributes to return
+    44	 *
+    45	 * Purpose:
+    46	 * - Implements JSON:API sparse fieldsets by selecting only requested fields
+    47	 * - Prevents ambiguous column errors in queries with joins
+    48	 * - Reduces database transfer by not selecting unnecessary columns
+    49	 * - Handles field aliases (e.g., "created_at as published")
+    50	 *
+    51	 * Data flow:
+    52	 * 1. Query parser extracts fields parameter (e.g., fields[articles]=title,author)
+    53	 * 2. This function adds appropriate SELECT clause to query
+    54	 * 3. Database returns only selected columns
+    55	 * 4. Smaller result sets improve query performance
+    56	 * 5. JSON:API response includes only requested attributes
+    57	 */
+    58	export const buildQuerySelection = (
+    59	  query,
+    60	  tableName,
+    61	  fieldsToSelect,
+    62	  useTablePrefix = false,
+    63	  options = {}
+    64	) => {
+    65	  const translateColumn = options.translateColumn
+    66	
+    67	  const applyTranslation = (field, aliasForField) => {
+    68	    if (translateColumn) {
+    69	      const translated = translateColumn(field, aliasForField)
+    70	      if (translated) {
+    71	        return translated
+    72	      }
+    73	    }
+    74	
+    75	    if (aliasForField) {
+    76	      return `${aliasForField}.${field}`
+    77	    }
+    78	    return field
+    79	  }
+    80	
+    81	  const targetAlias = useTablePrefix ? tableName : null
+    82	
+    83	  if (fieldsToSelect === '*') {
+    84	    const translated = translateColumn ? translateColumn('*', targetAlias) : null
+    85	    if (translated) {
+    86	      return query.select(translated)
+    87	    }
+    88	    return useTablePrefix ? query.select(`${tableName}.*`) : query
+    89	  }
+    90	
+    91	  const fieldsArray = Array.isArray(fieldsToSelect)
+    92	    ? fieldsToSelect
+    93	    : Array.from(fieldsToSelect || [])
+    94	
+    95	  const translatedFields = fieldsArray.map((field) => {
+    96	    if (typeof field !== 'string') return field
+    97	
+    98	    const aliasMatch = field.match(/\s+as\s+/i)
+    99	    if (aliasMatch) {
+   100	      const [source, alias] = field.split(/\s+as\s+/i)
+   101	      const translatedSource = applyTranslation(source.trim(), targetAlias)
+   102	      return `${translatedSource} as ${alias.trim()}`
+   103	    }
+   104	
+   105	    return applyTranslation(field.trim(), targetAlias)
+   106	  })
+   107	
+   108	  return query.select(translatedFields)
+   109	}