RxDBAdapterHttp

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:94

基于用户自有 REST API 的 QueryCache 远程适配器。

Remarks

transport 归本类，不归 handler。 handler 只做协议映射：request() 产出请求描述， parse() 解码响应体。发请求、注入 auth、提取状态码、分类错误、翻页、分块全在这一侧。让 handler 自己发请求的话，AC#12 / #13 / #16 三条契约的担保人就变成接入方，本包只能退化成文档劝告。

Example

const rxdb = new RxDB({
  dbName: 'app',
  entities: [Recipe],
  sync: `{ type: SyncType.QueryCache, local: { adapter: 'sqlite' }, remote: { adapter: 'http' } }`
});
// 读引擎随插件走（`@aiao/rxdb-plugin-querycache`），漏装时 `connect()` 直接拒绝
rxdb.use(rxDBPluginQueryCache);
rxdb.adapter('http', db => new RxDBAdapterHttp(db, {
  baseUrl: 'https://api.example.com',
  handlers: {
    onFetchMetadata: {
      request: ctx => ({ url: `${ctx.entityName}/metadata`, method: 'POST', body: ctx }),
      parse: body => body as QueryCacheEntityMetadata[]
    },
    onFindByIds: {
      request: ctx => ({ url: `${ctx.entityName}`, method: 'POST', body: { ids: ctx.ids } }),
      parse: body => body as unknown[]
    }
  }
}));

Extends

RxDBAdapterRemoteBase

Implements

IRxDBAdapter

Constructors

Constructor

new RxDBAdapterHttp(rxdb, options): RxDBAdapterHttp;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:171

Parameters

Parameter	Type	Description
`rxdb`	`RxDB`	宿主 RxDB 实例
`options`	`HttpAdapterOptions`	baseUrl、handlers 与可选的数值/认证配置

Returns

RxDBAdapterHttp

Throws

HttpConfigError baseUrl 为空、缺必选 handler，或任一数值配置不是 finite 正整数

Overrides

RxDBAdapterRemoteBase.constructor

Properties

config

readonly config: HttpNumericConfig;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:123

已校验的数值配置，构造期定型

create?

optional create?: <R>(entityName, data) => Observable<R>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:139

创建实体。仅在配置了 onCreate 时存在。

Type Parameters

Type Parameter
`R`

Parameters

Parameter	Type
`entityName`	`string`
`data`	`R`

Returns

Observable<R>

Remarks

QueryCacheEngine 用 if (!this.remoteAdapter.create) 做特性探测，所以「不支持」必须表现为属性缺席，不能是一个总在抛错的方法——后者会让探测判 true， AC#4 那句清晰的「Remote adapter does not support create」变成运行期意外。

因此这里只 declare 类型，实体由构造期的 #installWriteDucks() 按需挂上。

delete?

optional delete?: (entityName, ids) => Observable<void>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:145

删除实体。仅在配置了 onDelete 时存在，理由同 RxDBAdapterHttp.create。

Parameters

Parameter	Type
`entityName`	`string`
`ids`	`string` \| `string`[]

Returns

Observable<void>

name

readonly name: "http" = ADAPTER_NAME;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:120

适配器名，与 RxDB.adapter() 登记时用的键同值；错误消息与 getAdapter() 都按它认人

Implementation of

IRxDBAdapter.name

options

readonly options: HttpAdapterOptions;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:173

baseUrl、handlers 与可选的数值/认证配置

repository_cache

protected readonly repository_cache: Map<EntityType, RepositoryInstance<EntityType>>;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:347

Inherited from

RxDBAdapterRemoteBase.repository_cache

repository_map

protected readonly repository_map: Map<string, AdapterRepositoryConstructor<RxDBAdapterHttp, RepositoryInstance<EntityType>>>;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:346

Inherited from

RxDBAdapterRemoteBase.repository_map

rxdb

readonly rxdb: RxDB;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:345

Inherited from

RxDBAdapterRemoteBase.rxdb

update?

optional update?: <R>(entityName, id, data) => Observable<R>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:142

更新实体。仅在配置了 onUpdate 时存在，理由同 RxDBAdapterHttp.create。

Type Parameters

Type Parameter
`R`

Parameters

Parameter	Type
`entityName`	`string`
`id`	`string`
`data`	`Partial`<`R`>

Returns

Observable<R>

Accessors

changeFeedEnabled

Get Signature

get changeFeedEnabled(): boolean;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:162

变更通知通道此刻要不要跑，由 RxDBAdapterHttp.startChangeFeed / RxDBAdapterHttp.stopChangeFeed 翻转。

Remarks

这是意图，不是连接状态：通道正在退避重连、或所在运行时压根没有 EventSource 时，它照样是 true。想知道连接本身的死活，看 changeFeed.onUnavailable 的诊断上报—— EventSource 不暴露状态码，一个从这里返回的布尔值答不了「为什么没连上」，只会把两种问题混成一种。

（夹在写 duck 与构造函数之间是 lint member-ordering 的要求：访问器排在字段之后、构造函数之前。语义上它属于下面那组运行时开关。）

Returns

boolean

未配 changeFeed 时恒为 false

Methods

branchExists()?

optional branchExists(branchId): Promise<boolean>;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:804

Parameters

Parameter	Type
`branchId`	`string`

Returns

Promise<boolean>

Inherited from

RxDBAdapterRemoteBase.branchExists

connect()

connect(): Promise<IRxDBAdapter>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:209

不建立长连接，只做本地校验。

Returns

Promise<IRxDBAdapter>

适配器自身

Remarks

不发探测请求：远端此刻不可达不代表配置错，那是查询期的网络错误，交给 isNetworkError 分类。想在启动时确认可达性的应用自己调 RxDBAdapterHttp.isTableExisted，那是显式选择而非框架行为。

配了 changeFeed 才有长连接，且它建在最后：校验没过的 connect() 不该留下一条活着的通知连接。通道自身连不上不影响本方法的返回——它按 US-023 AC#17 只诊断不抛错。

通道走的是RxDBAdapterHttp.changeFeedEnabled这个意图位而不是「配了就开」：调用方手动 RxDBAdapterHttp.stopChangeFeed 掉的通道，不该被下一次重连（切后端、纪元交替都会走到这里）悄悄复活。

Throws

HttpUnsupportedWireTypeError 已注册实体声明了 bigint / binary 字段

Implementation of

IRxDBAdapter.connect

disconnect()

disconnect(): Promise<void>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:244

取消进行中的请求。

Returns

Promise<void>

Remarks

中止走 error 通道：complete 一个没发射过的 Observable 会让 core 的 forkJoin 静默产出「远端零条」，整表判成孤儿，比抛错危险得多。

已发出的写请求不回滚——HTTP 没有事务，假装能回滚比不回滚更危险。

顺带清空条件请求缓存（AC#28）：那些响应绑定的是断开前的认证身份与远端状态，跨越一次断开继续复用，等于让重连后的第一批查询读到上一段连接的世界。

变更通知通道一并停掉，含待执行的重连：只关连接不取消定时器的话，退避窗口里的那次重连会在断开之后把连接重新建起来。

但RxDBAdapterHttp.changeFeedEnabled不动：断开是生命周期事件，不是调用方改了主意。把它一并清掉的话，一次重连就会把用户「我要收通知」的选择吃掉。

Implementation of

IRxDBAdapter.disconnect

fetchMetadata()

fetchMetadata(entityName, query): Observable<QueryCacheEntityMetadata[]>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:390

拉取满足 query 的全部实体元数据。

Parameters

Parameter	Type	Description
`entityName`	`string`	实体名
`query`	`RuleGroup`<`unknown`>	查询条件，原样透传给 handler

Returns

Observable<QueryCacheEntityMetadata[]>

Remarks

恰好发射一次再 complete（AC#23）。翻页循环整体落在一个 Promise 里， from(promise) 天然满足这条；逐页发射会让调用方的 forkJoin 只留最后一页，前面各页当场丢失，那些 id 随即被判成「远端已删除」。

Overrides

RxDBAdapterRemoteBase.fetchMetadata

findByIds()

findByIds<R>(entityName, ids): Observable<R[]>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:412

按 id 列表批量拉取完整行。

Type Parameters

Type Parameter
`R`

Parameters

Parameter	Type	Description
`entityName`	`string`	实体名
`ids`	`string`[]	需要拉取的 id 列表

Returns

Observable<R[]>

Remarks

与 RxDBAdapterHttp.fetchMetadata 同款发射契约（AC#33）：所有块合并后恰好发射一次再 complete。逐块发射丢掉的是要写进本地缓存的完整行。

Overrides

RxDBAdapterRemoteBase.findByIds

getChangeCount()

getChangeCount(): Promise<{
  count: number;
  latestChangeId: number;
}>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:482

Returns

Promise<{ count: number; latestChangeId: number; }>

Throws

HttpChangelogUnsupportedError 总是（返回 0 同样会被读成「远端无变更」）

Overrides

RxDBAdapterRemoteBase.getChangeCount

getRepository()

getRepository<E, RT>(): RT;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:441

Type Parameters

Type Parameter	Default type
`E` extends `EntityType`	-
`RT` extends `IRepository`<`E`>	`IRepository`<`E`>

Returns

RT

Throws

HttpUnsupportedOperationError 总是

Remarks

QueryCache 的主仓储由 core 用本地适配器组装，本类这一侧没有可返回的东西。

这一组连形参都不声明（同 RxDBAdapterHttp.pullChanges）：函数少写形参照样满足 IRxDBAdapter，而留一个只为凑签名的 _entities 会让读者以为它被用上了。

Implementation of

IRxDBAdapter.getRepository

Overrides

RxDBAdapterRemoteBase.getRepository

isTableExisted()

isTableExisted(EntityType): Promise<boolean>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:346

按远端资源可达性回答，不恒 true 蒙混。

Parameters

Parameter	Type	Description
`EntityType`	`EntityType`	要检查的实体类

Returns

Promise<boolean>

Remarks

2xx → true，404 → false，其余状态码与传输失败 → 抛错。抛错而不是返回 false 是刻意的：「不知道」和「不存在」必须区分，把 500 读成「表不存在」会让调用方基于一个假答案做决定。

未配 onIsTableExisted 时复用 onFetchMetadata 的 limit: 1 探测。

Implementation of

IRxDBAdapter.isTableExisted

mergeChanges()

mergeChanges(): Promise<RemoteMergeResult>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:487

Returns

Promise<RemoteMergeResult>

Throws

HttpChangelogUnsupportedError 总是

Overrides

RxDBAdapterRemoteBase.mergeChanges

mutations()

mutations<E>(): Promise<InstanceType<E>[]>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:462

Type Parameters

Type Parameter
`E` extends `EntityType`

Returns

Promise<InstanceType<E>[]>

Throws

HttpUnsupportedOperationError 总是

Remarks

不影响 QueryCache 的批量写：EntityManager.mutations 判定为 QueryCache 批后走 #mutations_query_cache 的 remote-then-local，根本不经过这里。

Implementation of

IRxDBAdapter.mutations

pullBranches()?

optional pullBranches(): Promise<RemoteBranchInfo[]>;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:805

Returns

Promise<RemoteBranchInfo[]>

Inherited from

RxDBAdapterRemoteBase.pullBranches

pullChanges()

pullChanges(): Promise<RemoteChange[]>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:477

Returns

Promise<RemoteChange[]>

Throws

HttpChangelogUnsupportedError 总是

Remarks

返回空数组算失败：Full-sync 会把它读成「远端无变更」并覆盖本地认知。 v1 没有 changelog，unsupported throw 是唯一诚实行为。

Overrides

RxDBAdapterRemoteBase.pullChanges

pullChangesBatch()?

optional pullChangesBatch(
   requests, 
   limit, 
   branchIds?
): Promise<RemoteChange[]>;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:735

批量拉取多个实体的变更记录（单次 HTTP 请求）

每个实体可以有不同的 sinceId（水位线），通过服务端 OR 过滤实现单次请求获取所有实体的变更。

Parameters

Parameter	Type	Description
`requests`	`PullBatchRequest`[]	每个实体的拉取请求（namespace + 实体名 + sinceId）
`limit`	`number`	最大拉取数量
`branchIds?`	`string`[]	分支 ID 列表（支持包含祖先分支）

Returns

Promise<RemoteChange[]>

变更记录数组，按 id ASC 排序

Inherited from

RxDBAdapterRemoteBase.pullChangesBatch

pushBranches()?

optional pushBranches(branches): Promise<{
  skipped: string[];
  synced: number;
}>;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:800

Parameters

Parameter	Type
`branches`	`Record`<`string`, `unknown`>[]

Returns

Promise<{ skipped: string[]; synced: number; }>

Inherited from

RxDBAdapterRemoteBase.pushBranches

removeMany()

removeMany<E>(): Promise<InstanceType<E>[]>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:451

Type Parameters

Type Parameter
`E` extends `EntityType`

Returns

Promise<InstanceType<E>[]>

Throws

HttpUnsupportedOperationError 总是（同 RxDBAdapterHttp.saveMany）

Implementation of

IRxDBAdapter.removeMany

repository()

protected repository<RT>(repositoryName, RepositoryClass): void;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:350

Type Parameters

Type Parameter
`RT` extends `RepositoryInstance`<`EntityType`>

Parameters

Parameter	Type
`repositoryName`	`string`
`RepositoryClass`	`AdapterRepositoryConstructor`<`RxDBAdapterHttp`, `RT`>

Returns

void

Inherited from

RxDBAdapterRemoteBase.repository

saveMany()

saveMany<E>(): Promise<InstanceType<E>[]>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:446

Type Parameters

Type Parameter
`E` extends `EntityType`

Returns

Promise<InstanceType<E>[]>

Throws

HttpUnsupportedOperationError 总是（Full/Filter 写路径，v1 无 Full-sync）

Implementation of

IRxDBAdapter.saveMany

startChangeFeed()

startChangeFeed(): void;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:276

接通变更通知通道。

Returns

void

Remarks

幂等：已经开着时只是重建连接（start() 自带「先收口上一条」），不会留下第二条。连上之后照常触发一次全量失效（D7）——「从这一刻起我能收到变更了」对首次连接与重新接通是同一句话。

连接状态先判，与 RxDBAdapterHttp.version 同一条口径：在一个已经 disconnect() 的适配器上开出一条活着的 SSE，是实打实的资源泄漏。

这里判的是 #connected 而不是 #assertConnected 那一位。「从未 connect()」与「已 disconnect()」在这个方法上是同一件事：两种情况下都还没有一次成功的 connect()，也就意味着 #assertConfiguredEntitiesSupported() 还没跑过—— 用 new + startChangeFeed() 就能绕开线格式校验、在一个连不连得上都不知道的适配器上开出真连接，还会对着一份尚未确认可用的实体表做 D7 全量失效。

Throws

HttpDisconnectedError 尚未 connect()，或已 disconnect()

Throws

HttpUnsupportedOperationError 未配置 changeFeed

stopChangeFeed()

stopChangeFeed(): void;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:298

断开变更通知通道，含待执行的重连。

Returns

void

Remarks

断开期间远端的变更没有人会补发，重新 RxDBAdapterHttp.startChangeFeed 时的那次全量失效才是补课的地方。

与 RxDBAdapterHttp.startChangeFeed 不同，本方法不判断开状态：已经 disconnect() 的适配器上通道本来就停着，两条路通向同一个终点，为此抛错只会让「关掉开关」这种收尾动作平白需要一个 try。幂等的停止不是兜底——它没有掩盖任何差异。

Throws

HttpUnsupportedOperationError 未配置 changeFeed

version()

version(): Promise<string>;

Defined in: packages/rxdb-adapter-http/src/RxDBAdapterHttp.ts:320

返回远端服务端版本。

Returns

Promise<string>

Remarks

与 sqlite / pglite / supabase 三家口径一致（都返回后端引擎版本）。HTTP 没有内建 RPC，因此靠可选的 onVersion handler；未配置时抛错而不回落到本包 package.json 的版本号——那是拿适配器版本冒充后端版本。

断开状态先判：已 disconnect() 的适配器上，「未配 onVersion」不是调用方此刻该看见的答案——配置问题下次连上仍在，而生命周期问题是当下这一次调用的实情。反过来（先判 handler）还会让下面那句 #assertConnected 在缺 handler 的路径上永远走不到，而那条路径正是它存在的两个理由之一（另一个是空 id 列表的 findByIds）。

Throws

HttpDisconnectedError 适配器已断开

Throws

HttpUnsupportedOperationError 未配置 onVersion

Implementation of

IRxDBAdapter.version

Remarks​

Example​

Extends​

Implements​

Constructors​

Constructor​

Parameters​

Returns​

Throws​

Overrides​

Properties​

config​

create?​

Type Parameters​

Parameters​

Returns​

Remarks​

delete?​

Parameters​

Returns​

name​

Implementation of​

options​

repository_cache​

Inherited from​

repository_map​

Inherited from​

rxdb​

Inherited from​

update?​

Type Parameters​

Parameters​

Returns​

Accessors​

changeFeedEnabled​

Get Signature​

Remarks​

Returns​

Methods​

branchExists()?​

Parameters​

Returns​

Inherited from​

connect()​

Returns​

Remarks​

Throws​

Implementation of​

disconnect()​

Returns​

Remarks​

Implementation of​

fetchMetadata()​

Parameters​

Returns​

Remarks​

Overrides​

findByIds()​

Type Parameters​

Parameters​

Returns​

Remarks​

Overrides​

getChangeCount()​

Returns​

Throws​

Overrides​

getRepository()​

Type Parameters​

Returns​

Throws​

Remarks​

Implementation of​

Overrides​

isTableExisted()​

Parameters​

Returns​

Remarks​

Implementation of​

mergeChanges()​

Remarks

Example

Extends

Implements

Constructors

Constructor

Parameters

Returns

Throws

Overrides

Properties

config

create?

Type Parameters

Parameters

Returns

Remarks

delete?

Parameters

Returns

name

Implementation of

options

repository_cache

Inherited from

repository_map

Inherited from

rxdb

Inherited from

update?

Type Parameters

Parameters

Returns

Accessors

changeFeedEnabled

Get Signature

Remarks

Returns

Methods

branchExists()?

Parameters

Returns

Inherited from

connect()

Returns

Remarks

Throws

Implementation of

disconnect()

Returns

Remarks

Implementation of

fetchMetadata()

Parameters

Returns

Remarks

Overrides

findByIds()

Type Parameters

Parameters

Returns

Remarks

Overrides

getChangeCount()

Returns

Throws

Overrides

getRepository()

Type Parameters

Returns

Throws

Remarks

Implementation of

Overrides

isTableExisted()

Parameters

Returns

Remarks

Implementation of

mergeChanges()