This package has been deprecated

Author message:

use rwd

flavored-path

Node.js project

"path" module revisited with backward compatibility and additional features

Version: 0.0.8

The goal of this module is to fix the current working directory issue, provide backward compatibility to the path.normalize() function (it's terribly bugged on Windows), provide forward compatibility with the path.sep, path.delimiter aliases and all future aditions and add additional useful methods.

This module uses meta-path to guarantee the backward compatibility. See its documentation to understand the problems and the fixes.

The primary intention is to use flavored-path as a complete replacement of the path built-in module.

Every time you call a fs built-in function I recommend to call to the get() function:

var fs = require ("fs");
var path = require ("flavored-path");
fs.exists (path.get ("my/path"), cb);

The get() function will take care all the possible types of path (relative, absolute, network shared resource and relative from the home directory on Linux) and fix, resolve or whatever they need in order to work as expected.

Installation

npm install flavored-path

Example

var fs = require ("fs");
var path = require ("flavored-path");
 
/*
path.get (".") is equivalent to __dirname but get() can be used with any type
of path, e.g.: Linux home paths (~/a/b).
 
On Linux, home paths are resolved to absolute files, so this snippet prints
all the entries in the user's home path.
 
On Windows, home paths are processed like regular relative paths, that is,
get() will return something like this: <cwd>/~/, so don't use ~ on Windows.
 
The Node.js built-in functions work the same way, for them ~ is processed
like a relative home path.
*/
 
fs.readdir (path.get ("~"), function (error, files){
    if (error) return console.log (error);
    console.log (files);
});

Methods and Properties

• path.basename(p[, ext])
• path.delimiter
• path.dirname(p)
• path.extname(p)
• path.get(p)
• path.isAbsolute(p)
• path.isHome(p)
• path.isNetwork(p)
• path.isRelative(p)
• path.isRoot(p)
• path.join(path1, path2[, ...])
• path.normalize(p)
• path.prefix(p)
• path.realpath(p)
• path.relative(from, to)
• path.removePrefix(p)
• path.resolve([from, [...]], to)
• path.sep

path.basename(p[, ext])
Same Node.js built-in function (path.basename()).

path.delimiter
Same Node.js built-in function (path.delimiter).

path.dirname(p)
Same Node.js built-in function (path.dirname()).

path.extname(p)
Same Node.js built-in function (path.extname()).

path.get(p)
Returns a path suitable for using with a fs built-in function. Every time you need to call to a fs function you can call to this function:

fs.exists (path.get ("a"), cb);

You can pass any type of path. It will be normalized, fixed, resolved, whatever modification to convert the given path to a valid path for using with any fs built-in function.

The path is normalized and if the script is executed from a different directory from where the main script it's executed, e.g. node a/app.js instead of node app.js, the path is also be fixed. Example:

//app.js
var path = require ("flavored-path");
console.log (path.get ("app.js"));

$ pwd
/home/gll
$ node a/app.js
a/app.js

If flavored-path it's used within a global module it makes no sense to try to fix a relative path because it's not needed. In this case the function only normalizes the path and returns it.

In fact, this function provides the same funcionality as the __dirname approach but also works in third-party modules whereas __dirname cannot be used in them.

path.isAbsolute(p)
Checks whether the path is absolute. An absolute path begins with / or \ (the prefix is skipped, e.g.: D:), this means that network paths are also absolute. The given path doesn't need to be normalized. Returns true if is absolute, false otherwise.

path.isHome(p)
Checks whether the path is relative from the user's home directory. A home path path begins with ~ (cannot contain a prefix), this means that home paths are also relative. The given path doesn't need to be normalized. Returns true if is a home path, false otherwise.

path.isNetwork(p)
Checks whether the path is a network resource (on Windows world this is called a UNC path). A network path begins with // or \\\\ (the prefix is skipped, e.g.: smb:). The given path doesn't need to be normalized. Returns true if is a network resource, false otherwise.

path.isRelative(p)
Checks whether the path is relative. A relative path begins with any character different from / or \ (the prefix is skipped, e.g.: D:). The given path doesn't need to be normalized. Returns true if is relative, false otherwise.

path.isRoot(p)
Checks whether the path is a root. A root path is equal to /, \, // or \\ (the prefix is skipped, e.g.: D:). The given path doesn't need to be normalized. Returns true if is a root path, false otherwise.

path.join(path1, path2[, ...])
Same Node.js built-in function (path.join()).

The joined path is correctly normalized.

console.log (path.join ("smb://a//b", "c/")); //Prints: smb://a/b/c/

path.normalize(p)
Same Node.js built-in function (path.normalize()).

Takes care all of the bugs found in the built-in normalize function explained in the meta-path module.

path.prefix(p)
Returns the prefix. The prefix is the string before : (included).

path.realpath(p)
An alias for the resolve() function. The real path of . it's the real current working directory with the relative fix applied.

/*
You can overwrite the built-in cwd function and cache the result.
Now, the process.cwd() function will always return the same path if
you move across the directories and execute a script from outside of its
directory, so you don't need to call to get():
 
$ node app.js
$ node dir/app.js
$ node ../app.js
*/
 
process.cwd = (function (){
    var cwd = path.realpath (".");
    return function (){
        return cwd;
    };
})();

This is an error prone solution because you're overwritting a built-in Node.js function, and you may have other modules that may stop working properly. Use with caution.

path.relative(from, to)
Same Node.js built-in function (path.relative()).

path.removePrefix(p)
Returns the path without the prefix.

path.resolve([from, [...]], to)
Same Node.js built-in function (path.resolve()).

The absolute path that is returned fixes the current working directory issue.

The Linux relative home paths are resolved to its absolute path (only on Linux). The resolve built-in function doesn't provide this functionality. The fs built-in functions don't expand ~ to the user's home path, so when you deal with home paths you must convert it first to an absolute path:

fs.exists (path.resolve ("~/a"), cb);
//Or simply:
//fs.exists (path.get ("~/a"), cb);

Network resource paths (paths that begin with //) are also resolved correctly.

Some examples:

//app.js
console.log (path.resolve ("b", "c")); //Prints: /home/gll/a/b/c
console.log (path.resolve ("s", "~/a")); //Prints: /home/gll/a
console.log (path.resolve ("s", "/a", "b")); //Prints: /a/b
console.log (path.resolve ("s", "//a", "b")); //Prints: //a/b

$ pwd
/home/gll
$ node a/app.js

path.sep
Same Node.js built-in property (path.sep).