# top-level-dir

> Get the top-level directory from a URL

Latest version **1.0.5** (published 2018-12-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install top-level-dir
pnpm add top-level-dir
yarn add top-level-dir
bun add top-level-dir
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.5 |
| Published | 2018-12-11 |
| First published | 2018-12-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 25.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Neil Craig neil.craig@thedotproduct.org |
| Maintainers | tdp_org |

## Links

- npm: https://www.npmjs.com/package/top-level-dir
- Repository: https://github.com/neilstuartcraig/top-level-dir
- Homepage: https://github.com/neilstuartcraig/top-level-dir#readme
- Issues: https://github.com/neilstuartcraig/top-level-dir/issues
- npm.io page: https://npm.io/package/top-level-dir

## Recent versions

- 1.0.5 (latest) — 2018-12-11

## README

# top-level-dir

[![Travis CI build status](https://api.travis-ci.org/neilstuartcraig/top-level-dir.svg?branch=master)](https://travis-ci.org/neilstuartcraig/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](https://github.com/browserify/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](http://semver.org/) version numbering scheme.


## Changelog
See the [changelog](./changelog.md) 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](https://help.github.com/articles/using-pull-requests/) 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](./license.md)

---
_Source: https://npm.io/package/top-level-dir · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._