chore: standardize query param parsing (#14498)

The way we parse query params within endpoint handlers is currently
non-standard. This leads to subtle differences in how they are handled
across endpoints, e.g. using searchParams vs req.query, allowing values
to fallback to undefined, etc.

For background, each endpoint accepts arbitrary query params and must
transform them into what Payload expects.

For example:
- `draft` provided as a string of "true" is converted to a boolean
- `depth` provided as a string of "0" is converted to a number
- `sort` provided as a comma-separated string is converted to an array
of strings

It is also easy to overlook params that should fallback to `undefined`.
Not doing so will prevent the underlying operation from using its
defaults, if any:

```ts
await update({
  // ...
  trash: trash === 'true' // This is never `undefined` so the default arg will not used (if any)
})
```

Parsing these params is now shared via a single `parseParams` utility,
which takes in raw query parameters and returns them typed and properly
formatted.

```ts
const {
  depth, // number | undefined
  draft // number | undefined
} = parseParams(req.query)
```

Author: jacobsfletch

packages/payload/src/collections/endpoints/count.ts

@@ -1,22 +1,20 @@
 import { status as httpStatus } from 'http-status'
 
 import type { PayloadHandler } from '../../config/types.js'
-import type { Where } from '../../types/index.js'
 
 import { getRequestCollection } from '../../utilities/getRequestEntity.js'
+import { parseParams } from '../../utilities/parseParams/index.js'
 import { countOperation } from '../operations/count.js'
 
 export const countHandler: PayloadHandler = async (req) => {
   const collection = getRequestCollection(req)
-  const { trash, where } = req.query as {
-    trash?: string
-    where?: Where
-  }
+
+  const { trash, where } = parseParams(req.query)
 
   const result = await countOperation({
     collection,
     req,
-    trash: trash === 'true',
+    trash,
     where,
   })
 

packages/payload/src/collections/endpoints/create.ts

@@ -5,29 +5,26 @@ import type { PayloadHandler } from '../../config/types.js'
 
 import { getRequestCollection } from '../../utilities/getRequestEntity.js'
 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 { parseParams } from '../../utilities/parseParams/index.js'
 import { createOperation } from '../operations/create.js'
 
 export const createHandler: PayloadHandler = async (req) => {
   const collection = getRequestCollection(req)
-  const { searchParams } = req
-  const autosave = searchParams.get('autosave') === 'true'
-  const draft = searchParams.get('draft') === 'true'
-  const depth = searchParams.get('depth')
+
+  const { autosave, depth, draft, populate, select } = parseParams(req.query)
+
   const publishSpecificLocale = req.query.publishSpecificLocale as string | undefined
 
   const doc = await createOperation({
     autosave,
     collection,
     data: req.data!,
-    depth: isNumber(depth) ? depth : undefined,
+    depth,
     draft,
-    populate: sanitizePopulateParam(req.query.populate),
+    populate,
     publishSpecificLocale,
     req,
-    select: sanitizeSelectParam(req.query.select),
+    select,
   })
 
   return Response.json(

packages/payload/src/collections/endpoints/delete.ts

@@ -2,34 +2,25 @@ import { getTranslation } from '@payloadcms/translations'
 import { status as httpStatus } from 'http-status'
 
 import type { PayloadHandler } from '../../config/types.js'
-import type { Where } from '../../types/index.js'
 
 import { getRequestCollection } from '../../utilities/getRequestEntity.js'
 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 { parseParams } from '../../utilities/parseParams/index.js'
 import { deleteOperation } from '../operations/delete.js'
 
 export const deleteHandler: PayloadHandler = async (req) => {
   const collection = getRequestCollection(req)
-  const { depth, overrideLock, populate, select, trash, where } = req.query as {
-    depth?: string
-    overrideLock?: string
-    populate?: Record<string, unknown>
-    select?: Record<string, unknown>
-    trash?: string
-    where?: Where
-  }
+
+  const { depth, overrideLock, populate, select, trash, where } = parseParams(req.query)
 
   const result = await deleteOperation({
     collection,
-    depth: isNumber(depth) ? Number(depth) : undefined,
-    overrideLock: Boolean(overrideLock === 'true'),
-    populate: sanitizePopulateParam(populate),
+    depth,
+    overrideLock: overrideLock ?? false,
+    populate,
     req,
-    select: sanitizeSelectParam(select),
-    trash: trash === 'true',
+    select,
+    trash,
     where: where!,
   })
 

packages/payload/src/collections/endpoints/deleteByID.ts

@@ -4,26 +4,22 @@ import type { PayloadHandler } from '../../config/types.js'
 
 import { getRequestCollectionWithID } from '../../utilities/getRequestEntity.js'
 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 { parseParams } from '../../utilities/parseParams/index.js'
 import { deleteByIDOperation } from '../operations/deleteByID.js'
 
 export const deleteByIDHandler: PayloadHandler = async (req) => {
   const { id, collection } = getRequestCollectionWithID(req)
-  const { searchParams } = req
-  const depth = searchParams.get('depth')
-  const overrideLock = searchParams.get('overrideLock')
-  const trash = searchParams.get('trash') === 'true'
+
+  const { depth, overrideLock, populate, select, trash } = parseParams(req.query)
 
   const doc = await deleteByIDOperation({
     id,
     collection,
-    depth: isNumber(depth) ? depth : undefined,
-    overrideLock: Boolean(overrideLock === 'true'),
-    populate: sanitizePopulateParam(req.query.populate),
+    depth,
+    overrideLock: overrideLock ?? false,
+    populate,
     req,
-    select: sanitizeSelectParam(req.query.select),
+    select,
     trash,
   })
 

packages/payload/src/collections/endpoints/docAccess.ts

@@ -8,6 +8,7 @@ import { docAccessOperation } from '../operations/docAccess.js'
 
 export const docAccessHandler: PayloadHandler = async (req) => {
   const { id, collection } = getRequestCollectionWithID(req, { optionalID: true })
+
   const result = await docAccessOperation({
     id,
     collection,

packages/payload/src/collections/endpoints/duplicate.ts

@@ -5,30 +5,23 @@ import type { PayloadHandler } from '../../config/types.js'
 
 import { getRequestCollectionWithID } from '../../utilities/getRequestEntity.js'
 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 { parseParams } from '../../utilities/parseParams/index.js'
 import { duplicateOperation } from '../operations/duplicate.js'
 
 export const duplicateHandler: PayloadHandler = async (req) => {
   const { id, collection } = getRequestCollectionWithID(req)
-  const { depth, draft, populate, select, selectedLocales } = req.query as {
-    depth?: string
-    draft?: string
-    populate?: Record<string, unknown>
-    select?: Record<string, unknown>
-    selectedLocales?: string[]
-  }
+
+  const { depth, draft, populate, select, selectedLocales } = parseParams(req.query)
 
   const doc = await duplicateOperation({
     id,
     collection,
     data: req.data,
-    depth: isNumber(depth) ? Number(depth) : undefined,
-    draft: draft === 'true',
-    populate: sanitizePopulateParam(populate),
+    depth,
+    draft,
+    populate,
     req,
-    select: sanitizeSelectParam(select),
+    select,
     selectedLocales,
   })
 

packages/payload/src/collections/endpoints/find.ts

@@ -1,47 +1,31 @@
 import { status as httpStatus } from 'http-status'
 
 import type { PayloadHandler } from '../../config/types.js'
-import type { Where } from '../../types/index.js'
-import type { JoinParams } from '../../utilities/sanitizeJoinParams.js'
 
 import { getRequestCollection } from '../../utilities/getRequestEntity.js'
 import { headersWithCors } from '../../utilities/headersWithCors.js'
-import { isNumber } from '../../utilities/isNumber.js'
-import { sanitizeJoinParams } from '../../utilities/sanitizeJoinParams.js'
-import { sanitizePopulateParam } from '../../utilities/sanitizePopulateParam.js'
-import { sanitizeSelectParam } from '../../utilities/sanitizeSelectParam.js'
+import { parseParams } from '../../utilities/parseParams/index.js'
 import { findOperation } from '../operations/find.js'
 
 export const findHandler: PayloadHandler = async (req) => {
   const collection = getRequestCollection(req)
+
   const { depth, draft, joins, limit, page, pagination, populate, select, sort, trash, where } =
-    req.query as {
-      depth?: string
-      draft?: string
-      joins?: JoinParams
-      limit?: string
-      page?: string
-      pagination?: string
-      populate?: Record<string, unknown>
-      select?: Record<string, unknown>
-      sort?: string
-      trash?: string
-      where?: Where
-    }
+    parseParams(req.query)
 
   const result = await findOperation({
     collection,
-    depth: isNumber(depth) ? Number(depth) : undefined,
-    draft: draft === 'true',
-    joins: sanitizeJoinParams(joins),
-    limit: isNumber(limit) ? Number(limit) : undefined,
-    page: isNumber(page) ? Number(page) : undefined,
-    pagination: pagination === 'false' ? false : undefined,
-    populate: sanitizePopulateParam(populate),
+    depth,
+    draft,
+    joins,
+    limit,
+    page,
+    pagination,
+    populate,
     req,
-    select: sanitizeSelectParam(select),
-    sort: typeof sort === 'string' ? sort.split(',') : undefined,
-    trash: trash === 'true',
+    select,
+    sort,
+    trash,
     where,
   })
 

packages/payload/src/collections/endpoints/findByID.ts

@@ -4,39 +4,29 @@ import type { PayloadHandler } from '../../config/types.js'
 
 import { getRequestCollectionWithID } from '../../utilities/getRequestEntity.js'
 import { headersWithCors } from '../../utilities/headersWithCors.js'
-import { isNumber } from '../../utilities/isNumber.js'
-import { type JoinParams, sanitizeJoinParams } from '../../utilities/sanitizeJoinParams.js'
-import { sanitizePopulateParam } from '../../utilities/sanitizePopulateParam.js'
-import { sanitizeSelectParam } from '../../utilities/sanitizeSelectParam.js'
+import { parseParams } from '../../utilities/parseParams/index.js'
 import { findByIDOperation } from '../operations/findByID.js'
 
 export const findByIDHandler: PayloadHandler = async (req) => {
-  const { data, searchParams } = req
+  const { data: dataArg } = req
   const { id, collection } = getRequestCollectionWithID(req)
-  const depth = data ? data.depth : searchParams.get('depth')
-  const trash = data ? data.trash : searchParams.get('trash') === 'true'
-  const flattenLocales = data
-    ? data.flattenLocales
-    : searchParams.has('flattenLocales')
-      ? searchParams.get('flattenLocales') === 'true'
-      : // flattenLocales should be undefined if not provided, so that the default (true) is applied in the operation
-        undefined
+
+  const { data, depth, draft, flattenLocales, joins, populate, select, trash } = parseParams({
+    ...req.query,
+    ...dataArg,
+  })
 
   const result = await findByIDOperation({
     id,
     collection,
-    data: data
-      ? data?.data
-      : searchParams.get('data')
-        ? JSON.parse(searchParams.get('data') as string)
-        : undefined,
-    depth: isNumber(depth) ? Number(depth) : undefined,
-    draft: data ? data.draft : searchParams.get('draft') === 'true',
+    data,
+    depth,
+    draft,
     flattenLocales,
-    joins: sanitizeJoinParams(req.query.joins as JoinParams),
-    populate: sanitizePopulateParam(req.query.populate),
+    joins,
+    populate,
     req,
-    select: sanitizeSelectParam(req.query.select),
+    select,
     trash,
   })
 

packages/payload/src/collections/endpoints/findDistinct.ts

@@ -1,40 +1,31 @@
 import { status as httpStatus } from 'http-status'
 
 import type { PayloadHandler } from '../../config/types.js'
-import type { Where } from '../../types/index.js'
 
 import { APIError } from '../../errors/APIError.js'
 import { getRequestCollection } from '../../utilities/getRequestEntity.js'
 import { headersWithCors } from '../../utilities/headersWithCors.js'
-import { isNumber } from '../../utilities/isNumber.js'
+import { parseParams } from '../../utilities/parseParams/index.js'
 import { findDistinctOperation } from '../operations/findDistinct.js'
 
 export const findDistinctHandler: PayloadHandler = async (req) => {
   const collection = getRequestCollection(req)
-  const { depth, field, limit, page, sort, trash, where } = req.query as {
-    depth?: string
-    field?: string
-    limit?: string
-    page?: string
-    sort?: string
-    sortOrder?: string
-    trash?: string
-    where?: Where
-  }
+
+  const { depth, field, limit, page, sort, trash, where } = parseParams(req.query)
 
   if (!field) {
     throw new APIError('field must be specified', httpStatus.BAD_REQUEST)
   }
 
   const result = await findDistinctOperation({
     collection,
-    depth: isNumber(depth) ? Number(depth) : undefined,
+    depth,
     field,
-    limit: isNumber(limit) ? Number(limit) : undefined,
-    page: isNumber(page) ? Number(page) : undefined,
+    limit,
+    page,
     req,
-    sort: typeof sort === 'string' ? sort.split(',') : undefined,
-    trash: trash === 'true',
+    sort,
+    trash,
     where,
   })
 

packages/payload/src/collections/endpoints/findVersionByID.ts

@@ -4,25 +4,21 @@ import type { PayloadHandler } from '../../config/types.js'
 
 import { getRequestCollectionWithID } from '../../utilities/getRequestEntity.js'
 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 { parseParams } from '../../utilities/parseParams/index.js'
 import { findVersionByIDOperation } from '../operations/findVersionByID.js'
 
 export const findVersionByIDHandler: PayloadHandler = async (req) => {
-  const { searchParams } = req
-  const depth = searchParams.get('depth')
-  const trash = searchParams.get('trash') === 'true'
+  const { depth, populate, select, trash } = parseParams(req.query)
 
   const { id, collection } = getRequestCollectionWithID(req)
 
   const result = await findVersionByIDOperation({
     id,
     collection,
-    depth: isNumber(depth) ? Number(depth) : undefined,
-    populate: sanitizePopulateParam(req.query.populate),
+    depth,
+    populate,
     req,
-    select: sanitizeSelectParam(req.query.select),
+    select,
     trash,
   })