filesystem-path

FilesystemPath class

A utility class, like native Date, that provides a fluent interface over strings representing paths on a computer filesystem. Better than doing string surgery.

Does not actually touch the filesystem.

Installation and usage

Install from npm:

npm install filesystem-path

Import and use the class:

const FilesystemPath = require('filesystem-path')

let home = new FilesystemPath('/Users/tomprogers')
//> '/Users/tomprogers'

home.setFilename('.npmrc')
//> '/Users/tomprogers/.npmrc'

home.setDirectory('/Users/tomprogers/projects/filesystem-path')
//> '/Users/tomprogers/projects/filesystem-path/.npmrc'

Anatomy of a FilesystemPath

The FilesystemPath class provides methods for accessing and mutating specific portions of a path by name. The parts are:

/Users/tomprogers/projects/filesystem─path/README.md
└──────────────────────────────────────────────────┴   path

/Users/tomprogers/projects/filesystem─path/README.md
└────────────────────────────────────────┴             directory

/Users/tomprogers/projects/filesystem─path/README.md
 └───┘ └────────┘ └──────┘ └─────────────┘ └───────┴   segments (array)

/Users/tomprogers/projects/filesystem─path/README.md
 └───┘ └────────┘ └──────┘ └─────────────┴             folders (array)

/Users/tomprogers/projects/filesystem─path/README.md
                                           └───────┴   filename

/Users/tomprogers/projects/filesystem─path/README.md
                                           └────┴      basename

/Users/tomprogers/projects/filesystem─path/README.md
                                                 └─┴   ext (incl. dot)

/Users/tomprogers/projects/filesystem─path/README.md
└                                                      root (the slash)

Thus, for the example path:

Part	Value
root	"/"
folders	[ "Users", "tomprogers", "projects", "filesystem─path" ]
segments	[ "Users", "tomprogers", "projects", "filesystem─path", "README.md" ]
directory	"/Users/tomprogers/projects/filesystem-path"
filename	"README.md"
basename	"README"
ext	".md"

^{Note: this library deliberately uses the terms "basename" and "filename" opposite the *nix convention, which I've always felt is obviously counterintuitive. Here, the "base" plus the "extension" yields the full "filename."}

API

Construction

The FilesystemPath constructor supports a few signatures:

• new FilesystemPath( path )

This is the easiest way, but it forces the parser to guess what the directory separator is, and whether the final segment names a directory or a file. This can produce bad results in some cases.

Here, the parser misinterprets the final path segment as a filename because the final segment has a dotted suffix that looks like a file extension, and because no hints are provided to suggest otherwise:

// `/etc/pam.d` is a directory on *nix systems that houses PAM stuff, not a file
new FilesystemPath('/etc/pam.d')
//> directory='/etc'   filename='pam.d'

• new FilesystemPath( directory, filename, sep )

Specifies everything unambiguously, guaranteed to produce an instance that behaves correctly.

new FilesystemPath( '/Users/tomprogers/projects/filesystem-path', 'README.md', '/' )

Argument order is important, but all three arguments are optional, so all these also work:

• new FilesystemPath( path, sep )
• new FilesystemPath( directory, filename )
• new FilesystemPath( filename )
• new FilesystemPath( filename, sep )
• new FilesystemPath( sep )

Instance methods

Every instance has methods for getting and setting the different parts of the path. Generally speaking, every getter returns a String, and every setter returns the mutated instance (to support chaining).

• getAbsolute() : Boolean - reflects whether the path begins with separator
• getBasename() : String - returns the basename
• getDirectory() : String - returns the directory, without trailing slash
• getExt() : String - returns the ext, if any, including leading dot
• getFilename() : String - returns the filename
• getFolders() : Array<String> - returns mutable list of directories
• getRoot() : String - returns sep if path is absolute, empty string otherwise
• getSegments() : Array<String> - returns read-only list of directories plus filename
• getSep() : String - returns the sep
• setAbsolute( newAbsolute ) : FilesystemPath - set whether the path is absolute
• setBasename( newBasename ) : FilesystemPath - overwrite the basename
• setDirectory( newDirectory ) : FilesystemPath - overwrite everything except the filename
• setExt( newExt ) : FilesystemPath - overwrite the ext; leading dot optional (will be added if needed)
• setFilename( newFilename ) : FilesystemPath - overwrite the entire filename
• setFolders( newFolders ) : FilesystemPath - overwrite the entire list of directories
• setRoot( newRoot ) : FilesystemPath - overwrite the leading sep
• setSegments( newSegments ) : FilesystemPath - overwrite all directories and filename, but not the root
• setSep( newSep ) : FilesystemPath - change the path's sep; only accepts back- and forward-slash
• toString() : String - returns the complete path as a string