Skip to content

Latest commit

 

History

History

url

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
scripts
scripts
 
 
src
src
 
 
.npmrc
.npmrc
 
 
CHANGELOG.md
CHANGELOG.md
 
 
README.md
README.md
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

README.md

URL

A collection of utilities to manipulate URLs.

Installation

Install the module

npm install @wordpress/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 ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

Usage

# addQueryArgs

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

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 [Object]: Query arguments to apply to URL.

Returns

  • string: URL with arguments applied.

# buildQueryString

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

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,*>: Data to encode.

Returns

  • string: Query string.

# cleanForSlug

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

This replicates some of what sanitize_title() does in WordPress 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.

# filterURLForDisplay

Returns a URL for display.

Usage

const displayUrl = filterURLForDisplay( 'https://www.wordpress.org/gutenberg/' ); // wordpress.org/gutenberg
const imageUrl = filterURLForDisplay( 'https://www.wordpress.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.

# getAuthority

Returns the authority part of the URL.

Usage

const authority1 = getAuthority( 'https://wordpress.org/help/' ); // 'wordpress.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.

# getFragment

Returns the fragment part of the URL.

Usage

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

Parameters

  • url string: The full URL

Returns

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

# getPath

Returns the path part of the URL.

Usage

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

Parameters

  • url string: The full URL.

Returns

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

# getPathAndQueryString

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

Usage

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

Parameters

  • url string: The full URL.

Returns

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

# getProtocol

Returns the protocol part of the URL.

Usage

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

Parameters

  • url string: The full URL.

Returns

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

# getQueryArg

Returns a single query argument of the url

Usage

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

Parameters

  • url string: URL.
  • arg string: Query arg name.

Returns

  • QueryArgParsed|void: Query arg value.

# getQueryArgs

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

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

Parameters

  • url string: URL.

Returns

  • QueryArgs: Query args object.

# getQueryString

Returns the query string part of the URL.

Usage

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.

# hasQueryArg

Determines whether the URL contains a given query arg.

Usage

const hasBar = hasQueryArg( 'https://wordpress.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.

# isEmail

Determines whether the given string looks like an email.

Usage

const isEmail = isEmail( 'hello@wordpress.org' ); // true

Parameters

  • email string: The string to scrutinise.

Returns

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

# isURL

Determines whether the given string looks like a URL.

Related

Usage

const isURL = isURL( 'https://wordpress.org' ); // true

Parameters

  • url string: The string to scrutinise.

Returns

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

# isValidAuthority

Checks for invalid characters within the provided authority.

Usage

const isValid = isValidAuthority( 'wordpress.org' ); // true
const isNotValid = isValidAuthority( 'wordpress#org' ); // false

Parameters

  • authority string: A string containing the URL authority.

Returns

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

# isValidFragment

Checks for invalid characters within the provided fragment.

Usage

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.

# isValidPath

Checks for invalid characters within the provided path.

Usage

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

# isValidProtocol

Tests if a url protocol is valid.

Usage

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:).

# isValidQueryString

Checks for invalid characters within the provided query string.

Usage

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.

# prependHTTP

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

Usage

const actualURL = prependHTTP( 'wordpress.org' ); // http://wordpress.org

Parameters

  • url string: The URL to test.

Returns

  • string: The updated URL.

# removeQueryArgs

Removes arguments from the query string of the url

Usage

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

Parameters

  • url string: URL.
  • args ...string: Query Args.

Returns

  • string: Updated URL.

# safeDecodeURI

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

Usage

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

Parameters

  • uri string: URI to decode.

Returns

  • string: Decoded URI if possible.

# safeDecodeURIComponent

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.



Code is Poetry.