@byline/host-tanstack-start 4.18.0 → 5.0.0

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

@@ -1,5 +1,14 @@
 import type { CollectionHandle, PlaceTreeNodeOptions, RemoveFromTreeOptions } from '@byline/client'
-import { ErrorCodes, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER } from '@byline/core'
+import {
+  ErrorCodes,
+  getDocumentRevisionValidationDetails,
+  getDocumentStaleDetails,
+  getLockConflictDetails,
+  TREE_HOOK_COMMITTED_MARKER,
+  TREE_PLACEMENT_STALE_MARKER,
+} from '@byline/core'
+
+import { structuralReceipt } from '../structural-receipt.js'
 
 function hasErrorCode(error: unknown, code: string): boolean {
   return (
@@ -27,11 +36,11 @@ export function isCommittedTreeHookFailure(error: unknown): boolean {
 }
 
 export type AdminTreeMoveOutcome =
-  | { status: 'ok' }
+  | { status: 'ok'; receipt?: ReturnType<typeof structuralReceipt> }
   | { status: 'suppressed' }
   | { status: 'mutation-failed'; error: unknown; refreshError?: unknown }
   | { status: 'committed-hook-failed'; error: unknown; refreshError?: unknown }
-  | { status: 'refresh-failed'; error: unknown }
+  | { status: 'refresh-failed'; error: unknown; receipt?: ReturnType<typeof structuralReceipt> }
 
 export interface AdminTreeMoveUiEffects {
   rollback: boolean
@@ -93,9 +102,17 @@ export async function executeAdminTreeMove(
   mutate: () => Promise<unknown>,
   refresh: () => Promise<unknown>
 ): Promise<AdminTreeMoveOutcome> {
+  let receipt: ReturnType<typeof structuralReceipt>
   try {
-    await mutate()
+    receipt = structuralReceipt(await mutate())
   } catch (error) {
+    if (
+      getDocumentStaleDetails(error) ||
+      getDocumentRevisionValidationDetails(error) ||
+      getLockConflictDetails(error) ||
+      hasErrorCode(error, ErrorCodes.NOT_FOUND)
+    )
+      return { status: 'mutation-failed', error }
     const status = isCommittedTreeHookFailure(error)
       ? ('committed-hook-failed' as const)
       : ('mutation-failed' as const)
@@ -109,9 +126,9 @@ export async function executeAdminTreeMove(
 
   try {
     await refresh()
-    return { status: 'ok' }
+    return { status: 'ok', ...(receipt ? { receipt } : {}) }
   } catch (error) {
-    return { status: 'refresh-failed', error }
+    return { status: 'refresh-failed', error, ...(receipt ? { receipt } : {}) }
   }
 }
 
@@ -140,24 +157,24 @@ export function createAdminTreeMoveController(): AdminTreeMoveController {
   }
 }
 
-/** Admin retries reconcile post-commit tree hooks unless explicitly disabled. */
+/** Request reconciliation for explicit caller actions; never retry or replace their revision. */
 export function placeAdminTreeNode(
   handle: Pick<CollectionHandle, 'placeTreeNode'>,
   documentId: string,
   options: PlaceTreeNodeOptions
-): Promise<{ orderKey: string }> {
+): ReturnType<CollectionHandle['placeTreeNode']> {
   return handle.placeTreeNode(documentId, {
     ...options,
     reconcile: options.reconcile ?? true,
   })
 }
 
-/** Admin retries reconcile post-commit tree hooks unless explicitly disabled. */
+/** Request reconciliation for explicit caller actions; never retry or replace their revision. */
 export function removeAdminTreeNode(
   handle: Pick<CollectionHandle, 'removeFromTree'>,
   documentId: string,
-  options: RemoveFromTreeOptions = {}
-): Promise<void> {
+  options: RemoveFromTreeOptions
+): ReturnType<CollectionHandle['removeFromTree']> {
   return handle.removeFromTree(documentId, {
     ...options,
     reconcile: options.reconcile ?? true,

package/src/server-fns/collections/tree.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
@@ -21,7 +22,7 @@ import { createReadContext, ERR_NOT_FOUND, getLogger } from '@byline/core'
 
 import { ensureCollection } from '../../integrations/api-utils.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)
@@ -30,6 +31,7 @@ import { getAdminTreeParent, getAdminUnplacedTreeDocuments } from './tree-read.j
 export const placeTreeNode = createServerFn({ method: 'POST' })
   .validator(
     (input: {
+      expectedRevision: number
       collection: string
       documentId: string
       parentDocumentId: string | null
@@ -38,45 +40,62 @@ 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,
+  .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
@@ -84,30 +103,32 @@ export const removeFromTree = createServerFn({ method: 'POST' })
 
 export const getTreeAncestors = createServerFn({ method: 'GET' })
   .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)
@@ -115,17 +136,19 @@ export const getTreeAncestors = createServerFn({ method: 'GET' })
 
 export const getTreeParent = createServerFn({ method: 'GET' })
   .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 +158,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. */
@@ -150,70 +174,74 @@ export interface CollectionTreeRow {
 
 export const getCollectionTree = createServerFn({ method: 'GET' })
   .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

@@ -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
@@ -12,17 +13,14 @@ 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 } from '@byline/core/services'
-import { updateDocumentSystemFields, updateDocumentWithPatches } 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' })
@@ -31,43 +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(),
+      }
 
-    await updateDocumentWithPatches(ctx, {
-      documentId: id,
-      patches,
-      documentVersionId: versionId,
-      locale: locale ?? serverConfig.i18n.content.defaultLocale,
-    })
+      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 }
-  })
+      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)
@@ -82,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
@@ -89,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 }
-  })
+  )