@bytecodealliance/preview3-shim 0.1.2 → 0.2.1

package/lib/nodejs/filesystem/descriptor.js

@@ -1,1093 +0,0 @@
-import fs from "node:fs/promises";
-import nodePath from "node:path";
-import process from "node:process";
-
-import { StreamReader, readableByteStreamFromReader } from "../stream.js";
-import { FutureReader } from "../future.js";
-import { ResourceWorker } from "../workers/resource-worker.js";
-import { earlyDispose, registerDispose } from "../finalization.js";
-
-import { FSError } from "./error.js";
-import { wasiTypeFromDirent } from "./utils.js";
-
-const symbolDispose = Symbol.dispose || Symbol.for("dispose");
-
-let WORKER = null;
-function worker() {
-  return (WORKER ??= new ResourceWorker(
-    new URL("../workers/filesystem-worker.js", import.meta.url),
-  ));
-}
-
-class Descriptor {
-  /** Node.js file handle for file operations (FileHandle from fs.promises.open) */
-  #handle;
-  /** Descriptor flags */
-  #mode;
-  /** Absolute filesystem path to the file or directory */
-  #fullPath;
-  /** Cleanup finalizer */
-  #finalizer;
-  /** Host filesystem path for preopened directories */
-  #hostPreopen;
-  /** Whether this descriptor refers to a directory. */
-  #isDirectory = false;
-
-  static _create(handle, mode, fullPath, isDirectory = false) {
-    const {
-      read = false,
-      write = false,
-      fileIntegritySync = false,
-      dataIntegritySync = false,
-      requestedWriteSync = false,
-      mutateDirectory = false,
-    } = mode;
-
-    const merged = {
-      read,
-      write,
-      fileIntegritySync,
-      dataIntegritySync,
-      requestedWriteSync,
-      mutateDirectory,
-    };
-
-    const desc = new Descriptor();
-    desc.#handle = handle;
-    desc.#fullPath = fullPath;
-    desc.#isDirectory = isDirectory;
-    desc.#mode = merged;
-    desc.#finalizer = registerDispose(desc, null, handle, (handle) => handle.close());
-
-    return desc;
-  }
-
-  static _createPreopen(hostPreopen) {
-    const desc = new Descriptor();
-    desc.#isDirectory = true;
-    desc.#mode = {
-      read: true,
-      write: false,
-      fileIntegritySync: false,
-      dataIntegritySync: false,
-      requestedWriteSync: false,
-      mutateDirectory: true,
-    };
-
-    if (hostPreopen.endsWith("/")) {
-      desc.#hostPreopen = hostPreopen.slice(0, -1) || "/";
-    } else {
-      desc.#hostPreopen = hostPreopen;
-    }
-
-    // Windows requires UNC paths at minimum
-    if (process.platform === "win32") {
-      desc.#hostPreopen = desc.#hostPreopen.replace(/\\/g, "/");
-      if (desc.#hostPreopen === "/") {
-        desc.#hostPreopen = "//";
-      }
-    }
-    return desc;
-  }
-
-  [symbolDispose]() {
-    if (this.#finalizer) {
-      earlyDispose(this.#finalizer);
-      this.#finalizer = null;
-    }
-    this.#handle = null;
-  }
-
-  /**
-   * Return a stream for reading from a file.
-   * WIT:
-   * ```
-   * read-via-stream: func(offset: filesize) -> tuple<stream<u8>, future<result<_, error-code>>>
-   * ```
-   *
-   * @param {bigint} offset The offset within the file.
-   * @returns {{stream: StreamReader, future: FutureReader}}
-   *   A tuple: a readable byte stream and a future that resolves to an error code.
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  readViaStream(offset) {
-    this.#ensureHandle();
-    const transform = new TransformStream();
-    const promise = worker()
-      .run(
-        {
-          op: "read",
-          fd: this.#handle.fd,
-          offset,
-          stream: transform.writable,
-        },
-        [transform.writable],
-      )
-      .catch((err) => {
-        throw FSError.from(err);
-      });
-
-    return [new StreamReader(transform.readable), new FutureReader(promise)];
-  }
-
-  /**
-   * Write to a file via a byte stream.
-   * WIT:
-   * ```
-   * write-via-stream: async func(data: stream<u8>, offset: filesize) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {object} data A readable byte stream.
-   * @param {bigint} offset The offset within the file.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async writeViaStream(data, offset) {
-    this.#ensureWritable(data);
-    const stream = readableByteStreamFromReader(data, { name: "file write data" });
-
-    try {
-      await worker().run({ op: "write", fd: this.#handle.fd, offset, stream }, [stream]);
-    } catch (err) {
-      throw FSError.from(err);
-    }
-  }
-
-  /**
-   * Append to a file via a byte stream.
-   * WIT:
-   * ```
-   * append-via-stream: async func(data: stream<u8>) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {object} data A readable byte stream.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async appendViaStream(data) {
-    this.#ensureWritable(data);
-    const offset = await this.#handle.stat().then((s) => s.size);
-    return this.writeViaStream(data, offset);
-  }
-
-  /**
-   * Advisory on file access patterns.
-   * WIT:
-   * ```
-   * advise: async func(offset: filesize, length: filesize, advice: advice) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {bigint} offset Start of the region.
-   * @param {bigint} length Length of the region.
-   * @param {string} advice One of the Wasi `advice` values.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async advise(_offset, _length, _advice) {
-    // TODO: This not directly suported on Node.js:
-    // https://github.com/bytecodealliance/jco/issues/718
-    if ((await this.getType()).tag === "directory") {
-      throw new FSError("bad-descriptor");
-    }
-  }
-
-  /**
-   * Synchronize file data to disk.
-   * WIT:
-   * ```
-   * sync-data: async func() -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async syncData() {
-    this.#ensureHandle();
-    try {
-      await this.#handle.datasync();
-    } catch (e) {
-      // On windows, `sync_data` uses `FileFlushBuffers` which fails with `EPERM` if
-      // the file is not upen for writing. Ignore this error, for POSIX compatibility.
-      if (process.platform === "win32" && e.code === "EPERM") {
-        return;
-      }
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Get flags associated with a descriptor.
-   * WIT:
-   * ```
-   * get-flags: async func() -> result<descriptor-flags, error-code>
-   * ```
-   *
-   * @async
-   * @returns {Promise<object>} The descriptor flags object.
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async getFlags() {
-    return this.#mode;
-  }
-
-  /**
-   * Get the dynamic type of a descriptor.
-   * WIT:
-   * ```
-   * get-type: async func() -> result<descriptor-type, error-code>
-   * ```
-   *
-   * @async
-   * @returns {Promise<string>} The descriptor type.
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async getType() {
-    if (this.#hostPreopen) {
-      return { tag: "directory" };
-    }
-    try {
-      const stats = await this.#handle.stat();
-      return wasiTypeFromDirent(stats);
-    } catch (e) {
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Adjust the size of an open file.
-   * WIT:
-   * ```
-   * set-size: async func(size: filesize) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {bigint} size The new size.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async setSize(size) {
-    this.#ensureHandle();
-
-    if (size > Number.MAX_SAFE_INTEGER) {
-      throw new FSError("invalid");
-    }
-
-    try {
-      await this.#handle.truncate(Number(size));
-    } catch (e) {
-      if (process.platform === "win32" && e.code === "EPERM") {
-        throw new FSError("access");
-      }
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Adjust the timestamps of an open file or directory.
-   * WIT:
-   * ```
-   * set-times: async func(data-access-timestamp: new-timestamp, data-modification-timestamp: new-timestamp) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {object} atimeDesc new-timestamp descriptor
-   * @param {object} mtimeDesc new-timestamp descriptor
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async setTimes(atimeDesc, mtimeDesc) {
-    this.#ensureHandle();
-
-    const { atime, mtime } = await this.#computeTimestamps(atimeDesc, mtimeDesc);
-
-    try {
-      await this.#handle.utimes(atime, mtime);
-    } catch (e) {
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Read directory entries via a stream.
-   * WIT:
-   * ```
-   * read-directory: async func() -> tuple<stream<directory-entry>, future<result<_, error-code>>>
-   * ```
-   *
-   * @async
-   * @returns {{stream: StreamReader, future: FutureReader}}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  readDirectory() {
-    const fullPath = this.#fullPath ?? this.#hostPreopen;
-    if (!fullPath) {
-      throw new FSError("invalid");
-    }
-
-    const preopens = preopenEntries.map(([desc, _virtualPath]) => desc.#hostPreopen);
-
-    const transform = new TransformStream();
-    const promise = worker()
-      .run(
-        {
-          op: "readDir",
-          fullPath,
-          stream: transform.writable,
-          preopens,
-        },
-        [transform.writable],
-      )
-      .catch((err) => {
-        throw FSError.from(err);
-      });
-
-    return [new StreamReader(transform.readable), new FutureReader(promise)];
-  }
-
-  /**
-   * Synchronize data & metadata to disk.
-   * WIT:
-   * ```
-   * sync: async func() -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async sync() {
-    return this.#hostPreopen ? this.#syncDir() : this.#syncFile();
-  }
-
-  /**
-   * Create a directory.
-   * WIT:
-   * ```
-   * create-directory-at: async func(path: string) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {string} path Relative path.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async createDirectoryAt(path) {
-    await this.#ensureSandboxedPath(path);
-    const full = this.#getFullPath(path, false);
-    try {
-      await fs.mkdir(full);
-    } catch (e) {
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Return attributes of an open file or directory.
-   * WIT:
-   * ```
-   * stat: async func() -> result<descriptor-stat, error-code>
-   * ```
-   *
-   * @async
-   * @returns {Promise<object>} File statistics.
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async stat() {
-    try {
-      let s;
-      if (this.#hostPreopen) {
-        s = await fs.stat(this.#hostPreopen, { bigint: true });
-      } else {
-        this.#ensureHandle();
-        s = await this.#handle.stat({ bigint: true });
-      }
-
-      return {
-        type: wasiTypeFromDirent(s),
-        linkCount: s.nlink,
-        size: s.size,
-        dataAccessTimestamp: nsToDateTime(s.atimeNs),
-        dataModificationTimestamp: nsToDateTime(s.mtimeNs),
-        statusChangeTimestamp: nsToDateTime(s.ctimeNs),
-      };
-    } catch (e) {
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Adjust timestamps on a file or symlink.
-   * WIT:
-   * ```
-   * set-times-at: async func(
-   *   path-flags: path-flags,
-   *   path: string,
-   *   data-access-timestamp: new-timestamp,
-   *   data-modification-timestamp: new-timestamp
-   * ) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {object} flags Path flags.
-   * @param {string} path Relative path.
-   * @param {object} atimeDesc New access timestamp.
-   * @param {object} mtimeDesc New modification timestamp.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async statAt(flags, path) {
-    await this.#ensureSandboxedPath(path);
-    const full = this.#getFullPath(path, flags.symlinkFollow);
-    try {
-      const statFn = flags.symlinkFollow ? fs.stat : fs.lstat;
-      const s = await statFn(full, { bigint: true });
-      return {
-        type: wasiTypeFromDirent(s),
-        linkCount: s.nlink,
-        size: s.size,
-        dataAccessTimestamp: nsToDateTime(s.atimeNs),
-        dataModificationTimestamp: nsToDateTime(s.mtimeNs),
-        statusChangeTimestamp: nsToDateTime(s.ctimeNs),
-      };
-    } catch (e) {
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Adjust timestamps on a file or symlink.
-   * WIT:
-   * ```
-   * set-times-at: async func(
-   *   path-flags: path-flags,
-   *   path: string,
-   *   data-access-timestamp: new-timestamp,
-   *   data-modification-timestamp: new-timestamp
-   * ) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {object} flags Path flags.
-   * @param {string} path Relative path.
-   * @param {object} atimeDesc New access timestamp.
-   * @param {object} mtimeDesc New modification timestamp.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async setTimesAt(flags, path, atimeDesc, mtimeDesc) {
-    await this.#ensureSandboxedPath(path);
-    const { atime, mtime } = await this.#computeTimestamps(atimeDesc, mtimeDesc, path);
-
-    if (!flags.symlinkFollow && !fs.lutimes) {
-      throw new FSError("unsupported");
-    }
-
-    const full = this.#getFullPath(path, flags.symlinkFollow);
-
-    try {
-      const utimesFn = flags.symlinkFollow ? fs.utimes : fs.lutimes;
-      await utimesFn(full, atime, mtime);
-    } catch (e) {
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Create a hard link.
-   * WIT:
-   * ```
-   * link-at: async func(
-   *   old-path-flags: path-flags,
-   *   old-path: string,
-   *   new-descriptor: borrow<descriptor>,
-   *   new-path: string
-   * ) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {object} oldFlags Old path flags.
-   * @param {string} oldPath Source path.
-   * @param {Descriptor} newDesc Target descriptor.
-   * @param {string} newPath Destination path.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async linkAt(oldFlags, oldPath, newDesc, newPath) {
-    await this.#ensureSandboxedPath(oldPath);
-    await newDesc.#ensureSandboxedPath(newPath);
-    const src = this.#getFullPath(oldPath, oldFlags.symlinkFollow);
-    const dst = newDesc.#getFullPath(newPath, false);
-
-    // On Windows, a trailing '/' means the path is treated as a
-    // directory and hard links to directory are not supported
-    if (process.platform === "win32" && dst.endsWith("/")) {
-      throw new FSError("no-entry");
-    }
-
-    try {
-      await fs.link(src, dst);
-    } catch (e) {
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Open a file or directory.
-   * WIT:
-   * ```
-   * open-at: async func(
-   *   path-flags: path-flags,
-   *   path: string,
-   *   open-flags: open-flags,
-   *   %flags: descriptor-flags
-   * ) -> result<descriptor, error-code>
-   * ```
-   *
-   * @async
-   * @param {object} pf - path flags
-   * @param {string} path - relative path
-   * @param {object} of - open flags
-   * @param {object} df - descriptor flags
-   * @returns {Promise<Descriptor>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async openAt(pf, path, of, df) {
-    if (!preopenEntries.length) {
-      throw new FSError("access");
-    }
-
-    await this.#ensureSandboxedPath(path);
-    const fullPath = this.#getFullPath(path, pf.symlinkFollow);
-    const target = stripTrailingSlash(fullPath);
-
-    const mode = {
-      ...df,
-      read: df.read || !df.write,
-      write: df.write || of.create || of.truncate,
-    };
-
-    const makeFsFlags = () => {
-      let fsFlags = 0;
-      if (of.create) {
-        fsFlags |= fs.constants.O_CREAT;
-      }
-      if (of.directory) {
-        fsFlags |= fs.constants.O_DIRECTORY;
-      }
-      if (of.exclusive) {
-        fsFlags |= fs.constants.O_EXCL;
-      }
-      if (of.truncate) {
-        fsFlags |= fs.constants.O_TRUNC;
-      }
-      if (mode.read && mode.write) {
-        fsFlags |= fs.constants.O_RDWR;
-      } else if (mode.write) {
-        fsFlags |= fs.constants.O_WRONLY;
-      } else if (mode.read) {
-        fsFlags |= fs.constants.O_RDONLY;
-      }
-      if (df.fileIntegritySync) {
-        fsFlags |= fs.constants.O_SYNC;
-      }
-      if (df.requestedWriteSync) {
-        fsFlags |= fs.constants.O_SYNC;
-      }
-      if (df.dataIntegritySync) {
-        fsFlags |= fs.constants.O_DSYNC;
-      }
-      if (!pf.symlinkFollow) {
-        fsFlags |= fs.constants.O_NOFOLLOW;
-      }
-      return fsFlags;
-    };
-
-    const fsFlags = makeFsFlags();
-
-    if (process.platform === "win32") {
-      if (!pf.symlinkFollow && !of.create) {
-        const isSymlink = await fs
-          .lstat(fullPath)
-          .then((p) => p.isSymbolicLink())
-          .catch(() => false);
-
-        if (isSymlink) {
-          const tag = of.directory ? "not-directory" : "loop";
-          throw new FSError(tag);
-        }
-      }
-
-      if (pf.symlinkFollow && of.directory) {
-        const isFile = await fs
-          .stat(fullPath)
-          .then((p) => !p.isDirectory())
-          .catch(() => false);
-
-        if (isFile) {
-          throw new FSError("not-directory");
-        }
-      }
-    }
-
-    try {
-      const handle = await fs.open(target, fsFlags);
-      const stats = await handle.stat();
-      const isDir = stats.isDirectory();
-      const desc = descriptorCreate(handle, mode, fullPath, isDir);
-
-      if (fullPath.endsWith("/") && !isDir) {
-        desc[symbolDispose]();
-        throw new FSError("not-directory");
-      }
-      return desc;
-    } catch (err) {
-      if (err.code === "ERR_INVALID_ARG_VALUE") {
-        throw new FSError(process.platform === "win32" ? "no-entry" : "invalid");
-      }
-      throw FSError.from(err);
-    }
-  }
-
-  /**
-   * Read the contents of a symbolic link.
-   * WIT:
-   * ```
-   * readlink-at: async func(path: string) -> result<string, error-code>
-   * ```
-   *
-   * @async
-   * @param {string} path Relative path.
-   * @returns {Promise<string>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async readlinkAt(path) {
-    await this.#ensureSandboxedPath(path);
-    const full = this.#getFullPath(path, false);
-    try {
-      return await fs.readlink(full);
-    } catch (e) {
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Remove a directory.
-   * WIT:
-   * ```
-   * remove-directory-at: async func(path: string) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {string} path Relative path.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async removeDirectoryAt(path) {
-    if (path === ".") {
-      throw new FSError("invalid");
-    }
-    await this.#ensureSandboxedPath(path);
-    const full = this.#getFullPath(path, false);
-    try {
-      await fs.rmdir(full);
-    } catch (e) {
-      if (process.platform === "win32" && e.code === "ENOENT") {
-        throw new FSError("not-directory");
-      }
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Rename a filesystem object.
-   * WIT:
-   * ```
-   * rename-at: async func(old-path: string, new-descriptor: borrow<descriptor>, new-path: string) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {string} oldPath Source path.
-   * @param {Descriptor} newDesc Target descriptor.
-   * @param {string} newPath Destination path.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async renameAt(oldPath, newDesc, newPath) {
-    await this.#ensureSandboxedPath(oldPath);
-    await newDesc.#ensureSandboxedPath(newPath);
-    const src = this.#getFullPath(oldPath, false);
-    const dst = newDesc.#getFullPath(newPath, false);
-    try {
-      await fs.rename(src, dst);
-    } catch (e) {
-      if (process.platform === "win32" && e.code === "EPERM") {
-        throw new FSError("access");
-      }
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Create a symbolic link.
-   * WIT:
-   * ```
-   * symlink-at: async func(old-path: string, new-path: string) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {string} target Link target.
-   * @param {string} path Destination path.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async symlinkAt(target, path) {
-    if (target.startsWith("/")) {
-      throw new FSError("not-permitted");
-    }
-    await this.#ensureSandboxedPath(path);
-    const full = this.#getFullPath(path, false);
-
-    try {
-      await fs.symlink(target, full);
-    } catch (e) {
-      if (full.endsWith("/") && e.code === "EEXIST") {
-        const isDir = (await fs.stat(full)).isDirectory();
-        const isWin = process.platform === "win32";
-        if (!isDir) {
-          const tag = isWin ? "no-entry" : "not-directory";
-          throw new FSError(tag);
-        }
-      }
-
-      if (process.platform === "win32" && ["EPERM", "EEXIST"].includes(e.code)) {
-        throw new FSError("no-entry");
-      }
-
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Unlink a filesystem object that is not a directory.
-   * WIT:
-   * ```
-   * unlink-file-at: async func(path: string) -> result<_, error-code>
-   * ```
-   *
-   * @async
-   * @param {string} path Relative path.
-   * @returns {Promise<void>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async unlinkFileAt(path) {
-    await this.#ensureSandboxedPath(path);
-    const full = this.#getFullPath(path, false);
-    if (full.endsWith("/")) {
-      const isDir = (await fs.stat(full)).isDirectory();
-      if (isDir) {
-        if (process.platform === "win32") {
-          throw new FSError("access");
-        } else if (process.platform === "darwin") {
-          throw new FSError("not-permitted");
-        } else {
-          throw new FSError("is-directory");
-        }
-      }
-    }
-
-    try {
-      await fs.unlink(full);
-    } catch (err) {
-      if (process.platform === "win32" && err.code === "EPERM") {
-        throw new FSError("access");
-      } else {
-        throw FSError.from(err);
-      }
-    }
-  }
-
-  /**
-   * Test whether two descriptors refer to the same object.
-   * WIT:
-   * ```
-   * is-same-object: async func(other: borrow<descriptor>) -> bool
-   * ```
-   *
-   * @async
-   * @param {Descriptor} other Another descriptor.
-   * @returns {Promise<boolean>}
-   */
-  async isSameObject(other) {
-    const [left, right] = await Promise.all([this.#statForIdentity(), other.#statForIdentity()]);
-    return left.dev === right.dev && left.ino === right.ino;
-  }
-
-  /**
-   * Return a hash of the metadata associated with this descriptor.
-   * WIT:
-   * ```
-   * metadata-hash: async func() -> result<metadata-hash-value, error-code>
-   * ```
-   *
-   * @async
-   * @returns {Promise<{upper: bigint, lower: bigint}>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async metadataHash() {
-    try {
-      const s = await this.#statForIdentity();
-      return { upper: s.mtimeNs, lower: s.ino };
-    } catch (e) {
-      throw FSError.from(e);
-    }
-  }
-
-  /**
-   * Return a hash of the metadata via path.
-   * WIT:
-   * ```
-   * metadata-hash-at: async func(path-flags: path-flags, path: string) -> result<metadata-hash-value, error-code>
-   * ```
-   *
-   * @async
-   * @param {object} flags Path flags.
-   * @param {string} path Relative path.
-   * @returns {Promise<{upper: bigint, lower: bigint}>}
-   * @throws {FSError} `payload.tag` contains mapped WASI error code.
-   */
-  async metadataHashAt(flags, path) {
-    await this.#ensureSandboxedPath(path);
-    const full = this.#getFullPath(path, false);
-    try {
-      const statFn = flags.symlinkFollow ? fs.stat : fs.lstat;
-      const s = await statFn(full, { bigint: true });
-      return { upper: s.mtimeNs, lower: s.ino };
-    } catch (e) {
-      throw FSError.from(e);
-    }
-  }
-
-  async #syncDir() {
-    try {
-      const handle = await fs.open(this.#hostPreopen, fs.constants.O_RDONLY);
-      try {
-        await handle.sync();
-      } finally {
-        await handle.close();
-      }
-    } catch (e) {
-      throw FSError.from(e);
-    }
-  }
-
-  async #syncFile() {
-    this.#ensureHandle();
-    try {
-      await this.#handle.sync();
-    } catch (e) {
-      // On windows, `sync_data` uses `FileFlushBuffers` which fails with `EPERM` if
-      // the file is not upen for writing. Ignore this error, for POSIX compatibility.
-      if (process.platform === "win32" && e.code === "EPERM") {
-        return;
-      }
-      throw FSError.from(e);
-    }
-  }
-
-  #getNewTimestamp(newTimestamp, oldTimestamp) {
-    switch (newTimestamp.tag) {
-      case "now":
-        return Math.floor(Date.now() / 1e3);
-      case "no-change":
-        return timestampToSec(oldTimestamp);
-      case "timestamp":
-        return timestampToSec(newTimestamp.val);
-      default:
-        throw new FSError("invalid", `Unknown new-timestamp tag: ${newTimestamp.tag}`);
-    }
-  }
-
-  async #computeTimestamps(atimeDesc, mtimeDesc, path = null) {
-    let stats;
-    if (atimeDesc.tag === "no-change" || mtimeDesc.tag === "no-change") {
-      const flags = { symlinkFollow: true };
-      const p = path === null ? this.stat() : this.statAt(flags, path);
-      stats = await p;
-    }
-
-    const atime = this.#getNewTimestamp(atimeDesc, stats?.dataAccessTimestamp);
-    const mtime = this.#getNewTimestamp(mtimeDesc, stats?.dataModificationTimestamp);
-    return { atime, mtime };
-  }
-
-  /**
-   * Resolve a relative subpath against this descriptor.
-   */
-  #getFullPath(subpath, _followSymlinks) {
-    subpath = subpath.replaceAll("\\", "/").replace(/\/\/+/g, "/");
-
-    if (subpath === "") {
-      throw new FSError("no-entry");
-    }
-
-    if (subpath.startsWith("/")) {
-      throw new FSError("not-permitted");
-    }
-
-    const segments = [];
-    for (const seg of subpath.split("/")) {
-      if (seg === "" || seg === ".") {
-        continue;
-      }
-      if (seg === "..") {
-        if (segments.length === 0) {
-          throw new FSError("not-permitted");
-        }
-        segments.pop();
-      } else {
-        segments.push(seg);
-      }
-    }
-
-    const base = this.#hostPreopen ?? this.#fullPath;
-    if (segments.length === 0) {
-      return base;
-    }
-
-    const baseNormalized = stripTrailingSlash(base);
-    return `${baseNormalized}/${segments.join("/")}`;
-  }
-
-  async #statForIdentity() {
-    if (this.#hostPreopen) {
-      return fs.stat(this.#hostPreopen, { bigint: true });
-    }
-    this.#ensureHandle();
-    return this.#handle.stat({ bigint: true });
-  }
-
-  // WASI paths are always relative to a directory descriptor. During path
-  // resolution, both `..` and symlinks must not escape that descriptor's base.
-  async #ensureSandboxedPath(subpath) {
-    if (!this.#isDirectory) {
-      throw new FSError("not-directory");
-    }
-
-    const base = this.#hostPreopen ?? this.#fullPath;
-    const baseResolved = nodePath.resolve(base);
-    const segments = subpath.replaceAll("\\", "/").replace(/\/\/+/g, "/").split("/");
-    let current = baseResolved;
-
-    for (const seg of segments) {
-      if (seg === "" || seg === ".") {
-        continue;
-      }
-      if (seg === "..") {
-        current = nodePath.dirname(current);
-        if (!isWithinPath(baseResolved, current)) {
-          throw new FSError("not-permitted");
-        }
-        continue;
-      }
-
-      current = nodePath.join(current, seg);
-      let stat;
-      try {
-        stat = await fs.lstat(current);
-      } catch (err) {
-        if (err.code === "ENOENT") {
-          return;
-        }
-        throw FSError.from(err);
-      }
-
-      if (stat.isSymbolicLink()) {
-        const target = await fs.readlink(current);
-        current = nodePath.resolve(nodePath.dirname(current), target);
-        if (!isWithinPath(baseResolved, current)) {
-          throw new FSError("not-permitted");
-        }
-      }
-    }
-  }
-
-  #ensureHandle() {
-    if (!this.#handle) {
-      throw new FSError("bad-descriptor");
-    }
-  }
-
-  #ensureWritable(data) {
-    this.#ensureHandle();
-    if (!this.#mode.write) {
-      data?.[symbolDispose]?.();
-      data?.close?.();
-      throw new FSError("bad-descriptor");
-    }
-  }
-}
-
-const descriptorCreatePreopen = Descriptor._createPreopen;
-delete Descriptor._createPreopen;
-
-const descriptorCreate = Descriptor._create;
-delete Descriptor._create;
-
-const NS_PER_SEC = 1_000_000_000n;
-function nsToDateTime(ns) {
-  const seconds = ns / NS_PER_SEC;
-  const nanoseconds = Number(ns % NS_PER_SEC);
-  return { seconds, nanoseconds };
-}
-
-function timestampToSec({ seconds, nanoseconds }) {
-  return Number(seconds) + nanoseconds / 1e9;
-}
-
-function stripTrailingSlash(path) {
-  if (path === "/") {
-    return "/";
-  }
-  return path.replace(/\/+$/, "");
-}
-
-function isWithinPath(base, candidate) {
-  const relative = nodePath.relative(base, candidate);
-  return relative === "" || (!relative.startsWith("..") && !nodePath.isAbsolute(relative));
-}
-
-const preopenEntries = [];
-export const preopens = {
-  Descriptor,
-  getDirectories: () => preopenEntries,
-};
-
-export const types = {
-  Descriptor,
-};
-
-/**
- * Set the preopen table.
- *
- * @param {Record<string, string>} entries
- */
-export function _setPreopens(entries) {
-  preopenEntries.length = 0;
-  Object.entries(entries).forEach(([virtualPath, hostPreopen]) =>
-    _addPreopen(virtualPath, hostPreopen),
-  );
-}
-
-/**
- * Add a new preopen mapping.
- *
- * @param {string} virtualPath
- * @param {string} hostPreopen
- */
-export function _addPreopen(virtualPath, hostPreopen) {
-  preopenEntries.push([descriptorCreatePreopen(hostPreopen), virtualPath]);
-}