@byline/core 3.13.3 → 3.15.0

package/dist/auth/register-collection-abilities.test.node.js

@@ -42,6 +42,7 @@ describe('registerCollectionAbilities', () => {
             'collections.pages.delete',
             'collections.pages.publish',
             'collections.pages.changeStatus',
+            'collections.pages.reindex',
         ]);
     });
     it('places every ability under the same `collections.<path>` group', () => {
@@ -49,7 +50,7 @@ describe('registerCollectionAbilities', () => {
         registerCollectionAbilities(registry, pageCollection());
         const buckets = registry.byGroup();
         expect(buckets.size).toBe(1);
-        expect(buckets.get('collections.pages')?.length).toBe(6);
+        expect(buckets.get('collections.pages')?.length).toBe(7);
     });
     it('derives labels from the collection singular/plural labels', () => {
         const registry = new AbilityRegistry();
@@ -60,6 +61,7 @@ describe('registerCollectionAbilities', () => {
         expect(registry.get('collections.pages.delete')?.label).toBe('Delete Page');
         expect(registry.get('collections.pages.publish')?.label).toBe('Publish Pages');
         expect(registry.get('collections.pages.changeStatus')?.label).toBe('Change status of Pages');
+        expect(registry.get('collections.pages.reindex')?.label).toBe('Reindex Pages search');
     });
     it('tags every ability with source: "collection"', () => {
         const registry = new AbilityRegistry();
@@ -68,7 +70,7 @@ describe('registerCollectionAbilities', () => {
             expect(descriptor.source).toBe('collection');
         }
     });
-    it('registers the same six-ability shape regardless of workflow complexity', () => {
+    it('registers the same seven-ability shape regardless of workflow complexity', () => {
         const registry = new AbilityRegistry();
         registerCollectionAbilities(registry, newsCollection());
         expect(registry.list().map((d) => d.key)).toEqual([
@@ -78,14 +80,15 @@ describe('registerCollectionAbilities', () => {
             'collections.news.delete',
             'collections.news.publish',
             'collections.news.changeStatus',
+            'collections.news.reindex',
         ]);
     });
-    it('is idempotent — calling twice leaves the registry with the same six entries', () => {
+    it('is idempotent — calling twice leaves the registry with the same seven entries', () => {
         const registry = new AbilityRegistry();
         const collection = pageCollection();
         registerCollectionAbilities(registry, collection);
         registerCollectionAbilities(registry, collection);
-        expect(registry.size).toBe(6);
+        expect(registry.size).toBe(7);
     });
     it('keeps multiple collections isolated in distinct groups', () => {
         const registry = new AbilityRegistry();
@@ -93,9 +96,9 @@ describe('registerCollectionAbilities', () => {
         registerCollectionAbilities(registry, newsCollection());
         const buckets = registry.byGroup();
         expect(buckets.size).toBe(2);
-        expect(buckets.get('collections.pages')?.length).toBe(6);
-        expect(buckets.get('collections.news')?.length).toBe(6);
-        expect(registry.size).toBe(12);
+        expect(buckets.get('collections.pages')?.length).toBe(7);
+        expect(buckets.get('collections.news')?.length).toBe(7);
+        expect(registry.size).toBe(14);
     });
 });
 describe('COLLECTION_ABILITY_VERBS / collectionAbilityKey', () => {
@@ -107,6 +110,7 @@ describe('COLLECTION_ABILITY_VERBS / collectionAbilityKey', () => {
             'delete',
             'publish',
             'changeStatus',
+            'reindex',
         ]);
     });
     it('collectionAbilityKey composes a flat dotted key', () => {

package/dist/config/config.d.ts

@@ -1,4 +1,4 @@
-import type { ClientConfig, CollectionAdminConfig, CollectionDefinition, ServerConfig } from '../@types/index.js';
+import type { ClientConfig, CollectionAdminConfig, CollectionDefinition, ColumnDefinition, ServerConfig } from '../@types/index.js';
 /**
  * Resolve a collection definition by `path`. Returns `null` either when
  * no config has been registered (e.g. unit tests, isolated tooling) or
@@ -12,6 +12,17 @@ import type { ClientConfig, CollectionAdminConfig, CollectionDefinition, ServerC
  */
 export declare const getCollectionDefinition: (path: string) => CollectionDefinition | null;
 export declare const getCollectionAdminConfig: (slug: string) => CollectionAdminConfig | null;
+/**
+ * Resolve a collection's item-row/tile columns — the per-collection projection
+ * + presentation contract used by the relation picker, relation/`hasMany`
+ * tiles, and (planned) search-result rows.
+ *
+ * Prefers the canonical {@link CollectionAdminConfig.itemView}, falling back to
+ * the deprecated `picker` alias. Always read item-view columns through this
+ * helper rather than touching `config.picker` directly, so the alias keeps
+ * working until it is removed.
+ */
+export declare const resolveItemViewColumns: (config: CollectionAdminConfig | null | undefined) => ColumnDefinition[] | undefined;
 export declare function defineClientConfig(config: ClientConfig): void;
 export declare function defineServerConfig(config: ServerConfig): void;
 export declare function getClientConfig(): ClientConfig;

package/dist/config/config.js

@@ -54,6 +54,17 @@ export const getCollectionAdminConfig = (slug) => {
         return null;
     return clientConfig.admin?.find((admin) => admin.slug === slug) ?? null;
 };
+/**
+ * Resolve a collection's item-row/tile columns — the per-collection projection
+ * + presentation contract used by the relation picker, relation/`hasMany`
+ * tiles, and (planned) search-result rows.
+ *
+ * Prefers the canonical {@link CollectionAdminConfig.itemView}, falling back to
+ * the deprecated `picker` alias. Always read item-view columns through this
+ * helper rather than touching `config.picker` directly, so the alias keeps
+ * working until it is removed.
+ */
+export const resolveItemViewColumns = (config) => config?.itemView ?? config?.picker;
 export function defineClientConfig(config) {
     validateCollections(config.collections);
     validateAdminConfigs(config.admin, config.collections);

package/dist/config/resolve-item-view-columns.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/config/resolve-item-view-columns.test.node.js

@@ -0,0 +1,30 @@
+/**
+ * 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 { resolveItemViewColumns } from './config.js';
+const itemViewCols = [{ fieldName: 'title', label: 'Title' }];
+const pickerCols = [{ fieldName: 'name', label: 'Name' }];
+const cfg = (over) => ({ slug: 'x', ...over });
+describe('resolveItemViewColumns', () => {
+    it('returns itemView when present', () => {
+        expect(resolveItemViewColumns(cfg({ itemView: itemViewCols }))).toBe(itemViewCols);
+    });
+    it('falls back to the deprecated picker alias', () => {
+        expect(resolveItemViewColumns(cfg({ picker: pickerCols }))).toBe(pickerCols);
+    });
+    it('prefers itemView over picker when both are present', () => {
+        expect(resolveItemViewColumns(cfg({ itemView: itemViewCols, picker: pickerCols }))).toBe(itemViewCols);
+    });
+    it('returns undefined when neither is set', () => {
+        expect(resolveItemViewColumns(cfg({}))).toBeUndefined();
+    });
+    it('tolerates null / undefined config', () => {
+        expect(resolveItemViewColumns(null)).toBeUndefined();
+        expect(resolveItemViewColumns(undefined)).toBeUndefined();
+    });
+});

package/dist/core.js

@@ -14,6 +14,7 @@ import { ensureCollections } from './services/collection-bootstrap.js';
 import { discoverCounterGroups } from './services/discover-counter-groups.js';
 import { validateTranslations } from './services/i18n-validator.js';
 import { validateRichTextFieldFlags } from './services/richtext-populate.js';
+import { validateSearchConfig } from './services/validate-search-config.js';
 /**
  * Initialize Byline CMS core services via the typed registry.
  *
@@ -46,6 +47,12 @@ export const initBylineCore = async (config, pinoLogger) => {
         populate: config.fields?.richText?.populate != null,
         embed: config.fields?.richText?.embed != null,
     });
+    // Validate search configuration: a collection that opts into search must
+    // have a SearchProvider registered, otherwise indexing / client.search()
+    // would silently no-op. Fail-fast at boot, same posture as richText above.
+    validateSearchConfig(composed.collections, {
+        provider: config.search != null,
+    });
     // Validate the admin i18n translation registry against the configured
     // interface locale set. Throws on structural errors (missing bundle for
     // a declared locale, defaultLocale outside the permitted set, …); soft

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export * from './@types/index.js';
 export { applyBeforeRead, assertActorCanPerform, COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, registerCollectionAbilities, } from './auth/index.js';
-export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, } from './config/config.js';
+export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, resolveItemViewColumns, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';

package/dist/index.js

@@ -16,7 +16,7 @@
 // ---------------------------------------------------------------------------
 export * from './@types/index.js';
 export { applyBeforeRead, assertActorCanPerform, COLLECTION_ABILITY_VERBS, collectionAbilityKey, registerCollectionAbilities, } from './auth/index.js';
-export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, } from './config/config.js';
+export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, resolveItemViewColumns, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';

package/dist/schemas/zod/builder.js

@@ -155,7 +155,7 @@ export const fieldToZodSchema = (field, strict = true) => {
             // (recursive) and is not constrained here.
             schema = z.any();
             break;
-        case 'relation':
+        case 'relation': {
             // Relation values are `RelatedDocumentValue` objects:
             //   { targetDocumentId, targetCollectionId,
             //     relationshipType?, cascadeDelete? }
@@ -165,15 +165,26 @@ export const fieldToZodSchema = (field, strict = true) => {
             //
             // Populated responses (depth > 0) skip this schema in the route layer
             // because the tree then contains nested documents, not bare refs.
-            schema = z
-                .object({
+            const relationValue = z.object({
                 targetDocumentId: z.string(),
                 targetCollectionId: z.string(),
                 relationshipType: z.string().optional(),
                 cascadeDelete: z.boolean().optional(),
-            })
-                .nullable();
+            });
+            if (field.hasMany) {
+                // Ordered list of relation values; `minItems` / `maxItems` bound it.
+                let arr = z.array(relationValue);
+                if (typeof field.minItems === 'number')
+                    arr = arr.min(field.minItems);
+                if (typeof field.maxItems === 'number')
+                    arr = arr.max(field.maxItems);
+                schema = arr;
+            }
+            else {
+                schema = relationValue.nullable();
+            }
             break;
+        }
         default:
             schema = z.string();
     }

package/dist/services/build-search-document.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 { CollectionDefinition, RichTextToTextFn, SearchDocument } from '../@types/index.js';
+/** A locale-resolved document fed to the assembler — one locale's view. */
+export interface SearchSourceDocument {
+    /** Stable document id (shared across versions and locales). */
+    documentId: string;
+    /** Content locale this view represents. */
+    locale: string;
+    /** Lifecycle status of the indexed version. */
+    status: string;
+    /** URL path, or null when the collection has none. */
+    path?: string | null;
+    /**
+     * Locale-resolved, camelCase field data (the `ClientDocument.fields`
+     * shape). Relation fields named in `search.facets` must be populated.
+     */
+    fields: Record<string, any>;
+    /** Timestamp of the indexed version. */
+    updatedAt?: Date | string;
+}
+export interface BuildSearchDocumentOptions {
+    /**
+     * Rich-text plain-text extractor (`ServerConfig.fields.richText.toText`).
+     * Required for `richText` fields named in `search.body`; without it those
+     * fields are skipped.
+     */
+    richTextToText?: RichTextToTextFn;
+    /**
+     * Resolve a target collection definition by path — used to find a facet
+     * target's identity field (the term) and `counter` field (the id).
+     */
+    resolveTargetDefinition?: (collectionPath: string) => CollectionDefinition | null;
+    /** Content locale, for defensive locale-envelope resolution. */
+    locale?: string;
+}
+/**
+ * Assemble one type-enriched `SearchDocument` from a locale-resolved
+ * document and its collection's role-based `search` config.
+ */
+export declare function buildSearchDocument(doc: SearchSourceDocument, definition: CollectionDefinition, options?: BuildSearchDocumentOptions): SearchDocument;

package/dist/services/build-search-document.js

@@ -0,0 +1,220 @@
+/**
+ * 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
+ */
+/**
+ * `buildSearchDocument` — the document-grain assembler for the
+ * `SearchProvider` seam. Walks a collection's role-based `search` config
+ * against one locale-resolved document and emits a single, type-enriched
+ * `SearchDocument` for a driver to index. See
+ * `docs/05-reading-and-delivery/07-search.md`.
+ *
+ * Role-based and explicit: only the fields named in `search.{body,facets,
+ * filters}` are projected — nothing is auto-pulled, so unindexed content
+ * never leaks into the index. Core derives each field's `SearchFieldType`
+ * from the schema (the "type enrichment") so a driver can map it onto its
+ * own index without re-inspecting the collection definition.
+ *
+ * Pure and synchronous, like `documentToMarkdown`: the rich-text plain-text
+ * extractor is the editor-agnostic `toText` seam passed via options, and
+ * relation targets are resolved through a caller-supplied definition
+ * resolver — no globals, no DB reads. The caller is responsible for handing
+ * in a document whose `facets` relation fields are already populated (depth
+ * 1) with the target's identity + counter fields.
+ *
+ * v1 scope: `search.{body,facets,filters}` name **top-level** fields. Deep
+ * paths into blocks / arrays are a follow-up.
+ */
+import { resolveIdentityField } from './populate.js';
+/**
+ * Assemble one type-enriched `SearchDocument` from a locale-resolved
+ * document and its collection's role-based `search` config.
+ */
+export function buildSearchDocument(doc, definition, options = {}) {
+    const locale = options.locale ?? doc.locale;
+    const search = definition.search ?? {};
+    const fieldsData = doc.fields ?? {};
+    const title = stringValue(resolveLocalized(fieldsData[resolveIdentityField(definition) ?? ''], locale)) ?? '';
+    const zones = search.zones != null && search.zones.length > 0 ? search.zones : [definition.path];
+    const fields = [];
+    // --- body: searchable text -------------------------------------------------
+    for (const decl of search.body ?? []) {
+        const name = declName(decl);
+        const field = definition.fields.find((f) => f.name === name);
+        if (field == null)
+            continue;
+        let value;
+        if (field.type === 'richText') {
+            value = options.richTextToText
+                ? nonEmpty(options.richTextToText({
+                    value: resolveLocalized(fieldsData[name], locale),
+                    fieldPath: name,
+                    collectionPath: definition.path,
+                }))
+                : null;
+        }
+        else {
+            value = stringValue(resolveLocalized(fieldsData[name], locale));
+        }
+        if (value != null) {
+            fields.push(withBoost({ name, type: 'text', role: 'body', value }, decl));
+        }
+    }
+    // --- facets: controlled-vocabulary references ------------------------------
+    for (const decl of search.facets ?? []) {
+        const name = declName(decl);
+        const field = definition.fields.find((f) => f.name === name);
+        if (field == null || field.type !== 'relation')
+            continue;
+        const targetPath = field.targetCollection;
+        const targetDef = targetPath ? (options.resolveTargetDefinition?.(targetPath) ?? null) : null;
+        const termField = targetDef ? resolveIdentityField(targetDef) : undefined;
+        const idField = targetDef?.fields.find((f) => f.type === 'counter')?.name;
+        const facetValues = toEnvelopeArray(fieldsData[name])
+            .map((env) => extractFacetValue(env, termField, idField, locale))
+            .filter((v) => v != null);
+        if (facetValues.length > 0) {
+            fields.push(withBoost({ name, type: 'facet', role: 'facet', value: facetValues }, decl));
+        }
+    }
+    // --- filters: scalar projections for filtering / sorting -------------------
+    for (const name of search.filters ?? []) {
+        const field = definition.fields.find((f) => f.name === name);
+        if (field == null)
+            continue;
+        const type = filterType(field.type);
+        const value = coerceFilterValue(resolveLocalized(fieldsData[name], locale), type);
+        if (value != null) {
+            fields.push({ name, type, role: 'filter', value });
+        }
+    }
+    return {
+        collectionPath: definition.path,
+        documentId: doc.documentId,
+        locale,
+        status: doc.status,
+        zones,
+        title,
+        path: doc.path ?? null,
+        fields,
+        updatedAt: dateValue(doc.updatedAt) ?? new Date().toISOString(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function declName(decl) {
+    return typeof decl === 'string' ? decl : decl.field;
+}
+function withBoost(field, decl) {
+    const boost = typeof decl === 'string' ? undefined : decl.boost;
+    return boost != null ? { ...field, boost } : field;
+}
+/** A populated single relation or array of relations → array of envelopes. */
+function toEnvelopeArray(value) {
+    if (Array.isArray(value))
+        return value.filter((v) => v != null);
+    if (value != null && typeof value === 'object')
+        return [value];
+    return [];
+}
+function extractFacetValue(envelope, termField, idField, locale) {
+    const target = asRecord(envelope.document);
+    const targetFields = asRecord(target.fields);
+    const term = termField ? stringValue(resolveLocalized(targetFields[termField], locale)) : null;
+    if (term == null)
+        return null;
+    // Prefer the target's stable counter id (the aggregator's reporting key);
+    // fall back to its document id when the vocabulary has no counter field.
+    const rawId = idField != null ? targetFields[idField] : undefined;
+    const id = typeof rawId === 'number' || typeof rawId === 'string'
+        ? rawId
+        : (stringValue(target.documentId ?? target.id) ?? term);
+    return { id, term };
+}
+/** Map a collection field type to the filter-side `SearchFieldType`. */
+function filterType(fieldType) {
+    switch (fieldType) {
+        case 'integer':
+        case 'counter':
+            return 'integer';
+        case 'float':
+        case 'decimal':
+            return 'float';
+        case 'boolean':
+        case 'checkbox':
+            return 'boolean';
+        case 'date':
+        case 'time':
+        case 'datetime':
+            return 'datetime';
+        default:
+            return 'keyword';
+    }
+}
+function coerceFilterValue(value, type) {
+    if (value == null)
+        return null;
+    switch (type) {
+        case 'integer':
+        case 'float': {
+            const n = typeof value === 'number' ? value : Number(value);
+            return Number.isFinite(n) ? n : null;
+        }
+        case 'boolean':
+            return typeof value === 'boolean' ? value : null;
+        case 'datetime':
+            return dateValue(value);
+        default:
+            return stringValue(value);
+    }
+}
+/**
+ * Locale-scoped reads deliver flat values; `locale: 'all'` reads deliver
+ * `{ en: …, fr: … }` envelopes. Pick the requested locale (or the first
+ * available) when an envelope sneaks through.
+ */
+function resolveLocalized(value, locale) {
+    if (value != null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        !(value instanceof Date)) {
+        const record = value;
+        const keys = Object.keys(record);
+        const localeLike = keys.length > 0 && keys.every((k) => /^[a-z]{2}(-[A-Za-z]{2,4})?$/.test(k));
+        if (localeLike) {
+            if (locale && locale in record)
+                return record[locale];
+            return record[keys[0]];
+        }
+    }
+    return value;
+}
+function asRecord(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function nonEmpty(value) {
+    return value != null && value.trim().length > 0 ? value : null;
+}
+function stringValue(value) {
+    if (typeof value === 'string')
+        return value.trim().length > 0 ? value : null;
+    if (typeof value === 'number')
+        return String(value);
+    return null;
+}
+function dateValue(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'string') {
+        const date = new Date(value);
+        if (!Number.isNaN(date.getTime()))
+            return date.toISOString();
+    }
+    return null;
+}

package/dist/services/build-search-document.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 {};