top-level-dir

Overview

A Node package which finds the top-level (or an arbitrary level) directory from an absolute or relative URL (but not yet scheme-relative URL's). Examples:

Quickstart

import {default as getTopLevelDir} from "top-level-dir";

const tld1 = getTopLevelDir("https://www.example.com/a/b/c/");
// "/a"

const tld2 = getTopLevelDir("/x/y/z");
// "/x"

Installation

npm install top-level-dir --production

Using top-level-dir

top-level-dir is a Node package, it doesn't natively work in a browser (though you might have some luck with e.g. Browserify).

Including the library

You can use either the traditional require() or the newer import method:

import {default as getTopLevelDir} from "top-level-dir";
// or:
const getTopLevelDir = require("top-level-dir");

Arguments

getTopLevelDir(URL [fromLevel, toLevel])

URL is the URL from which to extract the directory. It must be a string (either relative or absolute URL) and is mandatory.
fromLevel is the directory level at which the output will begin. It is optional and must be an integer. fromLevel defaults to 1 if not supplied. toLevel is the directory level at which the output will end. It is optional and must be an integer. toLevel defaults to 1 if not supplied.

Output

top-level-dir will always return a string when the input arguments are valid and allow a valid output to be found. Otherwise, top-level-dir will throw an Error.

Examples

import {default as getTopLevelDir} from "top-level-dir";

// Get the top-level directory only (from absolute URL)
const tld1 = getTopLevelDir("https://www.example.com/a/b/c/");
// "/a"

// Get the top-level directory only (from relative URL)
const tld2 = getTopLevelDir("/x/y/z");
// "/x"


// Get the 2nd level directory only (from absolute URL)
const tld3 = getTopLevelDir("https://www.example.com/a/b/c/", 2, 2);
// "/b"

// Get the 2nd level directory only (from relative URL)
const tld4 = getTopLevelDir("/x/y/z", 2, 2);
// "/y"


// Get the 2nd and 3rd level directories (from absolute URL)
const tld3 = getTopLevelDir("https://www.example.com/a/b/c/", 2, 3);
// "/b/c"

// Get the 2nd and 3rd level directories (from relative URL)
const tld4 = getTopLevelDir("/x/y/z", 2, 3);
// "/y/z"


// Try to get the 20th level directory (from relative URL which is too short). This will fail and result in an Error being thrown
try
{
    const tld5 = getTopLevelDir("/x/y/z", 20);
}
catch(e)
{
    // e will be an Error
}

Semver

This project aims to maintain the semver version numbering scheme.

Changelog

See the changelog file

Contributing

Contributions are very welcome for fixes, improvements, new features, documentation, bug reports and/or ideas. Please create a Github issue initially so we can discuss and agree actions/approach - that should save time all-round.

The ideal way to receive contributions is via a Github Pull Request from the master branch. Please ensure that at least unit tests (you can run these via npm test) and if possible, linter rules (npm run lint).

If you find a sensitive, security issue with this application, please email me privately in the first instance: neil [dot] craig [at] thedotproduct [dot] org.

License

MIT license