Merge pull request #208 from payloadcms/feat/maxdepth-field-property

feat: adds maxDepth to relationships and upload fields

Author: jmikrut

demo/collections/RelationshipA.ts

@@ -41,6 +41,14 @@ const RelationshipA: PayloadCollectionConfig = {
       localized: true,
       hasMany: false,
     },
+    {
+      name: 'postMaxDepth',
+      maxDepth: 0,
+      label: 'Post With MaxDepth',
+      type: 'relationship',
+      relationTo: 'relationship-b',
+      hasMany: false,
+    },
   ],
   timestamps: true,
 };

docs/fields/relationship.mdx

@@ -23,6 +23,7 @@ keywords: relationship, fields, config, configuration, documentation, Content Ma
 | **`name`** *         | To be used as the property name when stored and retrieved from the database.  |
 | **`*relationTo`** *  | Provide one or many collection `slug`s to be able to assign relationships to. |
 | **`hasMany`**        | Boolean when, if set to `true`, allows this field to have many relations instead of only one. |
+| **`maxDepth`**       | Sets a number limit on iterations of related documents to populate when queried. [Depth](/docs/getting-started/concepts#depth) |
 | **`label`**          | Used as a field label in the Admin panel and to name the generated GraphQL type. |
 | **`unique`**         | Enforce that each entry in the Collection has a unique value for this field. |
 | **`validate`**       | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |

docs/fields/upload.mdx

@@ -27,6 +27,7 @@ keywords: upload, images media, fields, config, configuration, documentation, Co
 | ---------------- | ----------- |
 | **`name`** *         | To be used as the property name when stored and retrieved from the database.  |
 | **`*relationTo`** *  | Provide a single collection `slug` to allow this field to accept a relation to. <strong>Note: the related collection must be configured to support Uploads.</strong> |
+| **`maxDepth`**       | Sets a number limit on iterations of related documents to populate when queried. [Depth](/docs/getting-started/concepts#depth) |
 | **`label`**          | Used as a field label in the Admin panel and to name the generated GraphQL type. |
 | **`unique`**         | Enforce that each entry in the Collection has a unique value for this field. |
 | **`validate`**       | Provide a custom validation function that will be executed on both the Admin panel and the backend. [More](/docs/fields/overview#validation) |

docs/getting-started/concepts.mdx

@@ -69,7 +69,7 @@ For more, visit the [Access Control documentation](/docs/access-control/overview
 </Banner>
 
 You can specify population `depth` via query parameter in the REST API and by an option in the local API. *Depth has no effect in the GraphQL API, because there, depth is based on the shape of your queries.*
-
+It is also possible to limit the depth for specific `relation` and `upload` fields using the `maxDepth` property in your configuration.
 **For example, let's look the following Collections:** `departments`, `users`, `posts`
 
 ```

src/collections/tests/relationships.spec.js

@@ -58,6 +58,7 @@ describe('Collections - REST', () => {
       const updateA = await fetch(`${url}/api/relationship-a/${createAData.doc.id}`, {
         body: JSON.stringify({
           post: documentB.id,
+          postMaxDepth: documentB.id,
         }),
         headers,
         method: 'put',
@@ -90,5 +91,17 @@ describe('Collections - REST', () => {
       expect(nested).not.toHaveProperty('post');
       expect(nested).toBe(documentA.id);
     });
+
+    it('should respect max depth at the field level', async () => {
+      const response = await fetch(`${url}/api/relationship-a?depth=1`, {
+        headers,
+        method: 'get',
+      });
+      const data = await response.json();
+      const [doc] = data.docs;
+      // asserts postMaxDepth is not populated
+      expect(doc.postMaxDepth).toBe(documentB.id);
+      expect(doc.postMaxDepth).not.toHaveProperty('post');
+    });
   });
 });

src/fields/config/schema.ts

@@ -171,6 +171,7 @@ export const upload = baseField.keys({
   type: joi.string().valid('upload').required(),
   relationTo: joi.string().required(),
   name: joi.string().required(),
+  maxDepth: joi.number(),
 });
 
 export const checkbox = baseField.keys({
@@ -187,6 +188,7 @@ export const relationship = baseField.keys({
     joi.array().items(joi.string()),
   ),
   name: joi.string().required(),
+  maxDepth: joi.number(),
 });
 
 export const blocks = baseField.keys({

src/fields/config/types.ts

@@ -141,6 +141,7 @@ export type RowField = FieldBase & {
 export type UploadField = FieldBase & {
   type: 'upload';
   relationTo: string;
+  maxDepth?: number;
 }
 
 type CodeAdmin = Admin & {
@@ -164,6 +165,7 @@ export type RelationshipField = FieldBase & {
   type: 'relationship';
   relationTo: string | string[];
   hasMany?: boolean;
+  maxDepth?: number;
 }
 
 type RichTextPlugin = (editor: Editor) => Editor;
@@ -259,6 +261,10 @@ export type FieldWithMany =
   SelectField
   | RelationshipField
 
+export type FieldWithMaxDepth =
+  UploadField
+  | RelationshipField
+
 export function fieldHasSubFields(field: Field): field is FieldWithSubFields {
   return (field.type === 'group' || field.type === 'array' || field.type === 'row');
 }
@@ -287,4 +293,8 @@ export function fieldSupportsMany(field: Field): field is FieldWithMany {
   return field.type === 'select' || field.type === 'relationship';
 }
 
+export function fieldHasMaxDepth(field: Field): field is FieldWithMaxDepth {
+  return (field.type === 'upload' || field.type === 'relationship') && typeof field.maxDepth === 'number';
+}
+
 export type HookName = 'beforeChange' | 'beforeValidate' | 'afterChange' | 'afterRead';

src/fields/relationshipPopulationPromise.ts

@@ -1,6 +1,6 @@
 import { PayloadRequest } from '../express/types';
 import executeAccess from '../auth/executeAccess';
-import { Field, RelationshipField, fieldSupportsMany } from './config/types';
+import { Field, RelationshipField, fieldSupportsMany, fieldHasMaxDepth } from './config/types';
 import { Payload } from '..';
 
 type PopulateArgs = {
@@ -95,6 +95,7 @@ const relationshipPopulationPromise = ({
   payload,
 }: PromiseArgs) => async (): Promise<void> => {
   const resultingData = data;
+  const populateDepth = fieldHasMaxDepth(field) && field.maxDepth < depth ? field.maxDepth : depth;
 
   if (fieldSupportsMany(field) && field.hasMany && Array.isArray(data[field.name])) {
     const rowPromises = [];
@@ -103,7 +104,7 @@ const relationshipPopulationPromise = ({
       const rowPromise = async () => {
         if (relatedDoc) {
           await populate({
-            depth,
+            depth: populateDepth,
             currentDepth,
             req,
             overrideAccess,
@@ -122,7 +123,7 @@ const relationshipPopulationPromise = ({
     await Promise.all(rowPromises);
   } else if (data[field.name]) {
     await populate({
-      depth,
+      depth: populateDepth,
       currentDepth,
       req,
       overrideAccess,