QueryCacheEngine<T>

Defined in: rxdb-plugin-querycache/src/QueryCacheEngine.ts:155

Experimental

QueryCache 同步策略仓库

Example

const repo = new QueryCacheEngine('Product', remoteAdapter, localAdapter, localReader, pendingWriteIds);

// 查询 - 自动增量同步
const products = await firstValueFrom(repo.find({ where: { combinator: 'and', rules: [] } }));

// 单个查询
const product = await firstValueFrom(repo.findById('product-123'));

Remarks

生产路径不直接 new 本类：SyncType.QueryCache 的实体由 Repository 经 createQueryCachePrimary 接入（US-020 阶段 A），本类只负责 metadata-diff 与增量 pull。

远端对 where 的答复是权威的：本次 where 的本地投影里、远端没有返回的行一律是孤儿， 同步时删除（US-020 AC#11）。删除范围严格限定在该投影内 —— 不匹配 where 的本地行 不在本次问题域里，不能因为「远端没提」就被清掉。

直接 new 本类不在 1.0 兼容承诺内；稳定面是 SyncType.QueryCache 经 Repository 的间接路径。层级口径见 requirements/versioning-policy.md「实验性层级」。

Type Parameters

Type Parameter	Default type	Description
T extends EntityBaseType	EntityBaseType	实体类型

Constructors

Constructor

new QueryCacheEngine<T>(
   entityName, 
   remoteAdapter, 
   localAdapter, 
   localReader, 
   pendingWriteIds
): QueryCacheEngine<T>;

Defined in: rxdb-plugin-querycache/src/QueryCacheEngine.ts:180

Experimental

Parameters

Parameter	Type	Description
entityName	string	实体名
remoteAdapter	QueryCacheRemoteAdapter	远端适配器
localAdapter	QueryCacheLocalAdapter	本地适配器，负责写侧（upsert / delete）与单实体元数据
localReader	QueryCacheLocalReader<InstanceType<T>>	本地行读取出口，通常是该实体的本地 IRepository（US-020 D8）
pendingWriteIds	QueryCachePendingWriteIds	出站队列此刻占着哪些 id；每轮同步在写之前问一次

Returns

QueryCacheEngine<T>

Properties

entityName

readonly entityName: string;

Defined in: rxdb-plugin-querycache/src/QueryCacheEngine.ts:171

Experimental

实体名称

Methods

create()

create(data): Observable<InstanceType<T>>;

Defined in: rxdb-plugin-querycache/src/QueryCacheEngine.ts:369

Experimental

创建实体

执行远程优先写入策略：

1. 写入远程数据库
2. 远程成功后，将返回数据缓存到本地
3. 返回服务器生成的完整实体（可能包含服务器生成的 id/updatedAt）

Parameters

Parameter	Type	Description
data	Partial<InstanceType<T>>	要创建的实体数据

Returns

Observable<InstanceType<T>>

Observable<InstanceType<T>> - 创建成功的实体

Throws

远程写入失败时抛出错误，本地不写入

Example

repo.create({ name: 'New Product', price: 99 })
  .subscribe();

---

delete()

delete(ids): Observable<void>;

Defined in: rxdb-plugin-querycache/src/QueryCacheEngine.ts:433

Experimental

删除实体

执行远程优先写入策略：

1. 从远程数据库删除
2. 远程成功后，从本地缓存删除

Parameters

Parameter	Type	Description
ids	string | string[]	要删除的实体 ID 或 ID 数组

Returns

Observable<void>

Observable<void>

Throws

远程删除失败时抛出错误，本地不删除

Example

repo.delete('product-123').subscribe();
repo.delete(['p1', 'p2', 'p3']).subscribe();

---

find()

find(options): Observable<InstanceType<T>[]>;

Defined in: rxdb-plugin-querycache/src/QueryCacheEngine.ts:222

Experimental

查询实体列表

执行 QueryCache 同步流程：

1. fetchMetadata → 获取远程元数据
2. getMetadataByIds → 获取本地元数据
3. diffMetadata → 对比得出需要拉取的 ID
4. findByIds → 只拉取 missing + stale
5. upsertMany → 写入本地缓存
6. 返回合并结果

当 localCacheFirst: true 时 (SWR 模式)：

1. 立即返回本地缓存（如果有）
2. 后台执行上述同步流程
3. 如果数据有变化，发射更新后的结果

Parameters

Parameter	Type	Description
options	QueryCacheFindOptions<T>	查询选项

Returns

Observable<InstanceType<T>[]>

Observable<InstanceType<T>[]>

Example

repo.find({ where: { combinator: 'and', rules: [{ field: 'status', operator: '=', value: 'active' }] } })
  .subscribe();

// SWR 模式
repo.find({ where: { ... }, localCacheFirst: true })
  .subscribe(products => {
    // 第一次发射：本地缓存（立即）
    // 第二次发射：远程更新后数据（如果有变化）
  });

---

findById()

findById(id): Observable<InstanceType<T> | null>;

Defined in: rxdb-plugin-querycache/src/QueryCacheEngine.ts:302

Experimental

按 ID 查询单个实体

Parameters

Parameter	Type	Description
id	EntityStaticType<T, "idType">	实体 ID

Returns

Observable<InstanceType<T> | null>

Observable<InstanceType<T> | null>

Example

repo.findById('product-123')
  .subscribe();

---

invalidateInflight()

invalidateInflight(): void;

Defined in: rxdb-plugin-querycache/src/QueryCacheEngine.ts:285

Experimental

作废全部在飞查询（US-023 D13）。

Returns

void

Remarks

只清并发去重表，不取消已有订阅：正在等待的调用方照常收到它们那次的结果， 只是这些流不再被后来者复用。远端数据已变的那一刻，在飞的拉取问的是变更前的 远端状态；让失效后的重跑复用它，重跑就等于没跑。

「不取消」只管到结果这一层：陈旧流照常把它那次的答案发给自己的订阅者， 但从此不再写本地缓存（QueryCacheEngine.#isCurrent）。缓存是共享的， 而那份答案按定义已经过期 —— 让它落地就会把重跑刚写进来的新行盖回旧值， 且错误会一直留到 syncStaleTime 到期：重跑那次的 remember 是成功的， 窗口内不会再有人去校验一遍。

本地写路径不需要调用它 —— 那条路径上远端已由本仓储自己写过，在飞查询问到的 就是写后的状态。

---

update()

update(id, data): Observable<InstanceType<T>>;

Defined in: rxdb-plugin-querycache/src/QueryCacheEngine.ts:402

Experimental

更新实体

执行远程优先写入策略：

1. 更新远程数据库
2. 远程成功后，将返回数据缓存到本地（使用服务器返回的最新 updatedAt）
3. 返回更新后的完整实体

Parameters

Parameter	Type	Description
id	string	实体 ID
data	Partial<InstanceType<T>>	要更新的字段

Returns

Observable<InstanceType<T>>

Observable<InstanceType<T>> - 更新成功的实体

Throws

远程更新失败时抛出错误，本地不更新

Example

repo.update('product-123', { price: 199 })
  .subscribe();