json-rest-api 1.0.28 → 2.0.0

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

@@ -1,43 +1,208 @@
+import { assertScalarQueryField } from '../querying-writing/field-utils.js'
 import { normalizeStableSort, parseSortEntry } from './sort-helpers.js'
+import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+import { createSchemaFactory } from 'json-rest-schema'
+import { normalizeDateValue } from '../querying-writing/database-value-normalizers.js'
+
+const cursorContractCache = new WeakMap()
+
+function getCursorContract (schema, definition) {
+  let cache = cursorContractCache.get(schema)
+  if (!cache) {
+    cache = {
+      factory: createSchemaFactory({ types: schema.types, validators: schema.validators, installCore: false }),
+      contracts: new Map()
+    }
+    cursorContractCache.set(schema, cache)
+  }
+  // Unusual/invalid declarations retain schema validation without lossy JSON keys.
+  if (typeof definition.type !== 'string' ||
+      (definition.temporalPrecision !== undefined && !Number.isInteger(definition.temporalPrecision))) {
+    return cache.factory({ value: definition })
+  }
+  const key = JSON.stringify(definition)
+  if (!cache.contracts.has(key)) cache.contracts.set(key, cache.factory({ value: definition }))
+  return cache.contracts.get(key)
+}
+
+export const validateCursorValues = (descriptors, cursorValues, parameter, schema) => {
+  const validated = Object.create(null)
+  for (const { field, definition = {}, isRelationship, queryFieldRuntime } of descriptors) {
+    if (!Object.hasOwn(cursorValues, field)) continue
+    const value = cursorValues[field]
+    // Public resource IDs may be opaque strings, even when the storage schema
+    // uses the numeric id type for ordinary attributes.
+    const type = field === 'id' || isRelationship || definition?.type === 'id'
+      ? 'string'
+      : definition?.type
+    if (!type) {
+      validated[field] = value
+      continue
+    }
+    const contract = getCursorContract(schema, {
+      type,
+      noTrim: true,
+      nullable: field !== 'id',
+      ...(definition?.temporalPrecision !== undefined
+        ? { temporalPrecision: definition.temporalPrecision }
+        : {})
+    })
+    let validationValue = value
+    let invalidStorageValue = false
+    const storedTemporal = Boolean(queryFieldRuntime || definition.storage?.serialize) && ['date', 'dateTime', 'time'].includes(type)
+    if (storedTemporal && value !== null) {
+      try {
+        validationValue = normalizeDateValue(value, type, { temporalPrecision: definition.temporalPrecision, fieldName: field, source: 'cursor' })
+      } catch {
+        invalidStorageValue = true
+      }
+    }
+    const { validatedObject, errors } = contract.patch({ value: validationValue })
+    if (invalidStorageValue || Object.keys(errors).length > 0 || (field === 'id' && !String(value ?? '').trim())) {
+      const path = `page.${parameter}`
+      throw new RestApiValidationError(`Invalid cursor value for sort field '${field}'.`, {
+        fields: [path],
+        violations: [{ field: path, rule: 'invalid_cursor_value', message: `Invalid ${type} value for '${field}'.` }]
+      })
+    }
+    // Preserve temporal SQL spelling, but bind epochs and scalar numbers as
+    // numbers: SQLite expressions have no column affinity to coerce strings.
+    validated[field] = storedTemporal
+      ? (typeof value === 'string' && /^-?\d+$/.test(value) ? Number(value) : value)
+      : validatedObject.value
+  }
+  return validated
+}
+
+export const resolveSortField = (field, schemaInfo = {}) => {
+  if (field === 'id' || Object.hasOwn(schemaInfo.schemaStructure || {}, field) || Object.hasOwn(schemaInfo.queryFields || {}, field)) return field
+  return schemaInfo.searchSchemaStructure?.[field]?.actualField || field
+}
 
 export const getEffectiveSortableFields = (vars = {}) => {
-  const baseSortableFields = Array.isArray(vars.sortableFields)
+  const schema = vars.schemaInfo?.schemaStructure || {}
+  const baseSortableFields = Array.isArray(vars.sortableFields) && vars.sortableFields.length > 0
     ? vars.sortableFields
-    : []
-  const queryFieldSortableFields = Object.entries(vars.queryFields || {})
+    : ['id', ...Object.keys(schema).filter((field) => {
+        const definition = schema[field]
+        return !definition.hidden && !definition.virtual && !definition.computed && !definition.belongsToPolymorphic
+      }), ...Object.entries(vars.schemaInfo?.searchSchemaStructure || {})
+        .filter(([, definition]) => definition.isRelationship && schema[definition.actualField]?.hidden !== true)
+        .map(([field]) => field)]
+  const queryFieldSortableFields = Object.entries(vars.schemaInfo?.queryFields || {})
     .filter(([, fieldDef]) => fieldDef?.sortable === true)
     .map(([fieldName]) => fieldName)
 
-  return Array.from(new Set([...baseSortableFields, ...queryFieldSortableFields]))
+  return Array.from(new Set([...baseSortableFields, ...queryFieldSortableFields])).filter(field => {
+    const actualField = resolveSortField(field, vars.schemaInfo)
+    const queryFields = vars.schemaInfo?.queryFields || {}
+    const definition = Object.hasOwn(queryFields, actualField) ? queryFields[actualField] : schema[actualField]
+    return definition?.hidden !== true && !['object', 'array'].includes(definition?.type)
+  })
 }
 
-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}`]
-    }
+/**
+ * @param {unknown} sort
+ * @param {{ defaultSort?: unknown, idField?: string, schemaInfo?: Partial<import('../storage/storage-types.js').DataOperationSchema> }} [options]
+ * @returns {string[]}
+ */
+export const buildEffectiveSortList = (sort, { defaultSort, idField = 'id', schemaInfo } = {}) => {
+  const toList = (value, option) => {
+    if (value === undefined || value === null) return []
+    const list = Array.isArray(value) ? [...value] : [value]
+    if (list.some(entry => typeof entry !== 'string')) throw new Error(`${option} must be a string or an array of strings, such as ['-name', 'id'].`)
+    return list
   }
+  let sortList = toList(sort, 'sort')
+  if (sortList.length === 0) sortList = toList(defaultSort, 'defaultSort')
 
-  return normalizeStableSort(sortList.length > 0 ? sortList : [idField], { idField })
+  const normalized = normalizeStableSort(sortList.length > 0 ? sortList : [idField], { idField })
+  for (const entry of normalized) {
+    const { field } = parseSortEntry(entry)
+    const actualField = resolveSortField(field, schemaInfo)
+    const queryFields = schemaInfo?.queryFields || {}
+    const definition = Object.hasOwn(queryFields, actualField) ? queryFields[actualField] : schemaInfo?.schemaStructure?.[actualField]
+    if (definition?.hidden === true) {
+      throw new RestApiValidationError(`Hidden field '${field}' cannot be used for sorting.`, {
+        fields: [field],
+        violations: [{ field, rule: 'hidden_sort', message: 'Sort fields must be publicly readable because their values may appear in cursors.' }]
+      })
+    }
+    assertScalarQueryField(definition, field, 'sort')
+  }
+  return normalized
 }
 
-export const applyQueryFieldOrder = (query, queryFieldRuntime, direction) => {
+export const applyQueryFieldOrder = (query, queryFieldRuntime, direction, nulls = 'last') => {
+  if (['pg', 'postgresql'].includes(query.client.config.client)) {
+    // The selected alias also avoids different bound parameter numbers under DISTINCT.
+    query.orderBy(queryFieldRuntime.fieldName, direction, nulls)
+    return
+  }
+  if (['better-sqlite3', 'sqlite3'].includes(query.client.config.client)) {
+    const order = String(direction).toLowerCase() === 'desc' ? 'DESC' : 'ASC'
+    query.orderByRaw(`(${queryFieldRuntime.sql}) ${order} NULLS ${nulls === 'last' ? 'LAST' : 'FIRST'}`, queryFieldRuntime.bindings)
+    return
+  }
+  query.orderByRaw(`(${queryFieldRuntime.sql}) IS NULL ${nulls === 'last' ? 'ASC' : 'DESC'}`, queryFieldRuntime.bindings)
   query.orderByRaw(`(${queryFieldRuntime.sql}) ${direction}`, queryFieldRuntime.bindings)
 }
 
+export const applyColumnOrder = (query, column, direction, nulls = 'last') => {
+  if (['pg', 'postgresql'].includes(query.client.config.client)) {
+    query.orderBy(column, direction, nulls)
+  } else if (['better-sqlite3', 'sqlite3'].includes(query.client.config.client)) {
+    // Native null placement lets SQLite use the column's ordering index.
+    const order = String(direction).toLowerCase() === 'desc' ? 'DESC' : 'ASC'
+    query.orderByRaw(`?? ${order} NULLS ${nulls === 'last' ? 'LAST' : 'FIRST'}`, [column])
+  } else {
+    query.orderByRaw(`?? IS NULL ${nulls === 'last' ? 'ASC' : 'DESC'}`, [column])
+    query.orderBy(column, direction)
+  }
+}
+
+// Both storage modes use the same cursor direction and null placement.
+/**
+ * @param {import('../storage/storage-types.js').StorageQuery} query
+ * @param {{ column?: string, queryFieldRuntime?: import('../querying-writing/query-field-types.js').ProjectionRuntime, direction: string }} descriptor
+ * @param {{ before?: boolean }} [options]
+ */
+export const applySortDescriptorOrder = (query, { column, queryFieldRuntime, direction }, { before = false } = {}) => {
+  const ascending = String(direction).toLowerCase() === 'asc'
+  const queryDirection = (before ? !ascending : ascending) ? 'asc' : 'desc'
+  const nulls = before ? 'first' : 'last'
+  if (queryFieldRuntime) {
+    applyQueryFieldOrder(query, queryFieldRuntime, queryDirection.toUpperCase(), nulls)
+  } else {
+    applyColumnOrder(query, column, queryDirection, nulls)
+  }
+}
+
 export const applyQueryFieldPredicate = (builder, queryFieldRuntime, operator, value) => {
   builder.whereRaw(`(${queryFieldRuntime.sql}) ${operator} ?`, [...queryFieldRuntime.bindings, value])
 }
 
-export const applySortDescriptorPredicate = (builder, descriptor, operator, value, applyPlainPredicate) => {
+export const applySortDescriptorPredicate = (builder, descriptor, operator, value, applyPlainPredicate, includeNull = false) => {
+  if (includeNull) {
+    return builder.where(function () {
+      applySortDescriptorPredicate(this, descriptor, operator, value, applyPlainPredicate)
+      if (descriptor.queryFieldRuntime) {
+        this.orWhereRaw(`(${descriptor.queryFieldRuntime.sql}) IS NULL`, descriptor.queryFieldRuntime.bindings)
+      } else {
+        this.orWhereNull(descriptor.column)
+      }
+    })
+  }
+  if (value === null) {
+    const isNotNull = operator === 'IS NOT NULL'
+    if (descriptor.queryFieldRuntime) {
+      return builder.whereRaw(`(${descriptor.queryFieldRuntime.sql}) IS ${isNotNull ? 'NOT ' : ''}NULL`, descriptor.queryFieldRuntime.bindings)
+    }
+    return isNotNull ? builder.whereNotNull(descriptor.column) : builder.whereNull(descriptor.column)
+  }
+  if (descriptor.definition?.storage?.serialize) {
+    return builder.where(descriptor.column, operator, value)
+  }
   if (descriptor?.queryFieldRuntime) {
     return applyQueryFieldPredicate(builder, descriptor.queryFieldRuntime, operator, value)
   }
@@ -62,19 +227,27 @@ export const buildCursorPredicateChains = (
 
     if (cursorValue === undefined) {
       onMissingValue?.(descriptor.field)
-      return
+      throw new RestApiValidationError(`Cursor is missing a value for sort field '${descriptor.field}'.`, {
+        fields: [descriptor.field],
+        violations: [{
+          field: descriptor.field,
+          rule: 'missing_cursor_value',
+          message: 'Cursor must include every sort field.'
+        }]
+      })
     }
 
+    const operator = operatorSelector(descriptor.direction)
+    const forward = operator === (descriptor.direction.toUpperCase() === 'DESC' ? '<' : '>')
+    // Nulls sort last. There are no values after null at this sort position,
+    // but later tie breakers can still advance within the null group.
+    if (cursorValue === null && forward) 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: '=',
@@ -84,8 +257,9 @@ export const buildCursorPredicateChains = (
 
     chain.push({
       descriptor,
-      operator: operatorSelector(descriptor.direction),
-      value: cursorValue
+      operator: cursorValue === null ? 'IS NOT NULL' : operator,
+      value: cursorValue,
+      includeNull: cursorValue !== null && forward
     })
 
     predicateChains.push(chain)
@@ -116,13 +290,14 @@ export const applyCursorPredicate = (
   query.where(function () {
     predicateChains.forEach((chain) => {
       this.orWhere(function () {
-        chain.forEach(({ descriptor, operator, value }) => {
+        chain.forEach(({ descriptor, operator, value, includeNull }) => {
           applySortDescriptorPredicate(
             this,
             descriptor,
             operator,
             value,
-            applyPlainPredicate
+            applyPlainPredicate,
+            includeNull
           )
         })
       })

package/plugins/core/lib/querying/relationship-identifiers.js

@@ -0,0 +1,208 @@
+import { whereInIdentifiers } from './identifier-query.js'
+import { RELATIONSHIPS_KEY } from '../querying-writing/knex-constants.js'
+import { databaseIdentityExpression } from '../querying-writing/database-value-normalizers.js'
+import { getResourceFieldset, parseFieldset } from '../querying-writing/field-utils.js'
+import {
+  getIdColumnForScope,
+  getFieldValueForScope,
+  translateColumnForScope,
+  applyScopeFiltersToIncludeQuery,
+  parseIncludeTree,
+} from './include-query-helpers.js'
+/**
+ * Loads relationship identifiers for all hasMany relationships without fetching full related records.
+ *
+ * ## Purpose
+ * This function ensures that all hasMany relationships (one-to-many, many-to-many, and polymorphic)
+ * always return resource identifiers in the JSON:API response, even when the related resources
+ * are not included via the ?include parameter.
+ *
+ * ## Why this is needed
+ * 1. **JSON:API Consistency**: The JSON:API spec allows servers to include relationship identifiers
+ *    without including the full related resources. This provides a consistent API surface where
+ *    clients always know what relationships exist and their IDs.
+ *
+ * 2. **Simplified Mode Support**: In simplified mode, relationship IDs are transformed into
+ *    minimal objects (e.g., `reviews: [{id: '1'}, {id: '2'}, {id: '3'}]`). Without this function,
+ *    these objects only appear when using ?include, creating an inconsistent API where fields appear/disappear.
+ *
+ * 3. **Performance Balance**: Loading just IDs is much cheaper than loading full records. This gives
+ *    clients the ability to know what relationships exist without the cost of fetching all data.
+ *
+ * ## What it does
+ * - Runs ONE query per relationship type (not per record) to fetch all related IDs
+ * - Populates the relationship data with resource identifiers: `{ type: 'resource', id: '123' }`
+ * - Handles all relationship types: one-to-many, many-to-many, and polymorphic
+ * - Works for both JSON:API and simplified modes (transformation happens elsewhere)
+ *
+ * ## When it runs
+ * This runs after the main records are fetched but before includes are processed.
+ * If includes ARE specified, they will overwrite these IDs with full data.
+ *
+ * @param {Array<Object>} records - The parent records to load relationships for
+ * @param {string} scopeName - The parent scope name (e.g., 'authors')
+ * @param {Object} scopes - All available scopes with their schemas
+ * @param {Object} knex - Knex instance for database queries
+ * @param {import('../storage/storage-types.js').DataReadContext | null} [requestContext]
+ * @returns {Promise<void>} Modifies records in place by adding relationship data
+ */
+export const loadRelationshipIdentifiers = async (records, scopeName, scopes, knex, requestContext = null) => {
+  if (!records.length) return
+
+  const schemaInfo = scopes[scopeName]?.vars?.schemaInfo
+  if (!schemaInfo) throw new Error(`Missing relationship schema for scope '${scopeName}'`)
+
+  const relationships = schemaInfo.schemaRelationships || {}
+  const recordIds = records.map(record => String(getFieldValueForScope(scopes, scopeName, record, 'id')))
+  const requestedFields = parseFieldset(getResourceFieldset(requestContext?.queryParams?.fields, scopeName))
+  const includeTree = parseIncludeTree(requestContext?.queryParams?.include)
+
+  // Process each hasMany relationship
+  for (const [relName, relDef] of Object.entries(relationships)) {
+    if (requestedFields !== null && !requestedFields.includes(relName)) continue
+    if (Object.hasOwn(includeTree, relName)) continue
+    const idsMap = Object.create(null)
+
+    if (relDef.type === 'hasMany' && !relDef.via) {
+      // Regular one-to-many
+      // Example: publisher hasMany authors
+      const foreignKey = relDef.foreignKey
+
+      if (!foreignKey) {
+        throw new Error(`Missing foreignKey in hasMany relationship '${relName}' for scope '${scopeName}'`)
+      }
+      const targetScope = scopes[relDef.target]
+      const targetTable = targetScope?.vars?.schemaInfo?.tableName || relDef.target
+      const targetIdColumn = getIdColumnForScope(scopes, relDef.target)
+      const foreignKeyColumn = translateColumnForScope(scopes, relDef.target, foreignKey)
+
+      let query = knex(targetTable)
+        .modify(whereInIdentifiers, foreignKeyColumn, recordIds)
+        .select({ id: databaseIdentityExpression(knex, `${targetTable}.${targetIdColumn}`), [foreignKeyColumn]: databaseIdentityExpression(knex, `${targetTable}.${foreignKeyColumn}`) })
+
+      const scopedQueryState = await applyScopeFiltersToIncludeQuery({
+        query,
+        scopes,
+        scopeName: relDef.target,
+        requestContext,
+        db: knex,
+        tableName: targetTable,
+        queryPurpose: 'relationship-identifiers'
+      })
+      query = scopedQueryState.query
+
+      const results = await query
+
+      results.forEach(row => {
+        const parentId = String(row[foreignKeyColumn])
+        if (!idsMap[parentId]) idsMap[parentId] = []
+        idsMap[parentId].push(String(row.id))
+      })
+    } else if (relDef.type === 'manyToMany') {
+      // Many-to-many relationship
+      // Example: { type: 'manyToMany', through: 'article_tags', foreignKey: 'article_id', otherKey: 'tag_id' }
+      const { through, foreignKey, otherKey } = relDef
+      const fk = translateColumnForScope(scopes, through, foreignKey)
+      const ok = translateColumnForScope(scopes, through, otherKey)
+
+      if (!fk || !ok) {
+        throw new Error(`Missing foreignKey or otherKey in manyToMany relationship '${relName}' for scope '${scopeName}'`)
+      }
+
+      // Get the actual table name from the pivot scope
+      const pivotScope = scopes[through]
+      const pivotTable = pivotScope?.vars?.schemaInfo?.tableName || through
+
+      const targetScopeName = relDef.target || relName
+      const targetTable = scopes[targetScopeName]?.vars?.schemaInfo?.tableName || targetScopeName
+      const targetIdColumn = getIdColumnForScope(scopes, targetScopeName)
+      let query = knex(targetTable)
+        .join(`${pivotTable} as pivot`, `${targetTable}.${targetIdColumn}`, `pivot.${ok}`)
+        .modify(whereInIdentifiers, `pivot.${fk}`, recordIds)
+        .select({ __parent_id: databaseIdentityExpression(knex, `pivot.${fk}`), id: databaseIdentityExpression(knex, `${targetTable}.${targetIdColumn}`) })
+
+      const scopedQueryState = await applyScopeFiltersToIncludeQuery({
+        query,
+        scopes,
+        scopeName: targetScopeName,
+        requestContext,
+        db: knex,
+        tableName: targetTable,
+        queryPurpose: 'relationship-identifiers'
+      })
+      const pivotState = await applyScopeFiltersToIncludeQuery({
+        query: scopedQueryState.query, scopes, scopeName: through, requestContext, db: knex, tableName: 'pivot', queryPurpose: 'relationship-identifiers'
+      })
+      query = pivotState.query
+
+      const results = await query
+
+      results.forEach(row => {
+        const parentId = String(row.__parent_id)
+        const childId = String(row.id)
+        if (!idsMap[parentId]) idsMap[parentId] = []
+        idsMap[parentId].push(childId)
+      })
+    } else if (relDef.type === 'hasMany' && relDef.via) {
+      // Polymorphic reverse (via)
+      // Example: publishers hasMany reviews via reviewable (where reviews.reviewable_type = 'publishers')
+      const targetScope = relDef.target
+      const targetRelationships = scopes[targetScope]?.vars?.schemaInfo?.schemaRelationships
+      const viaRel = targetRelationships?.[relDef.via]
+
+      if (!viaRel?.belongsToPolymorphic) {
+        throw new Error(`Reverse relationship '${scopeName}.${relName}' requires polymorphic relationship '${targetScope}.${relDef.via}'`)
+      }
+      const { typeField, idField } = viaRel.belongsToPolymorphic
+
+      // Get the actual table name
+      const targetTable = scopes[targetScope]?.vars?.schemaInfo?.tableName || targetScope
+      const targetIdColumn = getIdColumnForScope(scopes, targetScope)
+      const typeColumn = translateColumnForScope(scopes, targetScope, typeField)
+      const idColumn = translateColumnForScope(scopes, targetScope, idField)
+
+      let query = knex(targetTable)
+        .where(typeColumn, scopeName)
+        .modify(whereInIdentifiers, idColumn, recordIds)
+        .select({ id: databaseIdentityExpression(knex, `${targetTable}.${targetIdColumn}`), [idColumn]: databaseIdentityExpression(knex, `${targetTable}.${idColumn}`) })
+
+      const scopedQueryState = await applyScopeFiltersToIncludeQuery({
+        query,
+        scopes,
+        scopeName: targetScope,
+        requestContext,
+        db: knex,
+        tableName: targetTable,
+        queryPurpose: 'relationship-identifiers'
+      })
+      query = scopedQueryState.query
+
+      const results = await query
+
+      results.forEach(row => {
+        const parentId = String(row[idColumn])
+        if (!idsMap[parentId]) idsMap[parentId] = []
+        idsMap[parentId].push(String(row.id))
+      })
+    }
+
+    // Apply the collected IDs to all records
+    if (Object.keys(idsMap).length > 0 || relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
+      records.forEach(record => {
+        if (!record[RELATIONSHIPS_KEY]) {
+          record[RELATIONSHIPS_KEY] = {}
+        }
+
+        const ids = idsMap[String(getFieldValueForScope(scopes, scopeName, record, 'id'))] || []
+        const targetType = relDef.target || relName
+
+        record[RELATIONSHIPS_KEY][relName] = {
+          data: ids.map(id => ({
+            type: targetType,
+            id
+          }))
+        }
+      })
+    }
+  }
+}

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

@@ -1,6 +1,21 @@
+// @ts-check
+
+/**
+ * @param {unknown} [sort]
+ * @param {{ idField?: string }} [options]
+ * @returns {string[]}
+ */
 export function normalizeStableSort (sort = [], { idField = 'id' } = {}) {
+  /** @type {Set<string>} */
+  const seenFields = new Set()
   const sortList = Array.isArray(sort)
-    ? sort.filter((entry) => typeof entry === 'string' && entry.trim())
+    ? sort.filter(/** @param {unknown} entry @returns {entry is string} */ (entry) => {
+      if (typeof entry !== 'string' || !entry.trim()) return false
+      const field = entry.startsWith('-') ? entry.slice(1) : entry
+      if (seenFields.has(field)) return false
+      seenFields.add(field)
+      return true
+    })
     : []
 
   if (sortList.length === 0) {
@@ -19,6 +34,10 @@ export function normalizeStableSort (sort = [], { idField = 'id' } = {}) {
   return sortList
 }
 
+/**
+ * @param {string} sortEntry
+ * @returns {{ raw: string, field: string, desc: boolean, direction: 'asc' | 'desc', sqlDirection: 'ASC' | 'DESC' }}
+ */
 export function parseSortEntry (sortEntry) {
   const desc = typeof sortEntry === 'string' && sortEntry.startsWith('-')
   const field = desc ? sortEntry.slice(1) : sortEntry

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

@@ -1,27 +1,33 @@
+// @ts-check
+/** @import { StorageAdapter, StorageHookParams } from '../storage/storage-types.js' */
+
+/** @param {StorageHookParams} hookParams @param {{ getStorageAdapter?: (scopeName: string) => StorageAdapter | null | undefined }} [options] */
 export const createStorageAdapterUtilities = (hookParams, { getStorageAdapter } = {}) => {
   const context = hookParams?.context || {}
   const activeQuery = context.knexQuery || {}
   const activeScopeName = activeQuery.scopeName
   const activeTableName = activeQuery.tableName
   const activeStorageAdapter = activeQuery.storageAdapter || context.storageAdapter
+  /** @type {Map<string, StorageAdapter | null | undefined>} */
   const storageCache = new Map()
 
+  /** @param {string} scopeName @returns {StorageAdapter | null | undefined} */
   const fetchStorageAdapter = (scopeName) => {
     if (!scopeName) return null
     if (storageCache.has(scopeName)) return storageCache.get(scopeName)
 
     let adapter = null
-    if (scopeName === activeScopeName) {
-      adapter = activeStorageAdapter ||
-        (typeof getStorageAdapter === 'function' ? getStorageAdapter(scopeName) : null)
-    } else {
-      adapter = typeof getStorageAdapter === 'function' ? getStorageAdapter(scopeName) : null
+    if (scopeName === activeScopeName && activeStorageAdapter) {
+      adapter = activeStorageAdapter
+    } else if (typeof getStorageAdapter === 'function') {
+      adapter = getStorageAdapter(scopeName)
     }
 
     storageCache.set(scopeName, adapter)
     return adapter
   }
 
+  /** @param {string} scopeName @returns {string} */
   const defaultAliasForScope = (scopeName) => {
     if (scopeName === activeScopeName) {
       return activeTableName || scopeName
@@ -29,6 +35,7 @@ export const createStorageAdapterUtilities = (hookParams, { getStorageAdapter }
     return scopeName
   }
 
+  /** @param {string} scopeName @param {string} field @param {string | null} [alias] @returns {string} */
   const translateColumn = (scopeName, field, alias = defaultAliasForScope(scopeName)) => {
     const adapter = fetchStorageAdapter(scopeName)
     const translated = adapter?.translateColumn?.(field) ?? field
@@ -36,6 +43,7 @@ export const createStorageAdapterUtilities = (hookParams, { getStorageAdapter }
     return `${alias}.${translated}`
   }
 
+  /** @param {string} scopeName @param {string} field @param {unknown} value @returns {unknown} */
   const translateFilterValue = (scopeName, field, value) => {
     const adapter = fetchStorageAdapter(scopeName)
     if (!adapter?.translateFilterValue) return value

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

@@ -5,6 +5,13 @@
  * and support flexible URL prefix override capabilities.
  */
 
+import { serializeJsonApiQuery } from '../querying-writing/connectors-query-parser.js'
+
+export const buildJsonApiLink = (baseUrl, queryParams, page) => {
+  const queryString = serializeJsonApiQuery(queryParams, { page })
+  return queryString ? `${baseUrl}?${queryString}` : baseUrl
+}
+
 /**
  * Get the complete URL prefix, handling all calculation and override logic
  *
@@ -63,7 +70,7 @@ export function getUrlPrefix (context, scope) {
  */
 export function buildResourceUrl (context, scope, scopeName, id) {
   const urlPrefix = getUrlPrefix(context, scope)
-  return `${urlPrefix}/${scopeName}/${id}`
+  return `${urlPrefix}/${scopeName}/${encodeURIComponent(id)}`
 }
 
 /**
@@ -87,11 +94,11 @@ export function buildResourceUrl (context, scope, scopeName, id) {
  * // Returns: "https://api.example.com/api/books/1/author"
  */
 export function buildRelationshipUrl (context, scope, scopeName, id, relationshipName, isRelationshipEndpoint = false) {
-  const urlPrefix = getUrlPrefix(context, scope)
+  const resourceUrl = buildResourceUrl(context, scope, scopeName, id)
   if (isRelationshipEndpoint) {
-    return `${urlPrefix}/${scopeName}/${id}/relationships/${relationshipName}`
+    return `${resourceUrl}/relationships/${relationshipName}`
   }
-  return `${urlPrefix}/${scopeName}/${id}/${relationshipName}`
+  return `${resourceUrl}/${relationshipName}`
 }
 
 /**