@dbnx/url-parse - URL Parser and Manipulator

The @dbnx/url-parse package is a TypeScript utility designed to parse, manipulate, and reconstruct URLs with ease. It provides methods for extracting and setting components like protocol, hostname, path, query, port, hash, and more. This class simplifies working with URLs in TypeScript, ensuring safe and efficient manipulation.

Table of Contents

• @dbnx/url-parse - URL Parser and Manipulator
• Table of Contents
• Installation
• Usage
  • Constructor
  • Methods
    • get
    • toString
    • set
• Type Definitions
  • setKeyType
  • Available Keys for get and set Methods
• Examples
  • 1. Basic URL Parsing
  • 2. Updating URL Components
  • 3. Working with Query Parameters
  • 4. Working with Hash
  • 5. Handling Authentication
  • 6. Rebuilding URL
  • 7. Complex URL Manipulation
  • 8. Handling Ports
  • 9. Empty URL Components
  • 10. Using Different Key Types
  • 11. Handling Protocols
• License

Installation

You can install the @dbnx/url-parse package via npm:

npm install @dbnx/url-parse

Usage

Constructor

To use the Url class, create an instance by passing the URL string to the constructor.

import Url from '@dbnx/url-parse';

const url = new Url('https://username:[email protected]:8080/path?query=value#hash');

Methods

get

The get method allows you to retrieve specific components of the URL.

const hostname = url.get('hostname'); // 'www.example.com'
const path = url.get('path'); // '/path'
const query = url.get('query'); // { query: 'value' }

toString

The toString method returns the full URL as a string, based on the current state of the URL object.

const urlString = url.toString(); // 'https://username:[email protected]:8080/path?query=value#hash'

set

The set method allows you to update a specific component of the URL and rebuild the URL string.

url.set('hostname', 'newhostname.com');
url.set('query', { newQuery: 'newValue' });

Type Definitions

setKeyType

This type describes the structure of the parsed URL components.

type setKeyType = {
  path: string | null;
  hash: string | null;
  protocol: string | null;
  origin: string | null;
  username: string | null;
  password: string | null;
  hostname: string | null;
  href: string | null;
  port: string | null;
  query: {
    [key: string]: string;
  };
};

Available Keys for get and set Methods

You can use the following keys when using the get or set methods:

• hostname
• path
• protocol
• username
• origin
• password
• query
• port
• hash

Examples

1. Basic URL Parsing

import Url from '@dbnx/url-parse';

const url = new Url('https://username:[email protected]:8080/path?query=value#hash');

// Get URL components
console.log(url.get('protocol')); // 'https'
console.log(url.get('hostname')); // 'www.example.com'
console.log(url.get('path')); // '/path'
console.log(url.get('query')); // { query: 'value' }
console.log(url.get('hash')); // 'hash'

2. Updating URL Components

const url = new Url('https://example.com/path?query=value');

// Update hostname and query
url.set('hostname', 'newhost.com');
url.set('query', { newQuery: 'newValue' });

console.log(url.toString()); // 'https://newhost.com/path?newQuery=newValue'

3. Working with Query Parameters

const url = new Url('https://example.com/path?name=JohnDoe&age=30');

// Get query parameters
console.log(url.get('query')); // { name: 'JohnDoe', age: '30' }

// Update query parameters
url.set('query', { name: 'JaneDoe', age: '25' });
console.log(url.toString()); // 'https://example.com/path?name=JaneDoe&age=25'

4. Working with Hash

const url = new Url('https://example.com/path#section1');

// Get hash
console.log(url.get('hash')); // 'section1'

// Update hash
url.set('hash', 'section2');
console.log(url.toString()); // 'https://example.com/path#section2'

5. Handling Authentication

const url = new Url('https://username:[email protected]');

// Get authentication details
console.log(url.get('username')); // 'username'
console.log(url.get('password')); // 'password'

// Update authentication
url.set('username', 'newUser');
url.set('password', 'newPassword');
console.log(url.toString()); // 'https://newUser:[email protected]'

6. Rebuilding URL

const url = new Url('https://username:[email protected]:8080/path?query=value#hash');

// Update multiple components
url.set('protocol', 'http');
url.set('hostname', 'newhost.com');
url.set('query', { newQuery: 'newValue' });
console.log(url.toString()); // 'http://username:[email protected]:8080/path?newQuery=newValue#hash'

7. Complex URL Manipulation

const url = new Url('https://username:[email protected]:8080/path?query=value#hash');

// Manipulate various components
url.set('protocol', 'ftp');
url.set('hostname', 'ftp.example.com');
url.set('port', '21');
url.set('path', '/newpath');
url.set('query', { file: 'test.txt' });
url.set('hash', 'top');
console.log(url.toString()); // 'ftp://username:[email protected]:21/newpath?file=test.txt#top'

8. Handling Ports

const url = new Url('https://example.com:8080/path');

// Get port
console.log(url.get('port')); // '8080'

// Update port
url.set('port', '9090');
console.log(url.toString()); // 'https://example.com:9090/path'

9. Empty URL Components

const url = new Url('https://example.com');

// Get components
console.log(url.get('path')); // null
console.log(url.get('query')); // {}
console.log(url.get('hash')); // null

// Set empty components
url.set('path', '/newpath');
url.set('query', { search: 'test' });
url.set('hash', 'section1');
console.log(url.toString()); // 'https://example.com/newpath?search=test#section1'

10. Using Different Key Types

const url = new Url('https://username:[email protected]:8080/path?query=value#hash');

// Get various components
console.log(url.get('hostname')); // 'www.example.com'
console.log(url.get('port')); // '8080'
console.log(url.get('query')); // { query: 'value' }

// Update multiple components
url.set('hostname', 'newhost.com');
url.set('port', '9090');
url.set('query', { updatedQuery: 'newValue' });
console.log(url.toString()); // 'https://username:[email protected]:9090/path?updatedQuery=newValue#hash'

11. Handling Protocols

const url = new Url('ftp://ftp.example.com/path');

// Get protocol
console.log(url.get('protocol')); // 'ftp'

// Update protocol
url.set('protocol', 'https');
console.log(url.toString()); // 'https://ftp.example.com/path'

License

This package is licensed under the MIT License.