chore: refactor VFS interface and the OPFS implementation

[samwillis]

This refactor does two things:

1. simplifies and divides up the VFS interfaces
2. refactors the OPFS implementation to use it

There are now two fs base classes that implement the Filesystem interface:

• EmscriptenBuiltinFilesystem: used for the InMemory, IDB and Node files systems. They are a wrapper for the ones provided by Emscripten
• BaseFilesystem: An abstract class that can be used to implement a custom filesystem. This is used by the OPFS-AHP file system. It has a number of abstract methods (see below) that an implementing class would provided in order to fully implement a VFS. This is somewhat modelled on the Node FS interface, and abstracts the implementation details of the Emscripten FS.

With this we are close to the point we can document the FS interface and describe how to build as custom VFS. However, we should implement at least one more custom FS on top of this first to check we have everything correct.

abstract methods of BaseFilesystem:

  abstract chmod(path: string, mode: number): void
  abstract close(fd: number): void
  abstract fstat(fd: number): FsStats
  abstract lstat(path: string): FsStats
  abstract mkdir(
    path: string,
    options?: { recursive?: boolean; mode?: number },
  ): void
  abstract open(path: string, flags?: string, mode?: number): number
  abstract readdir(path: string): string[]
  abstract read(
    fd: number,
    buffer: Int8Array, // Buffer to read into
    offset: number, // Offset in buffer to start writing to
    length: number, // Number of bytes to read
    position: number, // Position in file to read from
  ): number
  abstract rename(oldPath: string, newPath: string): void
  abstract rmdir(path: string): void
  abstract truncate(
    path: string,
    len: number, // Length to truncate to - defaults to 0
  ): void
  abstract unlink(path: string): void
  abstract utimes(path: string, atime: number, mtime: number): void
  abstract writeFile(
    path: string,
    data: string | Int8Array,
    options?: { encoding?: string; mode?: number; flag?: string },
  ): void
  abstract write(
    fd: number,
    buffer: Int8Array, // Buffer to read from
    offset: number, // Offset in buffer to start reading from
    length: number, // Number of bytes to write
    position: number, // Position in file to write to
  ): number

[github-actions[bot]]

Built bundles:

• Postgres WASM: https://github.com/electric-sql/pglite/actions/runs/11241622417/artifacts/2031057338
• Interim build files: https://github.com/electric-sql/pglite/actions/runs/11241622417/artifacts/2031057494
• PGlite: https://github.com/electric-sql/pglite/actions/runs/11241622417/artifacts/2031085571
• Demos: https://github.com/electric-sql/pglite/actions/runs/11241622417/artifacts/2031100395

[github-actions[bot]]

🚀 Deployed on https://67057e14ccb9cc1db897d117--pglite.netlify.app