From 470b2a5edc7f7884391913c78ea8b95dc2ab099e Mon Sep 17 00:00:00 2001 From: Thomas Roch Date: Sun, 25 Mar 2018 22:03:55 +0100 Subject: [PATCH] chore: v4.0.0 --- CHANGELOG.md | 18 +++++++ README.md | 107 +++++++++++++++++++--------------------- dist/cjs/path-parser.js | 1 - dist/es/path-parser.js | 1 - modules/Path.ts | 7 +-- package.json | 2 +- typings/Path.d.ts | 5 +- 7 files changed, 78 insertions(+), 63 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c49e7f..7600960 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,21 @@ + +# [4.0.0](https://github.com/troch/path-parser/compare/v3.0.1...v4.0.0) (2018-03-25) + + +### Features + +* make matching case insensitive, add support for 'caseSentive' option ([063aca6](https://github.com/troch/path-parser/commit/063aca6)) + + +### BREAKING CHANGES + +* query parameters can no longer be defined with brackets, instead options are available when matching and building to describe how arrays, booleans and null values are formatted (see 'queryParams' options in README). +* Boolean and null values in query parameters are stringified differently, see the list of options available. To keep behaviour unchanged, set `nullFormat` to `'hidden'` and `booleanFormat` to `'empty-true'`. +* 'trailingSlash' option has been renamed to 'strictTrailingSlash' +* 'test' and 'partialTest' are now case insensitive by default, use 'caseSensitive' option to make it case sensitive + + + ## [3.0.1](https://github.com/troch/path-parser/compare/v3.0.0...v3.0.1) (2017-11-16) diff --git a/README.md b/README.md index 7653a8e..d8024ad 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,101 @@ [![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) -[![Coverage Status](https://coveralls.io/repos/troch/path-parser/badge.svg?branch=master)](https://coveralls.io/r/troch/path-parser?branch=master) # path-parser -A small utility to parse and build paths. It can be used to partially or fully +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) -## Usage ```javascript -import Path from 'path-parser'; -// Defining a new path -const p = new Path('/users/profile/:id'); +import Path from 'path-parser' + +const path = new Path('/users/:id') + // Matching -p.test('/users/profile/00123') // => {id: "00123"} -// Partial testing: does this path -// starts with that pattern? -p.partialTest('/users/profile/00123/orders') // => {id: "00123"} -p.partialTest('/profile/00123/orders') // => null +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 -p.build({id: '00123'}) // => "users/profile/00123" +path.build({ id: '00123' }) +// => "/users/00123" ``` Without `new`: ```javascript -import Path from 'path-parser'; - -const p = Path.createPath('/users/profile/:id'); +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¶m2` or `?:param1&:param2`: for query parameters. Colons `:` are optional. -- `?param1=a¶m1=b` will result in `{param1: ['a', 'b']}` +* `:param`: for URL parameters +* `;param`: for matrix parameters +* `*splat`: for parameters spanning over multiple segments. Handle with care +* `?param1¶m2` or `?:param1&:param2`: for query parameters. Colons `:` are optional. -### Parameter constraints +#### 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` +* `: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/profile/:id<\d+>'); +var Path = new Path('/users/:id') -path.build({id: 'not-a-number'}); // => Will throw an error -path.build({id: 'not-a-number'}, {ignoreConstraints: true}); // => '/users/profile/not-a-number' +path.build({ id: 'not-a-number' }) // => Will throw an error +path.build({ id: '123' }) // => '/users/123' ``` -## Optional trailing slashes +## API -`.test(path, options)` accepts an option object: -- `strictTrailingSlash`: whether or not trailing slashes are optional (default to `false`). -```javascript -var path = new Path('/my-path'); +### path.test(path: string, opts?: object): object | null; -path.test('/my-path/') // => {} -path.test('/my-path/', { strictTrailingSlash: true }) // => 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`) +- `'queryParams'`: [options for query parameters](https://github.com/troch/search-params#options) -## Partial test with delimiters -`.partialTest(path, options)` accepts an option object: -- `delimited`: if truthy, a partial test will only be successful if a delimiter is found at the end of a match (default to `true`, delimiters are `/`, `?`, `.` and `;`). +### path.partialTest(path: string, opts?: object): object | null; -```javascript -var path = new Path('/my-path'); +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'`: [options for query parameters](https://github.com/troch/search-params#options) -path.partialTest('/my-path/extended') // => {} -path.partialTest('/my-path-extended') // => null -path.partialTest('/my-path-extended', { delimited: false }) // => {} -``` -## Query parameters +### path.build(params?: object, opts?: object): string; + +Builds the defined path template with the provided parameters +- `'ignoreConstraints'`: whether or not to ignore parameter constraints (default to `false`) +- `'ignoreSearch'`: whether or not to build query parameters (default to `false`) +- `'caseSensitive'`: whether matching should be case sensitive or not (default to `false`) +- `'queryParams'`: [options for query parameters](https://github.com/troch/search-params#options) -Query parameters are handled by [search-params](https://github.com/rcs/search-params). `test`, `partialTest` and `build` accept [search-params options](https://github.com/troch/search-params#options). -```js -path.build(params, { - queryParams: { - arrayFormat: 'index', - booleanFormat: 'none' - } -}); -``` ## Related modules -- [route-parser](https://github.com/rcs/route-parser) -- [url-pattern](https://github.com/snd/url-pattern) +* [route-parser](https://github.com/rcs/route-parser) +* [url-pattern](https://github.com/snd/url-pattern) diff --git a/dist/cjs/path-parser.js b/dist/cjs/path-parser.js index 2c72bf0..76eb813 100644 --- a/dist/cjs/path-parser.js +++ b/dist/cjs/path-parser.js @@ -201,7 +201,6 @@ var Path = /** @class */ (function () { Path.prototype.build = function (params, opts) { var _this = this; if (params === void 0) { params = {}; } - if (opts === void 0) { opts = {}; } var options = __assign({ ignoreConstraints: false, ignoreSearch: false, queryParams: {} }, opts); var encodedUrlParams = Object.keys(params) .filter(function (p) { return !_this.isQueryParam(p); }) diff --git a/dist/es/path-parser.js b/dist/es/path-parser.js index 2bb87df..23c7010 100644 --- a/dist/es/path-parser.js +++ b/dist/es/path-parser.js @@ -199,7 +199,6 @@ var Path = /** @class */ (function () { Path.prototype.build = function (params, opts) { var _this = this; if (params === void 0) { params = {}; } - if (opts === void 0) { opts = {}; } var options = __assign({ ignoreConstraints: false, ignoreSearch: false, queryParams: {} }, opts); var encodedUrlParams = Object.keys(params) .filter(function (p) { return !_this.isQueryParam(p); }) diff --git a/modules/Path.ts b/modules/Path.ts index 08fb7ec..07a6e8e 100644 --- a/modules/Path.ts +++ b/modules/Path.ts @@ -48,6 +48,7 @@ export interface IPartialTestOptions { export interface ITestOptions { caseSensitive?: boolean + strictTrailingSlash?: boolean queryParams?: IOptions } @@ -110,7 +111,7 @@ export default class Path { return this.queryParams.indexOf(name) !== -1 } - public test(path, opts): TestMatch { + public test(path: string, opts?: ITestOptions): TestMatch { const options = { strictTrailingSlash: false, queryParams: {}, ...opts } // trailingSlash: falsy => non optional, truthy => optional const source = optTrailingSlash( @@ -143,7 +144,7 @@ export default class Path { return null } - public partialTest(path: string, opts: IPartialTestOptions): TestMatch { + public partialTest(path: string, opts?: IPartialTestOptions): TestMatch { const options = { delimited: true, queryParams: {}, ...opts } // Check if partial match (start of given path matches regex) // trailingSlash: falsy => non optional, truthy => optional @@ -167,7 +168,7 @@ export default class Path { return match } - public build(params: object = {}, opts: IBuildOptions = {}): string { + public build(params: object = {}, opts?: IBuildOptions): string { const options = { ignoreConstraints: false, ignoreSearch: false, diff --git a/package.json b/package.json index 3b05c99..77bad6a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "path-parser", - "version": "3.0.1", + "version": "4.0.0", "description": "A small utility to parse, match and generate paths", "main": "dist/cjs/path-parser.js", "jsnext:main": "dist/es/path-parser.js", diff --git a/typings/Path.d.ts b/typings/Path.d.ts index 49edf6c..a87dbb5 100644 --- a/typings/Path.d.ts +++ b/typings/Path.d.ts @@ -7,6 +7,7 @@ export interface IPartialTestOptions { } export interface ITestOptions { caseSensitive?: boolean; + strictTrailingSlash?: boolean; queryParams?: IOptions; } export interface IBuildOptions { @@ -30,8 +31,8 @@ export default class Path { source: string; constructor(path: any); isQueryParam(name: string): boolean; - test(path: any, opts: any): TestMatch; - partialTest(path: string, opts: IPartialTestOptions): TestMatch; + test(path: string, opts?: ITestOptions): TestMatch; + partialTest(path: string, opts?: IPartialTestOptions): TestMatch; build(params?: object, opts?: IBuildOptions): string; private getParams(type); private urlTest(path, source, {caseSensitive}?);