@byline/core 3.21.0 → 4.1.0

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

@@ -11,6 +11,7 @@
  * branch C (per-leaf error swallow). The visitor-side branches (A / B /
  * found) live in `@byline/richtext-lexical` and have their own suite.
  */
+import { createSuperAdminContext } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
 import { embedRichTextFields } from './richtext-embed.js';
 const noopLogger = {
@@ -24,6 +25,11 @@ const noopLogger = {
     silent: vi.fn(),
 };
 const fakeReadContext = {};
+const authOptions = {
+    requestContext: createSuperAdminContext(),
+    readMode: 'published',
+    readDocuments: vi.fn(),
+};
 const richTextValue = (label) => ({
     root: { type: 'root', children: [], _label: label },
 });
@@ -56,9 +62,15 @@ describe('embedRichTextFields', () => {
             data,
             embed,
             readContext: fakeReadContext,
+            ...authOptions,
             logger: noopLogger,
         });
         expect(embed).toHaveBeenCalledTimes(3);
+        expect(embed).toHaveBeenCalledWith(expect.objectContaining({
+            requestContext: authOptions.requestContext,
+            readMode: 'published',
+            readDocuments: authOptions.readDocuments,
+        }));
         const paths = embed.mock.calls.map((call) => call[0].fieldPath);
         expect(paths.sort()).toEqual(['body', 'faq.0.answer', 'meta.summary']);
     });
@@ -83,6 +95,7 @@ describe('embedRichTextFields', () => {
             data,
             embed,
             readContext: fakeReadContext,
+            ...authOptions,
             logger: noopLogger,
         });
         expect(embed).toHaveBeenCalledTimes(1);
@@ -116,6 +129,7 @@ describe('embedRichTextFields', () => {
             data,
             embed,
             readContext: fakeReadContext,
+            ...authOptions,
             logger,
         })).resolves.toBeUndefined();
         // All three leaves were attempted — the failure in 'second' did not
@@ -142,6 +156,7 @@ describe('embedRichTextFields', () => {
             data,
             embed,
             readContext: fakeReadContext,
+            ...authOptions,
             logger: noopLogger,
         });
         expect(embed).not.toHaveBeenCalled();

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

@@ -23,9 +23,10 @@
  * each call has a precise `fieldPath` for error messages and so future
  * adapters can implement per-leaf caching if needed.
  */
-import { type FieldSet, type RichTextField, type RichTextPopulateFn } from '../@types/field-types.js';
+import type { RequestContext } from '@byline/auth';
+import { type FieldSet, type RichTextField, type RichTextPopulateFn, type RichTextReadDocumentsFn } from '../@types/field-types.js';
 import type { CollectionDefinition } from '../@types/collection-types.js';
-import type { ReadContext } from '../@types/index.js';
+import type { IDbAdapter, ReadContext, ReadMode } from '../@types/index.js';
 /**
  * One rich-text leaf yielded by `collectRichTextLeaves`. The walker hands
  * back a reference to the *parent container* (`parent[key]`) rather than
@@ -61,6 +62,9 @@ export interface PopulateRichTextFieldsOptions {
     /** Registered server-side populate function from `ServerConfig`. */
     populate: RichTextPopulateFn;
     readContext: ReadContext;
+    requestContext: RequestContext;
+    readMode: ReadMode;
+    readDocuments: RichTextReadDocumentsFn;
 }
 /**
  * Resolve the effective `populateRelationsOnRead` for a richText field.
@@ -76,6 +80,20 @@ export declare function resolvePopulateOnRead(field: RichTextField): boolean;
  * is `true`. Mutates document `fields` in place.
  */
 export declare function populateRichTextFields(options: PopulateRichTextFieldsOptions): Promise<void>;
+/** Build the secure batch reader exposed to editor-agnostic adapters. */
+export declare function createRichTextDocumentReader(options: {
+    db: IDbAdapter;
+    collections: readonly CollectionDefinition[];
+    requestContext: RequestContext;
+    readContext: ReadContext;
+    readMode: ReadMode;
+    locale?: string;
+    bypassBeforeRead?: true;
+    /** Private cache domain explicitly shared with the originating client read. */
+    securityDomain?: object;
+    /** Adapter reused recursively for rich-text fields on target documents. */
+    richTextPopulate?: RichTextPopulateFn;
+}): RichTextReadDocumentsFn;
 /**
  * Which richtext server adapters the host has registered. Pass both
  * flags so the validator can fail-fast on each missing-adapter case

package/dist/services/richtext-populate.js

@@ -5,25 +5,12 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-/**
- * Richtext populate service — walks a reconstructed document, finds every
- * rich-text leaf (including those nested inside `group` / `array` /
- * `blocks` structures), gates each leaf by its `populateRelationsOnRead`
- * flag, and dispatches to the registered richtext populate adapter.
- *
- * Slots into the read pipeline alongside `populateDocuments`:
- *
- *   findDocuments → reconstruct → populateDocuments → populateRichTextFields → afterRead
- *
- * The same `ReadContext` flows through both populate phases, so dedup /
- * cycle protection / read-budget enforcement covers rich-text fan-out
- * automatically and any nested reads the adapter performs.
- *
- * The adapter is invoked once per leaf rather than once per document so
- * each call has a precise `fieldPath` for error messages and so future
- * adapters can implement per-leaf caching if needed.
- */
 import { isArrayField, isBlocksField, isGroupField, } from '../@types/field-types.js';
+import { bindReadContextAuthority, compileBeforeReadFilters } from '../auth/apply-before-read.js';
+import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
+import { resolveReadContextRoot } from '../auth/read-context-scope.js';
+import { ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION } from '../lib/errors.js';
+import { applyAfterRead } from './document-read.js';
 import { walkFieldTree } from './walk-field-tree.js';
 /**
  * Walk a field set and a matching reconstructed data tree in lockstep,
@@ -66,7 +53,7 @@ export function resolvePopulateOnRead(field) {
  * is `true`. Mutates document `fields` in place.
  */
 export async function populateRichTextFields(options) {
-    const { fields, collectionPath, documents, populate, readContext } = options;
+    const { fields, collectionPath, documents, populate, readContext, requestContext, readMode, readDocuments, } = options;
     for (const doc of documents) {
         const docFields = (doc.fields ?? {});
         for (const leaf of collectRichTextLeaves(fields, docFields)) {
@@ -77,10 +64,164 @@ export async function populateRichTextFields(options) {
                 fieldPath: leaf.fieldPath,
                 collectionPath,
                 readContext,
+                requestContext,
+                readMode,
+                readDocuments,
             });
         }
     }
 }
+/** Build the secure batch reader exposed to editor-agnostic adapters. */
+export function createRichTextDocumentReader(options) {
+    const { db, collections, requestContext, readContext, readMode, locale, bypassBeforeRead, richTextPopulate, } = options;
+    const securityDomain = options.securityDomain ?? {};
+    const state = getRichTextReaderState(readContext);
+    const read = async ({ collectionPath, documentIds, fields }) => {
+        bindReadContextAuthority(readContext, requestContext);
+        if (documentIds.length === 0)
+            return [];
+        const definition = collections.find((candidate) => candidate.path === collectionPath);
+        if (definition == null) {
+            throw ERR_VALIDATION({
+                message: `richtext target collection '${collectionPath}' is not registered`,
+                details: { collectionPath },
+            });
+        }
+        assertActorCanPerform(requestContext, collectionPath, 'read');
+        let filters;
+        if (!bypassBeforeRead) {
+            filters = await compileBeforeReadFilters({
+                definition,
+                requestContext,
+                readContext,
+                securityDomain,
+                parseContext: {
+                    collections,
+                    resolveCollectionId: async (path) => {
+                        const row = await db.queries.collections.getCollectionByPath(path);
+                        return row?.id ?? '';
+                    },
+                },
+            });
+        }
+        const collection = await db.queries.collections.getCollectionByPath(collectionPath);
+        if (collection?.id == null) {
+            throw ERR_VALIDATION({
+                message: `richtext target collection '${collectionPath}' is not available`,
+                details: { collectionPath },
+            });
+        }
+        const collectionId = collection.id;
+        const projection = fields == null ? '*' : [...fields].sort().join(',');
+        const resultById = new Map();
+        const idsToFetch = [];
+        for (const documentId of new Set(documentIds)) {
+            const key = richTextMaterializationKey(collectionId, documentId, requestContext.requestId, locale, readMode, projection);
+            if (state.cache.has(key)) {
+                const cached = state.cache.get(key);
+                if (cached != null)
+                    resultById.set(documentId, cached);
+            }
+            else if (!state.active.has(`${collectionId}:${documentId}`)) {
+                idsToFetch.push(documentId);
+            }
+        }
+        if (idsToFetch.length > 0) {
+            const fetched = (await db.queries.documents.getDocumentsByDocumentIds({
+                collection_id: collectionId,
+                document_ids: idsToFetch,
+                fields,
+                readMode,
+                locale,
+                filters: filters && filters.length > 0 ? filters : undefined,
+            }));
+            const fetchedById = new Map(fetched
+                .filter((doc) => typeof doc.document_id === 'string')
+                .map((doc) => [doc.document_id, doc]));
+            for (const documentId of idsToFetch) {
+                const materializationKey = richTextMaterializationKey(collectionId, documentId, requestContext.requestId, locale, readMode, projection);
+                // Earlier items in this batch may recursively populate a later target.
+                // Honour that completed/active state rather than reprocessing the stale
+                // raw row captured by the outer batch and overwriting its redacted cache.
+                if (state.cache.has(materializationKey)) {
+                    const cached = state.cache.get(materializationKey);
+                    if (cached != null)
+                        resultById.set(documentId, cached);
+                    continue;
+                }
+                const documentKey = `${collectionId}:${documentId}`;
+                if (state.active.has(documentKey))
+                    continue;
+                const doc = fetchedById.get(documentId);
+                if (doc == null) {
+                    state.cache.set(materializationKey, null);
+                    continue;
+                }
+                state.active.add(documentKey);
+                readContext.visited.add(documentKey);
+                try {
+                    readContext.readCount += 1;
+                    if (readContext.readCount > readContext.maxReads) {
+                        throw ERR_READ_BUDGET_EXCEEDED({
+                            message: `richtext populate exceeded read budget (maxReads=${readContext.maxReads})`,
+                            details: {
+                                readCount: readContext.readCount,
+                                maxReads: readContext.maxReads,
+                                targetCollectionId: collectionId,
+                                targetDocumentId: documentId,
+                            },
+                        });
+                    }
+                    if (richTextPopulate) {
+                        await populateRichTextFields({
+                            fields: definition.fields,
+                            collectionPath,
+                            documents: [doc],
+                            populate: richTextPopulate,
+                            readContext,
+                            requestContext,
+                            readMode,
+                            readDocuments: read,
+                        });
+                    }
+                    await applyAfterRead({
+                        doc,
+                        definition,
+                        readContext,
+                        requestContext,
+                        locale,
+                        readMode,
+                        projection: fields,
+                        materialization: 'richtext-target',
+                    });
+                    state.cache.set(materializationKey, doc);
+                    resultById.set(documentId, doc);
+                }
+                finally {
+                    state.active.delete(documentKey);
+                }
+            }
+        }
+        return documentIds.flatMap((documentId) => {
+            const doc = resultById.get(documentId);
+            return doc == null ? [] : [doc];
+        });
+    };
+    return read;
+}
+const richTextReaderStates = new WeakMap();
+function getRichTextReaderState(readContext) {
+    const root = resolveReadContextRoot(readContext);
+    const existing = richTextReaderStates.get(root);
+    if (existing)
+        return existing;
+    const state = { active: new Set(), cache: new Map() };
+    richTextReaderStates.set(root, state);
+    return state;
+}
+function richTextMaterializationKey(collectionId, documentId, requestId, locale, readMode, projection) {
+    return `${collectionId}:${documentId}:${requestId}:${locale ?? 'all'}:${readMode}:${projection}`;
+}
 // ---------------------------------------------------------------------------
 // Boot-time validation
 // ---------------------------------------------------------------------------