Registry / http-networking / path-parser

path-parser

JSON →
library6.1.0jsnpmunverified

path-parser is a small utility library designed for parsing, matching, and generating URL paths. It allows developers to define path patterns with various parameter types (URL, matrix, splat, query) and apply regular expression constraints. It supports full and partial path matching, returning extracted parameters, and robust path building. The current stable version is 6.1.0, as indicated by the package.json and npm badge. While a specific release cadence isn't explicitly documented, the package appears actively maintained given its versioning and features. Its key differentiators include comprehensive parameter definition, robust constraint enforcement during path building, and flexible matching options (case-sensitive, strict trailing slash, delimited partial matching), making it a foundational tool for routing libraries like `route-node`. The library ships with TypeScript types, enhancing development experience for TypeScript users.

npm install path-parser
INSTALL
IMPORT
SIG · PATH-PARSER
P
path-parser
http-networkingjavascriptv6.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Path
import { Path } from 'path-parser'
import Path from 'path-parser'
Path is a named export and the primary class for defining path patterns. For CommonJS, use 'const { Path } = require('path-parser')'.
Path (CommonJS)
const { Path } = require('path-parser')
const Path = require('path-parser'); new Path(...)
When using CommonJS, Path is a named export from the module object. Direct 'require()' returns the module object, not the Path constructor directly, leading to 'TypeError: Path is not a constructor' if not destructured.
Path.create
import { Path } from 'path-parser'; const p = Path.create('/foo')
import Path from 'path-parser'; Path.create('/foo')
The static factory method 'create' (or 'createPath') is an alternative to 'new Path()' and is accessed via the named 'Path' export. It returns a new Path instance.

Demonstrates defining paths with parameters and constraints, performing full and partial matching, and building paths while handling constraint violations.

import { Path } from 'path-parser'; // Define a path with a URL parameter and a regex constraint const userPath = new Path('/users/:id<\\d+>/profile'); console.log('--- Matching Examples ---'); // Full match let matchResult = userPath.test('/users/12345/profile'); console.log('Full match for /users/12345/profile:', matchResult); // Expected: { id: "12345" } // Full match - no match due to constraint matchResult = userPath.test('/users/abcde/profile'); console.log('Full match for /users/abcde/profile:', matchResult); // Expected: null // Partial matching let partialMatchResult = userPath.partialTest('/users/67890/profile/settings'); console.log('Partial match for /users/67890/profile/settings:', partialMatchResult); // Expected: { id: "67890" } partialMatchResult = userPath.partialTest('/products/123'); console.log('Partial match for /products/123:', partialMatchResult); // Expected: null console.log('\n--- Building Examples ---'); // Building a path let builtPath = userPath.build({ id: '54321' }); console.log('Building path with id 54321:', builtPath); // Expected: "/users/54321/profile" // Building a path - with constraint violation (will throw an error) try { userPath.build({ id: 'not-a-number' }); } catch (e) { console.log('Building path with invalid id (expected error):', e.message); // Expected: "Parameter 'id' with value 'not-a-number' does not match constraint <\\d+>" } // Another path definition with query parameters const productPath = new Path('/products/:category?:page&:sort'); console.log('\n--- Product Path Examples ---'); console.log('Building product path:', productPath.build({ category: 'electronics', page: 2, sort: 'price' })); // Expected: "/products/electronics?page=2&sort=price" console.log('Matching product path:', productPath.test('/products/books?page=1&sort=title')); // Expected: { category: "books", page: "1", sort: "title" }
Debug
Known issues
breakingThe URL parameter encoding behavior changed significantly in version 6. Previously, the default encoding was 'legacy', which is now discouraged. If you relied on the exact encoding/decoding of URL parameters from versions <= 5.x, you might see different results.
fix
Review the new `urlParamsEncoding` options ('default', 'uriComponent', 'uri', 'none') and explicitly set the desired behavior during `Path` instantiation or test/build calls. If absolute backward compatibility is needed (not recommended), use `urlParamsEncoding: 'legacy'`.
affects: >=6.0.0
gotchaBuilding paths with parameters that do not satisfy their defined regular expression constraints will cause a runtime error. This enforcement applies by default during the `.build()` method.
fix
Ensure parameters passed to `.build()` conform to their regex constraints, or set the `ignoreConstraints: true` option in the build method options to bypass validation (use with caution).
affects: >=1.0.0
gotchaThe `*splat` parameter allows matching across multiple URL segments but should be used with care as its greedy nature can lead to unexpected matches if not properly placed within the path pattern. It consumes all subsequent segments until the end of the path or another clearly defined segment.
fix
Place `*splat` parameters at the end of your path definition or ensure subsequent segments are clearly distinguishable if partial matching is intended and further segments need to be matched later.
affects: >=1.0.0
gotchaBy default, path matching (`.test()` and `.partialTest()`) is not case-sensitive and does not strictly enforce trailing slashes. This might lead to broader matches than intended for some applications.
fix
Set `'caseSensitive: true'` and/or `'strictTrailingSlash: true'` in the options object for `.test()` or `.partialTest()` if stricter matching behavior is required for your routes.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Parameter 'id' with value 'not-a-number' does not match constraint <\d+>
Attempting to build a path using the `.build()` method with a parameter value that does not satisfy its defined regular expression constraint.
fix
Provide a value that matches the parameter's constraint (e.g., a number for `<\\d+>`), or pass `{ ignoreConstraints: true }` as an option to the `.build()` method to bypass validation.
TypeError: Path is not a constructor
Attempting to instantiate `Path` as a class (e.g., `new Path(...)`) when it was imported incorrectly, typically due to CommonJS `require()` without destructuring, or trying to use a default import in ESM where a named import is required.
fix
For ESM, use `import { Path } from 'path-parser';`. For CommonJS, use `const { Path } = require('path-parser');`. Alternatively, use the static factory method: `const path = Path.create('/your/path');`.
Upgrade
Version history
6.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources