@byline/core 3.20.4 → 4.0.0

package/dist/services/document-read.js

@@ -21,6 +21,8 @@
  * `beforeCreate` / `afterCreate` hooks.
  */
 import { normalizeCollectionHook, resolveHooks } from '../@types/index.js';
+import { resolveReadContextRoot } from '../auth/read-context-scope.js';
+import { ERR_READ_RECURSION } from '../lib/errors.js';
 async function invokeHook(hook, ctx) {
     const fns = normalizeCollectionHook(hook);
     for (const fn of fns) {
@@ -30,13 +32,16 @@ async function invokeHook(hook, ctx) {
 /**
  * Fire the `afterRead` hook for one reconstructed document.
  *
- * No-op when the collection has no hook. No-op when the document has
- * already been through `afterRead` in this `ReadContext` — enforces the
- * "once per document per logical request" rule that forecloses the
- * A→B→A infinite loop when hooks perform their own reads.
+ * No-op when the collection has no hook, when this exact materialized object
+ * completed the hook already. An active logical version fails closed with
+ * `ERR_READ_RECURSION`: even the same object may be only partially processed,
+ * so returning it cannot be proven safe. Fresh raw objects are always redacted
+ * once the active call completes. Failed hooks do not mark the object complete,
+ * and active state is cleared in `finally` so a later retry can proceed.
  *
  * The hook receives the raw storage-shape document (mutable) and the
- * shared `ReadContext` so it can thread the same context through any
+ * operation's authenticated context plus the shared `ReadContext`, so it can
+ * redact by actor and thread the same context through any
  * nested `client.collection(...).findById(id, { _readContext })` calls.
  */
 export async function applyAfterRead(params) {
@@ -47,14 +52,47 @@ export async function applyAfterRead(params) {
     const docId = params.doc?.document_id;
     if (typeof docId !== 'string')
         return;
-    const key = `${params.definition.path}:${docId}`;
-    if (params.readContext.afterReadFired.has(key))
+    const versionId = typeof params.doc?.document_version_id === 'string'
+        ? params.doc.document_version_id
+        : `document:${docId}`;
+    const state = getAfterReadState(params.readContext);
+    if (state.processed.has(params.doc))
         return;
-    params.readContext.afterReadFired.add(key);
+    // ReadContext already scopes the operation; keeping identity out of this key
+    // prevents a nested caller from evading the guard with another context clone.
+    const activeKey = `${params.definition.path}:${versionId}`;
+    if (state.active.has(activeKey)) {
+        throw ERR_READ_RECURSION({
+            message: `afterRead recursion blocked for active version '${versionId}'`,
+            details: {
+                collectionPath: params.definition.path,
+                documentId: docId,
+                documentVersionId: versionId,
+            },
+        });
+    }
     const ctx = {
         doc: params.doc,
         collectionPath: params.definition.path,
+        requestContext: params.requestContext,
         readContext: params.readContext,
     };
-    await invokeHook(hook, ctx);
+    state.active.add(activeKey);
+    try {
+        await invokeHook(hook, ctx);
+        state.processed.add(params.doc);
+    }
+    finally {
+        state.active.delete(activeKey);
+    }
+}
+const afterReadStates = new WeakMap();
+function getAfterReadState(readContext) {
+    const root = resolveReadContextRoot(readContext);
+    const existing = afterReadStates.get(root);
+    if (existing)
+        return existing;
+    const state = { active: new Set(), processed: new WeakSet() };
+    afterReadStates.set(root, state);
+    return state;
 }

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

@@ -7,6 +7,7 @@
  */
 import { createSuperAdminContext } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
+import { commitHookAttachment, prepareHookAttachment } from '../config/attach-hooks.js';
 import { BylineError, ErrorCodes } from '../lib/errors.js';
 import { uploadField } from './field-upload.js';
 const uploadCollection = {
@@ -62,12 +63,23 @@ function createMockDb() {
                 setOrderKey: vi.fn(),
                 placeTreeNode: vi.fn(),
                 removeFromTree: vi.fn(),
+                promoteChildrenAndRemoveFromTree: vi.fn(async () => ({
+                    removed: {
+                        changed: false,
+                        before: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        after: { placed: false, parentDocumentId: null, orderKey: null, index: null },
+                        beforeSiblingDocumentIds: [],
+                        beforeSubtreeDocumentIds: [],
+                    },
+                    promoted: [],
+                })),
             },
             counters: {
                 ensureCounterGroup: vi.fn(),
                 nextCounterValue: vi.fn(),
                 nextScopedCounterValue: vi.fn(),
             },
+            audit: { append: vi.fn(async () => ({ id: 'audit-1' })) },
         },
         queries: {
             collections: {
@@ -76,6 +88,7 @@ function createMockDb() {
                 getCollectionById: vi.fn(),
             },
             documents: {
+                getDocumentSystemFieldsForUpdate: vi.fn(async () => null),
                 getDocumentById: vi.fn(),
                 getCurrentVersionMetadata: vi.fn(),
                 getCurrentPath: vi.fn(),
@@ -96,7 +109,18 @@ function createMockDb() {
                 getTreeParent: vi.fn(),
                 getTreeSubtree: vi.fn(),
             },
+            audit: {
+                getDocumentAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+                findAuditLog: vi.fn(async () => ({
+                    entries: [],
+                    meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
+                })),
+            },
         },
+        withTransaction: async (fn) => fn(),
     };
     return { db, createDocumentVersion };
 }
@@ -162,6 +186,52 @@ function buildCtx(overrides) {
     return { ctx, createDocumentVersion, upload, del, imageProcessor };
 }
 describe('uploadField service', () => {
+    it('fires registry hooks for a nested array instance selected by its unique upload leaf', async () => {
+        const beforeStore = vi.fn();
+        const publicationFile = {
+            name: 'publicationFile',
+            type: 'file',
+            upload: { mimeTypes: ['application/pdf'] },
+        };
+        const definition = {
+            path: 'documents',
+            labels: { singular: 'Document', plural: 'Documents' },
+            fields: [
+                {
+                    name: 'files',
+                    type: 'array',
+                    fields: [{ name: 'filesGroup', type: 'group', fields: [publicationFile] }],
+                },
+            ],
+        };
+        commitHookAttachment(prepareHookAttachment({
+            collections: [definition],
+            hooks: {
+                uploads: {
+                    'documents.files.filesGroup.publicationFile': { beforeStore },
+                },
+            },
+        }));
+        const { ctx } = buildCtx({
+            definition,
+            collectionPath: 'documents',
+            fieldName: 'publicationFile',
+        });
+        await uploadField(ctx, {
+            buffer: Buffer.from('pdf'),
+            originalFilename: 'publication.pdf',
+            mimeType: 'application/pdf',
+            fileSize: 3,
+            fields: { runtimeFormPath: 'files[2].filesGroup.publicationFile' },
+            shouldCreateDocument: false,
+        });
+        expect(beforeStore).toHaveBeenCalledOnce();
+        expect(beforeStore).toHaveBeenCalledWith(expect.objectContaining({
+            fieldName: 'publicationFile',
+            field: publicationFile,
+            fields: { runtimeFormPath: 'files[2].filesGroup.publicationFile' },
+        }));
+    });
     it('uploads a file without creating a document when requested', async () => {
         const { ctx, createDocumentVersion, upload } = buildCtx();
         const result = await uploadField(ctx, {

package/dist/services/index.d.ts

@@ -1,4 +1,4 @@
-export { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, } from '../lib/errors.js';
+export { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_VALIDATION, } from '../lib/errors.js';
 export { normaliseDateFields } from '../utils/normalise-dates.js';
 export { type AssignCounterValuesInput, assignCounterValues } from './assign-counter-values.js';
 export { type BuildSearchDocumentOptions, buildSearchDocument, resolveSearchZones, type SearchSourceDocument, } from './build-search-document.js';
@@ -9,9 +9,10 @@ export * from './document-read.js';
 export * from './document-to-markdown.js';
 export * from './field-upload.js';
 export { type InterfaceI18nConfig, type TranslationDriftWarning, type ValidateTranslationsResult, validateTranslations, } from './i18n-validator.js';
+export { type CanonicalNumericFieldType, type CanonicalNumericValue, isCanonicalNumericValue, normalizeNumericFields, normalizeNumericValue, } from './normalize-numeric-fields.js';
 export { type CycleRelationValue, createReadContext, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateOptions, type PopulateSpec, populateDocuments, type ReadContext, resolveIdentityField, type UnresolvedRelationValue, } from './populate.js';
 export { buildRelationSummaryPopulateMap, type RelationTargetResolver, resolveRelationProjection, } from './relation-projection.js';
 export { type EmbedRichTextFieldsOptions, embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';
-export { collectRichTextLeaves, type PopulateRichTextFieldsOptions, populateRichTextFields, type RichTextAdapterPresence, type RichTextLeaf, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
+export { collectRichTextLeaves, createRichTextDocumentReader, type PopulateRichTextFieldsOptions, populateRichTextFields, type RichTextAdapterPresence, type RichTextLeaf, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
 export { type SearchProviderPresence, validateSearchConfig, } from './validate-search-config.js';
 export { type FieldLeaf, walkFieldTree } from './walk-field-tree.js';

package/dist/services/index.js

@@ -1,5 +1,5 @@
 // packages/core/src/services/index.ts
-export { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, } from '../lib/errors.js';
+export { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_VALIDATION, } from '../lib/errors.js';
 export { normaliseDateFields } from '../utils/normalise-dates.js';
 export { assignCounterValues } from './assign-counter-values.js';
 export { buildSearchDocument, resolveSearchZones, } from './build-search-document.js';
@@ -10,9 +10,10 @@ export * from './document-read.js';
 export * from './document-to-markdown.js';
 export * from './field-upload.js';
 export { validateTranslations, } from './i18n-validator.js';
+export { isCanonicalNumericValue, normalizeNumericFields, normalizeNumericValue, } from './normalize-numeric-fields.js';
 export { createReadContext, populateDocuments, resolveIdentityField, } from './populate.js';
 export { buildRelationSummaryPopulateMap, resolveRelationProjection, } from './relation-projection.js';
 export { embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';
-export { collectRichTextLeaves, populateRichTextFields, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
+export { collectRichTextLeaves, createRichTextDocumentReader, populateRichTextFields, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
 export { validateSearchConfig, } from './validate-search-config.js';
 export { walkFieldTree } from './walk-field-tree.js';

package/dist/services/normalize-numeric-fields.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 type { FieldSet } from '../@types/index.js';
+export type CanonicalNumericFieldType = 'integer' | 'float' | 'decimal';
+export type CanonicalNumericValue = number | string;
+/** Return whether a value already has the storage-facing canonical type and shape. */
+export declare function isCanonicalNumericValue(fieldType: CanonicalNumericFieldType, value: unknown): value is CanonicalNumericValue;
+/**
+ * Convert a tolerant numeric write value to its canonical representation.
+ * `undefined` means the value was empty and should be removed.
+ */
+export declare function normalizeNumericValue(fieldType: CanonicalNumericFieldType, value: unknown, path: string): CanonicalNumericValue | undefined;
+/**
+ * Normalize every user-writable numeric leaf in a schema-shaped data tree.
+ * Mutates `data` in place. Counter fields are deliberately excluded because
+ * their values are supplied by the lifecycle allocator.
+ */
+export declare function normalizeNumericFields(fields: FieldSet, data: Record<string, any>): void;

package/dist/services/normalize-numeric-fields.js

@@ -0,0 +1,89 @@
+/**
+ * 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_VALIDATION } from '../lib/errors.js';
+import { walkFieldTree } from './walk-field-tree.js';
+const NUMERIC_LITERAL_RE = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+/** Return whether a value already has the storage-facing canonical type and shape. */
+export function isCanonicalNumericValue(fieldType, value) {
+    if (fieldType === 'decimal') {
+        return typeof value === 'string' && value.trim() === value && NUMERIC_LITERAL_RE.test(value);
+    }
+    return (typeof value === 'number' &&
+        Number.isFinite(value) &&
+        (fieldType !== 'integer' || Number.isInteger(value)));
+}
+/**
+ * Convert a tolerant numeric write value to its canonical representation.
+ * `undefined` means the value was empty and should be removed.
+ */
+export function normalizeNumericValue(fieldType, value, path) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '')
+            return undefined;
+        if (!NUMERIC_LITERAL_RE.test(trimmed))
+            throwNumericValidation(fieldType, value, path);
+        if (fieldType === 'decimal')
+            return trimmed;
+        const numberValue = Number(trimmed);
+        if (!Number.isFinite(numberValue))
+            throwNumericValidation(fieldType, value, path);
+        if (fieldType === 'integer' && !Number.isInteger(numberValue)) {
+            throwNumericValidation(fieldType, value, path);
+        }
+        return numberValue;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throwNumericValidation(fieldType, value, path);
+        if (fieldType === 'integer' && !Number.isInteger(value)) {
+            throwNumericValidation(fieldType, value, path);
+        }
+        return fieldType === 'decimal' ? String(value) : value;
+    }
+    throwNumericValidation(fieldType, value, path);
+}
+/**
+ * Normalize every user-writable numeric leaf in a schema-shaped data tree.
+ * Mutates `data` in place. Counter fields are deliberately excluded because
+ * their values are supplied by the lifecycle allocator.
+ */
+export function normalizeNumericFields(fields, data) {
+    for (const leaf of walkFieldTree(fields, data)) {
+        if (!isWritableNumericType(leaf.field.type))
+            continue;
+        if (leaf.field.localized === true && isLocaleMap(leaf.value)) {
+            for (const [locale, localeValue] of Object.entries(leaf.value)) {
+                normalizeLeafValue(leaf.field.type, leaf.value, locale, localeValue, `${leaf.fieldPath}.${locale}`);
+            }
+            continue;
+        }
+        normalizeLeafValue(leaf.field.type, leaf.parent, leaf.key, leaf.value, leaf.fieldPath);
+    }
+}
+function normalizeLeafValue(fieldType, parent, key, value, path) {
+    const normalized = normalizeNumericValue(fieldType, value, path);
+    if (normalized === undefined) {
+        delete parent[key];
+    }
+    else {
+        parent[key] = normalized;
+    }
+}
+function isWritableNumericType(type) {
+    return type === 'integer' || type === 'float' || type === 'decimal';
+}
+function isLocaleMap(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+function throwNumericValidation(fieldType, value, path) {
+    throw ERR_VALIDATION({
+        message: `invalid ${fieldType} value at '${path}'`,
+        details: { path, fieldType, value },
+    });
+}

package/dist/services/normalize-numeric-fields.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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/normalize-numeric-fields.test.node.js

@@ -0,0 +1,99 @@
+/**
+ * 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 { BylineError, ErrorCodes } from '../lib/errors.js';
+import { normalizeNumericFields, normalizeNumericValue } from './normalize-numeric-fields.js';
+const fields = [
+    { name: 'count', type: 'integer' },
+    { name: 'ratio', type: 'float' },
+    { name: 'price', type: 'decimal' },
+    { name: 'sequence', type: 'counter', group: 'test' },
+    {
+        name: 'settings',
+        type: 'group',
+        fields: [{ name: 'threshold', type: 'float' }],
+    },
+    {
+        name: 'rows',
+        type: 'array',
+        fields: [{ name: 'quantity', type: 'integer' }],
+    },
+    {
+        name: 'content',
+        type: 'blocks',
+        blocks: [
+            {
+                blockType: 'amount',
+                fields: [{ name: 'value', type: 'decimal' }],
+            },
+        ],
+    },
+];
+describe('normalizeNumericFields', () => {
+    it('normalizes numeric leaves through groups, arrays, and blocks while leaving counters alone', () => {
+        const data = {
+            count: '12',
+            ratio: ' 1.25e2 ',
+            price: ' 001.2300 ',
+            sequence: 'caller-owned-value',
+            settings: { threshold: 2 },
+            rows: [{ quantity: '3.0' }, { quantity: 4 }],
+            content: [{ _type: 'amount', value: 5.5 }],
+        };
+        normalizeNumericFields(fields, data);
+        expect(data).toEqual({
+            count: 12,
+            ratio: 125,
+            price: '001.2300',
+            sequence: 'caller-owned-value',
+            settings: { threshold: 2 },
+            rows: [{ quantity: 3 }, { quantity: 4 }],
+            content: [{ _type: 'amount', value: '5.5' }],
+        });
+        normalizeNumericFields(fields, data);
+        expect(data.price).toBe('001.2300');
+    });
+    it('removes empty and whitespace-only values', () => {
+        const data = { count: '', ratio: '   ', price: '\t' };
+        normalizeNumericFields(fields, data);
+        expect(data).toEqual({});
+    });
+    it('normalizes all-locale value maps and reports the locale-qualified path', () => {
+        const localizedFields = [
+            { name: 'amount', type: 'decimal', localized: true },
+        ];
+        const data = { amount: { en: ' 1.20 ', fr: 'not-a-number', de: '' } };
+        expect(() => normalizeNumericFields(localizedFields, data)).toThrowError(expect.objectContaining({
+            code: ErrorCodes.VALIDATION,
+            details: expect.objectContaining({ path: 'amount.fr' }),
+        }));
+        expect(data.amount.en).toBe('1.20');
+    });
+    it.each([
+        ['integer', '1.2'],
+        ['integer', Number.NaN],
+        ['float', Number.POSITIVE_INFINITY],
+        ['float', '1e'],
+        ['decimal', '--1'],
+    ])('rejects invalid %s input', (fieldType, value) => {
+        expect(() => normalizeNumericValue(fieldType, value, 'nested.2.value')).toThrowError(expect.objectContaining({
+            code: ErrorCodes.VALIDATION,
+            details: expect.objectContaining({ path: 'nested.2.value' }),
+        }));
+    });
+    it('throws a BylineError with ERR_VALIDATION', () => {
+        try {
+            normalizeNumericValue('integer', {}, 'count');
+            expect.fail('expected ERR_VALIDATION');
+        }
+        catch (error) {
+            expect(error).toBeInstanceOf(BylineError);
+            expect(error).toMatchObject({ code: ErrorCodes.VALIDATION });
+        }
+    });
+});

package/dist/services/populate.d.ts

@@ -128,16 +128,17 @@
  *     wins; otherwise selects union together, identity field is always
  *     added).
  */
-import type { RequestContext } from '@byline/auth';
+import { type RequestContext } from '@byline/auth';
 import type { CollectionDefinition, FieldSet, IDbAdapter, PopulateFieldSpec, PopulateSpec, ReadContext, ReadMode, RelatedDocumentValue, RelationField } from '../@types/index.js';
 export type { ReadContext } from '../@types/index.js';
 /** Build a fresh ReadContext. */
 export declare function createReadContext(overrides?: Partial<ReadContext>): ReadContext;
 export type { PopulateFieldOptions, PopulateFieldSpec, PopulateMap, PopulateSpec, } from '../@types/populate-types.js';
+export type { CycleRelationValue, PopulatedRelationValue, RelationFieldReadValue, RelationReadValue, UnpopulatedRelationValue, UnresolvedRelationValue, } from '../@types/relation-types.js';
 export interface PopulateOptions {
     db: IDbAdapter;
     /** Every collection definition in the app — needed to resolve target fields. */
-    collections: CollectionDefinition[];
+    collections: readonly CollectionDefinition[];
     /** The source collection id for `documents`. */
     collectionId: string;
     /**
@@ -178,13 +179,17 @@ export interface PopulateOptions {
     /**
      * Request-scoped auth context. Required when any target collection in the
      * walk has a `beforeRead` hook configured. Each target's hook is invoked
-     * (and cached on `readContext.beforeReadCache`) before its batch fetch,
+     * (and cached in private authority-bound state) before its batch fetch,
      * and the resulting predicate is ANDed onto the fetch's WHERE. When
      * omitted — most synthetic / test call paths — `beforeRead` hooks are
      * skipped entirely; the production read paths all forward this through
-     * from `CollectionHandle`.
+     * from `CollectionHandle`. Low-level synthetic calls still receive an
+     * anonymous operation context in `afterRead`, so the hook contract never
+     * lacks identity state.
      */
     requestContext?: RequestContext;
+    /** Private cache domain explicitly shared by every read path in one client instance. */
+    securityDomain?: object;
     /**
      * Skip `beforeRead` hook resolution on every target collection. The
      * top-level read's `_bypassBeforeRead` flag rides through to populate
@@ -204,25 +209,6 @@ export interface PopulateOptions {
      */
     richTextPopulate?: import('../@types/index.js').RichTextPopulateFn;
 }
-/** Marker placed in a relation leaf when the target was already materialised earlier in this request. */
-export interface CycleRelationValue extends RelatedDocumentValue {
-    _resolved: true;
-    _cycle: true;
-}
-/** Marker placed in a relation leaf when the target was not found (deleted). */
-export interface UnresolvedRelationValue extends RelatedDocumentValue {
-    _resolved: false;
-}
-/**
- * Envelope placed in a relation leaf when populate successfully fetched
- * the target document. The `document` field carries the raw storage-shape
- * doc (`@byline/client` then reshapes it to `ClientDocument` during
- * response shaping).
- */
-export interface PopulatedRelationValue extends RelatedDocumentValue {
-    _resolved: true;
-    document: Record<string, any>;
-}
 /**
  * Populate relation leaves in `opts.documents` in place, one DB
  * round-trip per depth level per target collection.