@byline/core 3.13.3 → 3.15.0

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

@@ -0,0 +1,164 @@
+/**
+ * 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
+ */
+/**
+ * Contract tests for the document-grain search assembler. Verifies the
+ * role-based projection (body / facets / filters / zones), the schema-derived
+ * type enrichment, per-field boost, and that nothing outside the config is
+ * pulled (no leakage of unindexed content).
+ */
+import { describe, expect, it } from 'vitest';
+import { buildSearchDocument } from './build-search-document.js';
+// A controlled-vocabulary facet collection: a `counter` id + a `name` term.
+const topics = {
+    path: 'topics',
+    labels: { singular: 'Topic', plural: 'Topics' },
+    useAsTitle: 'name',
+    fields: [
+        { name: 'name', label: 'Name', type: 'text', localized: true },
+        { name: 'facetId', label: 'Facet Id', type: 'counter', group: 'publication-facets' },
+    ],
+};
+const publications = {
+    path: 'publications',
+    labels: { singular: 'Publication', plural: 'Publications' },
+    useAsTitle: 'title',
+    fields: [
+        { name: 'title', label: 'Title', type: 'text', localized: true },
+        { name: 'abstract', label: 'Abstract', type: 'richText', localized: true },
+        { name: 'editorialNotes', label: 'Editorial Notes', type: 'textArea' },
+        { name: 'publicationDate', label: 'Date', type: 'datetime' },
+        { name: 'citationCount', label: 'Citations', type: 'integer' },
+        {
+            name: 'topics',
+            label: 'Topics',
+            type: 'relation',
+            targetCollection: 'topics',
+        },
+    ],
+    search: {
+        body: ['title', { field: 'abstract', boost: 2 }],
+        facets: ['topics'],
+        filters: ['publicationDate', 'citationCount'],
+        zones: ['site', 'publications'],
+    },
+};
+const resolveTargetDefinition = (path) => (path === 'topics' ? topics : null);
+// Stub `toText` seam — returns a string property so we don't depend on Lexical.
+const richTextToText = ({ value }) => typeof value === 'object' && value != null ? String(value.text ?? '') : '';
+function source() {
+    return {
+        documentId: 'doc-1',
+        locale: 'en',
+        status: 'published',
+        path: 'forest-restoration',
+        updatedAt: '2026-06-01T00:00:00.000Z',
+        fields: {
+            title: 'Forest Restoration',
+            abstract: { text: 'Methods for restoring degraded forest.' },
+            editorialNotes: 'Internal: chase the author for figures.',
+            publicationDate: '2026-05-01T00:00:00.000Z',
+            citationCount: 42,
+            topics: [
+                {
+                    _resolved: true,
+                    document: { documentId: 't-1', fields: { name: 'Ecology', facetId: 1 } },
+                },
+                {
+                    _resolved: true,
+                    document: { documentId: 't-2', fields: { name: 'Biodiversity', facetId: 2 } },
+                },
+            ],
+        },
+    };
+}
+function fieldByName(fields, name) {
+    return fields.find((f) => f.name === name);
+}
+describe('buildSearchDocument', () => {
+    const doc = buildSearchDocument(source(), publications, {
+        richTextToText,
+        resolveTargetDefinition,
+    });
+    it('sets identity, status, locale, path, and updatedAt', () => {
+        expect(doc.collectionPath).toBe('publications');
+        expect(doc.documentId).toBe('doc-1');
+        expect(doc.locale).toBe('en');
+        expect(doc.status).toBe('published');
+        expect(doc.title).toBe('Forest Restoration');
+        expect(doc.path).toBe('forest-restoration');
+        expect(doc.updatedAt).toBe('2026-06-01T00:00:00.000Z');
+    });
+    it('resolves zones from config', () => {
+        expect(doc.zones).toEqual(['site', 'publications']);
+    });
+    it('projects body text fields as type:text role:body', () => {
+        const title = fieldByName(doc.fields, 'title');
+        expect(title).toMatchObject({
+            name: 'title',
+            type: 'text',
+            role: 'body',
+            value: 'Forest Restoration',
+        });
+    });
+    it('extracts richText body via the toText seam and carries boost', () => {
+        const abstract = fieldByName(doc.fields, 'abstract');
+        expect(abstract).toMatchObject({
+            name: 'abstract',
+            type: 'text',
+            role: 'body',
+            value: 'Methods for restoring degraded forest.',
+            boost: 2,
+        });
+    });
+    it('resolves facets to {id, term} from target counter + useAsTitle', () => {
+        const topicsField = fieldByName(doc.fields, 'topics');
+        expect(topicsField).toMatchObject({ name: 'topics', type: 'facet', role: 'facet' });
+        expect(topicsField?.value).toEqual([
+            { id: 1, term: 'Ecology' },
+            { id: 2, term: 'Biodiversity' },
+        ]);
+    });
+    it('projects filters with schema-derived types', () => {
+        expect(fieldByName(doc.fields, 'publicationDate')).toMatchObject({
+            type: 'datetime',
+            role: 'filter',
+            value: '2026-05-01T00:00:00.000Z',
+        });
+        expect(fieldByName(doc.fields, 'citationCount')).toMatchObject({
+            type: 'integer',
+            role: 'filter',
+            value: 42,
+        });
+    });
+    it('does not pull fields outside the search config (no leakage)', () => {
+        expect(fieldByName(doc.fields, 'editorialNotes')).toBeUndefined();
+    });
+    it('defaults zones to the collection path when unset', () => {
+        const noZones = { ...publications, search: { body: ['title'] } };
+        const out = buildSearchDocument(source(), noZones);
+        expect(out.zones).toEqual(['publications']);
+    });
+    it('skips richText body fields when no toText seam is registered', () => {
+        const out = buildSearchDocument(source(), publications, { resolveTargetDefinition });
+        expect(fieldByName(out.fields, 'abstract')).toBeUndefined();
+        // Plain text body field still projects.
+        expect(fieldByName(out.fields, 'title')).toBeDefined();
+    });
+    it('resolves localized values to the requested locale', () => {
+        const localized = {
+            ...source(),
+            fields: { ...source().fields, title: { en: 'Forest Restoration', fr: 'Restauration' } },
+        };
+        const out = buildSearchDocument(localized, publications, {
+            richTextToText,
+            resolveTargetDefinition,
+            locale: 'fr',
+        });
+        expect(out.title).toBe('Restauration');
+    });
+});

package/dist/services/index.d.ts

@@ -1,6 +1,7 @@
 export { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, } from '../lib/errors.js';
 export { normaliseDateFields } from '../utils/normalise-dates.js';
 export { type AssignCounterValuesInput, assignCounterValues } from './assign-counter-values.js';
+export { type BuildSearchDocumentOptions, buildSearchDocument, type SearchSourceDocument, } from './build-search-document.js';
 export { type CollectionRecord, type EnsureCollectionsInput, ensureCollections, } from './collection-bootstrap.js';
 export { type DiscoverCounterGroupsInput, discoverCounterGroups, } from './discover-counter-groups.js';
 export * from './document-lifecycle/index.js';
@@ -8,8 +9,9 @@ export * from './document-read.js';
 export * from './document-to-markdown.js';
 export * from './field-upload.js';
 export { type InterfaceI18nConfig, type TranslationDriftWarning, type ValidateTranslationsResult, validateTranslations, } from './i18n-validator.js';
-export { type CycleRelationValue, createReadContext, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateOptions, type PopulateSpec, populateDocuments, type ReadContext, type UnresolvedRelationValue, } from './populate.js';
+export { type CycleRelationValue, createReadContext, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateOptions, type PopulateSpec, populateDocuments, type ReadContext, resolveIdentityField, type UnresolvedRelationValue, } from './populate.js';
 export { buildRelationSummaryPopulateMap, type RelationTargetResolver, resolveRelationProjection, } from './relation-projection.js';
 export { type EmbedRichTextFieldsOptions, embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';
 export { collectRichTextLeaves, type PopulateRichTextFieldsOptions, populateRichTextFields, type RichTextAdapterPresence, type RichTextLeaf, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
+export { type SearchProviderPresence, validateSearchConfig, } from './validate-search-config.js';
 export { type FieldLeaf, walkFieldTree } from './walk-field-tree.js';

package/dist/services/index.js

@@ -2,6 +2,7 @@
 export { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, } from '../lib/errors.js';
 export { normaliseDateFields } from '../utils/normalise-dates.js';
 export { assignCounterValues } from './assign-counter-values.js';
+export { buildSearchDocument, } from './build-search-document.js';
 export { ensureCollections, } from './collection-bootstrap.js';
 export { discoverCounterGroups, } from './discover-counter-groups.js';
 export * from './document-lifecycle/index.js';
@@ -9,8 +10,9 @@ export * from './document-read.js';
 export * from './document-to-markdown.js';
 export * from './field-upload.js';
 export { validateTranslations, } from './i18n-validator.js';
-export { createReadContext, populateDocuments, } from './populate.js';
+export { createReadContext, populateDocuments, resolveIdentityField, } from './populate.js';
 export { buildRelationSummaryPopulateMap, resolveRelationProjection, } from './relation-projection.js';
 export { embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';
 export { collectRichTextLeaves, populateRichTextFields, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
+export { validateSearchConfig, } from './validate-search-config.js';
 export { walkFieldTree } from './walk-field-tree.js';

package/dist/services/populate.d.ts

@@ -276,6 +276,12 @@ declare function matchesPopulate(fieldName: string, populate: PopulateSpec): Pop
  * not need to appear in the `fields` list.
  */
 declare function buildBatchSelect(leaves: RelationLeafRef[], targetDef: CollectionDefinition | undefined): string[] | undefined;
+/**
+ * The field that represents a target document's identity for populate's
+ * default projection. Prefers `useAsTitle` (server-safe schema-level
+ * config), falling back to the first declared text field.
+ */
+export declare function resolveIdentityField(def: CollectionDefinition): string | undefined;
 /**
  * Merge the per-leaf sub-populate specs for all leaves pointing at a
  * single (now-populated) target document into a single PopulateSpec for

package/dist/services/populate.js

@@ -317,6 +317,24 @@ function collectRelationLeaves(fields, fieldDefs, populate, acc) {
         const sub = matchesPopulate(leaf.field.name, populate);
         if (sub === undefined)
             continue;
+        // hasMany: the value is an ordered array of relation envelopes. Expand it
+        // into one leaf ref per element, whose `parent` is the array itself and
+        // `key` is the index — so the envelope-assignment pass writes each
+        // populated result back into its array slot, in place.
+        if (leaf.field.hasMany) {
+            if (!Array.isArray(leaf.value))
+                continue;
+            const arr = leaf.value;
+            for (let i = 0; i < arr.length; i++) {
+                const item = arr[i];
+                if (!isRelatedDocumentValue(item))
+                    continue;
+                if ('_resolved' in item)
+                    continue;
+                acc.push({ parent: arr, key: String(i), field: leaf.field, value: item, sub });
+            }
+            continue;
+        }
         if (!isRelatedDocumentValue(leaf.value))
             continue;
         // Skip leaves that have already been replaced (e.g. via shared-ref
@@ -387,7 +405,7 @@ function buildBatchSelect(leaves, targetDef) {
  * default projection. Prefers `useAsTitle` (server-safe schema-level
  * config), falling back to the first declared text field.
  */
-function resolveIdentityField(def) {
+export function resolveIdentityField(def) {
     if (def.useAsTitle)
         return def.useAsTitle;
     const firstText = def.fields.find((f) => f.type === 'text');

package/dist/services/relation-projection.d.ts

@@ -5,17 +5,6 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-/**
- * Relation projection helpers.
- *
- * Translate a source collection's relation fields into a `PopulateMap`
- * projection that fetches just enough data from each target to render
- * a relation-summary tile on the admin edit view (picker columns,
- * `useAsTitle`, plus an optional source-side `displayField` override).
- *
- * Consumed by the admin webapp's edit-route server fn so relation tiles
- * arrive pre-hydrated on first paint — no client-side fetch per relation.
- */
 import type { CollectionAdminConfig, CollectionDefinition, FieldSet, RelationField } from '../@types/index.js';
 import type { PopulateMap } from './populate.js';
 /**
@@ -25,10 +14,10 @@ import type { PopulateMap } from './populate.js';
  *   - `sourceField.displayField` (explicit per-relation override)
  *   - target's `useAsTitle`
  *   - target's first declared text field (safety fallback)
- *   - every `picker[].fieldName` on the target admin config that maps
- *     to a real schema field (picker columns may reference metadata
- *     like `status` or `updated_at` which ride on the document row
- *     and don't need a projection entry)
+ *   - every item-view column `fieldName` on the target admin config that
+ *     maps to a real schema field (item-view columns may reference metadata
+ *     like `status` or `updated_at` which ride on the document row and don't
+ *     need a projection entry)
  */
 export declare function resolveRelationProjection(sourceField: RelationField, targetDef: CollectionDefinition | null, targetAdmin: CollectionAdminConfig | null): string[];
 export type RelationTargetResolver = (targetPath: string) => {

package/dist/services/relation-projection.js

@@ -5,6 +5,18 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+/**
+ * Relation projection helpers.
+ *
+ * Translate a source collection's relation fields into a `PopulateMap`
+ * projection that fetches just enough data from each target to render
+ * a relation-summary tile on the admin edit view (picker columns,
+ * `useAsTitle`, plus an optional source-side `displayField` override).
+ *
+ * Consumed by the admin webapp's edit-route server fn so relation tiles
+ * arrive pre-hydrated on first paint — no client-side fetch per relation.
+ */
+import { resolveItemViewColumns } from '../config/config.js';
 /**
  * Union of the target-collection field names needed to render a
  * relation-summary tile for the given source relation field.
@@ -12,10 +24,10 @@
  *   - `sourceField.displayField` (explicit per-relation override)
  *   - target's `useAsTitle`
  *   - target's first declared text field (safety fallback)
- *   - every `picker[].fieldName` on the target admin config that maps
- *     to a real schema field (picker columns may reference metadata
- *     like `status` or `updated_at` which ride on the document row
- *     and don't need a projection entry)
+ *   - every item-view column `fieldName` on the target admin config that
+ *     maps to a real schema field (item-view columns may reference metadata
+ *     like `status` or `updated_at` which ride on the document row and don't
+ *     need a projection entry)
  */
 export function resolveRelationProjection(sourceField, targetDef, targetAdmin) {
     const out = new Set();
@@ -26,8 +38,9 @@ export function resolveRelationProjection(sourceField, targetDef, targetAdmin) {
     const firstText = targetDef?.fields.find((f) => f.type === 'text')?.name;
     if (firstText)
         out.add(firstText);
-    if (targetAdmin?.picker) {
-        for (const col of targetAdmin.picker) {
+    const itemViewColumns = resolveItemViewColumns(targetAdmin);
+    if (itemViewColumns) {
+        for (const col of itemViewColumns) {
             const name = String(col.fieldName);
             if (targetDef?.fields.some((f) => f.name === name))
                 out.add(name);

package/dist/services/validate-search-config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 } from '../@types/collection-types.js';
+/** Whether a `SearchProvider` is registered on `ServerConfig.search`. */
+export interface SearchProviderPresence {
+    /** `ServerConfig.search != null` */
+    provider: boolean;
+}
+/**
+ * Validate search configuration across every collection. Throws when any
+ * collection opts into search (`CollectionDefinition.search`) but no
+ * `SearchProvider` is registered on `ServerConfig.search` — otherwise
+ * indexing and `client.search()` would silently no-op.
+ *
+ * Called once at `initBylineCore()` time, right after the richText field
+ * validation. Fail-fast at boot is the right posture; the alternative is a
+ * collection that declares it's searchable but never gets indexed.
+ *
+ * Note: a missing provider is only an error when at least one collection
+ * actually opts in. Installations that don't use search leave
+ * `ServerConfig.search` unset and pass cleanly.
+ */
+export declare function validateSearchConfig(collections: CollectionDefinition[], adapters: SearchProviderPresence): void;

package/dist/services/validate-search-config.js

@@ -0,0 +1,32 @@
+/**
+ * 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
+ */
+/**
+ * Validate search configuration across every collection. Throws when any
+ * collection opts into search (`CollectionDefinition.search`) but no
+ * `SearchProvider` is registered on `ServerConfig.search` — otherwise
+ * indexing and `client.search()` would silently no-op.
+ *
+ * Called once at `initBylineCore()` time, right after the richText field
+ * validation. Fail-fast at boot is the right posture; the alternative is a
+ * collection that declares it's searchable but never gets indexed.
+ *
+ * Note: a missing provider is only an error when at least one collection
+ * actually opts in. Installations that don't use search leave
+ * `ServerConfig.search` unset and pass cleanly.
+ */
+export function validateSearchConfig(collections, adapters) {
+    if (adapters.provider)
+        return;
+    const optedIn = collections.filter((def) => def.search != null).map((def) => def.path);
+    if (optedIn.length === 0)
+        return;
+    throw new Error(`initBylineCore: ${optedIn.length} collection(s) opt into search ` +
+        `(${optedIn.join(', ')}) but no search provider is registered. ` +
+        `Wire one via ServerConfig.search — see \`@byline/search-postgres\` → ` +
+        `\`postgresSearch()\` for the built-in Postgres full-text driver.`);
+}

package/dist/storage/collection-fingerprint.test.node.js

@@ -89,7 +89,7 @@ describe('fingerprintCollection', () => {
     it('ignores search / showStats (admin UX only)', async () => {
         const a = await fingerprintCollection(baseCollection());
         const b = baseCollection();
-        b.search = { fields: ['title', 'body.heading'] };
+        b.search = { body: ['title', 'body.heading'] };
         b.showStats = true;
         expect(await fingerprintCollection(b)).toBe(a);
     });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.13.3",
+  "version": "3.15.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.13.3"
+    "@byline/auth": "3.15.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",