feat: support qs-esm sort arrays in REST API (#15065)

### What?

Support qs-esm array in sort parameter to sort by multiple columns in
REST API

### Why?

To align input of Local API and REST API so that REST API also accepts
array like Local API do.

### How?

Extract parsing/sanitizing of sort input to it's own method which also
accept array.
Added unit and integration test. Updated docs with example.

Fixes #15052

Author: andershermansen

docs/queries/sort.mdx

@@ -67,6 +67,27 @@ fetch('https://localhost:3000/api/posts?sort=priority,-createdAt') // highlight-
   .then((data) => console.log(data))
 ```
 
+You can also pass `sort` as an array so each item is a single field when using query string builder:
+
+```ts
+import { stringify } from 'qs-esm'
+
+const getPosts = async () => {
+  const stringifiedQuery = stringify(
+    {
+      sort: ['priority', '-createdAt'],
+    },
+    { addQueryPrefix: true },
+  )
+
+  const response = await fetch(
+    `https://localhost:3000/api/posts${stringifiedQuery}`, // highlight-line
+  )
+  const data = await response.json()
+  return data
+}
+```
+
 ## GraphQL API
 
 To sort in the [GraphQL API](../graphql/overview), you can use the `sort` parameter in your query:

packages/payload/src/globals/endpoints/findVersions.ts

@@ -8,6 +8,7 @@ import { headersWithCors } from '../../utilities/headersWithCors.js'
 import { isNumber } from '../../utilities/isNumber.js'
 import { sanitizePopulateParam } from '../../utilities/sanitizePopulateParam.js'
 import { sanitizeSelectParam } from '../../utilities/sanitizeSelectParam.js'
+import { sanitizeSortParams } from '../../utilities/sanitizeSortParams.js'
 import { findVersionsOperation } from '../operations/findVersions.js'
 
 export const findVersionsHandler: PayloadHandler = async (req) => {
@@ -19,7 +20,7 @@ export const findVersionsHandler: PayloadHandler = async (req) => {
     pagination?: string
     populate?: Record<string, unknown>
     select?: Record<string, unknown>
-    sort?: string
+    sort?: string | string[]
     where?: Where
   }
 
@@ -32,7 +33,7 @@ export const findVersionsHandler: PayloadHandler = async (req) => {
     populate: sanitizePopulateParam(populate),
     req,
     select: sanitizeSelectParam(select),
-    sort: typeof sort === 'string' ? sort.split(',') : undefined,
+    sort: sanitizeSortParams(sort),
     where,
   })
 

packages/payload/src/utilities/parseParams/index.spec.ts

@@ -1,3 +1,4 @@
+import * as qs from 'qs-esm'
 import { describe, it, expect } from 'vitest'
 import { parseParams, booleanParams, numberParams } from './index.js'
 
@@ -105,11 +106,28 @@ describe('parseParams', () => {
       expect(result.sort).toEqual(['name', ' createdAt ', ' -updatedAt'])
     })
 
+    it('should parse array of strings', () => {
+      const result = parseParams({ sort: ['name', '-createdAt'] })
+      expect(result.sort).toEqual(['name', '-createdAt'])
+    })
+
     it('should return undefined for non-string sort values', () => {
       const result = parseParams({ sort: 123 as any })
       expect(result.sort).toBeUndefined()
     })
 
+    it('should return undefined for array with non-string sort values', () => {
+      const result = parseParams({ sort: ['name', 123] as any })
+      expect(result.sort).toBeUndefined()
+    })
+
+    it('should handle qs-esm array sort parsing', () => {
+      const query = qs.stringify({ sort: ['title', '-createdAt'] })
+      const parsed = qs.parse(query)
+      const result = parseParams(parsed)
+      expect(result.sort).toEqual(['title', '-createdAt'])
+    })
+
     it('should return undefined for null sort values', () => {
       const result = parseParams({ sort: null as any })
       expect(result.sort).toBeUndefined()

packages/payload/src/utilities/parseParams/index.ts

@@ -6,6 +6,7 @@ import { parseBooleanString } from '../parseBooleanString.js'
 import { sanitizeJoinParams } from '../sanitizeJoinParams.js'
 import { sanitizePopulateParam } from '../sanitizePopulateParam.js'
 import { sanitizeSelectParam } from '../sanitizeSelectParam.js'
+import { sanitizeSortParams } from '../sanitizeSortParams.js'
 
 type ParsedParams = {
   autosave?: boolean
@@ -45,7 +46,7 @@ type RawParams = {
   publishSpecificLocale?: string
   select?: unknown
   selectedLocales?: string
-  sort?: string
+  sort?: string | string[]
   trash?: string
   where?: Where
 }
@@ -66,7 +67,7 @@ export const numberParams = ['depth', 'limit', 'page']
  * Examples:
  *   a. `draft` provided as a string of "true" is converted to a boolean
  *   b. `depth` provided as a string of "0" is converted to a number
- *   c. `sort` provided as a comma-separated string is converted to an array of strings
+ *   c. `sort` provided as a comma-separated string or array is converted to an array of strings
  */
 export const parseParams = (params: RawParams): ParsedParams => {
   const parsedParams = (params || {}) as ParsedParams
@@ -99,7 +100,7 @@ export const parseParams = (params: RawParams): ParsedParams => {
   }
 
   if ('sort' in params) {
-    parsedParams.sort = typeof params.sort === 'string' ? params.sort.split(',') : undefined
+    parsedParams.sort = sanitizeSortParams(params.sort)
   }
 
   if ('data' in params && typeof params.data === 'string' && params.data.length > 0) {

packages/payload/src/utilities/sanitizeSortParams.ts

@@ -0,0 +1,11 @@
+export const sanitizeSortParams = (sort: unknown): string[] | undefined => {
+  if (typeof sort === 'string') {
+    return sort.split(',')
+  }
+
+  if (Array.isArray(sort) && sort.every((value) => typeof value === 'string')) {
+    return sort
+  }
+
+  return undefined
+}

test/sort/int.spec.ts

@@ -1,6 +1,7 @@
 import type { CollectionSlug, Payload } from 'payload'
 
 import path from 'path'
+import * as qs from 'qs-esm'
 import { fileURLToPath } from 'url'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 
@@ -915,6 +916,23 @@ describe('Sort', () => {
         ])
       })
     })
+
+    describe('Sort by multiple fields as array', () => {
+      it('should sort posts by multiple fields using qs-esm array params', async () => {
+        const query = qs.stringify({ sort: ['number2', '-number'] })
+
+        const res = await restClient.GET(`/posts?${query}`).then((res) => res.json())
+
+        expect(res.docs.map((post) => post.text)).toEqual([
+          'Post 10', // 5, 10
+          'Post 3', // 5, 3
+          'Post 2', // 10, 2
+          'Post 1', // 10, 1
+          'Post 12', // 20, 12
+          'Post 11', // 20, 11
+        ])
+      })
+    })
   })
 })