@webority/analytics 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webority/analytics",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "license": "MIT",
     "type": "module",
     "main": "src/index.js",
@@ -16,10 +16,11 @@
         "check": "biome check ./src ./test",
         "test": "node test/smoke.mjs"
     },
-    "dependencies": {
-        "posthog-js": "1.417.1"
+    "peerDependencies": {
+        "posthog-js": "^1.417.1"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.5.8"
+        "@biomejs/biome": "2.5.8",
+        "posthog-js": "1.417.1"
     }
 }

package/src/analytics.js

@@ -1,5 +1,5 @@
 import { ensurePosthogInitialized } from "./posthog-bridge.js";
-import { hasConsent, isActive, isEligible, resetState, state } from "./state.js";
+import { hasConsent, isActive, isEligible, resetState, state, WARNED_EVENT_LIMIT } from "./state.js";
 import { EVENT_NAME_PATTERN } from "./vocabulary.js";
 
 export function initAnalytics(config) {
@@ -110,11 +110,42 @@ export function registerEvents(names) {
 
 export function trackEvent(name, props = {}) {
     if (!state.registeredEvents.has(name)) {
-        throw new Error(`@webority/analytics: event "${name}" is not registered. Call registerEvents() first.`);
+        warnUnregisteredOnce(name);
+        return;
     }
     capture(name, props);
 }
 
+// Parity with IAnalyticsClient.Track on the server half: the same developer mistake never
+// throws there, it is logged and the event is dropped. A throw here runs inside the user's
+// browser and can take out the handler that raised it, so the browser half must not be the
+// harsher one. Once per name, because a misregistered event usually sits in a hot path.
+function warnUnregisteredOnce(name) {
+    if (state.warnedUnregisteredEvents.has(name)) {
+        return;
+    }
+    if (state.warnedUnregisteredEvents.size < WARNED_EVENT_LIMIT) {
+        state.warnedUnregisteredEvents.add(name);
+    }
+
+    const logger = state.config?.logger;
+    const message = `@webority/analytics: event "${name}" is not registered, so it was dropped. Call registerEvents() first.`;
+    if (typeof logger?.warn === "function") {
+        logger.warn(message);
+        return;
+    }
+    if (typeof logger?.info === "function") {
+        logger.info(message);
+        return;
+    }
+
+    // The no-console rule exists to stop debug logging, and passing no logger is the default.
+    // Routing the one diagnostic this package emits to a logger nobody passed would hide exactly
+    // the mistake the warning exists to surface.
+    // biome-ignore lint/suspicious/noConsole: the package's one diagnostic must be visible by default
+    console.warn(message);
+}
+
 function capture(name, props) {
     if (!isActive()) {
         logInactive(name, props);

package/src/posthog-bridge.js

@@ -1,7 +1,7 @@
 import { hasConsent, state } from "./state.js";
 
 // Dynamic import keeps posthog-js out of the module graph entirely for callers that
-// never go active (e.g. Local environment) — it assumes browser globals at init time.
+// never go active (e.g. Local environment), because it assumes browser globals at init time.
 export async function ensurePosthogInitialized() {
     if (state.posthogInstance) {
         return state.posthogInstance;

package/src/state.js

@@ -6,11 +6,18 @@ export const state = {
     posthogInstance: null,
     posthogInitPromise: null,
     registeredEvents: new Set(Object.values(events)),
+    warnedUnregisteredEvents: new Set(),
 };
 
+// The warning exists to reach a developer once. After this many distinct bad names the message
+// has landed, and a product building names from data must not grow the set for the life of the tab.
+export const WARNED_EVENT_LIMIT = 50;
+
 // registeredEvents is deliberately not reset: an event name is part of the product's
 // vocabulary, not of one analytics session, so a product that registers at module scope and
-// starts analytics later in a bootstrap effect keeps its registrations.
+// starts analytics later in a bootstrap effect keeps its registrations. warnedUnregisteredEvents
+// follows it for the same reason: the warning is about the code, not about one session, so
+// re-initializing must not make the same mistake shout again.
 export function resetState(config) {
     state.config = config;
     state.consentOverride = null;