feat: add improved protocol detection and handle messy strings in mak…

…eURL

README.md

@@ -83,6 +83,9 @@ Feel free to test and explore and if later on you need more guidance, read the w
     <tr>
       <td>👌 1kB <a href="https://bundlephobia.com/package/@nauverse/make-url@latest">minified and gzipped</a></td>
     </tr>
+    <tr>
+      <td>🔒 Reliable. Even when you pass really messed up strings, it finds a way to build a valid URL (just check the tests for some examples)</td>
+    </tr>
     <tr>
       <td>✍️ TypeScript types provided</td>
     </tr>

src/lib/helpers.ts

@@ -0,0 +1,381 @@
+import type {
+  IConfig,
+  IDomainData,
+  IProtocolData,
+  IURLArrayData
+} from "../types";
+
+/**
+ * Detects the domain in a given string.
+ *
+ * @param str - The string to detect the domain from. Important: To detect a valid domain, the URL must contain a non-relative protocol (http:// or https://).
+ * @returns An object containing information about the domain.
+ * @example
+ * detectDomainInString("https://example.com/blog");
+ * // => { hasDomain: true, domain: "example.com" }
+ * detectDomainInString("http://example/blog");
+ * // => { hasDomain: false, domain: "" }
+ */
+export function detectDomainInString(str: string): IDomainData {
+  // We will use "new URL(...)" to detect it
+  // If it throws an error, it means the string is not a valid URL, so probably it doesn't have a domain
+  try {
+    const url = new URL(str);
+
+    // But not throwing in the constructor does not mean it has a valid domain. For example: "https://example/blog" does not throw
+
+    // So we will check if the hostname has at least one dot and then we have greater confidence that it is a domain
+    if (url.hostname.split(".").length < 2) {
+      throw null; // We throw an error to be catched in the catch block
+    }
+
+    return {
+      hasDomain: true,
+      domain: url.hostname
+    };
+  } catch {
+    return {
+      hasDomain: false,
+      domain: ""
+    };
+  }
+}
+
+/**
+ * Detects the protocol in a given string.
+ * @param str - The string to detect the protocol from.
+ * @returns An object containing information about the protocol detection.
+ * @example
+ * detectProtocolInString("https://example.com/blog");
+ * // => { hasProtocol: true, protocol: "https" }
+ * detectProtocolInString("example.com/blog");
+ * // => { hasProtocol: false, protocol: "none" }
+ * detectProtocolInString("//example.com/blog");
+ * // => { hasProtocol: true, protocol: "relative" }
+ * detectProtocolInString("//example/blog");
+ * // => { hasProtocol: false, protocol: "relative" }
+ */
+export function detectProtocolInString(str: string): IProtocolData {
+  const cleanedStr = str.trim().toLowerCase();
+
+  if (cleanedStr.startsWith("//")) {
+    const urlToCheck = `https:${cleanedStr}`; // Since the domain detector function only works with URLs with a protocol, we add a fake non-relative protocol to the string
+    const detectDomainData = detectDomainInString(urlToCheck);
+    return {
+      hasProtocol: detectDomainData.hasDomain, // Even if it contains a valid relative protocol string, we can not count it as valid since it does not contain a valid domain
+      protocol: "relative" // It contains a valid protocol
+    };
+  }
+
+  // Regex that checks if the str starts with http or https
+  const hasProtocol = /^(http|https):\/\//.test(cleanedStr);
+  return {
+    hasProtocol,
+    protocol: hasProtocol
+      ? (cleanedStr.split("://")[0] as "http" | "https")
+      : "none"
+  };
+}
+
+/**
+ * Generates a temporary URL string by merging an array of fragments.
+ * This generated URL is not safe and should only be used for detecting the domain.
+ * Important: This should only be used when we need to detect stuff in the URL like in the `detectDomainInString` function. It should NEVER be used to generate a valid URL. For that you should use the `safeStringArrayToURLString` function.
+ *
+ * @param array - An array of string fragments to be merged.
+ * @param hasProtocol - A boolean indicating whether the array has a protocol.
+ * @returns The merged URL string.
+ * @example
+ * getUnsafeMergedURLString(["https://", "example.com", "blog"], true);
+ * // => "https://example.com/blog"
+ */
+function getUnsafeMergedURLString(
+  array: Array<string>,
+  hasProtocol: boolean
+): string {
+  // We need to generate a temporary URL to detect the domain
+  // This generated URL is not really safe, meaning it could contain
+  // unescaped character, wrong protocols, etc. But we don't care about that, since we only need it to detect the domain
+  // Just, don't use it for anything else
+  return (
+    array
+      // If the array has a protocol, we skip the first fragment
+      .slice(hasProtocol ? 1 : 0)
+      // We filter out empty fragments, keep in mind this is only for detecting the domain, so we don't care about empty fragments
+      .filter(v => v.trim() !== "")
+      // We could join using the `.join`method, but we need more control
+      // over how to join, so we use the `.map` method
+      .map((v, index) => {
+        // If it is the first item or if it contains a dot (potentially a part of the domain), we don't join with "/"
+        if (index === 0 || v.startsWith(".")) return v;
+        // Anything else is joined with "/"
+        else return `/${v}`;
+      })
+      // Previously I said "join", but it was more like modifying the fragment so we could just concatenate the array without any separator
+      .join("")
+  );
+}
+
+/**
+ * Extracts the protocol from an array of fragments based on the given protocol index.
+ *
+ * @param array - The array of fragments.
+ * @param protocolIndex - The index at which the protocol ends.
+ * @returns An array of fragments containing the extracted protocol.
+ * @example
+ * extractProtocolFromArray(["https://", "example", "", ".com", "blog"], 8);
+ * // => ["https://", "example.com", "blog"]
+ */
+function extractProtocolFromArray(
+  array: Array<string>,
+  protocolIndex: number
+): Array<string> {
+  let currentLength = 0;
+  let protocolFragment = "";
+  const returnedFragments: Array<string> = [];
+
+  array.forEach(fragment => {
+    // If the fragment is empty and there are already fragments in the returned fragments, we add the fragment to the returned fragments
+    // If there are no fragments in the returned fragments, we skip it
+    // since it could break our logic to handle the protocol and in any case it would be an empty fragment
+    if (fragment === "" && returnedFragments.length > 0) {
+      returnedFragments.push(fragment);
+      return;
+    }
+    // If the current length plus the length of the fragment is less than the protocol index, we add the fragment to the protocol fragment
+    if (currentLength + fragment.length <= protocolIndex) {
+      protocolFragment += fragment;
+      currentLength += fragment.length;
+      // If the current length is greater than the protocol index, we add the fragment to the returned fragments
+    } else if (currentLength < protocolIndex) {
+      const sliceIndex = protocolIndex - currentLength;
+      protocolFragment += fragment.slice(0, sliceIndex);
+
+      if (sliceIndex < fragment.length) {
+        returnedFragments.push(protocolFragment);
+        protocolFragment = "";
+        returnedFragments.push(fragment.slice(sliceIndex));
+      }
+
+      currentLength += sliceIndex;
+      // If the current length is equal to the protocol index, we add the fragment to the returned fragments
+    } else {
+      if (protocolFragment !== "") {
+        returnedFragments.push(protocolFragment);
+        protocolFragment = "";
+      }
+      returnedFragments.push(fragment);
+    }
+  });
+
+  if (protocolFragment !== "") {
+    returnedFragments.push(protocolFragment);
+    protocolFragment = "";
+  }
+
+  return returnedFragments;
+}
+
+/**
+ * Extracts the domain from an array of URL fragments.
+ * Important: The array entered must come from the extractProtocolFromArray function or the safeStringArrayAssembler function.
+ *
+ * @param array - The array of URL fragments.
+ * @param hasProtocolExtracted - A boolean indicating whether the protocol has been extracted from the URL.
+ * @returns An array of URL fragments with the domain extracted.
+ * @example
+ * extractDomainFromArray(["https://", "example", "", ".com", "blog"], true);
+ * // => ["https://", "example.com", "blog"]
+ * extractDomainFromArray(["example", "", ".com", "blog"], true);
+ * // => ["example.com", "blog"]
+ */
+function extractDomainFromArray(
+  array: Array<string>,
+  hasProtocolExtracted: boolean
+): Array<string> {
+  // We need to generate a temporary URL to detect the domain
+  // This generated URL is not really safe, meaning it could contain
+  // unescaped character, wrong protocols, etc. But we don't care about that, since we only need it to detect the domain
+  // Just, don't use it for anything else
+  const tempURL = getUnsafeMergedURLString(array, hasProtocolExtracted);
+
+  // Resulting URL has no protocol (we removed it if it was there to remove the case of relative protocols, incompatible with the `detectDomainInString` function)
+  // But the `detectDomainInString` function needs an input URL with a protocol, so we add a fake one
+  const domainData = detectDomainInString(`https://${tempURL}`);
+
+  // If the URL does not contain a domain, there is nothing to "extract"/"sort", so we return the array as is
+  if (!domainData.hasDomain) return array;
+
+  // if it contains a domain, we find the index position of the last character of the domain
+  const domainIndex =
+    tempURL.indexOf(domainData.domain) + domainData.domain.length;
+
+  // We need to create an array with the domain fragments but without the protocol (if it has one)
+  const safeArray = array.slice(hasProtocolExtracted ? 1 : 0);
+
+  let domainFragment = "";
+  let currentLength = 0;
+
+  // This will be the array of fragments we will return
+  let returnedFragments: Array<string> = [];
+
+  safeArray.forEach(fragment => {
+    // We will filter out empty strings
+    if (fragment === "") {
+      // We need to check first if the current length is greater or equal than the domain index, because that means we already found the full domain in the array
+      if (currentLength >= domainIndex) {
+        // If the returnedFragments has some item, that means we already found the domain and we already saved it, so we can just push the empty fragment into the array
+        if (returnedFragments.length > 0) {
+          returnedFragments.push(fragment);
+        } else {
+          // If the returnedFragments is empty, that means we haven't saved the domain yet into the array
+          // But since we already found it, we can just push it to the array
+          returnedFragments.push(domainFragment);
+          domainFragment = "";
+          // And then we can push the empty fragment into the array
+          returnedFragments.push(fragment);
+        }
+      }
+      return;
+    }
+
+    // If the current length plus the length of the fragment is less than the domain index, we add the fragment to the domain fragment
+    if (currentLength + fragment.length <= domainIndex) {
+      domainFragment += fragment;
+      currentLength += fragment.length;
+    } else if (currentLength < domainIndex) {
+      const sliceIndex = domainIndex - currentLength;
+      domainFragment += fragment.slice(0, sliceIndex);
+
+      // If the sliceIndex is less than the length of the fragment, we push the domain fragment into the array and then we push the rest of the fragment
+      if (sliceIndex < fragment.length) {
+        returnedFragments.push(domainFragment);
+        domainFragment = "";
+        returnedFragments.push(fragment.slice(sliceIndex));
+      }
+
+      currentLength += sliceIndex;
+      // If the current length is equal to the domain index, we add the fragment to the returned fragments
+    } else {
+      // If the domain fragment is not empty, we push it to the array
+      if (domainFragment !== "") {
+        returnedFragments.push(domainFragment);
+        domainFragment = "";
+      }
+
+      // Then we push the fragment to the array
+      returnedFragments.push(fragment);
+    }
+  });
+
+  // If the domain fragment is not empty, we push it to the array
+  if (domainFragment !== "") {
+    returnedFragments.push(domainFragment);
+    domainFragment = "";
+  }
+
+  // If the array had a protocol we have to add it back at the beginning
+  // of the array before returning it
+  if (hasProtocolExtracted) {
+    returnedFragments = [array[0], ...returnedFragments];
+  }
+
+  return returnedFragments;
+}
+
+/**
+ * Assembles a safe string array by filtering out empty strings and detecting protocols.
+ * @param fragments - An array of strings representing URL fragments.
+ * @param config - The configuration object.
+ * @returns An object containing the assembled URL fragments, information about the presence of a protocol, and the detected protocol.
+ * @example
+ * safeStringArrayAssembler(["https://", "example.com", "blog"]);
+ * // => { array: ["https://", "example.com", "blog"], hasProtocol: true, protocol: "https" }
+ * safeStringArrayAssembler(["example.com", "blog"]);
+ * // => { array: ["example.com", "blog"], hasProtocol: false, protocol: "none" }
+ * safeStringArrayAssembler(["//", "example.com", "blog"]);
+ * // => { array: ["//", "example.com", "blog"], hasProtocol: true, protocol: "relative" }
+ * safeStringArrayAssembler(["https://example.com", "blog", ""]);
+ * // => { array: ["https://", "example.com", "blog"], hasProtocol: true, protocol: "https" }
+ */
+export function safeStringArrayAssembler(
+  fragments: Array<string>,
+  config: IConfig
+): IURLArrayData {
+  // We will filter out empty strings
+  let filteredFragments = [...fragments];
+
+  // If "allowEmptyPathSegments" is false, we can clean empty path segments
+  // but if it is true, we can not because those empty fragments will be joined later with slashes, so technically the final URL wouldn't be what we expect.
+  // For example, if we have ["example.com", "", "blog"], the final URL should be "example.com//blog" instead of "example.com/blog" if "allowEmptyPathSegments" is true
+  if (!config.allowEmptyPathSegments) {
+    filteredFragments = filteredFragments.filter(
+      fragment => fragment.trim() !== ""
+    );
+  }
+
+  // Now we need to detect if it contains a protocol
+  const potentiallyWrongJoinedURL = filteredFragments.join(""); // We don't use here the getUnsafeMergedURLString function because it would fail, since it requires to have already detected the protocol
+  const { hasProtocol, protocol } = detectProtocolInString(
+    potentiallyWrongJoinedURL
+  );
+
+  // We need to join all the fragments until the end of the protocol (if it has one)
+  let returnedFragments: Array<string> = filteredFragments;
+
+  if (hasProtocol) {
+    // If it has a protocol, we need to find the index of the end of the protocol
+    const protocolIndex =
+      potentiallyWrongJoinedURL.indexOf(
+        protocol === "relative" ? "//" : "://"
+      ) + (protocol === "relative" ? 2 : 3);
+
+    // And then sort and merge items in the array so the first item is the whole protocol
+    returnedFragments = extractProtocolFromArray(
+      filteredFragments,
+      protocolIndex
+    );
+
+    // We now know that the first fragment is the protocol (if there are any fragments)
+    // We need to check if there is a second fragment and if there is one, we need to remove any leading slashes it might contain
+    // That way we can be sure the final URL won't contain things like "https:///example.com/blog"
+    if (returnedFragments.length > 1) {
+      returnedFragments[1] = returnedFragments[1].replace(/^\/*/, "");
+    }
+  }
+
+  // No matter if there is protocol or not, we need to check if there is a domain, and if there is one, we need to sort and merge items in the array so the domain is a single fragment in the first position (if there is no protocol) or in the second position (if there is a protocol)
+  returnedFragments = extractDomainFromArray(returnedFragments, hasProtocol);
+
+  return {
+    array: returnedFragments,
+    hasProtocol,
+    protocol
+  };
+}
+
+/**
+ * Converts a safe string array to a URL string.
+ * IMPORTANT: This function assumes the array is safe, meaning it has been processed by the safeStringArrayAssembler function.
+ * The generated string is a potential valid URL but is not guaranteed to be valid.
+ * @param urlArrayData - The data containing the array and whether it has a protocol.
+ * @returns The URL string.
+ * @example
+ * safeStringArrayToURLString({ array: ["https://", "example.com", "blog"], hasProtocol: true, protocol: "https" });
+ * // => "https://example.com/blog"
+ * safeStringArrayToURLString({ array: ["example.com", "blog"], hasProtocol: false, protocol: "none" });
+ * // => "example.com/blog"
+ */
+export function safeStringArrayToURLString(
+  urlArrayData: IURLArrayData
+): string {
+  const { array, hasProtocol } = urlArrayData;
+
+  if (hasProtocol) {
+    // If it has a protocol, we know the first fragment is the protocol, so we skip it
+    const slicedArray = array.length > 1 ? array.slice(1) : [];
+    return `${array.length > 0 ? array[0] : ""}${slicedArray.join("/")}`;
+  }
+
+  return array.join("/");
+}