@byline/core 4.2.0 → 4.4.0

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

@@ -510,6 +510,68 @@ describe('validateCollections', () => {
                 },
             ],
         };
-        expect(() => validateCollections([collection])).toThrow(/content\.file.*must not contain duplicate slashes/s);
+        // The path names the block type, so the message identifies which block's
+        // `file` declaration is at fault rather than just `content.file`.
+        expect(() => validateCollections([collection])).toThrow(/content\.attachmentsBlock\.file.*must not contain duplicate slashes/s);
+    });
+});
+// ---------------------------------------------------------------------------
+// search config field resolution
+//
+// `buildSearchDocument` resolves each name among the collection's top-level
+// fields and silently skips what it cannot resolve, so an unrecognised name
+// used to produce a collection that indexed less than its author intended,
+// with no signal at boot or at index time.
+// ---------------------------------------------------------------------------
+describe('validateCollections — search config fields', () => {
+    const searchable = (search) => ({
+        ...baseCollection,
+        search,
+        fields: [
+            { name: 'title', label: 'Title', type: 'text' },
+            { name: 'summary', label: 'Summary', type: 'text' },
+            { name: 'featured', label: 'Featured', type: 'checkbox' },
+            { name: 'topics', label: 'Topics', type: 'relation', targetCollection: 'topics' },
+            { name: 'format', label: 'Format', type: 'select', options: [] },
+            {
+                name: 'files',
+                label: 'Files',
+                type: 'array',
+                fields: [
+                    {
+                        name: 'filesGroup',
+                        type: 'group',
+                        fields: [{ name: 'caption', label: 'Caption', type: 'text' }],
+                    },
+                ],
+            },
+        ],
+    });
+    it('accepts top-level names, including a container in body', () => {
+        expect(() => validateCollections([
+            searchable({
+                body: [{ field: 'title', boost: 2 }, 'summary', 'files'],
+                facets: ['topics'],
+                filters: ['featured'],
+            }),
+        ])).not.toThrow();
+    });
+    it('rejects a body name that does not exist', () => {
+        expect(() => validateCollections([searchable({ body: ['titel'] })])).toThrow(/no top-level field with that name exists/);
+    });
+    it('rejects a dotted path and explains what to name instead', () => {
+        // Accepting it would be worse than rejecting: the indexer would resolve
+        // nothing and silently index an empty body.
+        expect(() => validateCollections([searchable({ body: ['files.filesGroup.caption'] })])).toThrow(/top-level fields only.*name the top-level container/s);
+    });
+    it('rejects a facet that is not a relation', () => {
+        expect(() => validateCollections([searchable({ facets: ['format'] })])).toThrow(/Facets are controlled-vocabulary references/);
+    });
+    it('rejects a filter naming a container field', () => {
+        expect(() => validateCollections([searchable({ filters: ['files'] })])).toThrow(/Filters project a single scalar value/);
+    });
+    it('checks facets and filters too, not only body', () => {
+        expect(() => validateCollections([searchable({ facets: ['nope'] })])).toThrow(/no top-level field with that name exists/);
+        expect(() => validateCollections([searchable({ filters: ['nope'] })])).toThrow(/no top-level field with that name exists/);
     });
 });

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './l
 export { type BylineLogger, getLogger } from './lib/logger.js';
 export { AsyncRegistry, type RegisteredServices, Registry } from './lib/registry.js';
 export * from './patches/index.js';
+export * from './paths/index.js';
 export { mergePredicates, type ParseContext, type ParsedSort, type ParsedWhere, parsePredicateFilters, parseSort, parseWhere, } from './query/parse-where.js';
 export { getCollectionSchemasForPath } from './schemas/zod/cache.js';
 export * from './services/index.js';

package/dist/index.js

@@ -28,6 +28,7 @@ export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './l
 export { getLogger } from './lib/logger.js';
 export { AsyncRegistry, Registry } from './lib/registry.js';
 export * from './patches/index.js';
+export * from './paths/index.js';
 export { mergePredicates, parsePredicateFilters, parseSort, parseWhere, } from './query/parse-where.js';
 export { getCollectionSchemasForPath } from './schemas/zod/cache.js';
 export * from './services/index.js';

package/dist/patches/apply-patches.js

@@ -1,6 +1,10 @@
 // Core implementation of the patch engine
 import { isBlocksField, isStructureField } from '../@types/field-types.js';
-// Very small path grammar:
+import { parseInstancePath } from '../paths/parse-path.js';
+// Instance-path grammar — see `@byline/core` `paths/`. Patch paths address
+// items, so they carry selectors and no block type (the item holds `_type`).
+//
+// Historical shapes, unchanged:
 // - "foo.bar" -> [{field: 'foo'}, {field: 'bar'}]
 // - "reviews[0].rating" -> [{field: 'reviews'}, {index: 0}, {field: 'rating'}]
 // - "reviews[id=abc].rating" -> [{field: 'reviews'}, {id: 'abc'}, {field: 'rating'}]
@@ -8,33 +12,19 @@ import { isBlocksField, isStructureField } from '../@types/field-types.js';
 export function parsePatchPath(path) {
     if (!path)
         return [];
-    const segments = [];
-    const parts = String(path).split('.');
-    for (const part of parts) {
-        const fieldMatch = part.match(/^([^[]+)/);
-        if (!fieldMatch) {
-            continue;
-        }
-        const field = fieldMatch[1];
-        segments.push({ kind: 'field', key: field });
-        const bracketRegex = /\[([^\]]+)\]/g;
-        let match;
-        // Biome: avoid assignment in the while condition
-        // eslint-disable-next-line no-constant-condition
-        while (true) {
-            match = bracketRegex.exec(part);
-            if (match === null)
-                break;
-            const token = match[1];
-            if (/^\d+$/.test(token)) {
-                segments.push({ kind: 'index', index: Number.parseInt(token, 10) });
-            }
-            else if (token.startsWith('id=')) {
-                segments.push({ kind: 'id', id: token.slice(3) });
-            }
-        }
-    }
-    return segments;
+    const parsed = parseInstancePath(String(path));
+    // An unparseable path yields no segments, so callers reject the patch
+    // rather than applying it somewhere else. The previous hand-rolled parser
+    // was lenient — `"a["` produced `[field: 'a']`, and the patch was then
+    // applied at `a`, a path the client never addressed. Silent misapplication
+    // is a worse failure than a rejected patch.
+    if (!parsed.ok)
+        return [];
+    return parsed.segments.map((segment) => segment.kind === 'field'
+        ? // The grammar names this `name`; the patch resolver has always called
+            // it `key`. Renamed at the boundary rather than churning consumers.
+            { kind: 'field', key: segment.name }
+        : segment);
 }
 // Very small, best-effort resolver that walks the CollectionDefinition to find
 // the field targeted by a patch path. This is intentionally conservative and
@@ -187,7 +177,8 @@ function ensurePath(root, segments) {
 function applyFieldPatch(doc, patch) {
     const segments = parsePatchPath(patch.path);
     if (segments.length === 0) {
-        throw new Error('Empty path for field patch');
+        // Covers both an empty path and one that did not parse.
+        throw new Error(`Empty or unparseable path for field patch: ${JSON.stringify(patch.path ?? '')}`);
     }
     if (patch.kind === 'field.set') {
         const { parent, key } = ensurePath(doc, segments);

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { applyPatches } from './apply-patches.js';
+import { applyPatches, parsePatchPath } from './apply-patches.js';
 const DocsDefinition = {
     path: 'docs',
     labels: {
@@ -270,3 +270,51 @@ describe('applyPatches', () => {
         expect(updated.content[0]?.constrainedWidth).toBe(true);
     });
 });
+// ---------------------------------------------------------------------------
+// Patch paths are instance paths
+//
+// `parsePatchPath` delegates to the shared grammar's `parseInstancePath`
+// (`@byline/core` `paths/`). The two agree on every well-formed path; they
+// differ only in that a malformed one is now rejected rather than partially
+// parsed.
+// ---------------------------------------------------------------------------
+describe('parsePatchPath — shared instance-path grammar', () => {
+    it('parses positional and id selectors', () => {
+        expect(parsePatchPath('content[0].gallery[1].alt')).toEqual([
+            { kind: 'field', key: 'content' },
+            { kind: 'index', index: 0 },
+            { kind: 'field', key: 'gallery' },
+            { kind: 'index', index: 1 },
+            { kind: 'field', key: 'alt' },
+        ]);
+        expect(parsePatchPath('content[id=abc].alt')).toEqual([
+            { kind: 'field', key: 'content' },
+            { kind: 'id', id: 'abc' },
+            { kind: 'field', key: 'alt' },
+        ]);
+    });
+    it('carries no block-type segment — the addressed item holds its own `_type`', () => {
+        expect(parsePatchPath('content[0].alt')).not.toContainEqual({
+            kind: 'field',
+            key: 'photoBlock',
+        });
+    });
+    it('rejects a malformed path instead of parsing it partially', () => {
+        // Previously `'a['` yielded `[{ kind: 'field', key: 'a' }]`, so a patch
+        // was applied at `a` — a path the client never addressed. Returning no
+        // segments makes callers reject the patch instead.
+        for (const malformed of ['a[', 'a[]', 'a[x]', 'a]b', 'a..b']) {
+            expect(parsePatchPath(malformed)).toEqual([]);
+        }
+    });
+    it('surfaces a malformed path as a patch error rather than a silent write', () => {
+        const original = { title: 'original' };
+        const { doc, errors } = applyPatches(DocsDefinition, original, [
+            { kind: 'field.set', path: 'title[', value: 'injected' },
+        ]);
+        expect(errors).toHaveLength(1);
+        expect(errors[0]?.message).toMatch(/unparseable path/i);
+        // The truncated path `title` is never written.
+        expect(doc.title).toBe('original');
+    });
+});

package/dist/paths/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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
+ */
+/**
+ * Field path grammar — one AST, two serialisations.
+ *
+ * See `path-types.ts` for the instance/declaration model, and
+ * `docs/04-collections/01-fields.md` for the author-facing account.
+ */
+export { formatDeclarationPath, formatInstancePath, parseDeclarationPath, parseInstancePath, toDeclarationSegments, } from './parse-path.js';
+export { resolveDeclarationPath, walkFieldDeclarations } from './resolve-path.js';
+export type { PathParseFailure, PathParseResult, PathResolution, PathSegment, ResolveOptions, } from './path-types.js';

package/dist/paths/index.js

@@ -0,0 +1,15 @@
+/**
+ * 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
+ */
+/**
+ * Field path grammar — one AST, two serialisations.
+ *
+ * See `path-types.ts` for the instance/declaration model, and
+ * `docs/04-collections/01-fields.md` for the author-facing account.
+ */
+export { formatDeclarationPath, formatInstancePath, parseDeclarationPath, parseInstancePath, toDeclarationSegments, } from './parse-path.js';
+export { resolveDeclarationPath, walkFieldDeclarations } from './resolve-path.js';

package/dist/paths/parse-path.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 { PathParseResult, PathSegment } from './path-types.js';
+/**
+ * Parse a declaration path: dotted, index-free, block types written as plain
+ * segments (`content.photoBlock.gallery.alt`).
+ *
+ * Every segment comes back as `kind: 'field'`. Item indices are a parse
+ * error rather than something silently dropped — a caller writing
+ * `files[0].caption` where a declaration is expected has made a category
+ * mistake, and saying so is more useful than quietly addressing every item.
+ */
+export declare function parseDeclarationPath(path: string): PathParseResult;
+/**
+ * Parse an instance path: dotted field names with bracket item selectors,
+ * either positional (`gallery[1]`) or by stable id (`gallery[id=abc]`).
+ *
+ * Blocks carry no discriminator here — the addressed item resolves its own
+ * `_type` — so a block hop is just the blocks field name followed by an
+ * item selector.
+ */
+export declare function parseInstancePath(path: string): PathParseResult;
+/**
+ * Serialise segments as a declaration path. Index and id segments are
+ * dropped, so this doubles as the instance → declaration projection when
+ * applied to instance segments.
+ */
+export declare function formatDeclarationPath(segments: readonly PathSegment[]): string;
+/** Serialise segments as an instance path, rendering selectors in brackets. */
+export declare function formatInstancePath(segments: readonly PathSegment[]): string;
+/**
+ * Drop the item selectors from a path, leaving the declaration it addresses.
+ *
+ * This is the projection several call sites hand-roll with a regex today.
+ * Doing it over segments rather than raw text is what makes it safe: a field
+ * legitimately named `0` is a `field` segment and survives, where a
+ * string-level `/^\d+$/` filter would silently delete it.
+ */
+export declare function toDeclarationSegments(segments: readonly PathSegment[]): readonly PathSegment[];

package/dist/paths/parse-path.js

@@ -0,0 +1,133 @@
+/**
+ * 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
+ */
+// ---------------------------------------------------------------------------
+// Parsing and serialising field paths.
+//
+// Parsing is schema-unaware: it recovers structure from text and nothing
+// more. In particular it cannot tell a block type from a field name, since
+// both are bare identifiers — `resolveDeclarationPath` settles that against
+// a field set. Callers that already hold the schema (path *producers*) should
+// build segments directly and use the formatters here.
+// ---------------------------------------------------------------------------
+const INDEX_TOKEN = /^\[(\d+)\]$/;
+const ID_TOKEN = /^\[id=(.+)\]$/;
+/**
+ * Parse a declaration path: dotted, index-free, block types written as plain
+ * segments (`content.photoBlock.gallery.alt`).
+ *
+ * Every segment comes back as `kind: 'field'`. Item indices are a parse
+ * error rather than something silently dropped — a caller writing
+ * `files[0].caption` where a declaration is expected has made a category
+ * mistake, and saying so is more useful than quietly addressing every item.
+ */
+export function parseDeclarationPath(path) {
+    if (path.trim() === '')
+        return { ok: false, reason: 'empty' };
+    if (path.includes('[') || path.includes(']'))
+        return { ok: false, reason: 'index' };
+    const segments = [];
+    for (const part of path.split('.')) {
+        if (part === '')
+            return { ok: false, reason: 'emptySegment' };
+        segments.push({ kind: 'field', name: part });
+    }
+    return { ok: true, segments };
+}
+/**
+ * Parse an instance path: dotted field names with bracket item selectors,
+ * either positional (`gallery[1]`) or by stable id (`gallery[id=abc]`).
+ *
+ * Blocks carry no discriminator here — the addressed item resolves its own
+ * `_type` — so a block hop is just the blocks field name followed by an
+ * item selector.
+ */
+export function parseInstancePath(path) {
+    if (path.trim() === '')
+        return { ok: false, reason: 'empty' };
+    const segments = [];
+    for (const part of path.split('.')) {
+        if (part === '')
+            return { ok: false, reason: 'emptySegment' };
+        const bracket = part.indexOf('[');
+        if (bracket === -1) {
+            if (part.includes(']'))
+                return { ok: false, reason: 'malformed' };
+            segments.push({ kind: 'field', name: part });
+            continue;
+        }
+        const name = part.slice(0, bracket);
+        if (name === '')
+            return { ok: false, reason: 'emptySegment' };
+        segments.push({ kind: 'field', name });
+        // One segment may carry several selectors (`items[0][1]` is not produced
+        // today, but parsing it costs nothing and beats silently truncating).
+        let rest = part.slice(bracket);
+        while (rest !== '') {
+            const close = rest.indexOf(']');
+            if (close === -1)
+                return { ok: false, reason: 'malformed' };
+            const token = rest.slice(0, close + 1);
+            rest = rest.slice(close + 1);
+            const indexMatch = INDEX_TOKEN.exec(token);
+            if (indexMatch?.[1] != null) {
+                segments.push({ kind: 'index', index: Number.parseInt(indexMatch[1], 10) });
+                continue;
+            }
+            const idMatch = ID_TOKEN.exec(token);
+            if (idMatch?.[1] != null) {
+                segments.push({ kind: 'id', id: idMatch[1] });
+                continue;
+            }
+            return { ok: false, reason: 'malformed' };
+        }
+    }
+    return { ok: true, segments };
+}
+/**
+ * Serialise segments as a declaration path. Index and id segments are
+ * dropped, so this doubles as the instance → declaration projection when
+ * applied to instance segments.
+ */
+export function formatDeclarationPath(segments) {
+    return segments
+        .filter((segment) => segment.kind === 'field' || segment.kind === 'blockType')
+        .map((segment) => (segment.kind === 'blockType' ? segment.blockType : segment.name))
+        .join('.');
+}
+/** Serialise segments as an instance path, rendering selectors in brackets. */
+export function formatInstancePath(segments) {
+    let out = '';
+    for (const segment of segments) {
+        switch (segment.kind) {
+            case 'field':
+                out += out === '' ? segment.name : `.${segment.name}`;
+                break;
+            case 'blockType':
+                // Instance paths carry no discriminator; the item knows its own type.
+                break;
+            case 'index':
+                out += `[${segment.index}]`;
+                break;
+            case 'id':
+                out += `[id=${segment.id}]`;
+                break;
+        }
+    }
+    return out;
+}
+/**
+ * Drop the item selectors from a path, leaving the declaration it addresses.
+ *
+ * This is the projection several call sites hand-roll with a regex today.
+ * Doing it over segments rather than raw text is what makes it safe: a field
+ * legitimately named `0` is a `field` segment and survives, where a
+ * string-level `/^\d+$/` filter would silently delete it.
+ */
+export function toDeclarationSegments(segments) {
+    return segments.filter((segment) => segment.kind === 'field' || segment.kind === 'blockType');
+}

package/dist/paths/path-dialects.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 {};