@byline/core 3.19.0 → 3.20.1

package/dist/@types/field-types.d.ts

@@ -221,6 +221,46 @@ interface BaseField {
      * `optional: true` or a `defaultValue`.
      */
     condition?: FieldCondition;
+    /**
+     * When `true`, the field is **virtual**: its value participates in the
+     * editing session and the write pipeline, but is **never persisted** and
+     * therefore never read back.
+     *
+     * Lifecycle of a virtual value:
+     *
+     *   1. The admin renders and edits the field normally; its value travels
+     *      with the save (as `field.set` patches / document data) like any
+     *      other field.
+     *   2. Every lifecycle hook sees it — `beforeCreate` / `beforeUpdate`
+     *      (and the `after*` counterparts) receive the in-flight `data` with
+     *      virtual values present, so hooks can act on them (the canonical
+     *      use case: a "generate thumbnail" checkbox that triggers cover
+     *      generation during the save).
+     *   3. The storage layer's flatten step skips virtual fields wholesale —
+     *      no `store_*` row is ever written. This is the single enforcement
+     *      point; adapters implementing `IDbAdapter` MUST honour it (see
+     *      `@byline/db-postgres` → storage-flatten).
+     *   4. Reads reconstruct from stored rows, so the value is structurally
+     *      absent afterwards: the next editing session starts with the field
+     *      empty / at its `defaultValue`, and saves that don't touch it can
+     *      never re-trigger whatever side effect it drives.
+     *
+     * Applies at any nesting depth — a virtual field inside an `array` item
+     * `group` (e.g. `files[].filesGroup.generateThumbnail`) is skipped per
+     * item. Setting `virtual` on a structure field (`group` / `array` /
+     * `blocks`) omits the entire subtree.
+     *
+     * Constraints (enforced at boot by `validateCollections`):
+     *   - A virtual field must be `optional: true` **or** declare a
+     *     `defaultValue` — the value is absent on every read, so a required
+     *     virtual field could never validate on a subsequent save.
+     *   - `counter` fields cannot be virtual (allocator-owned).
+     *   - Upload-capable `file` / `image` fields cannot be virtual (their
+     *     stored bytes are a side effect that "not persisting" can't undo).
+     *   - Fields referenced by `useAsTitle` / `useAsPath` / `search` cannot
+     *     be virtual (those subsystems read persisted values).
+     */
+    virtual?: boolean;
     /**
      * Optional submit-time validator. Called by `validateForm()` for every field
      * type — including structure fields (group, array, blocks).

package/dist/config/validate-collections.d.ts

@@ -33,6 +33,9 @@ export declare const RESERVED_FIELD_NAMES: ReadonlySet<string>;
  *  - A collection may not set both `tree: true` and `orderable: true`. A
  *    document-tree owns ordering per-parent on the tree edge, so
  *    `byline_documents.order_key` is inert for it.
+ *  - `virtual` fields must satisfy the constraints in
+ *    {@link validateVirtualFields} (optional-or-default, no counters, no
+ *    upload fields, not referenced by useAsTitle / useAsPath / search).
  *
  * Throws a plain `Error` (not a `BylineError`) because configuration
  * validation runs at startup, before the logger and error registry are

package/dist/config/validate-collections.js

@@ -64,6 +64,103 @@ function walkFields(fields, visit) {
         }
     }
 }
+/**
+ * Path-aware variant of `walkFields` — visits every field with its dotted
+ * schema path (e.g. `files.filesGroup.generateThumbnail`) so validation
+ * errors can point at the exact declaration site.
+ */
+function walkFieldsWithPath(fields, visit, prefix = '') {
+    for (const field of fields) {
+        const fieldPath = prefix === '' ? field.name : `${prefix}.${field.name}`;
+        visit(field, fieldPath);
+        if (field.type === 'group' || field.type === 'array') {
+            walkFieldsWithPath(field.fields, visit, fieldPath);
+        }
+        else if (field.type === 'blocks') {
+            for (const block of field.blocks) {
+                walkFieldsWithPath(block.fields, visit, fieldPath);
+            }
+        }
+    }
+}
+/**
+ * Top-level field names a collection's `search` config references (body +
+ * facets + filters). Used to reject `virtual` on searchable fields —
+ * search indexing reads persisted values, which virtual fields never have.
+ */
+function searchReferencedFieldNames(collection) {
+    const names = new Set();
+    const search = collection.search;
+    if (search == null)
+        return names;
+    for (const decl of search.body ?? []) {
+        names.add(typeof decl === 'string' ? decl : decl.field);
+    }
+    for (const decl of search.facets ?? []) {
+        names.add(typeof decl === 'string' ? decl : decl.field);
+    }
+    for (const name of search.filters ?? []) {
+        names.add(name);
+    }
+    return names;
+}
+/**
+ * Enforce the `virtual` field constraints for one collection. See
+ * `BaseField.virtual` in field-types.ts for the contract these rules back:
+ *
+ *   - virtual ⇒ `optional: true` OR a `defaultValue` — the value is absent
+ *     on every read, so a required virtual field could never validate on a
+ *     subsequent save.
+ *   - `counter` fields cannot be virtual (allocator-assigned, and the
+ *     lifecycle layer must be able to carry the value forward).
+ *   - Upload-capable `file` / `image` fields cannot be virtual — their
+ *     stored bytes are a side effect that "not persisting" can't undo.
+ *   - Fields referenced by `useAsTitle` / `useAsPath` / `search` cannot be
+ *     virtual — those subsystems read persisted values.
+ */
+function validateVirtualFields(collection) {
+    const searchNames = searchReferencedFieldNames(collection);
+    walkFieldsWithPath(collection.fields, (field, fieldPath) => {
+        if (field.virtual !== true)
+            return;
+        const hasDefault = 'defaultValue' in field && field.defaultValue !== undefined;
+        if (field.optional !== true && !hasDefault) {
+            throw new Error(`Collection "${collection.path}" declares virtual field "${fieldPath}" without ` +
+                '`optional: true` or a `defaultValue`. Virtual values are never persisted, so the ' +
+                'field is absent on every read — a required virtual field could never validate on a ' +
+                'subsequent save.');
+        }
+        if (field.type === 'counter') {
+            throw new Error(`Collection "${collection.path}" declares virtual counter field "${fieldPath}". ` +
+                'Counter values are allocator-assigned and carried forward across versions — they ' +
+                'cannot be virtual.');
+        }
+        if ((field.type === 'file' || field.type === 'image') && field.upload != null) {
+            throw new Error(`Collection "${collection.path}" declares virtual upload field "${fieldPath}". ` +
+                'Upload fields write bytes to storage as a side effect, which "not persisting" the ' +
+                'field value cannot undo — remove `virtual` or the `upload` block.');
+        }
+        // Collection-level directives read persisted values; a virtual source
+        // would resolve to nothing on every read. These only apply to top-level
+        // fields (nested paths never match a directive's field name).
+        const isTopLevel = !fieldPath.includes('.');
+        if (isTopLevel) {
+            if (collection.useAsTitle === field.name) {
+                throw new Error(`Collection "${collection.path}" sets \`useAsTitle: '${field.name}'\` but that field ` +
+                    'is virtual — titles are read from persisted values.');
+            }
+            if (collection.useAsPath === field.name) {
+                throw new Error(`Collection "${collection.path}" sets \`useAsPath: '${field.name}'\` but that field ` +
+                    'is virtual — paths are derived from persisted values.');
+            }
+            if (searchNames.has(field.name)) {
+                throw new Error(`Collection "${collection.path}" references virtual field "${field.name}" in its ` +
+                    '`search` config — search indexing reads persisted values, which virtual fields ' +
+                    'never have.');
+            }
+        }
+    });
+}
 /**
  * Validate every collection in a configuration.
  *
@@ -83,6 +180,9 @@ function walkFields(fields, visit) {
  *  - A collection may not set both `tree: true` and `orderable: true`. A
  *    document-tree owns ordering per-parent on the tree edge, so
  *    `byline_documents.order_key` is inert for it.
+ *  - `virtual` fields must satisfy the constraints in
+ *    {@link validateVirtualFields} (optional-or-default, no counters, no
+ *    upload fields, not referenced by useAsTitle / useAsPath / search).
  *
  * Throws a plain `Error` (not a `BylineError`) because configuration
  * validation runs at startup, before the logger and error registry are
@@ -111,5 +211,6 @@ export function validateCollections(collections) {
         if (collection.tree === true && collection.orderable === true) {
             throw new Error(`Collection "${collection.path}" sets both \`tree: true\` and \`orderable: true\`. A document-tree collection owns ordering on the tree edge (per-parent), so \`byline_documents.order_key\` is inert — set only \`tree: true\`.`);
         }
+        validateVirtualFields(collection);
     }
 }

package/dist/config/validate-collections.test.node.js

@@ -260,4 +260,154 @@ describe('validateCollections', () => {
         };
         expect(() => validateCollections([collection])).not.toThrow();
     });
+    // -------------------------------------------------------------------------
+    // Virtual fields
+    // -------------------------------------------------------------------------
+    it('accepts an optional virtual field', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                {
+                    name: 'regenerate',
+                    label: 'Regenerate',
+                    type: 'checkbox',
+                    virtual: true,
+                    optional: true,
+                },
+            ],
+        };
+        expect(() => validateCollections([collection])).not.toThrow();
+    });
+    it('accepts a virtual field with a defaultValue', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'page', label: 'Page', type: 'integer', virtual: true, defaultValue: 1 },
+            ],
+        };
+        expect(() => validateCollections([collection])).not.toThrow();
+    });
+    it('rejects a required virtual field with no defaultValue', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'regenerate', label: 'Regenerate', type: 'checkbox', virtual: true },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/virtual field "regenerate".*optional.*defaultValue/s);
+    });
+    it('rejects a required virtual field nested in an array group — error names the full path', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                {
+                    name: 'files',
+                    label: 'Files',
+                    type: 'array',
+                    fields: [
+                        {
+                            name: 'filesGroup',
+                            type: 'group',
+                            fields: [
+                                { name: 'generateThumbnail', label: 'Generate', type: 'checkbox', virtual: true },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/files\.filesGroup\.generateThumbnail/);
+    });
+    it('rejects a virtual counter field', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                {
+                    name: 'serial',
+                    label: 'Serial',
+                    type: 'counter',
+                    group: 'serials',
+                    virtual: true,
+                    optional: true,
+                },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/virtual counter field/);
+    });
+    it('rejects a virtual upload-capable file field', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                {
+                    name: 'attachment',
+                    label: 'Attachment',
+                    type: 'file',
+                    virtual: true,
+                    optional: true,
+                    upload: { mimeTypes: ['application/pdf'] },
+                },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/virtual upload field/);
+    });
+    it('accepts a virtual file field WITHOUT an upload block', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'scratchFile', label: 'Scratch', type: 'file', virtual: true, optional: true },
+            ],
+        };
+        expect(() => validateCollections([collection])).not.toThrow();
+    });
+    it('rejects useAsTitle pointing at a virtual field', () => {
+        const collection = {
+            ...baseCollection,
+            useAsTitle: 'ephemeral',
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'ephemeral', label: 'Ephemeral', type: 'text', virtual: true, optional: true },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/useAsTitle.*virtual/s);
+    });
+    it('rejects useAsPath pointing at a virtual field', () => {
+        const collection = {
+            ...baseCollection,
+            useAsPath: 'ephemeral',
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'ephemeral', label: 'Ephemeral', type: 'text', virtual: true, optional: true },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/useAsPath.*virtual/s);
+    });
+    it('rejects a search body entry referencing a virtual field', () => {
+        const collection = {
+            ...baseCollection,
+            search: { body: ['title', 'ephemeral'] },
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'ephemeral', label: 'Ephemeral', type: 'text', virtual: true, optional: true },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/search/);
+    });
+    it('accepts a virtual field that search does not reference', () => {
+        const collection = {
+            ...baseCollection,
+            search: { body: ['title'] },
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                { name: 'ephemeral', label: 'Ephemeral', type: 'text', virtual: true, optional: true },
+            ],
+        };
+        expect(() => validateCollections([collection])).not.toThrow();
+    });
 });

package/dist/patches/apply-patches.js

@@ -218,6 +218,28 @@ function resolveArrayAtPath(doc, path) {
     }
     return parent[key];
 }
+/**
+ * Resolve an `itemId` to an array index: stable `_id` match first, then —
+ * only when `itemId` is a *pure* integer string — an index fallback for
+ * items that have no stable id yet (e.g. added client-side by an older
+ * admin that did not assign `_id` at add time). The strict `^\d+$` test
+ * matters: `Number.parseInt` accepts leading digits, so a real-but-absent
+ * uuid like `'3f2a…'` would otherwise silently resolve to index 3 and the
+ * patch would hit the wrong item.
+ *
+ * Returns -1 when the item cannot be located either way.
+ */
+function resolveItemIndex(array, itemId) {
+    const byId = array.findIndex((item) => item && item._id === itemId);
+    if (byId !== -1)
+        return byId;
+    if (/^\d+$/.test(itemId)) {
+        const index = Number.parseInt(itemId, 10);
+        if (index >= 0 && index < array.length)
+            return index;
+    }
+    return -1;
+}
 function applyArrayPatch(doc, patch, definition) {
     const array = resolveArrayAtPath(doc, patch.path);
     if (patch.kind === 'array.insert') {
@@ -225,10 +247,8 @@ function applyArrayPatch(doc, patch, definition) {
         array.splice(index, 0, patch.item);
     }
     else if (patch.kind === 'array.move') {
-        const currentIndex = array.findIndex((item) => item && item._id === patch.itemId);
-        // Fallback for arrays without stable ids: treat itemId as an index
-        const index = currentIndex === -1 ? Number.parseInt(patch.itemId, 10) : currentIndex;
-        if (!Number.isFinite(index) || index < 0 || index >= array.length) {
+        const index = resolveItemIndex(array, patch.itemId);
+        if (index === -1) {
             throw new Error(`array.move: item with idOrIndex=${patch.itemId} not found`);
         }
         const [moved] = array.splice(index, 1);
@@ -236,8 +256,13 @@ function applyArrayPatch(doc, patch, definition) {
         array.splice(toIndex, 0, moved);
     }
     else if (patch.kind === 'array.remove') {
-        const index = array.findIndex((item) => item && item._id === patch.itemId);
+        const index = resolveItemIndex(array, patch.itemId);
         if (index === -1) {
+            // Removal is idempotent — an item that is already gone stays gone.
+            // (Historically this branch also swallowed a client bug where the
+            // admin sent a positional id for `_id`-carrying items; the admin now
+            // sends `_id` and the index fallback above covers id-less items, so
+            // reaching here should be rare.)
             return;
         }
         array.splice(index, 1);

package/dist/patches/patch.test.node.js

@@ -156,6 +156,86 @@ describe('applyPatches', () => {
         const moved = afterMove;
         expect(moved.reviews.map((r) => r._id)).toEqual(['c', 'a', 'b']);
     });
+    it('array.remove removes an item by stable _id', () => {
+        const original = {
+            reviews: [
+                { _id: 'a', rating: 3 },
+                { _id: 'b', rating: 4 },
+                { _id: 'c', rating: 5 },
+            ],
+        };
+        const { doc, errors } = applyPatches(DocsDefinition, original, [
+            { kind: 'array.remove', path: 'reviews', itemId: 'b' },
+        ]);
+        expect(errors).toHaveLength(0);
+        const result = doc;
+        expect(result.reviews.map((r) => r._id)).toEqual(['a', 'c']);
+    });
+    it('array.remove falls back to a positional index for items without stable ids', () => {
+        // Regression: an admin session can add an item (no _id yet) and remove
+        // it in the same save; the remove patch carries the item's index. This
+        // previously no-opped silently and the "removed" item reappeared.
+        const original = {
+            reviews: [{ rating: 3 }, { rating: 4 }, { rating: 5 }],
+        };
+        const { doc, errors } = applyPatches(DocsDefinition, original, [
+            { kind: 'array.remove', path: 'reviews', itemId: '1' },
+        ]);
+        expect(errors).toHaveLength(0);
+        const result = doc;
+        expect(result.reviews.map((r) => r.rating)).toEqual([3, 5]);
+    });
+    it('array.remove of a missing itemId is an idempotent no-op', () => {
+        const original = {
+            reviews: [{ _id: 'a', rating: 3 }],
+        };
+        const { doc, errors } = applyPatches(DocsDefinition, original, [
+            { kind: 'array.remove', path: 'reviews', itemId: 'gone' },
+        ]);
+        expect(errors).toHaveLength(0);
+        expect(doc.reviews).toHaveLength(1);
+    });
+    it('does NOT misread a digit-prefixed uuid as an index (strict integer fallback)', () => {
+        // Number.parseInt('3f2a…') === 3 — a real-but-absent _id starting with
+        // digits must not resolve to a positional index and hit the wrong item.
+        const original = {
+            reviews: [
+                { _id: 'a', rating: 1 },
+                { _id: 'b', rating: 2 },
+                { _id: 'c', rating: 3 },
+                { _id: 'd', rating: 4 },
+            ],
+        };
+        const removeResult = applyPatches(DocsDefinition, original, [
+            { kind: 'array.remove', path: 'reviews', itemId: '3f2a09c1-dead-beef-0000-000000000000' },
+        ]);
+        expect(removeResult.errors).toHaveLength(0);
+        // Nothing removed — in particular NOT the item at index 3.
+        expect(removeResult.doc.reviews).toHaveLength(4);
+        const moveResult = applyPatches(DocsDefinition, original, [
+            {
+                kind: 'array.move',
+                path: 'reviews',
+                itemId: '3f2a09c1-dead-beef-0000-000000000000',
+                toIndex: 0,
+            },
+        ]);
+        // array.move keeps its throw-on-missing contract.
+        expect(moveResult.errors).toHaveLength(1);
+        expect(moveResult.errors[0]?.message).toContain('not found');
+    });
+    it('array.insert followed by array.remove of the same _id within one patch batch', () => {
+        // Mirrors the admin flow after the fix: add assigns _id client-side, so
+        // add-then-remove in a single editing session round-trips cleanly.
+        const original = { reviews: [{ _id: 'a', rating: 3 }] };
+        const { doc, errors } = applyPatches(DocsDefinition, original, [
+            { kind: 'array.insert', path: 'reviews', index: 1, item: { _id: 'new-1', rating: 5 } },
+            { kind: 'array.remove', path: 'reviews', itemId: 'new-1' },
+        ]);
+        expect(errors).toHaveLength(0);
+        const result = doc;
+        expect(result.reviews.map((r) => r._id)).toEqual(['a']);
+    });
     it('supports block.add and block.updateField on content blocks', () => {
         const original = {
             content: [],

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.19.0",
+  "version": "3.20.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -76,7 +76,7 @@
     "pino": "^10.3.1",
     "sharp": "^0.35.3",
     "zod": "^4.4.3",
-    "@byline/auth": "3.19.0"
+    "@byline/auth": "3.20.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",