Omnipath NPM | npm.io

☠ This package is no longer maintained ☠

OmniPath

A consolidated API for file paths and URLs

OmniPath is a single API that consolidates Node's native path and url modules, so you can write clean code without separate branches for different types of paths. It has all the methods you're familiar with (parse, format, join, resolve, cwd, dirname, basename, etc.), and they all support POSIX paths, Windows paths, UNC paths, and URLs.

You can use OmniPath.win32, OmniPath.posix, or OmniPath.url to treat paths a particular way, or you can just use OmniPath to automatically adjust based on the runtime environment.

Tested in Node and all modern web browsers on Mac, Windows, and Linux.

Example

// Returns an object with all properties of url.parse() AND path.parse()
OmniPath.parse(somePath);

// Calls url.resolve() or path.resolve(), as appropriate
OmniPath.resolve(somePath, someOtherPath);

// Joins paths or URLs, using the appropriate separator
OmniPath.join(somePath, someOtherPath);

// Works just like path.dirname(), even for URLs
OmniPath.dirname(somePath);

// Works just like path.basename(), even for URLs
OmniPath.basename(somePath, ".html");

// Alternate Syntax: Create an OmniPath instance, then call its methods
var path = new OmniPath(somePath);
path.resolve(someOtherPath);
path.join(someOtherPath);
path.dirname();
path.basename(".html");
...

// OmniPath instances have all properties of url.parse() AND path.parse()
path.protocol;   // e.g. "http:", "file:", etc.
path.hostname;   // e.g. "www.google.com"
path.query;      // e.g. "name=Joe&age=45"
path.hash;       // e.g. "#page1"
path.dir;        // e.g. "/dir/subdir/subsubdir"
path.base;       // e.g. "index.html"
path.ext;        // e.g. ".html"
...

Installation

Node

Install using npm:

npm install omnipath

Then require it in your code:

var OmniPath = require('omnipath');

Web Browsers

Reference omnipath.js or omnipath.min.js in your HTML:

<script src="https://cdn.rawgit.com/JS-DevTools/omnipath/master/dist/omnipath.js"></script>
<script>
    OmniPath.resolve(somePath, someOtherPath);
</script>

API

`parse(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. This parameter will usually be a string, but can also be a Url object (from url.parse) or an existing OmniPath object.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: OmniPath object

Parses a path or URL string and returns an object with all the properties of url.parse AND path.parse.

If the path includes a protocol (e.g. "http://..., "file://...", etc.), then it will be parsed as a URL; otherwise, it will be parsed according to the runtime environment. That is, it will be parsed using path.win32 on Windows, it will be parsed using path.posix on Mac, Linux, SunOS, etc., and it will be parsed using url.parse when running in web browsers. If you want to use a particular parser regardless of the runtime environment, then call OmniPath.win32.parse(), OmniPath.posix.parse(), or OmniPath.url.parse() instead.

OmniPath.parse("http://server.com/dir/subdir/file.html");
OmniPath.parse("C:\\dir\\subdir\\file.html");
OmniPath.parse("/dir/subdir/file.html#page1", {allowFileHash: true});

`format(path, [options])`

path (required) - Url or OmniPath A parsed OmniPath object. Can also be a Url object (from url.parse)
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: string

The opposite of parse. Returns a formatted string from a parsed object. Just like path.format or url.format.

Just like Node's path.format and url.format methods, OmniPath.format does not normalize the path, so it is possible to get results with redundant/mixed slashes, as well as "." and ".." sequences. Use normalize instead if you want to ensure that the result is well-formatted.

var p = OmniPath.parse("C:\\dir\\subdir\\file.html");
var u = url.parse("http://server.com/dir/subdir/file.html");

OmniPath.format(p);        // => "C:\\dir\\subdir\\file.html"
OmniPath.format(u);        // => "http://server.com/dir/subdir/file.html"

`formatPart(path, part, [options])`

path (required) - Url or OmniPath A parsed OmniPath object. Can also be a Url object (from url.parse)
part (required) - string The name of the rightmost part to include in the returned string. For example, "protocol" will only return the protocol part, whereas "port" will return the protocol, slashes, auth, hostname, and port.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: string

OmniPath.formatPart("http://server.com:8080/dir/file.html", "hostname");  // => "http://server.com"
OmniPath.formatPart("http://server.com:8080/dir/file.html", "host");      // => "http://server.com:8080"
OmniPath.formatPart("http://server.com:8080/dir/file.html", "dir");       // => "http://server.com:8080/dir"
OmniPath.formatPart("C:\\dir\\subdir\\file.html", "pathname");            // => "C:\\dir\\subdir\\file.html"

`join(path1, path2, ..., [options])`

path1, path2, ... (optional) - string or Url or OmniPath The path parts to join. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: string

Joins multiple path segments together and normalizes the result. Just like path.join

OmniPath.join("http://server.com/dir", "..", "otherdir/file.html");  // => "http://server.com/otherdir/file.html"
OmniPath.join("C:\\", "dir/subdir", "\\file.html");                  // => "C:\\dir\\subdir\\file.html"
OmniPath.join("../dir", "./subdir", "..", "/file.html");             // => "../dir/file.html"

`resolve(from..., to, [options])`

from... (optional) - string or Url or OmniPath The paths used to resolve to. See parse for details.
to (required) - string or Url or OmniPath The path to resolve. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: string

Resolves to to an absolute path. Just like path.resolve

If to isn't already absolute, from arguments are prepended in right to left order, until an absolute path is found. If after using all from paths still no absolute path is found, OmniPath.cwd is used as well

OmniPath.resolve("http://server.com/dir", "otherdir/file.html");  // => "http://server.com/otherdir/file.html"
OmniPath.resolve("C:\\", "dir\\subdir", "\\file.html");           // => "C:\\file.html"

`normalize(path, [options])`

path (required) - string or Url or OmniPath The path to be normalized. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: string

Normalizes a path, taking care of .. and ., and removing duplicate path separators. Just like path.normalize

OmniPath.normalize("http://server.com//dir/./subdir/..//otherdir/file.html");  // => "http://server.com/dir/otherdir/file.html"
OmniPath.normalize("C:\\dir\\.\\subdir\\..\\file.html");                       // => "C:\\dir\\file.html"

`dirname(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: string

Returns the path's directory name. Just like path.dirname

OmniPath.dirname("http://server.com/dir/subdir/file.html");  // => "/dir/subdir"
OmniPath.dirname("C:\\dir\\subdir\\file.html");              // => "C:\\dir\\subdir"
OmniPath.dirname("/dir/subdir/");                            // => "/dir"

`basename(path, [ext], [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
ext (optional) - string The expected extension. If this matches the path's extension, then it will not be included in the return value.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: string

Returns the last portion of a path, optionally without the extension. Just like path.basename

OmniPath.basename("http://server.com/dir/subdir/file.html");  // => "file.html"
OmniPath.basename("C:\\dir\\subdir\\file.html", ".html");     // => "file"
OmniPath.basename("/dir/subdir/file.html", ".txt");           // => "file.html"

`extname(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: string

Returns the path's extension, if any. Just like path.extname

If the path's basename begins with a period, then an empty string is returned.

OmniPath.extname("http://server.com/dir/subdir/file.html");  // => ".html"
OmniPath.extname("C:\\dir\\subdir\\file");                   // => ""
OmniPath.extname("C:\\dir\\subdir\\file.");                  // => "."
OmniPath.extname("/dir/subdir/file.min.js");                 // => ".js"
OmniPath.extname("/dir/subdir/.hiddendir");                  // => ""

`cwd()`

Return Value: string

Returns the current working directory path. In Node, the current working directory is process.cwd. In web browsers, it is the directory of the current page.

var cwd = OmniPath.parse(OmniPath.cwd());
cwd.href;       // e.g. "http://localhost:8080/dir/subdir/"
cwd.pathname;   // e.g. "/dir/subdir/"
cwd.dir;        // e.g. "/dir"
cwd.base;       // e.g. "subdir"

`toUrl(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: Url object

Converts the given path to a Url object. If the path is already a URL, then it remain unchanged. If it is a filesystem path, then it is converted to a file:// URL.

You can also call OmniPath.toUrlString(), which does the same thing, but returns the result as a string instead of a Url object.

OmniPath.toUrlString("https://localhost:8080/dir/subdir/"); // => (same string)
OmniPath.toUrlString("file:///Users/johndoe/documents/");   // => (same string)
OmniPath.toUrlString("/dir/subdir");                        // => "file:///dir/subdir"
OmniPath.toUrlString("C:\dir\subdir\file.txt");             // => "file:///C:/dir/subdir/file.txt"
OmniPath.toUrlString("\\server\\dir\\subdir\\");            // => "file://server/dir/subdir/"

`isAbsolute(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: boolean

Determines whether the path is absolute. Just like path.isAbsolute

OmniPath.isAbsolute("https://localhost:8080/dir/subdir/"); // => true
OmniPath.isAbsolute("file:///Users/johndoe/documents/");   // => true
OmniPath.isAbsolute("/dir/subdir");                        // => true
OmniPath.isAbsolute("C:\dir\subdir\file.txt");             // => true on Windows
OmniPath.isAbsolute("\\server\\dir\\subdir\\");            // => true on Windows and browsers

`isUrl(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: boolean

Determines whether the path is a URL (as opposed to a filesystem path). See parse for details about how this is determined.

OmniPath.isUrl("https://localhost:8080/dir/subdir/"); // => true
OmniPath.isUrl("file:///Users/johndoe/documents/");   // => true
OmniPath.isUrl("/dir/subdir");                        // => false in Node, true in browsers
OmniPath.isUrl("C:\dir\subdir\file.txt");             // => false in Node, true in browsers
OmniPath.isUrl("\\server\\dir\\subdir\\");            // => false in Node, true in browsers

`isFS(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: boolean

Determines whether the path is a filesystem path (as opposed to a URL). See parse for details about how this is determined.

OmniPath.isFS("https://localhost:8080/dir/subdir/"); // => false
OmniPath.isFS("file:///Users/johndoe/documents/");   // => false
OmniPath.isFS("/dir/subdir");                        // => true in Node, false in browsers
OmniPath.isFS("C:\dir\subdir\file.txt");             // => true in Node, false in browsers
OmniPath.isFS("\\server\\dir\\subdir\\");            // => true in Node, false in browsers

`isPosix(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: boolean

Determines whether the path is a POSIX filesystem path. See parse for details about how this is determined.

If this is true, then isFS will also be true.

OmniPath.isPosix("https://localhost:8080/dir/subdir/"); // => false
OmniPath.isPosix("file:///Users/johndoe/documents/");   // => false
OmniPath.isPosix("/dir/subdir");                        // => true in Node, false in browsers
OmniPath.isPosix("C:\dir\subdir\file.txt");             // => true in Node, false in browsers
OmniPath.isPosix("\\server\\dir\\subdir\\");            // => true in Node, false in browsers

`isWindows(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: boolean

Determines whether the path is a Windows filesystem path. See parse for details about how this is determined.

If this is true, then isFS will also be true.

OmniPath.isWindows("https://localhost:8080/dir/subdir/"); // => false
OmniPath.isWindows("file:///Users/johndoe/documents/");   // => false
OmniPath.isWindows("/dir/subdir");                        // => true in Node, false in browsers
OmniPath.isWindows("C:\dir\subdir\file.txt");             // => true in Node, false in browsers
OmniPath.isWindows("\\server\\dir\\subdir\\");            // => true in Node, false in browsers

`isUnc(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: boolean

Determines whether the path is a Windows UNC path. See parse for details about how this is determined.

If this is true, then isFS and isWindows will also be true.

OmniPath.isUnc("https://localhost:8080/dir/subdir/"); // => false
OmniPath.isUnc("file:///Users/johndoe/documents/");   // => false
OmniPath.isUnc("/dir/subdir");                        // => false
OmniPath.isUnc("C:\dir\subdir\file.txt");             // => false
OmniPath.isUnc("\\server\\dir\\subdir\\");            // => true on Windows

`sep(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: boolean

Returns the path separator. Just like path.sep

This method returns the proper path separator for the path, which is not necessarily the one that's actually used in the path. For example, on Windows, the path "C:/dir/subdir/file.txt" is valid, but the path separator is still a backslash ("\").

If you just want to get the path separator for a given environment, then you can use OmniPath.win32.sep, OmniPath.posix.sep, or OmniPath.url.sep instead.

OmniPath.sep("https://localhost:8080/dir/subdir/"); // => "/"
OmniPath.sep("file:///Users/johndoe/documents/");   // => "/"
OmniPath.sep("/dir/subdir");                        // => "/" on POSIX and browsers, "\" on Windows
OmniPath.sep("C:\dir\subdir\file.txt");             // => "\" on Windows, "/" elsewhere
OmniPath.sep("\\server\\dir\\subdir\\");            // => "\" on Windows, "/" elsewhere

`delimiter(path, [options])`

path (required) - string or Url or OmniPath The path to be parsed. See parse for details.
options (optional) - object Options that determine how the path is parsed. See options below.
Return Value: boolean

Returns the path separator. Just like path.delimiter

If you just want to get the path delimiter for a given environment, then you can use OmniPath.win32.sep or OmniPath.posix.sep instead.

URLs do not have a path delimiter, so an empty string is returned.

OmniPath.delimiter("https://localhost:8080/dir/subdir/"); // => ""
OmniPath.delimiter("file:///Users/johndoe/documents/");   // => ""
OmniPath.delimiter("/dir/subdir");                        // => ":" on POSIX, ";" on Windows
OmniPath.delimiter("C:\dir\subdir\file.txt");             // => ":" on POSIX, ";" on Windows
OmniPath.delimiter("\\server\\dir\\subdir\\");            // => ":" on POSIX, ";" on Windows

`options`

The OmniPath constructor and all static methods accept an optional "options" argument. This argument determines how paths are parsed. The following options can be set:

property	type	default	description
`allowFileQuery`	boolean	false	Determines whether a question mark (`?`) in a file path should be interpreted as the start of a query string, like URLs, or as part of the file path. By default, it is treated as part of the file path.
`allowFileHash`	boolean	false	Determines whether a hash (`#`) in a file path should be interpreted as the start of a hash, like URLs, or as part of the file path. By default, it is treated as part of the file path.

`OmniPath(path, [options])`

This is the constructor for the OmniPath class. You can call it via new OmniPath(somePath) or via OmniPath.parse(somePath). Both are the same.

var path = new OmniPath("http://server.com/dir/subdir/file.html");
var path = new OmniPath("C:\\dir\\subdir\\file.html");
var path = new OmniPath("/dir/subdir/file.html#page1", {allowFileHash: true});

`OmniPath` object

All of the methods listed above instantiate OmniPath objects internally, and then call their methods or return their property values. You can create OmniPath objects yourself by calling new OmniPath(somePath), and then use the properties and methods directly. The behavior is the same either way. It's just a matter of which syntax you prefer.

OmniPath objects have all the same members listed above, but may be easier to use — especially when performing multiple operations on the same path — since you don't need to specify the path and options parameters over and over again. Also, many members are simple properties instead of methods, which can result in cleaner syntax.

var path = new OmniPath("http://server.com/dir/subdir/file.html?foo=bar");

// Methods
path.dirname();                         // => "/dir/subdir"
path.basename(".html");                 // => "file"
path.resolve("../anotherFile.html");    // => "http://server.com/dir/anotherFile.html"

// Properties
path.isUrl;                             // => true
path.isAbsolute;                        // => true
path.sep;                               // => "/"
path.pathname;                          // => "/dir/subdir/file.html"
path.base;                              // => "file.html"
path.name;                              // => "file"
path.query;                             // => {foo: "bar"}