RxdbFileStorage

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:102

用 StorageFilesystem 保存文件、用 RxDB 保存 metadata 的文件存储服务。

Remarks

默认后端是浏览器 OPFS；桌面宿主可经 RxDBStoragePluginOptions.filesystem 换成原生文件。同一路径写入在当前实例内串行执行。destroy 会先拒绝新任务、等待已开始的写任务，再释放对象 URL 和后端句柄；销毁后的实例不能重新初始化。

Constructors

Constructor

new RxdbFileStorage(
   rxdb, 
   options?, 
   entityType?, 
   objectUrls?
): RxdbFileStorage;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:205

创建文件存储服务。

Parameters

Parameter	Type	Default value	Description
`rxdb`	`RxDB`	`undefined`	metadata 所属 RxDB 实例。
`options`	`RxDBStoragePluginOptions`	`{}`	OPFS 根目录与预览限制。
`entityType`	typeof `StorageFileMeta`	`StorageFileMeta`	metadata 实体类型；主要用于测试或定制实体。
`objectUrls`	`ObjectUrlRegistry`	`...`	对象 URL 所有权注册表。

Returns

RxdbFileStorage

Accessors

activeObjectUrlCount

Get Signature

get activeObjectUrlCount(): number;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:183

当前由服务持有、尚未回收的对象 URL 数量。

Returns

number

changeEpoch

Get Signature

get changeEpoch(): number;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:193

当前捕获纪元：每次写操作结束时单调递增。

Remarks

只读，供 DevTools 诊断快照做「前后一致」判定；消费方不该依赖它的绝对值，只做等值比较。

Returns

number

Methods

clear()

clear(path?): Promise<void>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:604

清空全部存储，或删除指定目录子树中的文件与 metadata。

Parameters

Parameter	Type
`path?`	`string`

Returns

Promise<void>

createDirectory()

createDirectory(name, options?): Promise<string>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:495

Parameters

Parameter	Type
`name`	`string`
`options`	`CreateDirectoryOptions`

Returns

Promise<string>

新目录的 storage 绝对路径。

createObjectUrl()

createObjectUrl(fileId): Promise<string>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:344

为文件创建由本服务持有的对象 URL。

调用方应使用 revokeObjectUrl 释放；destroy 会回收所有残留 URL。

Parameters

Parameter	Type
`fileId`	`string`

Returns

Promise<string>

delete()

delete(fileId): Promise<void>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:564

删除 metadata 及其 OPFS 文件；两者任一失败时执行补偿。

Parameters

Parameter	Type
`fileId`	`string`

Returns

Promise<void>

destroy()

destroy(): Promise<void>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:648

永久销毁当前服务实例。

首次调用立即拒绝新任务，等待已开始的写任务结束，再回收资源；重复调用返回同一 Promise。

Returns

Promise<void>

download()

download(fileId, options?): Promise<void>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:359

通过文件选择器或浏览器下载链接保存文件。

只有用户取消文件选择器会静默返回；写入阶段的错误保持原样抛出。

Parameters

Parameter	Type
`fileId`	`string`
`options`	`DownloadOptions`

Returns

Promise<void>

fetch()

fetch(opfsPath, options): Promise<Blob>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:282

从远程 URL 拉取资源并持久化到 OPFS。

行为：

若 opfsPath 已存在缓存，直接返回缓存 Blob，不发请求（永久缓存，不做 ETag/TTL 判定）。
同一路径的并发调用共享同一 in-flight Promise；mimeType 不一致的后到 caller 会等 in-flight 完成后从缓存读取（此时 OPFS 已就绪），独立应用自己的 mimeType 返回 — 但 不会修改已落盘的 meta.mimeType：首个完成的 caller 决定 meta 上的 mime。
navigator.onLine === false 立即抛 StorageOfflineError。
响应 MIME 取 options.mimeType ?? Content-Type 头（自动 strip 参数）；两者都缺抛 StorageMimeTypeMissingError。
options.signal 已 abort 立即抛 AbortError，下载中途 abort 不会污染缓存。

Parameters

Parameter	Type	Description
`opfsPath`	`string`	OPFS 内的相对路径（如 `images/foo.png`），将规范化后作为缓存 key。
`options`	`FetchRemoteOptions`	见 FetchRemoteOptions。

Returns

Promise<Blob>

持久化到 OPFS 的 Blob，type 等于最终 MIME。

Remark

cached 命中分支：options.mimeType 仅影响本次返回 Blob 的 type，不修改已存的 meta.mimeType；下次通过 read(meta.id) 读取仍是原 mime。

getMeta()

getMeta(fileId): Promise<StorageFileMeta | null>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:416

按 ID 返回 metadata；不存在时返回 null。

Parameters

Parameter	Type
`fileId`	`string`

Returns

Promise<StorageFileMeta | null>

init()

init(): Promise<void>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:221

初始化存储根目录。

Returns

Promise<void>

Throws

StorageUnavailableError 当前环境不支持所选后端时抛出。

Throws

StorageDestroyedError 服务已开始销毁时抛出。

list()

list(options?): Promise<StorageFileMeta[]>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:434

列出 metadata。

省略 path：返回整库全部 metadata（跨目录）。
指定 path：默认只返回该目录的直属文件；recursive: true 则连同子目录。

Parameters

Parameter	Type
`options`	`ListOptions`

Returns

Promise<StorageFileMeta[]>

Remarks

STOR-005：此前过滤条件写作 options.path ? ... : true，于是 path: '' 虽然被 normalizeDirectoryPath 规范化成根目录，却因为空字符串是假值而落进「未限定目录」分支返回全树 —— 同一个规范化结果对应两套行为。现在一律以「path 是否被显式传入」判定，'' 与 '/' 行为一致。 README 早先声称本方法「只返回当前目录直属文件」，与默认行为不符，已同步更正。

listAllMetas()

listAllMetas(): Promise<StorageFileMeta[]>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:622

供诊断快照读取全部 metadata（US-904 AC#48）。

Returns

Promise<StorageFileMeta[]>

Remarks

排序与 RxdbFileStorage.list 一致（按 opfsPath）。快照来源据此物化「meta」侧。

listEntries()

listEntries(options?): Promise<StorageBrowserEntry[]>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:448

列出指定目录的直属目录和已被 metadata 跟踪的直属文件。

孤立文件不会暴露给调用方，结果按目录优先、名称升序排列。

Parameters

Parameter	Type
`options`	`ListOptions`

Returns

Promise<StorageBrowserEntry[]>

preview()

preview(fileId): Promise<StoragePreviewResult>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:329

创建包含显式 dispose 所有权的预览结果。

Parameters

Parameter	Type
`fileId`	`string`

Returns

Promise<StoragePreviewResult>

Throws

StoragePreviewLimitError 文件超过配置的预览上限时抛出。

read()

read(fileId): Promise<Blob>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:251

读取 metadata 对应的文件快照。

Parameters

Parameter	Type
`fileId`	`string`

Returns

Promise<Blob>

内容 Blob，type 恒为 metadata 记录的 MIME。

Throws

文件 ID 不存在、后端文件缺失或服务已销毁时抛出。

rename()

rename(
   fileId, 
   newName, 
   options?
): Promise<StorageFileMeta>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:516

在原目录内重命名文件。

支持 OPFS move() 时优先原生移动；overwrite 会完整替换目标并保留源 metadata ID。

Parameters

Parameter	Type
`fileId`	`string`
`newName`	`string`
`options`	`RenameOptions`

Returns

Promise<StorageFileMeta>

renameDirectory()

renameDirectory(
   directoryPath, 
   newName, 
   options?
): Promise<string>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:550

overwrite 是 replace 语义：目标独有文件和 metadata 会删除，不会与源树合并。

Parameters

Parameter	Type
`directoryPath`	`string`
`newName`	`string`
`options`	`RenameOptions`

Returns

Promise<string>

revokeObjectUrl()

revokeObjectUrl(url): void;

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

释放此前由 createObjectUrl 创建的 URL；重复释放是空操作。

Parameters

Parameter	Type
`url`	`string`

Returns

void

runExclusive()

runExclusive<T>(fn, signal?): Promise<T>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:639

在 storage 全局独占锁内执行 fn，与全部路径级写操作互斥（US-904 AC#48）。

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type	Description
`fn`	() => `Promise`<`T`>	临界区
`signal?`	`AbortSignal`	可选；等锁期间中止则放弃获取

Returns

Promise<T>

Remarks

供 DevTools 诊断快照物化使用：快照要同时读 metadata 与文件，必须与写操作互斥，否则两半属于不同时点，panel 会据此报出「有元数据无文件」这类假缺失。

signal 覆盖等锁阶段：慢写入排空之前中止，即以 signal.reason 拒绝且 fn 永不执行，不会留下一个日后仍会拿到锁的 waiter（快照来源的 dispose() / cancel() 依赖这一点）。

upload()

upload(file, options?): Promise<StorageFileMeta>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:233

把文件写入 OPFS 并提交 metadata。

Parameters

Parameter	Type
`file`	`File`
`options`	`UploadOptions`

Returns

Promise<StorageFileMeta>

新建或更新后的 metadata；覆盖时保留原 ID 并递增 contentVersion。

Throws

StorageConflictError 目标已存在且未启用 overwrite 时抛出。

Throws

StorageDestroyedError 服务已开始销毁时抛出。

watch()

watch(fileId): Observable<StorageFileMeta | null>;

Defined in: packages/rxdb-plugin-storage/src/storage.service.ts:589

观察单个文件的 metadata 变化。

订阅后立即发出当前值；删除后发出 null，服务销毁后流完成。

Parameters

Parameter	Type
`fileId`	`string`

Returns

Observable<StorageFileMeta | null>

Remarks​

Constructors​

Constructor​

Parameters​

Returns​

Accessors​

activeObjectUrlCount​

Get Signature​

Returns​

changeEpoch​

Get Signature​

Remarks​

Returns​

Methods​

clear()​

Parameters​

Returns​

createDirectory()​

Parameters​

Returns​

createObjectUrl()​

Parameters​

Returns​

delete()​

Parameters​

Returns​

destroy()​

Returns​

download()​

Parameters​

Returns​

fetch()​

Parameters​

Returns​

Remark​

getMeta()​

Parameters​

Returns​

init()​

Returns​

Throws​

Throws​

list()​

Parameters​

Returns​

Remarks​

listAllMetas()​

Returns​

Remarks​

listEntries()​

Parameters​

Returns​

preview()​

Parameters​

Returns​

Throws​

read()​

Parameters​

Returns​

Throws​

rename()​

Parameters​

Returns​

renameDirectory()​

Parameters​

Returns​

revokeObjectUrl()​

Parameters​

Returns​

runExclusive()​

Type Parameters​

Parameters​

Returns​

Remarks​

upload()​

Parameters​

Returns​

Throws​

Throws​

watch()​

Remarks

Constructors

Constructor

Parameters

Returns

Accessors

activeObjectUrlCount

Get Signature

Returns

changeEpoch

Get Signature

Remarks

Returns

Methods

clear()

Parameters

Returns

createDirectory()

Parameters

Returns

createObjectUrl()

Parameters

Returns

delete()

Parameters

Returns

destroy()

Returns

download()

Parameters

Returns

fetch()

Parameters

Returns

Remark

getMeta()

Parameters

Returns

init()

Returns

Throws

Throws

list()

Parameters

Returns

Remarks

listAllMetas()

Returns

Remarks

listEntries()

Parameters

Returns

preview()

Parameters

Returns

Throws

read()

Parameters

Returns

Throws

rename()

Parameters

Returns

renameDirectory()

Parameters

Returns

revokeObjectUrl()

Parameters

Returns

runExclusive()

Type Parameters

Parameters

Returns

Remarks

upload()

Parameters

Returns

Throws

Throws

watch()