@mountra/mountra-sdk 0.3.0 → 0.4.0

package/dist/index.js

@@ -94,6 +94,9 @@ function matchesLocator(request, locator) {
   }
   return String(request.ino) === String(locator.ino) && request.path === void 0;
 }
+function isPathWithin(path, ancestor) {
+  return ancestor === "/" || path === ancestor || path.startsWith(`${ancestor}/`);
+}
 function normalizePath(value) {
   if (!value || !value.trim()) {
     throw new TypeError("Mountra file path cannot be empty");
@@ -124,6 +127,73 @@ function normalizeIno(value) {
   return value;
 }
 
+// src/idb.ts
+function getIndexedDb() {
+  return globalThis.indexedDB ?? null;
+}
+function requestResult(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed"));
+  });
+}
+async function runTransaction(database, storeNames, mode, body) {
+  const transaction = database.transaction(storeNames, mode);
+  const done = new Promise((resolve, reject) => {
+    transaction.oncomplete = () => resolve();
+    transaction.onerror = () => reject(transaction.error ?? new Error("IndexedDB transaction failed"));
+    transaction.onabort = () => reject(transaction.error ?? new Error("IndexedDB transaction aborted"));
+  });
+  done.catch(() => void 0);
+  let result;
+  try {
+    result = await body(transaction);
+  } catch (error) {
+    try {
+      transaction.abort();
+    } catch {
+    }
+    throw error;
+  }
+  await done;
+  return result;
+}
+function workspaceRange(workspace) {
+  return IDBKeyRange.bound([workspace], [workspace, []]);
+}
+var CLOCK_KEY = "clock";
+async function nextClock(meta) {
+  const clock = (await requestResult(meta.get(CLOCK_KEY)) ?? 0) + 1;
+  await requestResult(meta.put(clock, CLOCK_KEY));
+  return clock;
+}
+function openDatabase(name, version, upgrade, onClose) {
+  const indexedDb = getIndexedDb();
+  if (!indexedDb) {
+    return Promise.resolve(null);
+  }
+  return new Promise((resolve) => {
+    let request;
+    try {
+      request = indexedDb.open(name, version);
+    } catch {
+      resolve(null);
+      return;
+    }
+    request.onupgradeneeded = () => upgrade(request.result);
+    request.onsuccess = () => {
+      const database = request.result;
+      database.onversionchange = () => {
+        database.close();
+        onClose();
+      };
+      resolve(database);
+    };
+    request.onerror = () => resolve(null);
+    request.onblocked = () => resolve(null);
+  });
+}
+
 // src/cache.ts
 var DEFAULT_MAX_BYTES = 512 * 1024 * 1024;
 var DEFAULT_MAX_CHUNK_BYTES = 128 * 1024 * 1024;
@@ -149,6 +219,13 @@ var InMemoryDownloadCacheStore = class {
   async removeFile(workspace, fileKey) {
     this.files.delete(memoryKey(workspace, fileKey));
   }
+  async removeFilesUnder(workspace, path) {
+    for (const [key, entry] of this.files) {
+      if (entry.workspace === workspace && isPathWithin(entry.file.path, path)) {
+        this.files.delete(key);
+      }
+    }
+  }
   async getChunk(workspace, storageKey) {
     const key = memoryKey(workspace, storageKey);
     const entry = this.chunks.get(key);
@@ -212,48 +289,9 @@ var CHUNK_DATA_STORE = "chunk-data";
 var META_STORE = "meta";
 var LRU_INDEX = "lastUsed";
 var USAGE_KEY = "bytes";
-var CLOCK_KEY = "clock";
-function getIndexedDb() {
-  return globalThis.indexedDB ?? null;
-}
-function workspaceRange(workspace) {
-  return IDBKeyRange.bound([workspace], [workspace, []]);
-}
 function sameKey(left, right) {
   return Array.isArray(left) && left[0] === right[0] && left[1] === right[1];
 }
-async function nextClock(meta) {
-  const clock = (await requestResult(meta.get(CLOCK_KEY)) ?? 0) + 1;
-  await requestResult(meta.put(clock, CLOCK_KEY));
-  return clock;
-}
-function requestResult(request) {
-  return new Promise((resolve, reject) => {
-    request.onsuccess = () => resolve(request.result);
-    request.onerror = () => reject(request.error ?? new Error("IndexedDB request failed"));
-  });
-}
-async function runTransaction(database, storeNames, mode, body) {
-  const transaction = database.transaction(storeNames, mode);
-  const done = new Promise((resolve, reject) => {
-    transaction.oncomplete = () => resolve();
-    transaction.onerror = () => reject(transaction.error ?? new Error("IndexedDB transaction failed"));
-    transaction.onabort = () => reject(transaction.error ?? new Error("IndexedDB transaction aborted"));
-  });
-  done.catch(() => void 0);
-  let result;
-  try {
-    result = await body(transaction);
-  } catch (error) {
-    try {
-      transaction.abort();
-    } catch {
-    }
-    throw error;
-  }
-  await done;
-  return result;
-}
 var IndexedDBDownloadCacheStore = class {
   databaseName;
   fallback = new InMemoryDownloadCacheStore();
@@ -291,6 +329,23 @@ var IndexedDBDownloadCacheStore = class {
       await requestResult(transaction.objectStore(FILES_STORE).delete([workspace, fileKey]));
     });
   }
+  async removeFilesUnder(workspace, path) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.removeFilesUnder(workspace, path);
+    }
+    await runTransaction(database, [FILES_STORE], "readwrite", async (transaction) => {
+      const cursorRequest = transaction.objectStore(FILES_STORE).openCursor(workspaceRange(workspace));
+      let cursor = await requestResult(cursorRequest);
+      while (cursor) {
+        if (isPathWithin(cursor.value.path, path)) {
+          await requestResult(cursor.delete());
+        }
+        cursor.continue();
+        cursor = await requestResult(cursorRequest);
+      }
+    });
+  }
   async getChunk(workspace, storageKey) {
     const database = await this.openDatabase();
     if (!database) {
@@ -414,47 +469,27 @@ var IndexedDBDownloadCacheStore = class {
     });
   }
   async openDatabase() {
-    if (!this.databasePromise) {
-      const indexedDb = getIndexedDb();
-      if (!indexedDb) {
-        this.databasePromise = Promise.resolve(null);
-      } else {
-        this.databasePromise = new Promise((resolve) => {
-          let request;
-          try {
-            request = indexedDb.open(this.databaseName, CACHE_DATABASE_VERSION);
-          } catch {
-            resolve(null);
-            return;
-          }
-          request.onupgradeneeded = () => {
-            const database = request.result;
-            if (!database.objectStoreNames.contains(FILES_STORE)) {
-              database.createObjectStore(FILES_STORE);
-            }
-            if (!database.objectStoreNames.contains(CHUNKS_STORE)) {
-              database.createObjectStore(CHUNKS_STORE).createIndex(LRU_INDEX, "lastUsed");
-            }
-            if (!database.objectStoreNames.contains(CHUNK_DATA_STORE)) {
-              database.createObjectStore(CHUNK_DATA_STORE);
-            }
-            if (!database.objectStoreNames.contains(META_STORE)) {
-              database.createObjectStore(META_STORE);
-            }
-          };
-          request.onsuccess = () => {
-            const database = request.result;
-            database.onversionchange = () => {
-              database.close();
-              this.databasePromise = void 0;
-            };
-            resolve(database);
-          };
-          request.onerror = () => resolve(null);
-          request.onblocked = () => resolve(null);
-        });
+    this.databasePromise ??= openDatabase(
+      this.databaseName,
+      CACHE_DATABASE_VERSION,
+      (database) => {
+        if (!database.objectStoreNames.contains(FILES_STORE)) {
+          database.createObjectStore(FILES_STORE);
+        }
+        if (!database.objectStoreNames.contains(CHUNKS_STORE)) {
+          database.createObjectStore(CHUNKS_STORE).createIndex(LRU_INDEX, "lastUsed");
+        }
+        if (!database.objectStoreNames.contains(CHUNK_DATA_STORE)) {
+          database.createObjectStore(CHUNK_DATA_STORE);
+        }
+        if (!database.objectStoreNames.contains(META_STORE)) {
+          database.createObjectStore(META_STORE);
+        }
+      },
+      () => {
+        this.databasePromise = void 0;
       }
-    }
+    );
     return this.databasePromise;
   }
 };
@@ -593,6 +628,20 @@ var DownloadCache = class {
       fileKeys.map((fileKey) => this.store.removeFile(workspace, fileKey).catch(() => void 0))
     );
   }
+  /** Drop the files at or below `paths`, which a write changed; their chunks stay cached. */
+  async invalidatePaths(workspace, paths) {
+    try {
+      if (!this.store.removeFilesUnder) {
+        await this.store.clear(workspace);
+        return;
+      }
+      for (const path of paths) {
+        await this.store.removeFilesUnder(workspace, path);
+      }
+    } catch {
+      await this.store.clear(workspace).catch(() => void 0);
+    }
+  }
   clear(workspace) {
     return this.store.clear(workspace);
   }
@@ -1156,6 +1205,14 @@ var MountraDownloader = class {
   async invalidateCachedFile(selector, target) {
     await this.cachedFileScope(selector, target)?.invalidate();
   }
+  /** Drop the cached files at or below paths that a delete, move, or copy changed. */
+  async invalidateCachedPaths(selector, paths) {
+    const cache = this.transport.cache;
+    const workspace = workspaceCacheKey(this.transport.baseUrl, selector);
+    if (cache && workspace !== null) {
+      await cache.invalidatePaths(workspace, paths);
+    }
+  }
   /**
    * Cache a file this client just uploaded, so downloading it needs no
    * network. Falls back to invalidation when any chunk cannot be cached.
@@ -1538,11 +1595,7 @@ var MountraDownloader = class {
   }
 };
 
-// src/upload.ts
-var JUMBO_CHUNK_THRESHOLD_BYTES = 128 * 1024 * 1024;
-var MIN_S3_MULTIPART_PART_SIZE_BYTES = 5 * 1024 * 1024;
-var DEFAULT_S3_MULTIPART_PART_SIZE_BYTES = 16 * 1024 * 1024;
-var MAX_S3_MULTIPART_PARTS = 1e4;
+// src/errors.ts
 var MountraApiError = class extends Error {
   status;
   code;
@@ -1555,9 +1608,936 @@ var MountraApiError = class extends Error {
     this.body = input.body;
   }
 };
+
+// src/metadata.ts
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function invalidField(field) {
+  return new TypeError(`Mountra metadata response field ${field} is invalid`);
+}
+function readString2(value, field) {
+  if (typeof value !== "string") {
+    throw invalidField(field);
+  }
+  return value;
+}
+function readCount(value, field) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw invalidField(field);
+  }
+  return value;
+}
+function readBoolean(value, field) {
+  if (typeof value !== "boolean") {
+    throw invalidField(field);
+  }
+  return value;
+}
+function optionalInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) ? value : void 0;
+}
+function optionalText(value) {
+  return typeof value === "string" && value ? value : void 0;
+}
+function withoutUndefined(value) {
+  for (const key of Object.keys(value)) {
+    if (value[key] === void 0) {
+      delete value[key];
+    }
+  }
+  return value;
+}
+function readNodeFields(raw, field) {
+  return {
+    name: readString2(raw.name, `${field}.name`),
+    path: normalizePath(readString2(raw.path, `${field}.path`)),
+    ino: readCount(raw.ino, `${field}.ino`),
+    isDirectory: readBoolean(raw.is_directory, `${field}.is_directory`),
+    size: readCount(raw.size, `${field}.size`),
+    mtimeMs: readCount(raw.mtime_ms, `${field}.mtime_ms`),
+    uid: optionalInteger(raw.uid),
+    gid: optionalInteger(raw.gid),
+    uidSubjectId: optionalText(raw.uid_subject_id),
+    uidSubjectType: optionalText(raw.uid_subject_type),
+    gidSubjectId: optionalText(raw.gid_subject_id),
+    gidSubjectType: optionalText(raw.gid_subject_type)
+  };
+}
+function readEntry(raw, field) {
+  if (!isRecord2(raw)) {
+    throw invalidField(field);
+  }
+  return withoutUndefined({
+    ...readNodeFields(raw, field),
+    atimeMs: readCount(raw.atime_ms, `${field}.atime_ms`),
+    uidDisplayName: optionalText(raw.uid_display_name),
+    uidUsername: optionalText(raw.uid_username),
+    gidDisplayName: optionalText(raw.gid_display_name),
+    gidUsername: optionalText(raw.gid_username)
+  });
+}
+function readTreeNode(raw, field) {
+  if (!isRecord2(raw) || !Array.isArray(raw.children)) {
+    throw invalidField(field);
+  }
+  return withoutUndefined({
+    ...readNodeFields(raw, field),
+    children: raw.children.map((child, index) => readTreeNode(child, `${field}.children[${index}]`))
+  });
+}
+function readListResponse(value) {
+  if (!isRecord2(value) || !Array.isArray(value.entries)) {
+    throw invalidField("entries");
+  }
+  return value.entries.map((entry, index) => readEntry(entry, `entries[${index}]`));
+}
+function readOperationResponse(value) {
+  if (!isRecord2(value)) {
+    throw new TypeError("Mountra file operation response is invalid");
+  }
+  return {
+    path: normalizePath(readString2(value.path, "path")),
+    ino: readCount(value.ino, "ino")
+  };
+}
+function sameJson(left, right) {
+  if (left === right) {
+    return true;
+  }
+  if (!isRecord2(left) || !isRecord2(right) || Array.isArray(left) !== Array.isArray(right)) {
+    return false;
+  }
+  const leftKeys = Object.keys(left);
+  return leftKeys.length === Object.keys(right).length && leftKeys.every((key) => Object.hasOwn(right, key) && sameJson(left[key], right[key]));
+}
+function sameContent(left, right) {
+  return left.kind === "list" && right.kind === "list" ? sameJson(left.entries, right.entries) : left.kind === "tree" && right.kind === "tree" && sameJson(left.root, right.root);
+}
+function workspaceBody(selector) {
+  return {
+    ...selector.workspaceCuid !== void 0 ? { workspace_cuid: selector.workspaceCuid } : {},
+    ...selector.workspaceId !== void 0 ? { workspace_id: selector.workspaceId } : {}
+  };
+}
+var MountraMetadata = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  list(options = {}) {
+    return this.read("list", options, (record, source) => ({
+      path: record.path,
+      entries: record.entries,
+      source,
+      fetchedAt: record.fetchedAt
+    }));
+  }
+  tree(options = {}) {
+    return this.read("tree", options, (record, source) => ({
+      path: record.path,
+      root: record.root,
+      source,
+      fetchedAt: record.fetchedAt
+    }));
+  }
+  async mkdir(options) {
+    const selector = this.resolveWorkspace(options);
+    const created = await this.operate(selector, "/file/mkdir", { path: normalizePath(options.path) }, options.signal);
+    await this.afterWrite(selector, {
+      type: "create",
+      path: created.path,
+      ino: created.ino,
+      isDirectory: true,
+      size: 0
+    });
+    return created;
+  }
+  async rename(options) {
+    const selector = this.resolveWorkspace(options);
+    const fromPath = normalizePath(options.fromPath);
+    const renamed = await this.operate(
+      selector,
+      "/file/rename",
+      { from_path: fromPath, to_name: options.toName },
+      options.signal
+    );
+    await this.afterWrite(selector, { type: "move", fromPath, toPath: renamed.path, ino: renamed.ino });
+    return renamed;
+  }
+  async move(options) {
+    const selector = this.resolveWorkspace(options);
+    const fromPath = normalizePath(options.fromPath);
+    const moved = await this.operate(
+      selector,
+      "/file/move",
+      { from_path: fromPath, to_path: normalizePath(options.toPath) },
+      options.signal
+    );
+    await this.afterWrite(selector, { type: "move", fromPath, toPath: moved.path, ino: moved.ino });
+    return moved;
+  }
+  async copy(options) {
+    const selector = this.resolveWorkspace(options);
+    const fromPath = normalizePath(options.fromPath);
+    const copied = await this.operate(
+      selector,
+      "/file/copy",
+      { from_path: fromPath, to_path: normalizePath(options.toPath) },
+      options.signal
+    );
+    await this.afterWrite(selector, { type: "copy", fromPath, toPath: copied.path, ino: copied.ino });
+    return copied;
+  }
+  async delete(options) {
+    const selector = this.resolveWorkspace(options);
+    const path = normalizePath(options.path);
+    await this.transport.requestJson("/file/delete", { ...workspaceBody(selector), path }, options.signal);
+    await this.afterWrite(selector, { type: "remove", path });
+  }
+  /** Show a file that an upload just finished. The upload updates the download cache itself. */
+  recordUpload(selector, file) {
+    return this.applyChange(selector, {
+      type: "create",
+      path: normalizePath(file.path),
+      ...file.ino !== void 0 ? { ino: file.ino } : {},
+      isDirectory: false,
+      size: file.size
+    });
+  }
+  async clearCache(selector) {
+    const cache = this.transport.cache;
+    if (!cache) {
+      return;
+    }
+    if (selector === void 0) {
+      await cache.clear();
+      return;
+    }
+    const workspace = workspaceCacheKey(this.transport.baseUrl, selector);
+    if (workspace === null) {
+      throw new TypeError("workspaceCuid or workspaceId is required");
+    }
+    await cache.clear(workspace);
+  }
+  async read(kind, options, present) {
+    const selector = this.resolveWorkspace(options);
+    const path = normalizePath(options.path ?? "/");
+    const scope = this.cacheScope(selector);
+    const { signal, onUpdate, onError } = options;
+    const cached = options.mode === "async" && scope ? await scope.cache.get(scope.workspace, kind, path) : null;
+    if (!cached) {
+      return present(await this.fetch(kind, selector, path, signal), "remote");
+    }
+    void this.fetch(kind, selector, path, signal).then(
+      (fresh) => {
+        if (!signal?.aborted && !sameContent(cached, fresh)) {
+          onUpdate?.(present(fresh, "remote"));
+        }
+      },
+      (error) => {
+        if (!signal?.aborted) {
+          onError?.(error);
+        }
+      }
+    );
+    return present(cached, "cache");
+  }
+  /** Fetch from Mountra, and cache the result before returning it. */
+  async fetch(kind, selector, path, signal) {
+    const scope = this.cacheScope(selector);
+    const ticket = scope?.cache.beginFetch(scope.workspace);
+    let body;
+    try {
+      body = await this.transport.requestJson(`/file/${kind}`, { ...workspaceBody(selector), path }, signal);
+    } catch (error) {
+      if (scope && ticket && error instanceof MountraApiError && error.status === 404) {
+        await scope.cache.forgetFetched(scope.workspace, path, ticket);
+      }
+      throw error;
+    }
+    const fetchedAt = ticket?.startedAt ?? Date.now();
+    let record;
+    if (kind === "list") {
+      record = { kind, path, entries: readListResponse(body), fetchedAt };
+    } else {
+      if (!isRecord2(body)) {
+        throw invalidField("root");
+      }
+      record = { kind, path, root: readTreeNode(body.root, "root"), fetchedAt };
+    }
+    if (scope && ticket) {
+      await scope.cache.storeFetched(scope.workspace, record, ticket);
+    }
+    return record;
+  }
+  async operate(selector, endpoint, body, signal) {
+    return readOperationResponse(
+      await this.transport.requestJson(endpoint, { ...workspaceBody(selector), ...body }, signal)
+    );
+  }
+  /**
+   * Reflect a write in both caches. Any download cached at a path the write
+   * changed is stale: the file is gone, moved, or a new one now lives there.
+   */
+  async afterWrite(selector, change) {
+    const paths = change.type === "move" ? [change.fromPath, change.toPath] : change.type === "copy" ? [change.toPath] : [change.path];
+    await Promise.all([
+      this.applyChange(selector, change),
+      this.transport.invalidateDownloads(selector, paths)
+    ]);
+  }
+  async applyChange(selector, change) {
+    const scope = this.cacheScope(selector);
+    await scope?.cache.applyChange(scope.workspace, change);
+  }
+  /** Fall back to the client workspace only when the call names none, as downloads do. */
+  resolveWorkspace(selector) {
+    const named = selector.workspaceCuid !== void 0 || selector.workspaceId !== void 0;
+    const { workspaceCuid, workspaceId } = named ? selector : this.transport.clientSelector;
+    if (workspaceCuid === void 0 && workspaceId === void 0) {
+      throw new TypeError("workspaceCuid or workspaceId is required");
+    }
+    return {
+      ...workspaceCuid !== void 0 ? { workspaceCuid } : {},
+      ...workspaceId !== void 0 ? { workspaceId } : {}
+    };
+  }
+  cacheScope(selector) {
+    const cache = this.transport.cache;
+    const workspace = workspaceCacheKey(this.transport.baseUrl, selector);
+    return cache && workspace !== null ? { cache, workspace } : null;
+  }
+};
+
+// src/metadata-cache.ts
+var DEFAULT_MAX_ENTRIES = 1e3;
+var KINDS = ["list", "tree"];
+function parentOf(path) {
+  const index = path.lastIndexOf("/");
+  return index <= 0 ? "/" : path.slice(0, index);
+}
+function baseName(path) {
+  return path.slice(path.lastIndexOf("/") + 1) || "/";
+}
+function selfAndAncestors(path) {
+  const paths = [path];
+  for (let current = path; current !== "/"; ) {
+    current = parentOf(current);
+    paths.push(current);
+  }
+  return paths;
+}
+function rebasePath(path, from, to) {
+  return `${to}${path.slice(from.length)}`;
+}
+function memoryKey2(workspace, kind, path) {
+  return JSON.stringify([workspace, kind, path]);
+}
+var InMemoryMetadataCacheStore = class {
+  /** Map iteration order is the eviction order: the first entry was written least recently. */
+  records = /* @__PURE__ */ new Map();
+  async get(workspace, kind, path) {
+    const entry = this.records.get(memoryKey2(workspace, kind, path));
+    return entry ? structuredClone(entry.record) : null;
+  }
+  async getSubtree(workspace, path, kind) {
+    return [...this.records.values()].filter(
+      (entry) => entry.workspace === workspace && (kind === void 0 || entry.record.kind === kind) && isPathWithin(entry.record.path, path)
+    ).map((entry) => structuredClone(entry.record));
+  }
+  async write(workspace, batch, maxEntries) {
+    for (const { kind, path } of batch.remove) {
+      this.records.delete(memoryKey2(workspace, kind, path));
+    }
+    for (const record of batch.put) {
+      const key = memoryKey2(workspace, record.kind, record.path);
+      this.records.delete(key);
+      this.records.set(key, { workspace, record: structuredClone(record) });
+    }
+    for (const key of this.records.keys()) {
+      if (this.records.size <= maxEntries) {
+        break;
+      }
+      this.records.delete(key);
+    }
+  }
+  async clear(workspace) {
+    for (const [key, entry] of this.records) {
+      if (workspace === void 0 || entry.workspace === workspace) {
+        this.records.delete(key);
+      }
+    }
+  }
+};
+var METADATA_DATABASE_NAME = "mountra-sdk-metadata-cache";
+var METADATA_DATABASE_VERSION = 1;
+var RECORDS_STORE = "records";
+var META_STORE2 = "meta";
+var WRITE_ORDER_INDEX = "written";
+var IndexedDBMetadataCacheStore = class {
+  databaseName;
+  fallback = new InMemoryMetadataCacheStore();
+  databasePromise;
+  constructor(options = {}) {
+    this.databaseName = options.databaseName ?? METADATA_DATABASE_NAME;
+  }
+  async get(workspace, kind, path) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.get(workspace, kind, path);
+    }
+    return runTransaction(database, [RECORDS_STORE], "readonly", async (transaction) => {
+      const stored = await requestResult(
+        transaction.objectStore(RECORDS_STORE).get([workspace, kind, path])
+      );
+      return stored?.record ?? null;
+    });
+  }
+  async getSubtree(workspace, path, kind) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.getSubtree(workspace, path, kind);
+    }
+    const upper = path === "/" ? "0" : `${path}0`;
+    return runTransaction(database, [RECORDS_STORE], "readonly", async (transaction) => {
+      const records = [];
+      for (const candidate of kind === void 0 ? KINDS : [kind]) {
+        const stored = await requestResult(
+          transaction.objectStore(RECORDS_STORE).getAll(IDBKeyRange.bound([workspace, candidate, path], [workspace, candidate, upper], false, true))
+        );
+        records.push(
+          ...stored.map(({ record }) => record).filter((record) => isPathWithin(record.path, path))
+        );
+      }
+      return records;
+    });
+  }
+  async write(workspace, batch, maxEntries) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.write(workspace, batch, maxEntries);
+    }
+    await runTransaction(database, [RECORDS_STORE, META_STORE2], "readwrite", async (transaction) => {
+      const records = transaction.objectStore(RECORDS_STORE);
+      const meta = transaction.objectStore(META_STORE2);
+      for (const { kind, path } of batch.remove) {
+        await requestResult(records.delete([workspace, kind, path]));
+      }
+      for (const record of batch.put) {
+        const stored = { record, written: await nextClock(meta) };
+        await requestResult(records.put(stored, [workspace, record.kind, record.path]));
+      }
+      let count = await requestResult(records.count());
+      if (count <= maxEntries) {
+        return;
+      }
+      const cursorRequest = records.index(WRITE_ORDER_INDEX).openCursor();
+      let cursor = await requestResult(cursorRequest);
+      while (cursor && count > maxEntries) {
+        await requestResult(cursor.delete());
+        count -= 1;
+        cursor.continue();
+        cursor = await requestResult(cursorRequest);
+      }
+    });
+  }
+  async clear(workspace) {
+    const database = await this.openDatabase();
+    if (!database) {
+      return this.fallback.clear(workspace);
+    }
+    await runTransaction(database, [RECORDS_STORE], "readwrite", async (transaction) => {
+      const records = transaction.objectStore(RECORDS_STORE);
+      await requestResult(
+        workspace === void 0 ? records.clear() : records.delete(workspaceRange(workspace))
+      );
+    });
+  }
+  async openDatabase() {
+    this.databasePromise ??= openDatabase(
+      this.databaseName,
+      METADATA_DATABASE_VERSION,
+      (database) => {
+        if (!database.objectStoreNames.contains(RECORDS_STORE)) {
+          database.createObjectStore(RECORDS_STORE).createIndex(WRITE_ORDER_INDEX, "written");
+        }
+        if (!database.objectStoreNames.contains(META_STORE2)) {
+          database.createObjectStore(META_STORE2);
+        }
+      },
+      () => {
+        this.databasePromise = void 0;
+      }
+    );
+    return this.databasePromise;
+  }
+};
+var NODE_FIELDS = [
+  "name",
+  "path",
+  "ino",
+  "isDirectory",
+  "size",
+  "mtimeMs",
+  "uid",
+  "gid",
+  "uidSubjectId",
+  "uidSubjectType",
+  "gidSubjectId",
+  "gidSubjectType"
+];
+function pickDefined(source, keys) {
+  const picked = {};
+  for (const key of keys) {
+    if (source[key] !== void 0) {
+      picked[key] = source[key];
+    }
+  }
+  return picked;
+}
+function nodeFromEntry(entry, children) {
+  return { ...pickDefined(entry, NODE_FIELDS), children };
+}
+function entryFromNode(node, previous) {
+  return {
+    ...pickDefined(node, NODE_FIELDS),
+    atimeMs: previous.atimeMs,
+    ...node.uid === previous.uid ? pickDefined(previous, ["uidDisplayName", "uidUsername"]) : {},
+    ...node.gid === previous.gid ? pickDefined(previous, ["gidDisplayName", "gidUsername"]) : {}
+  };
+}
+function findNode(root, path) {
+  let node = root;
+  while (node && node.path !== path) {
+    node = isPathWithin(path, node.path) ? node.children.find((child) => isPathWithin(path, child.path)) : void 0;
+  }
+  return node;
+}
+function rebaseNode(node, from, to) {
+  return {
+    ...node,
+    ...node.path === from ? { name: baseName(to) } : {},
+    path: rebasePath(node.path, from, to),
+    children: node.children.map((child) => rebaseNode(child, from, to))
+  };
+}
+function compareChildren(left, right) {
+  return Number(right.isDirectory) - Number(left.isDirectory) || left.name.localeCompare(right.name);
+}
+function withChild(children, child) {
+  const result = [...children];
+  const existing = result.findIndex((candidate) => candidate.path === child.path);
+  if (existing >= 0) {
+    result[existing] = child;
+    return result;
+  }
+  const position = result.findIndex((candidate) => compareChildren(child, candidate) < 0);
+  result.splice(position < 0 ? result.length : position, 0, child);
+  return result;
+}
+function recordKey(kind, path) {
+  return `${kind}:${path}`;
+}
+var MetadataDraft = class {
+  records = /* @__PURE__ */ new Map();
+  changed = /* @__PURE__ */ new Set();
+  removed = /* @__PURE__ */ new Map();
+  constructor(records) {
+    for (const record of records) {
+      this.records.set(recordKey(record.kind, record.path), record);
+    }
+  }
+  list(path) {
+    const record = this.records.get(recordKey("list", path));
+    return record?.kind === "list" ? record : void 0;
+  }
+  tree(path) {
+    const record = this.records.get(recordKey("tree", path));
+    return record?.kind === "tree" ? record : void 0;
+  }
+  /** Loaded trees that hold `path`: those rooted at `path` or at one of its ancestors. */
+  treesContaining(path) {
+    return [...this.records.values()].filter(
+      (record) => record.kind === "tree" && isPathWithin(path, record.path)
+    );
+  }
+  /** Loaded records at `path` or below it. */
+  within(path) {
+    return [...this.records.values()].filter((record) => isPathWithin(record.path, path));
+  }
+  put(record) {
+    const key = recordKey(record.kind, record.path);
+    this.records.set(key, record);
+    this.removed.delete(key);
+    this.changed.add(key);
+  }
+  /** Mark a loaded record that was changed in place. */
+  touch(record) {
+    this.changed.add(recordKey(record.kind, record.path));
+  }
+  remove(record) {
+    const key = recordKey(record.kind, record.path);
+    this.records.delete(key);
+    this.changed.delete(key);
+    this.removed.set(key, { kind: record.kind, path: record.path });
+  }
+  batch() {
+    return {
+      put: [...this.changed].map((key) => this.records.get(key)),
+      remove: [...this.removed.values()]
+    };
+  }
+  findEntry(path) {
+    return this.list(parentOf(path))?.entries.find((entry) => entry.path === path);
+  }
+  /** The node of `path` with its complete subtree, from any loaded tree. */
+  findNode(path) {
+    for (const tree of this.treesContaining(path)) {
+      const node = findNode(tree.root, path);
+      if (node) {
+        return node;
+      }
+    }
+    return void 0;
+  }
+  /** Remove `path` from the listing and the trees that show it. */
+  removeEntry(path) {
+    const parentPath = parentOf(path);
+    const list = this.list(parentPath);
+    if (list?.entries.some((entry) => entry.path === path)) {
+      list.entries = list.entries.filter((entry) => entry.path !== path);
+      this.touch(list);
+    }
+    for (const tree of this.treesContaining(parentPath)) {
+      const parent = findNode(tree.root, parentPath);
+      if (parent?.children.some((child) => child.path === path)) {
+        parent.children = parent.children.filter((child) => child.path !== path);
+        this.touch(tree);
+      }
+    }
+  }
+  /**
+   * Show `path` in its parent's listing and in the trees holding its parent.
+   * A record that cannot show it faithfully, because the entry or the
+   * complete node is unknown, is dropped instead.
+   */
+  insertEntry(path, entry, node) {
+    const parentPath = parentOf(path);
+    const list = this.list(parentPath);
+    if (list && entry) {
+      list.entries = withChild(list.entries, entry);
+      this.touch(list);
+    } else if (list) {
+      this.remove(list);
+    }
+    for (const tree of this.treesContaining(parentPath)) {
+      const parent = findNode(tree.root, parentPath);
+      if (node && parent?.isDirectory) {
+        parent.children = withChild(parent.children, structuredClone(node));
+        this.touch(tree);
+      } else {
+        this.remove(tree);
+      }
+    }
+  }
+  removeSubtree(path) {
+    for (const record of this.within(path)) {
+      this.remove(record);
+    }
+  }
+  /** Re-key the records at or below `from` to `to`, rewriting the paths they hold. */
+  moveSubtree(from, to) {
+    for (const record of this.within(from)) {
+      this.remove(record);
+      const path = rebasePath(record.path, from, to);
+      this.put(
+        record.kind === "list" ? {
+          ...record,
+          path,
+          entries: record.entries.map((entry) => ({ ...entry, path: rebasePath(entry.path, from, to) }))
+        } : { ...record, path, root: rebaseNode(record.root, from, to) }
+      );
+    }
+  }
+};
+function changeScope(change) {
+  const paths = change.type === "move" || change.type === "copy" ? [change.fromPath, change.toPath] : [change.path];
+  return {
+    lists: paths.map(parentOf),
+    trees: paths.flatMap((path) => selfAndAncestors(parentOf(path))),
+    // A copy keeps its source; any other change makes records below its paths stale or moves them.
+    subtrees: change.type === "copy" ? [change.toPath] : paths
+  };
+}
+function patchChange(draft, change, now) {
+  switch (change.type) {
+    case "create": {
+      const previousEntry = draft.findEntry(change.path);
+      const previousNode = draft.findNode(change.path);
+      draft.removeSubtree(change.path);
+      if (change.ino === void 0) {
+        draft.insertEntry(change.path, null, null);
+        return;
+      }
+      const fields = {
+        name: baseName(change.path),
+        path: change.path,
+        ino: change.ino,
+        isDirectory: change.isDirectory,
+        size: change.size,
+        mtimeMs: now
+      };
+      const sameKind = (previous) => previous?.isDirectory === change.isDirectory;
+      draft.insertEntry(
+        change.path,
+        { atimeMs: now, ...sameKind(previousEntry) ? previousEntry : {}, ...fields },
+        { ...sameKind(previousNode) ? previousNode : {}, ...fields, children: [] }
+      );
+      return;
+    }
+    case "remove":
+      draft.removeEntry(change.path);
+      draft.removeSubtree(change.path);
+      return;
+    case "move": {
+      const { fromPath, toPath } = change;
+      if (fromPath === toPath) {
+        return;
+      }
+      const entry = draft.findEntry(fromPath);
+      const node = draft.findNode(fromPath);
+      draft.removeEntry(fromPath);
+      draft.removeSubtree(toPath);
+      draft.moveSubtree(fromPath, toPath);
+      const fields = { name: baseName(toPath), path: toPath, ino: change.ino };
+      const movedEntry = entry ? { ...entry, ...fields } : null;
+      draft.insertEntry(
+        toPath,
+        movedEntry,
+        node ? { ...rebaseNode(node, fromPath, toPath), ino: change.ino } : movedEntry && !movedEntry.isDirectory ? nodeFromEntry(movedEntry, []) : null
+      );
+      return;
+    }
+    case "copy": {
+      const source = draft.findEntry(change.fromPath) ?? draft.findNode(change.fromPath);
+      draft.removeSubtree(change.toPath);
+      if (!source || source.isDirectory) {
+        draft.insertEntry(change.toPath, null, null);
+        return;
+      }
+      const fields = {
+        name: baseName(change.toPath),
+        path: change.toPath,
+        ino: change.ino,
+        isDirectory: false,
+        size: source.size,
+        mtimeMs: now
+      };
+      draft.insertEntry(change.toPath, { ...fields, atimeMs: now }, { ...fields, children: [] });
+      return;
+    }
+  }
+}
+function childrenFromEntries(directory, entries) {
+  const children = [];
+  for (const entry of entries) {
+    const previous = directory.children.find((child) => child.path === entry.path);
+    if (!entry.isDirectory) {
+      children.push(nodeFromEntry(entry, []));
+    } else if (previous?.isDirectory && previous.ino === entry.ino) {
+      children.push(nodeFromEntry(entry, previous.children));
+    } else {
+      return null;
+    }
+  }
+  return children;
+}
+function entriesFromNodes(entries, nodes) {
+  const previous = new Map(entries.map((entry) => [entry.path, entry]));
+  const fresh = new Map(nodes.map((node) => [node.path, node]));
+  for (const node of nodes) {
+    const entry = previous.get(node.path);
+    if (!entry || entry.ino !== node.ino || entry.isDirectory !== node.isDirectory) {
+      return null;
+    }
+  }
+  return entries.filter((entry) => fresh.has(entry.path)).map((entry) => entryFromNode(fresh.get(entry.path), entry));
+}
+function patchFetchedList(draft, record) {
+  if ((draft.list(record.path)?.fetchedAt ?? 0) > record.fetchedAt) {
+    return;
+  }
+  draft.put(record);
+  for (const tree of draft.treesContaining(record.path)) {
+    if (tree.fetchedAt > record.fetchedAt) {
+      continue;
+    }
+    const directory = findNode(tree.root, record.path);
+    const children = directory?.isDirectory ? childrenFromEntries(directory, record.entries) : null;
+    if (directory && children) {
+      directory.children = children;
+      draft.touch(tree);
+    } else {
+      draft.remove(tree);
+    }
+  }
+}
+function patchFetchedTree(draft, record) {
+  if ((draft.tree(record.path)?.fetchedAt ?? 0) > record.fetchedAt) {
+    return;
+  }
+  draft.put(record);
+  for (const other of draft.within(record.path)) {
+    if (other === record || other.fetchedAt > record.fetchedAt) {
+      continue;
+    }
+    const node = findNode(record.root, other.path);
+    if (other.kind === "tree") {
+      if (node?.isDirectory) {
+        draft.put({ ...other, root: structuredClone(node), fetchedAt: record.fetchedAt });
+      } else {
+        draft.remove(other);
+      }
+      continue;
+    }
+    const entries = node?.isDirectory ? entriesFromNodes(other.entries, node.children) : null;
+    if (entries) {
+      other.entries = entries;
+      draft.touch(other);
+    } else {
+      draft.remove(other);
+    }
+  }
+  if (record.path === "/") {
+    return;
+  }
+  const parentPath = parentOf(record.path);
+  for (const tree of draft.treesContaining(parentPath)) {
+    if (tree.fetchedAt > record.fetchedAt) {
+      continue;
+    }
+    const parent = findNode(tree.root, parentPath);
+    if (parent?.isDirectory) {
+      parent.children = withChild(parent.children, structuredClone(record.root));
+      draft.touch(tree);
+    } else {
+      draft.remove(tree);
+    }
+  }
+}
+var MetadataCache = class {
+  maxEntries;
+  store;
+  /** Per workspace, how many writes this client has applied. */
+  writeSeqs = /* @__PURE__ */ new Map();
+  /** Per workspace, the tail of the queue that serializes cache updates. */
+  queues = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    if (!Number.isSafeInteger(this.maxEntries) || this.maxEntries <= 0) {
+      throw new RangeError("metadataCache.maxEntries must be a positive safe integer");
+    }
+    this.store = options.store ?? new IndexedDBMetadataCacheStore();
+  }
+  async get(workspace, kind, path) {
+    try {
+      const record = await this.store.get(workspace, kind, path);
+      return record?.kind === kind && record.path === path ? record : null;
+    } catch {
+      return null;
+    }
+  }
+  beginFetch(workspace) {
+    return { startedAt: Date.now(), writeSeq: this.writeSeqs.get(workspace) ?? 0 };
+  }
+  /** Cache a fetched result, and bring the records it overlaps up to date with it. */
+  async storeFetched(workspace, record, ticket) {
+    await this.update(workspace, ticket, async () => {
+      if (record.kind === "list") {
+        const draft2 = await this.load(workspace, { lists: [record.path], trees: selfAndAncestors(record.path) });
+        patchFetchedList(draft2, record);
+        return draft2;
+      }
+      const draft = await this.load(workspace, { trees: selfAndAncestors(record.path), subtrees: [record.path] });
+      patchFetchedTree(draft, record);
+      return draft;
+    }).catch(() => void 0);
+  }
+  /** Mountra reported that `path` does not exist. */
+  async forgetFetched(workspace, path, ticket) {
+    const change = { type: "remove", path };
+    await this.update(workspace, ticket, async () => {
+      const draft = await this.load(workspace, changeScope(change));
+      patchChange(draft, change, Date.now());
+      return draft;
+    }).catch(() => void 0);
+  }
+  /** Reflect a write that Mountra completed. */
+  async applyChange(workspace, change) {
+    this.writeSeqs.set(workspace, (this.writeSeqs.get(workspace) ?? 0) + 1);
+    await this.update(workspace, null, async () => {
+      const draft = await this.load(workspace, changeScope(change));
+      patchChange(draft, change, Date.now());
+      return draft;
+    }).catch(
+      () => (
+        // A write that cannot be reflected must not leave records that contradict it.
+        this.store.clear(workspace).catch(() => void 0)
+      )
+    );
+  }
+  clear(workspace) {
+    return this.store.clear(workspace);
+  }
+  /**
+   * Run updates of one workspace one at a time. An update for a fetch is
+   * dropped when this client completed a write since the fetch started: the
+   * result may predate that write.
+   */
+  update(workspace, ticket, build) {
+    const run = async () => {
+      if (ticket && ticket.writeSeq !== (this.writeSeqs.get(workspace) ?? 0)) {
+        return;
+      }
+      const batch = (await build()).batch();
+      if (batch.put.length > 0 || batch.remove.length > 0) {
+        await this.store.write(workspace, batch, this.maxEntries);
+      }
+    };
+    const result = (this.queues.get(workspace) ?? Promise.resolve()).then(run);
+    const tail = result.catch(() => void 0);
+    this.queues.set(workspace, tail);
+    void tail.then(() => {
+      if (this.queues.get(workspace) === tail) {
+        this.queues.delete(workspace);
+      }
+    });
+    return result;
+  }
+  async load(workspace, scope) {
+    const [records, subtrees] = await Promise.all([
+      Promise.all([
+        ...[...new Set(scope.lists)].map((path) => this.store.get(workspace, "list", path)),
+        ...[...new Set(scope.trees)].map((path) => this.store.get(workspace, "tree", path))
+      ]),
+      Promise.all([...new Set(scope.subtrees)].map((path) => this.store.getSubtree(workspace, path)))
+    ]);
+    return new MetadataDraft([
+      ...records.filter((record) => record !== null),
+      ...subtrees.flat()
+    ]);
+  }
+};
+
+// src/upload.ts
+var JUMBO_CHUNK_THRESHOLD_BYTES = 128 * 1024 * 1024;
+var MIN_S3_MULTIPART_PART_SIZE_BYTES = 5 * 1024 * 1024;
+var DEFAULT_S3_MULTIPART_PART_SIZE_BYTES = 16 * 1024 * 1024;
+var MAX_S3_MULTIPART_PARTS = 1e4;
 var memoryCheckpointRecords = /* @__PURE__ */ new Map();
 function parseJumboCheckpoint(value) {
-  if (!isRecord2(value) || value.version !== 1 || typeof value.storageKey !== "string") {
+  if (!isRecord3(value) || value.version !== 1 || typeof value.storageKey !== "string") {
     return null;
   }
   if (typeof value.chunkIndex !== "number" || typeof value.chunkSize !== "number" || typeof value.chunkSha256 !== "string" || typeof value.partSize !== "number" || typeof value.uploadId !== "string" || !Array.isArray(value.parts)) {
@@ -1565,7 +2545,7 @@ function parseJumboCheckpoint(value) {
   }
   const parts = [];
   for (const part of value.parts) {
-    if (!isRecord2(part)) {
+    if (!isRecord3(part)) {
       return null;
     }
     if (typeof part.partNumber !== "number" || typeof part.etag !== "string" || typeof part.size !== "number" || typeof part.sha256 !== "string") {
@@ -1744,11 +2724,11 @@ function throwIfAborted2(signal) {
   }
   throw new DOMException("The upload was aborted", "AbortError");
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
 function parseApiErrorBody(body) {
-  if (!isRecord2(body)) {
+  if (!isRecord3(body)) {
     return {};
   }
   return {
@@ -1757,7 +2737,7 @@ function parseApiErrorBody(body) {
   };
 }
 function ensurePrepareResponse(value) {
-  if (!isRecord2(value) || typeof value.upload_id !== "string") {
+  if (!isRecord3(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra prepare response is invalid");
   }
   if (!Array.isArray(value.upload_targets)) {
@@ -1766,13 +2746,13 @@ function ensurePrepareResponse(value) {
   return value;
 }
 function ensureFinishResponse(value) {
-  if (!isRecord2(value) || typeof value.upload_id !== "string") {
+  if (!isRecord3(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra finish response is invalid");
   }
   return value;
 }
 function ensureUploadStatusResponse(value) {
-  if (!isRecord2(value) || typeof value.upload_id !== "string") {
+  if (!isRecord3(value) || typeof value.upload_id !== "string") {
     throw new TypeError("Mountra upload status response is invalid");
   }
   if (!Array.isArray(value.chunks)) {
@@ -1823,6 +2803,7 @@ var MountraClient = class {
   jumboChunkCheckpointStore;
   jumboPartSize;
   downloader;
+  metadata;
   constructor(options) {
     this.baseUrl = normalizeBaseUrl(options.baseUrl);
     this.apiPrefix = normalizeApiPrefix(options.apiPrefix ?? "/api");
@@ -1849,6 +2830,13 @@ var MountraClient = class {
       cache: options.downloadCache ? new DownloadCache(options.downloadCache) : null,
       requestJson: (path, body, signal) => this.requestJson(path, body, signal)
     });
+    this.metadata = new MountraMetadata({
+      baseUrl: this.baseUrl,
+      clientSelector: this.clientSelector,
+      cache: options.metadataCache ? new MetadataCache(options.metadataCache) : null,
+      requestJson: (path, body, signal) => this.requestJson(path, body, signal),
+      invalidateDownloads: (selector, paths) => this.downloader.invalidateCachedPaths(selector, paths)
+    });
   }
   async exportFile(options) {
     return this.downloader.exportFile(options);
@@ -1875,6 +2863,33 @@ var MountraClient = class {
   getDownloadCacheUsage(selector) {
     return this.downloader.cacheUsage(selector);
   }
+  /** List the entries of a directory. See `MetadataReadMode` for how `mode` uses the metadata cache. */
+  list(options) {
+    return this.metadata.list(options);
+  }
+  /** Return a directory with its complete subtree. See `MetadataReadMode` for how `mode` uses the metadata cache. */
+  tree(options) {
+    return this.metadata.tree(options);
+  }
+  mkdir(options) {
+    return this.metadata.mkdir(options);
+  }
+  rename(options) {
+    return this.metadata.rename(options);
+  }
+  move(options) {
+    return this.metadata.move(options);
+  }
+  copy(options) {
+    return this.metadata.copy(options);
+  }
+  delete(options) {
+    return this.metadata.delete(options);
+  }
+  /** Clear the metadata cache of one workspace, or of every workspace when none is given. */
+  clearMetadataCache(selector) {
+    return this.metadata.clearCache(selector);
+  }
   /** Create a stable resource object for one file in this or another workspace. */
   file(locator) {
     return new MountraFile(
@@ -2055,6 +3070,7 @@ var MountraClient = class {
     if (finished.finish_status !== "completed") {
       throw new Error(`Mountra upload did not finish successfully: ${finished.finish_status}`);
     }
+    await this.metadata.recordUpload(this.cacheWorkspace(options), finished);
     await this.downloader.cacheUploadedFile(
       this.cacheWorkspace(options),
       {
@@ -2257,6 +3273,7 @@ var MountraClient = class {
       })
     );
     if (finished.finish_status === "completed") {
+      await this.metadata.recordUpload(this.cacheWorkspace(selector), finished);
       await this.downloader.invalidateCachedFile(this.cacheWorkspace(selector), {
         path: finished.path,
         ...finished.ino !== void 0 ? { ino: finished.ino } : {}
@@ -2312,8 +3329,10 @@ export {
   InMemoryDownloadCacheStore,
   InMemoryDownloadCheckpointStore,
   InMemoryJumboChunkCheckpointStore,
+  InMemoryMetadataCacheStore,
   IndexedDBDownloadCacheStore,
   IndexedDBDownloadCheckpointStore,
+  IndexedDBMetadataCacheStore,
   JUMBO_CHUNK_THRESHOLD_BYTES,
   LocalStorageJumboChunkCheckpointStore,
   MAX_S3_MULTIPART_PARTS,