Novice, Paragon, Master

    This package has been deprecated

    Author message:

    This package is no longer maintained

    omnipath

    2.0.4 • Public • Published

    ☠ This package is no longer maintained ☠

    OmniPath

    A consolidated API for file paths and URLs

    npm License

    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.

    Install

    npm i omnipath

    DownloadsWeekly Downloads

    136

    Version

    2.0.4

    License

    MIT

    Unpacked Size

    548 kB

    Total Files

    16

    Last publish

    Collaborators

    • bigstickcarpet
    • jamesmessinger