json-rest-api 1.0.28 → 2.0.0

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

@@ -1,59 +1,14 @@
+// @ts-check
+import { isImmediateExpression } from '../querying-writing/query-field-helpers.js'
 /**
- * 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
+ * Add logical field selections to an unexecuted builder, using the caller's translator.
+ * `*` retains wildcard behavior. Aliases are null when table prefixing is disabled.
+ * @param {import('../storage/storage-types.js').StorageQuery} query
+ * @param {string} tableName
+ * @param {readonly string[] | string} fieldsToSelect
+ * @param {boolean} [useTablePrefix]
+ * @param {{ translateColumn?: (field: string, alias?: string | null) => string | import('knex').Knex.Raw<unknown> | Record<string, string | import('knex').Knex.Raw<unknown>> | null | undefined }} [options]
+ * @returns {import('../storage/storage-types.js').StorageQuery}
  */
 export const buildQuerySelection = (
   query,
@@ -64,6 +19,7 @@ export const buildQuerySelection = (
 ) => {
   const translateColumn = options.translateColumn
 
+  /** @param {string} field @param {string | null} aliasForField */
   const applyTranslation = (field, aliasForField) => {
     if (translateColumn) {
       const translated = translateColumn(field, aliasForField)
@@ -88,6 +44,7 @@ export const buildQuerySelection = (
     return useTablePrefix ? query.select(`${tableName}.*`) : query
   }
 
+  /** @type {readonly string[]} */
   const fieldsArray = Array.isArray(fieldsToSelect)
     ? fieldsToSelect
     : Array.from(fieldsToSelect || [])
@@ -97,8 +54,16 @@ export const buildQuerySelection = (
 
     const aliasMatch = field.match(/\s+as\s+/i)
     if (aliasMatch) {
-      const [source, alias] = field.split(/\s+as\s+/i)
+      const [source = '', alias = ''] = field.split(/\s+as\s+/i)
       const translatedSource = applyTranslation(source.trim(), targetAlias)
+      if (typeof translatedSource !== 'string') {
+        if (isImmediateExpression(translatedSource)) return { [alias.trim()]: translatedSource }
+        const values = Object.values(translatedSource)
+        if (values.length !== 1 || values[0] === undefined) {
+          throw new Error(`Cannot apply alias '${alias.trim()}' to a translation containing multiple or missing expressions`)
+        }
+        return { [alias.trim()]: values[0] }
+      }
       return `${translatedSource} as ${alias.trim()}`
     }