From CommonJS Spec Wiki
Jump to: navigation, search

Filesystem Class Hierarchy

This proposal aims to create a set of classes (in an OOP sense) which would add some structuring (and taxonomy) to the Filesystem API. I believe that this can (and should) be done prior to standardizing every available method, including their names, arguments, return values and exceptions thrown.


Top-level class is a Path. This object (var path = new Path("/etc")) represents a generic path in a filesystem hierarchy. We are not aware of the underlying representation's properties, type (file/dir/link/pipe/socket/whatever), existence etc. Path acts as an ancestor, offering methods which are commot to all fielsystem objects. For instance, we might have path.exists(), path.isFile(), path.stat(), path.join("/passwd"), path.delete() and so on.

Then, we have a File. This class extends Path by adding methods which are specific to files; most notable methods for creation, reading and writing. Similarly, we have a Directory - File's sibling - which adds (to the Path parent) methods useful for Directory traversal and creation.

One can freely extend this, for instance by creating a Symlink class - its parent would be File. Symlink might offer additional funcionality - methods symlink.follow(), symlink.edit() etc.

Note that neither of these objects guarantees the existence of its underlying filesystem representation.


  1. var data = new File("/etc/passwd").open("r").read();
  2. var data = new Directory("/etc").listFiles();
  3. var path = new Path("/home").join("ondras");
  4. var path = new Path("/a/b/c");
    if (path.isDirectory()) { doSomething(); }


There are still several points in this proposal which make me uncomfortable. Perhaps a different point of view or a discussion can make things clear in this area.

  • It is unclear how should one convert between various Filesystem-related classes. Two solutions come to my mind:
    1. var dir = new Path("/etc").toDirectory();
    2. var dir = new Directory(new Path("/etc/"));

Both are problematic. The first one states that a Path should offer toXXX() methods, which is incorrect - as a top class, Path should not depend on existence of any of its descendants. The second way, on the other hand, is less readable.

  • It is unclear how moving, copying and removing should be implemented. In my original proposal, these are methods of Path object. However, as the real file/directory manipulation might be (in some way) specific to the object in question, it seems logical to have these implemented in each movable/copyable/removable class.