Initial Commit

packages/devtools/docs/sitemap/src/utils/url-utils.md

@@ -0,0 +1,97 @@
+# url-utils
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Provides the four foundational URL and XML utility functions that the sitemap
+builder and parser modules rely on. Keeping these helpers in a dedicated module
+allows them to be independently tested and reused across all sitemap generation
+paths without coupling them to any particular class or algorithm.
+
+## Features
+
+- `isValidUrl` — validates that a string is an absolute `http` or `https` URL using the platform `URL` constructor
+- `normalizeUrl` — lowercases the scheme and host of any absolute URL for canonical sitemap output
+- `escapeXml` — escapes the five XML-special characters (`&`, `<`, `>`, `"`, `'`)
+- `formatPriority` — clamps a floating-point value to `[0.0, 1.0]` and renders it as a two-decimal-place string
+
+## Usage: Basic Example
+
+```ts
+import {
+  isValidUrl,
+  escapeXml,
+  formatPriority,
+} from "@suaveplan/sitemap";
+
+console.log(isValidUrl("https://example.com/")); // true
+console.log(isValidUrl("ftp://example.com/"));   // false
+console.log(escapeXml("a & b < c"));             // "a &amp; b &lt; c"
+console.log(formatPriority(0.75));                // "0.75"
+```
+
+## Usage: Advanced Example
+
+```ts
+import { isValidUrl, normalizeUrl, escapeXml, formatPriority } from "@suaveplan/sitemap";
+
+// Normalise user-supplied URLs before XML serialisation
+const userUrl = "HTTPS://Example.COM/About";
+if (isValidUrl(userUrl)) {
+  const canonical = normalizeUrl(userUrl);
+  // "https://example.com/About"
+
+  const xml = `<loc>${escapeXml(canonical)}</loc>`;
+  // "<loc>https://example.com/About</loc>"
+}
+
+// Clamp out-of-range priorities gracefully
+const userPriority = 1.5;
+const safeAttr = `<priority>${formatPriority(userPriority)}</priority>`;
+// "<priority>1.00</priority>"
+```
+
+## API Reference
+
+### `isValidUrl(url: string): boolean`
+
+Returns `true` when `url` parses as a valid absolute URL with `http:` or `https:` protocol. Returns `false` for any other protocol, relative URLs, or malformed strings.
+
+**Throws:** never — all errors are caught internally.
+
+### `normalizeUrl(url: string): string`
+
+Lowercases the protocol and hostname of the parsed URL and returns the
+reconstituted string. If the URL cannot be parsed, the original string is
+returned unchanged.
+
+**Throws:** never.
+
+### `escapeXml(str: string): string`
+
+Replaces `&` → `&amp;`, `<` → `&lt;`, `>` → `&gt;`, `"` → `&quot;`,
+`'` → `&apos;`. Suitable for both element content and attribute values.
+
+**Throws:** never.
+
+### `formatPriority(priority: number): string`
+
+Clamps `priority` to the closed interval `[0.0, 1.0]` using `Math.max` /
+`Math.min`, then calls `.toFixed(2)` to produce a two-decimal-place string
+(e.g. `"0.50"`).
+
+**Throws:** never.
+
+## Implementation Notes
+
+`isValidUrl` and `normalizeUrl` deliberately delegate to the platform `URL`
+constructor rather than attempting regex parsing. This gives accurate results
+for IDNs, percent-encoded paths, and IPv6 host literals without maintaining a
+custom parser. The `try/catch` wrappers ensure the helpers never throw
+regardless of input.
+
+`escapeXml` uses a sequence of `.replace()` calls rather than a single regex
+with a callback to keep the implementation readable and free of closure
+overhead for the common case.