Add URL type detection to lib/url. (#37030)

* Add URL type detection to lib/url.

It adds a new method, `determineUrlType`, which categorises a given URL
into one of five types: absolute, protocol relative, root relative, path
relative, and invalid.

* Change type names to follow spec.

See https://url.spec.whatwg.org/#urls

* Add some more tests based on spec examples.

* Add tests for naked params and fragments.

* Add explicit return type to determineUrlType

Co-Authored-By: Jon Surrell <[email protected]>

Author: sgomes

client/lib/url/index.ts

@@ -17,6 +17,7 @@ export { addQueryArgs } from 'lib/route';
 export { withoutHttp, urlToSlug, urlToDomainAndPath } from './http-utils';
 export { default as isExternal } from './is-external';
 export { default as resemblesUrl } from './resembles-url';
+export { URL_TYPE, determineUrlType } from './url-type';
 
 /**
  * Check if a URL is located outside of Calypso.

client/lib/url/test/url-type.js

@@ -0,0 +1,60 @@
+/**
+ * @jest-environment jsdom
+ */
+
+/**
+ * Internal dependencies
+ */
+import { determineUrlType } from '../url-type';
+
+describe( 'determineUrlType', () => {
+	test( 'should detect the correct type for absolute URLs', () => {
+		expect( determineUrlType( 'http://example.com/' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( 'http://www.example.com' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( 'http://example.com/bar' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( 'http://example.com/bar?baz=1' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( new URL( 'http://example.com' ) ) ).toBe( 'ABSOLUTE' );
+		// From https://url.spec.whatwg.org/#urls
+		expect( determineUrlType( 'https:example.org' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( 'https://////example.com///' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( 'https://example.com/././foo' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( 'hello:world' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( 'file:///C|/demo' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( 'file://loc%61lhost/' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( 'https://user:[email protected]/' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( 'https://example.org/foo bar' ) ).toBe( 'ABSOLUTE' );
+		expect( determineUrlType( 'https://EXAMPLE.com/../x' ) ).toBe( 'ABSOLUTE' );
+	} );
+
+	test( 'should detect the correct type for protocol-relative URLs', () => {
+		expect( determineUrlType( '//example.com/' ) ).toBe( 'SCHEME_RELATIVE' );
+		expect( determineUrlType( '//www.example.com' ) ).toBe( 'SCHEME_RELATIVE' );
+		expect( determineUrlType( '//example.com/bar' ) ).toBe( 'SCHEME_RELATIVE' );
+		expect( determineUrlType( '//example.com/bar?baz=1' ) ).toBe( 'SCHEME_RELATIVE' );
+	} );
+
+	test( 'should detect the correct type for root-relative URLs', () => {
+		expect( determineUrlType( '/' ) ).toBe( 'PATH_ABSOLUTE' );
+		expect( determineUrlType( '/bar' ) ).toBe( 'PATH_ABSOLUTE' );
+		expect( determineUrlType( '/bar?baz=1' ) ).toBe( 'PATH_ABSOLUTE' );
+	} );
+
+	test( 'should detect the correct type for path-relative URLs', () => {
+		expect( determineUrlType( '' ) ).toBe( 'PATH_RELATIVE' );
+		expect( determineUrlType( 'bar' ) ).toBe( 'PATH_RELATIVE' );
+		expect( determineUrlType( 'bar?baz=1' ) ).toBe( 'PATH_RELATIVE' );
+		expect( determineUrlType( 'bar#anchor' ) ).toBe( 'PATH_RELATIVE' );
+		expect( determineUrlType( '?query=param' ) ).toBe( 'PATH_RELATIVE' );
+		expect( determineUrlType( '#fragment' ) ).toBe( 'PATH_RELATIVE' );
+	} );
+
+	test( 'should detect the correct type for invalid URLs', () => {
+		expect( determineUrlType( null ) ).toBe( 'INVALID' );
+		expect( determineUrlType( 0 ) ).toBe( 'INVALID' );
+		expect( determineUrlType( '///' ) ).toBe( 'INVALID' );
+		// From https://url.spec.whatwg.org/#urls
+		expect( determineUrlType( 'https://ex ample.org/' ) ).toBe( 'INVALID' );
+		expect( determineUrlType( 'https://example.com:demo' ) ).toBe( 'INVALID' );
+		expect( determineUrlType( 'http://[www.example.com]/' ) ).toBe( 'INVALID' );
+	} );
+} );

client/lib/url/url-type.ts

@@ -0,0 +1,80 @@
+/**
+ * External dependencies
+ */
+import { URL as URLString } from 'types';
+import { Falsey } from 'utility-types';
+
+// For complete definitions of these classifications, see:
+// https://url.spec.whatwg.org/#urls
+export enum URL_TYPE {
+	// A complete URL, with (at least) protocol and host.
+	// E.g. `http://example.com` or `http://example.com/path`
+	ABSOLUTE = 'ABSOLUTE',
+	// A URL with no protocol, but with a host.
+	// E.g. `//example.com` or `//example.com/path`
+	SCHEME_RELATIVE = 'SCHEME_RELATIVE',
+	// A URL with no protocol or host, but with a path starting at the root.
+	// E.g. `/` or `/path`
+	PATH_ABSOLUTE = 'PATH_ABSOLUTE',
+	// A URL with no protocol or host, but with a path relative to the current resource.
+	// E.g. `../foo` or `bar`
+	PATH_RELATIVE = 'PATH_RELATIVE',
+	// Any invalid URL.
+	// E.g. `///`
+	INVALID = 'INVALID',
+}
+
+const BASE_HOSTNAME = '__domain__.invalid';
+const BASE_URL = `http://${ BASE_HOSTNAME }`;
+
+/**
+ * Determine the type of a URL, with regards to its completeness.
+ * @param url the URL to analyze
+ *
+ * @returns the type of the URL
+ */
+export function determineUrlType( url: URLString | URL | Falsey ): URL_TYPE {
+	// As a URL, the empty string means "the current resource".
+	if ( url === '' ) {
+		return URL_TYPE.PATH_RELATIVE;
+	}
+
+	// Any other falsey value is an invalid URL.
+	if ( ! url ) {
+		return URL_TYPE.INVALID;
+	}
+
+	// The native URL object can only represent absolute URLs.
+	if ( url instanceof URL ) {
+		return URL_TYPE.ABSOLUTE;
+	}
+
+	let parsed;
+
+	try {
+		// If we can parse the URL without a base, it's an absolute URL.
+		parsed = new URL( url );
+		return URL_TYPE.ABSOLUTE;
+	} catch {
+		// Do nothing.
+	}
+
+	try {
+		parsed = new URL( url, BASE_URL );
+	} catch {
+		// If it can't be parsed even with a base URL, it's an invalid URL.
+		return URL_TYPE.INVALID;
+	}
+
+	// If we couldn't parse it without a base, but it didn't take the hostname we provided, that means
+	// it's a protocol-relative URL.
+	if ( parsed.hostname !== BASE_HOSTNAME ) {
+		return URL_TYPE.SCHEME_RELATIVE;
+	}
+
+	// Otherwise, it's a relative URL of some sort.
+	if ( url.startsWith( '/' ) ) {
+		return URL_TYPE.PATH_ABSOLUTE;
+	}
+	return URL_TYPE.PATH_RELATIVE;
+}