@mountra/mountra-sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.0 - 2026-10-07
+
+### Added
+
+- Added `list()` and `tree()` to read a directory's entries or its complete subtree.
+- Added `mkdir()`, `rename()`, `move()`, `copy()`, and `delete()` for files and directories. With the `downloadCache` enabled, they also stop the download cache from serving files at the paths they change: the next download asks Mountra again and still reuses the cached chunks. A custom `DownloadCacheStore` can implement the new optional `removeFilesUnder()`; without it, the workspace's download cache is cleared instead.
+- Added an opt-in metadata cache through the `metadataCache` client option, stored in IndexedDB per workspace:
+  - `list` and `tree` take `mode`. `sync`, the default, waits for Mountra. `async` returns the cached result at once, refreshes it in the background, and delivers a changed result through `onUpdate` (failures through `onError`).
+  - Every result fetched from Mountra is cached before it is returned, and also refreshes the cached listings and trees it overlaps.
+  - Writes through the client, including uploads, update the cached listings and trees as soon as Mountra confirms them. Renaming or moving a directory carries its cached contents to the new path.
+  - A fetch that overlapped a write through the client is not cached, and an older fetch never replaces a newer one.
+- Added `clearMetadataCache()`, `IndexedDBMetadataCacheStore`, and `InMemoryMetadataCacheStore`.
+
 ## 0.3.0 - 2026-10-07
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # @mountra/mountra-sdk
 
-用于浏览器前端接入 Mountra 的 TypeScript SDK。提供文件上传、流式下载、断点续传和多 chunk 客户端组装。
+用于浏览器前端接入 Mountra 的 TypeScript SDK。提供文件上传、流式下载、断点续传、多 chunk 客户端组装，以及目录列表、目录树和文件操作（可选本地元数据缓存）。
 
 ## 使用
 
@@ -182,6 +182,8 @@ const mountra = createMountraClient({
 
 通过客户端 `upload` 的文件默认也会写入缓存：上传完成后，各 chunk 直接从本地文件写入 IndexedDB，并按路径和 inode 记录文件布局，之后在有效期内下载这个文件不需要访问网络。缓存规则与下载相同（只缓存内容寻址的 chunk，并受 `maxChunkBytes` 限制）。如果有 chunk 无法缓存，或者上传时传入 `cache: "no-store"`，就只让该文件原有的缓存失效。
 
+通过客户端执行的 `mkdir`、`rename`、`move`、`copy`、`delete`（见[目录与元数据](#目录与元数据)）成功后，这些操作涉及的路径及其下所有文件的缓存布局都会失效（按路径和 inode 记录的都包括），之后下载会重新向 Mountra 获取布局，已缓存的 chunk 仍然复用。自定义的 `DownloadCacheStore` 可以实现可选的 `removeFilesUnder` 方法；未实现时，会清除该 workspace 的全部下载缓存。
+
 有效期内其他客户端对文件的修改不会被感知。单次下载可以用 `cache` 选项调整行为：
 
 ```ts
@@ -206,6 +208,87 @@ const downloadCache = {
 
 IndexedDB 不可用时（例如非浏览器环境）SDK 回退到内存缓存；缓存读写失败只会当作未命中，不会导致下载失败。
 
+## 目录与元数据
+
+`list` 返回一个目录的直接子项，`tree` 返回一个目录及其完整子树。未传 `path` 时读取根目录 `/`：
+
+```ts
+const { entries } = await mountra.list({ path: "/documents" });
+// entries: [{ name, path, ino, isDirectory, size, mtimeMs, atimeMs, uid?, uidDisplayName?, ... }]，目录在前，再按名称排序
+
+const { root } = await mountra.tree({ path: "/documents" });
+// root: { name, path, ino, isDirectory, size, mtimeMs, children: [...] }
+```
+
+目录和文件的写操作：
+
+```ts
+await mountra.mkdir({ path: "/documents/2026" }); // 父目录必须存在
+await mountra.rename({ fromPath: "/documents/2026", toName: "archive" });
+await mountra.move({ fromPath: "/documents/archive", toPath: "/archive" }); // toPath 是完整的目标路径
+await mountra.copy({ fromPath: "/report.pdf", toPath: "/archive/report.pdf" }); // 只能复制文件
+await mountra.delete({ path: "/archive/report.pdf" }); // 文件或空目录
+```
+
+`mkdir`、`rename`、`move`、`copy` 返回 `{ path, ino }`。
+
+## 元数据缓存
+
+创建客户端时传入 `metadataCache` 即可启用基于 IndexedDB 的元数据缓存（默认关闭，传 `{}` 使用默认值）：
+
+```ts
+const mountra = createMountraClient({
+  baseUrl: "https://mountra.example.com",
+  token: "your-bearer-token",
+  workspaceCuid: "workspace-cuid",
+  metadataCache: {
+    maxEntries: 2000, // 缓存的 list / tree 结果数上限，默认 1000；超出后先淘汰最久未刷新的
+  },
+});
+```
+
+`list` 和 `tree` 通过 `mode` 选择读取方式：
+
+- `sync`（默认）：等待 Mountra 返回最新结果。
+- `async`：立即返回缓存的结果（`source: "cache"`），同时在后台向 Mountra 刷新。刷新结果与已返回的结果不同时，通过 `onUpdate` 回调送达；刷新失败时调用 `onError`。没有缓存时与 `sync` 相同，等待 Mountra 返回，也不会再调用 `onUpdate`。
+
+```ts
+const result = await mountra.list({
+  path: "/documents",
+  mode: "async",
+  onUpdate: (fresh) => render(fresh.entries), // 只在内容变化时调用
+  onError: (error) => console.warn("刷新失败", error),
+});
+render(result.entries);
+console.log(result.source, result.fetchedAt); // "cache" | "remote"，以及这份结果向 Mountra 请求的时间
+```
+
+`signal` 同样会取消后台刷新；中止之后不再调用任何回调。未启用 `metadataCache` 时 `async` 等同于 `sync`。
+
+缓存按以下规则保持更新：
+
+- 每次从 Mountra 取得 `list` / `tree` 结果，都先写入缓存再返回给调用方（包括 `async` 的后台刷新）。同时会刷新与它重叠的缓存：新的 `list` 结果会更新包含该目录的 `tree`，新的 `tree` 结果会更新其下各目录的 `list`。无法准确更新的条目会被删除而不是保留旧数据，例如 `list` 中出现了子树未知的新目录时，对应的 `tree` 缓存会失效。
+- 通过客户端执行的 `mkdir`、`rename`、`move`、`copy`、`delete` 以及上传成功后，SDK 会直接更新父目录的 `list` 缓存和包含它的 `tree` 缓存，重命名或移动目录时还会把该目录下的缓存一起迁移到新路径。因此写操作之后用 `async` 读取能立即看到变化。新条目中只有 Mountra 才知道的字段（例如所有者、服务端修改时间）会在下一次刷新后补全。
+- 在写操作完成之前发出、完成之后才返回的读取请求，结果可能早于这次写入，因此只返回给调用方，不写入缓存；较早发出的请求也不会覆盖较新的缓存。
+- 读取时 Mountra 返回 404，说明该目录已不存在：它会从父目录的缓存中移除，它自身及其下的缓存也会被删除。
+
+其他客户端或其他浏览器标签页的修改只能通过刷新感知：`async` 读取会先返回旧的缓存，再通过 `onUpdate` 送达最新结果。需要确保拿到最新数据时使用 `sync`。
+
+缓存与下载缓存一样以 `baseUrl` 和 workspace 作为命名空间（`workspaceCuid` 优先于 `workspaceId`），同一 workspace 应始终用同一种方式指定，否则会产生两份互不更新的缓存。用户退出登录时应调用 `clearMetadataCache()`；多个用户共用浏览器时，可以为每个用户使用独立的数据库：
+
+```ts
+import { IndexedDBMetadataCacheStore } from "@mountra/mountra-sdk";
+
+const metadataCache = {
+  store: new IndexedDBMetadataCacheStore({ databaseName: `mountra-metadata-cache-${userId}` }),
+};
+
+await mountra.clearMetadataCache({ workspaceCuid: "workspace-cuid" }); // 清除一个 workspace
+await mountra.clearMetadataCache(); // 清除全部
+```
+
+IndexedDB 不可用时 SDK 回退到内存缓存（测试时也可以直接使用 `InMemoryMetadataCacheStore`）。缓存读写失败不会导致元数据操作失败；写操作成功后若缓存无法更新，该 workspace 的元数据缓存会被清空，以免保留与写入矛盾的数据。
+
 ## 开发
 
 ```bash