@xesam/url

Split URL-like strings in constrained JavaScript runtimes with ES5 + RegExp.

This package is designed for environments such as mini-program runtimes where you may not have a reliable built-in URL object and do not want to depend on third-party parser behavior.

@xesam/url is not a standards-compliant URL parser. It is a tiny splitter for a narrow set of supported input shapes.

npm install @xesam/url

Supported input shapes

• scheme://[auth@]host[:port][/path][?query][#hash]
• /path[?query][#hash]

?query-only and #hash-only are documented boundary cases: ?query-only returns populated search and query fields, and #hash-only returns a populated hash field.

Unsupported input classes

• non-authority scheme URIs such as mailto:[email protected]
• non-authority payload schemes such as data:text/plain,hello
• script-like schemes such as javascript:alert(1)
• protocol-relative URLs such as //example.com/path

Non-goals / not provided

• RFC / WHATWG compatibility guarantees
• validation, normalization, decoding, or formatting

Result contract

Every call returns the same stable object shape with these fields:

• protocol
• auth
• host
• hostname
• port
• pathname
• search
• query
• hash

Supported input shapes and documented boundary cases always return the stable object shape above, with populated fields determined by the matched shape or documented boundary rule. Unsupported input classes are non-throwing, but any returned field values are not part of the contract.

Malformed, blank (empty or whitespace-only), nullish, or unmatched inputs collapse to the fixed all-undefined result shape.

Usage

const url = require('@xesam/url');

console.log(url('https://admin:[email protected]:443/path/to/view?tab=home#top'));
console.log(url('miniapp://page.example/path/to/view?tab=home#top'));
console.log(url('/pages/home/index?tab=home#top'));
console.log(url('?query-only'));
console.log(url('#hash-only'));
console.log(url('????'));

Output:

For https://admin:[email protected]:443/path/to/view?tab=home#top:

{
    protocol: 'https:',
    auth: 'admin:root',
    host: 'page.example:443',
    hostname: 'page.example',
    port: '443',
    pathname: '/path/to/view',
    search: '?tab=home',
    query: 'tab=home',
    hash: '#top'
}

For miniapp://page.example/path/to/view?tab=home#top:

{
    protocol: 'miniapp:',
    auth: undefined,
    host: 'page.example',
    hostname: 'page.example',
    port: undefined,
    pathname: '/path/to/view',
    search: '?tab=home',
    query: 'tab=home',
    hash: '#top'
}

For /pages/home/index?tab=home#top:

{
    protocol: undefined,
    auth: undefined,
    host: undefined,
    hostname: undefined,
    port: undefined,
    pathname: '/pages/home/index',
    search: '?tab=home',
    query: 'tab=home',
    hash: '#top'
}

For ?query-only:

{
    protocol: undefined,
    auth: undefined,
    host: undefined,
    hostname: undefined,
    port: undefined,
    pathname: undefined,
    search: '?query-only',
    query: 'query-only',
    hash: undefined
}

For #hash-only:

{
    protocol: undefined,
    auth: undefined,
    host: undefined,
    hostname: undefined,
    port: undefined,
    pathname: undefined,
    search: undefined,
    query: undefined,
    hash: '#hash-only'
}

For ????:

{
    protocol: undefined,
    auth: undefined,
    host: undefined,
    hostname: undefined,
    port: undefined,
    pathname: undefined,
    search: undefined,
    query: undefined,
    hash: undefined
}