json-rest-api 1.0.22 → 1.0.24

package/plugins/core/lib/querying/query-builder-utils.js

@@ -0,0 +1,19 @@
+export const unwrapQueryBuilderState = (value, fallback = null) => {
+  let current = value
+  const seen = new Set()
+
+  while (
+    current &&
+    typeof current === 'object' &&
+    !Array.isArray(current) &&
+    Object.hasOwn(current, 'query') &&
+    current.query &&
+    current.query !== current &&
+    !seen.has(current)
+  ) {
+    seen.add(current)
+    current = current.query
+  }
+
+  return current || fallback
+}

package/plugins/core/lib/querying/query-field-sort-helpers.js

@@ -0,0 +1,135 @@
+import { normalizeStableSort, parseSortEntry } from './sort-helpers.js'
+
+export const getEffectiveSortableFields = (vars = {}) => {
+  const baseSortableFields = Array.isArray(vars.sortableFields)
+    ? vars.sortableFields
+    : []
+  const queryFieldSortableFields = Object.entries(vars.queryFields || {})
+    .filter(([, fieldDef]) => fieldDef?.sortable === true)
+    .map(([fieldName]) => fieldName)
+
+  return Array.from(new Set([...baseSortableFields, ...queryFieldSortableFields]))
+}
+
+export const buildEffectiveSortList = (sort, { defaultSort, idField = 'id' } = {}) => {
+  let sortList = Array.isArray(sort) ? [...sort] : (sort ? [sort] : [])
+
+  if (sortList.length === 0 && defaultSort) {
+    if (Array.isArray(defaultSort)) {
+      sortList = [...defaultSort]
+    } else if (typeof defaultSort === 'string') {
+      sortList = [defaultSort]
+    } else if (typeof defaultSort === 'object') {
+      const field = defaultSort.field || defaultSort.column || idField
+      const direction = (defaultSort.direction || '').toLowerCase() === 'desc' ? '-' : ''
+      sortList = [`${direction}${field}`]
+    }
+  }
+
+  return normalizeStableSort(sortList.length > 0 ? sortList : [idField], { idField })
+}
+
+export const applyQueryFieldOrder = (query, queryFieldRuntime, direction) => {
+  query.orderByRaw(`(${queryFieldRuntime.sql}) ${direction}`, queryFieldRuntime.bindings)
+}
+
+export const applyQueryFieldPredicate = (builder, queryFieldRuntime, operator, value) => {
+  builder.whereRaw(`(${queryFieldRuntime.sql}) ${operator} ?`, [...queryFieldRuntime.bindings, value])
+}
+
+export const applySortDescriptorPredicate = (builder, descriptor, operator, value, applyPlainPredicate) => {
+  if (descriptor?.queryFieldRuntime) {
+    return applyQueryFieldPredicate(builder, descriptor.queryFieldRuntime, operator, value)
+  }
+
+  return applyPlainPredicate(builder, descriptor, operator, value)
+}
+
+export const buildCursorPredicateChains = (
+  descriptors,
+  cursorValues,
+  operatorSelector,
+  { onMissingValue } = {}
+) => {
+  if (!Array.isArray(descriptors) || descriptors.length === 0) {
+    return []
+  }
+
+  const predicateChains = []
+
+  descriptors.forEach((descriptor, index) => {
+    const cursorValue = cursorValues?.[descriptor.field]
+
+    if (cursorValue === undefined) {
+      onMissingValue?.(descriptor.field)
+      return
+    }
+
+    const chain = []
+    for (let i = 0; i < index; i += 1) {
+      const previousDescriptor = descriptors[i]
+      const previousValue = cursorValues?.[previousDescriptor.field]
+
+      if (previousValue === undefined) {
+        onMissingValue?.(previousDescriptor.field)
+        return
+      }
+
+      chain.push({
+        descriptor: previousDescriptor,
+        operator: '=',
+        value: previousValue
+      })
+    }
+
+    chain.push({
+      descriptor,
+      operator: operatorSelector(descriptor.direction),
+      value: cursorValue
+    })
+
+    predicateChains.push(chain)
+  })
+
+  return predicateChains
+}
+
+export const applyCursorPredicate = (
+  query,
+  descriptors,
+  cursorValues,
+  operatorSelector,
+  applyPlainPredicate,
+  { onMissingValue } = {}
+) => {
+  const predicateChains = buildCursorPredicateChains(
+    descriptors,
+    cursorValues,
+    operatorSelector,
+    { onMissingValue }
+  )
+
+  if (predicateChains.length === 0) {
+    return false
+  }
+
+  query.where(function () {
+    predicateChains.forEach((chain) => {
+      this.orWhere(function () {
+        chain.forEach(({ descriptor, operator, value }) => {
+          applySortDescriptorPredicate(
+            this,
+            descriptor,
+            operator,
+            value,
+            applyPlainPredicate
+          )
+        })
+      })
+    })
+  })
+
+  return true
+}
+
+export { parseSortEntry }

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

@@ -0,0 +1,33 @@
+export function normalizeStableSort (sort = [], { idField = 'id' } = {}) {
+  const sortList = Array.isArray(sort)
+    ? sort.filter((entry) => typeof entry === 'string' && entry.trim())
+    : []
+
+  if (sortList.length === 0) {
+    return [idField]
+  }
+
+  const hasId = sortList.some((entry) => {
+    const fieldName = entry.startsWith('-') ? entry.slice(1) : entry
+    return fieldName === idField
+  })
+
+  if (!hasId) {
+    sortList.push(idField)
+  }
+
+  return sortList
+}
+
+export function parseSortEntry (sortEntry) {
+  const desc = typeof sortEntry === 'string' && sortEntry.startsWith('-')
+  const field = desc ? sortEntry.slice(1) : sortEntry
+
+  return {
+    raw: sortEntry,
+    field,
+    desc,
+    direction: desc ? 'desc' : 'asc',
+    sqlDirection: desc ? 'DESC' : 'ASC'
+  }
+}

package/plugins/core/lib/querying/storage-adapter-utils.js

@@ -0,0 +1,51 @@
+export const createStorageAdapterUtilities = (hookParams, { getStorageAdapter } = {}) => {
+  const context = hookParams?.context || {}
+  const storageCache = new Map()
+
+  const fetchStorageAdapter = (scopeName) => {
+    if (!scopeName) return null
+    if (storageCache.has(scopeName)) return storageCache.get(scopeName)
+
+    let adapter = null
+    if (scopeName === context?.knexQuery?.scopeName) {
+      adapter = context.storageAdapter ||
+        context.knexQuery?.storageAdapter ||
+        (typeof getStorageAdapter === 'function' ? getStorageAdapter(scopeName) : null)
+      if (adapter && !context.storageAdapter) {
+        context.storageAdapter = adapter
+      }
+    } else {
+      adapter = typeof getStorageAdapter === 'function' ? getStorageAdapter(scopeName) : null
+    }
+
+    storageCache.set(scopeName, adapter)
+    return adapter
+  }
+
+  const defaultAliasForScope = (scopeName) => {
+    if (scopeName === context?.knexQuery?.scopeName) {
+      return context.knexQuery?.tableName || scopeName
+    }
+    return scopeName
+  }
+
+  const translateColumn = (scopeName, field, alias = defaultAliasForScope(scopeName)) => {
+    const adapter = fetchStorageAdapter(scopeName)
+    const translated = adapter?.translateColumn?.(field) ?? field
+    if (!alias) return translated
+    return `${alias}.${translated}`
+  }
+
+  const translateFilterValue = (scopeName, field, value) => {
+    const adapter = fetchStorageAdapter(scopeName)
+    if (!adapter?.translateFilterValue) return value
+    return adapter.translateFilterValue(field, value)
+  }
+
+  return {
+    fetchStorageAdapter,
+    defaultAliasForScope,
+    translateColumn,
+    translateFilterValue,
+  }
+}

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

@@ -41,8 +41,14 @@ export function getUrlPrefix (context, scope, req = null) {
 
   // 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 protocol = req.get?.('x-forwarded-proto') ||
+      req.headers?.['x-forwarded-proto'] ||
+      req.protocol ||
+      'http'
+    const host = req.get?.('x-forwarded-host') ||
+      req.headers?.['x-forwarded-host'] ||
+      req.get?.('host') ||
+      req.headers?.host
     const mountPath = scope?.vars?.transport?.mountPath || ''
 
     if (host) {

package/plugins/core/lib/querying-writing/compile-schemas.js

@@ -1,5 +1,6 @@
 import { createSchema } from 'json-rest-schema'
 import { ensureSearchFieldsAreIndexed, generateSearchSchemaFromSchema, sortFieldsByDependencies } from './schema-helpers.js'
+import { buildStorageInfo, normalizeStorageConfig } from '../storage/storage-mapping.js'
 
 /**
  * Compiles and enriches schemas for a resource scope
@@ -154,7 +155,7 @@ export async function compileSchemas (scope, deps) {
   }
 
   // Default enrichment: Add type to belongsTo fields
-  for (const [fieldName, fieldDef] of Object.entries(enrichedFields)) {
+  for (const [, fieldDef] of Object.entries(enrichedFields)) {
     if (fieldDef.belongsTo && !fieldDef.type) {
       fieldDef.type = 'id'
     }
@@ -173,7 +174,7 @@ export async function compileSchemas (scope, deps) {
 
   if (isProbablyPivot) {
     // Make all belongsTo fields searchable for pivot operations
-    for (const [fieldName, fieldDef] of belongsToFields) {
+    for (const [, fieldDef] of belongsToFields) {
       if (!fieldDef.search) {
         fieldDef.search = true
       }
@@ -205,6 +206,7 @@ export async function compileSchemas (scope, deps) {
     scope.scopeOptions.searchSchema
   )
 
+  let searchSchemaObject
   if (rawSearchFields) {
     // Mark all search fields as indexed for database optimization.
     // This ensures that any field used for filtering will have a database index created,
@@ -223,9 +225,9 @@ export async function compileSchemas (scope, deps) {
     await runHooks('searchSchema:enrich', searchSchemaContext)
 
     // Create searchSchema object
-    var searchSchemaObject = createSchema(rawSearchFields)
+    searchSchemaObject = createSchema(rawSearchFields)
   } else {
-    var searchSchemaObject = createSchema({})
+    searchSchemaObject = createSchema({})
   }
 
   // Build schemaRelationships including polymorphic fields from schema
@@ -315,6 +317,14 @@ export async function compileSchemas (scope, deps) {
     }
   }
 
+  const idProperty = scope.scopeOptions.idProperty || scope.vars.idProperty || 'id'
+  const storage = normalizeStorageConfig(scope.scopeOptions.storage)
+  const storageInfo = buildStorageInfo({
+    schemaStructure: schemaObject.structure,
+    idProperty,
+    storage
+  })
+
   // Cache everything
   scope.vars.schemaInfo = {
 
@@ -327,7 +337,12 @@ export async function compileSchemas (scope, deps) {
     computed: computedFields,
     schemaRelationships,
     tableName: scope.scopeOptions.tableName || scopeName,
-    idProperty: scope.scopeOptions.idProperty || scope.vars.idProperty,
+    idProperty,
+    storage,
+    storageInfo,
+    indexes: Array.isArray(scope.scopeOptions.indexes) ? [...scope.scopeOptions.indexes] : [],
+    foreignKeys: Array.isArray(scope.scopeOptions.foreignKeys) ? [...scope.scopeOptions.foreignKeys] : [],
+    checkConstraints: Array.isArray(scope.scopeOptions.checkConstraints) ? [...scope.scopeOptions.checkConstraints] : [],
     fieldGetters,
     sortedGetterFields,
     fieldSetters,

package/plugins/core/lib/querying-writing/knex-field-helpers.js

@@ -1,3 +1,7 @@
+import { buildQuerySelection } from '../querying/knex-query-helpers-base.js'
+import { createSelectTranslator } from '../storage/storage-adapter.js'
+import { buildQueryFieldRuntimes } from './query-field-helpers.js'
+
 /**
  * Checks if a field exists only in code, not in the database
  *
@@ -143,25 +147,21 @@ export const buildFieldSelection = async (scope, deps) => {
   const computedDependencies = new Set()
 
   // Extract values from scope
+  const scopeSchemaInfo = scope?.vars?.schemaInfo || {}
   const {
-    vars: {
-      schemaInfo: { schemaInstance, computed: computedFields = {}, schemaStructure }
-    }
-  } = scope
+    schemaInstance,
+    computed: computedFields = {}
+  } = scopeSchemaInfo
+  let schemaStructure = scopeSchemaInfo.schemaStructure
+  const queryFields = scope?.vars?.queryFields || {}
 
   // Extract values from deps
   const { context } = deps
   const scopeName = context.scopeName
   const requestedFields = context.queryParams?.fields?.[scopeName]
-  const idProperty = context.schemaInfo.idProperty
 
-  // Always include the ID field - required for JSON:API
-  // Handle aliasing if idProperty is not 'id'
-  if (idProperty !== 'id') {
-    fieldsToSelect.add(`${idProperty} as id`)
-  } else {
-    fieldsToSelect.add('id')
-  }
+  // Always include the logical ID field - the storage adapter translates it.
+  fieldsToSelect.add('id')
 
   // Handle both Schema objects and plain objects
   if (!schemaStructure) {
@@ -170,6 +170,8 @@ export const buildFieldSelection = async (scope, deps) => {
 
   // Get computed fields and virtual fields from schema
   const computedFieldNames = new Set(Object.keys(computedFields))
+  const queryFieldNames = new Set(Object.keys(queryFields))
+  const queryFieldsToSelect = new Set()
 
   // Find fields marked as virtual in the schema
   const virtualFieldNames = new Set()
@@ -194,6 +196,12 @@ export const buildFieldSelection = async (scope, deps) => {
     // Sparse fieldsets requested - only select specified fields
     // Example: ?fields[products]=name,price,profit_margin
     requested.forEach(field => {
+      if (queryFieldNames.has(field)) {
+        if (queryFields[field]?.hidden === true) return
+        queryFieldsToSelect.add(field)
+        return
+      }
+
       // Skip computed and virtual fields - they don't exist in database
       // Computed fields will be calculated later in enrichAttributes
       // Virtual fields are handled separately (from request input)
@@ -274,7 +282,7 @@ export const buildFieldSelection = async (scope, deps) => {
     // So we need to include their dependencies even if normallyHidden
     // Example: profit_margin depends on 'cost' which is normallyHidden
     // We fetch 'cost' for calculation but don't return it in response
-    for (const [fieldName, fieldDef] of Object.entries(computedFields)) {
+    for (const [, fieldDef] of Object.entries(computedFields)) {
       if (fieldDef.dependencies) {
         for (const dep of fieldDef.dependencies) {
           const depFieldDef = schemaStructure[dep]
@@ -289,6 +297,24 @@ export const buildFieldSelection = async (scope, deps) => {
         }
       }
     }
+
+    for (const [fieldName, fieldDef] of Object.entries(queryFields)) {
+      if (fieldDef.hidden === true || fieldDef.normallyHidden === true) continue
+      queryFieldsToSelect.add(fieldName)
+    }
+  }
+
+  const sortFields = Array.isArray(context.queryParams?.sort)
+    ? context.queryParams.sort
+    : []
+
+  for (const sortField of sortFields) {
+    if (typeof sortField !== 'string') continue
+    const normalizedField = sortField.startsWith('-') ? sortField.slice(1) : sortField
+
+    if (queryFieldNames.has(normalizedField)) {
+      queryFieldsToSelect.add(normalizedField)
+    }
   }
 
   // Always include foreign keys for relationships (unless hidden)
@@ -318,9 +344,52 @@ export const buildFieldSelection = async (scope, deps) => {
   // 3. enrichAttributes to remove dependencies from final response
   return {
     fieldsToSelect: Array.from(fieldsToSelect),      // Fields to SELECT from database
+    queryFieldsToSelect: Array.from(queryFieldsToSelect),
     requestedFields: requested,                       // Fields explicitly requested by user
     computedDependencies: Array.from(computedDependencies),  // Dependencies to remove from response
-    idProperty                                        // Pass idProperty for reference
+    idProperty: 'id'                                  // Logical field name reference
+  }
+}
+
+export const applyFieldSelectionToQuery = async ({
+  query,
+  scope,
+  fieldSelectionInfo,
+  tableName,
+  useTablePrefix = false,
+  storageAdapter = null,
+  db = null,
+  context = null,
+  scopeName = ''
+}) => {
+  const selectTranslator = createSelectTranslator(storageAdapter)
+
+  const selectedQuery = buildQuerySelection(
+    query,
+    tableName,
+    fieldSelectionInfo?.fieldsToSelect || [],
+    useTablePrefix,
+    selectTranslator ? { translateColumn: selectTranslator } : undefined
+  )
+
+  const queryFieldRuntimeByField = await buildQueryFieldRuntimes({
+    queryFieldNames: fieldSelectionInfo?.queryFieldsToSelect || [],
+    queryFields: scope?.vars?.queryFields || {},
+    schemaInfo: scope?.vars?.schemaInfo || {},
+    tableName,
+    storageAdapter,
+    db,
+    context,
+    scopeName
+  })
+
+  for (const [fieldName, runtime] of queryFieldRuntimeByField.entries()) {
+    selectedQuery.select({ [fieldName]: runtime.expression })
+  }
+
+  return {
+    query: selectedQuery,
+    queryFieldRuntimeByField
   }
 }
 

package/plugins/core/lib/querying-writing/knex-json-api-transformers.js

@@ -1,5 +1,6 @@
 import { toJsonApiRecord } from '../querying/knex-json-api-transformers-querying.js'
 import { getSchemaStructure } from './knex-constants.js'
+import { translateRecordFromStorage } from '../storage/storage-mapping.js'
 
 /**
  * Converts database record to JSON:API format with belongsTo relationships
@@ -92,17 +93,17 @@ import { getSchemaStructure } from './knex-constants.js'
 export const toJsonApiRecordWithBelongsTo = (scope, record, scopeName) => {
   if (!record) return null
 
+  const schemaInfo = scope.vars.schemaInfo
+  const logicalRecord = translateRecordFromStorage(record, schemaInfo)
+
   // Get the basic JSON:API structure (without relationships)
-  const jsonApiRecord = toJsonApiRecord(scope, record, scopeName)
+  const jsonApiRecord = toJsonApiRecord(scope, logicalRecord, scopeName)
 
   // Extract schema info from scope
   const {
-    vars: {
-      schemaInfo: { schemaInstance, schemaRelationships: relationships, idProperty }
-    }
-  } = scope
-
-  const idField = idProperty || 'id'
+    schemaInstance,
+    schemaRelationships: relationships
+  } = schemaInfo
 
   // Get schema structure
   const schemaStructure = getSchemaStructure(schemaInstance)
@@ -113,13 +114,13 @@ export const toJsonApiRecordWithBelongsTo = (scope, record, scopeName) => {
   // Process regular belongsTo relationships from schema
   for (const [fieldName, fieldDef] of Object.entries(schemaStructure)) {
     if (fieldDef.belongsTo && fieldDef.as) {
-      const foreignKeyValue = record[fieldName]
+      const fieldValue = logicalRecord[fieldName]
 
-      if (foreignKeyValue !== null && foreignKeyValue !== undefined) {
+      if (fieldValue !== null && fieldValue !== undefined) {
         jsonApiRecord.relationships[fieldDef.as] = {
           data: {
             type: fieldDef.belongsTo,
-            id: String(foreignKeyValue)
+            id: String(fieldValue)
           }
         }
       } else {
@@ -134,8 +135,8 @@ export const toJsonApiRecordWithBelongsTo = (scope, record, scopeName) => {
   // Process polymorphic belongsTo relationships
   Object.entries(relationships || {}).forEach(([relName, relDef]) => {
     if (relDef.belongsToPolymorphic) {
-      const typeValue = record[relDef.typeField]
-      const idValue = record[relDef.idField]
+      const typeValue = logicalRecord[relDef.typeField]
+      const idValue = logicalRecord[relDef.idField]
 
       if (typeValue && idValue) {
         jsonApiRecord.relationships[relName] = {

package/plugins/core/lib/querying-writing/query-field-helpers.js

@@ -0,0 +1,88 @@
+import { getStorageColumn } from '../storage/storage-mapping.js'
+
+function qualifyColumnReference (columnName, tableName) {
+  if (!tableName || !columnName || columnName === '*' || String(columnName).includes('.')) {
+    return columnName
+  }
+
+  return `${tableName}.${columnName}`
+}
+
+function normalizeQueryFieldSql (expression) {
+  if (expression && typeof expression.toSQL === 'function') {
+    const compiled = expression.toSQL()
+    return {
+      sql: compiled.sql,
+      bindings: compiled.bindings || []
+    }
+  }
+
+  throw new Error('Query field expressions must return knex raw, knex ref, or a knex query builder.')
+}
+
+export async function buildQueryFieldRuntimes ({
+  queryFieldNames = [],
+  queryFields = {},
+  schemaInfo = {},
+  tableName = '',
+  storageAdapter = null,
+  db = null,
+  context = null,
+  scopeName = ''
+} = {}) {
+  const runtimes = new Map()
+  const seen = new Set()
+
+  for (const fieldName of queryFieldNames) {
+    if (!fieldName || seen.has(fieldName)) {
+      continue
+    }
+    seen.add(fieldName)
+
+    const fieldDef = queryFields[fieldName]
+    if (!fieldDef) {
+      throw new Error(`Unknown query field '${fieldName}' requested for '${scopeName}'.`)
+    }
+
+    const column = (logicalField) => {
+      const translated = storageAdapter?.translateColumn?.(logicalField) || getStorageColumn(schemaInfo, logicalField)
+      return qualifyColumnReference(translated, tableName)
+    }
+
+    const selectResult = fieldDef.select({
+      knex: db,
+      db,
+      context,
+      scopeName,
+      tableName,
+      fieldName,
+      schemaInfo,
+      adapter: storageAdapter,
+      column,
+      ref: (logicalField) => db?.ref ? db.ref(column(logicalField)) : column(logicalField)
+    })
+
+    const expression = (
+      selectResult &&
+      typeof selectResult === 'object' &&
+      typeof selectResult.toSQL === 'function'
+    )
+      ? selectResult
+      : await selectResult
+
+    if (expression === undefined || expression === null) {
+      throw new Error(`Query field '${fieldName}' in scope '${scopeName}' returned an empty select expression.`)
+    }
+
+    const { sql, bindings } = normalizeQueryFieldSql(expression)
+    runtimes.set(fieldName, {
+      fieldName,
+      definition: fieldDef,
+      expression,
+      sql,
+      bindings
+    })
+  }
+
+  return runtimes
+}