@alessiofrittoli/url-utils v3.5.0

URL utils 🔗

TypeScript URL utility library

Table of Contents

• Getting started
• API Reference
  • Url utility Class
  • Check functions
  • Parse functions
  • Slash functions
• Development
  • Install depenendencies
  • Build the source code
  • ESLint
  • Jest
• Contributing
• Security
• Credits

Getting started

Run the following command to start using url-utils in your projects:

npm i @alessiofrittoli/url-utils

or using pnpm

pnpm i @alessiofrittoli/url-utils

API Reference

Url utility Class

The Url utility class provides methods for parsing and formatting URLs. It supports multiple input types, ensuring flexibility in handling URL manipulation.

Type Definitions

UrlInput

The Url parse/format accepted input.

Methods

Url.parse()

Parses a given URL input into a URL instance. If the host is not provided, it defaults to unresolved.

Type: URL

A new instance of URL.

Url.format()

Formats a given URL input into a URL string. If the hostname is unresolved, it returns a relative URL string.

Type: string

The formatted URL string.

Check functions

Importing functions

import { ... } from '@alessiofrittoli/url-utils/check'

isExternalUrl

Determines if a given URL is external compared to a provided or default location.

Type: boolean

• true if the URL is external.
• false otherwise.

// External URL check
const result1 = isExternalUrl( 'https://example.com', 'https://mywebsite.com' )
console.log( result1 ) // true

// Internal URL check
const result2 = isExternalUrl( '/about', 'https://mywebsite.com' )
console.log( result2 ) // false

isAbsoluteUrl

Checks if a given URL is absolute.

Type: boolean

• true if the URL is absolute.
• false otherwise.

// Absolute URL check
const result1 = isAbsoluteUrl( 'https://example.com' )
console.log( result1 ) // true

// Relative URL check
const result2 = isAbsoluteUrl( '/about' )
console.log( result2 ) // false

Parse functions

Importing functions

import { ... } from '@alessiofrittoli/url-utils/parse'

slugify

Converts a given string into a URL-friendly slug.

Type: string

A string representing the slugified version of the input text.

Basic usage

const slug = slugify( 'Hello World! Let\'s Code.' )
console.log( slug ) // Outputs: 'hello-world-lets-code'

Transforming user input

input.addEventListener( 'input', event => {
    const input = event.target
    // setting `trim` to false will allow the user to type whitespace characters that will be converted to hyphen characters, improving typing experience.
    input.value = slugify( input.value, false )
} )

getDomain

Extracts the domain name from a given URL.

Type: string

A string representing the domain name.

Basic usage

const domain = getDomain( 'https://www.sub.example.com/path' )
console.log( domain ) // 'sub.example.com'

Getting 1st level domain name

const domain = getDomain( 'https://www.sub.example.com/path', false )
console.log( domain ) // 'example.com'

Slash functions

Importing functions

import { ... } from '@alessiofrittoli/url-utils/slash'

backToForwardSlashes

Converts all backslashes (\) in a string to forward slashes (/).

Type: string

A string with all backslashes replaced by forward slashes.

console.log( backToForwardSlashes( 'path\\to\\file' ) ) // Outputs: 'path/to/file'

forwardToBackSlashes

Converts all forward slashes (/) in a string to backslashes (\).

Type: string

A string with all forward slashes replaced by backslashes.

console.log( forwardToBackSlashes( 'path/to/file' ) ) // Outputs: 'path\to\file'

addLeadingSlash

Adds a leading slash (/ or \) to a string if it doesn’t already have one.

Type: string

A string with the specified leading slash.

console.log( addLeadingSlash( 'path/to/file' ) ) // Outputs: '/path/to/file'
console.log( addLeadingSlash( 'path\\to\\file', '\\' ) ) // Outputs: '\path\to\file'

removeLeadingSlash

Removes any leading slashes (/ or \) from a string.

Type: string

A string without leading slashes.

console.log( removeLeadingSlash( '/path/to/file' ) ) // Outputs: 'path/to/file'
console.log( removeLeadingSlash( '\\path\\to\\file' ) ) // Outputs: 'path\to\file'

addTrailingSlash

Adds a trailing slash (/ or \) to a string if it doesn’t already have one.

Type: string

A string with the specified trailing slash.

console.log( addTrailingSlash( 'path/to/file' ) ) // Outputs: 'path/to/file/'
console.log( addTrailingSlash( 'path\\to\\file', '\\' ) ) // Outputs: 'path\to\file\'

removeTrailingSlash

Removes any trailing slashes (/ or \) from a string.

Type: string

A string without trailing slashes.

console.log( removeTrailingSlash( 'path/to/file/' ) ) // Outputs: 'path/to/file'
console.log( removeTrailingSlash( 'path\\to\\file\\' ) ) // Outputs: 'path\\to\\file'

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests and watch file changes with jest-environment-jsdom.
pnpm test:jsdom

# Run tests in a CI environment.
pnpm test:ci

# Run tests in a CI environment with jest-environment-jsdom.
pnpm test:ci:jsdom

You can eventually run specific suits like so:

• See package.json file scripts for more info.

pnpm test:jest
pnpm test:jest:jsdom

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email security@alessiofrittoli.it to disclose any security vulnerabilities.

Made with ☕