diff --git a/index.d.ts b/index.d.ts index 2a50665..463fb40 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,183 +1,216 @@ -export interface Options { - /** - * @default 'http:' - */ - readonly defaultProtocol?: string; +declare namespace normalizeUrl { + interface Options { + /** + @default 'http:' + */ + readonly defaultProtocol?: string; - /** - * Prepends `defaultProtocol` to the URL if it's protocol-relative. - * - * @default true - * - * @example - * - * normalizeUrl('//sindresorhus.com:80/'); - * //=> 'http://sindresorhus.com' - * - * normalizeUrl('//sindresorhus.com:80/', {normalizeProtocol: false}); - * //=> '//sindresorhus.com' - */ - readonly normalizeProtocol?: boolean; + /** + Prepends `defaultProtocol` to the URL if it's protocol-relative. - /** - * Normalizes `https:` URLs to `http:`. - * - * @default false - * - * @example - * - * normalizeUrl('https://sindresorhus.com:80/'); - * //=> 'https://sindresorhus.com' - * - * normalizeUrl('https://sindresorhus.com:80/', {forceHttp: true}); - * //=> 'http://sindresorhus.com' - */ - readonly forceHttp?: boolean; + @default true - /** - * Normalizes `http:` URLs to `https:`. - * - * This option can't be used with the `forceHttp` option at the same time. - * - * @default false - * - * @example - * - * normalizeUrl('https://sindresorhus.com:80/'); - * //=> 'https://sindresorhus.com' - * - * normalizeUrl('http://sindresorhus.com:80/', {forceHttps: true}); - * //=> 'https://sindresorhus.com' - */ - readonly forceHttps?: boolean; + @example + ``` + normalizeUrl('//sindresorhus.com:80/'); + //=> 'http://sindresorhus.com' - /** - * Strip the [authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) part of a URL. - * - * @default true - * - * @example - * - * normalizeUrl('user:password@sindresorhus.com'); - * //=> 'https://sindresorhus.com' - * - * normalizeUrl('user:password@sindresorhus.com', {stripAuthentication: false}); - * //=> 'https://user:password@sindresorhus.com' - */ - readonly stripAuthentication?: boolean; + normalizeUrl('//sindresorhus.com:80/', {normalizeProtocol: false}); + //=> '//sindresorhus.com' + ``` + */ + readonly normalizeProtocol?: boolean; - /** - * Removes hash from the URL. - * - * @default false - * - * @example - * - * normalizeUrl('sindresorhus.com/about.html#contact'); - * //=> 'http://sindresorhus.com/about.html#contact' - * - * normalizeUrl('sindresorhus.com/about.html#contact', {stripHash: true}); - * //=> 'http://sindresorhus.com/about.html' - */ - readonly stripHash?: boolean; + /** + Normalizes `https:` URLs to `http:`. - /** - * Removes HTTP(S) protocol from an URL `http://sindresorhus.com` → `sindresorhus.com`. - * - * @default false - * - * @example - * - * normalizeUrl('https://sindresorhus.com'); - * //=> 'https://sindresorhus.com' - * - * normalizeUrl('sindresorhus.com', {stripProtocol: true}); - * //=> 'sindresorhus.com' - */ - readonly stripProtocol?: boolean; + @default false - /** - * Removes `www.` from the URL. - * - * @default true - * - * @example - * - * normalizeUrl('http://www.sindresorhus.com'); - * //=> 'http://sindresorhus.com' - * - * normalizeUrl('http://www.sindresorhus.com', {stripWWW: false}); - * //=> 'http://www.sindresorhus.com' - */ - readonly stripWWW?: boolean; + @example + ``` + normalizeUrl('https://sindresorhus.com:80/'); + //=> 'https://sindresorhus.com' - /** - * Removes query parameters that matches any of the provided strings or regexes. - * - * @default [/^utm_\w+/i] - * - * @example - * - * normalizeUrl('www.sindresorhus.com?foo=bar&ref=test_ref', { - * removeQueryParameters: ['ref'] - * }); - * //=> 'http://sindresorhus.com/?foo=bar' - */ - readonly removeQueryParameters?: (RegExp | string)[]; + normalizeUrl('https://sindresorhus.com:80/', {forceHttp: true}); + //=> 'http://sindresorhus.com' + ``` + */ + readonly forceHttp?: boolean; - /** - * Removes trailing slash. - * - * **Note**: Trailing slash is always removed if the URL doesn't have a pathname. - * - * @default true - * - * @example - * - * normalizeUrl('http://sindresorhus.com/redirect/'); - * //=> 'http://sindresorhus.com/redirect' - * - * normalizeUrl('http://sindresorhus.com/redirect/', {removeTrailingSlash: false}); - * //=> 'http://sindresorhus.com/redirect/' - * - * normalizeUrl('http://sindresorhus.com/', {removeTrailingSlash: false}); - * //=> 'http://sindresorhus.com' - */ - readonly removeTrailingSlash?: boolean; + /** + Normalizes `http:` URLs to `https:`. - /** - * Removes the default directory index file from path that matches any of the provided strings or regexes. - * When `true`, the regex `/^index\.[a-z]+$/` is used. - * - * @default false - * - * @example - * - * normalizeUrl('www.sindresorhus.com/foo/default.php', { - * removeDirectoryIndex: [/^default\.[a-z]+$/] - * }); - * //=> 'http://sindresorhus.com/foo' - */ - readonly removeDirectoryIndex?: (RegExp | string)[]; + This option can't be used with the `forceHttp` option at the same time. - /** - * Sorts the query parameters alphabetically by key. - * - * @default true - * - * @example - * - * normalizeUrl('www.sindresorhus.com?b=two&a=one&c=three', { - * sortQueryParameters: false - * }); - * //=> 'http://sindresorhus.com/?b=two&a=one&c=three' - */ - readonly sortQueryParameters?: boolean; + @default false + + @example + ``` + normalizeUrl('https://sindresorhus.com:80/'); + //=> 'https://sindresorhus.com' + + normalizeUrl('http://sindresorhus.com:80/', {forceHttps: true}); + //=> 'https://sindresorhus.com' + ``` + */ + readonly forceHttps?: boolean; + + /** + Strip the [authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) part of a URL. + + @default true + + @example + ``` + normalizeUrl('user:password@sindresorhus.com'); + //=> 'https://sindresorhus.com' + + normalizeUrl('user:password@sindresorhus.com', {stripAuthentication: false}); + //=> 'https://user:password@sindresorhus.com' + ``` + */ + readonly stripAuthentication?: boolean; + + /** + Removes hash from the URL. + + @default false + + @example + ``` + normalizeUrl('sindresorhus.com/about.html#contact'); + //=> 'http://sindresorhus.com/about.html#contact' + + normalizeUrl('sindresorhus.com/about.html#contact', {stripHash: true}); + //=> 'http://sindresorhus.com/about.html' + ``` + */ + readonly stripHash?: boolean; + + /** + Removes HTTP(S) protocol from an URL `http://sindresorhus.com` → `sindresorhus.com`. + + @default false + + @example + ``` + normalizeUrl('https://sindresorhus.com'); + //=> 'https://sindresorhus.com' + + normalizeUrl('sindresorhus.com', {stripProtocol: true}); + //=> 'sindresorhus.com' + ``` + */ + readonly stripProtocol?: boolean; + + /** + Removes `www.` from the URL. + + @default true + + @example + ``` + normalizeUrl('http://www.sindresorhus.com'); + //=> 'http://sindresorhus.com' + + normalizeUrl('http://www.sindresorhus.com', {stripWWW: false}); + //=> 'http://www.sindresorhus.com' + ``` + */ + readonly stripWWW?: boolean; + + /** + Removes query parameters that matches any of the provided strings or regexes. + + @default [/^utm_\w+/i] + + @example + ``` + normalizeUrl('www.sindresorhus.com?foo=bar&ref=test_ref', { + removeQueryParameters: ['ref'] + }); + //=> 'http://sindresorhus.com/?foo=bar' + ``` + */ + readonly removeQueryParameters?: (RegExp | string)[]; + + /** + Removes trailing slash. + + __Note__: Trailing slash is always removed if the URL doesn't have a pathname. + + @default true + + @example + ``` + normalizeUrl('http://sindresorhus.com/redirect/'); + //=> 'http://sindresorhus.com/redirect' + + normalizeUrl('http://sindresorhus.com/redirect/', {removeTrailingSlash: false}); + //=> 'http://sindresorhus.com/redirect/' + + normalizeUrl('http://sindresorhus.com/', {removeTrailingSlash: false}); + //=> 'http://sindresorhus.com' + ``` + */ + readonly removeTrailingSlash?: boolean; + + /** + Removes the default directory index file from path that matches any of the provided strings or regexes. + When `true`, the regex `/^index\.[a-z]+$/` is used. + + @default false + + @example + ``` + normalizeUrl('www.sindresorhus.com/foo/default.php', { + removeDirectoryIndex: [/^default\.[a-z]+$/] + }); + //=> 'http://sindresorhus.com/foo' + ``` + */ + readonly removeDirectoryIndex?: (RegExp | string)[]; + + /** + Sorts the query parameters alphabetically by key. + + @default true + + @example + ``` + normalizeUrl('www.sindresorhus.com?b=two&a=one&c=three', { + sortQueryParameters: false + }); + //=> 'http://sindresorhus.com/?b=two&a=one&c=three' + ``` + */ + readonly sortQueryParameters?: boolean; + } } -/** - * [Normalize](https://en.wikipedia.org/wiki/URL_normalization) a URL. - * - * @param url - URL to normalize. - */ -export default function normalizeUrl(url: string, options?: Options): string; +declare const normalizeUrl: { + /** + [Normalize](https://en.wikipedia.org/wiki/URL_normalization) a URL. + + @param url - URL to normalize. + + @example + ``` + import normalizeUrl = require('normalize-url'); + + normalizeUrl('sindresorhus.com'); + //=> 'http://sindresorhus.com' + + normalizeUrl('HTTP://xn--xample-hva.com:80/?b=bar&a=foo'); + //=> 'http://êxample.com/?a=foo&b=bar' + ``` + */ + (url: string, options?: normalizeUrl.Options): string; + + // TODO: Remove this for the next major release, refactor the whole definition to: + // declare function normalizeUrl(url: string, options?: normalizeUrl.Options): string; + // export = normalizeUrl; + default: typeof normalizeUrl; +}; + +export = normalizeUrl; diff --git a/index.js b/index.js index d11ffb3..ac386a0 100644 --- a/index.js +++ b/index.js @@ -156,4 +156,5 @@ const normalizeUrl = (urlString, options) => { }; module.exports = normalizeUrl; +// TODO: Remove this for the next major release module.exports.default = normalizeUrl; diff --git a/index.test-d.ts b/index.test-d.ts index dad80be..104541f 100644 --- a/index.test-d.ts +++ b/index.test-d.ts @@ -1,5 +1,5 @@ -import {expectType} from 'tsd-check'; -import normalizeUrl from '.'; +import {expectType} from 'tsd'; +import normalizeUrl = require('.'); expectType(normalizeUrl('sindresorhus.com')); expectType(normalizeUrl('HTTP://xn--xample-hva.com:80/?b=bar&a=foo')); diff --git a/package.json b/package.json index 4b968a3..f839057 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "normalize-url", - "version": "4.2.0", + "version": "4.3.0", "description": "Normalize a URL", "license": "MIT", "repository": "sindresorhus/normalize-url", @@ -13,7 +13,7 @@ "node": ">=8" }, "scripts": { - "test": "xo && nyc ava && tsd-check" + "test": "xo && nyc ava && tsd" }, "files": [ "index.js", @@ -35,10 +35,10 @@ "canonical" ], "devDependencies": { - "ava": "^1.2.1", - "coveralls": "^3.0.0", - "nyc": "^13.1.0", - "tsd-check": "^0.3.0", + "ava": "^1.4.1", + "coveralls": "^3.0.3", + "nyc": "^13.3.0", + "tsd": "^0.7.2", "xo": "^0.24.0" } }