json-rest-api 1.0.22 → 1.0.23

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

@@ -1,167 +0,0 @@
-     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

@@ -1,109 +0,0 @@
-     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	}