@mapvx/web-js 1.0.1 → 1.1.1

package/dist/es/utils/preconnect.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Hostnames that MapVX maps typically need to talk to during the first
+ * paint: vector tiles, sprite, glyphs and indoor tile sources. Exposed so
+ * that consumer apps can call `injectPreconnects(MAPVX_DEFAULT_PRECONNECT_HOSTS)`
+ * without having to maintain the list themselves.
+ *
+ * @group Utils
+ */
+export declare const MAPVX_DEFAULT_PRECONNECT_HOSTS: readonly string[];
+/**
+ * Injects `<link rel="preconnect">` (and a `<link rel="dns-prefetch">` fallback)
+ * tags into `document.head` for the given origins, so the browser starts the
+ * DNS + TLS handshake before MapLibre actually requests sprite/glyph/tile
+ * resources.
+ *
+ * Call this as early as possible — ideally before {@link initializeSDK} — to
+ * maximize the savings. In real captures this shaves ~150-300 ms off the
+ * first-paint cascade.
+ *
+ * Idempotent: hosts that already have a `<link rel="preconnect" crossorigin>`
+ * are skipped. If an existing `preconnect` link is missing `crossorigin`, it
+ * is upgraded in place (added `crossorigin="anonymous"`) — without that
+ * attribute the warmed socket can't be reused for the CORS tile/font/sprite
+ * fetches MapLibre performs, so leaving the existing link untouched would
+ * silently defeat the optimization. Existing `crossorigin="use-credentials"`
+ * is respected and never overwritten.
+ *
+ * @param hosts - Origin URLs (`"https://tiles.mapvx.com"`) or bare hostnames
+ *   (`"tiles.mapvx.com"`, normalized to `https://`). Invalid entries are
+ *   silently ignored.
+ * @returns The origins where the helper made a change — either a new link was
+ *   appended, or an existing one was upgraded with `crossorigin="anonymous"`.
+ *
+ * @example
+ * ```ts
+ * import { initializeSDK, injectPreconnects, MAPVX_DEFAULT_PRECONNECT_HOSTS } from "@mapvx/web-js"
+ *
+ * injectPreconnects(MAPVX_DEFAULT_PRECONNECT_HOSTS)
+ * const sdk = initializeSDK(apiKey)
+ * ```
+ *
+ * @group Utils
+ */
+export declare function injectPreconnects(hosts: readonly string[]): string[];
+//# sourceMappingURL=preconnect.d.ts.map

package/dist/es/utils/preconnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preconnect.d.ts","sourceRoot":"","sources":["../../../src/utils/preconnect.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAI3D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CA+CpE"}

package/dist/es/utils/preconnect.js

@@ -0,0 +1,127 @@
+/**
+ * Hostnames that MapVX maps typically need to talk to during the first
+ * paint: vector tiles, sprite, glyphs and indoor tile sources. Exposed so
+ * that consumer apps can call `injectPreconnects(MAPVX_DEFAULT_PRECONNECT_HOSTS)`
+ * without having to maintain the list themselves.
+ *
+ * @group Utils
+ */
+export const MAPVX_DEFAULT_PRECONNECT_HOSTS = [
+    "https://tiles.mapvx.com",
+    "https://api.maptiler.com",
+    "https://indoorequals.mapvx.com",
+];
+/**
+ * Injects `<link rel="preconnect">` (and a `<link rel="dns-prefetch">` fallback)
+ * tags into `document.head` for the given origins, so the browser starts the
+ * DNS + TLS handshake before MapLibre actually requests sprite/glyph/tile
+ * resources.
+ *
+ * Call this as early as possible — ideally before {@link initializeSDK} — to
+ * maximize the savings. In real captures this shaves ~150-300 ms off the
+ * first-paint cascade.
+ *
+ * Idempotent: hosts that already have a `<link rel="preconnect" crossorigin>`
+ * are skipped. If an existing `preconnect` link is missing `crossorigin`, it
+ * is upgraded in place (added `crossorigin="anonymous"`) — without that
+ * attribute the warmed socket can't be reused for the CORS tile/font/sprite
+ * fetches MapLibre performs, so leaving the existing link untouched would
+ * silently defeat the optimization. Existing `crossorigin="use-credentials"`
+ * is respected and never overwritten.
+ *
+ * @param hosts - Origin URLs (`"https://tiles.mapvx.com"`) or bare hostnames
+ *   (`"tiles.mapvx.com"`, normalized to `https://`). Invalid entries are
+ *   silently ignored.
+ * @returns The origins where the helper made a change — either a new link was
+ *   appended, or an existing one was upgraded with `crossorigin="anonymous"`.
+ *
+ * @example
+ * ```ts
+ * import { initializeSDK, injectPreconnects, MAPVX_DEFAULT_PRECONNECT_HOSTS } from "@mapvx/web-js"
+ *
+ * injectPreconnects(MAPVX_DEFAULT_PRECONNECT_HOSTS)
+ * const sdk = initializeSDK(apiKey)
+ * ```
+ *
+ * @group Utils
+ */
+export function injectPreconnects(hosts) {
+    if (typeof document === "undefined" || !document.head)
+        return [];
+    if (!Array.isArray(hosts) || hosts.length === 0)
+        return [];
+    const injected = [];
+    for (const raw of hosts) {
+        if (typeof raw !== "string" || raw.length === 0)
+            continue;
+        const origin = normalizeOrigin(raw);
+        if (origin === null)
+            continue;
+        // Check what's already in <head>. We may need to UPGRADE an existing
+        // preconnect — server-rendered or hand-authored hints frequently omit
+        // `crossorigin`, and a warmed socket without it cannot be reused for
+        // the CORS tile/font/sprite fetches that MapLibre performs. Without
+        // this branch the optimization would silently no-op when the page
+        // already had a partial hint.
+        const existingPreconnect = findLinkForOrigin("preconnect", origin);
+        let preconnectChanged = false;
+        if (existingPreconnect) {
+            if (!existingPreconnect.hasAttribute("crossorigin")) {
+                existingPreconnect.crossOrigin = "anonymous";
+                preconnectChanged = true;
+            }
+            // If the existing link already has any `crossorigin` value
+            // (including `use-credentials`), respect the author's intent and
+            // leave it alone.
+        }
+        else {
+            const preconnect = document.createElement("link");
+            preconnect.rel = "preconnect";
+            preconnect.href = origin;
+            preconnect.crossOrigin = "anonymous";
+            document.head.appendChild(preconnect);
+            preconnectChanged = true;
+        }
+        // dns-prefetch is a fallback for older browsers that ignore preconnect.
+        if (!findLinkForOrigin("dns-prefetch", origin)) {
+            const dnsPrefetch = document.createElement("link");
+            dnsPrefetch.rel = "dns-prefetch";
+            dnsPrefetch.href = origin;
+            document.head.appendChild(dnsPrefetch);
+        }
+        if (preconnectChanged)
+            injected.push(origin);
+    }
+    return injected;
+}
+/**
+ * Returns the first `<link rel="${rel}">` in `<head>` whose resolved origin
+ * matches `origin`, or null. We compare canonical URL origins instead of
+ * the raw `href` attribute text — the same origin can be written as
+ * `https://tiles.mapvx.com` or `https://tiles.mapvx.com/`, and a strict
+ * attribute selector would miss the second form and inject a duplicate.
+ */
+function findLinkForOrigin(rel, origin) {
+    const links = document.head.querySelectorAll(`link[rel="${rel}"]`);
+    for (let i = 0; i < links.length; i++) {
+        const link = links[i];
+        try {
+            if (new URL(link.href).origin === origin)
+                return link;
+        }
+        catch (_a) {
+            // Malformed href — skip and keep scanning.
+        }
+    }
+    return null;
+}
+function normalizeOrigin(raw) {
+    try {
+        const candidate = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+        return new URL(candidate).origin;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+//# sourceMappingURL=preconnect.js.map

package/dist/es/utils/preconnect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preconnect.js","sourceRoot":"","sources":["../../../src/utils/preconnect.ts"],"names":[],"mappings":"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"}