calypso-url
This library provides both generic and Calypso-specific utilities for handling URLs.
url
Migrating from Node's Node's url
is deprecated and may be abandoned at any point in the future. As such, it shouldn't be
used on the server, and it should be avoided on the client as well, as the browserified version is
just as abandoned.
That functionality has been replaced with the native URL
and URLSearchParams
, which exist as
globals both in Node and in browsers (Calypso polyfills this functionality where needed).
Unfortunately, URL
and URLSearchParams
offer limited functionality compared to Node's url
, with
the main difference being that they're only able to handle absolute URLs (e.g. http://example.com
),
and not partial URLs (e.g., //example.com
, /path
).
calypso-url
is a collection of utilities built on top of URL
and URLSearchParams
, which aim to
offer a way of handling all types of URLs.
calypso-url
does not offer the same API as Node's url
, instead attempting to fix some of its flaws.
IMPORTANT NOTE: URL part names are different between Node's url
and calypso-url
. This is because
calypso-url
is aligned to the URL
/ URLSearchParam
standard in detriment of the legacy API.
Overview of generic functionality
Here is a short summary of the different functionality in calypso-url
:
- Determine the type for a URL:
determineUrlType
(e.g.'ABSOLUTE'
or'SCHEME_RELATIVE'
). - Split a URL into its parts:
getUrlParts
. - Create an absolute URL based on its parts:
getUrlFromParts
. - Format a URL into another type (e.g. format an absolute URL into a scheme-relative one):
format
.
determineUrlType
Takes a string or a URL object and returns one of the following strings:
- ABSOLUTE: a complete URL, with (at least) protocol and host.
Examples:
http://example.com
orhttp://example.com/path
- SCHEME_RELATIVE: A URL with no protocol, but with a host.
Examples:
//example.com
or//example.com/path
- PATH_ABSOLUTE: A URL with no protocol or host, but with a path starting at the root.
Examples:
/
or/path
- PATH_RELATIVE: A URL with no protocol or host, but with a path relative to the current resource.
Examples:
../foo
orbar
- INVALID Any invalid URL.
Example:
///
getUrlParts
Returns an object with the URL's parts, taking into account that some of them may be missing, depending on the type of URL.
getUrlParts( 'https://user:password@www.example.com:8000/path?param=value#anchor' );
The above returns:
const object = {
protocol: 'https:',
host: 'www.example.com:8000',
hostname: 'www.example.com',
port: '8000',
origin: 'https://www.example.com:8000',
pathname: '/path',
hash: '#anchor',
search: '?param=value',
searchParams: searchParams, // A URLSearchParams object containing the search parameters
username: 'user',
password: 'password',
};
IMPORTANT NOTE: URL part names are different between Node's url
and calypso-url
. This is because
calypso-url
is aligned to the URL
/ URLSearchParam
standard in detriment of the legacy API.
getUrlFromParts
Returns a URL object (not a string) from an absolute URL's parts. Note that this method will only work for parts adding up to a full absolute URL, and will throw an error for anything else.
If you need to obtain a string from this method, just access the href
property on the returned
URL object.
getUrlFromParts( parts );
format
Formats a URL object or string into a particular type. For example, you can format an absolute URL as a scheme-relative URL:
format( 'http://example.com/path', 'SCHEME_RELATIVE' );
// -> '//example.com/path'
Formatting to a wider type (for example, from scheme-relative to absolute) will produce an error, as there is missing information.
Attempting to format to PATH_RELATIVE
or INVALID
will also fail with an error.