top-level-dir v1.0.5
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
5 years ago