feat(db-*): support atomic array $push db updates

[AlessioGr]

This PR adds atomic $push support for array fields. It makes it possible to safely append new items to arrays, which is especially useful when running tasks in parallel (like job queues) where multiple processes might update the same record at the same time. By handling pushes atomically, we avoid race conditions and keep data consistent - especially on postgres, where the current implementation would nuke the entire array table before re-inserting every single array item.

The feature works for both localized and unlocalized arrays, and supports pushing either single or multiple items at once.

This PR is a requirement for reliably running parallel tasks in the job queue - see #13452.

Alongside documenting $push, this PR also adds documentation for $inc.

Changes to updatedAt behavior

#13335 allows us to override the updatedAt property instead of the db always setting it to the current date.

However, we are not able to skip updating the updatedAt property completely. This means, usage of $push results in 2 postgres db calls:

1. set updatedAt in main row
2. append array row in arrays table

This PR changes the behavior to only automatically set updatedAt if it's undefined. If you explicitly set it to null, this now allows you to skip the db adapter automatically setting updatedAt.

Note

I would like to note that this does differ from the behavior of other fields being set to null.

For other fields, setting them to null will cause the database to think we want to set it to null. In this PR, we created an exception for the updatedAt field, where setting it to null will simply skip it from the db update, neither setting it to the current date (this would be the behavior if it was undefined) nor setting it to null in the db.

The alternative to this would be adding a new property like disableTimestampUpdates, but that would be more code to maintain and less simple.

=> This allows us to use $push in just one single db call

Usage Examples

Pushing a single item to an array

const post = (await payload.db.updateOne({
  data: {
    array: {
      $push: {
        text: 'some text 2',
        id: new mongoose.Types.ObjectId().toHexString(),
      },
    },
  },
  collection: 'posts',
  id: post.id,
}))

Pushing a single item to a localized array

const post = (await payload.db.updateOne({
  data: {
    arrayLocalized: {
      $push: {
        en: {
          text: 'some text 2',
          id: new mongoose.Types.ObjectId().toHexString(),
        },
        es: {
          text: 'some text 2 es',
          id: new mongoose.Types.ObjectId().toHexString(),
        },
      },
    },
  },
  collection: 'posts',
  id: post.id,
}))

Pushing multiple items to an array

const post = (await payload.db.updateOne({
  data: {
    array: {
      $push: [
        {
          text: 'some text 2',
          id: new mongoose.Types.ObjectId().toHexString(),
        },
        {
          text: 'some text 3',
          id: new mongoose.Types.ObjectId().toHexString(),
        },
      ],
    },
  },
  collection: 'posts',
  id: post.id,
}))

Pushing multiple items to a localized array

const post = (await payload.db.updateOne({
  data: {
    arrayLocalized: {
      $push: {
        en: {
          text: 'some text 2',
          id: new mongoose.Types.ObjectId().toHexString(),
        },
        es: [
          {
            text: 'some text 2 es',
            id: new mongoose.Types.ObjectId().toHexString(),
          },
          {
            text: 'some text 3 es',
            id: new mongoose.Types.ObjectId().toHexString(),
          },
        ],
      },
    },
  },
  collection: 'posts',
  id: post.id,
}))

---

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

[github-actions]

📦 esbuild Bundle Analysis for payload

This analysis was generated by esbuild-bundle-analyzer. 🤖
This PR introduced no changes to the esbuild bundle! 🙌

[jmikrut]

we should chat about this one with @DanRibbens

[github-actions]

🚀 This is included in version v3.54.0