@byline/host-tanstack-start 4.19.0 → 5.1.0

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

@@ -20,16 +20,20 @@ import { getAdminBylineClient } from '@byline/client/server'
 import { createReadContext, ERR_NOT_FOUND, getLogger } from '@byline/core'
 
 import { ensureCollection } from '../../integrations/api-utils.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.js'
 import { placeAdminTreeNode, removeAdminTreeNode } from './tree-mutation.js'
-import { getAdminTreeParent, getAdminUnplacedTreeDocuments } from './tree-read.js'
+import { getAdminTreeParent } from './tree-read.js'
 
 // ---------------------------------------------------------------------------
 // Place / move a node within the tree (place / reorder / re-parent)
 // ---------------------------------------------------------------------------
 
 export const placeTreeNode = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
   .validator(
     (input: {
+      expectedRevision: number
       collection: string
       documentId: string
       parentDocumentId: string | null
@@ -38,94 +42,118 @@ export const placeTreeNode = createServerFn({ method: 'POST' })
       reconcile?: boolean
     }) => input
   )
-  .handler(async ({ data }) => {
-    const { collection: path, documentId } = data
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(getLogger())
-    }
-    const handle = getAdminBylineClient().collection(path)
-    const result = await placeAdminTreeNode(handle, documentId, {
-      parentDocumentId: data.parentDocumentId,
-      beforeDocumentId: data.beforeDocumentId ?? null,
-      afterDocumentId: data.afterDocumentId ?? null,
-      reconcile: data.reconcile,
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      const { collection: path, documentId } = data
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(getLogger())
+      }
+      const handle = getAdminBylineClient().collection(path)
+      const result = await placeAdminTreeNode(handle, documentId, {
+        expectedRevision: data.expectedRevision,
+        parentDocumentId: data.parentDocumentId,
+        beforeDocumentId: data.beforeDocumentId ?? null,
+        afterDocumentId: data.afterDocumentId ?? null,
+        reconcile: data.reconcile,
+      })
+      return { status: 'ok' as const, ...result }
     })
-    return { status: 'ok' as const, orderKey: result.orderKey }
-  })
+  )
 
 // ---------------------------------------------------------------------------
 // Remove a node from the tree (back to the unplaced state)
 // ---------------------------------------------------------------------------
 
 export const removeFromTree = createServerFn({ method: 'POST' })
-  .validator((input: { collection: string; documentId: string; reconcile?: boolean }) => input)
-  .handler(async ({ data }) => {
-    const { collection: path, documentId } = data
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(getLogger())
-    }
-    await removeAdminTreeNode(getAdminBylineClient().collection(path), documentId, {
-      reconcile: data.reconcile,
+  .middleware([adminSessionMiddleware])
+  .validator(
+    (input: {
+      expectedRevision: number
+      collection: string
+      documentId: string
+      reconcile?: boolean
+    }) => input
+  )
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      const { collection: path, documentId } = data
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(getLogger())
+      }
+      const result = await removeAdminTreeNode(
+        getAdminBylineClient().collection(path),
+        documentId,
+        {
+          expectedRevision: data.expectedRevision,
+          reconcile: data.reconcile,
+        }
+      )
+      return { status: 'ok' as const, ...result }
     })
-    return { status: 'ok' as const }
-  })
+  )
 
 // ---------------------------------------------------------------------------
 // Resolve a document's ancestor chain (root-first), hydrated with titles
 // ---------------------------------------------------------------------------
 
 export const getTreeAncestors = createServerFn({ method: 'GET' })
+  .middleware([adminSessionMiddleware])
   .validator((input: { collection: string; documentId: string }) => input)
-  .handler(async ({ data }) => {
-    const { collection: path, documentId } = data
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(getLogger())
-    }
-    const useAsTitle = config.definition.useAsTitle
-    // Admin context: read with `status: 'any'` so draft ancestors still show.
-    const ancestors = await getAdminBylineClient()
-      .collection(path)
-      .getAncestors(documentId, { status: 'any' })
-    return ancestors.map((doc) => {
-      const fields = doc.fields as Record<string, any> | undefined
-      const title = useAsTitle ? fields?.[useAsTitle] : undefined
-      return {
-        id: doc.id,
-        title: typeof title === 'string' && title.length > 0 ? title : doc.path,
-        path: doc.path,
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      const { collection: path, documentId } = data
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(getLogger())
       }
+      const useAsTitle = config.definition.useAsTitle
+      // Admin context: read with `status: 'any'` so draft ancestors still show.
+      const ancestors = await getAdminBylineClient()
+        .collection(path)
+        .getAncestors(documentId, { status: 'any' })
+      return ancestors.map((doc) => {
+        const fields = doc.fields as Record<string, any> | undefined
+        const title = useAsTitle ? fields?.[useAsTitle] : undefined
+        return {
+          id: doc.id,
+          title: typeof title === 'string' && title.length > 0 ? title : doc.path,
+          path: doc.path,
+        }
+      })
     })
-  })
+  )
 
 // ---------------------------------------------------------------------------
 // Resolve a document's placement state in the tree (unplaced / root / child)
 // ---------------------------------------------------------------------------
 
 export const getTreeParent = createServerFn({ method: 'GET' })
+  .middleware([adminSessionMiddleware])
   .validator((input: { collection: string; documentId: string }) => input)
-  .handler(async ({ data }) => {
-    const { collection: path, documentId } = data
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(getLogger())
-    }
-    return getAdminTreeParent(getAdminBylineClient().collection(path), documentId)
-  })
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      const { collection: path, documentId } = data
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(getLogger())
+      }
+      return getAdminTreeParent(getAdminBylineClient().collection(path), documentId)
+    })
+  )
 
 // ---------------------------------------------------------------------------
 // Read the whole collection tree as ordered, depth-tagged rows for the built-in
@@ -135,6 +163,7 @@ export const getTreeParent = createServerFn({ method: 'GET' })
 // ---------------------------------------------------------------------------
 
 export interface CollectionTreeRow {
+  revision: number
   id: string
   /** Parent document id, or `null` for a root or unplaced node. Drives the
    * client-side tree reconstruction for drag-to-reorder / re-parent. */
@@ -149,71 +178,76 @@ export interface CollectionTreeRow {
 }
 
 export const getCollectionTree = createServerFn({ method: 'GET' })
+  .middleware([adminSessionMiddleware])
   .validator((input: { collection: string; locale?: string }) => input)
-  .handler(async ({ data }) => {
-    const { collection: path } = data
-    const config = await ensureCollection(path)
-    if (!config) {
-      throw ERR_NOT_FOUND({
-        message: 'Collection not found',
-        details: { collectionPath: path },
-      }).log(getLogger())
-    }
-    const handle = getAdminBylineClient().collection(path)
-    // Shared deliberately across the structural and unplaced reads: the
-    // beforeRead predicate cache is per-ReadContext, so sharing gives both
-    // halves one predicate snapshot — a time-dependent predicate (embargo
-    // cutoff) evaluated twice could otherwise disagree between the placed
-    // forest and the unplaced list. The request-memoized context factory
-    // keeps this sharing safe (one request authority per request).
-    const readContext = createReadContext()
-
-    const forest = await handle.getSubtree({
-      status: 'any',
-      locale: data.locale,
-      _readContext: readContext,
-    })
-    const rows: CollectionTreeRow[] = []
-    const placed = new Set<string>()
-    const walk = (nodes: typeof forest, depth: number, parentId: string | null): void => {
-      for (const node of nodes) {
-        const doc = node.document
+  .handler(
+    withDocumentMutationErrors(async ({ data }) => {
+      const { collection: path } = data
+      const config = await ensureCollection(path)
+      if (!config) {
+        throw ERR_NOT_FOUND({
+          message: 'Collection not found',
+          details: { collectionPath: path },
+        }).log(getLogger())
+      }
+      const handle = getAdminBylineClient().collection(path)
+      // Shared deliberately across the structural and unplaced reads: the
+      // beforeRead predicate cache is per-ReadContext, so sharing gives both
+      // halves one predicate snapshot — a time-dependent predicate (embargo
+      // cutoff) evaluated twice could otherwise disagree between the placed
+      // forest and the unplaced list. The request-memoized context factory
+      // keeps this sharing safe (one request authority per request).
+      const readContext = createReadContext()
+
+      const { forest, unplaced } = await handle.getTreeForEdit({
+        locale: data.locale,
+        _readContext: readContext,
+      })
+      const rows: CollectionTreeRow[] = []
+      const placed = new Set<string>()
+      const walk = (nodes: typeof forest, depth: number, parentId: string | null): void => {
+        for (const node of nodes) {
+          const doc = node.document
+          rows.push({
+            id: doc.id,
+            revision: doc.revision,
+            parentId,
+            depth,
+            unplaced: false,
+            status: doc.status,
+            path: doc.path,
+            createdAt: doc.createdAt,
+            updatedAt: doc.updatedAt,
+            fields: doc.fields as Record<string, any>,
+          })
+          placed.add(doc.id)
+          walk(node.children, depth + 1, doc.id)
+        }
+      }
+      walk(forest, 0, null)
+
+      // Surface documents not yet in the tree (e.g. freshly created) so they
+      // remain reachable. Trees are small by design, so a single wide read is fine.
+      for (const doc of unplaced) {
         rows.push({
           id: doc.id,
-          parentId,
-          depth,
-          unplaced: false,
+          revision: doc.revision,
+          parentId: null,
+          depth: 0,
+          unplaced: true,
           status: doc.status,
           path: doc.path,
           createdAt: doc.createdAt,
           updatedAt: doc.updatedAt,
           fields: doc.fields as Record<string, any>,
         })
-        placed.add(doc.id)
-        walk(node.children, depth + 1, doc.id)
       }
-    }
-    walk(forest, 0, null)
-
-    // Surface documents not yet in the tree (e.g. freshly created) so they
-    // remain reachable. Trees are small by design, so a single wide read is fine.
-    const unplaced = await getAdminUnplacedTreeDocuments(handle, placed, readContext, data.locale)
-    for (const doc of unplaced) {
-      rows.push({
-        id: doc.id,
-        parentId: null,
-        depth: 0,
-        unplaced: true,
-        status: doc.status,
-        path: doc.path,
-        createdAt: doc.createdAt,
-        updatedAt: doc.updatedAt,
-        fields: doc.fields as Record<string, any>,
-      })
-    }
 
-    return {
-      rows,
-      included: { collection: { path: config.collection.path, labels: config.definition.labels } },
-    }
-  })
+      return {
+        rows,
+        included: {
+          collection: { path: config.collection.path, labels: config.definition.labels },
+        },
+      }
+    })
+  )

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

@@ -11,78 +11,89 @@ 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 { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+import { withDocumentMutationErrors } from '../document-mutation-errors.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' })
+  .middleware([adminSessionMiddleware])
   .validator(
     (input: {
       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)
@@ -93,10 +104,12 @@ export const updateCollectionDocumentWithPatches = createServerFn({ method: 'POS
 // ---------------------------------------------------------------------------
 
 export const updateCollectionDocumentSystemFields = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
   .validator(
     (input: {
       collection: string
       id: string
+      expectedRevision: number
       locale?: string
       /** Path override; `null`/omitted means no path write. */
       path?: string | null
@@ -104,39 +117,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

@@ -7,12 +7,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'
 
@@ -25,6 +20,9 @@ vi.mock('@tanstack/react-start', () => ({
   createServerFn: () => {
     let validate = (input: unknown) => input
     const chain = {
+      middleware() {
+        return chain
+      },
       validator(validator: (input: unknown) => unknown) {
         validate = validator
         return chain
@@ -54,6 +52,11 @@ vi.mock('../../integrations/byline-core.js', () => ({
 import { ensureCollection, ensureDocumentResource } from '../../integrations/api-utils.js'
 import { uploadField } from './upload.js'
 
+// Handler-level tests isolate transport; session-middleware tests exercise the real pre-handler boundary.
+vi.mock('../../integrations/session-middleware.js', () => ({ adminSessionMiddleware: {} }))
+
+import { testAdapter } from '../../../../core/src/storage/db-adapter.test-helper.js'
+
 const SERVER_CONFIG = Symbol.for('__byline_server_config__')
 const BYLINE_LOGGER = Symbol.for('__byline_logger__')
 const previousServer = (globalThis as Record<PropertyKey, unknown>)[SERVER_CONFIG]
@@ -112,7 +115,7 @@ beforeAll(() => {
   )
   defineServerConfig({
     collections: [singleton],
-    db: {} as IDbAdapter,
+    db: testAdapter(),
     storage,
     i18n: {
       admin: { defaultLocale: 'en', locales: ['en'] },