@byline/core 4.19.0 → 5.1.0

package/dist/services/document-lifecycle/update.d.ts

@@ -10,10 +10,12 @@ import type { DocumentLifecycleContext } from './context.js';
 export interface UpdateDocumentResult {
     documentId: string;
     documentVersionId: string;
+    revision: number;
 }
 export interface UpdateDocumentWithPatchesResult {
     documentId: string;
     documentVersionId: string;
+    revision: number;
 }
 /**
  * Update a document via full replacement (PUT semantics).
@@ -28,8 +30,9 @@ export interface UpdateDocumentWithPatchesResult {
  *   4. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
  *   5. `hooks.afterUpdate({ data, originalData, collectionPath, documentId, documentVersionId })`
  */
-export declare function updateDocument(ctx: DocumentLifecycleContext, params: {
+type UpdateDocumentParams = {
     documentId: string;
+    expectedRevision: number;
     data: Record<string, any>;
     locale?: string;
     /**
@@ -46,27 +49,29 @@ export declare function updateDocument(ctx: DocumentLifecycleContext, params: {
      * available-locales sidebar widget. See docs/08-internationalization/index.md.
      */
     availableLocales?: string[];
-}): Promise<UpdateDocumentResult>;
+};
+export declare function updateDocument(ctx: DocumentLifecycleContext, params: UpdateDocumentParams): Promise<UpdateDocumentResult>;
+/** Maintenance-only replacement; status is derived from the guarded observation. */
+export declare function replaceDocumentFieldsPreservingStatus(ctx: DocumentLifecycleContext, params: Pick<UpdateDocumentParams, 'documentId' | 'data' | 'expectedRevision'>): Promise<UpdateDocumentResult>;
 /**
  * Update a document via patch application.
  *
  * Flow:
  *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
- *   2. Optimistic concurrency check on `documentVersionId`
+ *   2. Validate the observed document revision before preparation
  *   3. `applyPatches(definition, originalData, patches)` → `nextData`
  *   4. Normalize date and numeric fields
  *   5. `hooks.beforeUpdate({ data: nextData, originalData, collectionPath })`, then normalize numerics again
  *   6. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
  *   7. `hooks.afterUpdate({ data: nextData, originalData, collectionPath, documentId, documentVersionId })`
  *
- * @throws {BylineError} ERR_CONFLICT if the supplied `documentVersionId` does not match the current version.
+ * @throws {BylineError} ERR_DOCUMENT_STALE if the observed revision is stale.
  * @throws {BylineError} ERR_PATCH_FAILED if `applyPatches` fails.
  */
 export declare function updateDocumentWithPatches(ctx: DocumentLifecycleContext, params: {
     documentId: string;
+    expectedRevision: number;
     patches: DocumentPatch[];
-    /** Client-supplied version ID for optimistic concurrency. */
-    documentVersionId?: string;
     locale?: string;
     /**
      * Explicit path override (typically supplied alongside patches when
@@ -82,3 +87,6 @@ export declare function updateDocumentWithPatches(ctx: DocumentLifecycleContext,
      */
     availableLocales?: string[];
 }): Promise<UpdateDocumentWithPatchesResult>;
+/** Combined patch/content and optional metadata save, with one guarded commit. */
+export declare function saveDocument(ctx: DocumentLifecycleContext, params: Parameters<typeof updateDocumentWithPatches>[1]): Promise<import("./system-fields.js").UpdateDocumentSystemFieldsResult | UpdateDocumentWithPatchesResult>;
+export {};

package/dist/services/document-lifecycle/update.js

@@ -7,44 +7,53 @@
  */
 import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
-import { ERR_CONFLICT, ERR_NOT_FOUND, ERR_PATCH_FAILED } from '../../lib/errors.js';
+import { ERR_PATCH_FAILED, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { applyPatches } from '../../patches/index.js';
 import { normaliseDateFields } from '../../utils/normalise-dates.js';
-import { getDefaultStatus } from '../../workflow/workflow.js';
+import { getDefaultStatus, getWorkflowStatuses } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
 import { normalizeNumericFields } from '../normalize-numeric-fields.js';
 import { runCommittedDocumentHook } from './committed-hook.js';
 import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, } from './internals.js';
 import { persistExistingDocumentVersion } from './persistence.js';
+import { commitGuardedDocumentMutation, readDocumentForMutation } from './revision-guard.js';
+import { finishSystemFieldMutation, updateDocumentSystemFields, writeSystemFieldsInTransaction, } from './system-fields.js';
 import { selfHealTreePlacement } from './tree.js';
-/**
- * Update a document via full replacement (PUT semantics).
- *
- * Unlike the previous implementation, this now fetches the current version
- * from storage to provide a real `originalData` to hooks.
- *
- * Flow:
- *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
- *   2. Normalize date and numeric fields
- *   3. `hooks.beforeUpdate({ data, originalData, collectionPath })`, then normalize numerics again
- *   4. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
- *   5. `hooks.afterUpdate({ data, originalData, collectionPath, documentId, documentVersionId })`
- */
-export async function updateDocument(ctx, params) {
+export function updateDocument(ctx, params) {
+    return replaceFields(ctx, params, 'editorial');
+}
+/** Maintenance-only replacement; status is derived from the guarded observation. */
+export async function replaceDocumentFieldsPreservingStatus(ctx, params) {
+    assertActorCanPerform(ctx.requestContext, ctx.definition, 'update');
+    ctx.requestContext?.actor?.assertAbility('system.documentMaintenance');
+    return replaceFields(ctx, { ...params, locale: 'all' }, 'preserve');
+}
+function preservedStatus(ctx, status) {
+    if (status === null || !getWorkflowStatuses(ctx.definition).some((item) => item.name === status))
+        throw ERR_VALIDATION({
+            message: 'The observed status is no longer declared by this collection',
+            details: { status },
+        });
+    if (status === 'published')
+        assertActorCanPerform(ctx.requestContext, ctx.definition, 'publish');
+    return status;
+}
+async function replaceFields(ctx, params, policy) {
+    params = { ...params, availableLocales: params.availableLocales?.slice() };
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'updateDocument' }, async () => {
-        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
+        const { db, definition, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, definition, 'update');
-        const hooks = await resolveHooks(definition);
         const data = params.data;
         // Fetch the real original so hooks get accurate originalData (fixes the
         // PUT handler bug where originalData === data).
-        const latest = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
-            locale: params.locale ?? defaultLocale,
-            reconstruct: true,
-        });
+        const latest = await readDocumentForMutation(ctx, params);
+        if (policy === 'preserve')
+            preservedStatus(ctx, latest.status);
+        const hooks = await resolveHooks(definition);
+        const previousVersionId = latest.document_version_id;
+        const observedPath = latest.path;
+        const observedSourceLocale = latest.source_locale ?? defaultLocale;
         const originalData = latest ?? {};
         normaliseDateFields(data);
         normalizeNumericFields(definition.fields, data);
@@ -68,32 +77,47 @@ export async function updateDocument(ctx, params) {
         // The document's own content-locale anchor governs which save writes the
         // path row — not the mutable global default. Falls back to the global
         // default for rows predating source_locale (not yet backfilled).
-        const sourceLocale = originalData.source_locale ?? defaultLocale;
+        const sourceLocale = observedSourceLocale;
         const pathForCommand = resolvePathForUpdate({
             explicitPath,
-            currentPath: originalData.path,
+            currentPath: observedPath,
             requestLocale,
             sourceLocale,
             documentId: params.documentId,
             logger: ctx.logger,
         });
         await applyRichTextEmbed(ctx, data);
-        const result = await persistExistingDocumentVersion(ctx, {
+        const committed = await commitGuardedDocumentMutation(ctx, {
             documentId: params.documentId,
-            action: 'update',
-            documentData: data,
-            path: pathForCommand,
-            availableLocales: params.availableLocales,
-            status: defaultStatus,
+            expectedRevision: params.expectedRevision,
+            previousVersionId,
             locale: requestLocale,
-            previousVersionId: originalData.document_version_id,
-        }).catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', sourceLocale, 'update'));
+        }, async (locked) => {
+            const systemFields = await writeSystemFieldsInTransaction(ctx, params, locked);
+            const result = await persistExistingDocumentVersion(ctx, {
+                documentId: params.documentId,
+                action: 'update',
+                documentData: data,
+                path: pathForCommand,
+                status: policy === 'preserve' ? preservedStatus(ctx, locked.status) : defaultStatus,
+                locale: requestLocale,
+                previousVersionId,
+            });
+            if (policy === 'preserve' && locked.status === 'published') {
+                await db.commands.documents.archivePublishedVersions({
+                    document_id: params.documentId,
+                    excludeVersionId: extractVersionId(result.document),
+                });
+            }
+            await selfHealTreePlacement(ctx, params.documentId);
+            return { value: { result, systemFields }, changed: true };
+        }, policy === 'preserve' ? { collectionLock: 'exclusive' } : {}).catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', sourceLocale, 'update'));
+        const { result, systemFields } = committed.value;
+        const revision = committed.revision;
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
-        // Self-heal: re-root a genuinely-unplaced doc in a tree collection so any
-        // save re-trees a stray (system step, best-effort, no-op when placed).
-        await selfHealTreePlacement(ctx, documentId);
-        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId, documentVersionId }, () => invokeHook(hooks?.afterUpdate, {
+        await finishSystemFieldMutation(ctx, params, { ...systemFields, documentVersionId }, revision);
+        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId, documentVersionId, revision }, () => invokeHook(hooks?.afterUpdate, {
             data,
             originalData,
             collectionPath,
@@ -101,7 +125,7 @@ export async function updateDocument(ctx, params) {
             documentVersionId,
             path: pathForCommand ?? originalData.path,
         }));
-        return { documentId, documentVersionId };
+        return { documentId, documentVersionId, revision };
     });
 }
 /**
@@ -109,46 +133,28 @@ export async function updateDocument(ctx, params) {
  *
  * Flow:
  *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
- *   2. Optimistic concurrency check on `documentVersionId`
+ *   2. Validate the observed document revision before preparation
  *   3. `applyPatches(definition, originalData, patches)` → `nextData`
  *   4. Normalize date and numeric fields
  *   5. `hooks.beforeUpdate({ data: nextData, originalData, collectionPath })`, then normalize numerics again
  *   6. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
  *   7. `hooks.afterUpdate({ data: nextData, originalData, collectionPath, documentId, documentVersionId })`
  *
- * @throws {BylineError} ERR_CONFLICT if the supplied `documentVersionId` does not match the current version.
+ * @throws {BylineError} ERR_DOCUMENT_STALE if the observed revision is stale.
  * @throws {BylineError} ERR_PATCH_FAILED if `applyPatches` fails.
  */
 export async function updateDocumentWithPatches(ctx, params) {
+    params = { ...params, availableLocales: params.availableLocales?.slice() };
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'updateDocumentWithPatches' }, async () => {
-        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
+        const { db, definition, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, definition, 'update');
-        const hooks = await resolveHooks(definition);
         // 1. Fetch current document.
-        const latest = await db.queries.documents.getDocumentById({
-            collection_id: collectionId,
-            document_id: params.documentId,
-            locale: params.locale ?? defaultLocale,
-            reconstruct: true,
-        });
-        if (latest == null) {
-            throw ERR_NOT_FOUND({
-                message: 'document not found',
-                details: { documentId: params.documentId },
-            }).log(ctx.logger);
-        }
+        const latest = await readDocumentForMutation(ctx, params);
+        const hooks = await resolveHooks(definition);
+        const previousVersionId = latest.document_version_id;
+        const observedPath = latest.path;
+        const observedSourceLocale = latest.source_locale ?? defaultLocale;
         const originalData = latest;
-        // 2. Optimistic concurrency check.
-        if (params.documentVersionId &&
-            params.documentVersionId !== originalData.document_version_id) {
-            throw ERR_CONFLICT({
-                message: 'document has been modified since you loaded it',
-                details: {
-                    currentVersionId: originalData.document_version_id,
-                    yourVersionId: params.documentVersionId,
-                },
-            }).log(ctx.logger);
-        }
         // 3. Apply patches (patches operate on flat field data, not the full envelope).
         const { doc: patchedDocument, errors } = applyPatches(definition, originalData.fields ?? {}, params.patches);
         if (errors.length > 0) {
@@ -181,33 +187,42 @@ export async function updateDocumentWithPatches(ctx, params) {
         // The document's own content-locale anchor governs which save writes the
         // path row — not the mutable global default. Falls back to the global
         // default for rows predating source_locale (not yet backfilled).
-        const sourceLocale = originalData.source_locale ?? defaultLocale;
+        const sourceLocale = observedSourceLocale;
         const pathForCommand = resolvePathForUpdate({
             explicitPath,
-            currentPath: originalData.path,
+            currentPath: observedPath,
             requestLocale,
             sourceLocale,
             documentId: params.documentId,
             logger: ctx.logger,
         });
         await applyRichTextEmbed(ctx, nextData);
-        const result = await persistExistingDocumentVersion(ctx, {
+        const committed = await commitGuardedDocumentMutation(ctx, {
             documentId: params.documentId,
-            action: 'update',
-            documentData: nextData,
-            path: pathForCommand,
-            availableLocales: params.availableLocales,
-            status: defaultStatus,
+            expectedRevision: params.expectedRevision,
+            previousVersionId,
             locale: requestLocale,
-            previousVersionId: originalData.document_version_id,
+        }, async (locked) => {
+            const systemFields = await writeSystemFieldsInTransaction(ctx, params, locked);
+            const result = await persistExistingDocumentVersion(ctx, {
+                documentId: params.documentId,
+                action: 'update',
+                documentData: nextData,
+                path: pathForCommand,
+                status: defaultStatus,
+                locale: requestLocale,
+                previousVersionId,
+            });
+            await selfHealTreePlacement(ctx, params.documentId);
+            return { value: { result, systemFields }, changed: true };
         }).catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', sourceLocale, 'update'));
+        const { result, systemFields } = committed.value;
+        const revision = committed.revision;
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
-        // Self-heal: re-root a genuinely-unplaced doc in a tree collection so any
-        // save re-trees a stray (system step, best-effort, no-op when placed).
-        await selfHealTreePlacement(ctx, documentId);
         // 7. afterUpdate hook.
-        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId, documentVersionId }, () => invokeHook(hooks?.afterUpdate, {
+        await finishSystemFieldMutation(ctx, params, { ...systemFields, documentVersionId }, revision);
+        await runCommittedDocumentHook(ctx, { phase: 'afterUpdate', documentId, documentVersionId, revision }, () => invokeHook(hooks?.afterUpdate, {
             data: nextData,
             originalData,
             collectionPath,
@@ -215,6 +230,12 @@ export async function updateDocumentWithPatches(ctx, params) {
             documentVersionId,
             path: pathForCommand ?? originalData.path,
         }));
-        return { documentId, documentVersionId };
+        return { documentId, documentVersionId, revision };
     });
 }
+/** Combined patch/content and optional metadata save, with one guarded commit. */
+export async function saveDocument(ctx, params) {
+    if (params.patches.length === 0)
+        return updateDocumentSystemFields(ctx, params);
+    return updateDocumentWithPatches(ctx, params);
+}