This package has been deprecated

Author message:

This package is no longer maintained

omnipath

☠ 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"}

Contributing

I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.

Building/Testing

To build/test the project locally on your computer:

1. Clone this repo
   git clone https://github.com/JS-DevTools/omnipath.git

2. Install dependencies
   npm install

3. Run the build script
   npm run build

4. Run the tests
   npm test

License

OmniPath is 100% free and open-source, under the MIT license. Use it however you want.