json-rest-api 1.0.29 → 2.1.0

package/plugins/core/lib/querying/knex-window-queries.js

@@ -1,261 +1,70 @@
 import { RestApiResourceError } from '../../../../lib/rest-api-errors.js'
 import { ROW_NUMBER_KEY, DEFAULT_QUERY_LIMIT, DEFAULT_MAX_QUERY_LIMIT, DEFAULT_MAX_INCLUDE_LIMIT } from '../querying-writing/knex-constants.js'
-
-/**
- * Builds the inner window-function query used to limit included children per
- * parent. Mandatory target filters must be applied to this inner query before
- * the caller wraps it and filters by ROW_NUMBER.
- *
- * @param {Object} knex - Knex instance
- * @param {string} tableName - Target table name
- * @param {string} foreignKey - Foreign key field
- * @param {Array} parentIds - Parent record IDs
- * @param {Array|string} fieldsToSelect - Fields to select, or '*'
- * @param {Object} includeConfig - Include limit and ordering
- * @param {Object} capabilities - Database capabilities
- * @param {Object} scopeVars - Resource query limits
- * @returns {{ subquery: Object, effectiveLimit: number }} Inner query and validated limit
- */
-export const buildWindowedIncludeSubquery = (
-  knex,
-  tableName,
-  foreignKey,
-  parentIds,
-  fieldsToSelect,
-  includeConfig,
-  capabilities,
-  scopeVars = {}
-) => {
-  const { orderBy = [] } = includeConfig
-
-  // Apply defaults for limit
-  const effectiveLimit = includeConfig.limit ?? scopeVars.queryDefaultLimit ?? DEFAULT_QUERY_LIMIT
-
-  // Validate against max
-  if (scopeVars.queryMaxLimit && effectiveLimit > scopeVars.queryMaxLimit) {
-    throw new RestApiResourceError({
-      title: 'Include Limit Exceeds Maximum',
-      detail: `Requested include limit (${effectiveLimit}) exceeds queryMaxLimit (${scopeVars.queryMaxLimit})`,
-      status: 400
-    })
+import { prepareReferenceSortColumns } from './knex-query-helpers.js'
+import { buildEffectiveSortList, parseSortEntry, resolveSortField } from './query-field-sort-helpers.js'
+import { applyDatabaseReadOptions, databaseIdentityExpression } from '../querying-writing/database-value-normalizers.js'
+
+// Apply ordering and limits after target/pivot visibility has constrained the query.
+export async function applyIncludeQueryConfig ({ query, scopeName, tableName, parentColumn, includeConfig = {}, context = {}, capabilities, queryFieldRuntimeByField = new Map() }, dependencies) {
+  const { scopes, knex, getStorageAdapter } = dependencies
+  const db = context.db || context.transaction || knex
+  const vars = scopes[scopeName].vars
+  const storageAdapter = getStorageAdapter(scopeName)
+  const fields = buildEffectiveSortList(includeConfig.orderBy, { defaultSort: vars.defaultSort, schemaInfo: vars.schemaInfo }).map(parseSortEntry)
+  const references = await prepareReferenceSortColumns({
+    query,
+    fields: fields.map(({ field }) => field).filter(field => !queryFieldRuntimeByField.has(field)),
+    scopeName,
+    tableAlias: tableName,
+    context
+  }, dependencies)
+  const names = new Set([
+    ...Object.keys(vars.schemaInfo?.queryFields || {}),
+    ...Object.keys(vars.schemaInfo.schemaStructure).flatMap(field => [field, storageAdapter.translateColumn(field)]),
+    ...[...references.values()].map(reference => reference.resultColumn)
+  ])
+  const uniqueName = base => {
+    let name = base
+    while (names.has(name)) name += '_'
+    names.add(name)
+    return name
   }
-
-  // Check if window functions are supported
-  if (!capabilities.windowFunctions) {
-    const { dbInfo } = capabilities
-    throw new RestApiResourceError(
-      `Include limits require window function support. Your database (${dbInfo.client} ${dbInfo.version}) does not support this feature. ` +
-      'Window functions are supported in: PostgreSQL 8.4+, MySQL 8.0+, MariaDB 10.2+, SQLite 3.25+, SQL Server 2005+',
-      {
-        subtype: 'unsupported_operation',
-        database: dbInfo.client,
-        version: dbInfo.version,
-        requiredFeature: 'window_functions'
+  const parentResultColumn = uniqueName('__jra_include_parent')
+  const rowNumberColumn = uniqueName(ROW_NUMBER_KEY)
+  query.select({ [parentResultColumn]: typeof parentColumn === 'string' ? databaseIdentityExpression(db, parentColumn) : parentColumn })
+  const ordering = fields.map(({ field, sqlDirection }) => {
+    const runtime = queryFieldRuntimeByField.get(field)
+    if (runtime) {
+      return {
+        sql: `(${runtime.sql}) IS NULL ASC, (${runtime.sql}) ${sqlDirection}`,
+        bindings: [...runtime.bindings, ...runtime.bindings]
       }
-    )
-  }
-
-  // Build the window function query
-  // This creates a subquery that partitions by the foreign key and numbers rows
-  const subquery = knex(tableName)
-    .select('*')
-    .select(
-      knex.raw(
-        'ROW_NUMBER() OVER (PARTITION BY ?? ORDER BY ' +
-        buildOrderByClause(orderBy) +
-        ') as ' + ROW_NUMBER_KEY,
-        [foreignKey]
-      )
-    )
-    .whereIn(foreignKey, parentIds)
-
-  // Apply field selection if specified
-  if (fieldsToSelect !== '*' && Array.isArray(fieldsToSelect)) {
-    // Include the foreign key and row number in selection
-    const fieldsWithFK = [...new Set([...fieldsToSelect, foreignKey, ROW_NUMBER_KEY])]
-    subquery.select(fieldsWithFK)
-  }
-
-  return { subquery, effectiveLimit }
-}
-
-/**
- * Builds ORDER BY clause from array of sort fields
- *
- * @param {Array<string>} orderBy - Array of field names, prefix with '-' for DESC
- * @param {string} tablePrefix - Optional table name to prefix fields
- * @returns {string} SQL ORDER BY clause
- *
- * @example
- * // Input: Simple ascending sort
- * const clause = buildOrderByClause(['name', 'created_at']);
- * // Output: "name ASC, created_at ASC"
- *
- * @example
- * // Input: Mixed ascending/descending with '-' prefix
- * const clause = buildOrderByClause(['name', '-created_at', 'status']);
- * // Output: "name ASC, created_at DESC, status ASC"
- *
- * @example
- * // Input: With table prefix for joins
- * const clause = buildOrderByClause(['-updated_at', 'title'], 'articles');
- * // Output: "articles.updated_at DESC, articles.title ASC"
- *
- * @example
- * // Input: Empty array (default to id)
- * const clause = buildOrderByClause([]);
- * // Output: "id ASC"
- *
- * @description
- * Used by:
- * - buildWindowedIncludeSubquery for PARTITION BY ordering
- * - applyStandardIncludeConfig for regular ORDER BY
- * - Query builders that need consistent sort syntax
- *
- * Purpose:
- * - Converts API sort syntax (with '-' prefix) to SQL ORDER BY
- * - Handles table prefixing for queries with joins
- * - Provides default ordering by id when none specified
- * - Ensures consistent sort behavior across the API
- *
- * Data flow:
- * 1. Receives array of sort fields from API parameters
- * 2. Detects DESC sorts by '-' prefix
- * 3. Optionally prefixes with table name
- * 4. Joins into SQL-compatible ORDER BY clause
- */
-export const buildOrderByClause = (orderBy, tablePrefix) => {
-  if (!orderBy || orderBy.length === 0) {
-    const defaultField = tablePrefix ? `${tablePrefix}.id` : 'id'
-    return `${defaultField} ASC` // Default ordering
-  }
-
-  return orderBy.map(field => {
-    const isDesc = field.startsWith('-')
-    const fieldName = isDesc ? field.substring(1) : field
-    const qualifiedField = tablePrefix ? `${tablePrefix}.${fieldName}` : fieldName
-    return `${qualifiedField} ${isDesc ? 'DESC' : 'ASC'}`
-  }).join(', ')
-}
-
-/**
- * Applies standard (non-windowed) include configuration to a query
- *
- * @param {Object} query - Knex query builder instance
- * @param {Object} includeConfig - Include configuration object
- * @param {Object} scopeVars - Scope variables with defaults and limits
- * @param {Object} log - Logger instance
- * @returns {Object} Modified query builder
- *
- * @example
- * // Input: Basic include with limit and ordering
- * let query = knex('comments').whereIn('article_id', [1, 2, 3]);
- * query = applyStandardIncludeConfig(
- *   query,
- *   { limit: 20, orderBy: ['-created_at', 'id'] },
- *   { queryDefaultLimit: 100, queryMaxLimit: 1000 },
- *   logger
- * );
- *
- * // Result: Query modified with:
- * // ORDER BY created_at DESC, id ASC
- * // LIMIT 20
- *
- * @example
- * // Input: No explicit limit, uses defaults
- * let query = knex('tags');
- * query = applyStandardIncludeConfig(
- *   query,
- *   { orderBy: ['name'] },  // No limit specified
- *   { queryDefaultLimit: 50, queryMaxLimit: 500 },
- *   logger
- * );
- *
- * // Result: Uses default limit
- * // ORDER BY name ASC
- * // LIMIT 50
- * // Log: "Using default limit"
- *
- * @example
- * // Input: Limit exceeds maximum
- * let query = knex('reviews');
- * query = applyStandardIncludeConfig(
- *   query,
- *   { limit: 5000 },  // Exceeds max
- *   { queryMaxLimit: 1000, maxIncludeLimit: 500 },
- *   logger
- * );
- *
- * // Result: Clamped to effective maximum
- * // LIMIT 500 (min of maxIncludeLimit and queryMaxLimit)
- *
- * @example
- * // Input: Explicitly disable limit
- * let query = knex('categories');
- * query = applyStandardIncludeConfig(
- *   query,
- *   { limit: null },  // Explicitly no limit
- *   { queryDefaultLimit: 100 },
- *   logger
- * );
- *
- * // Result: No LIMIT clause added
- * // Log: "No limit applied to include query (explicitly disabled)"
- *
- * @description
- * Used by:
- * - loadHasMany when window functions not available or not requested
- * - loadReversePolymorphic for standard relationship queries
- * - Any include loader that needs consistent limit/order handling
- *
- * Purpose:
- * - Provides fallback when window functions unavailable
- * - Applies consistent ordering based on API sort syntax
- * - Enforces limit hierarchy: explicit > default > max
- * - Respects both queryMaxLimit and maxIncludeLimit
- * - Logs decisions for debugging
- *
- * Data flow:
- * 1. Applies ORDER BY for each field in orderBy array
- * 2. Determines effective limit from explicit/default/max values
- * 3. Clamps limit to maximum allowed values
- * 4. Adds LIMIT clause unless explicitly disabled
- * 5. Logs the reasoning for the applied limit
- */
-export const applyStandardIncludeConfig = (query, includeConfig, scopeVars, log) => {
-  const { orderBy = [] } = includeConfig
-
-  // Apply ordering
-  orderBy.forEach(field => {
-    const desc = field.startsWith('-')
-    const column = desc ? field.substring(1) : field
-    query = query.orderBy(column, desc ? 'desc' : 'asc')
+    }
+    const actualField = resolveSortField(field, vars.schemaInfo)
+    const column = references.get(field)?.column || `${tableName}.${storageAdapter.translateColumn(actualField)}`
+    return { sql: `?? IS NULL ASC, ?? ${sqlDirection}`, bindings: [column, column] }
   })
-
-  // Apply limit with defaults
-  const requestedLimit = includeConfig.limit
-  const defaultLimit = scopeVars.queryDefaultLimit ?? DEFAULT_QUERY_LIMIT
-  const limit = requestedLimit ?? defaultLimit
-
-  // Allow explicit null/false to mean no limit
-  if (limit !== null && limit !== false) {
-    const maxInclude = scopeVars.maxIncludeLimit || DEFAULT_MAX_INCLUDE_LIMIT
-    const maxQuery = scopeVars.queryMaxLimit || DEFAULT_MAX_QUERY_LIMIT
-    const effectiveMax = Math.min(maxInclude, maxQuery)
-    const effectiveLimit = Math.min(limit, effectiveMax)
-
-    query = query.limit(effectiveLimit)
-
-    log.debug('Applied include limit:', {
-      requested: requestedLimit,
-      default: defaultLimit,
-      effective: effectiveLimit,
-      maxAllowed: effectiveMax,
-      note: requestedLimit !== undefined ? 'Using explicit limit' : 'Using default limit'
-    })
+  const orderSql = ordering.map(order => order.sql).join(', ')
+  const orderBindings = ordering.flatMap(order => order.bindings)
+  const requested = includeConfig.limit
+  const limit = requested === null || requested === false
+    ? null
+    : Math.min(requested ?? vars.queryDefaultLimit ?? DEFAULT_QUERY_LIMIT,
+      vars.queryMaxLimit ?? DEFAULT_MAX_QUERY_LIMIT, vars.maxIncludeLimit ?? DEFAULT_MAX_INCLUDE_LIMIT)
+  if (limit !== null && (!Number.isInteger(limit) || limit < 0)) throw new Error(`Invalid include limit for ${scopeName}: expected a non-negative integer or null`)
+
+  if (includeConfig.strategy === 'window' && limit !== null) {
+    if (capabilities?.windowFunctions === false) throw new RestApiResourceError('Per-parent include limits require window function support', { subtype: 'unsupported_operation' })
+    query.select(db.raw(`ROW_NUMBER() OVER (PARTITION BY ?? ORDER BY ${orderSql}) as ??`, [parentColumn, ...orderBindings, rowNumberColumn]))
+    query = db.select('*').from(query.as('_windowed')).where(rowNumberColumn, '<=', limit)
+      .orderBy(parentResultColumn).orderBy(rowNumberColumn)
   } else {
-    log.debug('No limit applied to include query (explicitly disabled)')
+    query.orderByRaw(orderSql, orderBindings)
+    if (limit !== null) query.limit(limit)
+  }
+  return {
+    query: applyDatabaseReadOptions(query),
+    parentColumn: parentResultColumn,
+    temporaryFields: [parentResultColumn, rowNumberColumn, ...[...references.values()].map(reference => reference.resultColumn)]
   }
-
-  return query
 }

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

@@ -1,4 +1,24 @@
-export const unwrapQueryBuilderState = (value, fallback = null) => {
+// @ts-check
+/** @import { StorageQuery, QueryFilteringState } from '../storage/storage-types.js' */
+
+/**
+ * @overload
+ * @param {import('../storage/storage-types.js').QueryBuilderResult | null | undefined} value
+ * @param {StorageQuery} fallback
+ * @returns {StorageQuery}
+ */
+/**
+ * @overload
+ * @param {unknown} value
+ * @param {unknown} [fallback]
+ * @returns {unknown}
+ */
+/**
+ * @param {unknown} value
+ * @param {unknown} [fallback]
+ * @returns {unknown} Hook values are untrusted until the caller validates them.
+ */
+export function unwrapQueryBuilderState (value, fallback = null) {
   let current = value
   const seen = new Set()
 
@@ -7,13 +27,33 @@ export const unwrapQueryBuilderState = (value, fallback = null) => {
     typeof current === 'object' &&
     !Array.isArray(current) &&
     Object.hasOwn(current, 'query') &&
-    current.query &&
-    current.query !== current &&
+    /** @type {{ query?: unknown }} */ (current).query &&
+    /** @type {{ query?: unknown }} */ (current).query !== current &&
     !seen.has(current)
   ) {
     seen.add(current)
-    current = current.query
+    current = /** @type {{ query?: unknown }} */ (current).query
   }
 
   return current || fallback
 }
+
+/**
+ * @param {{ knexQuery?: QueryFilteringState | null }} context
+ * @param {QueryFilteringState & { query: StorageQuery }} state
+ * @param {() => unknown | Promise<unknown>} applyFilters
+ * @returns {Promise<{ query: StorageQuery }>}
+ */
+// Return a wrapper: resolving an async function with a Knex builder executes it.
+export async function withQueryFilteringContext (context, state, applyFilters) {
+  const query = state.query
+  const previousKnexQuery = context.knexQuery
+  context.knexQuery = state
+  try {
+    await applyFilters()
+    return { query: context.knexQuery?.query || query }
+  } finally {
+    if (previousKnexQuery === undefined) delete context.knexQuery
+    else context.knexQuery = previousKnexQuery
+  }
+}

package/plugins/core/lib/querying/query-constraint.d.ts

@@ -0,0 +1,12 @@
+import type { MandatoryQueryConstraint, StorageAdapter, StorageQuery } from '../storage/storage-types.js'
+
+export type { MandatoryQueryConstraint } from '../storage/storage-types.js'
+export declare const queryConstraint: unique symbol
+
+export declare function applyQueryConstraint(options: {
+  query: StorageQuery
+  context: { [queryConstraint]?: MandatoryQueryConstraint }
+  scopeName: string
+  storageAdapter: StorageAdapter
+  tableName: string
+}): void

package/plugins/core/lib/querying/query-constraint.js

@@ -0,0 +1,27 @@
+// @ts-check
+/** @import { MandatoryQueryConstraint, StorageAdapter, StorageQuery } from '../storage/storage-types.js' */
+
+// Mandatory selection is independent of public search fields and caller filters.
+export const queryConstraint = Symbol('queryConstraint')
+
+/**
+ * @param {object} options
+ * @param {StorageQuery} options.query
+ * @param {{ [queryConstraint]?: MandatoryQueryConstraint }} options.context
+ * @param {string} options.scopeName
+ * @param {StorageAdapter} options.storageAdapter
+ * @param {string} options.tableName
+ */
+export function applyQueryConstraint ({ query, context, scopeName, storageAdapter, tableName }) {
+  const constraint = context[queryConstraint]
+  if (!constraint || constraint.scopeName !== scopeName) return
+
+  if (constraint.idsQuery) {
+    query.whereIn(`${tableName}.${storageAdapter.getIdColumn()}`, constraint.idsQuery)
+  }
+  for (const [field, value] of Object.entries(constraint.values || {})) {
+    query.where({
+      [`${tableName}.${storageAdapter.translateColumn(field)}`]: storageAdapter.translateFilterValue(field, value)
+    })
+  }
+}

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

@@ -1,11 +1,33 @@
+import { assertScalarQueryField } from '../querying-writing/field-utils.js'
 import { normalizeStableSort, parseSortEntry } from './sort-helpers.js'
 import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
-import { createSchema } from 'json-rest-schema'
-import { normalizeValueForDatabaseStorage } from '../querying-writing/database-value-normalizers.js'
+import { createSchemaFactory } from 'json-rest-schema'
+import { normalizeDateValue } from '../querying-writing/database-value-normalizers.js'
 
-export const validateCursorValues = (descriptors, cursorValues, parameter) => {
+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 } of descriptors) {
+  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
@@ -17,29 +39,46 @@ export const validateCursorValues = (descriptors, cursorValues, parameter) => {
       validated[field] = value
       continue
     }
-    const contract = createSchema({
-      value: {
-        type,
-        noTrim: true,
-        nullable: field !== 'id',
-        ...(definition?.temporalPrecision !== undefined
-          ? { temporalPrecision: definition.temporalPrecision }
-          : {})
-      }
+    const contract = getCursorContract(schema, {
+      type,
+      noTrim: true,
+      nullable: field !== 'id',
+      ...(definition?.temporalPrecision !== undefined
+        ? { temporalPrecision: definition.temporalPrecision }
+        : {})
     })
-    const { validatedObject, errors } = contract.patch({ value })
-    if (Object.keys(errors).length > 0 || (field === 'id' && !String(value ?? '').trim())) {
+    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}'.` }]
       })
     }
-    validated[field] = validatedObject.value
+    // 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 schema = vars.schemaInfo?.schemaStructure || {}
   const baseSortableFields = Array.isArray(vars.sortableFields) && vars.sortableFields.length > 0
@@ -50,42 +89,97 @@ export const getEffectiveSortableFields = (vars = {}) => {
       }), ...Object.entries(vars.schemaInfo?.searchSchemaStructure || {})
         .filter(([, definition]) => definition.isRelationship && schema[definition.actualField]?.hidden !== true)
         .map(([field]) => field)]
-  const queryFieldSortableFields = Object.entries(vars.queryFields || {})
+  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, 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) => {
-  const definition = queryFieldRuntime.definition || {}
-  const normalizedValue = normalizeValueForDatabaseStorage(value, definition.type, {
-    temporalPrecision: definition.temporalPrecision
-  })
-  builder.whereRaw(`(${queryFieldRuntime.sql}) ${operator} ?`, [...queryFieldRuntime.bindings, normalizedValue])
+  builder.whereRaw(`(${queryFieldRuntime.sql}) ${operator} ?`, [...queryFieldRuntime.bindings, value])
 }
 
 export const applySortDescriptorPredicate = (builder, descriptor, operator, value, applyPlainPredicate, includeNull = false) => {
@@ -106,6 +200,9 @@ export const applySortDescriptorPredicate = (builder, descriptor, operator, valu
     }
     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)
   }