117 lines
7.1 KiB
Markdown
117 lines
7.1 KiB
Markdown
# @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.
|
||
|
||
<!-- begin:auto-docs -->
|
||
## Documentation tree
|
||
|
||
- [analyzer](./src/analyzer/analyzer.md) — The analyzer module owns the text-analysis pipeline used by both the indexing path and the query path of `@suaveplan/ap…
|
||
- [analyzer](./src/analyzer/analyzer.md) — The analyzer module owns the text-analysis pipeline used by both the indexing path and the query path of `@suaveplan/ap…
|
||
- [error-codes](./src/error-codes/error-codes.md) — The error-codes module defines the stable registry of programmatic failure codes raised by `@suaveplan/api-plugin-searc…
|
||
- [error-codes](./src/error-codes/error-codes.md) — The error-codes module defines the stable registry of programmatic failure codes raised by `@suaveplan/api-plugin-searc…
|
||
- [otel](./src/otel/instruments.md) — The OTel instruments module exposes the canonical set of meters the search plugin records on every hot path. The bundle…
|
||
- [instruments](./src/otel/instruments.md) — The OTel instruments module exposes the canonical set of meters the search plugin records on every hot path. The bundle…
|
||
- [plugin](./src/plugin/plugin.md) — The plugin module exposes `createSearchPlugin`, the `@suaveplan/api-plugin`-shaped factory that the host `PluginRegistr…
|
||
- [plugin](./src/plugin/plugin.md) — The plugin module exposes `createSearchPlugin`, the `@suaveplan/api-plugin`-shaped factory that the host `PluginRegistr…
|
||
- [routes](./src/routes/build-routes.md) — The build-routes module constructs the `OpenAPIHono` instance that the plugin mounts under `routePrefix` (`/search` by…
|
||
- [build-routes](./src/routes/build-routes.md) — The build-routes module constructs the `OpenAPIHono` instance that the plugin mounts under `routePrefix` (`/search` by…
|
||
- [schemas](./src/schemas/schemas.md) — The schemas module owns the public Zod surface of `@suaveplan/api-plugin-search`. Every HTTP route in the package valid…
|
||
- [options](./src/schemas/options.md) — The options module defines the Zod schema for the input accepted by `createSearchPlugin(options?)`. The factory validat…
|
||
- [schemas](./src/schemas/schemas.md) — The schemas module owns the public Zod surface of `@suaveplan/api-plugin-search`. Every HTTP route in the package valid…
|
||
- [service](./src/service/service.md) — The service module is the in-memory search engine that powers `@suaveplan/api-plugin-search`. It owns index creation an…
|
||
- [service](./src/service/service.md) — The service module is the in-memory search engine that powers `@suaveplan/api-plugin-search`. It owns index creation an…
|
||
- [services](./src/services/registry-augmentation.md) — This module is a TypeScript `declare module` augmentation. It adds the `searchIndexes` slot to `@suaveplan/api-plugin`'…
|
||
- [registry-augmentation](./src/services/registry-augmentation.md) — This module is a TypeScript `declare module` augmentation. It adds the `searchIndexes` slot to `@suaveplan/api-plugin`'…
|
||
- [types](./src/types/types.md) — The types module owns the internal-shape contracts of the search plugin — the materialised `SearchIndex` held in memory…
|
||
- [types](./src/types/types.md) — The types module owns the internal-shape contracts of the search plugin — the materialised `SearchIndex` held in memory…
|
||
<!-- end:auto-docs -->
|
||
|
||
## Install
|
||
|
||
```bash
|
||
bun add @suaveplan/api-plugin-search
|
||
```
|
||
|
||
## Quick start
|
||
|
||
```ts
|
||
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`](./src/analyzer/analyzer.md)
|
||
- [`error-codes/error-codes`](./src/error-codes/error-codes.md)
|
||
- [`otel/instruments`](./src/otel/instruments.md)
|
||
- [`plugin/plugin`](./src/plugin/plugin.md)
|
||
- [`routes/build-routes`](./src/routes/build-routes.md)
|
||
- [`schemas/options`](./src/schemas/options.md)
|
||
- [`schemas/schemas`](./src/schemas/schemas.md)
|
||
- [`service/service`](./src/service/service.md)
|
||
- [`services/registry-augmentation`](./src/services/registry-augmentation.md)
|
||
- [`types/types`](./src/types/types.md)
|
||
|
||
## 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.
|
||
|