[@wordpress/url] add new definitions (#35876)

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 <https://github.com/dsifford>
+// 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<InputArgsValue> {}
+export interface OutputArgArray extends Array<OutputArg> {}
+
+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;

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"]
+}

types/wordpress__url/tslint.json

@@ -0,0 +1 @@
+{ "extends": "dtslint/dt.json" }

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'