feat(db-*): add customID arg to db.create (#15653)

This PR adds `customID` argument to `payload.db.create` which can be
used to ensure that a document is created with the provided ID, for
example:
```ts
payload.db.create({ collection: 'posts', customID: 'ce98d6c4-c3ab-45de-9dfc-bf33d94cc941', data: { } })
```
This does not require to have a custom ID field in `posts` collection,
as the following:
```ts
payload.db.create({ collection: 'posts', data: { customID: 'ce98d6c4-c3ab-45de-9dfc-bf33d94cc941' } })
```
Can be used only when you define a custom ID field

Author: r1tsuu

packages/db-mongodb/src/create.ts

@@ -11,7 +11,7 @@ import { transform } from './utilities/transform.js'
 
 export const create: Create = async function create(
   this: MongooseAdapter,
-  { collection: collectionSlug, data, req, returning },
+  { collection: collectionSlug, customID, data, req, returning },
 ) {
   const { collectionConfig, customIDType, Model } = getCollection({ adapter: this, collectionSlug })
 
@@ -30,6 +30,12 @@ export const create: Create = async function create(
 
   if (customIDType) {
     data._id = data.id
+  } else if (customID) {
+    if (Types.ObjectId.isValid(customID)) {
+      data._id = new Types.ObjectId(customID)
+    } else {
+      data._id = customID
+    }
   } else if (this.allowIDOnCreate && data.id) {
     try {
       data._id = new Types.ObjectId(data.id as string)

packages/drizzle/src/create.ts

@@ -9,7 +9,7 @@ import { getTransaction } from './utilities/getTransaction.js'
 
 export const create: Create = async function create(
   this: DrizzleAdapter,
-  { collection: collectionSlug, data, req, returning, select },
+  { collection: collectionSlug, customID, data, req, returning, select },
 ) {
   const collection = this.payload.collections[collectionSlug].config
 
@@ -20,6 +20,7 @@ export const create: Create = async function create(
   const result = await upsertRow({
     adapter: this,
     collectionSlug,
+    customID,
     data,
     db,
     fields: collection.flattenedFields,

packages/drizzle/src/upsertRow/index.ts

@@ -44,6 +44,7 @@ export const upsertRow = async <T extends Record<string, unknown> | TypeWithID>(
   // TODO:
   // When we support joins for write operations (create/update) - pass collectionSlug to the buildFindManyArgs
   // Make a new argument in upsertRow.ts and pass the slug from every operation.
+  customID,
   joinQuery: _joinQuery,
   operation,
   path = '',
@@ -196,6 +197,10 @@ export const upsertRow = async <T extends Record<string, unknown> | TypeWithID>(
     tableName,
   })
 
+  if (customID) {
+    rowToInsert.row.id = customID
+  }
+
   // First, we insert the main row
   try {
     if (operation === 'update') {

packages/drizzle/src/upsertRow/types.ts

@@ -28,6 +28,7 @@ type BaseArgs = {
 }
 
 type CreateArgs = {
+  customID?: number | string
   id?: never
   joinQuery?: never
   operation: 'create'
@@ -37,6 +38,7 @@ type CreateArgs = {
 } & BaseArgs
 
 type UpdateArgs = {
+  customID?: never
   id?: number | string
   joinQuery?: JoinQuery
   operation: 'update'

packages/payload/src/database/types.ts

@@ -507,6 +507,7 @@ export type UpdateVersion = <T extends JsonObject = JsonObject>(
 
 export type CreateArgs = {
   collection: CollectionSlug
+  customID?: number | string
   data: Record<string, unknown>
   draft?: boolean
   locale?: string

test/database/int.spec.ts

@@ -1,3 +1,4 @@
+/* eslint-disable vitest/no-conditional-expect */
 import type { MongooseAdapter } from '@payloadcms/db-mongodb'
 import type { PostgresAdapter } from '@payloadcms/db-postgres'
 import type { Table } from 'drizzle-orm'
@@ -604,14 +605,17 @@ describe('database', () => {
       expect(updatedDocWithTimestamps.updatedAt).toBeUndefined()
     }
 
+    // eslint-disable-next-line vitest/expect-expect
     it('ensure timestamps are not created in update or create when timestamps are disabled', async () => {
       await noTimestampsTestLocalAPI()
     })
 
+    // eslint-disable-next-line vitest/expect-expect
     it('ensure timestamps are not created in db adapter update or create when timestamps are disabled', async () => {
       await noTimestampsTestDB(true)
     })
 
+    // eslint-disable-next-line vitest/expect-expect
     it(
       'ensure timestamps are not created in update or create when timestamps are disabled even with allowAdditionalKeys true',
       { db: 'mongo' },
@@ -623,6 +627,7 @@ describe('database', () => {
       },
     )
 
+    // eslint-disable-next-line vitest/expect-expect
     it(
       'ensure timestamps are not created in db adapter update or create when timestamps are disabled even with allowAdditionalKeys true',
       { db: 'mongo' },
@@ -4206,6 +4211,32 @@ describe('database', () => {
     }
   })
 
+  it('should allow creating docs with payload.db.create with custom ID', async () => {
+    if (payload.db.name === 'mongoose') {
+      const customId = new mongoose.Types.ObjectId().toHexString()
+      const res = await payload.db.create({
+        collection: 'simple',
+        customID: customId,
+        data: {
+          text: 'Test with custom ID',
+        },
+      })
+
+      expect(res.id).toBe(customId)
+    } else {
+      const id = payload.db.defaultIDType === 'text' ? randomUUID() : 95231
+      const res = await payload.db.create({
+        collection: 'simple',
+        customID: id,
+        data: {
+          text: 'Test with custom ID',
+        },
+      })
+
+      expect(res.id).toBe(id)
+    }
+  })
+
   it('should allow to query like by ID with draft: true', async () => {
     const category = await payload.create({
       collection: 'categories',