feat: add missing disableErrors to globals and sdk operations

Author: rilrom

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({

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,

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}`)
+  }
 }

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}`)
+  }
 }

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}`)
+  }
 }

packages/sdk/src/index.ts

@@ -209,10 +209,14 @@ export class PayloadSDK<T extends PayloadGeneratedTypes = PayloadGeneratedTypes>
     return findByID(this, options, init)
   }
 
-  findGlobal<TSlug extends GlobalSlug<T>, TSelect extends SelectFromGlobalSlug<T, TSlug>>(
-    options: FindGlobalOptions<T, TSlug, TSelect>,
+  findGlobal<
+    TSlug extends GlobalSlug<T>,
+    TSelect extends SelectFromGlobalSlug<T, TSlug>,
+    TDisableErrors extends boolean,
+  >(
+    options: FindGlobalOptions<T, TSlug, TSelect, TDisableErrors>,
     init?: RequestInit,
-  ): Promise<TransformGlobalWithSelect<T, TSlug, TSelect>> {
+  ): Promise<ApplyDisableErrors<TransformGlobalWithSelect<T, TSlug, TSelect>, TDisableErrors>> {
     return findGlobal(this, options, init)
   }
 

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', () => {

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,

test/sdk/int.spec.ts

@@ -57,6 +57,17 @@ describe('@payloadcms/sdk', () => {
     await payload.delete({ collection: 'posts', where: { id: { in: ids } } })
   })
 
+  it('should execute find with disableErrors: true', async () => {
+    const result = await sdk.find({
+      collection: 'posts',
+      where: { id: { equals: 'non-existent-id' } },
+      disableErrors: true,
+    })
+
+    expect(result.docs).toHaveLength(0)
+    expect(result.totalDocs).toBe(0)
+  })
+
   it('should execute findVersions', async () => {
     const result = await sdk.findVersions({
       collection: 'posts',
@@ -93,6 +104,16 @@ describe('@payloadcms/sdk', () => {
     expect(result.id).toBe(version.id)
   })
 
+  it('should execute findVersionByID with disableErrors: true', async () => {
+    const result = await sdk.findVersionByID({
+      collection: 'posts',
+      id: 'non-existent-version-id',
+      disableErrors: true,
+    })
+
+    expect(result).toBeNull()
+  })
+
   it('should execute create', async () => {
     const result = await sdk.create({ collection: 'posts', data: { text: 'text' } })
 
@@ -113,6 +134,15 @@ describe('@payloadcms/sdk', () => {
     expect(result.totalDocs).toBe(1)
   })
 
+  it('should execute count with disableErrors: true', async () => {
+    const result = await sdk.count({
+      collection: 'posts',
+      where: { id: { equals: 'non-existent-id' } },
+      disableErrors: true,
+    })
+    expect(result.totalDocs).toBe(0)
+  })
+
   it('should execute update (by ID)', async () => {
     const result = await sdk.update({
       collection: 'posts',
@@ -195,6 +225,14 @@ describe('@payloadcms/sdk', () => {
     expect(result.text).toBe('some-global')
   })
 
+  it('should execute findGlobal with disableErrors: true', async () => {
+    const result = await sdk.findGlobal({
+      slug: 'non-existent-global',
+      disableErrors: true,
+    })
+    expect(result).toBeNull()
+  })
+
   it('should execute findGlobalVersions', async () => {
     const result = await sdk.findGlobalVersions({
       slug: 'global',
@@ -215,6 +253,16 @@ describe('@payloadcms/sdk', () => {
     expect(result.id).toBe(version.id)
   })
 
+  it('should execute findGlobalVersionByID with disableErrors: true', async () => {
+    const result = await sdk.findGlobalVersionByID({
+      id: 'non-existent-version-id',
+      slug: 'global',
+      disableErrors: true,
+    })
+
+    expect(result).toBeNull()
+  })
+
   it('should execute updateGlobal', async () => {
     const result = await sdk.updateGlobal({ slug: 'global', data: { text: 'some-updated-global' } })
     expect(result.text).toBe('some-updated-global')

test/versions/int.spec.ts

@@ -209,6 +209,16 @@ describe('Versions', () => {
         expect(version.id).toStrictEqual(versionID)
       })
 
+      it('should return null when finding non-existent version via ID with disableErrors: true', async () => {
+        const res = await payload.findVersionByID({
+          collection: autosaveCollectionSlug,
+          id: 'non-existent',
+          disableErrors: true,
+        })
+
+        expect(res).toBeNull()
+      })
+
       it('should allow a version to save locales properly', async () => {
         const englishTitle = 'Title in EN'
         const spanishTitle = 'Title in ES'
@@ -2212,6 +2222,15 @@ describe('Versions', () => {
       expect(version_1_deleted).toBeFalsy()
     })
 
+    it('should count global versions with disableErrors: true', async () => {
+      const res = await payload.countGlobalVersions({
+        global: 'draft-unlimited-global',
+        disableErrors: true,
+      })
+
+      expect(res.totalDocs).toEqual(0)
+    })
+
     it('findGlobalVersions - pagination should work correctly', async () => {
       for (let i = 0; i < 100; i++) {
         await payload.updateGlobal({ slug: 'draft-unlimited-global', data: { title: 'title' } })