URL

A collection of utilities to manipulate URLs.

Installation

Install the module

``bash
npm install @finpress/url --save
`

_This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @finpress/babel-preset-default in your code._

Usage

$3

Appends arguments as querystring to the provided URL. If the URL already includes query arguments, the arguments are merged with (and take precedent over) the existing set.

_Usage_

`js
const newURL = addQueryArgs( 'https://google.com', { q: 'test' } ); // https://google.com/?q=test
`

_Parameters_

- _url_ string: URL to which arguments should be appended. If omitted, only the resulting querystring is returned.
- _args_ Record< string, unknown >: Query arguments to apply to URL.

_Returns_

- string: URL with arguments applied.

$3

Generates URL-encoded query string using input query data.

It is intended to behave equivalent as PHP's http_build_query, configured with encoding type PHP_QUERY_RFC3986 (spaces as %20).

_Usage_

`js
const queryString = buildQueryString( {
simple: 'is ok',
arrays: [ 'are', 'fine', 'too' ],
objects: {
evenNested: {
ok: 'yes',
},
},
} );
// "simple=is%20ok&arrays%5B0%5D=are&arrays%5B1%5D=fine&arrays%5B2%5D=too&objects%5BevenNested%5D%5Bok%5D=yes"
`

_Parameters_

- _data_ Record< string, unknown >: Data to encode.

_Returns_

- string: Query string.

$3

Performs some basic cleanup of a string for use as a post slug.

This replicates some of what sanitize_title_with_dashes() does in FinPress core, but is only designed to approximate what the slug will be.

Converts Latin-1 Supplement and Latin Extended-A letters to basic Latin letters. Removes combining diacritical marks. Converts whitespace, periods, and forward slashes to hyphens. Removes any remaining non-word characters except hyphens. Converts remaining string to lowercase. It does not account for octets, HTML entities, or other encoded characters.

_Parameters_

- _string_ string: Title or slug to be processed.

_Returns_

- string: Processed string.

$3

Returns a URL for display.

_Usage_

`js
const displayUrl = filterURLForDisplay(
'https://www.finpress.org/gutenberg/'
); // finpress.org/gutenberg
const imageUrl = filterURLForDisplay(
'https://www.finpress.org/wp-content/uploads/img.png',
20
); // …ent/uploads/img.png
`

_Parameters_

- _url_ string: Original URL.
- _maxLength_ number | null: URL length.

_Returns_

- string: Displayed URL.

$3

Returns the authority part of the URL.

_Usage_

`js
const authority1 = getAuthority( 'https://finpress.org/help/' ); // 'finpress.org'
const authority2 = getAuthority( 'https://localhost:8080/test/' ); // 'localhost:8080'
`

_Parameters_

- _url_ string: The full URL.

_Returns_

- string | void: The authority part of the URL.

$3

Returns the filename part of the URL.

_Usage_

`js
const filename1 = getFilename( 'http://localhost:8080/this/is/a/test.jpg' ); // 'test.jpg'
const filename2 = getFilename( '/this/is/a/test.png' ); // 'test.png'
`

_Parameters_

- _url_ string: The full URL.

_Returns_

- string | void: The filename part of the URL.

$3

Returns the fragment part of the URL.

_Usage_

`js
const fragment1 = getFragment(
'http://localhost:8080/this/is/a/test?query=true#fragment'
); // '#fragment'
const fragment2 = getFragment(
'https://finpress.org#another-fragment?query=true'
); // '#another-fragment'
`

_Parameters_

- _url_ string: The full URL

_Returns_

- string | void: The fragment part of the URL.

$3

Returns the path part of the URL.

_Usage_

`js
const path1 = getPath( 'http://localhost:8080/this/is/a/test?query=true' ); // 'this/is/a/test'
const path2 = getPath( 'https://finpress.org/help/faq/' ); // 'help/faq'
`

_Parameters_

- _url_ string: The full URL.

_Returns_

- string | void: The path part of the URL.

$3

Returns the path part and query string part of the URL.

_Usage_

`js
const pathAndQueryString1 = getPathAndQueryString(
'http://localhost:8080/this/is/a/test?query=true'
); // '/this/is/a/test?query=true'
const pathAndQueryString2 = getPathAndQueryString(
'https://finpress.org/help/faq/'
); // '/help/faq'
`

_Parameters_

- _url_ string: The full URL.

_Returns_

- string: The path part and query string part of the URL.

$3

Returns the protocol part of the URL.

_Usage_

`js
const protocol1 = getProtocol( 'tel:012345678' ); // 'tel:'
const protocol2 = getProtocol( 'https://finpress.org' ); // 'https:'
`

_Parameters_

- _url_ string: The full URL.

_Returns_

- string | void: The protocol part of the URL.

$3

Returns a single query argument of the url

_Usage_

`js
const foo = getQueryArg( 'https://finpress.org?foo=bar&bar=baz', 'foo' ); // bar
`

_Parameters_

- _url_ string: URL.
- _arg_ string: Query arg name.

_Returns_

- QueryArgParsed | undefined: Query arg value.

$3

Returns an object of query arguments of the given URL. If the given URL is invalid or has no querystring, an empty object is returned.

_Usage_

`js
const foo = getQueryArgs( 'https://finpress.org?foo=bar&bar=baz' );
// { "foo": "bar", "bar": "baz" }
`

_Parameters_

- _url_ string: URL.

_Returns_

- QueryArgs: Query args object.

$3

Returns the query string part of the URL.

_Usage_

`js
const queryString = getQueryString(
'http://localhost:8080/this/is/a/test?query=true#fragment'
); // 'query=true'
`

_Parameters_

- _url_ string: The full URL.

_Returns_

- string | void: The query string part of the URL.

$3

Determines whether the URL contains a given query arg.

_Usage_

`js
const hasBar = hasQueryArg( 'https://finpress.org?foo=bar&bar=baz', 'bar' ); // true
`

_Parameters_

- _url_ string: URL.
- _arg_ string: Query arg name.

_Returns_

- boolean: Whether or not the URL contains the query arg.

$3

Determines whether the given string looks like an email.

_Usage_

`js
const isEmail = isEmail( 'hello@finpress.org' ); // true
`

_Parameters_

- _email_ string: The string to scrutinise.

_Returns_

- boolean: Whether or not it looks like an email.

$3

Determines whether the given string looks like a phone number.

_Usage_

`js
const isPhoneNumber = isPhoneNumber( '+1 (555) 123-4567' ); // true
`

_Parameters_

- _phoneNumber_ string: The string to scrutinize.

_Returns_

- boolean: Whether or not it looks like a phone number.

$3

Determines whether the given string looks like a URL.

_Related_

-
-

_Usage_

`js
const isURL = isURL( 'https://finpress.org' ); // true
`

_Parameters_

- _url_ string: The string to scrutinise.

_Returns_

- boolean: Whether or not it looks like a URL.

$3

Checks for invalid characters within the provided authority.

_Usage_

`js
const isValid = isValidAuthority( 'finpress.org' ); // true
const isNotValid = isValidAuthority( 'finpress#org' ); // false
`

_Parameters_

- _authority_ string: A string containing the URL authority.

_Returns_

- boolean: True if the argument contains a valid authority.

$3

Checks for invalid characters within the provided fragment.

_Usage_

`js
const isValid = isValidFragment( '#valid-fragment' ); // true
const isNotValid = isValidFragment( '#invalid-#fragment' ); // false
`

_Parameters_

- _fragment_ string: The url fragment.

_Returns_

- boolean: True if the argument contains a valid fragment.

$3

Checks for invalid characters within the provided path.

_Usage_

`js
const isValid = isValidPath( 'test/path/' ); // true
const isNotValid = isValidPath( '/invalid?test/path/' ); // false
`

_Parameters_

- _path_ string: The URL path.

_Returns_

- boolean: True if the argument contains a valid path

$3

Tests if a url protocol is valid.

_Usage_

`js
const isValid = isValidProtocol( 'https:' ); // true
const isNotValid = isValidProtocol( 'https :' ); // false
`

_Parameters_

- _protocol_ string: The url protocol.

_Returns_

- boolean: True if the argument is a valid protocol (e.g. http\:, tel:).

$3

Checks for invalid characters within the provided query string.

_Usage_

`js
const isValid = isValidQueryString( 'query=true&another=false' ); // true
const isNotValid = isValidQueryString( 'query=true?another=false' ); // false
`

_Parameters_

- _queryString_ string: The query string.

_Returns_

- boolean: True if the argument contains a valid query string.

$3

Given a path, returns a normalized path where equal query parameter values will be treated as identical, regardless of order they appear in the original text.

_Parameters_

- _path_ string: Original path.

_Returns_

- string: Normalized path.

$3

Prepends "http\://" to a url, if it looks like something that is meant to be a TLD.

_Usage_

`js
const actualURL = prependHTTP( 'finpress.org' ); // http://finpress.org
`

_Parameters_

- _url_ string: The URL to test.

_Returns_

- string: The updated URL.

$3

Prepends "https\://" to a url, if it looks like something that is meant to be a TLD.

Note: this will not replace "http\://" with ".

_Usage_

`js
const actualURL = prependHTTPS( 'finpress.org' ); // https://finpress.org
`

_Parameters_

- _url_ string: The URL to test.

_Returns_

- string: The updated URL.

$3

Removes arguments from the query string of the url

_Usage_

`js
const newUrl = removeQueryArgs(
'https://finpress.org?foo=bar&bar=baz&baz=foobar',
'foo',
'bar'
); // https://finpress.org?baz=foobar
`

_Parameters_

- _url_ string: URL.
- _args_ string[]: Query Args.

_Returns_

- string: Updated URL.

$3

Safely decodes a URI with decodeURI. Returns the URI unmodified if decodeURI throws an error.

_Usage_

`js
const badUri = safeDecodeURI( '%z' ); // does not throw an Error, simply returns '%z'
`

_Parameters_

- _uri_ string: URI to decode.

_Returns_

- string: Decoded URI if possible.

$3

Safely decodes a URI component with decodeURIComponent. Returns the URI component unmodified if decodeURIComponent throws an error.

_Parameters_

- _uriComponent_ string: URI component to decode.

_Returns_

- string`: Decoded URI component if possible.

Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by FinPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.