# path-parser

> A small utility to parse, match and generate paths

Latest version **6.1.0** (published 2020-01-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install path-parser
pnpm add path-parser
yarn add path-parser
bun add path-parser
```

## Health

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

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.1.0 |
| Published | 2020-01-06 |
| First published | 2015-06-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 124.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 138 |
| Author | Thomas Roch |
| Maintainers | troch |

## Links

- npm: https://www.npmjs.com/package/path-parser
- Repository: https://github.com/troch/path-parser
- Issues: https://github.com/troch/path-parser/issues
- npm.io page: https://npm.io/package/path-parser

## Dependencies (2)

- [tslib](https://npm.io/package/tslib.md) ^1.10.0
- [search-params](https://npm.io/package/search-params.md) 3.0.0

## Recent versions

- 6.1.0 (latest) — 2020-01-06
- 6.0.0 — 2020-01-05
- 5.1.0 — 2019-12-30
- 5.0.1 — 2019-12-29
- 5.0.0 — 2019-12-29
- 4.2.0 — 2018-07-11
- 4.1.1 — 2018-06-05
- 4.1.0 — 2018-05-14
- 4.0.5 — 2018-05-14
- 4.0.4 — 2018-04-09
- 4.0.3 — 2018-04-03
- 4.0.2 — 2018-03-27
- 4.0.1 — 2018-03-26
- 4.0.0 — 2018-03-25
- 3.0.1 — 2017-11-16
- … 33 more at https://npm.io/package/path-parser/versions

## README

[![npm version](https://badge.fury.io/js/path-parser.svg)](http://badge.fury.io/js/path-parser)
[![Build Status](https://travis-ci.org/troch/path-parser.svg)](https://travis-ci.org/troch/path-parser)

# path-parser

A small library to parse and build paths. It can be used to partially or fully
test paths against a defined pattern.

Partial testing allows to determine if a given path starts with the defined pattern.
It is used by [route-node](https://github.com/troch/route-node)

```javascript
import { Path } from 'path-parser'
// or
const { Path } = require('path-parser')

const path = new Path('/users/:id')

// Matching
path.test('/users/00123')
// {
//  id: "00123"
// }

// Partial testing: does the provided path
// starts with the defined pattern?
path.partialTest('/users/00123/orders')
// {
//  id: "00123"
// }
path.partialTest('/profile/00123/orders')
// null

// Building
path.build({ id: '00123' })
// => "/users/00123"
```

Without `new`:

```javascript
const path = Path.createPath('/users/:id')
```

## Defining parameters

- `:param`: for URL parameters
- `;param`: for matrix parameters
- `*splat`: for parameters spanning over multiple segments. Handle with care
- `?param1&param2` or `?:param1&:param2`: for query parameters. Colons `:` are optional.

#### Parameter constraints

For URL parameters and matrix parameters, you can add a constraint in the form of a regular expression.
Note that back slashes have to be escaped.

- `:param<\\d+>` will match numbers only for parameter `param`
- `;id<[a-fA-F0-9]{8}` will match 8 characters hexadecimal strings for parameter `id`

Constraints are also applied when building paths, unless specified otherwise (set option flag `ignoreConstraints` to true).

```javascript
// Path.build(params, opts)
var Path = new Path('/users/:id<d+>')

path.build({ id: 'not-a-number' }) // => Will throw an error
path.build({ id: '123' }) // => '/users/123'
```

## API

### Constructor

A path instance can be created two ways:

- `new Path(path: string, opts?: object): object`
- `Path.create(path: string, opts?: object): object`

Options available are:

- `'queryParams'`: [options for query parameters](https://github.com/troch/search-params#options)
- `'urlParamsEncoding`, to specify how URL parameters are encoded and decoded:
  - `'default':`encodeURIComponent`and`decodeURIComponent`are used but some characters to encode and decode URL parameters, but some characters are preserved when encoding (sub-delimiters:`+`,`:`,`'`,`!`,`,`,`;`,`'\*'`).
  - `'uriComponent'`: use `encodeURIComponent` and `decodeURIComponent`
    for encoding and decoding URL parameters.
  - `'uri'`: use `encodeURI` and `decodeURI for encoding amd decoding
    URL parameters.
  - `'none'`: no encoding or decoding is performed
  - `'legacy'`: the approach for version 5.x and below (not recoomended)

### path.test(path: string, opts?: object): object | null;

Test if the provided path matches the defined path template. Options available are:

- `'caseSensitive'`: whether matching should be case sensitive or not (default to `false`)
- `'strictTrailingSlash'`: whether or not it should strictly match trailing slashes (default to `false`)

### path.partialTest(path: string, opts?: object): object | null;

Test if the provided path is partially matched (starts with) the defined path template. Options available are:

- `'caseSensitive'`: whether matching should be case sensitive or not (default to `false`)
- `'delimited'`: whether or not a partial match should only be successful if it reaches a delimiter (`/`, `?`, `.` and `;`). Default to `true`.
- `'queryParams'`: to overwrite query parameter options (see above)
- `'urlParamsEncoding`: to overwrite URL param encoding and decoding option (see above)

### path.build(params?: object, opts?: object): string;

Builds the defined path template with the provided parameters

- `'caseSensitive'`: whether matching should be case sensitive or not (default to `false`)
- `'ignoreConstraints'`: whether or not to ignore parameter constraints (default to `false`)
- `'ignoreSearch'`: whether or not to build query parameters (default to `false`)
- `'queryParams'`: to overwrite query parameter options (see above)
- `'urlParamsEncoding`: to overwrite URL param encoding and decoding option (see above)

## Related modules

- [route-parser](https://github.com/rcs/route-parser)
- [url-pattern](https://github.com/snd/url-pattern)

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