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.
// 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"
...
Install using npm:
npm install omnipath
Then require it in your code:
var OmniPath = require('omnipath');
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>
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. This parameter will usually be a string, but can also be aUrl
object (fromurl.parse
) or an existingOmniPath
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});
-
path (required) -
Url
orOmniPath
A parsedOmniPath
object. Can also be aUrl
object (fromurl.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"
-
path (required) -
Url
orOmniPath
A parsedOmniPath
object. Can also be aUrl
object (fromurl.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"
-
path1, path2, ... (optional) -
string
orUrl
orOmniPath
The path parts to join. Seeparse
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"
-
from... (optional) -
string
orUrl
orOmniPath
The paths used to resolveto
. Seeparse
for details. -
to (required) -
string
orUrl
orOmniPath
The path to resolve. Seeparse
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"
-
path (required) -
string
orUrl
orOmniPath
The path to be normalized. Seeparse
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"
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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"
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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"
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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"); // => ""
- 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"
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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/"
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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
-
path (required) -
string
orUrl
orOmniPath
The path to be parsed. Seeparse
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
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. |
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});
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"}
I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.
To build/test the project locally on your computer:
-
Clone this repo
git clone https://github.com/JS-DevTools/omnipath.git
-
Install dependencies
npm install
-
Run the build script
npm run build
-
Run the tests
npm test
OmniPath is 100% free and open-source, under the MIT license. Use it however you want.