@focus-reactive/payload-plugin-translator 0.4.0 → 0.5.1

package/dist/server/shared/field-traversal/walkFields.js

@@ -0,0 +1,164 @@
+import { classifyField, tabScopes } from "./kernel";
+/**
+ * Internal engine backing {@link walkFields}. Methods return `true` to mean "stop requested —
+ * unwind and halt the entire walk". A class is used (over nested functions) because the three
+ * steps are mutually recursive; methods can reference each other without use-before-define
+ * ordering.
+ *
+ * @internal
+ */ class FieldTreeWalker {
+    walker;
+    constructor(walker){
+        this.walker = walker;
+    }
+    run(fields, root) {
+        const out = [];
+        if (this.level(fields, root, out)) return undefined;
+        return this.walker.combine({
+            kind: "root",
+            field: null
+        }, out, root);
+    }
+    /** Walk one data level (root, a group/tab body, or a list element), pushing child outputs into `out`. */ level(fields, cursor, out) {
+        for (const field of fields){
+            const structure = classifyField(field);
+            switch(structure.kind){
+                case "presentational":
+                    break;
+                case "transparent":
+                    if (this.level(structure.fields, cursor, out)) return true;
+                    break;
+                case "tabs":
+                    for (const scope of tabScopes(structure.field)){
+                        if (scope.named) {
+                            if (this.object(scope.tab, scope.tab.name, scope.tab.fields, cursor, out)) return true;
+                        } else if (this.level(scope.fields, cursor, out)) {
+                            return true;
+                        }
+                    }
+                    break;
+                case "group":
+                    if (this.object(structure.field, structure.name, structure.fields, cursor, out)) return true;
+                    break;
+                case "array":
+                case "blocks":
+                    if (this.list(structure.field, structure.name, cursor, out)) return true;
+                    break;
+                case "leaf":
+                    {
+                        const leafOut = this.walker.leaf(structure.field, cursor);
+                        if (leafOut !== undefined) out.push({
+                            key: structure.name,
+                            out: leafOut
+                        });
+                        break;
+                    }
+                default:
+                    {
+                        // Exhaustiveness guard: if a new FieldStructure kind is added, this errors at compile time.
+                        const exhaustive = structure;
+                        throw new Error(`unhandled field structure: ${String(exhaustive)}`);
+                    }
+            }
+        }
+        return false;
+    }
+    /** Descend a single-object boundary (named group or named tab) and assemble it. */ object(field, key, childFields, cursor, out) {
+        const result = this.walker.enterObject(field, cursor);
+        if (result === "stop") return true;
+        if (result === "skip") return false;
+        const childOut = [];
+        if (this.level(childFields, result, childOut)) return true;
+        const assembled = this.walker.combine({
+            kind: "object",
+            field,
+            key
+        }, childOut, result);
+        if (assembled !== undefined) out.push({
+            key,
+            out: assembled
+        });
+        return false;
+    }
+    /** Descend an array/blocks boundary, assembling each element then the list itself. */ list(field, key, cursor, out) {
+        const result = this.walker.enterList(field, cursor);
+        if (result === "stop") return true;
+        if (result === "skip") return false;
+        const elements = [];
+        for (const child of result){
+            const childOut = [];
+            if (this.level(child.fields, child.cursor, childOut)) return true;
+            const elementOut = this.walker.combine({
+                kind: "element",
+                field,
+                key: child.key
+            }, childOut, child.cursor);
+            if (elementOut !== undefined) elements.push({
+                key: child.key,
+                out: elementOut
+            });
+        }
+        const listOut = this.walker.combine({
+            kind: "list",
+            field,
+            key
+        }, elements, cursor);
+        if (listOut !== undefined) out.push({
+            key,
+            out: listOut
+        });
+        return false;
+    }
+}
+/**
+ * Depth-first walk of a Payload field **schema**, driving a caller-supplied
+ * {@link FieldWalker}. The single traversal engine this package's data operations build on
+ * (filtering, reconciling, collecting, navigating).
+ *
+ * The engine owns structural dispatch (via {@link classifyField} / {@link tabScopes}) and the
+ * recursion; the caller owns the **data** through the opaque `Cursor` and decides what to
+ * produce. The engine never reads the cursor — so the caller can thread one, two, or more
+ * parallel data trees (plus a path) inside it. Containers are assembled bottom-up via
+ * `combine`, after their children.
+ *
+ * @template Cursor - The caller's data position threaded through the walk (e.g. the current
+ * data object, a `{ source, target }` pair, plus a path). Constrained to `object` so a cursor
+ * can never collide with a {@link WalkSignal} string (`'skip'`/`'stop'`).
+ * @template Out - What the walker produces per node and assembles per container (e.g. a
+ * rebuilt data subtree, or `void` for a collect-only walk).
+ *
+ * @param fields - The schema to walk (a collection/global/group `fields` array).
+ * @param root - The initial `Cursor` paired with the top-level `fields`.
+ * @param walker - The behavior to drive: `enterObject` / `enterList` derive child cursors (or
+ * return a {@link WalkSignal} to `'skip'` a branch or `'stop'` the whole walk), `leaf`
+ * produces a value per data-affecting leaf, and `combine` assembles each container from its
+ * children.
+ * @returns The root `combine` output. `undefined` if the walk was halted by `'stop'` before the
+ * root assembled, OR if the root `combine` itself returned `undefined` (e.g. a collect-only
+ * walker). To distinguish "stopped" from "empty result", track it via the cursor, not this value.
+ *
+ * @example
+ * Keep only localized leaves and rebuild the data tree (a "filter" walk):
+ * ```ts
+ * type Cursor = { data: Record<string, unknown> };
+ *
+ * const filtered = walkFields<Cursor, unknown>(schema, { data }, {
+ *   enterObject: (field, c) =>
+ *     isRecord(c.data[field.name]) ? { data: c.data[field.name] } : "skip",
+ *   enterList: (field, c) => toItemCursors(field, c), // one ChildCursor per element
+ *   leaf: (field, c) => (field.localized ? c.data[field.name] : undefined),
+ *   combine: (container, children) => {
+ *     if (children.length === 0) return undefined; // drop empty containers
+ *     if (container.kind === "list") return children.map((ch) => ch.out);
+ *     return Object.fromEntries(children.map((ch) => [ch.key, ch.out]));
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link FieldWalker} for the full visitor contract and the caller shapes it subsumes.
+ * @public
+ */ export function walkFields(fields, root, walker) {
+    return new FieldTreeWalker(walker).run(fields, root);
+}
+
+//# sourceMappingURL=walkFields.js.map

package/dist/server/shared/utils/filterLocalizedFields.d.ts

@@ -1,7 +1,7 @@
-import type { Field } from 'payload';
+import type { Field } from "payload";
 /**
- * Filters data to keep only translatable localized fields.
- * For container fields (group, array, blocks) recursively filters nested data.
+ * Filters data to keep only translatable localized fields, recursively for container fields
+ * (group, array, blocks, named tabs). Built on the shared {@link walkFields} engine.
  *
  * @param schema - Payload field schema (original, not sanitized)
  * @param data - Document data to filter

package/dist/server/shared/utils/filterLocalizedFields.js

@@ -1,72 +1,61 @@
-import { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType } from 'payload/shared';
-import { hasFields, isBlockItem, isLocalizedField, isTabsField, isTranslatableField } from '../guards';
-import { isObject } from './isObject';
-import { isEmpty } from './isEmpty';
+import { resolveBlockFields, walkFields } from "../field-traversal";
+import { isLocalizedField, isTranslatableField } from "../guards";
+import { isObject } from "./isObject";
 /**
- * Filters data to keep only translatable localized fields.
- * For container fields (group, array, blocks) recursively filters nested data.
+ * Filter walker: keeps only translatable, localized leaves, rebuilding the surrounding
+ * object/array/blocks structure and dropping any container left empty. `id` (array/block
+ * elements) and `blockType` (block elements) are preserved since they aren't schema fields.
+ */ const filterWalker = {
+    enterObject (field, cursor) {
+        const value = cursor.data[field.name];
+        return isObject(value) ? {
+            data: value
+        } : "skip";
+    },
+    enterList (field, cursor) {
+        const value = cursor.data[field.name];
+        if (!Array.isArray(value)) return "skip";
+        const children = [];
+        value.forEach((item, index)=>{
+            if (!isObject(item)) return; // drop non-object elements
+            const fields = field.type === "blocks" ? resolveBlockFields(field, item) : field.fields;
+            if (fields) children.push({
+                cursor: {
+                    data: item
+                },
+                fields,
+                key: index
+            }); // unknown blockType → fields null → drop
+        });
+        return children;
+    },
+    leaf (field, cursor) {
+        return isTranslatableField(field) && isLocalizedField(field) ? cursor.data[field.name] : undefined;
+    },
+    combine (container, children, cursor) {
+        if (children.length === 0) return undefined; // drop empty containers/lists
+        if (container.kind === "list") return children.map((child)=>child.out);
+        const result = {};
+        for (const child of children)result[child.key] = child.out;
+        if (container.kind === "element") {
+            const item = cursor.data;
+            if (item.id !== undefined) result.id = item.id;
+            if (container.field.type === "blocks") result.blockType = item.blockType;
+        }
+        return result;
+    }
+};
+/**
+ * Filters data to keep only translatable localized fields, recursively for container fields
+ * (group, array, blocks, named tabs). Built on the shared {@link walkFields} engine.
  *
  * @param schema - Payload field schema (original, not sanitized)
  * @param data - Document data to filter
  * @returns Filtered data containing only translatable localized fields
  */ export function filterLocalizedFields(schema, data) {
-    const result = {};
-    for (const field of schema){
-        if (isTabsField(field)) {
-            for (const tab of field.tabs){
-                if (hasFields(tab)) Object.assign(result, filterLocalizedFields(tab.fields, data));
-            }
-            continue;
-        }
-        if (!fieldAffectsData(field)) {
-            if (hasFields(field)) Object.assign(result, filterLocalizedFields(field.fields, data));
-            continue;
-        }
-        const value = data[field.name];
-        if (value === undefined) continue;
-        if (fieldIsGroupType(field) && isObject(value)) {
-            const filtered = filterLocalizedFields(field.fields, value);
-            if (!isEmpty(filtered)) result[field.name] = filtered;
-            continue;
-        }
-        if (fieldIsArrayType(field) && Array.isArray(value)) {
-            const filteredArray = value.map((item)=>{
-                if (isObject(item)) {
-                    const filtered = filterLocalizedFields(field.fields, item);
-                    if (!isEmpty(filtered)) return {
-                        ...filtered,
-                        id: item.id
-                    };
-                }
-                return null;
-            }).filter(Boolean);
-            if (!isEmpty(filteredArray)) result[field.name] = filteredArray;
-            continue;
-        }
-        if (fieldIsBlockType(field) && Array.isArray(value)) {
-            const filteredBlocks = value.map((item)=>{
-                if (isBlockItem(item)) {
-                    const block = field.blocks.find((b)=>b.slug === item.blockType);
-                    if (block) {
-                        const filtered = filterLocalizedFields(block.fields, item);
-                        if (!isEmpty(filtered)) return {
-                            ...filtered,
-                            blockType: item.blockType,
-                            id: item.id
-                        };
-                    }
-                }
-                return null;
-            }).filter(Boolean);
-            if (!isEmpty(filteredBlocks)) result[field.name] = filteredBlocks;
-            continue;
-        }
-        if (isTranslatableField(field) && isLocalizedField(field)) {
-            result[field.name] = value;
-            continue;
-        }
-    }
-    return result;
+    return walkFields(schema, {
+        data
+    }, filterWalker) ?? {};
 }
 
 //# sourceMappingURL=filterLocalizedFields.js.map

package/dist/types/AccessGuard.d.ts

@@ -1,10 +1,33 @@
-import type { BasePayload, TypedUser } from 'payload';
+import type { BasePayload, TypedUser } from "payload";
+/**
+ * The request context an {@link AccessGuard} receives when deciding whether to
+ * allow a translation API call.
+ */
 export type AccessGuardRequest = {
+    /** Incoming request headers (e.g. for token/cookie checks). */
     headers: Headers;
+    /** The authenticated user, or `null`/`undefined` if the request is anonymous. */
     user?: TypedUser | null;
+    /** The Payload instance, for any DB/permission lookups the guard needs. */
     payload: BasePayload;
 };
+/**
+ * Gate for the translation API endpoints. Provide one via `translatorPlugin({ access })`
+ * to control who may trigger translations; omit it to leave the endpoints open.
+ *
+ * @example
+ * ```ts
+ * const adminsOnly: AccessGuard = {
+ *   check: ({ req }) => req.user?.role === 'admin',
+ * }
+ * translatorPlugin({ collections, translationProvider, runner, access: adminsOnly })
+ * ```
+ */
 export interface AccessGuard {
+    /**
+     * Return `true` to allow the request, `false` to reject it with `403 Forbidden`.
+     * May be async (e.g. to query permissions).
+     */
     check<R extends AccessGuardRequest>({ req }: {
         req: R;
     }): Promise<boolean> | boolean;

package/dist/types/AccessGuard.js

@@ -1,3 +1,14 @@
-export { };
+/**
+ * Gate for the translation API endpoints. Provide one via `translatorPlugin({ access })`
+ * to control who may trigger translations; omit it to leave the endpoints open.
+ *
+ * @example
+ * ```ts
+ * const adminsOnly: AccessGuard = {
+ *   check: ({ req }) => req.user?.role === 'admin',
+ * }
+ * translatorPlugin({ collections, translationProvider, runner, access: adminsOnly })
+ * ```
+ */ export { };
 
 //# sourceMappingURL=AccessGuard.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@focus-reactive/payload-plugin-translator",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Translation plugin for Payload CMS 3.x. Automatically translate your localized content using any translation provider.",
   "type": "module",
   "license": "MIT",
@@ -55,7 +55,7 @@
     "lint:fix": "ultracite fix",
     "test": "vitest run",
     "test:watch": "vitest",
-    "check-types": "tsgo --noEmit"
+    "check-types": "tsgo --noEmit -p tsconfig.check.json"
   },
   "peerDependencies": {
     "@payloadcms/richtext-lexical": "^3.76.0",