skills/plugins/document-navigator/docs/api-stack/api/api-plugin-search/README.md

@suaveplan/api-plugin-search - Full-text search plugin for @suaveplan/api with TF-weighted relevance scoring, four built-in text analyzers (standard / simple / whitespace / keyword), facets, scalar+array filters, multi-key sort, highlighting, prefix autocomplete, 9 OpenAPI-typed Hono routes, 10 SEARCH.* error codes, and 5 OTel instruments. Server-tier — runs in Bun and Node.

Full-text search plugin for @suaveplan/api. Brings TF-weighted relevance scoring, four built-in text analyzers (standard, simple, whitespace, keyword), faceted aggregation, scalar/array filters, multi-key sort, optional highlighting, prefix autocomplete suggestions, and a typed SearchAdapter interface for future persistent backends. Server-tier — runs in Bun and Node.

Documentation tree

• analyzer — The analyzer module owns the text-analysis pipeline used by both the indexing path and the query path of `@suaveplan/ap…
  • analyzer — The analyzer module owns the text-analysis pipeline used by both the indexing path and the query path of `@suaveplan/ap…
• error-codes — The error-codes module defines the stable registry of programmatic failure codes raised by `@suaveplan/api-plugin-searc…
  • error-codes — The error-codes module defines the stable registry of programmatic failure codes raised by `@suaveplan/api-plugin-searc…
• otel — The OTel instruments module exposes the canonical set of meters the search plugin records on every hot path. The bundle…
  • instruments — The OTel instruments module exposes the canonical set of meters the search plugin records on every hot path. The bundle…
• plugin — The plugin module exposes createSearchPlugin, the @suaveplan/api-plugin-shaped factory that the host `PluginRegistr…
  • plugin — The plugin module exposes createSearchPlugin, the @suaveplan/api-plugin-shaped factory that the host `PluginRegistr…
• routes — The build-routes module constructs the OpenAPIHono instance that the plugin mounts under routePrefix (/search by…
  • build-routes — The build-routes module constructs the OpenAPIHono instance that the plugin mounts under routePrefix (/search by…
• schemas — The schemas module owns the public Zod surface of @suaveplan/api-plugin-search. Every HTTP route in the package valid…
  • options — The options module defines the Zod schema for the input accepted by createSearchPlugin(options?). The factory validat…
  • schemas — The schemas module owns the public Zod surface of @suaveplan/api-plugin-search. Every HTTP route in the package valid…
• service — The service module is the in-memory search engine that powers @suaveplan/api-plugin-search. It owns index creation an…
  • service — The service module is the in-memory search engine that powers @suaveplan/api-plugin-search. It owns index creation an…
• services — This module is a TypeScript declare module augmentation. It adds the searchIndexes slot to @suaveplan/api-plugin'…
  • registry-augmentation — This module is a TypeScript declare module augmentation. It adds the searchIndexes slot to @suaveplan/api-plugin'…
• types — The types module owns the internal-shape contracts of the search plugin — the materialised SearchIndex held in memory…
  • types — The types module owns the internal-shape contracts of the search plugin — the materialised SearchIndex held in memory…

Install

bun add @suaveplan/api-plugin-search

Quick start

import { createApi } from "@suaveplan/api";
import { createSearchPlugin } from "@suaveplan/api-plugin-search";

const api = createApi({
    plugins: [
        createSearchPlugin({
            routePrefix: "/search",
            maxIndexes: 100,
            maxDocumentsPerIndex: 100_000,
            defaultAnalyzer: "standard",
        }),
    ],
});

await api.start();
// POST /search/indexes → create index
// POST /search/indexes/:name/documents → index a document
// POST /search/query → run a search
// POST /search/suggest → prefix autocomplete

Features

• 9 HTTP routes with Zod-typed @hono/zod-openapi request/response validation: POST /query, POST /suggest, GET /indexes, POST /indexes, GET /indexes/:name, DELETE /indexes/:name, POST /indexes/:name/documents, POST /indexes/:name/bulk, DELETE /indexes/:name/documents/:docId.
• TF × field-weight scoring with deterministic ordering, plus five-way sort (relevance, date_asc, date_desc, alpha_asc, alpha_desc).
• Four built-in analyzers — standard (tokenise → stop-words → stem), simple (tokenise only), whitespace (case-preserving), and keyword (single-token) — plus public primitives (tokenize, removeStopWords, stem) for custom analyzers.
• Faceted aggregation restricted to fields declared with facet: true; counts reflect the filtered document set.
• Scalar + array filters through a single Zod schema so callers can send { tag: "blog" } or { tag: ["blog", "release"] } with the same field.
• Optional highlighting wrapping matching whole words in the configured tag (<mark> by default).
• Prefix autocomplete via suggest() — ranks by occurrence count across every indexed field.
• 10 SEARCH.* error codes through defineCodes so callers can branch on error.code with full type narrowing.
• 5 OTel instruments under the @suaveplan/api-plugin-search meter — counters for queries / indexes / docs / suggests and a histogram for query duration.
• ServiceRegistry augmentation — ctx.getService("searchIndexes") returns Map<string, SearchIndex> | undefined without a cast.

Modules

• analyzer/analyzer
• error-codes/error-codes
• otel/instruments
• plugin/plugin
• routes/build-routes
• schemas/options
• schemas/schemas
• service/service
• services/registry-augmentation
• types/types

Status

0.1.0 — first migration wave shipping with full upstream parity. Persistent backends (SearchAdapter` implementations against SurrealDB FTS / Typesense / Meilisearch), tenant scoping, auth gates, rate limiting, and the enterprise-audit §4 enhancements (vector search, synonyms, query DSL, saved searches, learning-to-rank) are tracked as follow-up changes.