trousse 2.4.0 → 2.6.0

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/trousse.svg)](https://www.npmjs.com/package/trousse)
 [![license](https://img.shields.io/npm/l/trousse.svg)](https://github.com/macieklamberski/trousse/blob/main/LICENSE)
 
-Personal toolbox of shared TypeScript utilities used across my projects: type guards, coercions, matching, array, object and locale interpolation helpers.
+Personal toolbox of shared TypeScript utilities used across my projects: type guards, coercions, matching, URL, array, object and locale interpolation helpers.
 
 ## Installation
 

package/dist/files.d.ts

@@ -0,0 +1,12 @@
+//#region src/files.d.ts
+export declare const audioExtensions: string[];
+export declare const videoExtensions: string[];
+export declare const imageExtensions: string[];
+export declare const documentExtensions: string[];
+export declare const archiveExtensions: string[];
+export declare const installerExtensions: string[];
+export declare const flashExtensions: string[];
+export declare const codeExtensions: string[];
+export declare const fontExtensions: string[];
+export declare const subtitleExtensions: string[];
+//#endregion

package/dist/files.js

@@ -0,0 +1,101 @@
+//#region src/files.ts
+const audioExtensions = [
+	"aac",
+	"aif",
+	"aiff",
+	"amr",
+	"flac",
+	"m4a",
+	"m4b",
+	"mid",
+	"midi",
+	"mka",
+	"mp3",
+	"oga",
+	"ogg",
+	"opus",
+	"wav",
+	"weba",
+	"wma"
+];
+const videoExtensions = [
+	"3gp",
+	"avi",
+	"flv",
+	"m4v",
+	"mkv",
+	"mov",
+	"mp4",
+	"mpeg",
+	"mpg",
+	"ogv",
+	"webm",
+	"wmv"
+];
+const imageExtensions = [
+	"avif",
+	"bmp",
+	"gif",
+	"heic",
+	"heif",
+	"ico",
+	"jpeg",
+	"jpg",
+	"jxl",
+	"png",
+	"svg",
+	"tif",
+	"tiff",
+	"webp"
+];
+const documentExtensions = [
+	"doc",
+	"docx",
+	"epub",
+	"mobi",
+	"odp",
+	"ods",
+	"odt",
+	"pdf",
+	"ppt",
+	"pptx",
+	"rtf",
+	"xls",
+	"xlsx"
+];
+const archiveExtensions = [
+	"7z",
+	"bz2",
+	"gz",
+	"rar",
+	"tar",
+	"tgz",
+	"xz",
+	"zip"
+];
+const installerExtensions = [
+	"apk",
+	"deb",
+	"dmg",
+	"exe",
+	"iso",
+	"msi",
+	"pkg",
+	"rpm"
+];
+const flashExtensions = ["swf"];
+const codeExtensions = [
+	"css",
+	"js",
+	"mjs"
+];
+const fontExtensions = [
+	"eot",
+	"otf",
+	"ttf",
+	"woff",
+	"woff2"
+];
+const subtitleExtensions = ["srt", "vtt"];
+//#endregion
+export { archiveExtensions, audioExtensions, codeExtensions, documentExtensions, flashExtensions, fontExtensions, imageExtensions, installerExtensions, subtitleExtensions, videoExtensions };

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import { omitEmpty } from "./arrays.js";
-import { AnyOf, DeepOmit, IsPlainObject, MaybePromise, Nullish, PartialNullish, Pattern } from "./types.js";
+import { AnyOf, DeepOmit, IsPlainObject, MaybePromise, NormalizeOptions, Nullish, PartialNullish, Pattern } from "./types.js";
 import { coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString } from "./coercions.js";
+import { archiveExtensions, audioExtensions, codeExtensions, documentExtensions, flashExtensions, fontExtensions, imageExtensions, installerExtensions, subtitleExtensions, videoExtensions } from "./files.js";
 import { isBoolean, isFunction, isNonEmptyString, isNullish, isNumber, isObject, isPlainObject, isPresent, isString, isValidDate } from "./is.js";
 import { isJsonLike, isParseableJson } from "./json.js";
 import { escapeHtml, t, tx } from "./locales.js";
 import { anyWordMatchesAnyOf, endsWithAnyOf, escapeRegex, getAnyOf, includesAnyOf, isAnyOf, startsWithAnyOf } from "./matching.js";
 import { omit, pick, toMap, trimObject } from "./objects.js";
 import { sleep } from "./timers.js";
-import { decodeSegment, getPathSegments, getSubdomain, isHostOf, isHostOrSubdomainOf, isHttpUrl, isSubdomainOf, parseUrl } from "./urls.js";
-export { type AnyOf, type DeepOmit, type IsPlainObject, type MaybePromise, type Nullish, type PartialNullish, type Pattern, anyWordMatchesAnyOf, coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString, decodeSegment, endsWithAnyOf, escapeHtml, escapeRegex, getAnyOf, getPathSegments, getSubdomain, includesAnyOf, isAnyOf, isBoolean, isFunction, isHostOf, isHostOrSubdomainOf, isHttpUrl, isJsonLike, isNonEmptyString, isNullish, isNumber, isObject, isParseableJson, isPlainObject, isPresent, isString, isSubdomainOf, isValidDate, omit, omitEmpty, parseUrl, pick, sleep, startsWithAnyOf, t, toMap, trimObject, tx };
+import { addMissingProtocol, decodeSegment, fixMalformedProtocol, getPathSegments, getRegistrableDomain, getSubdomain, isHostOf, isHostOrSubdomainOf, isHttpUrl, isIpAddress, isSubdomainOf, normalizeUrl, parseUrl, resolveFeedProtocol, resolveUrl, stripWww, upgradeProtocol } from "./urls.js";
+export { type AnyOf, type DeepOmit, type IsPlainObject, type MaybePromise, type NormalizeOptions, type Nullish, type PartialNullish, type Pattern, addMissingProtocol, anyWordMatchesAnyOf, archiveExtensions, audioExtensions, codeExtensions, coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString, decodeSegment, documentExtensions, endsWithAnyOf, escapeHtml, escapeRegex, fixMalformedProtocol, flashExtensions, fontExtensions, getAnyOf, getPathSegments, getRegistrableDomain, getSubdomain, imageExtensions, includesAnyOf, installerExtensions, isAnyOf, isBoolean, isFunction, isHostOf, isHostOrSubdomainOf, isHttpUrl, isIpAddress, isJsonLike, isNonEmptyString, isNullish, isNumber, isObject, isParseableJson, isPlainObject, isPresent, isString, isSubdomainOf, isValidDate, normalizeUrl, omit, omitEmpty, parseUrl, pick, resolveFeedProtocol, resolveUrl, sleep, startsWithAnyOf, stripWww, subtitleExtensions, t, toMap, trimObject, tx, upgradeProtocol, videoExtensions };

package/dist/index.js

@@ -1,10 +1,11 @@
 import { isBoolean, isFunction, isNonEmptyString, isNullish, isNumber, isObject, isPlainObject, isPresent, isString, isValidDate } from "./is.js";
 import { omitEmpty } from "./arrays.js";
 import { coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString } from "./coercions.js";
+import { archiveExtensions, audioExtensions, codeExtensions, documentExtensions, flashExtensions, fontExtensions, imageExtensions, installerExtensions, subtitleExtensions, videoExtensions } from "./files.js";
 import { isJsonLike, isParseableJson } from "./json.js";
 import { escapeHtml, t, tx } from "./locales.js";
 import { anyWordMatchesAnyOf, endsWithAnyOf, escapeRegex, getAnyOf, includesAnyOf, isAnyOf, startsWithAnyOf } from "./matching.js";
 import { omit, pick, toMap, trimObject } from "./objects.js";
 import { sleep } from "./timers.js";
-import { decodeSegment, getPathSegments, getSubdomain, isHostOf, isHostOrSubdomainOf, isHttpUrl, isSubdomainOf, parseUrl } from "./urls.js";
-export { anyWordMatchesAnyOf, coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString, decodeSegment, endsWithAnyOf, escapeHtml, escapeRegex, getAnyOf, getPathSegments, getSubdomain, includesAnyOf, isAnyOf, isBoolean, isFunction, isHostOf, isHostOrSubdomainOf, isHttpUrl, isJsonLike, isNonEmptyString, isNullish, isNumber, isObject, isParseableJson, isPlainObject, isPresent, isString, isSubdomainOf, isValidDate, omit, omitEmpty, parseUrl, pick, sleep, startsWithAnyOf, t, toMap, trimObject, tx };
+import { addMissingProtocol, decodeSegment, fixMalformedProtocol, getPathSegments, getRegistrableDomain, getSubdomain, isHostOf, isHostOrSubdomainOf, isHttpUrl, isIpAddress, isSubdomainOf, normalizeUrl, parseUrl, resolveFeedProtocol, resolveUrl, stripWww, upgradeProtocol } from "./urls.js";
+export { addMissingProtocol, anyWordMatchesAnyOf, archiveExtensions, audioExtensions, codeExtensions, coerceArray, coerceBoolean, coerceDate, coerceNumber, coerceSingular, coerceString, decodeSegment, documentExtensions, endsWithAnyOf, escapeHtml, escapeRegex, fixMalformedProtocol, flashExtensions, fontExtensions, getAnyOf, getPathSegments, getRegistrableDomain, getSubdomain, imageExtensions, includesAnyOf, installerExtensions, isAnyOf, isBoolean, isFunction, isHostOf, isHostOrSubdomainOf, isHttpUrl, isIpAddress, isJsonLike, isNonEmptyString, isNullish, isNumber, isObject, isParseableJson, isPlainObject, isPresent, isString, isSubdomainOf, isValidDate, normalizeUrl, omit, omitEmpty, parseUrl, pick, resolveFeedProtocol, resolveUrl, sleep, startsWithAnyOf, stripWww, subtitleExtensions, t, toMap, trimObject, tx, upgradeProtocol, videoExtensions };

package/dist/types.d.ts

@@ -6,4 +6,20 @@ export type Nullish<T> = T | null | undefined;
 export type PartialNullish<T> = { [Key in keyof T]?: Nullish<T[Key]>; };
 export type MaybePromise<T> = T | Promise<T>;
 export type Pattern = string | RegExp;
+export type NormalizeOptions = {
+  stripProtocol?: boolean;
+  stripAuthentication?: boolean;
+  stripWww?: boolean;
+  stripTrailingSlash?: boolean;
+  stripRootSlash?: boolean;
+  collapseSlashes?: boolean;
+  stripHash?: boolean;
+  sortQueryParams?: boolean;
+  stripQueryParams?: Array<string>;
+  stripQuery?: boolean;
+  stripEmptyQuery?: boolean;
+  lowercaseQuery?: boolean;
+  normalizeEncoding?: boolean;
+  normalizeUnicode?: boolean;
+};
 //#endregion

package/dist/urls.d.ts

@@ -1,3 +1,4 @@
+import { NormalizeOptions } from "./types.js";
 //#region src/urls.d.ts
 export declare const parseUrl: (value: string | URL, base?: string | URL) => URL | undefined;
 export declare const getPathSegments: (value: string | URL) => Array<string>;
@@ -7,4 +8,13 @@ export declare const isHttpUrl: (url: string | URL) => boolean;
 export declare const isHostOrSubdomainOf: (url: string | URL, domains: string | ReadonlyArray<string>) => boolean;
 export declare const getSubdomain: (url: string | URL, domains: string | ReadonlyArray<string>) => string | undefined;
 export declare const decodeSegment: (segment: string | undefined) => string | undefined;
+export declare const fixMalformedProtocol: (url: string) => string;
+export declare const resolveFeedProtocol: (url: string, protocol?: 'http' | 'https') => string;
+export declare const addMissingProtocol: (url: string, protocol?: 'http' | 'https') => string;
+export declare const upgradeProtocol: (url: string, protocol?: 'http' | 'https') => string;
+export declare const resolveUrl: (url: string, base?: string) => string | undefined;
+export declare const normalizeUrl: (url: string, options: NormalizeOptions) => string;
+export declare const stripWww: (hostname: string) => string;
+export declare const isIpAddress: (hostname: string) => boolean;
+export declare const getRegistrableDomain: (url: string | URL) => string | undefined;
 //#endregion

package/dist/urls.js

@@ -1,4 +1,5 @@
 import { endsWithAnyOf, isAnyOf } from "./matching.js";
+import { decodeHTMLStrict } from "entities";
 //#region src/urls.ts
 const httpProtocols = ["http:", "https:"];
 const parseUrl = (value, base) => {
@@ -43,5 +44,218 @@ const decodeSegment = (segment) => {
 		return decodeURIComponent(segment);
 	} catch {}
 };
+const strippedParamsCache = /* @__PURE__ */ new WeakMap();
+const getStrippedParamsSet = (params) => {
+	let cached = strippedParamsCache.get(params);
+	if (!cached) {
+		cached = new Set(params.map((param) => param.toLowerCase()));
+		strippedParamsCache.set(params, cached);
+	}
+	return cached;
+};
+const ipv4Regex = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+const ipv6Regex = /^([0-9a-f]{0,4}:){2,7}[0-9a-f]{0,4}$/i;
+const wwwPrefixRegex = /^www\./;
+const ipv6BracketsRegex = /^\[|\]$/g;
+const safePathCharsRegex = /[a-zA-Z0-9._~!$&'()*+,;=:@-]/;
+const httpsLetterRegex = /s/i;
+const protocolPrefixRegex = /^https?:\/\//;
+const percentEscapeOrLettersRegex = /%[0-9A-Fa-f]{2}|[A-Z]+/g;
+const plusRegex = /\+/g;
+const httpProtocolRegex = /^http:\/\//i;
+const httpsProtocolRegex = /^https:\/\//i;
+const leadingWhitespaceChars = [
+	" ",
+	"	",
+	"\n"
+];
+const validUrlRegex = /^https?:\/\/(?:www\.|[a-vx-z0-9])/i;
+const schemeSeparator = String.raw`\.*[:\s=\\/][:\s=.\\/]*`;
+const doubledProtocolRegex = new RegExp(String.raw`^\/?[htps]{2,7}${schemeSeparator}([htps]{2,7})${schemeSeparator}[.,:/]*(www[./]+)?`, "i");
+const singleMalformedRegex = new RegExp(String.raw`^\/?(?:h[htps():]{1,10}|t{1,2}ps?)${schemeSeparator}[.,:/]*(www[./]+)?`, "i");
+const fixMalformedProtocol = (url) => {
+	if (validUrlRegex.test(url) && !doubledProtocolRegex.test(url)) return url;
+	const doubledMatch = doubledProtocolRegex.exec(url);
+	if (doubledMatch) {
+		const inner = doubledMatch[1];
+		const www = doubledMatch[2];
+		const rest = url.slice(doubledMatch[0].length);
+		return (httpsLetterRegex.test(inner) ? "https://" : "http://") + (www ? "www." : "") + rest;
+	}
+	const singleMatch = singleMalformedRegex.exec(url);
+	if (singleMatch) {
+		const fullMatch = singleMatch[0];
+		const www = singleMatch[1];
+		const rest = url.slice(fullMatch.length);
+		return (httpsLetterRegex.test(fullMatch) ? "https://" : "http://") + (www ? "www." : "") + rest;
+	}
+	return url;
+};
+const feedProtocols = [
+	"feed:",
+	"rss:",
+	"podcast:",
+	"podcasts:",
+	"pcast:",
+	"itpc:",
+	"itms:",
+	"itms-pcast:",
+	"itms-pcasts:",
+	"itms-podcast:",
+	"itms-podcasts:"
+];
+const resolveFeedProtocol = (url, protocol = "https") => {
+	const firstCharCode = url.charCodeAt(0) | 32;
+	if (firstCharCode !== 102 && firstCharCode !== 114 && firstCharCode !== 112 && firstCharCode !== 105) return url;
+	const urlLower = url.toLowerCase();
+	for (const scheme of feedProtocols) {
+		if (!urlLower.startsWith(scheme)) continue;
+		if (urlLower.startsWith(`${scheme}http://`) || urlLower.startsWith(`${scheme}https://`)) return url.slice(scheme.length);
+		if (urlLower.startsWith(`${scheme}//`)) return `${protocol}:${url.slice(scheme.length)}`;
+	}
+	return url;
+};
+const addMissingProtocol = (url, protocol = "https") => {
+	const colonIndex = url.indexOf(":");
+	if (colonIndex > 0) {
+		const beforeColon = url.slice(0, colonIndex);
+		if (!beforeColon.includes(".") && !beforeColon.includes("/") && beforeColon !== "localhost") return url;
+	}
+	if (url.startsWith("//") && !url.startsWith("///")) {
+		const parsed = parseUrl(`${protocol}:${url}`);
+		if (!parsed) return url;
+		const hostname = parsed.hostname;
+		if (hostname.includes(".") || hostname === "localhost" || isIpAddress(hostname)) return parsed.href;
+		return url;
+	}
+	if (url.startsWith("/") || url.startsWith(".")) return url;
+	const slashIndex = url.indexOf("/");
+	const dotIndex = url.indexOf(".");
+	if (dotIndex === -1 || slashIndex !== -1 && dotIndex > slashIndex) {
+		if (!url.startsWith("localhost")) return url;
+	}
+	const firstChar = url.charAt(0);
+	if (leadingWhitespaceChars.includes(firstChar)) return url;
+	return `${protocol}://${url}`;
+};
+const upgradeProtocol = (url, protocol = "https") => {
+	if (protocol === "https") return url.replace(httpProtocolRegex, "https://");
+	return url.replace(httpsProtocolRegex, "http://");
+};
+const resolveUrl = (url, base) => {
+	if (url.startsWith("#") && !base) return;
+	let resolvedUrl;
+	resolvedUrl = url.includes("&") ? decodeHTMLStrict(url) : url;
+	resolvedUrl = resolveFeedProtocol(resolvedUrl);
+	resolvedUrl = fixMalformedProtocol(resolvedUrl);
+	if (base) {
+		const resolved = parseUrl(resolvedUrl, base);
+		if (!resolved) return;
+		if (isHttpUrl(resolved)) return resolved.href;
+		resolvedUrl = resolved.href;
+	}
+	resolvedUrl = addMissingProtocol(resolvedUrl);
+	const parsed = parseUrl(resolvedUrl);
+	if (!parsed || !isHttpUrl(parsed)) return;
+	return parsed.href;
+};
+const decodeAndNormalizeEncoding = (value) => {
+	if (!value.includes("%")) return value;
+	return value.replace(/%([0-9A-Fa-f]{2})/g, (_match, hex) => {
+		const charCode = Number.parseInt(hex, 16);
+		const char = String.fromCharCode(charCode);
+		if (safePathCharsRegex.test(char)) return char;
+		return `%${hex.toUpperCase()}`;
+	});
+};
+const decodeQueryKey = (pair) => {
+	const key = pair.split("=")[0].replace(plusRegex, " ");
+	try {
+		return decodeURIComponent(key);
+	} catch {
+		return key;
+	}
+};
+const compareQueryPairs = (a, b) => {
+	const keyA = decodeQueryKey(a);
+	const keyB = decodeQueryKey(b);
+	if (keyA < keyB) return -1;
+	if (keyA > keyB) return 1;
+	return 0;
+};
+const lowercaseQueryPair = (pair) => {
+	return pair.replace(percentEscapeOrLettersRegex, (match) => {
+		return match.startsWith("%") ? match : match.toLowerCase();
+	});
+};
+const normalizeUrl = (url, options) => {
+	try {
+		const parsed = new URL(url);
+		if (options.normalizeUnicode) {
+			parsed.hostname = parsed.hostname.normalize("NFC");
+			parsed.pathname = parsed.pathname.normalize("NFC");
+		}
+		if (options.stripAuthentication) {
+			parsed.username = "";
+			parsed.password = "";
+		}
+		if (options.stripWww) parsed.hostname = stripWww(parsed.hostname);
+		if (options.stripHash) parsed.hash = "";
+		let pathname = parsed.pathname;
+		if (options.normalizeEncoding) pathname = decodeAndNormalizeEncoding(pathname);
+		if (options.collapseSlashes) pathname = pathname.replace(/\/+/g, "/");
+		if (options.stripTrailingSlash && pathname.length > 1 && pathname.endsWith("/")) pathname = pathname.slice(0, -1);
+		if (options.stripRootSlash && pathname === "/") pathname = "";
+		parsed.pathname = pathname;
+		if (options.stripQuery) parsed.search = "";
+		if (parsed.search && (options.stripQueryParams || options.lowercaseQuery)) {
+			let pairs = parsed.search.slice(1).split("&");
+			if (options.stripQueryParams) {
+				const strippedSet = getStrippedParamsSet(options.stripQueryParams);
+				pairs = pairs.filter((pair) => !strippedSet.has(decodeQueryKey(pair).toLowerCase()));
+			}
+			if (options.lowercaseQuery) pairs = pairs.map(lowercaseQueryPair);
+			parsed.search = pairs.join("&");
+		}
+		if (options.sortQueryParams && parsed.search.includes("&")) parsed.search = parsed.search.slice(1).split("&").filter(Boolean).sort(compareQueryPairs).join("&");
+		if (options.stripEmptyQuery && parsed.href.endsWith("?")) parsed.search = "";
+		let result = parsed.href;
+		if (options.stripRootSlash && result === `${parsed.origin}/`) result = parsed.origin;
+		if (options.stripProtocol) result = result.replace(protocolPrefixRegex, "");
+		return result;
+	} catch {
+		return url;
+	}
+};
+const stripWww = (hostname) => {
+	return hostname.replace(wwwPrefixRegex, "");
+};
+const isIpAddress = (hostname) => {
+	return ipv4Regex.test(hostname) || ipv6Regex.test(hostname.replace(ipv6BracketsRegex, ""));
+};
+const genericSecondLevels = [
+	"ac",
+	"co",
+	"com",
+	"edu",
+	"go",
+	"gob",
+	"gov",
+	"id",
+	"ne",
+	"net",
+	"or",
+	"org"
+];
+const getRegistrableDomain = (url) => {
+	const hostname = parseUrl(url)?.hostname;
+	if (!hostname) return;
+	if (isIpAddress(hostname)) return hostname;
+	const parts = hostname.split(".");
+	if (parts.length <= 2) return hostname;
+	const [secondLevel, topLevel] = parts.slice(-2);
+	const labels = topLevel.length === 2 && genericSecondLevels.includes(secondLevel) ? 3 : 2;
+	return parts.slice(-labels).join(".");
+};
 //#endregion
-export { decodeSegment, getPathSegments, getSubdomain, isHostOf, isHostOrSubdomainOf, isHttpUrl, isSubdomainOf, parseUrl };
+export { addMissingProtocol, decodeSegment, fixMalformedProtocol, getPathSegments, getRegistrableDomain, getSubdomain, isHostOf, isHostOrSubdomainOf, isHttpUrl, isIpAddress, isSubdomainOf, normalizeUrl, parseUrl, resolveFeedProtocol, resolveUrl, stripWww, upgradeProtocol };

package/package.json

@@ -43,5 +43,8 @@
     "kvalita": "^1.24.0",
     "tsdown": "^0.23.0"
   },
-  "version": "2.4.0"
+  "dependencies": {
+    "entities": "^8.1.0"
+  },
+  "version": "2.6.0"
 }