@byline/client 3.14.0 → 3.15.0

package/dist/client.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { type RequestContext } from '@byline/auth';
-import type { BylineLogger, CollectionDefinition, IDbAdapter, IStorageProvider, RichTextPopulateFn, SlugifierFn } from '@byline/core';
+import type { BylineLogger, CollectionDefinition, IDbAdapter, IStorageProvider, RichTextPopulateFn, RichTextToTextFn, SearchProvider, SlugifierFn } from '@byline/core';
 import { CollectionHandle } from './collection-handle.js';
 import type { BylineClientConfig } from './types.js';
 /**
@@ -22,6 +22,9 @@ export declare class BylineClient {
     readonly defaultLocale: string;
     readonly slugifier: SlugifierFn | undefined;
     readonly richTextPopulate: RichTextPopulateFn | undefined;
+    readonly search: SearchProvider | undefined;
+    readonly richTextToText: RichTextToTextFn | undefined;
+    readonly contentLocales: string[];
     /** Cache: collection path → database row id + schema version. */
     private collectionRecordCache;
     /** The raw `requestContext` config value, stored for per-call resolution. */

package/dist/client.js

@@ -56,6 +56,9 @@ export class BylineClient {
     defaultLocale;
     slugifier;
     richTextPopulate;
+    search;
+    richTextToText;
+    contentLocales;
     /** Cache: collection path → database row id + schema version. */
     collectionRecordCache = new Map();
     /** The raw `requestContext` config value, stored for per-call resolution. */
@@ -82,6 +85,10 @@ export class BylineClient {
         this.slugifier = config.slugifier ?? fromConfig?.slugifier;
         this.richTextPopulate =
             config.richTextPopulate ?? fromConfig?.fields?.richText?.populate ?? undefined;
+        this.search = config.search ?? fromConfig?.search ?? undefined;
+        this.richTextToText = config.richTextToText ?? fromConfig?.fields?.richText?.toText ?? undefined;
+        this.contentLocales = config.contentLocales ??
+            fromConfig?.i18n?.content?.locales ?? [this.defaultLocale];
         this.requestContextSource = config.requestContext;
     }
     /**

package/dist/collection-handle.d.ts

@@ -5,9 +5,9 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { AuditLogPage, ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, RestoreVersionResult, UnpublishResult, UpdateDocumentResult } from '@byline/core';
+import type { AuditLogPage, ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, RestoreVersionResult, SearchResults, UnpublishResult, UpdateDocumentResult } from '@byline/core';
 import type { BylineClient } from './client.js';
-import type { AuditLogOptions, ClientDocument, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, HistoryOptions, PlaceTreeNodeOptions, TreeNode, UpdateOptions } from './types.js';
+import type { AuditLogOptions, ClientDocument, CollectionSearchOptions, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, HistoryOptions, PlaceTreeNodeOptions, ReindexResult, TreeNode, UpdateOptions } from './types.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
  * operations against that collection's documents.
@@ -33,6 +33,48 @@ export declare class CollectionHandle {
      * document matches.
      */
     findOne<F = Record<string, any>>(options?: FindOneOptions<F>): Promise<ClientDocument<F> | null>;
+    /**
+     * Ranked full-text search scoped to this collection, delegated to the
+     * registered `SearchProvider` (see `ServerConfig.search`). Returns the
+     * lightweight hit tier — `title`, `path`, `score`, and matched-snippet
+     * `highlights` — enough to render a results list without hydration; fetch
+     * the hit ids via `findById` when a richer item is needed.
+     *
+     * Asserts the collection `read` ability first (same gate as the other
+     * reads), and defaults `status` to `'published'`, so a public viewer only
+     * sees published content — which is also all the index holds, since
+     * indexing is published-only.
+     *
+     * Throws `ERR_VALIDATION` when no provider is registered.
+     */
+    search(options: CollectionSearchOptions): Promise<SearchResults>;
+    /**
+     * Re-sync one document into the search index across every content locale.
+     * Reads the document's *published* view per locale (`onMissingLocale: 'omit'`)
+     * and `upsert`s where present, `remove`s where absent — so publish, unpublish,
+     * draft-over-published, and plain edits all converge on the same idempotent
+     * path. The index always mirrors what a public reader can see.
+     */
+    indexDocument(documentId: string): Promise<void>;
+    /** Remove one document from the search index entirely (all locales). */
+    removeFromIndex(documentId: string): Promise<void>;
+    /**
+     * Rebuild this collection's entire search index from its published
+     * documents. Clears the existing slice (dropping orphans for deleted docs),
+     * then walks every published document (paginated) and re-indexes it. Used for
+     * first-time backfill, after a `search` config change, or a driver swap.
+     *
+     * Asserts the collection `reindex` ability. No-op (returns zero counts) when
+     * the collection doesn't opt into search or no provider is registered.
+     */
+    reindex(): Promise<ReindexResult>;
+    /**
+     * Build the populate map for this collection's facet relation fields so each
+     * target arrives with the two fields the assembler needs: its `counter` field
+     * (the aggregation id) and its identity field (`useAsTitle`, the term).
+     * Returns `undefined` when the collection declares no facets.
+     */
+    private buildSearchFacetPopulateMap;
     /**
      * Find a document by its logical document ID.
      */

package/dist/collection-handle.js

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { applyAfterRead, applyBeforeRead, assertActorCanPerform, changeDocumentStatus, createDocument, createReadContext, deleteDocument, ERR_VALIDATION, mergePredicates, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, restoreDocumentVersion, unpublishDocument, updateDocument, } from '@byline/core';
+import { applyAfterRead, applyBeforeRead, assertActorCanPerform, buildSearchDocument, changeDocumentStatus, createDocument, createReadContext, deleteDocument, ERR_VALIDATION, mergePredicates, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, resolveIdentityField, restoreDocumentVersion, unpublishDocument, updateDocument, } from '@byline/core';
 import { shapeDocument, shapePopulatedInPlace } from './response.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
@@ -103,6 +103,165 @@ export class CollectionHandle {
         });
         return result.docs[0] ?? null;
     }
+    /**
+     * Ranked full-text search scoped to this collection, delegated to the
+     * registered `SearchProvider` (see `ServerConfig.search`). Returns the
+     * lightweight hit tier — `title`, `path`, `score`, and matched-snippet
+     * `highlights` — enough to render a results list without hydration; fetch
+     * the hit ids via `findById` when a richer item is needed.
+     *
+     * Asserts the collection `read` ability first (same gate as the other
+     * reads), and defaults `status` to `'published'`, so a public viewer only
+     * sees published content — which is also all the index holds, since
+     * indexing is published-only.
+     *
+     * Throws `ERR_VALIDATION` when no provider is registered.
+     */
+    async search(options) {
+        await this.resolveAndAssertRead();
+        const provider = this.client.search;
+        if (provider == null) {
+            throw ERR_VALIDATION({
+                message: 'No search provider is registered. Register one on ServerConfig.search — ' +
+                    'see `@byline/search-postgres` → `postgresSearch()` for the built-in driver.',
+            });
+        }
+        return provider.search({
+            query: options.query,
+            collectionPath: this.definition.path,
+            locale: options.locale ?? this.client.defaultLocale,
+            status: resolveReadMode(options.status),
+            where: options.where,
+            facets: options.facets,
+            limit: options.limit,
+            offset: options.offset,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Search index maintenance
+    //
+    // `indexDocument` / `removeFromIndex` are the canonical per-document sync the
+    // collection lifecycle hooks call; `reindex` is the bulk rebuild (backfill /
+    // config change / driver swap). All are no-ops when the collection doesn't
+    // opt into search or no provider is registered. System operations — reads use
+    // `_bypassBeforeRead` so the index reflects every published document.
+    // -------------------------------------------------------------------------
+    /**
+     * Re-sync one document into the search index across every content locale.
+     * Reads the document's *published* view per locale (`onMissingLocale: 'omit'`)
+     * and `upsert`s where present, `remove`s where absent — so publish, unpublish,
+     * draft-over-published, and plain edits all converge on the same idempotent
+     * path. The index always mirrors what a public reader can see.
+     */
+    async indexDocument(documentId) {
+        const provider = this.client.search;
+        if (provider == null || this.definition.search == null)
+            return;
+        const populate = this.buildSearchFacetPopulateMap();
+        for (const locale of this.client.contentLocales) {
+            const view = await this.findById(documentId, {
+                locale,
+                status: 'published',
+                onMissingLocale: 'omit',
+                populate,
+                _bypassBeforeRead: true,
+            });
+            if (view == null) {
+                await provider.remove({ collectionPath: this.definition.path, documentId, locale });
+                continue;
+            }
+            await provider.upsert(buildSearchDocument({
+                documentId: view.id,
+                locale,
+                status: view.status,
+                path: view.path,
+                fields: view.fields,
+                updatedAt: view.updatedAt,
+            }, this.definition, {
+                locale,
+                richTextToText: this.client.richTextToText,
+                resolveTargetDefinition: (path) => this.client.collections.find((c) => c.path === path) ?? null,
+            }));
+        }
+    }
+    /** Remove one document from the search index entirely (all locales). */
+    async removeFromIndex(documentId) {
+        const provider = this.client.search;
+        if (provider == null)
+            return;
+        await provider.remove({ collectionPath: this.definition.path, documentId });
+    }
+    /**
+     * Rebuild this collection's entire search index from its published
+     * documents. Clears the existing slice (dropping orphans for deleted docs),
+     * then walks every published document (paginated) and re-indexes it. Used for
+     * first-time backfill, after a `search` config change, or a driver swap.
+     *
+     * Asserts the collection `reindex` ability. No-op (returns zero counts) when
+     * the collection doesn't opt into search or no provider is registered.
+     */
+    async reindex() {
+        const requestContext = await this.client.resolveRequestContext();
+        assertActorCanPerform(requestContext, this.definition.path, 'reindex');
+        const provider = this.client.search;
+        const result = { collectionPath: this.definition.path, documents: 0, indexed: 0 };
+        if (provider == null || this.definition.search == null)
+            return result;
+        // Clear the slice so deleted documents don't leave orphan rows.
+        await provider.reindex?.({ collectionPath: this.definition.path });
+        const pageSize = 100;
+        let page = 1;
+        for (;;) {
+            const batch = await this.find({
+                status: 'published',
+                page,
+                pageSize,
+                _bypassBeforeRead: true,
+            });
+            for (const doc of batch.docs) {
+                await this.indexDocument(doc.id);
+                result.documents++;
+            }
+            if (page >= batch.meta.totalPages || batch.docs.length === 0)
+                break;
+            page++;
+        }
+        // `indexed` mirrors documents × locales present; the provider upserts are
+        // the source of truth, so report the document count walked.
+        result.indexed = result.documents;
+        return result;
+    }
+    /**
+     * Build the populate map for this collection's facet relation fields so each
+     * target arrives with the two fields the assembler needs: its `counter` field
+     * (the aggregation id) and its identity field (`useAsTitle`, the term).
+     * Returns `undefined` when the collection declares no facets.
+     */
+    buildSearchFacetPopulateMap() {
+        const facets = this.definition.search?.facets;
+        if (facets == null || facets.length === 0)
+            return undefined;
+        const map = {};
+        for (const decl of facets) {
+            const name = typeof decl === 'string' ? decl : decl.field;
+            const field = this.definition.fields.find((f) => f.name === name);
+            if (field == null || field.type !== 'relation')
+                continue;
+            const targetPath = field.targetCollection;
+            const targetDef = targetPath
+                ? this.client.collections.find((c) => c.path === targetPath)
+                : undefined;
+            const select = [];
+            const idField = targetDef?.fields.find((f) => f.type === 'counter')?.name;
+            const termField = targetDef ? resolveIdentityField(targetDef) : undefined;
+            if (idField)
+                select.push(idField);
+            if (termField)
+                select.push(termField);
+            map[name] = select.length > 0 ? { select } : true;
+        }
+        return Object.keys(map).length > 0 ? map : undefined;
+    }
     /**
      * Find a document by its logical document ID.
      */

package/dist/index.d.ts

@@ -8,4 +8,4 @@
 export { type AuditLogEntry, type AuditLogPage, type ChangeStatusResult, type CreateDocumentResult, type CycleRelationValue, createReadContext, type DeleteDocumentResult, ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateSpec, type ReadContext, type ReadMode, type RestoreVersionResult, type UnpublishResult, type UnresolvedRelationValue, type UpdateDocumentResult, } from '@byline/core';
 export { BylineClient, createBylineClient } from './client.js';
 export { CollectionHandle } from './collection-handle.js';
-export type { AuditLogOptions, BylineClientConfig, ClientDocument, CreateOptions, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, PlaceTreeNodeOptions, PopulatedRelation, SortDirection, SortSpec, TreeNode, UpdateOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, } from './types.js';
+export type { AuditLogOptions, BylineClientConfig, ClientDocument, CollectionSearchOptions, CreateOptions, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, PlaceTreeNodeOptions, PopulatedRelation, ReindexResult, SearchFacetBucket, SearchHit, SearchResults, SortDirection, SortSpec, TreeNode, UpdateOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, } from './types.js';

package/dist/types.d.ts

@@ -6,8 +6,8 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { RequestContext } from '@byline/auth';
-import type { BylineLogger, CollectionDefinition, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, ServerConfig, SlugifierFn, SortSpec } from '@byline/core';
-export type { FilterOperators, PredicateValue, QueryPredicate, SortDirection, SortSpec, } from '@byline/core';
+import type { BylineLogger, CollectionDefinition, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchProvider, ServerConfig, SlugifierFn, SortSpec } from '@byline/core';
+export type { FilterOperators, PredicateValue, QueryPredicate, SearchFacetBucket, SearchHit, SearchProvider, SearchResults, SortDirection, SortSpec, } from '@byline/core';
 export interface BylineClientConfig {
     /**
      * Convenience shorthand: pass an already-resolved `ServerConfig` (typically
@@ -34,6 +34,26 @@ export interface BylineClientConfig {
     collections?: CollectionDefinition[];
     /** Optional storage provider — needed for delete file cleanup. */
     storage?: IStorageProvider;
+    /**
+     * Optional search provider (`ServerConfig.search`). When present,
+     * `collection(path).search(...)` delegates ranked queries to it. When
+     * omitted (and not provided via the `config` shorthand's `search`), calling
+     * `search()` throws a clear error pointing at provider registration.
+     */
+    search?: SearchProvider;
+    /**
+     * Optional richtext plain-text extractor (`ServerConfig.fields.richText.toText`).
+     * Used by the search-indexing methods (`indexDocument` / `reindex`) to feed
+     * a collection's searchable `body` from rich-text fields. When omitted, those
+     * fields are skipped.
+     */
+    richTextToText?: RichTextToTextFn;
+    /**
+     * The installation's content locales (`ServerConfig.i18n.content.locales`).
+     * The search-indexing methods iterate them to index one row per
+     * `(document, locale)`. Falls back to `[defaultLocale]` when not provided.
+     */
+    contentLocales?: string[];
     /**
      * Optional logger. Used by the write path to emit structured events
      * from `document-lifecycle`. When omitted, the client falls back to
@@ -138,6 +158,38 @@ interface PopulateControls {
 interface StatusControls {
     status?: ReadMode;
 }
+/**
+ * Options for `CollectionHandle.search(...)` — a ranked full-text query
+ * scoped to this collection, delegated to the registered `SearchProvider`.
+ * `collectionPath` is implied by the handle, so callers supply only the
+ * query and optional scoping. `status` defaults to `'published'` (public
+ * readers); pass `'any'` for admin contexts.
+ */
+export interface CollectionSearchOptions {
+    /** Free-text query string. */
+    query: string;
+    /** Restrict to a single content locale (defaults to the client default). */
+    locale?: string;
+    /** Read mode — `'published'` (default) or `'any'`. */
+    status?: ReadMode;
+    /** Structured filters AND-merged with the text query (driver-dependent). */
+    where?: QueryPredicate;
+    /** Field names to compute facet buckets for (driver-capability gated). */
+    facets?: string[];
+    /** Max hits to return. */
+    limit?: number;
+    /** Offset for pagination. */
+    offset?: number;
+}
+/** Outcome of a collection `reindex()` — counts for reporting. */
+export interface ReindexResult {
+    /** Collection that was reindexed. */
+    collectionPath: string;
+    /** Number of published documents walked. */
+    documents: number;
+    /** Number of `(document, locale)` index rows upserted. */
+    indexed: number;
+}
 /**
  * What a read does when the requested content locale is missing. Shared by
  * every read method. `@byline/client` defaults this to `'fallback'`.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -38,8 +38,8 @@
   ],
   "dependencies": {
     "npm-run-all": "^4.1.5",
-    "@byline/auth": "3.14.0",
-    "@byline/core": "3.14.0"
+    "@byline/auth": "3.15.0",
+    "@byline/core": "3.15.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
@@ -51,7 +51,7 @@
     "tsx": "^4.22.3",
     "typescript": "6.0.3",
     "vitest": "^4.1.7",
-    "@byline/db-postgres": "3.14.0"
+    "@byline/db-postgres": "3.15.0"
   },
   "publishConfig": {
     "access": "public",