@byline/core 4.19.0 → 5.0.0

package/dist/services/field-upload.d.ts

@@ -93,6 +93,7 @@ export interface UploadFieldParams {
     locale?: string;
 }
 export interface UploadFieldResult {
+    revision?: number;
     documentId?: string;
     documentVersionId?: string;
     /**

package/dist/services/field-upload.js

@@ -10,7 +10,7 @@ import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
 import { ERR_DATABASE, ERR_STORAGE, ERR_VALIDATION } from '../lib/errors.js';
 import { withLogContext } from '../lib/logger.js';
 import { resolveUploadFilename } from '../utils/slugify-filename.js';
-import { createDocument } from './document-lifecycle/index.js';
+import { createDocument, getDocumentHookCommittedDetails, } from './document-lifecycle/index.js';
 function isMimeTypeAllowed(mimeType, allowedTypes) {
     return allowedTypes.some((allowed) => {
         if (allowed === '*/*')
@@ -339,10 +339,14 @@ export async function uploadField(ctx, params) {
             return {
                 documentId: result.documentId,
                 documentVersionId: result.documentVersionId,
+                revision: result.revision,
                 storedFile: storedFileValue,
             };
         }
         catch (err) {
+            // A committed document owns these files even when its after-hook fails.
+            if (getDocumentHookCommittedDetails(err) !== null)
+                throw err;
             logger.error({ err, collectionPath, fieldName }, 'document creation failed — rolling back storage files');
             const rollbackPaths = [storedFile.storagePath, ...variantStoragePaths];
             for (const storagePath of rollbackPaths) {

package/dist/services/field-upload.test.node.d.ts

@@ -1,8 +1 @@
-/**
- * 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
- * file, You can obtain one at http://mozilla.org/MPL/2.0/.
- *
- * Copyright (c) Infonomic Company Limited
- */
 export {};

package/dist/services/field-upload.test.node.js

@@ -1,3 +1,4 @@
+import { testAdapter } from '../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
@@ -9,6 +10,7 @@ import { AdminAuth, createRequestContext, createSuperAdminContext } from '@bylin
 import { describe, expect, it, vi } from 'vitest';
 import { commitHookAttachment, prepareHookAttachment } from '../config/attach-hooks.js';
 import { BylineError, ErrorCodes } from '../lib/errors.js';
+import { unusedRevisionStore } from '../storage/revision-store.test-helper.js';
 import { uploadField } from './field-upload.js';
 const uploadCollection = {
     path: 'media',
@@ -55,14 +57,19 @@ function createMockDb() {
         fieldCount: 2,
     });
     const db = {
+        revisions: unusedRevisionStore,
+        withReadSnapshot: async () => {
+            throw new Error('Unexpected editable snapshot in this test');
+        },
         commands: {
             collections: {
+                lockCollectionRegistration: vi.fn(async () => { }),
                 create: vi.fn(),
                 update: vi.fn(),
                 delete: vi.fn(),
             },
             documents: {
-                publishSchedules: {},
+                publishSchedules: testAdapter().commands.documents.publishSchedules,
                 createDocumentVersion,
                 updateDocumentPath: vi.fn(),
                 setDocumentAvailableLocales: vi.fn(),
@@ -104,7 +111,10 @@ function createMockDb() {
                 getCollectionById: vi.fn(),
             },
             documents: {
-                publishSchedules: {},
+                publishSchedules: testAdapter().queries.documents.publishSchedules,
+                getDocumentRevision: async () => {
+                    throw new Error('Unexpected revision read in this test');
+                },
                 getDocumentSystemFieldsForUpdate: vi.fn(async () => null),
                 getDocumentById: vi.fn(),
                 getCurrentVersionMetadata: vi.fn(),
@@ -392,6 +402,7 @@ describe('uploadField service', () => {
             shouldCreateDocument: true,
             locale: 'en',
         });
+        expect(result.revision).toBe(1);
         // beforeStore receives the rich context.
         expect(beforeStore).toHaveBeenCalledWith(expect.objectContaining({
             fieldName: 'image',
@@ -578,6 +589,31 @@ describe('uploadField service', () => {
         expect(del).not.toHaveBeenCalled();
         expect(result.storedFile.filename).toBe('hero.png');
     });
+    it('preserves uploaded files and the receipt after a committed creation hook fails', async () => {
+        const { ctx, createDocumentVersion, del, storedPaths } = buildCtx({
+            definition: {
+                ...uploadCollection,
+                hooks: {
+                    afterCreate: () => {
+                        throw new Error('index unavailable');
+                    },
+                },
+            },
+        });
+        await expect(uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: true,
+        })).rejects.toMatchObject({
+            code: ErrorCodes.DOCUMENT_HOOK_COMMITTED,
+            details: { phase: 'afterCreate', revision: 1 },
+        });
+        expect(createDocumentVersion).toHaveBeenCalledOnce();
+        expect(del).not.toHaveBeenCalled();
+        expect(storedPaths.has('media/original.png')).toBe(true);
+    });
     it('rolls back stored files when document creation fails', async () => {
         const { db } = createMockDb();
         db.commands.documents.createDocumentVersion = vi.fn().mockRejectedValue(new Error('db down'));

package/dist/services/populate.test.node.d.ts

@@ -1,8 +1 @@
-/**
- * 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
- * file, You can obtain one at http://mozilla.org/MPL/2.0/.
- *
- * Copyright (c) Infonomic Company Limited
- */
 export {};

package/dist/services/populate.test.node.js

@@ -1,3 +1,4 @@
+import { testAdapter } from '../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
@@ -8,6 +9,7 @@
 import { AdminAuth, createRequestContext } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
 import { BylineError, ErrorCodes } from '../lib/errors.js';
+import { unusedRevisionStore } from '../storage/revision-store.test-helper.js';
 import { __internal, createReadContext, populateDocuments } from './populate.js';
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -141,10 +143,21 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
         return path ? { id, path } : null;
     });
     const db = {
+        revisions: unusedRevisionStore,
+        withReadSnapshot: async () => {
+            throw new Error('Unexpected editable snapshot in this test');
+        },
         commands: {
-            collections: { create: vi.fn(), update: vi.fn(), delete: vi.fn() },
+            collections: {
+                lockCollectionRegistration: vi.fn(async () => {
+                    throw new Error('Unexpected collection lock');
+                }),
+                create: vi.fn(),
+                update: vi.fn(),
+                delete: vi.fn(),
+            },
             documents: {
-                publishSchedules: {},
+                publishSchedules: testAdapter().commands.documents.publishSchedules,
                 createDocumentVersion: vi.fn(),
                 updateDocumentPath: vi.fn(),
                 setDocumentAvailableLocales: vi.fn(),
@@ -186,7 +199,10 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 getCollectionById,
             },
             documents: {
-                publishSchedules: {},
+                publishSchedules: testAdapter().queries.documents.publishSchedules,
+                getDocumentRevision: async () => {
+                    throw new Error('Unexpected revision read in this test');
+                },
                 getDocumentSystemFieldsForUpdate: vi.fn(async () => null),
                 getDocumentById: vi.fn(),
                 getCurrentVersionMetadata: vi.fn(),

package/dist/services/richtext-populate.test.node.d.ts

@@ -1,8 +1 @@
-/**
- * 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
- * file, You can obtain one at http://mozilla.org/MPL/2.0/.
- *
- * Copyright (c) Infonomic Company Limited
- */
 export {};

package/dist/services/richtext-populate.test.node.js

@@ -1,3 +1,4 @@
+import { testAdapter } from '../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
@@ -126,12 +127,12 @@ describe('createRichTextDocumentReader', () => {
         const getCollectionByPath = vi.fn().mockResolvedValue({ id: 'media-id', path: 'media' });
         const getDocumentsByDocumentIds = vi.fn().mockResolvedValue([]);
         return {
-            db: {
+            db: testAdapter({
                 queries: {
                     collections: { getCollectionByPath },
                     documents: { getDocumentsByDocumentIds },
                 },
-            },
+            }),
             getCollectionByPath,
             getDocumentsByDocumentIds,
         };

package/dist/services/singleton-lifecycle/copy-to-locale.d.ts

@@ -8,6 +8,7 @@
 import type { DocumentLifecycleContext } from '../document-lifecycle/context.js';
 import type { SingletonSaveResult } from './internals.js';
 export interface CopySingletonToLocaleParams {
+    expectedRevision: number;
     sourceLocale: string;
     targetLocale: string;
     overwrite: boolean;

package/dist/services/singleton-lifecycle/copy-to-locale.js

@@ -14,6 +14,7 @@ import { persistExistingDocumentVersion } from '../document-lifecycle/persistenc
 import { authorizeSingletonUpdate, commitSingletonSave } from './internals.js';
 /** Copy localized singleton fields to another locale on the mapped document. */
 export async function copySingletonToLocale(ctx, params) {
+    params = { ...params };
     return withLogContext({ domain: 'services', module: 'singleton-lifecycle', function: 'copySingletonToLocale' }, async () => {
         const definition = authorizeSingletonUpdate(ctx);
         if (params.sourceLocale === params.targetLocale) {
@@ -25,7 +26,13 @@ export async function copySingletonToLocale(ctx, params) {
         return commitSingletonSave({
             ctx,
             definition,
-            operation: { type: 'copyToLocale', ...params },
+            expectedRevision: params.expectedRevision,
+            operation: {
+                type: 'copyToLocale',
+                sourceLocale: params.sourceLocale,
+                targetLocale: params.targetLocale,
+                overwrite: params.overwrite,
+            },
             prepare: async (slot) => {
                 if (slot.documentId == null || slot.currentVersion == null) {
                     throw ERR_NOT_FOUND({
@@ -82,8 +89,8 @@ export async function copySingletonToLocale(ctx, params) {
                     data: merged.data,
                     originalData,
                     locale: params.targetLocale,
+                    prepareWrite: () => applyRichTextEmbed(ctx, merged.data),
                     write: async () => {
-                        await applyRichTextEmbed(ctx, merged.data);
                         return persistExistingDocumentVersion(ctx, {
                             documentId: slot.documentId,
                             action: 'copy_to_locale',

package/dist/services/singleton-lifecycle/index.d.ts

@@ -11,4 +11,4 @@ export { restoreSingletonVersion } from './restore.js';
 export { updateSingleton } from './update.js';
 export type { CopySingletonToLocaleParams } from './copy-to-locale.js';
 export type { SingletonSaveResult } from './internals.js';
-export type { UpdateSingletonParams } from './update.js';
+export type { UpdateSingletonParams, UpdateSingletonResult } from './update.js';

package/dist/services/singleton-lifecycle/internals.d.ts

@@ -10,6 +10,7 @@ import type { DocumentLifecycleContext } from '../document-lifecycle/context.js'
 type VersionWriteResult = Awaited<ReturnType<IDocumentCommands['createDocumentVersion']>>;
 type CurrentVersionMetadata = NonNullable<Awaited<ReturnType<IDocumentQueries['getCurrentVersionMetadata']>>>;
 export interface SingletonSaveResult {
+    revision: number;
     documentId: string;
     documentVersionId: string;
 }
@@ -21,6 +22,7 @@ interface PreparedSingletonSave {
     data: Record<string, any>;
     originalData: Record<string, any> | null;
     locale: string;
+    prepareWrite: () => Promise<void>;
     write: () => Promise<VersionWriteResult>;
 }
 /**
@@ -34,15 +36,11 @@ export declare function authorizeSingletonUpdate(ctx: DocumentLifecycleContext):
  * or hooks. Client-facing callers must authorize before invoking this resolver.
  */
 export declare function resolveSingletonDocumentId(ctx: DocumentLifecycleContext): Promise<string | null>;
-/**
- * Coordinate one singleton version write under the registered-slot lock.
- * `prepare` runs after the mapping and current version have been read while
- * locked. The before hook and write remain inside the outer transaction; the
- * after hook cannot run until that transaction has committed.
- */
+/** Prepare singleton restore/copy outside locks, then commit under S → D → P. */
 export declare function commitSingletonSave(params: {
     ctx: DocumentLifecycleContext;
     definition: SingletonDefinition;
+    expectedRevision: number;
     operation: SingletonSaveOperation;
     prepare: (slot: LockedSingletonSlot) => Promise<PreparedSingletonSave>;
 }): Promise<SingletonSaveResult>;

package/dist/services/singleton-lifecycle/internals.js

@@ -7,9 +7,12 @@
  */
 import { resolveHooks } from '../../@types/index.js';
 import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
-import { DbErrorCodes, ERR_CONFLICT, ERR_VALIDATION } from '../../lib/errors.js';
+import { ERR_DOCUMENT_STALE, ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
+import { documentRevisionFromDatabase, parseDocumentRevision, } from '../../storage/document-revision.js';
 import { runCommittedDocumentHook } from '../document-lifecycle/committed-hook.js';
 import { extractDocumentId, extractVersionId } from '../document-lifecycle/internals.js';
+import { assertLifecycleTransactionOwnership, commitGuardedDocumentMutation, readDocumentForMutation, } from '../document-lifecycle/revision-guard.js';
+import { sameDocumentData } from '../document-lifecycle/same-document-data.js';
 /**
  * Assert the kind-aware singleton update ability without touching storage.
  * The runtime kind guard keeps this internal service from becoming an
@@ -32,88 +35,82 @@ export function authorizeSingletonUpdate(ctx) {
 export function resolveSingletonDocumentId(ctx) {
     return ctx.db.queries.singletons.getMappedDocumentId(ctx.collectionId);
 }
-/**
- * Coordinate one singleton version write under the registered-slot lock.
- * `prepare` runs after the mapping and current version have been read while
- * locked. The before hook and write remain inside the outer transaction; the
- * after hook cannot run until that transaction has committed.
- */
+/** Prepare singleton restore/copy outside locks, then commit under S → D → P. */
 export async function commitSingletonSave(params) {
     const { ctx, definition, operation } = params;
-    const hooks = await resolveHooks(definition);
-    const requestContext = ctx.requestContext;
-    if (requestContext == null) {
-        throw new Error('singleton authorization completed without a request context');
-    }
-    const committed = await ctx.db.withTransaction(async () => {
-        await ctx.db.commands.singletons.lockSlot(ctx.collectionId);
-        const mappedDocumentId = await resolveSingletonDocumentId(ctx);
-        const currentVersion = mappedDocumentId == null
-            ? null
-            : await ctx.db.queries.documents.getCurrentVersionMetadata({
-                collection_id: ctx.collectionId,
-                document_id: mappedDocumentId,
+    assertLifecycleTransactionOwnership(ctx);
+    const expectedRevision = parseDocumentRevision(params.expectedRevision);
+    const slot = await ctx.db.withReadSnapshot(async (queries) => {
+        const documentId = await queries.singletons.getMappedDocumentId(ctx.collectionId);
+        if (documentId === null)
+            throw ERR_NOT_FOUND({ message: 'Singleton document is unavailable' });
+        const currentVersion = await queries.documents.getCurrentVersionMetadata({
+            collection_id: ctx.collectionId,
+            document_id: documentId,
+        });
+        if (currentVersion === null)
+            throw ERR_NOT_FOUND({ message: 'Singleton document is unavailable' });
+        const currentRevision = documentRevisionFromDatabase(await queries.documents.getDocumentRevision({
+            collection_id: ctx.collectionId,
+            document_id: documentId,
+        }));
+        if (currentRevision !== expectedRevision)
+            throw ERR_DOCUMENT_STALE({
+                message: 'This singleton has changed. Reload before saving.',
+                details: { reason: 'revision_mismatch', documentId, expectedRevision, currentRevision },
             });
-        if (mappedDocumentId != null && currentVersion == null) {
-            throw ERR_CONFLICT({
-                message: `singleton '${ctx.collectionPath}' is mapped to a deleted or unavailable document; ` +
-                    'clear the mapping deliberately before rematerialising the slot',
-                details: { singletonPath: ctx.collectionPath, documentId: mappedDocumentId },
-            }).log(ctx.logger);
+        return { documentId, currentVersion };
+    });
+    const prepared = await params.prepare(slot);
+    // The operation-specific locale/history reads must still belong to this observation.
+    await readDocumentForMutation(ctx, {
+        documentId: slot.documentId,
+        expectedRevision,
+        locale: prepared.locale,
+        lenient: true,
+    });
+    const baseline = structuredClone(prepared.originalData);
+    const hooks = await resolveHooks(definition);
+    if (!ctx.requestContext)
+        throw new Error('Singleton authorization completed without a request context');
+    const beforeSaveContext = {
+        data: prepared.data,
+        originalData: prepared.originalData,
+        singletonPath: ctx.collectionPath,
+        locale: prepared.locale,
+        requestContext: ctx.requestContext,
+        isInitialSave: false,
+        operation,
+        documentId: slot.documentId,
+    };
+    await invokeSingletonHook(hooks?.beforeSave, beforeSaveContext);
+    await prepared.prepareWrite();
+    const committed = await commitGuardedDocumentMutation(ctx, {
+        documentId: slot.documentId,
+        expectedRevision,
+        previousVersionId: slot.currentVersion.document_version_id,
+        locale: prepared.locale,
+    }, async () => {
+        if (operation.type === 'copyToLocale' &&
+            baseline !== null &&
+            sameDocumentData(prepared.data, baseline)) {
+            return {
+                value: {
+                    documentId: slot.documentId,
+                    documentVersionId: slot.currentVersion.document_version_id,
+                },
+                changed: false,
+            };
         }
-        const slot = { documentId: mappedDocumentId, currentVersion };
-        const prepared = await params.prepare(slot);
-        const isInitialSave = mappedDocumentId == null;
-        const beforeSaveContext = {
-            data: prepared.data,
-            originalData: prepared.originalData,
-            singletonPath: ctx.collectionPath,
-            locale: prepared.locale,
-            requestContext,
-            isInitialSave,
-            operation,
-            documentId: mappedDocumentId,
-        };
-        await invokeSingletonHook(hooks?.beforeSave, beforeSaveContext);
         const writeResult = await prepared.write();
-        const documentId = extractDocumentId(writeResult.document) || mappedDocumentId || '';
-        const documentVersionId = extractVersionId(writeResult.document);
-        if (documentId === '' || documentVersionId === '') {
-            throw new Error('singleton persistence did not return document and version ids');
-        }
-        if (isInitialSave) {
-            try {
-                await ctx.db.commands.singletons.setMapping(ctx.collectionId, documentId);
-            }
-            catch (error) {
-                if (ctx.db.classifyError?.(error)?.code === DbErrorCodes.UNIQUE_VIOLATION) {
-                    throw ERR_CONFLICT({
-                        message: `singleton '${ctx.collectionPath}' was materialised concurrently`,
-                        details: { singletonPath: ctx.collectionPath },
-                    }).log(ctx.logger);
-                }
-                throw error;
-            }
-        }
-        return {
-            documentId,
-            documentVersionId,
-            afterSaveContext: {
-                ...beforeSaveContext,
-                documentId,
-                documentVersionId,
-            },
-        };
+        const documentId = extractDocumentId(writeResult.document), documentVersionId = extractVersionId(writeResult.document);
+        if (!documentId || !documentVersionId)
+            throw new Error('Singleton persistence returned no document/version identity');
+        return { value: { documentId, documentVersionId }, changed: true };
     });
-    await runCommittedDocumentHook(ctx, {
-        phase: 'afterSave',
-        documentId: committed.documentId,
-        documentVersionId: committed.documentVersionId,
-    }, () => invokeSingletonHook(hooks?.afterSave, committed.afterSaveContext));
-    return {
-        documentId: committed.documentId,
-        documentVersionId: committed.documentVersionId,
-    };
+    const receipt = { ...committed.value, revision: committed.revision };
+    await runCommittedDocumentHook(ctx, { phase: 'afterSave', ...receipt }, () => invokeSingletonHook(hooks?.afterSave, { ...beforeSaveContext, ...committed.value }));
+    return receipt;
 }
 async function invokeSingletonHook(hook, context) {
     const hooks = hook == null ? [] : Array.isArray(hook) ? hook : [hook];

package/dist/services/singleton-lifecycle/restore.d.ts

@@ -10,4 +10,5 @@ import type { SingletonSaveResult } from './internals.js';
 /** Restore one historical singleton version as the new current version. */
 export declare function restoreSingletonVersion(ctx: DocumentLifecycleContext, params: {
     sourceVersionId: string;
+    expectedRevision: number;
 }): Promise<SingletonSaveResult>;

package/dist/services/singleton-lifecycle/restore.js

@@ -13,11 +13,13 @@ import { persistExistingDocumentVersion } from '../document-lifecycle/persistenc
 import { authorizeSingletonUpdate, commitSingletonSave } from './internals.js';
 /** Restore one historical singleton version as the new current version. */
 export async function restoreSingletonVersion(ctx, params) {
+    params = { ...params };
     return withLogContext({ domain: 'services', module: 'singleton-lifecycle', function: 'restoreSingletonVersion' }, async () => {
         const definition = authorizeSingletonUpdate(ctx);
         return commitSingletonSave({
             ctx,
             definition,
+            expectedRevision: params.expectedRevision,
             operation: { type: 'restore', sourceVersionId: params.sourceVersionId },
             prepare: async (slot) => {
                 if (slot.documentId == null || slot.currentVersion == null) {
@@ -75,8 +77,8 @@ export async function restoreSingletonVersion(ctx, params) {
                     data,
                     originalData,
                     locale: 'all',
+                    prepareWrite: () => applyRichTextEmbed(ctx, data),
                     write: async () => {
-                        await applyRichTextEmbed(ctx, data);
                         return persistExistingDocumentVersion(ctx, {
                             documentId: slot.documentId,
                             action: 'restore',

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

@@ -5,12 +5,13 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import type { DocumentRevisionReceipt, SingletonSavePrecondition } from '../../@types/index.js';
 import type { DocumentLifecycleContext } from '../document-lifecycle/context.js';
 import type { SingletonSaveResult } from './internals.js';
-export interface UpdateSingletonParams {
+export type UpdateSingletonParams = SingletonSavePrecondition & {
     data: Record<string, any>;
     locale?: string;
-    expectedVersionId?: string;
-}
-/** Materialise or update a singleton slot as one immutable document version. */
-export declare function updateSingleton(ctx: DocumentLifecycleContext, params: UpdateSingletonParams): Promise<SingletonSaveResult>;
+};
+export type UpdateSingletonResult = SingletonSaveResult & DocumentRevisionReceipt;
+/** Prepare outside locks; recheck the observed slot/document under S → D before committing. */
+export declare function updateSingleton(ctx: DocumentLifecycleContext, params: UpdateSingletonParams): Promise<UpdateSingletonResult>;