feat: add $push and $remove atomic operations to localAPI update for hasMany relationship fields

[tak-amboss]

What?

This PR adds atomic update operations ($push and $remove) to Local API update functions for relationship fields configured with hasMany: true. The operations work for both single-document updates (updateById) and multi-document updates. It is related to #13891, which introduced atomic operations at the database adapter layer.

New API:

// Single document: apply atomic operations by ID
await payload.update({
  collection: 'posts',
  id: '507f1f77bcf86cd799439011',
  data: {},
  operations: {
    $push: { categories: ['featured'] },
  },
})

// Multiple documents: apply atomic operations to all matches
await payload.update({
  collection: 'posts',
  where: { status: { equals: 'published' } },
  data: {},
  operations: {
    $remove: { categories: ['outdated'] },
  },
})

Why?

Right now, updating relationship arrays generally means replacing the whole array. That forces clients to first fetch the existing document, merge changes locally, and then send everything back. Atomic operations let clients express intent directly (e.g., “add this category” or “remove that relation”) without shuttling full arrays back and forth.

How?

LocalAPI update got a new operations property where atomic operations for hasMany: true relationship fields can be submitted. Atomic operations are resolved in updateById / update internally before collection- and field-level hooks are executed so existing hooks and validations are not affected by this change.

Implementation Notes:

• Local API only. REST and GraphQL support will be added separately.
• $push and $remove for relationship fields only. Similar operations such as $inc might be added later.
• Handles localized and nested fields
• Validates field conflicts between data and operations

Considerations

This change proposes introducing a dedicated operations property to carry atomic updates such as $remove, $push, and $inc. Keeping these mutation operators separate from data preserves the existing semantics of data as pure payload and avoids breaking changes - especially hook implementations - that currently assume data contains only field data. From a typing perspective, operations can be described with a focused, well-scoped type that models update operators without altering the shape of data.

An obvious alternative would be to allow these operators directly within data. While superficially simpler, that approach risks breaking existing hooks that are not prepared to receive operator syntax mixed with collection data. It would also force a significant expansion in type complexity: we’d need recursive types that permit operators at every nesting level, which would likely cascade into type errors for downstream implementations and reduce overall readability. For these reasons, the proposal favors a new operations field, keeping backward compatibility intact and making both validation and type definitions more tractable.

[r1tsuu]

Can we avoid deep copying when it's not needed? Same in other files.

[tak-amboss]

That's actually not new but just changed the position, see https://github.com/payloadcms/payload/pull/13997/files/09ba82957240505900d3ffbe2c7f62a958d6e5d4#diff-3ccb2a85d05878478da5e00ca525dbb2113206db098d4ec5a1f5618b82eec9f0L249

I assumed it is there for a reason, so I kept it.

[r1tsuu]

I might be wrong, but it doesn't seem like this function actually uses DB atomic operations which are processed here

payload/packages/db-mongodb/src/updateOne.ts

Lines 57 to 71 in 89ab526

	const $inc: Record<string, number> = {}
	const $push: Record<string, { $each: any[] } | any> = {}
	const $addToSet: Record<string, { $each: any[] } | any> = {}
	const $pull: Record<string, { $in: any[] } | any> = {}
	transform({
	$addToSet,
	$inc,
	$pull,
	$push,
	adapter: this,
	data,
	fields,
	operation: 'write',
	})

and it just merges the new item into the existing data, right? If yes, the performance of using payload.update({ data: { hasManyRelationship: [...prev, new] }}) and payload.update({ data: {}, $push: { hasManyRelationship: new }) should be the same here. To actually benefit from this functionallity I think we need to rely on DB atomic operations

[tak-amboss]

You are right that it doesn't use the atomic operations on a database level. I don't think it is feasible to use the database operations here directly because this way we would skip all hooks and other field-level operations and introduce breaking changes once someone wants to start using atomic operations. That's why I avoided that.

Nevertheless it has significant benefits:

1. On LocalAPI level it allows you to use atomic operations without considering any side effects (such as skipped hooks, dependencies to other fields, etc.).
2. To achieve the same via the local API in the current setup, you would need to fetch the data, change the data, and save it. With the new atomic operations we can shortcut this.
3. As a next step, we can bring this to REST and GraphQL APIs. This will eventually allow us to utilize them in the admin UI, e.g. on the bulk edit UI to allow adding / removing items from hasMany relationship fields which is currently impossible to achieve.

I agree on the performance aspect, but that's not the primary motivation here. If there is later on a way to also improve the performance, that'd certainly great, but the current way enables already a whole bunch of things which are IMO totally worth it.

Does that make sense to you?