diff --git a/types/wordpress__url/index.d.ts b/types/wordpress__url/index.d.ts new file mode 100644 index 0000000000..1ce4283f70 --- /dev/null +++ b/types/wordpress__url/index.d.ts @@ -0,0 +1,120 @@ +// Type definitions for @wordpress/url 2.3 +// Project: https://github.com/WordPress/gutenberg/tree/master/packages/url/README.md +// Definitions by: Derek Sifford +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 3.4 + +export interface InputArgsObject { + [key: string]: InputArgsValue; +} +export interface OutputArgObject { + [key: string]: OutputArg; +} + +export interface InputArgsArray extends Array {} +export interface OutputArgArray extends Array {} + +export type InputArgsValue = + | string + | number + | boolean + | InputArgsObject + | InputArgsArray + | null + | undefined; + +export type InputArgs = InputArgsObject; +export type OutputArg = string | OutputArgObject | OutputArgArray; + +/** + * 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. + */ +export function addQueryArgs(url?: string, args?: InputArgs): string; + +/** + * Returns a URL for display. + */ +export function filterURLForDisplay(url: string): string; + +/** + * Returns the authority part of the URL. + */ +export function getAuthority(url: string): string | undefined; + +/** + * Returns the fragment part of the URL. + */ +export function getFragment(url: string): string | undefined; + +/** + * Returns the path part of the URL. + */ +export function getPath(url: string): string | undefined; + +/** + * Returns the protocol part of the URL. + */ +export function getProtocol(url: string): string | undefined; + +/** + * Returns a single query argument of the url + */ +export function getQueryArg(url: string, arg: string): OutputArg | undefined; + +/** + * Returns the query string part of the URL. + */ +export function getQueryString(url: string): string | undefined; + +/** + * Determines whether the URL contains a given query arg. + */ +export function hasQueryArg(url: string, arg: string): boolean; + +/** + * Determines whether the given string looks like a URL. + */ +export function isURL(url: string): boolean; + +/** + * Checks for invalid characters within the provided authority. + */ +export function isValidAuthority(url: string): boolean; + +/** + * Checks for invalid characters within the provided fragment. + */ +export function isValidFragment(frag: string): boolean; + +/** + * Checks for invalid characters within the provided path. + */ +export function isValidPath(path: string): boolean; + +/** + * Tests if a url protocol is valid. + */ +export function isValidProtocol(proto: string): boolean; + +/** + * Checks for invalid characters within the provided query string. + */ +export function isValidQueryString(query: string): boolean; + +/** + * Prepends "http://" to a url, if it looks like something that is meant to be a TLD. + */ +export function prependHTTP(url: string): string; + +/** + * Removes arguments from the query string of the url + */ +export function removeQueryArgs(url: string, ...args: readonly string[]): string; + +/** + * Safely decodes a URI with `decodeURI`. Returns the URI unmodified if + * `decodeURI` throws an error. + */ +export function safeDecodeURI(uri: string): string; diff --git a/types/wordpress__url/tsconfig.json b/types/wordpress__url/tsconfig.json new file mode 100644 index 0000000000..7367b9f30a --- /dev/null +++ b/types/wordpress__url/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": ["es6"], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../", + "typeRoots": ["../"], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true, + "paths": { + "@wordpress/url": ["wordpress__url"] + } + }, + "files": ["index.d.ts", "wordpress__url-tests.ts"] +} diff --git a/types/wordpress__url/tslint.json b/types/wordpress__url/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/wordpress__url/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" } diff --git a/types/wordpress__url/wordpress__url-tests.ts b/types/wordpress__url/wordpress__url-tests.ts new file mode 100644 index 0000000000..2019b6b2bd --- /dev/null +++ b/types/wordpress__url/wordpress__url-tests.ts @@ -0,0 +1,57 @@ +import * as url from "@wordpress/url"; + +url.addQueryArgs("https://google.com", { q: "test" }); // https://google.com/?q=test +url.addQueryArgs(undefined, { + foo: "foo", + bar: 24, + baz: { foo: "foo" }, + quux: [1, 2, 3] +}); + +url.filterURLForDisplay("https://www.wordpress.org/gutenberg/"); // wordpress.org/gutenberg + +url.getAuthority("https://wordpress.org/help/"); // 'wordpress.org' +url.getAuthority("https://localhost:8080/test/"); // 'localhost:8080' + +url.getFragment("http://localhost:8080/this/is/a/test?query=true#fragment"); // '#fragment' +url.getFragment("https://wordpress.org#another-fragment?query=true"); // '#another-fragment' + +url.getPath("http://localhost:8080/this/is/a/test?query=true"); // 'this/is/a/test' +url.getPath("https://wordpress.org/help/faq/"); // 'help/faq' + +url.getProtocol("tel:012345678"); // 'tel:' +url.getProtocol("https://wordpress.org"); // 'https:' + +url.getQueryArg("https://wordpress.org?foo=bar&bar=baz", "foo"); // bar + +url.getQueryString("http://localhost:8080/this/is/a/test?query=true#fragment"); // 'query=true' +url.getQueryString("https://wordpress.org#fragment?query=false&search=hello"); // 'query=false&search=hello' + +url.hasQueryArg("https://wordpress.org?foo=bar&bar=baz", "bar"); // true + +url.isURL("https://wordpress.org"); // true + +url.isValidAuthority("wordpress.org"); // true +url.isValidAuthority("wordpress#org"); // false + +url.isValidFragment("#valid-fragment"); // true +url.isValidFragment("#invalid-#fragment"); // false + +url.isValidPath("test/path/"); // true +url.isValidPath("/invalid?test/path/"); // false + +url.isValidProtocol("https:"); // true +url.isValidProtocol("https :"); // false + +url.isValidQueryString("query=true&another=false"); // true +url.isValidQueryString("query=true?another=false"); // false + +url.prependHTTP("wordpress.org"); // http://wordpress.org + +url.removeQueryArgs( + "https://wordpress.org?foo=bar&bar=baz&baz=foobar", + "foo", + "bar" +); // https://wordpress.org?baz=foobar + +url.safeDecodeURI("%z"); // does not throw an Error, simply returns '%z'