patha
> File paths library. All you need to work with paths. Tiny drop-in replacement for 'path'. Works in Node, Browser, and Deno.
- [Install](#install)
- [Usage](#usage)
- [API](#api)
- [`addExeExt` (function)](#addexeext-function)
- [`addNamePrefix` (function)](#addnameprefix-function)
- [`addNameSuffix` (function)](#addnamesuffix-function)
- [`addShExt` (function)](#addshext-function)
- [`addShRelativePrefix` (function)](#addshrelativeprefix-function)
- [`name` (function)](#name-function)
- [`normalizeTrim` (function)](#normalizetrim-function)
- [`removeExt` (function)](#removeext-function)
- [`replaceExt` (function)](#replaceext-function)
- [`isPathInside` (function)](#ispathinside-function)
- [🤝 Contributing](#contributing)
## Install
```sh
npm install --save patha
```
`patha` is tiny and treeshakable.
## Usage
Automatic (depends on your build system)
```js
import * as patha from "patha"
```
Node
```js
import * as patha from "patha/dist/index.node.mjs"
```
Node CJS
```js
const patha = require("patha/dist/index.node.cjs")
```
Browser
```js
import * as patha from "patha/dist/index.browser.mjs"
```
Browser Legacy
```js
import * as patha from "patha/dist/index.browser.legacy.js"
```
Deno
```js
import * as patha from "patha/dist/index.deno.mjs"
```
## API
`patha` is a drop-replacement for `path`, which is explained in [the Nodejs documentation](https://nodejs.org/api/path.html).
```js
import {
basename,
delimiter,
dirname,
extname,
format,
isAbsolute,
join,
normalize,
parse,
posix,
relative,
resolve,
sep,
toNamespacedPath,
win32,
} from "patha"
```
Additionally, `patha` supports the following functions:
### `addExeExt` (function)
Add bin extension to the given binary name.
**Parameters:**
- name (`string`) - The name you want to add the shell extension to
- win_ext (`string`) - Defaults to `.exe` on Windows
- other_ext (`string`) - Defaults to `""` On other platforms.
**returns:** string
```js
import { addExeExt } from "patha"
addExeExt("path/to/file-name") // gives "path/to/file-name.exe" on Windows and "path/to/file-name" on others
```
### `addNamePrefix` (function)
Adds a prefix to the start of the name of the given path
**Parameters:**
- path (`string`) - The given file path
- prefix (`string`) - The prefix to add to the start of the file name
**returns:** string
```js
import { addNamePrefix } from "patha"
addNamePrefix("path/to/file-name.ext", "new-") // gives "path/to/new-file-name.ext"
```
### `addNameSuffix` (function)
Adds a suffix to the end of the name of the given path
**Parameters:**
- path (`string`) - The given file path
- suffix (`string`) - The suffix to add to the end of the file name
**returns:** string
```js
import { addNameSuffix } from "patha"
addNameSuffix("path/to/file-name.ext", "-old") // gives "path/to/file-name-old.ext"
addNameSuffix("path/to/file-name.ext", ".test") // gives "path/to/file-name.test.ext"
```
### `addShExt` (function)
Add a native shell extension to the given name.
**Parameters:**
- name (`string`) - The name you want to add the shell extension to
- win_ext (`string`) - `.cmd` on Windows
- other_ext (`string`) - `.sh` On others.
**returns:** string
```js
import { addShExt } from "patha"
addShExt("path/to/file-name") // gives "path/to/file-name.cmd" on Windows and "path/to/file-name.sh" on others
addShExt("path/to/file-name", ".bat") // gives "path/to/file-name.bat" on Windows and "path/to/file-name.sh" on others
```
### `addShRelativePrefix` (function)
Prefix a `./` for unix shell and nothing for `cmd`.
**Parameters:**
- path (`string`) - The given path
**returns:** string
```js
import { addShRelativePrefix } from "patha"
addShRelativePrefix("some/file-name") // gives "some/file-name" on Windows and "./some/file-name" on others.
```
### `name` (function)
Get the name of the given file path.
By default the file extension is included in the returned name. To remove the extension, set the second parameter to `false`.
**Parameters:**
- path (`string`) - The given file path
- includeExtension (`boolean`) - If the name should include the file extension as well
**returns:** string
```js
import { name } from "patha"
name("path/to/file.md") // gives "file.md"
name("path/to/file.md", false) // gives "file"
```
### `normalizeTrim` (function)
Normalizes the path and removes the trailing slashes.
**Parameters:**
- path (`string`) - The given file path
**returns:** string
```js
import { normalize, normalizeTrim } from "patha"
normalizeTrim("/foo/bar//baz/asdf/hello/../") // gives "/foo/bar/baz/asdf"
normalize("/foo/bar//baz/asdf/hello/../") // gives "/foo/bar/baz/asdf/"
```
### `removeExt` (function)
Remove a path's extension.
**Parameters:**
- path (`string`) - The given path
**returns:** string
```js
import { removeExt } from "patha"
removeExt("some/dir/file.ext") // gives "some/dir/file"
```
### `replaceExt` (function)
Replaces the extension from path with extension and returns the updated path string.
Does not replace the extension if path is not a string or is empty.
**Parameters:**
- path (`string`) - The given path
- extension (`string`) - The extension to replace
**returns:** any
```js
import { replaceExt } from "patha"
replaceExt("path/to/file.md", ".html") // gives "path/to/file.html"
```
### `isPathInside` (function)
Check if a path is inside another path.
Note that relative paths are resolved against `process.cwd()` to make them absolute.
This function does not check if the paths exist and it only works with strings.
**Parameters:**
- childPath (`string`)
- parentPath (`string`)
**returns:** boolean
```js
import { isPathInside } from "patha"
isPathInside("a/b/c", "a/b")
//=> true
isPathInside("a/b/c", "x/y")
//=> false
isPathInside("a/b/c", "a/b/c")
//=> false
isPathInside("/Users/some/dev/aa", "/Users/some")
//=> true
```
## 🤝 Contributing
You can sponsor my work here:
https://github.com/sponsors/aminya
Pull requests, issues and feature requests are welcome.
See the [Contributing guide](https://github.com/aminya/patha/blob/master/CONTRIBUTING.md).