@jskit-ai/connectors-catalog 0.2.5 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/connectors-catalog",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Provider definitions and focused API operations for JSKIT connectors.",
   "type": "module",
   "exports": {
@@ -125,14 +125,14 @@
     "@aws-sdk/client-redshift-data": "3.1128.0",
     "@aws-sdk/client-s3": "3.1128.0",
     "@aws-sdk/s3-request-presigner": "3.1128.0",
-    "@jskit-ai/connectors-core": "0.2.5",
+    "@jskit-ai/connectors-core": "0.2.6",
     "@modelcontextprotocol/sdk": "1.32.1",
     "@smithy/fetch-http-handler": "5.8.0",
     "jose": "^6.1.3",
     "json-rest-schema": "^1.0.17"
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.2.4"
+    "@jskit-ai/kernel": "0.2.5"
   },
   "jskit": {
     "kind": "runtime",

package/src/client/google-analytics.js

@@ -1,7 +1,12 @@
 // Optional browser implementation. The application owns consent and route hooks.
 const installations = new WeakMap();
 
-function createGoogleAnalytics({ measurementId, window: browser = globalThis.window } = {}) {
+/**
+ * @param {object} options
+ * @param {string} options.measurementId
+ * @param {Window & typeof globalThis} [options.window] The page to install on, the current one by default.
+ */
+function createGoogleAnalytics({ measurementId, window: browser = globalThis.window }) {
   if (typeof measurementId !== "string" || !/^G-[A-Z0-9]+$/.test(measurementId) || measurementId.length > 64) throw new TypeError("Supply a valid GA4 Measurement ID.");
   if (!browser?.document) throw new TypeError("Initialize Google Analytics in the browser after hydration.");
   const existing = installations.get(browser);

package/src/client/google-maps-platform.js

@@ -1,9 +1,10 @@
 /** Compose an app-owned Google map after the application has loaded Google's SDK. */
-async function mountGoogleMap({ element, maps = globalThis.google?.maps, center, zoom = 12, mapId, markers = [], path = [], signal } = {}) {
+async function mountGoogleMap({ element, maps = globalThis.google?.maps, center, zoom = 12, mapId, markers = [], path = [], signal = new AbortController().signal }) {
   const coordinate = point => {
     if (!point || !Number.isFinite(point.lat) || Math.abs(point.lat) > 90 || !Number.isFinite(point.lng) || Math.abs(point.lng) > 180) throw new Error("Use finite lat/lng coordinates within Earth bounds.");
     return { lat: point.lat, lng: point.lng };
   };
+  // readable-check: allow method-probe - platform object: Google's SDK is on the page only once the application has loaded it
   if (!element?.replaceChildren || typeof maps?.importLibrary !== "function") throw new Error("Provide a map container and load the Google Maps JavaScript SDK first.");
   if (!Number.isFinite(zoom) || zoom < 0 || zoom > 22) throw new Error("Use zoom between 0 and 22.");
   if (!Array.isArray(markers) || markers.length > 100 || !Array.isArray(path) || path.length > 10000) throw new Error("Use at most 100 markers and 10000 route points.");
@@ -14,16 +15,16 @@ async function mountGoogleMap({ element, maps = globalThis.google?.maps, center,
     return { position: coordinate(marker.position), title: marker.title || "" };
   });
   const route = path.map(coordinate);
-  signal?.throwIfAborted();
+  signal.throwIfAborted();
   const library = await maps.importLibrary("maps");
   const markerLibrary = markerOptions.length ? await maps.importLibrary("marker") : null;
-  signal?.throwIfAborted();
+  signal.throwIfAborted();
   const map = new library.Map(element, { center: position, zoom, ...(mapId ? { mapId } : {}) });
   const pins = []; let line; let disposed = false;
   function dispose() {
     if (disposed) return;
     disposed = true;
-    signal?.removeEventListener("abort", dispose);
+    signal.removeEventListener("abort", dispose);
     for (const pin of pins) { maps.event.clearInstanceListeners(pin); pin.map = null; }
     if (line) { maps.event.clearInstanceListeners(line); line.setMap(null); }
     maps.event.clearInstanceListeners(map);
@@ -32,7 +33,7 @@ async function mountGoogleMap({ element, maps = globalThis.google?.maps, center,
   try {
     for (const options of markerOptions) pins.push(new markerLibrary.AdvancedMarkerElement({ ...options, map }));
     if (route.length) line = new library.Polyline({ map, path: route });
-    signal?.addEventListener("abort", dispose, { once: true });
+    signal.addEventListener("abort", dispose, { once: true });
     return { map, dispose };
   } catch (error) { dispose(); throw error; }
 }

package/test/browserClients.test.js

@@ -0,0 +1,120 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createGoogleAnalytics } from "../src/client/google-analytics.js";
+import { mountGoogleMap } from "../src/client/google-maps-platform.js";
+
+function createMapElement() {
+  return {
+    clears: 0,
+    replaceChildren() {
+      this.clears += 1;
+    }
+  };
+}
+
+function createMapsSdk() {
+  const imported = [];
+  const released = [];
+  class Map {
+    constructor(element, options) {
+      this.element = element;
+      this.options = options;
+    }
+  }
+  return {
+    imported,
+    released,
+    async importLibrary(name) {
+      imported.push(name);
+      return { Map };
+    },
+    event: {
+      clearInstanceListeners(target) {
+        released.push(target);
+      }
+    }
+  };
+}
+
+function createAnalyticsPage() {
+  const scripts = [];
+  return {
+    scripts,
+    location: { href: "https://example.test/start" },
+    document: {
+      title: "Start",
+      querySelector: () => null,
+      createElement: () => ({}),
+      head: {
+        appendChild(script) {
+          scripts.push(script);
+        }
+      }
+    }
+  };
+}
+
+const center = { lat: -31.95, lng: 115.86 };
+
+test("a map mounts and disposes once without an abort signal", async () => {
+  const element = createMapElement();
+  const maps = createMapsSdk();
+
+  const mounted = await mountGoogleMap({ element, maps, center });
+  assert.deepEqual(mounted.map.options, { center, zoom: 12 });
+  assert.equal(element.clears, 0);
+
+  mounted.dispose();
+  mounted.dispose();
+  assert.equal(element.clears, 1);
+  assert.deepEqual(maps.released, [mounted.map]);
+});
+
+test("a signal aborted before mounting stops it before Google's SDK loads a library", async () => {
+  const controller = new AbortController();
+  const maps = createMapsSdk();
+  controller.abort();
+
+  await assert.rejects(mountGoogleMap({ element: createMapElement(), maps, center, signal: controller.signal }));
+  assert.deepEqual(maps.imported, []);
+});
+
+test("aborting a mounted map disposes it, and disposing it stops listening to the signal", async () => {
+  const aborted = new AbortController();
+  const abortedElement = createMapElement();
+  await mountGoogleMap({ element: abortedElement, maps: createMapsSdk(), center, signal: aborted.signal });
+  aborted.abort();
+  assert.equal(abortedElement.clears, 1);
+
+  const disposed = new AbortController();
+  const disposedElement = createMapElement();
+  const mounted = await mountGoogleMap({ element: disposedElement, maps: createMapsSdk(), center, signal: disposed.signal });
+  mounted.dispose();
+  disposed.abort();
+  assert.equal(disposedElement.clears, 1);
+});
+
+test("a page without Google's SDK is told to load it", async () => {
+  await assert.rejects(
+    mountGoogleMap({ element: createMapElement(), center }),
+    /load the Google Maps JavaScript SDK first/u
+  );
+});
+
+test("a page has one Analytics owner, and nothing loads before consent", () => {
+  const page = createAnalyticsPage();
+  const analytics = createGoogleAnalytics({ measurementId: "G-FIXTURE1", window: page });
+
+  assert.equal(createGoogleAnalytics({ measurementId: "G-FIXTURE1", window: page }), analytics);
+  assert.throws(() => createGoogleAnalytics({ measurementId: "G-OTHER1", window: page }), /already has an Analytics owner/u);
+  assert.equal(page.scripts.length, 0);
+
+  analytics.setConsent(true);
+  assert.equal(page.scripts.length, 1);
+  assert.match(page.scripts[0].src, /googletagmanager\.com\/gtag\/js\?id=G-FIXTURE1/u);
+});
+
+test("Analytics refuses an invalid Measurement ID and a page with no document", () => {
+  assert.throws(() => createGoogleAnalytics({ measurementId: "UA-1", window: createAnalyticsPage() }), /valid GA4 Measurement ID/u);
+  assert.throws(() => createGoogleAnalytics({ measurementId: "G-FIXTURE1", window: {} }), /in the browser after hydration/u);
+});