@quaesitor-textus/mongo 0.2.0

package/LICENSE

@@ -0,0 +1,180 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Derivative Works, as You see fit.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (even if such Contributor has been advised of the possibility
+      of such damages).
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer such
+      obligations only on Your own behalf and on behalf of the sole
+      responsibility of those additional obligations, not on behalf of
+      any other Contributor. You are solely responsible for fulfilling
+      the obligations under such additional warranty or liability terms.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Kristof Csillag
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,417 @@
+# @quaesitor-textus/mongo
+
+Server-side MongoDB search that reproduces the exact matching behaviour of
+[`@quaesitor-textus/core`](../core) — diacritic- and case-insensitive substring
+matching — **index-backed** and with **zero server-side JavaScript**.
+
+## What it is / why
+
+`@quaesitor-textus/core` does its matching in the browser: it folds text (Unicode
+normalization, diacritic stripping, case folding) and runs substring matches over
+an in-memory corpus. That is perfect for a few hundred items already on the client,
+but it does not scale to a collection that lives in a database.
+
+This package is the server-side companion. It moves the same matching semantics
+into MongoDB while keeping two hard constraints:
+
+- **Index-backed.** Queries use a multikey index over stored n-grams as a coarse
+  superset pre-filter, so Mongo never has to scan the whole collection for a
+  substring.
+- **No server-side JavaScript.** MongoDB's query engine (and its `$where` / server
+  JS) does **not** implement `String.prototype.normalize`, so it cannot fold
+  Unicode the way the client does. Instead, **all normalization happens in Node at
+  ingest time**: each document gets derived fields holding fully-folded n-grams and
+  one pre-folded "verify" string per query mode. Queries then combine a `$all`
+  n-gram filter with a `$regex` substring check against the appropriate verify
+  string. The folding never runs inside Mongo — it was already baked into the
+  stored fields.
+
+The result: a server query built by `buildTextSearchFilter` returns exactly what
+the client's `matchItem` would have matched over the same corpus. (That guarantee
+is exercised by the parity integration test in this package.)
+
+### How the derived fields are shaped
+
+For namespace `ns` (default `_qt`) and a configured target `t`, each document gains:
+
+```
+{ [ns]: { [t]: { ngrams: string[], norm: string, /* + e.g. */ norm_cs: string } } }
+```
+
+- `ngrams` — bigrams + trigrams of the **fully-folded** corpus
+  (`normalizeText(corpus, {})`). This is the coarsest fold, so the same n-gram index
+  is a valid superset filter for every query mode.
+- one **verify string** per stored query mode, keyed by `modeKey(mode)`:
+  - `norm` — the base, fully-folded string (case- and diacritic-insensitive).
+  - `norm_cs` — case-sensitive (diacritics stripped, case preserved).
+  - `norm_ds` — diacritic-sensitive (lowercased, diacritics preserved).
+  - `norm_cs_ds` — both case- and diacritic-sensitive.
+
+A query for a given mode `$all`s the fully-folded n-grams of its patterns against
+`ngrams`, then `$regex`es each pattern (folded with that same mode) against the
+mode's verify string.
+
+## Mongo setup
+
+Change streams (used by the recommended watcher, below) require MongoDB to run as a
+**replica set**. A single-node replica set is enough for development.
+
+With a stock `mongo:7` server:
+
+```bash
+mongod --replSet rs0 --bind_ip_all
+# in another shell, once:
+mongosh --eval 'rs.initiate()'
+```
+
+(`packages/demo` ships a `docker-compose.yml` + `Makefile` that does exactly this on
+port 27018 with an idempotent `rs.initiate()` healthcheck — see the runnable
+companion below.)
+
+Then create the search indexes once, against your collection:
+
+```ts
+import { createSearchIndexes } from '@quaesitor-textus/mongo'
+
+await createSearchIndexes(collection, config)
+```
+
+This creates one multikey index per target over its `ngrams` array (named
+`${namespace}_${target}_ngrams`). If you only want to inspect the specs without
+creating them, call `searchIndexSpecs(config)`.
+
+## Server wiring
+
+### 1. Define a `MongoSearchConfig`
+
+A target names the document fields whose text you want to search, plus the query
+modes you intend to support at runtime.
+
+```ts
+import type { MongoSearchConfig } from '@quaesitor-textus/mongo'
+
+const config: MongoSearchConfig = {
+  namespace: '_qt',          // optional; default '_qt'
+  ngramSizes: [2, 3],        // optional; default [2, 3]
+  targets: {
+    author: { fields: ['author'], queryModes: [{ caseSensitive: true }] },
+    title:  { fields: ['title'],  queryModes: [{ caseSensitive: true }] },
+  },
+}
+```
+
+- `fields` — paths harvested into the corpus (same path semantics as the core
+  filter, e.g. nested objects/arrays and the `$` root).
+- `options` — the base/default query mode for the target; defaults to `{}` (fully
+  folded).
+- `queryModes` — additional runtime-selectable modes. The set of verify strings a
+  target stores is `[options ?? {}, ...queryModes]` deduped by `modeKey`.
+
+### 2. Keep derived fields in sync
+
+You need each document's derived `[namespace]` block to stay current as documents
+are written. There are two ways:
+
+**(a) Compute inline on every write.** Merge the derived fields into the document
+before you persist it:
+
+```ts
+import { computeSearchFields } from '@quaesitor-textus/mongo'
+
+const doc = { author: 'Gabriel García Márquez', title: 'One Hundred Years of Solitude' }
+await collection.insertOne({ ...doc, ...computeSearchFields(doc, config) })
+```
+
+This gives you read-your-writes: the document is searchable the instant the insert
+acknowledges. The cost is that every write path in your app must remember to do it.
+
+**(b) Run the change-stream watcher (recommended).** Start it once at boot and write
+your documents **raw** — the watcher recomputes and `$set`s the derived block for
+you:
+
+```ts
+import { startSearchSync } from '@quaesitor-textus/mongo'
+
+const sync = startSearchSync(collection, config)
+// ... later, on shutdown:
+await sync.stop()
+```
+
+The watcher tails the collection's change stream (`insert` / `update` / `replace`),
+recomputes `computeSearchFields`, and writes the derived block back. It includes a
+loop guard: if the stored derived block already equals the freshly computed one, it
+skips the write so its own update does not retrigger the handler.
+
+`startSearchSync` returns a `SearchSync` **emitter**: register a listener with
+`sync.on(listener)` (remove it with `sync.off(listener)`) to receive a stream of
+events — `indexing-started`, `indexing-finished` (a debounced burst summary, handy
+for logging), and a per-document `indexed` event fired **after** each derive write
+resolves (so a filter on the derived fields will match). Switch on `event.type`:
+
+```ts
+const sync = startSearchSync(collection, config)
+sync.on((e) => {
+  if (e.type === 'indexing-started') console.log('indexing started')
+  else if (e.type === 'indexing-finished') console.log(`indexed ${e.count} doc(s) in ${e.durationMs}ms`)
+})
+```
+
+**Backfill for external writers / restart resilience.** Change streams are
+forward-only: they only see writes that happen *after* the watcher opens the stream,
+so documents written before the watcher ran (or during downtime) never get a derived
+block. Pass `{ backfill: true }` to sweep, on start, any pre-existing documents that
+are missing the namespace (`{ [namespace]: { $exists: false } }`) and derive them:
+
+```ts
+const sync = startSearchSync(collection, config, { backfill: true })
+```
+
+This is the heterogeneous-writer pattern: one process (e.g. a Python tool) writes raw
+documents, while a separate Node app runs the watcher with `backfill: true` and serves
+search. On boot the Node app catches up on everything written while it was down, then
+keeps current via the change stream. Backfill also requires a replica set.
+
+**Versioned re-indexing.** `computeSearchFields` stamps `_qt._v = \`${SEARCH_FIELDS_VERSION}:${fingerprint(config)}\`` on each derived block. `SEARCH_FIELDS_VERSION` (a code constant) is bumped on any change to the derived output (normalization, n-grams, corpus, shape); the fingerprint hashes the derivation-affecting config (namespace, n-gram sizes, targets). The `backfill` sweep re-derives documents whose stored `_v` differs from the current one, so **upgrading the library or changing your config automatically re-indexes the collection on the next start with `backfill: true`** — no manual migration. This is how a normalization change (e.g. the precomposed-letter folding in v2) invalidates and rebuilds existing data.
+
+**Trade-offs of the watcher:**
+
+- It **requires a replica set** (change streams are a replica-set feature).
+- Sync is **asynchronous**: there is a small window between your raw write and the
+  watcher's `$set`. During that window the document exists but its text is not yet
+  searchable, so **read-your-writes on text search is not guaranteed**. If you need
+  the document searchable immediately, use approach (a) for that write (or do both —
+  inline compute on the critical path, watcher as a backstop).
+
+### 3. Translate a text-search node into a Mongo filter
+
+```ts
+import { buildTextSearchFilter } from '@quaesitor-textus/mongo'
+
+const filter = buildTextSearchFilter('author', ['garcia', 'marquez'], config)
+const rows = await collection.find(filter).toArray()
+```
+
+`buildTextSearchFilter(target, patterns, config, options?)` returns a
+`Filter<Document>`:
+
+- empty `patterns` → `{}` (match everything);
+- otherwise `{ $and: [ { ngramField: { $all: <folded ngrams> } }, ...perPatternVerifyRegex ] }`.
+
+Each pattern must be a substring of the mode-folded verify string (patterns are
+AND-ed). Pass `options` to pick a non-default mode (e.g.
+`{ caseSensitive: true }`); omit it to use the target's base mode.
+
+## Client usage
+
+The browser builds a query *description* and POSTs it to your server, which calls
+`buildTextSearchFilter`. Below are three escalating shapes. The client tokenizes raw
+input into patterns with core's `parseInput`.
+
+### (a) Naive single field
+
+```ts
+import { parseInput } from '@quaesitor-textus/core'
+
+// client
+const patterns = parseInput(userInput)              // e.g. 'garcia marquez' → ['garcia','marquez']
+await fetch('/api/search', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ patterns }),
+})
+
+// server
+app.post('/api/search', async (req) => {
+  const { patterns } = req.body as { patterns: string[] }
+  const filter = buildTextSearchFilter('author', patterns, config)
+  return collection.find(filter).toArray()
+})
+```
+
+### (b) Two fields (author OR title)
+
+Combine two per-target filters yourself with `$or`:
+
+```ts
+// server
+const { patterns } = req.body as { patterns: string[] }
+const filter = {
+  $or: [
+    buildTextSearchFilter('author', patterns, config),
+    buildTextSearchFilter('title', patterns, config),
+  ],
+}
+return collection.find(filter).toArray()
+```
+
+### (c) Inside a predicate tree
+
+For richer UIs you will want to compose text search with other conditions (boolean
+logic, scalar leaves). Here is **one reasonable, generic** predicate shape:
+
+```ts
+type Predicate =
+  | { AND: Predicate[] }
+  | { OR: Predicate[] }
+  | { TEXT: { target: string; patterns: string[]; options?: SearchOptions } }
+  | { YEAR: { gte?: number; lte?: number } }   // example scalar leaf
+
+function toMongo(p: Predicate, config: MongoSearchConfig): Filter<Document> {
+  if ('AND' in p) return p.AND.length ? { $and: p.AND.map(c => toMongo(c, config)) } : {}
+  if ('OR' in p)  return p.OR.length  ? { $or:  p.OR.map(c => toMongo(c, config)) } : {}
+  if ('TEXT' in p) return buildTextSearchFilter(p.TEXT.target, p.TEXT.patterns, config, p.TEXT.options)
+  // ...scalar leaves like YEAR translate to ordinary Mongo range filters
+  return {}
+}
+```
+
+> **Note:** this package does **not** own or assume your filter syntax. The shape
+> above is just one reasonable example — `buildTextSearchFilter` is the only piece
+> you need from here; you decide how text-search nodes fit into your own query
+> language. (`packages/demo` implements a concrete version of exactly this pattern.)
+
+## Maintenance alternatives
+
+The shipped mechanism for keeping derived fields in sync is the change-stream
+**watcher** (`startSearchSync`). Other approaches are possible but worse:
+
+- **Mongoose plugin** (pre-save hook) or a **driver wrapper** that intercepts writes:
+  both can call `computeSearchFields` and merge the result before persisting. They
+  work for full-document writes, but partial updates (`$set` of a single field) force
+  a **racy read-modify-write**: you must re-read the current document, recompute the
+  whole corpus, and write back — and there is no way to recompute server-side (no
+  Unicode normalization in Mongo's engine), so two concurrent partial updates can
+  clobber each other's derived fields.
+
+The watcher sidesteps this: it always recomputes from the post-write `fullDocument`,
+so it is correct regardless of how the write was shaped. Its only requirements are a
+replica set and tolerance for the brief async-staleness window (see the watcher
+trade-offs above).
+
+## Live search (SSE)
+
+The watcher's per-document `indexed` event is the foundation for a **live, push-based
+search**: clients see the current matching set, then watch new matches arrive as
+documents are indexed. This package ships a small, layered, transport-agnostic engine
+plus thin adapters for Fastify, Express, and Next.js (App + Pages Router).
+
+### The engine: `createLiveSearch`
+
+`createLiveSearch` is framework-agnostic — it knows nothing about HTTP. Give it a
+`SearchSync` (from `startSearchSync`), the collection/config, a Mongo `filter`, and a
+`sendEvent` callback; it emits:
+
+- `snapshot` — the current matching set (capped), sent once on start;
+- `match` — one per newly-`indexed` document that matches `filter`;
+- `capped` — sent once the emitted count reaches `cap` (default `500`), after which
+  no further matches are pushed.
+
+```ts
+import { createLiveSearch } from '@quaesitor-textus/mongo'
+
+const live = createLiveSearch({
+  sync,                       // a SearchSync from startSearchSync
+  collection,
+  config,
+  filter,                     // a Filter<Document>, e.g. from buildTextSearchFilter
+  sort: { field: 'year', dir: 1 },   // optional; sorts the initial snapshot
+  cap: 500,                   // optional; default 500
+  sendEvent: (event) => { /* serialize + push to the client */ },
+})
+// ... when the client disconnects:
+live.stop()
+```
+
+Internally it sends the snapshot (a sorted, capped `find`), then for each `indexed`
+event runs a `findOne` match-test (`_id` AND `filter`) and emits a `match` only for
+newly-matching, not-yet-seen documents.
+
+### The wire helpers: `formatSse` / `sseComment`
+
+These format the SSE wire bytes, independent of any framework:
+
+```ts
+import { formatSse, sseComment } from '@quaesitor-textus/mongo'
+
+formatSse({ type: 'match', item }) // => `data: {"type":"match","item":{...}}\n\n`
+sseComment()                       // => `: ping\n\n`  (a heartbeat comment)
+```
+
+### Fastify — `@quaesitor-textus/mongo/fastify`
+
+`streamLiveSearch` is the transport glue for Fastify: it sets the SSE headers, hijacks
+the reply socket, runs a heartbeat (`heartbeatMs`, default `25000`), wires
+`createLiveSearch` to `reply.raw.write(formatSse(...))`, and tears everything down when
+the request closes. It lives behind a subpath export; **fastify is an optional peer
+dependency**, so you only pull it in if you use this adapter.
+
+```ts
+import { streamLiveSearch } from '@quaesitor-textus/mongo/fastify'
+
+app.get('/api/live', (request, reply) => {
+  const filter = buildTextSearchFilter('author', patterns, config)
+  streamLiveSearch(request, reply, {
+    sync,                  // a SearchSync shared across requests
+    collection,
+    config,
+    filter,
+    sort: { field: 'year', dir: 1 },  // optional
+    cap: 500,                          // optional
+    heartbeatMs: 25000,                // optional
+  })
+})
+```
+
+### Express — `@quaesitor-textus/mongo/express`
+
+```ts
+import { streamLiveSearch } from '@quaesitor-textus/mongo/express'
+
+app.get('/api/live', (req, res) => {
+  const filter = buildTextSearchFilter('author', patterns, config)
+  streamLiveSearch(req, res, { sync, collection, config, filter })
+})
+```
+
+### Next.js Pages Router — `@quaesitor-textus/mongo/next/pages`
+
+```ts
+import { streamLiveSearch } from '@quaesitor-textus/mongo/next/pages'
+
+export default function handler(req, res) {
+  streamLiveSearch(req, res, { sync, collection, config, filter })
+}
+export const config = { api: { responseLimit: false } } // allow long-lived SSE
+```
+
+### Next.js App Router — `@quaesitor-textus/mongo/next/app`
+
+```ts
+import { liveSearchResponse } from '@quaesitor-textus/mongo/next/app'
+
+export async function GET(request: Request) {
+  // parse the filter from request.url, build the Mongo filter, then:
+  return liveSearchResponse({ sync, collection, config, filter })
+}
+```
+
+**Dependency-free by design.** The Express and Next Pages adapters are typed against
+Node's `http` `IncomingMessage`/`ServerResponse` (those frameworks' request/response
+objects are subtypes), and the Next App adapter uses only the Web `Response`/`ReadableStream`
+APIs. So **none of them import — or require you to install — `express` or `next`**; you
+only need the framework you already use. Only the Fastify adapter imports its framework
+(for `reply.hijack()`), as an optional peer dependency.
+
+### Any other framework
+
+`createLiveSearch` + `formatSse`/`sseComment` are the reusable core. Wiring them to any
+runtime that exposes a writable response is a handful of lines (write the SSE headers,
+push each `sendEvent` payload through `formatSse`, run a heartbeat with `sseComment`, call
+`live.stop()` on disconnect) — exactly what the shared `runLiveSearch` helper does.
+
+## Runnable companion
+
+See [`packages/demo`](../demo) for a full-stack, runnable example: a Fastify + Vite /
+React / antd book-search UI over MongoDB with server-side pagination, a year-range
+predicate composed with text search, and a live watcher showcase (the "truckload"
+button inserts raw documents and you watch them become searchable a moment later).