refact: Migrate $helper.url to TypeScript

distantnative · distantnative · commit 4d19c4eb995e · 2026-02-28T13:18:10.000+01:00
diff --git a/panel/lab/internals/helpers/url/index.php b/panel/lab/internals/helpers/url/index.php
@@ -1,5 +1,5 @@
 <?php
 
 return [
-	'source' => 'panel/src/helpers/url.js'
+	'source' => 'panel/src/helpers/url.ts'
 ];
diff --git a/panel/src/helpers/index.js b/panel/src/helpers/index.js
@@ -17,7 +17,7 @@ import sort from "./sort.js";
 import string from "./string";
 import throttle from "./throttle";
 import upload from "./upload.js";
-import url from "./url.js";
+import url from "./url";
 import writer from "./writer.js";
 
 import "./regex";
diff --git a/panel/src/helpers/url.base.test.ts b/panel/src/helpers/url.base.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import url from "./url.js";
+import url from "./url";
 
 describe("$helper.url.base", () => {
 	it("should return the origin", () => {
diff --git a/panel/src/helpers/url.buildQuery.test.ts b/panel/src/helpers/url.buildQuery.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import url from "./url.js";
+import url from "./url";
 
 describe("$helper.url.buildQuery", () => {
 	it("should build query", () => {
diff --git a/panel/src/helpers/url.buildUrl.test.ts b/panel/src/helpers/url.buildUrl.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import url from "./url.js";
+import url from "./url";
 
 describe("$helper.url.buildUrl", () => {
 	it("should build Url", () => {
diff --git a/panel/src/helpers/url.isAbsolute.test.ts b/panel/src/helpers/url.isAbsolute.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import url from "./url.js";
+import url from "./url";
 
 describe("$helper.url.isAbsolute", () => {
 	it("should work", () => {
diff --git a/panel/src/helpers/url.isSameOrigin.test.ts b/panel/src/helpers/url.isSameOrigin.test.ts
@@ -1,8 +1,8 @@
-import { describe, expect, it } from "vitest";
-import url from "./url.js";
+import { describe, expect, it, vi } from "vitest";
+import url from "./url";
 
 describe("$helper.url.isSameOrigin", () => {
-	window.location = new URL("https://test.com");
+	vi.stubGlobal("location", new URL("https://test.com"));
 
 	it("should detect same origin", () => {
 		const input = "https://test.com";
diff --git a/panel/src/helpers/url.isUrl.test.ts b/panel/src/helpers/url.isUrl.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import url from "./url.js";
+import url from "./url";
 import urls from "@/../../tests/Toolkit/fixtures/urls.json";
 
 describe("$helper.url.isUrl", () => {
diff --git a/panel/src/helpers/url.makeAbsolute.test.ts b/panel/src/helpers/url.makeAbsolute.test.ts
@@ -1,5 +1,5 @@
-import { describe, expect, it } from "vitest";
-import url from "./url.js";
+import { describe, expect, it, vi } from "vitest";
+import url from "./url";
 
 describe("$helper.url.makeAbsolute", () => {
 	it("should not touch absolute URLs", () => {
@@ -8,7 +8,7 @@ describe("$helper.url.makeAbsolute", () => {
 	});
 
 	it("should make URLs absolute", () => {
-		window.location = new URL("https://getkirby.com");
+		vi.stubGlobal("location", new URL("https://getkirby.com"));
 
 		const result = url.makeAbsolute("/foo");
 		expect(result).toStrictEqual("https://getkirby.com/foo");
diff --git a/panel/src/helpers/url.toObject.test.ts b/panel/src/helpers/url.toObject.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import url from "./url.js";
+import url from "./url";
 
 describe("$helper.url.toObject", () => {
 	it("should convert string", () => {
diff --git a/panel/src/helpers/url.ts b/panel/src/helpers/url.ts
@@ -1,10 +1,8 @@
 /**
  * Returns the base URL from the <base> element
- *
  * @since 4.0.0
- * @returns {URL}
  */
-export function base() {
+export function base(): URL {
 	return new URL(
 		document.querySelector("base")?.href ?? window.location.origin
 	);
@@ -13,18 +11,14 @@ export function base() {
 /**
  * Turns the given object into an URL query string
  * and appends it, if given, to the query of the origin
- *
  * @since 4.0.0
- * @param {object} query
- * @param {string|URL} origin
- * @returns {string}
  */
-export function buildQuery(query = {}, origin = {}) {
-	if (origin instanceof URL) {
-		origin = origin.search;
-	}
-
-	const params = new URLSearchParams(origin);
+export function buildQuery(
+	query: Record<string, string | null> = {},
+	origin: string | Record<string, string> | URL = {}
+): URLSearchParams {
+	const search = origin instanceof URL ? origin.search : origin;
+	const params = new URLSearchParams(search);
 
 	// add all data params unless they are empty/null
 	for (const [key, value] of Object.entries(query)) {
@@ -40,63 +34,55 @@ export function buildQuery(query = {}, origin = {}) {
  * Builds a full URL object based on the
  * given path or another URL object and query data
  * @since 4.0.0
- *
- * @param {string|URL} url
- * @param {Object} query
- * @param {string|URL} origin
- * @returns {URL}
  */
-export function buildUrl(url = "", query = {}, origin) {
-	url = toObject(url, origin);
-	url.search = buildQuery(query, url.search);
-
-	return url;
+export function buildUrl(
+	url: string | URL = "",
+	query: Record<string, string | null> = {},
+	origin?: string | URL
+): URL {
+	const result = toObject(url, origin);
+	result.search = String(buildQuery(query, result.search));
+	return result;
 }
 
 /**
  * Checks if the url string is absolute
  * @since 4.0.0
- *
- * @param {string} url
- * @returns {boolean}
  */
-export function isAbsolute(url) {
+export function isAbsolute(url: unknown): boolean {
 	return String(url).match(/^https?:\/\//) !== null;
 }
 
 /**
  * Checks if the url is on the same origin
  * @since 4.0.0
- *
- * @param {string} url
- * @returns {boolean}
  */
-export function isSameOrigin(url) {
+export function isSameOrigin(url: string | URL): boolean {
 	return toObject(url).origin === window.location.origin;
 }
 
 /**
  * Checks if the given argument is a URL
  * @since 4.0.0
  *
- * @param {string|URL} url
- * @param {boolean} strict Whether to also check the URL against Kirby's URL validator
- * @returns {boolean}
+ * @param strict - Whether to also check the URL against Kirby's URL validator
  */
-export function isUrl(url, strict) {
-	if (url instanceof URL || url instanceof Location) {
-		url = url.toString();
-	}
+export function isUrl(url: unknown, strict: boolean = false): boolean {
+	let normalized: string;
 
-	if (typeof url !== "string") {
+	if (url instanceof URL || url instanceof Location) {
+		normalized = url.toString();
+	} else if (typeof url === "string") {
+		normalized = url;
+	} else {
 		return false;
 	}
 
 	// check if the given URL can be
 	// converted to a URL object to
 	// validate it
 	try {
-		new URL(url, window.location);
+		new URL(normalized, window.location.href);
 	} catch {
 		return false;
 	}
@@ -106,7 +92,7 @@ export function isUrl(url, strict) {
 	if (strict === true) {
 		const regex =
 			/^(?:(?:(?:https?|ftp):)?\/\/)(?:\S+(?::\S*)?@)?(?:(?!(?:10)(?:\.\d{1,3}){3})(?!(?:169\.254|192\.168)(?:\.\d{1,3}){2})(?!172\.(?:1[6-9]|2\d|3[0-1])(?:\.\d{1,3}){2})(?:[1-9]\d?|1\d\d|2[01]\d|22[0-3])(?:\.(?:1?\d{1,2}|2[0-4]\d|25[0-5])){2}(?:\.(?:[1-9]\d?|1\d\d|2[0-4]\d|25[0-4]))|(?:localhost)|(?:[a-z0-9\u00a1-\uffff](?:[a-z0-9\u00a1-\uffff_-]{0,62}[a-z0-9\u00a1-\uffff])?\.)+(?:[a-z\u00a1-\uffff]{2,}))(?::\d{2,5})?(?:[/?#]\S*)?$/i;
-		return regex.test(url);
+		return regex.test(normalized);
 	}
 
 	return true;
@@ -115,33 +101,24 @@ export function isUrl(url, strict) {
 /**
  * Make sure the URL is absolute
  * @since 4.0.0
- *
- * @param {string} path
- * @param {string|URL} origin
- * @returns {string}
  */
-export function makeAbsolute(path, origin) {
+export function makeAbsolute(path: string, origin?: string | URL): string {
 	if (isAbsolute(path) === true) {
 		return path;
 	}
 
-	origin ??= base();
-	origin = String(origin).replaceAll(/\/$/g, "");
-	path = String(path).replaceAll(/^\//g, "");
+	const originStr = String(origin ?? base()).replaceAll(/\/$/g, "");
+	const pathStr = path.replaceAll(/^\//g, "");
 
-	return origin + "/" + path;
+	return originStr + "/" + pathStr;
 }
 
 /**
  * Converts any given url to a URL object
  * @since 4.0.0
- *
- * @param {string|URL} url
- * @param {string|URL} origin
- * @returns {URL}
  */
-export function toObject(url, origin) {
-	return url instanceof URL ? url : new URL(makeAbsolute(url, origin));
+export function toObject(url: string | URL, origin?: string | URL): URL {
+	return url instanceof URL ? url : new URL(makeAbsolute(String(url), origin));
 }
 
 export default {
diff --git a/panel/src/panel/panel.js b/panel/src/panel/panel.js
@@ -14,7 +14,7 @@ import Search from "./search.js";
 import System from "./system.js";
 import Theme from "./theme.js";
 import Translation from "./translation.js";
-import { buildUrl, isUrl } from "@/helpers/url.js";
+import { buildUrl, isUrl } from "@/helpers/url";
 import { reactive } from "vue";
 import { redirect, request } from "./request.js";
 import Upload from "./upload.js";
diff --git a/panel/src/panel/request.js b/panel/src/panel/request.js
@@ -1,5 +1,5 @@
-import { buildUrl, isSameOrigin, makeAbsolute } from "@/helpers/url.js";
 import { toLowerKeys } from "../helpers/object";
+import { buildUrl, isSameOrigin, makeAbsolute } from "@/helpers/url";
 import AuthError from "@/errors/AuthError.js";
 import JsonRequestError from "@/errors/JsonRequestError.js";
 import OfflineError from "@/errors/OfflineError.js";
