chore: merges

.github/workflows/pr-title.yml

@@ -52,7 +52,6 @@ jobs:
             plugin-form-builder
             plugin-nested-docs
             plugin-redirects
-            plugin-relationship-object-ids
             plugin-search
             plugin-sentry
             plugin-seo

.vscode/launch.json

@@ -118,6 +118,13 @@
       "request": "launch",
       "type": "node-terminal"
     },
+    {
+      "command": "node --no-deprecation test/dev.js locked-documents",
+      "cwd": "${workspaceFolder}",
+      "name": "Run Dev Locked Documents",
+      "request": "launch",
+      "type": "node-terminal"
+    },
     {
       "command": "node --no-deprecation test/dev.js uploads",
       "cwd": "${workspaceFolder}",

docs/configuration/collections.mdx

@@ -65,12 +65,13 @@ The following options are available:
 | **`custom`**           | Extension point for adding custom data (e.g. for plugins)                                                                          |
 | **`disableDuplicate`** | When true, do not show the "Duplicate" button while editing documents within this Collection and prevent `duplicate` from all APIs.                                                                                      |
 | **`defaultSort`**      | Pass a top-level field to sort by default in the Collection List View. Prefix the name of the field with a minus symbol ("-") to sort in descending order.                                                               |
-| **`dbName`**      | Custom table or Collection name depending on the Database Adapter. Auto-generated from slug if not defined. |
+| **`dbName`**           | Custom table or Collection name depending on the Database Adapter. Auto-generated from slug if not defined. |
 | **`endpoints`**        | Add custom routes to the REST API. Set to `false` to disable routes. [More details](../rest-api/overview#custom-endpoints).                                                                                                    |
 | **`fields`** \*        | Array of field types that will determine the structure and functionality of the data stored within this Collection. [More details](../fields/overview). |
 | **`graphQL`**          | An object with `singularName` and `pluralName` strings used in schema generation. Auto-generated from slug if not defined. Set to `false` to disable GraphQL.                                                            |
 | **`hooks`**            | Entry point for Hooks. [More details](../hooks/overview#collection-hooks).                                                                                                         |
 | **`labels`**           | Singular and plural labels for use in identifying this Collection throughout Payload. Auto-generated from slug if not defined.                                                                                           |
+| **`lockWhenEditing`**  | Enables or disables the ability to lock documents while they are being edited. When set to `true` (default), the document is locked upon editing, preventing others from making changes until the lock is released. You can pass an object to this property to configure the `lockDuration` in seconds, which defines how long the document remains locked without user interaction. If no edits are made within the specified time (default: 300 seconds), the lock expires, allowing other users to edit or delete the document. Set to `false` to disable document locking entirely. |
 | **`slug`** \*          | Unique, URL-friendly string that will act as an identifier for this Collection.                                                                                                                                          |
 | **`timestamps`**       | Set to false to disable documents' automatically generated `createdAt` and `updatedAt` timestamps.                                                                                                                       |
 | **`typescript`**       | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined.                                                                                                                                                                                  |

docs/configuration/globals.mdx

@@ -65,21 +65,22 @@ export const Nav: GlobalConfig = {
 
 The following options are available:
 
-| Option             | Description                                                                                                                                                                                                          |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`access`**       | Provide Access Control functions to define exactly who should be able to do what with this Global. [More details](../access-control/globals).                                                                    |
-| **`admin`**        | The configuration options for the Admin Panel. [More details](../admin/globals).                                                                           |
-| **`custom`**       | Extension point for adding custom data (e.g. for plugins)                                                                                                                                                            |
-| **`dbName`**       | Custom table or collection name for this Global depending on the Database Adapter. Auto-generated from slug if not defined. |
-| **`description`**  | Text or React component to display below the Global header to give editors more information.                                                                                                                         |
-| **`endpoints`**    | Add custom routes to the REST API. [More details](../rest-api/overview#custom-endpoints).                                                                                                                                  |
-| **`fields`** \*    | Array of field types that will determine the structure and functionality of the data stored within this Global. [More details](../fields/overview). |
-| **`graphQL.name`** | Text used in schema generation. Auto-generated from slug if not defined.                                                                                                                          |
-| **`hooks`**        | Entry point for Hooks. [More details](../hooks/overview#global-hooks).  |
-| **`label`**        | Text for the name in the Admin Panel or an object with keys for each language. Auto-generated from slug if not defined.                                                                                                                                                                                      |
-| **`slug`** \*      | Unique, URL-friendly string that will act as an identifier for this Global.                                                                                                                                          |
-| **`typescript`**   | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined.    |
-| **`versions`**     | Set to true to enable default options, or configure with object properties. [More details](../versions/overview#globals-config).                                                                                           |
+| Option                | Description                                                                                                                                                                                                          |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`access`**          | Provide Access Control functions to define exactly who should be able to do what with this Global. [More details](../access-control/globals).                                                                    |
+| **`admin`**           | The configuration options for the Admin Panel. [More details](../admin/globals).                                                                           |
+| **`custom`**          | Extension point for adding custom data (e.g. for plugins)                                                                                                                                                            |
+| **`dbName`**          | Custom table or collection name for this Global depending on the Database Adapter. Auto-generated from slug if not defined. |
+| **`description`**     | Text or React component to display below the Global header to give editors more information.                                                                                                                         |
+| **`endpoints`**       | Add custom routes to the REST API. [More details](../rest-api/overview#custom-endpoints).                                                                                                                                  |
+| **`fields`** \*       | Array of field types that will determine the structure and functionality of the data stored within this Global. [More details](../fields/overview). |
+| **`graphQL.name`**    | Text used in schema generation. Auto-generated from slug if not defined.                                                                                                                          |
+| **`hooks`**           | Entry point for Hooks. [More details](../hooks/overview#global-hooks).  |
+| **`label`**           | Text for the name in the Admin Panel or an object with keys for each language. Auto-generated from slug if not defined.                                                                                                                                                                                      |
+| **`lockWhenEditing`** | Enables or disables the ability to lock documents while they are being edited. When set to `true` (default), the document is locked upon editing, preventing others from making changes until the lock is released. You can pass an object to this property to configure the `lockDuration` in seconds, which defines how long the document remains locked without user interaction. If no edits are made within the specified time (default: 300 seconds), the lock expires, allowing other users to edit or delete the document. Set to `false` to disable document locking entirely. |
+| **`slug`** \*         | Unique, URL-friendly string that will act as an identifier for this Global.                                                                                                                                          |
+| **`typescript`**      | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined.    |
+| **`versions`**        | Set to true to enable default options, or configure with object properties. [More details](../versions/overview#globals-config).                                                                                           |
 
 _\* An asterisk denotes that a property is required._
 

docs/fields/join.mdx

@@ -0,0 +1,140 @@
+---
+title: Join Field
+label: Join
+order: 140
+desc: The Join field provides the ability to work on related documents. Learn how to use Join field, see examples and options.
+keywords: join, relationship, junction, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
+---
+
+The Join Field is used to make Relationship fields in the opposite direction. It is used to show the relationship from
+the other side. The field itself acts as a virtual field, in that no new data is stored on the collection with a Join
+field. Instead, the Admin UI surfaces the related documents for a better editing experience and is surfaced by Payload's APIs.
+
+The Join field is useful in scenarios including:
+
+- To see related `Products` on an `Order`
+- To view and edit `Posts` belonging to a `Category`
+- To work with any bi-directional relationship data
+
+For the Join field to work, you must have an existing [relationship](./relationship) field in the collection you are
+joining. This will reference the collection and path of the field of the related documents.
+To add a Relationship Field, set the `type` to `join` in your [Field Config](./overview):
+
+```ts
+import type { Field } from 'payload/types'
+
+export const MyJoinField: Field = {
+  // highlight-start
+  name: 'relatedPosts',
+  type: 'join',
+  collection: 'posts',
+  on: 'category',
+  // highlight-end
+}
+
+// relationship field in another collection:
+export const MyRelationshipField: Field = {
+  name: 'category',
+  type: 'relationship',
+  relationTo: 'categories',
+}
+```
+
+In this example, the field is defined to show the related `posts` when added to a `category` collection. The `on` property is used to
+specify the relationship field name of the field that relates to the collection document.
+
+## Config Options
+
+| Option                 | Description                                                                                                                                                                                  |
+|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **`name`** \*          | To be used as the property name when retrieved from the database. [More](/docs/fields/overview#field-names)                                                                                  |
+| **`collection`** \*    | The `slug`s having the relationship field.                                                                                                                                                   |
+| **`on`** \*            | The relationship field name of the field that relates to collection document. Use dot notation for nested paths, like 'myGroup.relationName'.                                                |
+| **`maxDepth`**         | Default is 1, Sets a maximum population depth for this field, regardless of the remaining depth when this field is reached. [Max Depth](/docs/getting-started/concepts#field-level-max-depth) |
+| **`label`**            | Text used as a field label in the Admin Panel or an object with keys for each language.                                                                                                      |
+| **`hooks`**            | Provide Field Hooks to control logic for this field. [More details](../hooks/fields).                                                                                                        |
+| **`access`**           | Provide Field Access Control to denote what users can see and do with this field's data. [More details](../access-control/fields).                                                           |
+| **`localized`**        | Enable localization for this field. Requires [localization to be enabled](/docs/configuration/localization) in the Base config.                                                              |
+| **`required`**         | Require this field to have a value.                                                                                                                                                          |
+| **`admin`**            | Admin-specific configuration.                                                                                                                                 |
+| **`custom`**           | Extension point for adding custom data (e.g. for plugins)                                                                                                                                    |
+| **`typescriptSchema`** | Override field type generation with providing a JSON schema                                                                                                                                  |
+
+_\* An asterisk denotes that a property is required._
+
+## Join Field Data
+
+When a document is returned that for a Join field is populated with related documents. The structure returned is an object with:
+
+- `docs` an array of related documents or only IDs if the depth is reached
+- `hasNextPage` a boolean indicating if there are additional documents
+
+```json
+{
+  "id": "66e3431a3f23e684075aae9c",
+  "relatedPosts": {
+    "docs": [
+      {
+        "id": "66e3431a3f23e684075aaeb9",
+        // other fields...
+        "category": "66e3431a3f23e684075aae9c",
+      },
+      // { ... }
+    ],
+    "hasNextPage": false
+  },
+  // other fields...
+}
+```
+
+## Query Options
+
+The Join Field supports custom queries to filter, sort, and limit the related documents that will be returned. In addition to the specific query options for each Join Field, you can pass `joins: false` to disable all Join Field from returning. This is useful for performance reasons when you don't need the related documents.
+
+The following query options are supported:
+
+| Property    | Description                                                  |
+|-------------|--------------------------------------------------------------|
+| **`limit`** | The maximum related documents to be returned, default is 10. |
+| **`where`** | An optional `Where` query to filter joined documents.        |
+| **`sort`**  | A string used to order related results                       |
+
+These can be applied to the local API, GraphQL, and REST API.
+
+### Local API
+
+By adding `joins` to the local API you can customize the request for each join field by the `name` of the field.
+
+```js
+const result = await db.findOne('categories', {
+  where: {
+    title: {
+      equals: 'My Category'
+    }
+  },
+  joins: {
+    relatedPosts: {
+      limit: 5,
+      where: {
+        title: {
+          equals: 'My Post'
+        }
+      },
+      sort: 'title'
+    }
+  }
+})
+```
+
+### Rest API
+
+The rest API supports the same query options as the local API. You can use the `joins` query parameter to customize the request for each join field by the `name` of the field. For example, an API call to get a document with the related posts limited to 5 and sorted by title:
+
+`/api/categories/${id}?joins[relatedPosts][limit]=5&joins[relatedPosts][sort]=title`
+
+You can specify as many `joins` parameters as needed for the same or different join fields for a single request.
+
+### GraphQL
+
+Coming soon.
+

package.json

@@ -34,7 +34,6 @@
     "build:plugin-form-builder": "turbo build --filter \"@payloadcms/plugin-form-builder\"",
     "build:plugin-nested-docs": "turbo build --filter \"@payloadcms/plugin-nested-docs\"",
     "build:plugin-redirects": "turbo build --filter \"@payloadcms/plugin-redirects\"",
-    "build:plugin-relationship-object-ids": "turbo build --filter \"@payloadcms/plugin-relationship-object-ids\"",
     "build:plugin-search": "turbo build --filter \"@payloadcms/plugin-search\"",
     "build:plugin-sentry": "turbo build --filter \"@payloadcms/plugin-sentry\"",
     "build:plugin-seo": "turbo build --filter \"@payloadcms/plugin-seo\"",

packages/db-mongodb/package.json

@@ -38,13 +38,14 @@
     "bson-objectid": "2.0.4",
     "http-status": "1.6.2",
     "mongoose": "6.12.3",
+    "mongoose-aggregate-paginate-v2": "1.0.6",
     "mongoose-paginate-v2": "1.7.22",
     "prompts": "2.4.2",
     "uuid": "10.0.0"
   },
   "devDependencies": {
     "@payloadcms/eslint-config": "workspace:*",
-    "@types/mongoose-aggregate-paginate-v2": "1.0.9",
+    "@types/mongoose-aggregate-paginate-v2": "1.0.6",
     "mongodb": "4.17.1",
     "mongodb-memory-server": "^9",
     "payload": "workspace:*"