@byline/core 4.16.0 → 4.18.0

package/dist/services/singleton-lifecycle.test.node.js

@@ -0,0 +1,396 @@
+/**
+ * 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
+ */
+import { AdminAuth, createRequestContext } from '@byline/auth';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { DbErrorCodes } from '../lib/errors.js';
+import { copySingletonToLocale, resolveSingletonDocumentId, restoreSingletonVersion, updateSingleton, } from './singleton-lifecycle/index.js';
+const noopLogger = {
+    log: vi.fn(),
+    fatal: vi.fn(),
+    error: vi.fn(),
+    warn: vi.fn(),
+    info: vi.fn(),
+    debug: vi.fn(),
+    trace: vi.fn(),
+    silent: vi.fn(),
+};
+function createHarness(options = {}) {
+    const definition = {
+        path: 'site-settings',
+        label: 'Site settings',
+        singleton: true,
+        fields: [
+            { name: 'title', type: 'text', localized: true },
+            { name: 'count', type: 'integer', optional: true },
+        ],
+        hooks: options.hooks,
+    };
+    let mappedDocumentId = options.mapped ? 'doc-1' : null;
+    let currentVersion = options.mapped && !options.softDeleted
+        ? {
+            document_version_id: 'ver-current',
+            document_id: 'doc-1',
+            collection_id: 'col-1',
+            status: 'draft',
+            created_at: new Date('2026-08-25T00:00:00.000Z'),
+            updated_at: new Date('2026-08-25T00:00:00.000Z'),
+        }
+        : null;
+    const views = new Map();
+    const versions = new Map();
+    if (options.mapped && !options.softDeleted) {
+        views.set('en', { fields: { title: 'Before', count: 1 } });
+        views.set('all', { fields: { title: { en: 'Before' }, count: 1 } });
+    }
+    let transactionDepth = 0;
+    let committedTransactions = 0;
+    let versionCounter = 0;
+    const withTransaction = vi.fn(async (operation) => {
+        const isOuter = transactionDepth === 0;
+        const snapshot = isOuter
+            ? {
+                mappedDocumentId,
+                currentVersion,
+                views: new Map(views),
+                versionCounter,
+            }
+            : null;
+        transactionDepth++;
+        try {
+            const result = await operation();
+            transactionDepth--;
+            if (isOuter)
+                committedTransactions++;
+            return result;
+        }
+        catch (error) {
+            transactionDepth--;
+            if (snapshot != null) {
+                mappedDocumentId = snapshot.mappedDocumentId;
+                currentVersion = snapshot.currentVersion;
+                views.clear();
+                for (const [locale, view] of snapshot.views)
+                    views.set(locale, view);
+                versionCounter = snapshot.versionCounter;
+            }
+            throw error;
+        }
+    });
+    const lockSlot = vi.fn(async () => {
+        expect(transactionDepth).toBeGreaterThan(0);
+    });
+    const setMapping = vi.fn(async (_collectionId, documentId) => {
+        mappedDocumentId = documentId;
+    });
+    const createDocumentVersion = vi.fn(async (write) => {
+        const documentId = write.documentId ?? 'doc-1';
+        const documentVersionId = `ver-${++versionCounter}`;
+        currentVersion = {
+            document_version_id: documentVersionId,
+            document_id: documentId,
+            collection_id: 'col-1',
+            status: write.status,
+            created_at: new Date('2026-08-25T00:00:00.000Z'),
+            updated_at: new Date('2026-08-26T00:00:00.000Z'),
+        };
+        views.set(write.locale, { fields: write.documentData });
+        return {
+            document: { id: documentVersionId, document_id: documentId },
+            fieldCount: Object.keys(write.documentData).length,
+        };
+    });
+    const getMappedDocumentId = vi.fn(async () => mappedDocumentId);
+    const getCurrentVersionMetadata = vi.fn(async () => currentVersion);
+    const getDocumentById = vi.fn(async (params) => {
+        if (mappedDocumentId == null || currentVersion == null)
+            return null;
+        const locale = params.locale ?? 'en';
+        const view = views.get(locale);
+        if (view == null && params.onMissingLocale === 'omit')
+            return null;
+        return {
+            document_id: mappedDocumentId,
+            document_version_id: currentVersion.document_version_id,
+            status: currentVersion.status,
+            fields: view?.fields ?? {},
+        };
+    });
+    const getDocumentByVersion = vi.fn(async (params) => versions.get(params.document_version_id));
+    const classifyError = vi.fn((_error) => ({ code: DbErrorCodes.UNKNOWN }));
+    const db = {
+        classifyError,
+        commands: {
+            documents: {
+                createDocumentVersion,
+                publishSchedules: {
+                    suspendForContentEdit: vi.fn(async () => ({ status: 'schedule_not_found' })),
+                },
+            },
+            counters: {
+                nextCounterValue: vi.fn(async () => 1),
+            },
+            audit: { append: vi.fn(async () => ({ id: 'audit-1' })) },
+            singletons: {
+                lockSlot,
+                setMapping,
+                clearMapping: vi.fn(async () => {
+                    mappedDocumentId = null;
+                }),
+            },
+        },
+        queries: {
+            documents: {
+                getCurrentVersionMetadata,
+                getDocumentById,
+                getDocumentByVersion,
+            },
+            singletons: { getMappedDocumentId },
+        },
+        withTransaction,
+    };
+    const actor = new AdminAuth({
+        id: 'editor',
+        abilities: ['singletons.site-settings.update'],
+    });
+    const ctx = {
+        db,
+        definition,
+        collectionId: 'col-1',
+        collectionVersion: 1,
+        collectionPath: definition.path,
+        defaultLocale: 'en',
+        logger: noopLogger,
+        requestContext: createRequestContext({ actor }),
+    };
+    return {
+        ctx,
+        definition,
+        views,
+        versions,
+        createDocumentVersion,
+        getMappedDocumentId,
+        getCurrentVersionMetadata,
+        getDocumentById,
+        lockSlot,
+        setMapping,
+        classifyError,
+        withTransaction,
+        isInTransaction: () => transactionDepth > 0,
+        committedTransactions: () => committedTransactions,
+        mappedDocumentId: () => mappedDocumentId,
+        currentVersion: () => currentVersion,
+    };
+}
+describe('singleton lifecycle service', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('resolves null from the mapping before initial materialisation', async () => {
+        const harness = createHarness();
+        await expect(resolveSingletonDocumentId(harness.ctx)).resolves.toBeNull();
+    });
+    it('materialises once and fires save hooks around the committed transaction', async () => {
+        const contexts = [];
+        let harness;
+        harness = createHarness({
+            hooks: {
+                beforeSave: (context) => {
+                    expect(harness.isInTransaction()).toBe(true);
+                    contexts.push({ phase: 'before', ...context });
+                    context.data.title = 'Mutated by hook';
+                },
+                afterSave: (context) => {
+                    expect(harness.isInTransaction()).toBe(false);
+                    expect(harness.committedTransactions()).toBe(1);
+                    contexts.push({ phase: 'after', ...context });
+                },
+            },
+        });
+        const result = await updateSingleton(harness.ctx, { data: { title: 'Incoming' } });
+        expect(result).toEqual({ documentId: 'doc-1', documentVersionId: 'ver-1' });
+        expect(harness.lockSlot).toHaveBeenCalledOnce();
+        expect(harness.setMapping).toHaveBeenCalledWith('col-1', 'doc-1');
+        expect(harness.createDocumentVersion).toHaveBeenCalledWith(expect.objectContaining({
+            action: 'create',
+            documentData: { title: 'Mutated by hook' },
+            locale: 'en',
+        }));
+        expect(harness.createDocumentVersion.mock.calls[0]?.[0]).not.toHaveProperty('documentId');
+        expect(contexts).toEqual([
+            expect.objectContaining({
+                phase: 'before',
+                isInitialSave: true,
+                originalData: null,
+                documentId: null,
+                operation: { type: 'save' },
+            }),
+            expect.objectContaining({
+                phase: 'after',
+                isInitialSave: true,
+                documentId: 'doc-1',
+                documentVersionId: 'ver-1',
+                operation: { type: 'save' },
+            }),
+        ]);
+    });
+    it.each([
+        ['Postgres', 'byline_singleton_documents_pkey'],
+        ['MySQL', 'PRIMARY'],
+    ])('classifies a %s first-save mapping race by code and rolls back the version', async (_adapterName, constraint) => {
+        const harness = createHarness();
+        const uniqueViolation = new Error('engine-specific duplicate error');
+        harness.setMapping.mockRejectedValueOnce(uniqueViolation);
+        harness.classifyError.mockReturnValueOnce({
+            code: DbErrorCodes.UNIQUE_VIOLATION,
+            constraint,
+        });
+        await expect(updateSingleton(harness.ctx, { data: { title: 'Losing write' } })).rejects.toMatchObject({
+            code: 'ERR_CONFLICT',
+            message: "singleton 'site-settings' was materialised concurrently",
+        });
+        expect(harness.classifyError).toHaveBeenCalledWith(uniqueViolation);
+        expect(harness.committedTransactions()).toBe(0);
+        expect(harness.mappedDocumentId()).toBeNull();
+        expect(harness.currentVersion()).toBeNull();
+        expect(harness.views.size).toBe(0);
+    });
+    it('updates the mapped document and supplies current field data to both hooks', async () => {
+        const beforeSave = vi.fn((context) => {
+            expect(context.data.count).toBe(2);
+            context.data.count = '3';
+        });
+        const afterSave = vi.fn();
+        const harness = createHarness({ mapped: true, hooks: { beforeSave, afterSave } });
+        await updateSingleton(harness.ctx, {
+            data: { title: 'After', count: '2' },
+            expectedVersionId: 'ver-current',
+        });
+        expect(harness.setMapping).not.toHaveBeenCalled();
+        expect(harness.createDocumentVersion).toHaveBeenCalledWith(expect.objectContaining({
+            documentId: 'doc-1',
+            action: 'update',
+            documentData: { title: 'After', count: 3 },
+            previousVersionId: 'ver-current',
+        }));
+        expect(beforeSave).toHaveBeenCalledWith(expect.objectContaining({
+            isInitialSave: false,
+            documentId: 'doc-1',
+            originalData: { title: 'Before', count: 1 },
+        }));
+        expect(afterSave).toHaveBeenCalledWith(expect.objectContaining({ isInitialSave: false, documentVersionId: 'ver-1' }));
+    });
+    it('rejects a missing update ability before any database work', async () => {
+        const harness = createHarness();
+        harness.ctx.requestContext = createRequestContext({
+            actor: new AdminAuth({ id: 'reader', abilities: ['singletons.site-settings.read'] }),
+        });
+        await expect(updateSingleton(harness.ctx, { data: { title: 'No' } })).rejects.toMatchObject({
+            code: 'ERR_FORBIDDEN',
+        });
+        expect(harness.lockSlot).not.toHaveBeenCalled();
+        expect(harness.getMappedDocumentId).not.toHaveBeenCalled();
+    });
+    it('enforces expectedVersionId under the locked slot state', async () => {
+        const current = createHarness({ mapped: true });
+        await expect(updateSingleton(current.ctx, {
+            data: { title: 'Yes' },
+            expectedVersionId: 'ver-current',
+        })).resolves.toMatchObject({ documentId: 'doc-1' });
+        const stale = createHarness({ mapped: true });
+        await expect(updateSingleton(stale.ctx, { data: { title: 'No' }, expectedVersionId: 'ver-stale' })).rejects.toMatchObject({ code: 'ERR_CONFLICT' });
+        expect(stale.createDocumentVersion).not.toHaveBeenCalled();
+        const unmaterialised = createHarness();
+        await expect(updateSingleton(unmaterialised.ctx, {
+            data: { title: 'No' },
+            expectedVersionId: 'ver-believed-current',
+        })).rejects.toMatchObject({ code: 'ERR_CONFLICT' });
+        expect(unmaterialised.createDocumentVersion).not.toHaveBeenCalled();
+    });
+    it('rejects a non-default first locale before document or mapping writes', async () => {
+        const beforeSave = vi.fn();
+        const harness = createHarness({ hooks: { beforeSave } });
+        await expect(updateSingleton(harness.ctx, { data: { title: 'ไทย' }, locale: 'th' })).rejects.toMatchObject({ code: 'ERR_VALIDATION' });
+        expect(beforeSave).not.toHaveBeenCalled();
+        expect(harness.createDocumentVersion).not.toHaveBeenCalled();
+        expect(harness.setMapping).not.toHaveBeenCalled();
+    });
+    it('keeps a soft-deleted document mapped and rejects a replacement save', async () => {
+        const harness = createHarness({ mapped: true, softDeleted: true });
+        await expect(updateSingleton(harness.ctx, { data: { title: 'Replacement' } })).rejects.toMatchObject({ code: 'ERR_CONFLICT' });
+        expect(harness.mappedDocumentId()).toBe('doc-1');
+        expect(harness.createDocumentVersion).not.toHaveBeenCalled();
+        expect(harness.setMapping).not.toHaveBeenCalled();
+    });
+    it('leaves a committed version in place when afterSave rejects', async () => {
+        const harness = createHarness({
+            hooks: {
+                afterSave: () => {
+                    throw new Error('notification failed');
+                },
+            },
+        });
+        await expect(updateSingleton(harness.ctx, { data: { title: 'Committed' } })).rejects.toThrow('notification failed');
+        expect(harness.committedTransactions()).toBe(1);
+        expect(harness.mappedDocumentId()).toBe('doc-1');
+        expect(harness.currentVersion()?.document_version_id).toBe('ver-1');
+    });
+    it('restores complete all-locale data through the singleton save discriminator', async () => {
+        const beforeSave = vi.fn();
+        const afterSave = vi.fn();
+        const harness = createHarness({ mapped: true, hooks: { beforeSave, afterSave } });
+        harness.views.set('all', { fields: { title: { en: 'Current', th: 'ปัจจุบัน' }, count: 2 } });
+        harness.versions.set('ver-source', {
+            document_id: 'doc-1',
+            fields: { title: { en: 'Historic', th: 'อดีต' }, count: 1 },
+        });
+        await restoreSingletonVersion(harness.ctx, { sourceVersionId: 'ver-source' });
+        const hookShape = expect.objectContaining({
+            data: { title: { en: 'Historic', th: 'อดีต' }, count: 1 },
+            originalData: { title: { en: 'Current', th: 'ปัจจุบัน' }, count: 2 },
+            locale: 'all',
+            isInitialSave: false,
+            operation: { type: 'restore', sourceVersionId: 'ver-source' },
+        });
+        expect(beforeSave).toHaveBeenCalledWith(hookShape);
+        expect(afterSave).toHaveBeenCalledWith(hookShape);
+        expect(harness.createDocumentVersion).toHaveBeenCalledWith(expect.objectContaining({ action: 'restore', locale: 'all' }));
+    });
+    it('copies the merged target payload and distinguishes overwrite modes', async () => {
+        const run = async (overwrite) => {
+            const beforeSave = vi.fn();
+            const harness = createHarness({ mapped: true, hooks: { beforeSave } });
+            harness.views.set('en', { fields: { title: 'Source', count: 1 } });
+            harness.views.set('th', { fields: { title: 'Target', count: 1 } });
+            await copySingletonToLocale(harness.ctx, {
+                sourceLocale: 'en',
+                targetLocale: 'th',
+                overwrite,
+            });
+            return { context: beforeSave.mock.calls[0]?.[0], harness };
+        };
+        const preserving = await run(false);
+        const overwriting = await run(true);
+        expect(preserving.context).toEqual(expect.objectContaining({
+            data: { title: 'Target', count: 1 },
+            originalData: { title: 'Target', count: 1 },
+            locale: 'th',
+            operation: {
+                type: 'copyToLocale',
+                sourceLocale: 'en',
+                targetLocale: 'th',
+                overwrite: false,
+            },
+        }));
+        expect(overwriting.context).toEqual(expect.objectContaining({
+            data: { title: 'Source', count: 1 },
+            operation: expect.objectContaining({ type: 'copyToLocale', overwrite: true }),
+        }));
+        expect(preserving.harness.setMapping).not.toHaveBeenCalled();
+        expect(overwriting.harness.setMapping).not.toHaveBeenCalled();
+    });
+});

package/dist/storage/collection-fingerprint.js

@@ -5,6 +5,11 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+// Web Crypto (`globalThis.crypto.subtle`) works identically in Node 20+
+// and every modern browser. Using it here — instead of `node:crypto` —
+// keeps this module free of Node built-ins so it can sit in the static
+// module graph walked by client bundlers without being externalised.
+import { isSingleton } from '../@types/collection-types.js';
 function canonicalField(field) {
     const base = {
         name: field.name,
@@ -124,14 +129,21 @@ function canonicalCollection(def) {
         path: def.path,
         fields: def.fields.map(canonicalField),
     };
+    // Emitted only for singletons: adding an unconditional `kind` would change
+    // every existing collection's hash and bump every stored schema version on
+    // upgrade, even though its data shape did not change.
+    if (isSingleton(def))
+        out.kind = 'singleton';
     if (def.workflow)
         out.workflow = canonicalWorkflow(def.workflow);
-    if (def.useAsPath !== undefined)
-        out.useAsPath = def.useAsPath;
-    if (def.useAsTitle !== undefined)
-        out.useAsTitle = def.useAsTitle;
-    if (def.advertiseLocales !== undefined)
-        out.advertiseLocales = def.advertiseLocales;
+    if (!isSingleton(def)) {
+        if (def.useAsPath !== undefined)
+            out.useAsPath = def.useAsPath;
+        if (def.useAsTitle !== undefined)
+            out.useAsTitle = def.useAsTitle;
+        if (def.advertiseLocales !== undefined)
+            out.advertiseLocales = def.advertiseLocales;
+    }
     return out;
 }
 // ---------------------------------------------------------------------------

package/dist/storage/collection-fingerprint.test.node.js

@@ -270,4 +270,19 @@ describe('fingerprintCollection', () => {
         });
         expect(await fingerprintCollection(b)).toBe(hashA);
     });
+    it('distinguishes a singleton from a collection with the same shape', async () => {
+        const fields = [{ name: 'name', label: 'Site name', type: 'text' }];
+        const asCollection = await fingerprintCollection({
+            path: 'site-settings',
+            labels: { singular: 'Setting', plural: 'Settings' },
+            fields,
+        });
+        const asSingleton = await fingerprintCollection({
+            path: 'site-settings',
+            label: 'Site settings',
+            singleton: true,
+            fields,
+        });
+        expect(asSingleton).not.toBe(asCollection);
+    });
 });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.16.0",
+  "version": "4.18.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -84,14 +84,14 @@
   "dependencies": {
     "dotenv": "^17.4.2",
     "pino": "^10.3.1",
-    "sharp": "^0.35.3",
+    "sharp": "^0.35.4",
     "uuid": "^14.0.2",
     "zod": "^4.4.3",
-    "@byline/auth": "4.16.0"
+    "@byline/auth": "4.18.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.9",
-    "@types/node": "^26.2.0",
+    "@biomejs/biome": "2.5.10",
+    "@types/node": "^26.4.0",
     "chokidar": "^5.0.0",
     "chokidar-cli": "^3.0.0",
     "npm-run-all": "^4.1.5",

package/dist/config/resolve-item-view-columns.test.node.js

@@ -1,30 +0,0 @@
-/**
- * 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
- */
-import { describe, expect, it } from 'vitest';
-import { resolveItemViewColumns } from './config.js';
-const itemViewCols = [{ fieldName: 'title', label: 'Title' }];
-const pickerCols = [{ fieldName: 'name', label: 'Name' }];
-const cfg = (over) => ({ slug: 'x', ...over });
-describe('resolveItemViewColumns', () => {
-    it('returns itemView when present', () => {
-        expect(resolveItemViewColumns(cfg({ itemView: itemViewCols }))).toBe(itemViewCols);
-    });
-    it('falls back to the deprecated picker alias', () => {
-        expect(resolveItemViewColumns(cfg({ picker: pickerCols }))).toBe(pickerCols);
-    });
-    it('prefers itemView over picker when both are present', () => {
-        expect(resolveItemViewColumns(cfg({ itemView: itemViewCols, picker: pickerCols }))).toBe(itemViewCols);
-    });
-    it('returns undefined when neither is set', () => {
-        expect(resolveItemViewColumns(cfg({}))).toBeUndefined();
-    });
-    it('tolerates null / undefined config', () => {
-        expect(resolveItemViewColumns(null)).toBeUndefined();
-        expect(resolveItemViewColumns(undefined)).toBeUndefined();
-    });
-});