@mountra/mountra-sdk 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -52,6 +52,12 @@ interface DownloadCacheStore {
     getFile(workspace: string, fileKey: string): Promise<DownloadCacheFile | null>;
     putFile(workspace: string, fileKey: string, file: DownloadCacheFile): Promise<void>;
     removeFile(workspace: string, fileKey: string): Promise<void>;
+    /**
+     * Remove every file whose `path` is `path` or below it, keeping the chunks.
+     * Optional: without it, a move or delete through the client clears the
+     * whole workspace instead.
+     */
+    removeFilesUnder?(workspace: string, path: string): Promise<void>;
     /** Return the chunk bytes and mark the chunk as most recently used. */
     getChunk(workspace: string, storageKey: string): Promise<Blob | null>;
     /** Store the chunk bytes, then evict least recently used chunks until at most `maxBytes` remain. */
@@ -68,6 +74,7 @@ declare class InMemoryDownloadCacheStore implements DownloadCacheStore {
     getFile(workspace: string, fileKey: string): Promise<DownloadCacheFile | null>;
     putFile(workspace: string, fileKey: string, file: DownloadCacheFile): Promise<void>;
     removeFile(workspace: string, fileKey: string): Promise<void>;
+    removeFilesUnder(workspace: string, path: string): Promise<void>;
     getChunk(workspace: string, storageKey: string): Promise<Blob | null>;
     putChunk(workspace: string, storageKey: string, data: Blob, maxBytes: number): Promise<void>;
     clear(workspace?: string): Promise<void>;
@@ -86,6 +93,7 @@ declare class IndexedDBDownloadCacheStore implements DownloadCacheStore {
     getFile(workspace: string, fileKey: string): Promise<DownloadCacheFile | null>;
     putFile(workspace: string, fileKey: string, file: DownloadCacheFile): Promise<void>;
     removeFile(workspace: string, fileKey: string): Promise<void>;
+    removeFilesUnder(workspace: string, path: string): Promise<void>;
     getChunk(workspace: string, storageKey: string): Promise<Blob | null>;
     putChunk(workspace: string, storageKey: string, data: Blob, maxBytes: number): Promise<void>;
     clear(workspace?: string): Promise<void>;
@@ -110,6 +118,8 @@ declare class DownloadCache {
     storeChunk(workspace: string, chunk: DownloadCacheChunk, data: Blob): Promise<boolean>;
     storeFile(workspace: string, fileKey: string, file: Omit<DownloadCacheFile, "cachedAt" | "expiresAt">): Promise<void>;
     invalidateFiles(workspace: string, fileKeys: string[]): Promise<void>;
+    /** Drop the files at or below `paths`, which a write changed; their chunks stay cached. */
+    invalidatePaths(workspace: string, paths: string[]): Promise<void>;
     clear(workspace?: string): Promise<void>;
     usage(workspace?: string): Promise<DownloadCacheUsage>;
 }
@@ -280,6 +290,8 @@ declare class MountraDownloader {
         path?: string;
         ino?: number | string;
     }): Promise<void>;
+    /** Drop the cached files at or below paths that a delete, move, or copy changed. */
+    invalidateCachedPaths(selector: WorkspaceSelector, paths: string[]): Promise<void>;
     /**
      * Cache a file this client just uploaded, so downloading it needs no
      * network. Falls back to invalidation when any chunk cannot be cached.
@@ -348,6 +360,197 @@ declare class MountraFile {
     resume(options?: MountraFileResumeOptions): Promise<DownloadResult>;
 }
 
+type MetadataCacheKind = "list" | "tree";
+/** A cached `list` result: the entries of one directory. */
+interface MetadataListRecord {
+    kind: "list";
+    path: string;
+    entries: MountraFileEntry[];
+    /**
+     * When the request that returned this result was sent. Writes through this
+     * client and overlapping fetches may have updated the record since.
+     */
+    fetchedAt: number;
+}
+/** A cached `tree` result: one directory and its complete subtree. */
+interface MetadataTreeRecord {
+    kind: "tree";
+    path: string;
+    root: MountraFileTreeNode;
+    /** See `MetadataListRecord.fetchedAt`. */
+    fetchedAt: number;
+}
+type MetadataCacheRecord = MetadataListRecord | MetadataTreeRecord;
+interface MetadataCacheBatch {
+    put: MetadataCacheRecord[];
+    remove: Array<{
+        kind: MetadataCacheKind;
+        path: string;
+    }>;
+}
+interface MetadataCacheOptions {
+    /**
+     * Upper bound of cached `list` and `tree` results, shared by all
+     * workspaces. A tree counts as one result however large it is. Defaults to
+     * 1000; the least recently refreshed results are evicted first.
+     */
+    maxEntries?: number;
+    /** Cache storage. Defaults to IndexedDB, or memory when IndexedDB is unavailable. */
+    store?: MetadataCacheStore;
+}
+/**
+ * Storage behind the metadata cache. A record is identified by an opaque
+ * workspace key together with its `kind` and `path`, so one workspace never
+ * observes another workspace's records.
+ */
+interface MetadataCacheStore {
+    get(workspace: string, kind: MetadataCacheKind, path: string): Promise<MetadataCacheRecord | null>;
+    /** The records stored at `path` or at any path below it, of one kind or of both. */
+    getSubtree(workspace: string, path: string, kind?: MetadataCacheKind): Promise<MetadataCacheRecord[]>;
+    /** Apply the batch atomically, then evict the least recently written records until at most `maxEntries` remain. */
+    write(workspace: string, batch: MetadataCacheBatch, maxEntries: number): Promise<void>;
+    /** Remove every record, or only the records of one workspace. */
+    clear(workspace?: string): Promise<void>;
+}
+declare class InMemoryMetadataCacheStore implements MetadataCacheStore {
+    /** Map iteration order is the eviction order: the first entry was written least recently. */
+    private readonly records;
+    get(workspace: string, kind: MetadataCacheKind, path: string): Promise<MetadataCacheRecord | null>;
+    getSubtree(workspace: string, path: string, kind?: MetadataCacheKind): Promise<MetadataCacheRecord[]>;
+    write(workspace: string, batch: MetadataCacheBatch, maxEntries: number): Promise<void>;
+    clear(workspace?: string): Promise<void>;
+}
+interface IndexedDBMetadataCacheStoreOptions {
+    /** Use a separate database, for example one per signed-in user. */
+    databaseName?: string;
+}
+/** Records are keyed `[workspace, kind, path]`, so a subtree of one kind is one key range. */
+declare class IndexedDBMetadataCacheStore implements MetadataCacheStore {
+    private readonly databaseName;
+    private readonly fallback;
+    private databasePromise?;
+    constructor(options?: IndexedDBMetadataCacheStoreOptions);
+    get(workspace: string, kind: MetadataCacheKind, path: string): Promise<MetadataCacheRecord | null>;
+    getSubtree(workspace: string, path: string, kind?: MetadataCacheKind): Promise<MetadataCacheRecord[]>;
+    write(workspace: string, batch: MetadataCacheBatch, maxEntries: number): Promise<void>;
+    clear(workspace?: string): Promise<void>;
+    private openDatabase;
+}
+
+/** One entry of a directory listing. */
+interface MountraFileEntry {
+    name: string;
+    /** Absolute path in the workspace. */
+    path: string;
+    ino: number;
+    isDirectory: boolean;
+    size: number;
+    mtimeMs: number;
+    atimeMs: number;
+    uid?: number;
+    gid?: number;
+    uidDisplayName?: string;
+    uidUsername?: string;
+    uidSubjectId?: string;
+    uidSubjectType?: string;
+    gidDisplayName?: string;
+    gidUsername?: string;
+    gidSubjectId?: string;
+    gidSubjectType?: string;
+}
+/** A node of a file tree. A directory node holds its complete subtree. */
+interface MountraFileTreeNode {
+    name: string;
+    /** Absolute path in the workspace. */
+    path: string;
+    ino: number;
+    isDirectory: boolean;
+    size: number;
+    mtimeMs: number;
+    uid?: number;
+    gid?: number;
+    uidSubjectId?: string;
+    uidSubjectType?: string;
+    gidSubjectId?: string;
+    gidSubjectType?: string;
+    children: MountraFileTreeNode[];
+}
+/**
+ * How a metadata read uses the client's `metadataCache`:
+ * - `sync`: wait for Mountra and return its result.
+ * - `async`: return the cached result at once and refresh it in the
+ *   background. Without a cached result, wait for Mountra as `sync` does.
+ *
+ * Either way, a result fetched from Mountra is cached before it is returned.
+ */
+type MetadataReadMode = "sync" | "async";
+/** `cache` when the result was served from the metadata cache, `remote` when Mountra just returned it. */
+type MetadataSource = "cache" | "remote";
+interface MetadataReadOptions<T> extends WorkspaceSelector {
+    /** The directory to read. Defaults to `/`. */
+    path?: string;
+    /** Defaults to `sync`. */
+    mode?: MetadataReadMode;
+    /**
+     * `async` only: receives the refreshed result of a cached result that was
+     * returned, when the two differ.
+     */
+    onUpdate?: (result: T) => void;
+    /** `async` only: receives the error of a failed background refresh. */
+    onError?: (error: unknown) => void;
+    /** Also cancels the background refresh; no callback runs once it has aborted. */
+    signal?: AbortSignal;
+}
+interface ListResult {
+    path: string;
+    /** Directories first, then by name. */
+    entries: MountraFileEntry[];
+    source: MetadataSource;
+    /**
+     * When the request that returned this result was sent. A cached result
+     * also reflects writes made through this client since then.
+     */
+    fetchedAt: number;
+}
+interface TreeResult {
+    path: string;
+    root: MountraFileTreeNode;
+    source: MetadataSource;
+    /** See `ListResult.fetchedAt`. */
+    fetchedAt: number;
+}
+type ListOptions = MetadataReadOptions<ListResult>;
+type TreeOptions = MetadataReadOptions<TreeResult>;
+interface MkdirOptions extends WorkspaceSelector {
+    /** The directory to create. Its parent must exist. */
+    path: string;
+    signal?: AbortSignal;
+}
+interface RenameOptions extends WorkspaceSelector {
+    fromPath: string;
+    /** The new name within the same directory. */
+    toName: string;
+    signal?: AbortSignal;
+}
+interface MoveOptions extends WorkspaceSelector {
+    fromPath: string;
+    /** The complete destination path, which must not exist yet. */
+    toPath: string;
+    signal?: AbortSignal;
+}
+/** Copies one file; Mountra does not copy directories. */
+type CopyOptions = MoveOptions;
+interface DeleteOptions extends WorkspaceSelector {
+    /** A file, or an empty directory. */
+    path: string;
+    signal?: AbortSignal;
+}
+interface FileOperationResult {
+    /** The path of the created, renamed, moved, or copied entry. */
+    path: string;
+    ino: number;
+}
+
 type ChunkMethod = "none" | "fix";
 type WorkspaceId = number | string;
 declare const JUMBO_CHUNK_THRESHOLD_BYTES: number;
@@ -381,6 +584,12 @@ interface MountraClientOptions extends WorkspaceSelector {
      * unless set; pass `{}` for the defaults.
      */
     downloadCache?: DownloadCacheOptions;
+    /**
+     * Cache `list` and `tree` results locally, per workspace, in IndexedDB, so
+     * reads with `mode: "async"` return at once. Disabled unless set; pass `{}`
+     * for the defaults.
+     */
+    metadataCache?: MetadataCacheOptions;
 }
 interface UploadFileOptions extends WorkspaceSelector {
     path: string;
@@ -593,16 +802,6 @@ interface PreparedUpload {
     contentHash: string;
     context: UploadSessionContext;
 }
-declare class MountraApiError extends Error {
-    readonly status: number;
-    readonly code?: string;
-    readonly body?: unknown;
-    constructor(message: string, input: {
-        status: number;
-        code?: string;
-        body?: unknown;
-    });
-}
 declare class InMemoryJumboChunkCheckpointStore implements JumboChunkCheckpointStore {
     private readonly records;
     load(key: string): Promise<JumboChunkCheckpoint | null>;
@@ -652,6 +851,7 @@ declare class MountraClient {
     private readonly jumboChunkCheckpointStore;
     private readonly jumboPartSize;
     private readonly downloader;
+    private readonly metadata;
     constructor(options: MountraClientOptions);
     exportFile(options: ExportFileOptions): Promise<ExportFileResponse>;
     downloadFile(options: DownloadFileOptions): Promise<DownloadResult>;
@@ -662,6 +862,17 @@ declare class MountraClient {
     /** Clear the download cache of one workspace, or of every workspace when none is given. */
     clearDownloadCache(selector?: WorkspaceSelector): Promise<void>;
     getDownloadCacheUsage(selector?: WorkspaceSelector): Promise<DownloadCacheUsage>;
+    /** List the entries of a directory. See `MetadataReadMode` for how `mode` uses the metadata cache. */
+    list(options?: ListOptions): Promise<ListResult>;
+    /** Return a directory with its complete subtree. See `MetadataReadMode` for how `mode` uses the metadata cache. */
+    tree(options?: TreeOptions): Promise<TreeResult>;
+    mkdir(options: MkdirOptions): Promise<FileOperationResult>;
+    rename(options: RenameOptions): Promise<FileOperationResult>;
+    move(options: MoveOptions): Promise<FileOperationResult>;
+    copy(options: CopyOptions): Promise<FileOperationResult>;
+    delete(options: DeleteOptions): Promise<void>;
+    /** Clear the metadata cache of one workspace, or of every workspace when none is given. */
+    clearMetadataCache(selector?: WorkspaceSelector): Promise<void>;
     /** Create a stable resource object for one file in this or another workspace. */
     file(locator: MountraFileLocator): MountraFile;
     prepareUpload(file: Blob, options: UploadFileOptions): Promise<PreparedUpload>;
@@ -688,4 +899,16 @@ declare class MountraClient {
 }
 declare function createMountraClient(options: MountraClientOptions): MountraClient;
 
-export { type AccessToken, type ChunkMethod, DEFAULT_S3_MULTIPART_PART_SIZE_BYTES, type DownloadCacheChunk, type DownloadCacheFile, type DownloadCacheMode, type DownloadCacheOptions, type DownloadCacheStore, type DownloadCacheUsage, type DownloadCheckpoint, type DownloadCheckpointChunk, type DownloadCheckpointRequest, type DownloadCheckpointStore, type DownloadFileOptions, DownloadHttpError, type DownloadProgress, type DownloadResult, type DownloadResumeOptions, type ExportFileChunk, type ExportFileOptions, type ExportFileResponse, type FileChunk, type FileSystemFileHandleLike, type FileSystemWritableFileStreamLike, type FinishUploadResponse, InMemoryDownloadCacheStore, InMemoryDownloadCheckpointStore, InMemoryJumboChunkCheckpointStore, IndexedDBDownloadCacheStore, type IndexedDBDownloadCacheStoreOptions, IndexedDBDownloadCheckpointStore, JUMBO_CHUNK_THRESHOLD_BYTES, type JumboChunkCheckpoint, type JumboChunkCheckpointStore, type JumboChunkCompleteInput, type JumboChunkCreateInput, type JumboChunkUploadPartInput, type JumboChunkUploader, LocalStorageJumboChunkCheckpointStore, MAX_S3_MULTIPART_PARTS, MIN_S3_MULTIPART_PART_SIZE_BYTES, MountraApiError, MountraClient, type MountraClientOptions, MountraDownloader, MountraFile, type MountraFileDownloadOptions, type MountraFileExportOptions, type MountraFileLocator, type MountraFileResumeOptions, type MountraProgress, MountraClient as MountraSDK, type NormalizedMountraFileLocator, type PrepareUploadResponse, type PreparedUpload, type S3MultipartClient, type S3MultipartPart, S3MultipartUploader, type UploadFileOptions, type UploadResult, type UploadResumeOptions, type UploadSessionChunkContext, type UploadSessionContext, type UploadStatusChunk, type UploadStatusResponse, type UploadTarget, type WorkspaceId, type WorkspaceSelector, createMountraClient, isJumboChunk, sha256Hex, splitFileIntoChunks };
+/** An HTTP error returned by Mountra, or by a signed upload URL. */
+declare class MountraApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly body?: unknown;
+    constructor(message: string, input: {
+        status: number;
+        code?: string;
+        body?: unknown;
+    });
+}
+
+export { type AccessToken, type ChunkMethod, type CopyOptions, DEFAULT_S3_MULTIPART_PART_SIZE_BYTES, type DeleteOptions, type DownloadCacheChunk, type DownloadCacheFile, type DownloadCacheMode, type DownloadCacheOptions, type DownloadCacheStore, type DownloadCacheUsage, type DownloadCheckpoint, type DownloadCheckpointChunk, type DownloadCheckpointRequest, type DownloadCheckpointStore, type DownloadFileOptions, DownloadHttpError, type DownloadProgress, type DownloadResult, type DownloadResumeOptions, type ExportFileChunk, type ExportFileOptions, type ExportFileResponse, type FileChunk, type FileOperationResult, type FileSystemFileHandleLike, type FileSystemWritableFileStreamLike, type FinishUploadResponse, InMemoryDownloadCacheStore, InMemoryDownloadCheckpointStore, InMemoryJumboChunkCheckpointStore, InMemoryMetadataCacheStore, IndexedDBDownloadCacheStore, type IndexedDBDownloadCacheStoreOptions, IndexedDBDownloadCheckpointStore, IndexedDBMetadataCacheStore, type IndexedDBMetadataCacheStoreOptions, JUMBO_CHUNK_THRESHOLD_BYTES, type JumboChunkCheckpoint, type JumboChunkCheckpointStore, type JumboChunkCompleteInput, type JumboChunkCreateInput, type JumboChunkUploadPartInput, type JumboChunkUploader, type ListOptions, type ListResult, LocalStorageJumboChunkCheckpointStore, MAX_S3_MULTIPART_PARTS, MIN_S3_MULTIPART_PART_SIZE_BYTES, type MetadataCacheBatch, type MetadataCacheKind, type MetadataCacheOptions, type MetadataCacheRecord, type MetadataCacheStore, type MetadataListRecord, type MetadataReadMode, type MetadataReadOptions, type MetadataSource, type MetadataTreeRecord, type MkdirOptions, MountraApiError, MountraClient, type MountraClientOptions, MountraDownloader, MountraFile, type MountraFileDownloadOptions, type MountraFileEntry, type MountraFileExportOptions, type MountraFileLocator, type MountraFileResumeOptions, type MountraFileTreeNode, type MountraProgress, MountraClient as MountraSDK, type MoveOptions, type NormalizedMountraFileLocator, type PrepareUploadResponse, type PreparedUpload, type RenameOptions, type S3MultipartClient, type S3MultipartPart, S3MultipartUploader, type TreeOptions, type TreeResult, type UploadFileOptions, type UploadResult, type UploadResumeOptions, type UploadSessionChunkContext, type UploadSessionContext, type UploadStatusChunk, type UploadStatusResponse, type UploadTarget, type WorkspaceId, type WorkspaceSelector, createMountraClient, isJumboChunk, sha256Hex, splitFileIntoChunks };

package/dist/index.d.ts

@@ -52,6 +52,12 @@ interface DownloadCacheStore {
     getFile(workspace: string, fileKey: string): Promise<DownloadCacheFile | null>;
     putFile(workspace: string, fileKey: string, file: DownloadCacheFile): Promise<void>;
     removeFile(workspace: string, fileKey: string): Promise<void>;
+    /**
+     * Remove every file whose `path` is `path` or below it, keeping the chunks.
+     * Optional: without it, a move or delete through the client clears the
+     * whole workspace instead.
+     */
+    removeFilesUnder?(workspace: string, path: string): Promise<void>;
     /** Return the chunk bytes and mark the chunk as most recently used. */
     getChunk(workspace: string, storageKey: string): Promise<Blob | null>;
     /** Store the chunk bytes, then evict least recently used chunks until at most `maxBytes` remain. */
@@ -68,6 +74,7 @@ declare class InMemoryDownloadCacheStore implements DownloadCacheStore {
     getFile(workspace: string, fileKey: string): Promise<DownloadCacheFile | null>;
     putFile(workspace: string, fileKey: string, file: DownloadCacheFile): Promise<void>;
     removeFile(workspace: string, fileKey: string): Promise<void>;
+    removeFilesUnder(workspace: string, path: string): Promise<void>;
     getChunk(workspace: string, storageKey: string): Promise<Blob | null>;
     putChunk(workspace: string, storageKey: string, data: Blob, maxBytes: number): Promise<void>;
     clear(workspace?: string): Promise<void>;
@@ -86,6 +93,7 @@ declare class IndexedDBDownloadCacheStore implements DownloadCacheStore {
     getFile(workspace: string, fileKey: string): Promise<DownloadCacheFile | null>;
     putFile(workspace: string, fileKey: string, file: DownloadCacheFile): Promise<void>;
     removeFile(workspace: string, fileKey: string): Promise<void>;
+    removeFilesUnder(workspace: string, path: string): Promise<void>;
     getChunk(workspace: string, storageKey: string): Promise<Blob | null>;
     putChunk(workspace: string, storageKey: string, data: Blob, maxBytes: number): Promise<void>;
     clear(workspace?: string): Promise<void>;
@@ -110,6 +118,8 @@ declare class DownloadCache {
     storeChunk(workspace: string, chunk: DownloadCacheChunk, data: Blob): Promise<boolean>;
     storeFile(workspace: string, fileKey: string, file: Omit<DownloadCacheFile, "cachedAt" | "expiresAt">): Promise<void>;
     invalidateFiles(workspace: string, fileKeys: string[]): Promise<void>;
+    /** Drop the files at or below `paths`, which a write changed; their chunks stay cached. */
+    invalidatePaths(workspace: string, paths: string[]): Promise<void>;
     clear(workspace?: string): Promise<void>;
     usage(workspace?: string): Promise<DownloadCacheUsage>;
 }
@@ -280,6 +290,8 @@ declare class MountraDownloader {
         path?: string;
         ino?: number | string;
     }): Promise<void>;
+    /** Drop the cached files at or below paths that a delete, move, or copy changed. */
+    invalidateCachedPaths(selector: WorkspaceSelector, paths: string[]): Promise<void>;
     /**
      * Cache a file this client just uploaded, so downloading it needs no
      * network. Falls back to invalidation when any chunk cannot be cached.
@@ -348,6 +360,197 @@ declare class MountraFile {
     resume(options?: MountraFileResumeOptions): Promise<DownloadResult>;
 }
 
+type MetadataCacheKind = "list" | "tree";
+/** A cached `list` result: the entries of one directory. */
+interface MetadataListRecord {
+    kind: "list";
+    path: string;
+    entries: MountraFileEntry[];
+    /**
+     * When the request that returned this result was sent. Writes through this
+     * client and overlapping fetches may have updated the record since.
+     */
+    fetchedAt: number;
+}
+/** A cached `tree` result: one directory and its complete subtree. */
+interface MetadataTreeRecord {
+    kind: "tree";
+    path: string;
+    root: MountraFileTreeNode;
+    /** See `MetadataListRecord.fetchedAt`. */
+    fetchedAt: number;
+}
+type MetadataCacheRecord = MetadataListRecord | MetadataTreeRecord;
+interface MetadataCacheBatch {
+    put: MetadataCacheRecord[];
+    remove: Array<{
+        kind: MetadataCacheKind;
+        path: string;
+    }>;
+}
+interface MetadataCacheOptions {
+    /**
+     * Upper bound of cached `list` and `tree` results, shared by all
+     * workspaces. A tree counts as one result however large it is. Defaults to
+     * 1000; the least recently refreshed results are evicted first.
+     */
+    maxEntries?: number;
+    /** Cache storage. Defaults to IndexedDB, or memory when IndexedDB is unavailable. */
+    store?: MetadataCacheStore;
+}
+/**
+ * Storage behind the metadata cache. A record is identified by an opaque
+ * workspace key together with its `kind` and `path`, so one workspace never
+ * observes another workspace's records.
+ */
+interface MetadataCacheStore {
+    get(workspace: string, kind: MetadataCacheKind, path: string): Promise<MetadataCacheRecord | null>;
+    /** The records stored at `path` or at any path below it, of one kind or of both. */
+    getSubtree(workspace: string, path: string, kind?: MetadataCacheKind): Promise<MetadataCacheRecord[]>;
+    /** Apply the batch atomically, then evict the least recently written records until at most `maxEntries` remain. */
+    write(workspace: string, batch: MetadataCacheBatch, maxEntries: number): Promise<void>;
+    /** Remove every record, or only the records of one workspace. */
+    clear(workspace?: string): Promise<void>;
+}
+declare class InMemoryMetadataCacheStore implements MetadataCacheStore {
+    /** Map iteration order is the eviction order: the first entry was written least recently. */
+    private readonly records;
+    get(workspace: string, kind: MetadataCacheKind, path: string): Promise<MetadataCacheRecord | null>;
+    getSubtree(workspace: string, path: string, kind?: MetadataCacheKind): Promise<MetadataCacheRecord[]>;
+    write(workspace: string, batch: MetadataCacheBatch, maxEntries: number): Promise<void>;
+    clear(workspace?: string): Promise<void>;
+}
+interface IndexedDBMetadataCacheStoreOptions {
+    /** Use a separate database, for example one per signed-in user. */
+    databaseName?: string;
+}
+/** Records are keyed `[workspace, kind, path]`, so a subtree of one kind is one key range. */
+declare class IndexedDBMetadataCacheStore implements MetadataCacheStore {
+    private readonly databaseName;
+    private readonly fallback;
+    private databasePromise?;
+    constructor(options?: IndexedDBMetadataCacheStoreOptions);
+    get(workspace: string, kind: MetadataCacheKind, path: string): Promise<MetadataCacheRecord | null>;
+    getSubtree(workspace: string, path: string, kind?: MetadataCacheKind): Promise<MetadataCacheRecord[]>;
+    write(workspace: string, batch: MetadataCacheBatch, maxEntries: number): Promise<void>;
+    clear(workspace?: string): Promise<void>;
+    private openDatabase;
+}
+
+/** One entry of a directory listing. */
+interface MountraFileEntry {
+    name: string;
+    /** Absolute path in the workspace. */
+    path: string;
+    ino: number;
+    isDirectory: boolean;
+    size: number;
+    mtimeMs: number;
+    atimeMs: number;
+    uid?: number;
+    gid?: number;
+    uidDisplayName?: string;
+    uidUsername?: string;
+    uidSubjectId?: string;
+    uidSubjectType?: string;
+    gidDisplayName?: string;
+    gidUsername?: string;
+    gidSubjectId?: string;
+    gidSubjectType?: string;
+}
+/** A node of a file tree. A directory node holds its complete subtree. */
+interface MountraFileTreeNode {
+    name: string;
+    /** Absolute path in the workspace. */
+    path: string;
+    ino: number;
+    isDirectory: boolean;
+    size: number;
+    mtimeMs: number;
+    uid?: number;
+    gid?: number;
+    uidSubjectId?: string;
+    uidSubjectType?: string;
+    gidSubjectId?: string;
+    gidSubjectType?: string;
+    children: MountraFileTreeNode[];
+}
+/**
+ * How a metadata read uses the client's `metadataCache`:
+ * - `sync`: wait for Mountra and return its result.
+ * - `async`: return the cached result at once and refresh it in the
+ *   background. Without a cached result, wait for Mountra as `sync` does.
+ *
+ * Either way, a result fetched from Mountra is cached before it is returned.
+ */
+type MetadataReadMode = "sync" | "async";
+/** `cache` when the result was served from the metadata cache, `remote` when Mountra just returned it. */
+type MetadataSource = "cache" | "remote";
+interface MetadataReadOptions<T> extends WorkspaceSelector {
+    /** The directory to read. Defaults to `/`. */
+    path?: string;
+    /** Defaults to `sync`. */
+    mode?: MetadataReadMode;
+    /**
+     * `async` only: receives the refreshed result of a cached result that was
+     * returned, when the two differ.
+     */
+    onUpdate?: (result: T) => void;
+    /** `async` only: receives the error of a failed background refresh. */
+    onError?: (error: unknown) => void;
+    /** Also cancels the background refresh; no callback runs once it has aborted. */
+    signal?: AbortSignal;
+}
+interface ListResult {
+    path: string;
+    /** Directories first, then by name. */
+    entries: MountraFileEntry[];
+    source: MetadataSource;
+    /**
+     * When the request that returned this result was sent. A cached result
+     * also reflects writes made through this client since then.
+     */
+    fetchedAt: number;
+}
+interface TreeResult {
+    path: string;
+    root: MountraFileTreeNode;
+    source: MetadataSource;
+    /** See `ListResult.fetchedAt`. */
+    fetchedAt: number;
+}
+type ListOptions = MetadataReadOptions<ListResult>;
+type TreeOptions = MetadataReadOptions<TreeResult>;
+interface MkdirOptions extends WorkspaceSelector {
+    /** The directory to create. Its parent must exist. */
+    path: string;
+    signal?: AbortSignal;
+}
+interface RenameOptions extends WorkspaceSelector {
+    fromPath: string;
+    /** The new name within the same directory. */
+    toName: string;
+    signal?: AbortSignal;
+}
+interface MoveOptions extends WorkspaceSelector {
+    fromPath: string;
+    /** The complete destination path, which must not exist yet. */
+    toPath: string;
+    signal?: AbortSignal;
+}
+/** Copies one file; Mountra does not copy directories. */
+type CopyOptions = MoveOptions;
+interface DeleteOptions extends WorkspaceSelector {
+    /** A file, or an empty directory. */
+    path: string;
+    signal?: AbortSignal;
+}
+interface FileOperationResult {
+    /** The path of the created, renamed, moved, or copied entry. */
+    path: string;
+    ino: number;
+}
+
 type ChunkMethod = "none" | "fix";
 type WorkspaceId = number | string;
 declare const JUMBO_CHUNK_THRESHOLD_BYTES: number;
@@ -381,6 +584,12 @@ interface MountraClientOptions extends WorkspaceSelector {
      * unless set; pass `{}` for the defaults.
      */
     downloadCache?: DownloadCacheOptions;
+    /**
+     * Cache `list` and `tree` results locally, per workspace, in IndexedDB, so
+     * reads with `mode: "async"` return at once. Disabled unless set; pass `{}`
+     * for the defaults.
+     */
+    metadataCache?: MetadataCacheOptions;
 }
 interface UploadFileOptions extends WorkspaceSelector {
     path: string;
@@ -593,16 +802,6 @@ interface PreparedUpload {
     contentHash: string;
     context: UploadSessionContext;
 }
-declare class MountraApiError extends Error {
-    readonly status: number;
-    readonly code?: string;
-    readonly body?: unknown;
-    constructor(message: string, input: {
-        status: number;
-        code?: string;
-        body?: unknown;
-    });
-}
 declare class InMemoryJumboChunkCheckpointStore implements JumboChunkCheckpointStore {
     private readonly records;
     load(key: string): Promise<JumboChunkCheckpoint | null>;
@@ -652,6 +851,7 @@ declare class MountraClient {
     private readonly jumboChunkCheckpointStore;
     private readonly jumboPartSize;
     private readonly downloader;
+    private readonly metadata;
     constructor(options: MountraClientOptions);
     exportFile(options: ExportFileOptions): Promise<ExportFileResponse>;
     downloadFile(options: DownloadFileOptions): Promise<DownloadResult>;
@@ -662,6 +862,17 @@ declare class MountraClient {
     /** Clear the download cache of one workspace, or of every workspace when none is given. */
     clearDownloadCache(selector?: WorkspaceSelector): Promise<void>;
     getDownloadCacheUsage(selector?: WorkspaceSelector): Promise<DownloadCacheUsage>;
+    /** List the entries of a directory. See `MetadataReadMode` for how `mode` uses the metadata cache. */
+    list(options?: ListOptions): Promise<ListResult>;
+    /** Return a directory with its complete subtree. See `MetadataReadMode` for how `mode` uses the metadata cache. */
+    tree(options?: TreeOptions): Promise<TreeResult>;
+    mkdir(options: MkdirOptions): Promise<FileOperationResult>;
+    rename(options: RenameOptions): Promise<FileOperationResult>;
+    move(options: MoveOptions): Promise<FileOperationResult>;
+    copy(options: CopyOptions): Promise<FileOperationResult>;
+    delete(options: DeleteOptions): Promise<void>;
+    /** Clear the metadata cache of one workspace, or of every workspace when none is given. */
+    clearMetadataCache(selector?: WorkspaceSelector): Promise<void>;
     /** Create a stable resource object for one file in this or another workspace. */
     file(locator: MountraFileLocator): MountraFile;
     prepareUpload(file: Blob, options: UploadFileOptions): Promise<PreparedUpload>;
@@ -688,4 +899,16 @@ declare class MountraClient {
 }
 declare function createMountraClient(options: MountraClientOptions): MountraClient;
 
-export { type AccessToken, type ChunkMethod, DEFAULT_S3_MULTIPART_PART_SIZE_BYTES, type DownloadCacheChunk, type DownloadCacheFile, type DownloadCacheMode, type DownloadCacheOptions, type DownloadCacheStore, type DownloadCacheUsage, type DownloadCheckpoint, type DownloadCheckpointChunk, type DownloadCheckpointRequest, type DownloadCheckpointStore, type DownloadFileOptions, DownloadHttpError, type DownloadProgress, type DownloadResult, type DownloadResumeOptions, type ExportFileChunk, type ExportFileOptions, type ExportFileResponse, type FileChunk, type FileSystemFileHandleLike, type FileSystemWritableFileStreamLike, type FinishUploadResponse, InMemoryDownloadCacheStore, InMemoryDownloadCheckpointStore, InMemoryJumboChunkCheckpointStore, IndexedDBDownloadCacheStore, type IndexedDBDownloadCacheStoreOptions, IndexedDBDownloadCheckpointStore, JUMBO_CHUNK_THRESHOLD_BYTES, type JumboChunkCheckpoint, type JumboChunkCheckpointStore, type JumboChunkCompleteInput, type JumboChunkCreateInput, type JumboChunkUploadPartInput, type JumboChunkUploader, LocalStorageJumboChunkCheckpointStore, MAX_S3_MULTIPART_PARTS, MIN_S3_MULTIPART_PART_SIZE_BYTES, MountraApiError, MountraClient, type MountraClientOptions, MountraDownloader, MountraFile, type MountraFileDownloadOptions, type MountraFileExportOptions, type MountraFileLocator, type MountraFileResumeOptions, type MountraProgress, MountraClient as MountraSDK, type NormalizedMountraFileLocator, type PrepareUploadResponse, type PreparedUpload, type S3MultipartClient, type S3MultipartPart, S3MultipartUploader, type UploadFileOptions, type UploadResult, type UploadResumeOptions, type UploadSessionChunkContext, type UploadSessionContext, type UploadStatusChunk, type UploadStatusResponse, type UploadTarget, type WorkspaceId, type WorkspaceSelector, createMountraClient, isJumboChunk, sha256Hex, splitFileIntoChunks };
+/** An HTTP error returned by Mountra, or by a signed upload URL. */
+declare class MountraApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly body?: unknown;
+    constructor(message: string, input: {
+        status: number;
+        code?: string;
+        body?: unknown;
+    });
+}
+
+export { type AccessToken, type ChunkMethod, type CopyOptions, DEFAULT_S3_MULTIPART_PART_SIZE_BYTES, type DeleteOptions, type DownloadCacheChunk, type DownloadCacheFile, type DownloadCacheMode, type DownloadCacheOptions, type DownloadCacheStore, type DownloadCacheUsage, type DownloadCheckpoint, type DownloadCheckpointChunk, type DownloadCheckpointRequest, type DownloadCheckpointStore, type DownloadFileOptions, DownloadHttpError, type DownloadProgress, type DownloadResult, type DownloadResumeOptions, type ExportFileChunk, type ExportFileOptions, type ExportFileResponse, type FileChunk, type FileOperationResult, type FileSystemFileHandleLike, type FileSystemWritableFileStreamLike, type FinishUploadResponse, InMemoryDownloadCacheStore, InMemoryDownloadCheckpointStore, InMemoryJumboChunkCheckpointStore, InMemoryMetadataCacheStore, IndexedDBDownloadCacheStore, type IndexedDBDownloadCacheStoreOptions, IndexedDBDownloadCheckpointStore, IndexedDBMetadataCacheStore, type IndexedDBMetadataCacheStoreOptions, JUMBO_CHUNK_THRESHOLD_BYTES, type JumboChunkCheckpoint, type JumboChunkCheckpointStore, type JumboChunkCompleteInput, type JumboChunkCreateInput, type JumboChunkUploadPartInput, type JumboChunkUploader, type ListOptions, type ListResult, LocalStorageJumboChunkCheckpointStore, MAX_S3_MULTIPART_PARTS, MIN_S3_MULTIPART_PART_SIZE_BYTES, type MetadataCacheBatch, type MetadataCacheKind, type MetadataCacheOptions, type MetadataCacheRecord, type MetadataCacheStore, type MetadataListRecord, type MetadataReadMode, type MetadataReadOptions, type MetadataSource, type MetadataTreeRecord, type MkdirOptions, MountraApiError, MountraClient, type MountraClientOptions, MountraDownloader, MountraFile, type MountraFileDownloadOptions, type MountraFileEntry, type MountraFileExportOptions, type MountraFileLocator, type MountraFileResumeOptions, type MountraFileTreeNode, type MountraProgress, MountraClient as MountraSDK, type MoveOptions, type NormalizedMountraFileLocator, type PrepareUploadResponse, type PreparedUpload, type RenameOptions, type S3MultipartClient, type S3MultipartPart, S3MultipartUploader, type TreeOptions, type TreeResult, type UploadFileOptions, type UploadResult, type UploadResumeOptions, type UploadSessionChunkContext, type UploadSessionContext, type UploadStatusChunk, type UploadStatusResponse, type UploadTarget, type WorkspaceId, type WorkspaceSelector, createMountraClient, isJumboChunk, sha256Hex, splitFileIntoChunks };