@byline/core 4.19.0 → 5.0.0

package/dist/storage/document-revision-capability.js

@@ -0,0 +1,15 @@
+import { ERR_DATABASE } from '../lib/errors.js';
+/** Must run before collection reconciliation, counters, or boot maintenance writes. */
+export async function assertDocumentRevisionCapability(db) {
+    if (typeof db.withTransaction !== 'function' ||
+        typeof db.withReadSnapshot !== 'function' ||
+        typeof db.commands?.collections?.lockCollectionRegistration !== 'function' ||
+        typeof db.commands?.documents?.publishSchedules?.lockDocuments !== 'function' ||
+        db.revisions == null ||
+        ['assertCompatibleSchema', 'isInTransaction', 'lock', 'advance', 'readStructure'].some((name) => typeof db.revisions[name] !== 'function')) {
+        throw ERR_DATABASE({
+            message: 'Byline requires a revision-capable database adapter. Upgrade the adapter and document revision schema while all writers/workers are fenced.',
+        });
+    }
+    await db.revisions.assertCompatibleSchema();
+}

package/dist/storage/document-revision-capability.test.node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/storage/document-revision-capability.test.node.js

@@ -0,0 +1,53 @@
+import { describe, expect, it, vi } from 'vitest';
+import { testAdapter } from './db-adapter.test-helper.js';
+import { assertDocumentRevisionCapability } from './document-revision-capability.js';
+describe('document revision adapter capability', () => {
+    const adapter = () => testAdapter({
+        commands: {
+            collections: { lockCollectionRegistration: vi.fn() },
+            documents: { publishSchedules: { lockDocuments: vi.fn() } },
+        },
+        withTransaction: vi.fn(),
+        withReadSnapshot: vi.fn(),
+        revisions: {
+            assertCompatibleSchema: vi.fn(async () => { }),
+            isInTransaction: () => false,
+            lock: vi.fn(),
+            readStructure: vi.fn(),
+            advance: vi.fn(),
+        },
+    });
+    for (const missing of [
+        'assertCompatibleSchema',
+        'isInTransaction',
+        'lock',
+        'advance',
+        'readStructure',
+    ]) {
+        it(`rejects JavaScript adapters missing ${missing}`, async () => {
+            const db = adapter();
+            Reflect.deleteProperty(db.revisions, missing);
+            await expect(assertDocumentRevisionCapability(db)).rejects.toMatchObject({
+                code: 'ERR_DATABASE',
+                message: expect.stringContaining('Upgrade the adapter'),
+            });
+        });
+    }
+    it('rejects JavaScript adapters without coherent read snapshots before schema work', async () => {
+        const db = adapter();
+        Reflect.deleteProperty(db, 'withReadSnapshot');
+        await expect(assertDocumentRevisionCapability(db)).rejects.toMatchObject({
+            code: 'ERR_DATABASE',
+        });
+        expect(db.revisions.assertCompatibleSchema).not.toHaveBeenCalled();
+    });
+    it('rejects old adapters with no revision surface', async () => {
+        await expect(Reflect.apply(assertDocumentRevisionCapability, undefined, [{ withTransaction: vi.fn() }])).rejects.toMatchObject({ code: 'ERR_DATABASE' });
+    });
+    it('awaits schema validation and preserves the actionable upgrade error', async () => {
+        const db = adapter();
+        const error = new Error('fence and upgrade schema');
+        vi.mocked(db.revisions.assertCompatibleSchema).mockRejectedValue(error);
+        await expect(assertDocumentRevisionCapability(db)).rejects.toBe(error);
+    });
+});

package/dist/storage/document-revision.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare function isDocumentRevision(value: unknown): value is number;
+/** Validate caller input without coercing strings, nulls, or missing values. */
+export declare function parseDocumentRevision(value: unknown): number;
+/** Convert driver BIGINT values without accepting unsafe or noncanonical values. */
+export declare function documentRevisionFromDatabase(value: unknown): number;

package/dist/storage/document-revision.js

@@ -0,0 +1,37 @@
+/**
+ * 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 { ERR_DATABASE, ERR_VALIDATION } from '../lib/errors.js';
+export function isDocumentRevision(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+/** Validate caller input without coercing strings, nulls, or missing values. */
+export function parseDocumentRevision(value) {
+    if (isDocumentRevision(value))
+        return value;
+    const details = {
+        reason: value === undefined ? 'missing_document_revision' : 'invalid_document_revision',
+    };
+    throw ERR_VALIDATION({
+        message: 'an observed positive safe-integer document revision is required',
+        details,
+    });
+}
+/** Convert driver BIGINT values without accepting unsafe or noncanonical values. */
+export function documentRevisionFromDatabase(value) {
+    if (isDocumentRevision(value))
+        return value;
+    if (typeof value === 'bigint' && value > 0n && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
+        return Number(value);
+    }
+    if (typeof value === 'string' && /^[1-9]\d{0,15}$/.test(value)) {
+        const revision = Number(value);
+        if (isDocumentRevision(revision) && String(revision) === value)
+            return revision;
+    }
+    throw ERR_DATABASE({ message: 'database returned an invalid document revision' });
+}

package/dist/storage/document-revision.test.node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/storage/document-revision.test.node.js

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { ErrorCodes } from '../lib/errors.js';
+import { documentRevisionFromDatabase, isDocumentRevision, parseDocumentRevision, } from './document-revision.js';
+describe('document revisions', () => {
+    it.each([1, 2, Number.MAX_SAFE_INTEGER])('accepts observed revision %s unchanged', (value) => {
+        expect(isDocumentRevision(value)).toBe(true);
+        expect(parseDocumentRevision(value)).toBe(value);
+    });
+    it.each([null, '1', 1n, 0, -1, 1.5, NaN, Infinity, Number.MAX_SAFE_INTEGER + 1, {}, []])('rejects invalid caller input %s without coercion', (value) => {
+        expect(isDocumentRevision(value)).toBe(false);
+        expect(() => parseDocumentRevision(value)).toThrowError(expect.objectContaining({
+            code: ErrorCodes.VALIDATION,
+            details: { reason: 'invalid_document_revision' },
+        }));
+    });
+    it('distinguishes an omitted revision from malformed input', () => {
+        expect(() => parseDocumentRevision(undefined)).toThrowError(expect.objectContaining({
+            code: ErrorCodes.VALIDATION,
+            details: { reason: 'missing_document_revision' },
+        }));
+    });
+    it.each([1, '1', 1n, Number.MAX_SAFE_INTEGER, '9007199254740991', 9007199254740991n])('converts the database representation %s exactly', (value) => expect(documentRevisionFromDatabase(value)).toBe(Number(value)));
+    it.each([
+        undefined,
+        null,
+        0,
+        -1,
+        1.2,
+        NaN,
+        Infinity,
+        '01',
+        '+1',
+        '1.0',
+        '1e1',
+        ' 1',
+        '1 ',
+        '1\n',
+        '',
+        '9007199254740992',
+        '9007199254740993',
+        9007199254740992n,
+        -1n,
+        Number.MAX_SAFE_INTEGER + 1,
+        { valueOf: () => 1 },
+    ])('rejects malformed/overflowing storage value %s', (value) => {
+        expect(() => documentRevisionFromDatabase(value)).toThrowError(expect.objectContaining({ code: ErrorCodes.DATABASE }));
+    });
+});

package/dist/storage/read-snapshot.d.ts

@@ -0,0 +1,3 @@
+import type { IDbAdapter, ReadSnapshotQueries } from '../@types/db-types.js';
+/** Construct an allowlisted facade without leaking query classes or their executors. */
+export declare function runReadSnapshot<T>(queries: IDbAdapter['queries'], fn: (queries: ReadSnapshotQueries) => Promise<T>): Promise<T>;

package/dist/storage/read-snapshot.js

@@ -0,0 +1,55 @@
+import { ERR_DATABASE } from '../lib/errors.js';
+/** Construct an allowlisted facade without leaking query classes or their executors. */
+export async function runReadSnapshot(queries, fn) {
+    let active = true;
+    function bind(source, names) {
+        return Object.freeze(Object.fromEntries(names.map((name) => [
+            name,
+            (...args) => {
+                if (!active)
+                    throw ERR_DATABASE({ message: 'Read snapshot has expired' });
+                return source[name].apply(source, args);
+            },
+        ])));
+    }
+    const facade = Object.freeze({
+        collections: bind(queries.collections, [
+            'getAllCollections',
+            'getCollectionByPath',
+            'getCollectionById',
+        ]),
+        audit: bind(queries.audit, ['getDocumentAuditLog', 'findAuditLog']),
+        singletons: bind(queries.singletons, ['getMappedDocumentId']),
+        documents: Object.freeze({
+            ...bind(queries.documents, [
+                'getDocumentRevision',
+                'getDocumentById',
+                'getCurrentVersionMetadata',
+                'getCurrentPath',
+                'getDocumentByPath',
+                'getDocumentByVersion',
+                'getDocumentsByVersionIds',
+                'getDocumentsByDocumentIds',
+                'getDocumentHistory',
+                'getPublishedVersion',
+                'getPublishedDocumentIds',
+                'getDocumentCountsByStatus',
+                'findDocuments',
+                'getLastOrderKey',
+                'getNeighborOrderKeys',
+                'getCanonicalDocumentOrder',
+                'getTreeAncestors',
+                'getTreeChildren',
+                'getTreeParent',
+                'getTreeSubtree',
+            ]),
+            publishSchedules: bind(queries.documents.publishSchedules, ['get', 'list']),
+        }),
+    });
+    try {
+        return await fn(facade);
+    }
+    finally {
+        active = false;
+    }
+}

package/dist/storage/revision-store.test-helper.d.ts

@@ -0,0 +1,3 @@
+import type { DocumentRevisionStore } from '../@types/document-revision.js';
+/** Unrelated unit fixtures must fail if they accidentally exercise revision storage. */
+export declare const unusedRevisionStore: DocumentRevisionStore;

package/dist/storage/revision-store.test-helper.js

@@ -0,0 +1,16 @@
+/** Unrelated unit fixtures must fail if they accidentally exercise revision storage. */
+export const unusedRevisionStore = {
+    readStructure: async () => {
+        throw new Error('Structural storage is outside this unit fixture.');
+    },
+    assertCompatibleSchema: async () => {
+        throw new Error('Revision storage is outside this unit fixture.');
+    },
+    isInTransaction: () => false,
+    lock: async () => {
+        throw new Error('Revision storage is outside this unit fixture.');
+    },
+    advance: async () => {
+        throw new Error('Revision storage is outside this unit fixture.');
+    },
+};

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.19.0",
+  "version": "5.0.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -87,7 +87,7 @@
     "sharp": "^0.35.4",
     "uuid": "^14.0.2",
     "zod": "^4.4.3",
-    "@byline/auth": "4.19.0"
+    "@byline/auth": "5.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.10",