feat: adds keepAfterRead to plugin-relationship-objectid (#7388)

## Description

Duplicate of
payloadcms/plugin-relationship-object-ids#6 for
3.x

Author: jmikrut

packages/plugin-relationship-object-ids/README.md

@@ -8,6 +8,8 @@ Minimum required version of Payload: `1.9.5`
 
 It injects a `beforeChange` field hook into each `relationship` and `upload` field, which converts string-based IDs to `ObjectID`s immediately prior to storage.
 
+By default, it also injects an `afterRead` field hook into the above fields, which ensures that the values are re-formatted back to strings after having been read from the database.
+
 #### Usage
 
 Simply import and install the plugin to make it work:
@@ -20,7 +22,11 @@ export default buildConfig({
   // your config here
   plugins: [
     // Call the plugin within your `plugins` array
-    relationshipsAsObjectID(),
+    relationshipsAsObjectID({
+      // Optionally keep relationship values as ObjectID
+      // when they are retrieved from the database.
+      keepAfterRead: true,
+    }),
   ],
 })
 ```

packages/plugin-relationship-object-ids/src/hooks/afterRead.ts

@@ -0,0 +1,101 @@
+import type { CollectionConfig, Config, FieldHook, RelationshipField, UploadField } from 'payload'
+
+import mongoose from 'mongoose'
+import { fieldAffectsData } from 'payload/shared'
+
+const convertValue = ({
+  relatedCollection,
+  value,
+}: {
+  relatedCollection: CollectionConfig
+  value: number | string
+}): mongoose.Types.ObjectId | number | string => {
+  const customIDField = relatedCollection.fields.find(
+    (field) => fieldAffectsData(field) && field.name === 'id',
+  )
+
+  if (!customIDField && mongoose.Types.ObjectId.isValid(value)) {
+    return value.toString()
+  }
+
+  return value
+}
+
+interface RelationObject {
+  relationTo: string
+  value: number | string
+}
+
+function isValidRelationObject(value: unknown): value is RelationObject {
+  return typeof value === 'object' && value !== null && 'relationTo' in value && 'value' in value
+}
+
+interface Args {
+  config: Config
+  field: RelationshipField | UploadField
+}
+
+export const getAfterReadHook =
+  ({ config, field }: Args): FieldHook =>
+  ({ value }) => {
+    let relatedCollection: CollectionConfig | undefined
+
+    const hasManyRelations = typeof field.relationTo !== 'string'
+
+    if (!hasManyRelations) {
+      relatedCollection = config.collections?.find(({ slug }) => slug === field.relationTo)
+    }
+
+    if (Array.isArray(value)) {
+      return value.map((val) => {
+        // Handle has many
+        if (relatedCollection && val) {
+          return convertValue({
+            relatedCollection,
+            value: val,
+          })
+        }
+
+        // Handle has many - polymorphic
+        if (isValidRelationObject(val)) {
+          const relatedCollectionForSingleValue = config.collections?.find(
+            ({ slug }) => slug === val.relationTo,
+          )
+
+          if (relatedCollectionForSingleValue) {
+            return {
+              relationTo: val.relationTo,
+              value: convertValue({
+                relatedCollection: relatedCollectionForSingleValue,
+                value: val.value,
+              }),
+            }
+          }
+        }
+
+        return val
+      })
+    }
+
+    // Handle has one - polymorphic
+    if (isValidRelationObject(value)) {
+      relatedCollection = config.collections?.find(({ slug }) => slug === value.relationTo)
+
+      if (relatedCollection) {
+        return {
+          relationTo: value.relationTo,
+          value: convertValue({ relatedCollection, value: value.value }),
+        }
+      }
+    }
+
+    // Handle has one
+    if (relatedCollection && value) {
+      return convertValue({
+        relatedCollection,
+        value,
+      })
+    }
+
+    return value
+  }

packages/plugin-relationship-object-ids/src/index.ts

@@ -1,14 +1,28 @@
-import type { Config, Field } from 'payload'
+import type { Config, Field, FieldHook } from 'payload'
 
+import { getAfterReadHook } from './hooks/afterRead.js'
 import { getBeforeChangeHook } from './hooks/beforeChange.js'
 
-const traverseFields = ({ config, fields }: { config: Config; fields: Field[] }): Field[] => {
+interface TraverseFieldsArgs {
+  config: Config
+  fields: Field[]
+  keepAfterRead: boolean
+}
+
+const traverseFields = ({ config, fields, keepAfterRead }: TraverseFieldsArgs): Field[] => {
   return fields.map((field) => {
     if (field.type === 'relationship' || field.type === 'upload') {
+      const afterRead: FieldHook[] = [...(field.hooks?.afterRead || [])]
+
+      if (!keepAfterRead) {
+        afterRead.unshift(getAfterReadHook({ config, field }))
+      }
+
       return {
         ...field,
         hooks: {
           ...(field.hooks || {}),
+          afterRead,
           beforeChange: [
             ...(field.hooks?.beforeChange || []),
             getBeforeChangeHook({ config, field }),
@@ -20,7 +34,7 @@ const traverseFields = ({ config, fields }: { config: Config; fields: Field[] })
     if ('fields' in field) {
       return {
         ...field,
-        fields: traverseFields({ config, fields: field.fields }),
+        fields: traverseFields({ config, fields: field.fields, keepAfterRead }),
       }
     }
 
@@ -30,7 +44,7 @@ const traverseFields = ({ config, fields }: { config: Config; fields: Field[] })
         tabs: field.tabs.map((tab) => {
           return {
             ...tab,
-            fields: traverseFields({ config, fields: tab.fields }),
+            fields: traverseFields({ config, fields: tab.fields, keepAfterRead }),
           }
         }),
       }
@@ -42,7 +56,7 @@ const traverseFields = ({ config, fields }: { config: Config; fields: Field[] })
         blocks: field.blocks.map((block) => {
           return {
             ...block,
-            fields: traverseFields({ config, fields: block.fields }),
+            fields: traverseFields({ config, fields: block.fields, keepAfterRead }),
           }
         }),
       }
@@ -52,9 +66,19 @@ const traverseFields = ({ config, fields }: { config: Config; fields: Field[] })
   })
 }
 
+interface Args {
+  /*
+    If you want to keep ObjectIDs as ObjectIDs after read, you can enable this flag.
+    By default, all relationship ObjectIDs are stringified within the AfterRead hook.
+  */
+  keepAfterRead?: boolean
+}
+
 export const relationshipsAsObjectID =
-  (/** Possible args in the future */) =>
+  (args?: Args) =>
   (config: Config): Config => {
+    const keepAfterRead = typeof args?.keepAfterRead === 'boolean' ? args.keepAfterRead : false
+
     return {
       ...config,
       collections: (config.collections || []).map((collection) => {
@@ -63,6 +87,7 @@ export const relationshipsAsObjectID =
           fields: traverseFields({
             config,
             fields: collection.fields,
+            keepAfterRead,
           }),
         }
       }),
@@ -72,6 +97,7 @@ export const relationshipsAsObjectID =
           fields: traverseFields({
             config,
             fields: global.fields,
+            keepAfterRead,
           }),
         }
       }),