@byline/host-tanstack-start 4.19.0 → 5.0.0

package/src/server-fns/collections/update.ts

@@ -1,3 +1,4 @@
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -11,22 +12,15 @@ import { createServerFn } from '@tanstack/react-start'
 import { getAdminRequestContext } from '@byline/client/server'
 import { ERR_NOT_FOUND, getLogger, getServerConfig } from '@byline/core'
 import type { DocumentPatch } from '@byline/core/patches'
-import type {
-  DocumentLifecycleContext,
-  UpdateDocumentWithPatchesResult,
-} from '@byline/core/services'
-import { updateDocumentSystemFields, updateDocumentWithPatches } from '@byline/core/services'
+import type { DocumentLifecycleContext } from '@byline/core/services'
+import { saveDocument, updateDocumentSystemFields } from '@byline/core/services'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
 import { toCommittedDocumentHookFailureResponse } from './save-outcome.js'
 
 // ---------------------------------------------------------------------------
-// Apply patches (patch-based update — creates a new immutable version)
-//
-// Document-grain system fields (`path`, `availableLocales`) are deliberately
-// NOT handled here: they are written through their own non-versioned path
-// (`updateCollectionDocumentSystemFields` below) so that editing them does not
-// mint a new version or reset workflow status. See docs/08-internationalization/index.md.
+// Save content patches and optional metadata in one guarded transaction.
+// Empty patches retain the non-versioned metadata-only behavior.
 // ---------------------------------------------------------------------------
 
 export const updateCollectionDocumentWithPatches = createServerFn({ method: 'POST' })
@@ -35,54 +29,69 @@ export const updateCollectionDocumentWithPatches = createServerFn({ method: 'POS
       collection: string
       id: string
       patches: DocumentPatch[]
-      versionId?: string
+      expectedRevision: number
+      path?: string | null
+      availableLocales?: string[]
       locale?: string
     }) => input
   )
-  .handler(async ({ data: input }) => {
-    const { collection: path, id, patches, versionId, locale } = input
-    const logger = getLogger()
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
+  .handler(
+    withDocumentMutationErrors(async ({ data: input }) => {
+      const {
+        collection: path,
+        id,
+        patches,
+        expectedRevision,
+        locale,
+        path: explicitPath,
+        availableLocales,
+      } = input
+      const logger = getLogger()
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(logger)
+      }
 
-    const serverConfig = getServerConfig()
-    const ctx: DocumentLifecycleContext = {
-      db: serverConfig.db,
-      definition: config.definition,
-      collectionId: config.collection.id,
-      collectionVersion: config.collection.version,
-      collectionPath: path,
-      logger,
-      defaultLocale: serverConfig.i18n.content.defaultLocale,
-      slugifier: serverConfig.slugifier,
-      requestContext: await getAdminRequestContext(),
-    }
+      const serverConfig = getServerConfig()
+      const ctx: DocumentLifecycleContext = {
+        db: serverConfig.db,
+        definition: config.definition,
+        collectionId: config.collection.id,
+        collectionVersion: config.collection.version,
+        collectionPath: path,
+        logger,
+        defaultLocale: serverConfig.i18n.content.defaultLocale,
+        slugifier: serverConfig.slugifier,
+        requestContext: await getAdminRequestContext(),
+      }
 
-    let result: UpdateDocumentWithPatchesResult
-    try {
-      result = await updateDocumentWithPatches(ctx, {
-        documentId: id,
-        patches,
-        documentVersionId: versionId,
-        locale: locale ?? serverConfig.i18n.content.defaultLocale,
-      })
-    } catch (error) {
-      const committedFailure = toCommittedDocumentHookFailureResponse(error)
-      if (committedFailure != null) return committedFailure
-      throw error
-    }
+      let result: Awaited<ReturnType<typeof saveDocument>>
+      try {
+        result = await saveDocument(ctx, {
+          documentId: id,
+          patches,
+          expectedRevision,
+          path: explicitPath ?? undefined,
+          availableLocales,
+          locale: locale ?? serverConfig.i18n.content.defaultLocale,
+        })
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
+      }
 
-    return {
-      status: 'ok' as const,
-      documentId: result.documentId,
-      documentVersionId: result.documentVersionId,
-    }
-  })
+      return {
+        status: 'ok' as const,
+        documentId: result.documentId,
+        ...('documentVersionId' in result ? { documentVersionId: result.documentVersionId } : {}),
+        revision: result.revision,
+      }
+    })
+  )
 
 // ---------------------------------------------------------------------------
 // System-managed, document-grain fields (path + advertised locales)
@@ -97,6 +106,7 @@ export const updateCollectionDocumentSystemFields = createServerFn({ method: 'PO
     (input: {
       collection: string
       id: string
+      expectedRevision: number
       locale?: string
       /** Path override; `null`/omitted means no path write. */
       path?: string | null
@@ -104,39 +114,53 @@ export const updateCollectionDocumentSystemFields = createServerFn({ method: 'PO
       availableLocales?: string[]
     }) => input
   )
-  .handler(async ({ data: input }) => {
-    const { collection: path, id, locale, path: explicitPath, availableLocales } = input
-    const logger = getLogger()
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(logger)
-    }
+  .handler(
+    withDocumentMutationErrors(async ({ data: input }) => {
+      const {
+        collection: path,
+        id,
+        expectedRevision,
+        locale,
+        path: explicitPath,
+        availableLocales,
+      } = input
+      const logger = getLogger()
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(logger)
+      }
 
-    const serverConfig = getServerConfig()
-    const ctx: DocumentLifecycleContext = {
-      db: serverConfig.db,
-      definition: config.definition,
-      collectionId: config.collection.id,
-      collectionVersion: config.collection.version,
-      collectionPath: path,
-      logger,
-      defaultLocale: serverConfig.i18n.content.defaultLocale,
-      slugifier: serverConfig.slugifier,
-      requestContext: await getAdminRequestContext(),
-    }
+      const serverConfig = getServerConfig()
+      const ctx: DocumentLifecycleContext = {
+        db: serverConfig.db,
+        definition: config.definition,
+        collectionId: config.collection.id,
+        collectionVersion: config.collection.version,
+        collectionPath: path,
+        logger,
+        defaultLocale: serverConfig.i18n.content.defaultLocale,
+        slugifier: serverConfig.slugifier,
+        requestContext: await getAdminRequestContext(),
+      }
 
-    await updateDocumentSystemFields(ctx, {
-      documentId: id,
-      locale: locale ?? serverConfig.i18n.content.defaultLocale,
-      path: explicitPath,
-      availableLocales,
-      // A failed after-hook happens after commit. Retrying this same admin save
-      // must re-run cache/search reconciliation when DB values are now current.
-      reconcile: true,
+      try {
+        const result = await updateDocumentSystemFields(ctx, {
+          expectedRevision,
+          documentId: id,
+          locale: locale ?? serverConfig.i18n.content.defaultLocale,
+          path: explicitPath,
+          availableLocales,
+          // Reconciliation still requires a current observation.
+          reconcile: true,
+        })
+        return { status: 'ok' as const, revision: result.revision }
+      } catch (error) {
+        const committedFailure = toCommittedDocumentHookFailureResponse(error)
+        if (committedFailure != null) return committedFailure
+        throw error
+      }
     })
-
-    return { status: 'ok' as const }
-  })
+  )

package/src/server-fns/collections/upload-singleton.test.node.ts

@@ -1,3 +1,4 @@
+import { testAdapter } from '../../../../core/src/storage/db-adapter.test-helper.js'
 /**
  * This Source Code is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -7,12 +8,7 @@
  */
 
 import { AdminAuth, createRequestContext } from '@byline/auth'
-import {
-  defineServerConfig,
-  defineSingleton,
-  type IDbAdapter,
-  type IStorageProvider,
-} from '@byline/core'
+import { defineServerConfig, defineSingleton, type IStorageProvider } from '@byline/core'
 import { defineLogger } from '@byline/core/logger'
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
 
@@ -112,7 +108,7 @@ beforeAll(() => {
   )
   defineServerConfig({
     collections: [singleton],
-    db: {} as IDbAdapter,
+    db: testAdapter(),
     storage,
     i18n: {
       admin: { defaultLocale: 'en', locales: ['en'] },

package/src/server-fns/collections/upload.ts

@@ -14,6 +14,7 @@ import { getLogger, withLogContext } from '@byline/core/logger'
 import { uploadField as coreUploadField } from '@byline/core/services'
 
 import { ensureDocumentResource } from '../../integrations/api-utils.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 
 /**
  * Result of an upload through the host transport. The legacy top-level
@@ -25,6 +26,7 @@ export interface UploadFieldResult {
   /** Present when the upload endpoint created a document (createDocument=true, the default). */
   documentId?: string
   documentVersionId?: string
+  revision?: number
   storedFile: StoredFileValue
 }
 
@@ -149,88 +151,90 @@ function resolveUploadField(
  */
 export const uploadCollectionField = createServerFn({ method: 'POST' })
   .validator(parseUploadFormData)
-  .handler(async ({ data }) => {
-    const { collectionPath, shouldCreateDocument, fieldName, file, fields } = data
-    const logger = getLogger()
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      const { collectionPath, shouldCreateDocument, fieldName, file, fields } = data
+      const logger = getLogger()
 
-    return withLogContext(
-      { domain: 'api', module: 'upload', function: 'uploadCollectionField' },
-      async () => {
-        // Upload is the one field transport shared by both document-resource
-        // kinds. The core service selects the kind-aware ability and rejects
-        // singleton document creation before hooks or storage; the admin form
-        // always requests the field-only branch (`createDocument=false`).
-        const config = await ensureDocumentResource(collectionPath)
-        if (config == null) {
-          throw ERR_NOT_FOUND(
-            {
-              message: 'Document resource not found.',
-              details: { collectionPath },
-            },
-            uploadCollectionField
-          ).log(logger)
-        }
+      return withLogContext(
+        { domain: 'api', module: 'upload', function: 'uploadCollectionField' },
+        async () => {
+          // Upload is the one field transport shared by both document-resource
+          // kinds. The core service selects the kind-aware ability and rejects
+          // singleton document creation before hooks or storage; the admin form
+          // always requests the field-only branch (`createDocument=false`).
+          const config = await ensureDocumentResource(collectionPath)
+          if (config == null) {
+            throw ERR_NOT_FOUND(
+              {
+                message: 'Document resource not found.',
+                details: { collectionPath },
+              },
+              uploadCollectionField
+            ).log(logger)
+          }
 
-        const serverConfig = getServerConfig()
-        const targetField = resolveUploadField(config.definition, collectionPath, fieldName)
-        // Per-field storage routing falls through to the site-wide default.
-        const storage = targetField.upload?.storage ?? serverConfig.storage
-        if (!storage) {
-          throw new Error(
-            `No storage provider configured for field '${targetField.name}' on collection ` +
-              `'${collectionPath}'. Set either field.upload.storage or the site-wide ` +
-              'ServerConfig.storage.'
-          )
-        }
+          const serverConfig = getServerConfig()
+          const targetField = resolveUploadField(config.definition, collectionPath, fieldName)
+          // Per-field storage routing falls through to the site-wide default.
+          const storage = targetField.upload?.storage ?? serverConfig.storage
+          if (!storage) {
+            throw new Error(
+              `No storage provider configured for field '${targetField.name}' on collection ` +
+                `'${collectionPath}'. Set either field.upload.storage or the site-wide ` +
+                'ServerConfig.storage.'
+            )
+          }
 
-        let buffer: Buffer
-        try {
-          buffer = Buffer.from(await file.arrayBuffer())
-        } catch (err: unknown) {
-          logger.error({ err, collectionPath }, 'failed to read file buffer')
-          throw new Error('Failed to read uploaded file.')
-        }
+          let buffer: Buffer
+          try {
+            buffer = Buffer.from(await file.arrayBuffer())
+          } catch (err: unknown) {
+            logger.error({ err, collectionPath }, 'failed to read file buffer')
+            throw new Error('Failed to read uploaded file.')
+          }
 
-        const ctx: FieldUploadContext = {
-          db: serverConfig.db,
-          definition: config.definition,
-          collectionId: config.collection.id,
-          collectionVersion: config.collection.version,
-          collectionPath,
-          fieldName: targetField.name,
-          storage,
-          logger,
-          defaultLocale: serverConfig.i18n.content.defaultLocale,
-          slugifier: serverConfig.slugifier,
-          filenameSlugifier: serverConfig.uploads?.filenameSlugifier,
-          requestContext: await getAdminRequestContext(),
-          imageProcessor: {
-            extractMeta: extractImageMeta,
-            isBypassMimeType,
-            generateVariants: ({ buffer, mimeType, storedFile, storage, upload, logger }) =>
-              generateImageVariants(
-                buffer,
-                mimeType,
-                storedFile,
-                storage,
-                upload.sizes ?? [],
-                logger
-              ),
-          },
-        }
+          const ctx: FieldUploadContext = {
+            db: serverConfig.db,
+            definition: config.definition,
+            collectionId: config.collection.id,
+            collectionVersion: config.collection.version,
+            collectionPath,
+            fieldName: targetField.name,
+            storage,
+            logger,
+            defaultLocale: serverConfig.i18n.content.defaultLocale,
+            slugifier: serverConfig.slugifier,
+            filenameSlugifier: serverConfig.uploads?.filenameSlugifier,
+            requestContext: await getAdminRequestContext(),
+            imageProcessor: {
+              extractMeta: extractImageMeta,
+              isBypassMimeType,
+              generateVariants: ({ buffer, mimeType, storedFile, storage, upload, logger }) =>
+                generateImageVariants(
+                  buffer,
+                  mimeType,
+                  storedFile,
+                  storage,
+                  upload.sizes ?? [],
+                  logger
+                ),
+            },
+          }
 
-        return coreUploadField(ctx, {
-          buffer,
-          originalFilename: file.name || 'upload',
-          mimeType: file.type || 'application/octet-stream',
-          fileSize: file.size,
-          fields,
-          shouldCreateDocument,
-          locale: serverConfig.i18n.content.defaultLocale,
-        })
-      }
-    )
-  })
+          return coreUploadField(ctx, {
+            buffer,
+            originalFilename: file.name || 'upload',
+            mimeType: file.type || 'application/octet-stream',
+            fileSize: file.size,
+            fields,
+            shouldCreateDocument,
+            locale: serverConfig.i18n.content.defaultLocale,
+          })
+        }
+      )
+    })
+  )
 
 /**
  * Upload a file to an upload-enabled collection.

package/src/server-fns/document-mutation-errors.ts

@@ -0,0 +1,67 @@
+import {
+  BylineError,
+  ErrorCodes,
+  getDocumentRevisionValidationDetails,
+  getDocumentStaleDetails,
+  getLockConflictDetails,
+} from '@byline/core'
+import { getDocumentHookCommittedDetails } from '@byline/core/services'
+
+import { committedTreeReceipt } from './structural-receipt.js'
+
+/** Error subclasses lose custom properties in the server-function serializer.
+ * Throw only validated plain data for document failures; never transport causes,
+ * SQL, hook messages or an unverified current revision. */
+export function documentMutationError(error: unknown): unknown {
+  const stale = getDocumentStaleDetails(error)
+  if (stale)
+    return {
+      code: ErrorCodes.DOCUMENT_STALE,
+      message: 'This document has changed. Reload before making changes.',
+      details: stale,
+    }
+  const validation = getDocumentRevisionValidationDetails(error)
+  if (validation)
+    return {
+      code: ErrorCodes.VALIDATION,
+      message: 'Reload this document before making changes.',
+      details: validation,
+    }
+  const lock = getLockConflictDetails(error)
+  if (lock)
+    return {
+      code: ErrorCodes.LOCK_CONFLICT,
+      message:
+        'This change could not be saved because another operation was using the document. Reload before trying again.',
+      details: lock,
+    }
+  const tree = committedTreeReceipt(error)
+  if (tree)
+    return {
+      code: ErrorCodes.TREE_HOOK_COMMITTED,
+      message: 'The structure was saved, but a follow-up action failed.',
+      details: tree,
+    }
+  const committed = getDocumentHookCommittedDetails(error)
+  if (committed)
+    return {
+      code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+      message: 'The document was saved, but a follow-up action failed.',
+      details: committed,
+    }
+  if (error instanceof BylineError && error.code === ErrorCodes.NOT_FOUND)
+    return { code: ErrorCodes.NOT_FOUND, message: 'This document is no longer available.' }
+  return error
+}
+
+export function withDocumentMutationErrors<T, R>(
+  handler: (input: T) => Promise<R>
+): (input: T) => Promise<R> {
+  return async (input) => {
+    try {
+      return await handler(input)
+    } catch (error) {
+      throw documentMutationError(error)
+    }
+  }
+}