RxDBPluginSearch

Defined in: packages/rxdb-plugin-search/src/plugin.ts:158

@aiao/rxdb-plugin-search 主类。

职责：

• createRxDatabase 阶段校验 adapter（fail-fast）
• install() 阶段安装 FTS5 + backfill + 缓存 searchable 索引（时机由宿主按 RxDBPluginSearch.inject 决定，插件自己不等依赖）
• 在 RxDB 上挂载 search / searchCollection 入口
• 订阅 ENTITY_LOCAL_CREATE/UPDATE/REMOVE_EVENT 向注册的 handle 派发静默重查

Extends

• RxDBPluginBase

Implements

• IRxDBPlugin

Constructors

Constructor

new RxDBPluginSearch(rxdb, options?): RxDBPluginSearch;

Defined in: packages/rxdb-plugin-search/src/plugin.ts:239

Parameters

Parameter	Type
rxdb	RxDB
options?	SearchPluginOptions

Returns

RxDBPluginSearch

Overrides

RxDBPluginBase.constructor

Properties

inject

readonly inject: readonly ["adapter:local"];

Defined in: packages/rxdb-plugin-search/src/plugin.ts:196

本地适配器就绪之后才安装。

Remarks

声明之前这段等待写在插件自己身上：#runInstall() 先 rxdb.connect(localAdapterName) 再 firstValueFrom(adapterConnected$)，而 RxDB.connect() 又在等插件安装完成—— 两边互等，只靠「adapterConnected$ 必须早于插件安装置位」这条时序约定绕开死锁。 交给宿主之后，install() 被调用即代表引导链（迁移、建表、索引）已经跑完， 直接 RxDB.localAdapterSync 取实例即可。

Implementation of

IRxDBPlugin.inject

---

lifecycle

readonly lifecycle: "scoped";

Defined in: packages/rxdb-plugin-search/src/plugin.ts:206

拆卸完全交给作用域。

Remarks

原来的 SearchPluginPhase 状态机已经没有了：installing / failed 由宿主调度器 记账，destroyed 由 scope.state 表达。缓存复位从 destroy() 挪进作用域的一条 撤销条目（search:state），于是「先释放作用域、再补一次 destroy()」的两步拆卸 收敛成一步。

Implementation of

IRxDBPlugin.lifecycle

---

name

readonly name: Uncapitalize<string> = 'search';

Defined in: packages/rxdb-plugin-search/src/plugin.ts:207

插件名，用于日志与宿主侧的错误归因

Implementation of

IRxDBPlugin.name

---

options

readonly options: SearchPluginOptions;

Defined in: packages/rxdb-plugin-search/src/plugin.ts:209

插件级默认项（页大小、防抖、snippet、排除 collection）

---

rxdb

protected readonly rxdb: RxDB;

Defined in: packages/rxdb/dist/rxdb-plugin.d.ts:136

Inherited from

RxDBPluginBase.rxdb

Accessors

ready

Get Signature

get ready(): Promise<void>;

Defined in: packages/rxdb-plugin-search/src/plugin.ts:235

当 FTS5 安装完成时 resolve；若失败则 reject，便于宿主应用在关键路径等待并处理 SearchSchemaMismatchError 等致命错误。插件不擅自记录日志；宿主通过显式 await 此 promise 决定错误展示与遥测策略。

Remarks

一个连接纪元一格 deferred，各态如下：

时机	ready
connect() 之前 / 依赖未就绪	pending
安装中	pending
安装成功	resolve
安装失败	reject（原始安装错误）
作用域被释放（断连 / 回滚）	reject（destroyed）

「未安装先 reject」的老口径被 pending 取代是有意的：依赖调度落地之后， 「还没轮到装」与「装不起来」不再是同一件事，前者只是还没到时候。老口径下 await connect() 与 await ready 之间存在一个竞态窗口——connect() 在飞时 ready 已经 reject，调用方拿到的错误与真实原因无关。

返回的 promise 逐纪元更换。跨断连持有同一个引用读到的是那一纪元的结果， 重连之后要重新读一次 ready。

Returns

Promise<void>

Methods

createHandle()

createHandle(performSearch, options?): SearchHandle;

Defined in: packages/rxdb-plugin-search/src/plugin.ts:350

直接以注入 performSearch 的方式创建 SearchHandle。

供框架绑定层与集成测试使用（便于 mock 执行器）；生产路径请使用 search / searchCollection。

Parameters

Parameter	Type	Description
performSearch	PerformSearch	真实查询执行函数；入参是归一化后的查询词与页号
options?	SearchOptions	单次调用级覆盖（debounce / initialQuery）

Returns

SearchHandle

---

install()

install(scope): Promise<void>;

Defined in: packages/rxdb-plugin-search/src/plugin.ts:249

安装插件。

Parameters

Parameter	Type	Description
scope	LifecycleScope	本次连接纪元的插件激活作用域；一次 acquire() 只包一步可能抛错的获取

Returns

Promise<void>

Remarks

抛错（含 Promise reject）视为安装失败：宿主会先把已经登记进 scope 的部分 逆序释放掉，再把原错误传播给 connect()。回滚期间的清理错误只记日志，不会盖掉安装错误。

实现方不写形参不破坏契约——install() 与 install(scope) 同样满足本接口。

Implementation of

IRxDBPlugin.install

---

search()

search(query, options?): SearchHandle;

Defined in: packages/rxdb-plugin-search/src/plugin.ts:299

跨 collection 聚合搜索入口。

query 可以是字符串（一次性查询）或 Observable<string>（对接输入流，自带防抖）。 SearchOptions.collections 用于进一步收窄范围（接受实体名或表名）； 包含未知名称或与插件级 excludedCollections 求交后为空时抛错（fail-fast）。

Parameters

Parameter	Type
query	string | Observable<string>
options?	SearchOptions

Returns

SearchHandle

Throws

插件未安装（db.connect() 之前）或作用域已释放时抛错——与 searchCollection 对称。不会降级成空结果句柄，见 #assertInstalled。

Throws

install() 失败时抛出原始安装错误。

---

searchCollection()

searchCollection(
   collection, 
   query, 
   options?
): SearchHandle;

Defined in: packages/rxdb-plugin-search/src/plugin.ts:324

限定单个 collection（按实体名或表名）的搜索入口。

若给定 collection 未被索引（无 searchable 字段）或被 excludedCollections 排除，抛错； 宿主应在调用前通过 RxDBPluginSearch.ready 确认安装完成。

Parameters

Parameter	Type
collection	string
query	string | Observable<string>
options?	SearchOptions

Returns

SearchHandle

Throws

插件未安装（db.connect() 之前）或作用域已释放时抛错——与 search 对称。 该守卫先于「不可搜索」判断，避免把「插件没装」误报成「这个 collection 不可搜索」。

Throws

install() 失败时抛出原始安装错误。