feat: add missing disableErrors to globals findOne operation (#14913)

### What?

This PR introduces the `disableErrors` option into the global `findOne`
operation.

### Why?

`disableErrors` is handy for certain flows where a user may be
unauthorised but you don't need an error to be thrown, instead you would
prefer an empty result.

Without this, the developer needs to catch the error themselves, leading
to inconsistencies as some operations have `disableErrors` and others do
not.

### How?

Introduced the `disableErrors` option to the global `findOne` operation.

### Additional information

- Initial [discord
discussion](https://discord.com/channels/967097582721572934/1102950643259424828/1438504179961430059).
- A [PR](#6357) was created to
address this in mid 2024 but was later closed.
- There is opportunity here to include `disableErrors` in a number of
operations that seem to be lacking it, especially in the `sdk` package.
Originally I included these changes in this PR but have since removed to
instead allow for some discussion before we consider introducing them in
a separate PR.
- There is opportunity to introduce better test coverage in a separate
PR for `disableErrors` across existing operations that use it.
- In `packages/payload/src/collections/operations/restoreVersion.ts`,
`disableErrors` exists in the types but is not actually implemented. I
have left this as is for now but wanted to flag it.

Author: rilrom

packages/payload/src/globals/operations/findOne.ts

@@ -28,6 +28,7 @@ export type GlobalFindOneArgs = {
    */
   data?: Record<string, unknown>
   depth?: number
+  disableErrors?: boolean
   draft?: boolean
   globalConfig: SanitizedGlobalConfig
   includeLockStatus?: boolean
@@ -45,6 +46,7 @@ export const findOneOperation = async <T extends Record<string, unknown>>(
   const {
     slug,
     depth,
+    disableErrors,
     draft: replaceWithVersion = false,
     flattenLocales,
     globalConfig,
@@ -86,11 +88,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({
@@ -125,7 +130,10 @@ export const findOneOperation = async <T extends Record<string, unknown>>(
     const hasDoc = docFromDB && Object.keys(docFromDB).length > 0
 
     if (!hasDoc && !args.data && !overrideAccess && accessResult !== true) {
-      return {} as any
+      if (!disableErrors) {
+        return {} as any
+      }
+      return null!
     }
 
     let doc = (args.data as any) ?? (hasDoc ? docFromDB : null) ?? {}

packages/payload/src/globals/operations/local/findOne.ts

@@ -40,6 +40,14 @@ type BaseFindOneOptions<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)
+   */
+  draft?: boolean
   /**
    * Specify a [fallback locale](https://payloadcms.com/docs/configuration/localization) to use for any returned documents.
    */
@@ -98,6 +106,7 @@ export async function findOneGlobalLocal<
     slug: globalSlug,
     data,
     depth,
+    disableErrors,
     draft = false,
     flattenLocales,
     includeLockStatus,
@@ -117,6 +126,7 @@ export async function findOneGlobalLocal<
     slug: globalSlug as string,
     data,
     depth,
+    disableErrors,
     draft,
     flattenLocales,
     globalConfig,

test/globals/int.spec.ts

@@ -173,6 +173,16 @@ describe('globals', () => {
       expect(es).toMatchObject(localized.es)
     })
 
+    it('should return null when user is unauthorised and using findGlobal with disableErrors: true', async () => {
+      const doc = await payload.findGlobal({
+        disableErrors: true,
+        overrideAccess: false,
+        slug: accessControlSlug,
+      })
+
+      expect(doc).toBeNull()
+    })
+
     it('should respect valid access query constraint', async () => {
       const emptyGlobal = await payload.findGlobal({
         overrideAccess: false,