feat: add missing disableErrors to globals and sdk operations

rilrom · rilrom · commit 21d54f0f6d59 · 2025-12-13T21:31:46.000+10:30
diff --git a/packages/payload/src/globals/operations/findOne.ts b/packages/payload/src/globals/operations/findOne.ts
@@ -25,6 +25,7 @@ export type GlobalFindOneArgs = {
    */
   data?: Record<string, unknown>
   depth?: number
+  disableErrors?: boolean
   draft?: boolean
   globalConfig: SanitizedGlobalConfig
   includeLockStatus?: boolean
@@ -42,6 +43,7 @@ export const findOneOperation = async <T extends Record<string, unknown>>(
   const {
     slug,
     depth,
+    disableErrors,
     draft: replaceWithVersion = false,
     flattenLocales,
     globalConfig,
@@ -79,11 +81,14 @@ export const findOneOperation = async <T extends Record<string, unknown>>(
     let accessResult!: AccessResult
 
     if (!overrideAccess) {
-      accessResult = await executeAccess({ req }, globalConfig.access.read)
+      accessResult = await executeAccess({ disableErrors, req }, globalConfig.access.read)
     }
 
     if (accessResult === false) {
-      throw new NotFound(req.t)
+      if (!disableErrors) {
+        throw new NotFound(req.t)
+      }
+      return null!
     }
 
     const select = sanitizeSelect({
diff --git a/packages/payload/src/globals/operations/local/findOne.ts b/packages/payload/src/globals/operations/local/findOne.ts
@@ -36,6 +36,10 @@ export type Options<TSlug extends GlobalSlug, TSelect extends SelectType> = {
    * [Control auto-population](https://payloadcms.com/docs/queries/depth) of nested relationship and upload fields.
    */
   depth?: number
+  /**
+   * When set to `true`, errors will not be thrown.
+   */
+  disableErrors?: boolean
   /**
    * Whether the document should be queried from the versions table/collection or not. [More](https://payloadcms.com/docs/versions/drafts#draft-api)
    */
@@ -97,6 +101,7 @@ export async function findOneGlobalLocal<
     slug: globalSlug,
     data,
     depth,
+    disableErrors,
     draft = false,
     flattenLocales,
     includeLockStatus,
@@ -116,6 +121,7 @@ export async function findOneGlobalLocal<
     slug: globalSlug as string,
     data,
     depth,
+    disableErrors,
     draft,
     flattenLocales,
     globalConfig,
diff --git a/packages/sdk/src/collections/count.ts b/packages/sdk/src/collections/count.ts
@@ -8,6 +8,10 @@ export type CountOptions<T extends PayloadGeneratedTypes, TSlug extends Collecti
    * the Collection slug to operate against.
    */
   collection: TSlug
+  /**
+   * When set to `true`, errors will not be thrown.
+   */
+  disableErrors?: boolean
   /**
    *  Specify [locale](https://payloadcms.com/docs/configuration/localization) for any returned documents.
    */
@@ -23,12 +27,24 @@ export async function count<T extends PayloadGeneratedTypes, TSlug extends Colle
   options: CountOptions<T, TSlug>,
   init?: RequestInit,
 ): Promise<{ totalDocs: number }> {
-  const response = await sdk.request({
-    args: options,
-    init,
-    method: 'GET',
-    path: `/${options.collection}/count`,
-  })
+  try {
+    const response = await sdk.request({
+      args: options,
+      init,
+      method: 'GET',
+      path: `/${options.collection}/count`,
+    })
+
+    if (response.ok) {
+      return response.json()
+    } else {
+      throw new Error()
+    }
+  } catch {
+    if (options.disableErrors) {
+      return { totalDocs: 0 }
+    }
 
-  return response.json()
+    throw new Error(`Error counting documents in ${options.collection}`)
+  }
 }
diff --git a/packages/sdk/src/collections/find.ts b/packages/sdk/src/collections/find.ts
@@ -23,6 +23,10 @@ export type FindOptions<
    * [Control auto-population](https://payloadcms.com/docs/queries/depth) of nested relationship and upload fields.
    */
   depth?: number
+  /**
+   * When set to `true`, errors will not be thrown.
+   */
+  disableErrors?: boolean
   /**
    * Whether the documents should be queried from the versions table/collection or not. [More](https://payloadcms.com/docs/versions/drafts#draft-api)
    */
@@ -94,12 +98,34 @@ export async function find<
   options: FindOptions<T, TSlug, TSelect>,
   init?: RequestInit,
 ): Promise<PaginatedDocs<TransformCollectionWithSelect<T, TSlug, TSelect>>> {
-  const response = await sdk.request({
-    args: options,
-    init,
-    method: 'GET',
-    path: `/${options.collection}`,
-  })
+  try {
+    const response = await sdk.request({
+      args: options,
+      init,
+      method: 'GET',
+      path: `/${options.collection}`,
+    })
+
+    if (response.ok) {
+      return response.json()
+    } else {
+      throw new Error()
+    }
+  } catch {
+    if (options.disableErrors) {
+      return {
+        docs: [],
+        hasNextPage: false,
+        hasPrevPage: false,
+        limit: 0,
+        page: 1,
+        pagingCounter: 1,
+        prevPage: null,
+        totalDocs: 0,
+        totalPages: 1,
+      }
+    }
 
-  return response.json()
+    throw new Error(`Error retrieving documents from ${options.collection}`)
+  }
 }
diff --git a/packages/sdk/src/collections/restoreVersion.ts b/packages/sdk/src/collections/restoreVersion.ts
@@ -1,3 +1,5 @@
+import type { ApplyDisableErrors } from 'payload'
+
 import type { PayloadSDK } from '../index.js'
 import type {
   CollectionSlug,
@@ -10,6 +12,7 @@ import type {
 export type RestoreVersionByIDOptions<
   T extends PayloadGeneratedTypes,
   TSlug extends CollectionSlug<T>,
+  TDisableErrors extends boolean,
 > = {
   /**
    * the Collection slug to operate against.
@@ -19,6 +22,10 @@ export type RestoreVersionByIDOptions<
    * [Control auto-population](https://payloadcms.com/docs/queries/depth) of nested relationship and upload fields.
    */
   depth?: number
+  /**
+   * When set to `true`, errors will not be thrown.
+   */
+  disableErrors?: TDisableErrors
   /**
    * Whether the document should be queried from the versions table/collection or not. [More](https://payloadcms.com/docs/versions/drafts#draft-api)
    */
@@ -44,17 +51,31 @@ export type RestoreVersionByIDOptions<
 export async function restoreVersion<
   T extends PayloadGeneratedTypes,
   TSlug extends CollectionSlug<T>,
+  TDisableErrors extends boolean,
 >(
   sdk: PayloadSDK<T>,
-  options: RestoreVersionByIDOptions<T, TSlug>,
+  options: RestoreVersionByIDOptions<T, TSlug, TDisableErrors>,
   init?: RequestInit,
-): Promise<DataFromCollectionSlug<T, TSlug>> {
-  const response = await sdk.request({
-    args: options,
-    init,
-    method: 'POST',
-    path: `/${options.collection}/versions/${options.id}`,
-  })
+): Promise<ApplyDisableErrors<DataFromCollectionSlug<T, TSlug>, TDisableErrors>> {
+  try {
+    const response = await sdk.request({
+      args: options,
+      init,
+      method: 'POST',
+      path: `/${options.collection}/versions/${options.id}`,
+    })
+
+    if (response.ok) {
+      return response.json()
+    } else {
+      throw new Error()
+    }
+  } catch {
+    if (options.disableErrors) {
+      // @ts-expect-error generic nullable
+      return null
+    }
 
-  return response.json()
+    throw new Error(`Error restoring version ${options.id} in ${options.collection}`)
+  }
 }
diff --git a/packages/sdk/src/globals/findOne.ts b/packages/sdk/src/globals/findOne.ts
@@ -1,4 +1,4 @@
-import type { SelectType } from 'payload'
+import type { ApplyDisableErrors, SelectType } from 'payload'
 
 import type { PayloadSDK } from '../index.js'
 import type {
@@ -14,11 +14,18 @@ export type FindGlobalOptions<
   T extends PayloadGeneratedTypes,
   TSlug extends GlobalSlug<T>,
   TSelect extends SelectType,
+  // TODO 4.0: place TDisableErrors above TSelect to match with other operations
+  TDisableErrors extends boolean,
 > = {
   /**
    * [Control auto-population](https://payloadcms.com/docs/queries/depth) of nested relationship and upload fields.
    */
   depth?: number
+  /**
+   * When set to `true`, errors will not be thrown.
+   * `null` will be returned instead, if the document was not found.
+   */
+  disableErrors?: TDisableErrors
   /**
    * Whether the document should be queried from the versions table/collection or not. [More](https://payloadcms.com/docs/versions/drafts#draft-api)
    */
@@ -49,17 +56,31 @@ export async function findGlobal<
   T extends PayloadGeneratedTypes,
   TSlug extends GlobalSlug<T>,
   TSelect extends SelectFromGlobalSlug<T, TSlug>,
+  TDisableErrors extends boolean = boolean,
 >(
   sdk: PayloadSDK<T>,
-  options: FindGlobalOptions<T, TSlug, TSelect>,
+  options: FindGlobalOptions<T, TSlug, TSelect, TDisableErrors>,
   init?: RequestInit,
-): Promise<TransformGlobalWithSelect<T, TSlug, TSelect>> {
-  const response = await sdk.request({
-    args: options,
-    init,
-    method: 'GET',
-    path: `/globals/${options.slug}`,
-  })
+): Promise<ApplyDisableErrors<TransformGlobalWithSelect<T, TSlug, TSelect>, TDisableErrors>> {
+  try {
+    const response = await sdk.request({
+      args: options,
+      init,
+      method: 'GET',
+      path: `/globals/${options.slug}`,
+    })
+
+    if (response.ok) {
+      return response.json()
+    } else {
+      throw new Error()
+    }
+  } catch {
+    if (options.disableErrors) {
+      // @ts-expect-error generic nullable
+      return null
+    }
 
-  return response.json()
+    throw new Error(`Error retrieving global ${options.slug}`)
+  }
 }
diff --git a/packages/sdk/src/globals/restoreVersion.ts b/packages/sdk/src/globals/restoreVersion.ts
@@ -1,4 +1,4 @@
-import type { TypeWithVersion } from 'payload'
+import type { ApplyDisableErrors, TypeWithVersion } from 'payload'
 
 import type { PayloadSDK } from '../index.js'
 import type {
@@ -12,11 +12,16 @@ import type {
 export type RestoreGlobalVersionByIDOptions<
   T extends PayloadGeneratedTypes,
   TSlug extends GlobalSlug<T>,
+  TDisableErrors extends boolean,
 > = {
   /**
    * [Control auto-population](https://payloadcms.com/docs/queries/depth) of nested relationship and upload fields.
    */
   depth?: number
+  /**
+   * When set to `true`, errors will not be thrown.
+   */
+  disableErrors?: TDisableErrors
   draft?: boolean
   /**
    * Specify a [fallback locale](https://payloadcms.com/docs/configuration/localization) to use for any returned documents.
@@ -43,19 +48,29 @@ export type RestoreGlobalVersionByIDOptions<
 export async function restoreGlobalVersion<
   T extends PayloadGeneratedTypes,
   TSlug extends GlobalSlug<T>,
+  TDisableErrors extends boolean = boolean,
 >(
   sdk: PayloadSDK<T>,
-  options: RestoreGlobalVersionByIDOptions<T, TSlug>,
+  options: RestoreGlobalVersionByIDOptions<T, TSlug, TDisableErrors>,
   init?: RequestInit,
-): Promise<TypeWithVersion<DataFromGlobalSlug<T, TSlug>>> {
-  const response = await sdk.request({
-    args: options,
-    init,
-    method: 'POST',
-    path: `/globals/${options.slug}/versions/${options.id}`,
-  })
+): Promise<ApplyDisableErrors<TypeWithVersion<DataFromGlobalSlug<T, TSlug>>, TDisableErrors>> {
+  try {
+    const response = await sdk.request({
+      args: options,
+      init,
+      method: 'POST',
+      path: `/globals/${options.slug}/versions/${options.id}`,
+    })
+
+    const { doc } = await response.json()
 
-  const { doc } = await response.json()
+    return doc
+  } catch {
+    if (options.disableErrors) {
+      // @ts-expect-error generic nullable
+      return null
+    }
 
-  return doc
+    throw new Error(`Error restoring version ${options.id} for global ${options.slug}`)
+  }
 }
diff --git a/test/collections-rest/int.spec.ts b/test/collections-rest/int.spec.ts
@@ -1754,6 +1754,19 @@ describe('collections-rest', () => {
         payload.findByID({ collection: 'posts', id, disableErrors: true }),
       ).resolves.toBeNull()
     })
+
+    it('find should support disableErrors: true', async () => {
+      const res = await payload.find({ collection: 'posts', disableErrors: true })
+
+      expect(res.docs).toHaveLength(0)
+      expect(res.totalDocs).toBe(0)
+    })
+
+    it('count should support disableErrors: true', async () => {
+      const res = await payload.count({ collection: 'posts', disableErrors: true })
+
+      expect(res.totalDocs).toEqual(0)
+    })
   })
 
   describe('Custom endpoints', () => {
diff --git a/test/globals/int.spec.ts b/test/globals/int.spec.ts
@@ -195,6 +195,15 @@ describe('globals', () => {
       expect(hasAccess.title).toBeDefined()
     })
 
+    it('should return null when finding non-existent global with disableErrors: true', async () => {
+      const doc = await payload.findGlobal({
+        slug,
+        disableErrors: true,
+      })
+
+      expect(doc).toBeNull()
+    })
+
     it('should get globals with defaultValues populated before first creation', async () => {
       const defaultValueGlobal = await payload.findGlobal({
         slug: defaultValueSlug,
diff --git a/test/sdk/int.spec.ts b/test/sdk/int.spec.ts
diff --git a/test/versions/int.spec.ts b/test/versions/int.spec.ts
