@dbnx/useparams v1.0.5

@dbnx/useparams

A lightweight library for parsing, manipulating, and extracting URL parameters based on a given path pattern. It supports dynamic segments, optional parameters, and wildcards.

Installation

To install the package, run the following command:

npm install @dbnx/useparams

Alternatively, if you use Yarn:

yarn add @dbnx/useparams

Usage

The useParams function allows you to extract dynamic parameters from a given path based on a URL pattern. You can match dynamic segments, handle optional parameters, and use wildcards.

Example

Matching a path with dynamic segments

import useParams from '@dbnx/useparams';

const result = useParams({ path: '/user/123/profile', urlPattern: '/user/:id/profile' });

console.log(result);
// Output: { success: true, params: { id: '123' } }

Matching a path with wildcards

import useParams from '@dbnx/useparams';

const result = useParams({ path: '/files/documents/photos/2021/file1.jpg', urlPattern: '/files/*' });

console.log(result);
// Output: { success: true, params: { wildcard: 'documents/photos/2021/file1.jpg' } }

Matching a path with optional parameters

import useParams from '@dbnx/useparams';

const result = useParams({ path: '/user/123/profile', urlPattern: '/user/:id?/profile' });

console.log(result);
// Output: { success: true, params: { id: '123' } }

Handling invalid pattern

import useParams from '@dbnx/useparams';

const result = useParams({ path: '/user/123/profile', urlPattern: '/profile/:id' });

console.log(result);
// Output: { success: false, params: {} }

API

useParams({ path: string, urlPattern: string }): { success: boolean, params: Record<string, any> }

• path: The URL path you want to match against the pattern. (Example: /user/123/profile)
• urlPattern: The pattern to match against, which can include dynamic segments, optional parameters, and wildcards. (Example: /user/:id/profile)

Returns an object with:

• success: A boolean indicating whether the path matched the pattern.
• params: An object containing the extracted parameters. If a dynamic segment is present, it will be included in params with its value. If a wildcard is used, the remaining path will be captured under wildcard.

Features

• Dynamic Segments: Capture dynamic segments with the :paramName syntax.
• Optional Segments: Use the :paramName? syntax for optional segments that may or may not be present in the path.
• Wildcards: Use * to capture all remaining segments as a single value (useful for capturing deep paths).
• Strict Matching: Ensure that static segments match exactly.

Advanced Examples

Path with multiple dynamic segments

const result = useParams({ path: '/user/123/profile/abc', urlPattern: '/user/:id/profile/:section' });

console.log(result);
// Output: { success: true, params: { id: '123', section: 'abc' } }

Path with optional segments

const result1 = useParams({ path: '/user/123/profile', urlPattern: '/user/:id?/profile' });
const result2 = useParams({ path: '/user/123/profile/details', urlPattern: '/user/:id?/profile/:section?' });

console.log(result1);
// Output: { success: true, params: { id: '123' } }

console.log(result2);
// Output: { success: true, params: { id: '123', section: 'details' } }

Author

• SRAKIB17
• GitHub

@dbnx/useparams is a utility library that simplifies the process of URL path matching, extracting parameters, and supporting complex patterns like wildcards and optional parameters.

Key Sections Explained

• Installation: Instructions on how to install the package using npm or Yarn.
• Usage: Includes various examples demonstrating the core functionality of the useParams function.
• API: Describes the function signature, its parameters (path and urlPattern), and the return value (success and params).
• Features: Lists the main features of the library like dynamic segments, optional parameters, and wildcards.