Add operation/utility to delete a draft version

[jhb-dev]

Hi, I am currently implementing a custom content approval view that lists all draft versions of documents which are not yet published, including actions to review, discard, and publish individual versions.

While working on this, I noticed that there is no built-in operation or utility to delete a specific version while also ensuring that the latest tag is correctly reassigned in the database for collections with drafts enabled.

Below is the approach I came up with. I would appreciate feedback on whether this aligns with existing patterns or if there is a preferred way to handle this internally. If this is something the team would find useful, I would be happy to contribute it to the codebase.

/**
 * Deletes a specific version of a document from a collection.
 *
 * Payload's `db.deleteVersions` does not handle `latest` cleanup for collections with drafts enabled.
 * This function ensures the `latest` flag is reassigned to the most recent remaining version of the same document.
 * Both operations run inside a transaction to keep versions consistent.
 */
export async function deleteVersion(
  collectionSlug: CollectionSlug,
  versionId: string,
  parentId: string,
  req: PayloadRequest,
): Promise<{
  success: boolean
  error?: string
}> {
  if (!req.user) {
    return { success: false, error: 'Unauthorized' }
  }

  if (req.user.collection !== 'users' || !req.user.roles?.includes('editor')) {
    return { success: false, error: 'Unauthorized' }
  }

  try {
    await initTransaction(req)

    await req.payload.db.deleteVersions({
      collection: collectionSlug,
      req,
      where: {
        id: { equals: versionId },
      },
    })

    const collectionConfig = req.payload.collections[collectionSlug].config
    const hasDraftsEnabled =
      typeof collectionConfig.versions === 'object' && collectionConfig.versions.drafts

    // For collections with drafts enabled, reassign the `latest` flag if we
    // deleted the version that held it. This ensures Payload's
    // `getLatestCollectionVersion` resolves the correct version.
    if (hasDraftsEnabled) {
      const newestVersionResult = await req.payload.db.findVersions({
        collection: collectionSlug,
        req,
        where: { parent: { equals: parentId } },
        sort: '-updatedAt',
        limit: 1,
        pagination: false,
      })

      const newestVersion = newestVersionResult.docs[0]
      if (newestVersion && !newestVersion.latest) {
        await req.payload.db.updateVersion({
          id: newestVersion.id,
          collection: collectionSlug,
          req,
          returning: false,
          versionData: {
            ...newestVersion, // the newestVersion object is just passed to satisfy the type, theoretically, just passing latest: true is enough
            latest: true, // <- this is the important part
          },
        })
      }
    }

    await commitTransaction(req)

    return { success: true }
  } catch (error) {
    await killTransaction(req)

    return {
      success: false,
      error: error instanceof Error ? error.message : 'Failed to delete version',
    }
  }
}