feat!: remove deprecated jobs queue depth and runHooks options (#16414)

**BREAKING:** The deprecated `jobs.depth` and `jobs.runHooks` config
options have been removed. Job operations now always use direct database
calls with depth `0`. If you relied on either option, remove it from
your `jobs` config; if you depended on collection hooks running for
jobs, migrate that logic out of hooks.

The `jobsCollectionOverrides` warning that detected extra hooks and
prompted users to set `runHooks` has also been removed.

---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1214349495376496

Author: AlessioGr

packages/payload/src/config/sanitize.ts

@@ -411,21 +411,6 @@ export const sanitizeConfig = async (incomingConfig: Config): Promise<SanitizedC
       defaultJobsCollection = config.jobs.jobsCollectionOverrides({
         defaultJobsCollection,
       })
-
-      const hooks = defaultJobsCollection?.hooks
-      // @todo - delete this check in 4.0
-      if (hooks && config?.jobs?.runHooks !== true) {
-        for (const [hookKey, hook] of Object.entries(hooks)) {
-          const defaultAmount = hookKey === 'afterRead' || hookKey === 'beforeChange' ? 1 : 0
-          if (hook.length > defaultAmount) {
-            // eslint-disable-next-line no-console
-            console.warn(
-              `The jobsCollectionOverrides function is returning a collection with an additional ${hookKey} hook defined. These hooks will not run unless the jobs.runHooks option is set to true. Setting this option to true will negatively impact performance.`,
-            )
-            break
-          }
-        }
-      }
     }
     const sanitizedJobsCollection = await sanitizeCollection(
       config as unknown as Config,

packages/payload/src/queues/config/types/index.ts

@@ -135,17 +135,6 @@ export type JobsConfig = {
    * Determine whether or not to delete a job after it has successfully completed.
    */
   deleteJobOnComplete?: boolean
-  /**
-   * Specify depth for retrieving jobs from the queue.
-   * This should be as low as possible in order for job retrieval
-   * to be as efficient as possible. Setting it to anything higher than
-   * 0 will drastically affect performance, as less efficient database
-   * queries will be used.
-   *
-   * @default 0
-   * @deprecated - this will be removed in 4.0
-   */
-  depth?: number
   /**
    * Enable concurrency controls for workflows and tasks.
    * When enabled, adds a `concurrencyKey` field to the jobs collection schema.
@@ -179,16 +168,6 @@ export type JobsConfig = {
         }
       }
     | Sort
-  /**
-   * By default, the job system uses direct database calls for optimal performance.
-   * If you added custom hooks to your jobs collection, you can set this to true to
-   * use the standard Payload API for all job operations. This is discouraged, as it will
-   * drastically affect performance.
-   *
-   * @default false
-   * @deprecated - this will be removed in 4.0
-   */
-  runHooks?: boolean
   /**
    * A function that will be executed before Payload picks up jobs which are configured by the `jobs.autorun` function.
    * If this function returns true, jobs will be queried and picked up. If it returns false, jobs will not be run.

packages/payload/src/queues/localAPI.ts

@@ -193,32 +193,17 @@ export const getJobsLocalAPI = (payload: Payload) => ({
 
         // If supersedes is enabled, delete older pending jobs with the same key
         if (supersedes) {
-          if (payload.config.jobs.runHooks) {
-            await payload.delete({
-              collection: jobsCollectionSlug,
-              depth: 0,
-              disableTransaction: true,
-              where: {
-                and: [
-                  { concurrencyKey: { equals: concurrencyKey } },
-                  { processing: { equals: false } },
-                  { completedAt: { exists: false } },
-                ],
-              },
-            })
-          } else {
-            await payload.db.deleteMany({
-              collection: jobsCollectionSlug,
-              req,
-              where: {
-                and: [
-                  { concurrencyKey: { equals: concurrencyKey } },
-                  { processing: { equals: false } },
-                  { completedAt: { exists: false } },
-                ],
-              },
-            })
-          }
+          await payload.db.deleteMany({
+            collection: jobsCollectionSlug,
+            req,
+            where: {
+              and: [
+                { concurrencyKey: { equals: concurrencyKey } },
+                { processing: { equals: false } },
+                { completedAt: { exists: false } },
+              ],
+            },
+          })
         }
       }
     }
@@ -227,24 +212,14 @@ export const getJobsLocalAPI = (payload: Payload) => ({
       ? Job<TTaskOrWorkflowSlug>
       : RunningJobFromTask<TTaskOrWorkflowSlug> // Type assertion is still needed here
 
-    if (payload?.config?.jobs?.depth || payload?.config?.jobs?.runHooks) {
-      return (await payload.create({
+    return jobAfterRead({
+      config: payload.config,
+      doc: await payload.db.create({
         collection: jobsCollectionSlug,
         data,
-        depth: payload.config.jobs.depth ?? 0,
-        overrideAccess,
         req,
-      })) as ReturnType
-    } else {
-      return jobAfterRead({
-        config: payload.config,
-        doc: await payload.db.create({
-          collection: jobsCollectionSlug,
-          data,
-          req,
-        }),
-      }) as unknown as ReturnType
-    }
+      }),
+    }) as unknown as ReturnType
   },
 
   run: async (args?: {
@@ -406,8 +381,6 @@ export const getJobsLocalAPI = (payload: Payload) => ({
         processing: false,
         waitUntil: null,
       },
-      depth: 0, // No depth, since we're not returning
-      disableTransaction: true,
       req,
       returning: false,
       where: { and },
@@ -452,8 +425,6 @@ export const getJobsLocalAPI = (payload: Payload) => ({
         processing: false,
         waitUntil: null,
       },
-      depth: 0, // No depth, since we're not returning
-      disableTransaction: true,
       req,
       returning: false,
     })

packages/payload/src/queues/operations/runJobs/index.ts

@@ -204,8 +204,6 @@ export const runJobs = async (args: RunJobsArgs): Promise<RunJobsResult> => {
       data: {
         processing: true,
       },
-      depth: jobsConfig.depth,
-      disableTransaction: true,
       req,
       returning: true,
     })
@@ -237,8 +235,6 @@ export const runJobs = async (args: RunJobsArgs): Promise<RunJobsResult> => {
       data: {
         processing: true,
       },
-      depth: jobsConfig.depth,
-      disableTransaction: true,
       limit,
       req,
       returning: true,
@@ -285,7 +281,6 @@ export const runJobs = async (args: RunJobsArgs): Promise<RunJobsResult> => {
       const releaseIds = jobsToRelease.map((job) => job.id)
       await updateJobs({
         data: { processing: false },
-        disableTransaction: true,
         req,
         returning: false,
         where: { id: { in: releaseIds } },
@@ -449,8 +444,6 @@ export const runJobs = async (args: RunJobsArgs): Promise<RunJobsResult> => {
               processing: false,
               waitUntil: null,
             },
-            depth: 0,
-            disableTransaction: true,
             req,
             returning: false,
           })
@@ -485,19 +478,10 @@ export const runJobs = async (args: RunJobsArgs): Promise<RunJobsResult> => {
 
   if (jobsConfig.deleteJobOnComplete && successfullyCompletedJobs.length) {
     try {
-      if (jobsConfig.runHooks) {
-        await payload.delete({
-          collection: jobsCollectionSlug,
-          depth: 0, // can be 0 since we're not returning anything
-          disableTransaction: true,
-          where: { id: { in: successfullyCompletedJobs } },
-        })
-      } else {
-        await payload.db.deleteMany({
-          collection: jobsCollectionSlug,
-          where: { id: { in: successfullyCompletedJobs } },
-        })
-      }
+      await payload.db.deleteMany({
+        collection: jobsCollectionSlug,
+        where: { id: { in: successfullyCompletedJobs } },
+      })
     } catch (err) {
       if (!silent || (typeof silent === 'object' && !silent.error)) {
         payload.logger.error({

packages/payload/src/queues/operations/runJobs/runJob/getUpdateJobFunction.ts

@@ -16,8 +16,6 @@ export function getUpdateJobFunction(job: Job, req: PayloadRequest): UpdateJobFu
     const updatedJob = await updateJob({
       id: job.id,
       data: jobData,
-      depth: req.payload.config.jobs.depth,
-      disableTransaction: true,
       req,
     })
 

packages/payload/src/queues/utilities/updateJob.ts

@@ -1,15 +1,12 @@
-import type { ManyOptions } from '../../collections/operations/local/update.js'
 import type { UpdateJobsArgs } from '../../database/types.js'
 import type { Job } from '../../index.js'
 import type { PayloadRequest, Sort, Where } from '../../types/index.js'
 
-import { jobAfterRead, jobsCollectionSlug } from '../config/collection.js'
+import { jobAfterRead } from '../config/collection.js'
 import { getCurrentDate } from './getCurrentDate.js'
 
 type BaseArgs = {
   data: Partial<Job>
-  depth?: number
-  disableTransaction?: boolean
   limit?: number
   req: PayloadRequest
   returning?: boolean
@@ -49,8 +46,6 @@ export async function updateJob(args: ArgsByID & BaseArgs) {
 export async function updateJobs({
   id,
   data,
-  depth,
-  disableTransaction,
   limit: limitArg,
   req,
   returning,
@@ -60,23 +55,6 @@ export async function updateJobs({
   const limit = id ? 1 : limitArg
   const where = id ? { id: { equals: id } } : whereArg
 
-  if (depth || req.payload.config?.jobs?.runHooks) {
-    const result = await req.payload.update({
-      id,
-      collection: jobsCollectionSlug,
-      data,
-      depth,
-      disableTransaction,
-      limit,
-      req,
-      where,
-    } as ManyOptions<any, any>)
-    if (returning === false || !result) {
-      return null
-    }
-    return result.docs as Job[]
-  }
-
   const jobReq = {
     transactionID:
       req.payload.db.name !== 'mongoose'

test/queues/int.spec.ts

@@ -14,8 +14,8 @@ import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from
 
 import type { NextRESTClient } from '../__helpers/shared/NextRESTClient.js'
 
-import { devUser } from '../credentials.js'
 import { initPayloadInt } from '../__helpers/shared/initPayloadInt.js'
+import { devUser } from '../credentials.js'
 import { clearAndSeedEverything } from './seed.js'
 import { waitUntilAutorunIsDone } from './utilities.js'