@real-router/logger-plugin 0.4.2 → 0.4.4

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types.ts","../../src/factory.ts"],"mappings":";;;;;;AAMA;KAAY,QAAA;;;;UAKK,kBAAA;EAAkB;;;;;;;;;;;;;;ACFnC;;;EDoBE,mBAAA;ECnBU;;;;;;;;;;ED8BV,KAAA,GAAQ,QAAA;;;;;;;EAQR,UAAA;;;;;;;;EASA,cAAA;;;;;;;EAQA,OAAA;AAAA;;;iBCxDc,mBAAA,CACd,OAAA,GAAU,OAAA,CAAQ,kBAAA,IACjB,aAAA"}

package/dist/esm/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/types.ts","../../src/factory.ts"],"mappings":";;;;;;AAMA;KAAY,QAAA;;;;UAKK,kBAAA;EAAkB;;;;;;;;;;;;;;ACFnC;;;EDoBE,mBAAA;ECnBU;;;;;;;;;;ED8BV,KAAA,GAAQ,QAAA;;;;;;;EAQR,UAAA;;;;;;;;EASA,cAAA;;;;;;;EAQA,OAAA;AAAA;;;iBCxDc,mBAAA,CACd,OAAA,GAAU,OAAA,CAAQ,kBAAA,IACjB,aAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/logger-plugin",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "type": "commonjs",
   "description": "Development logging plugin with transition tracking and performance metrics",
   "main": "./dist/cjs/index.js",
@@ -8,7 +8,6 @@
   "types": "./dist/esm/index.d.mts",
   "exports": {
     ".": {
-      "development": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
         "require": "./dist/cjs/index.d.ts"
@@ -18,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "repository": {
     "type": "git",
@@ -44,7 +44,7 @@
   "homepage": "https://github.com/greydragon888/real-router",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.45.1"
+    "@real-router/core": "^0.46.0"
   },
   "scripts": {
     "build": "tsdown --config-loader unrun",
@@ -54,7 +54,7 @@
     "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
     "test:mutation": "stryker run",
     "test:mutation:report": "open reports/mutation-report.html",
-    "lint:package": "bash ../../scripts/publint-filter.sh",
+    "lint:package": "publint",
     "lint:types": "attw --pack .",
     "build:dist-only": "tsdown --config-loader unrun"
   }

package/src/constants.ts

@@ -0,0 +1,15 @@
+// packages/logger-plugin/src/constants.ts
+
+import type { LoggerPluginConfig } from "./types";
+
+export const LOGGER_CONTEXT = "logger-plugin";
+
+export const ERROR_PREFIX = `[@real-router/${LOGGER_CONTEXT}]`;
+
+export const DEFAULT_CONFIG: Required<LoggerPluginConfig> = {
+  level: "all",
+  usePerformanceMarks: false,
+  showParamsDiff: true,
+  showTiming: true,
+  context: LOGGER_CONTEXT,
+};

package/src/factory.ts

@@ -0,0 +1,21 @@
+// packages/logger-plugin/src/factory.ts
+
+import { DEFAULT_CONFIG } from "./constants";
+import { LoggerPlugin } from "./plugin";
+import { validateOptions } from "./validation";
+
+import type { LoggerPluginConfig } from "./types";
+import type { PluginFactory } from "@real-router/core";
+
+export function loggerPluginFactory(
+  options?: Partial<LoggerPluginConfig>,
+): PluginFactory {
+  validateOptions(options);
+
+  const config: Required<LoggerPluginConfig> = {
+    ...DEFAULT_CONFIG,
+    ...options,
+  };
+
+  return () => new LoggerPlugin(config).getPlugin();
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// packages/logger-plugin/src/index.ts
+
+export { loggerPluginFactory } from "./factory";
+
+export type { LoggerPluginConfig, LogLevel } from "./types";

package/src/internal/console-groups.ts

@@ -0,0 +1,74 @@
+// packages/logger-plugin/src/internal/console-groups.ts
+
+/**
+ * Checks if console.group is supported in the current environment.
+ */
+export const supportsConsoleGroups = (): boolean => {
+  return (
+    typeof console !== "undefined" &&
+    typeof console.group === "function" &&
+    typeof console.groupEnd === "function"
+  );
+};
+
+/**
+ * Manager for handling console groups
+ */
+export interface GroupManager {
+  /**
+   * Opens a group if it's not already open
+   */
+  open: (label: string) => void;
+  /**
+   * Closes a group if it's open
+   */
+  close: () => void;
+  /**
+   * Checks if a group is currently open
+   */
+  isOpen: () => boolean;
+}
+
+/**
+ * Creates a manager for handling console groups.
+ * Prevents duplicate group opening.
+ *
+ * @param enabled - Whether groups are supported in the environment
+ * @returns Object with open and close methods
+ */
+export const createGroupManager = (enabled: boolean): GroupManager => {
+  let isOpened = false;
+
+  return {
+    /**
+     * Opens a group if it's not already open.
+     */
+    open(label: string): void {
+      if (!enabled || isOpened) {
+        return;
+      }
+
+      console.group(label);
+      isOpened = true;
+    },
+
+    /**
+     * Closes a group if it's open.
+     */
+    close(): void {
+      if (!enabled || !isOpened) {
+        return;
+      }
+
+      console.groupEnd();
+      isOpened = false;
+    },
+
+    /**
+     * Checks if a group is currently open.
+     */
+    isOpen(): boolean {
+      return isOpened;
+    },
+  };
+};

package/src/internal/formatting.ts

@@ -0,0 +1,56 @@
+// packages/logger-plugin/src/internal/formatting.ts
+
+import type { State } from "@real-router/core";
+
+/**
+ * Formats route name for logging output.
+ * Handles undefined/null.
+ */
+export const formatRouteName = (state?: State): string => {
+  return state?.name ?? "(none)";
+};
+
+/**
+ * Formats execution time information.
+ * Uses adaptive units:
+ * - Microseconds (μs) for <0.1ms
+ * - Milliseconds (ms) for ≥0.1ms
+ *
+ * @param startTime - Start time or null
+ * @param now - Function to get current time
+ * @returns String with time or empty string
+ */
+export const formatTiming = (
+  startTime: number | null,
+  now: () => number,
+): string => {
+  if (startTime === null) {
+    return "";
+  }
+
+  const durationMs = now() - startTime;
+
+  if (!Number.isFinite(durationMs) || durationMs < 0) {
+    return " (?)";
+  }
+
+  if (durationMs < 0.1) {
+    const durationMks = (durationMs * 1000).toFixed(2);
+
+    return ` (${durationMks}μs)`;
+  } else {
+    const duration = durationMs.toFixed(2);
+
+    return ` (${duration}ms)`;
+  }
+};
+
+/**
+ * Creates a label for Performance API from route names.
+ */
+export const createTransitionLabel = (
+  fromRoute: string,
+  toRoute: string,
+): string => {
+  return `${fromRoute}→${toRoute}`;
+};

package/src/internal/params-diff.ts

@@ -0,0 +1,91 @@
+// packages/logger-plugin/src/internal/params-diff.ts
+
+import type { Params } from "@real-router/core";
+
+export interface ParamsDiff {
+  changed: Record<string, { from: unknown; to: unknown }>;
+  added: Record<string, unknown>;
+  removed: Record<string, unknown>;
+}
+
+/**
+ * Calculates differences between two parameter objects.
+ * Performs only shallow comparison.
+ *
+ * @param fromParams - Previous parameters
+ * @param toParams - New parameters
+ * @returns Object with differences or null if there are no changes
+ */
+export const getParamsDiff = (
+  fromParams: Params,
+  toParams: Params,
+): ParamsDiff | null => {
+  const changed: ParamsDiff["changed"] = {};
+  const added: ParamsDiff["added"] = {};
+  const removed: ParamsDiff["removed"] = {};
+
+  // Track if any changes found to avoid iterating through objects at the end.
+  // This is a performance optimization: instead of calling Object.keys().length
+  // three times to check if objects are empty, we set this flag when we find
+  // any change and check it once at the end.
+  let hasChanges = false;
+
+  // Find changed and removed
+  for (const key in fromParams) {
+    if (!(key in toParams)) {
+      removed[key] = fromParams[key];
+      hasChanges = true;
+    } else if (fromParams[key] !== toParams[key]) {
+      changed[key] = { from: fromParams[key], to: toParams[key] };
+      hasChanges = true;
+    }
+  }
+
+  // Find added
+  for (const key in toParams) {
+    if (!(key in fromParams)) {
+      added[key] = toParams[key];
+      hasChanges = true;
+    }
+  }
+
+  // Return null if there are no changes
+  if (!hasChanges) {
+    return null;
+  }
+
+  return { changed, added, removed };
+};
+
+/**
+ * Formats and logs parameter differences.
+ *
+ * @param diff - Object with differences
+ * @param context - Context for console
+ */
+export const logParamsDiff = (diff: ParamsDiff, context: string): void => {
+  const parts: string[] = [];
+
+  // Cache entries to avoid double iteration
+  const changedEntries = Object.entries(diff.changed);
+
+  if (changedEntries.length > 0) {
+    const items: string[] = [];
+
+    for (const [key, { from, to }] of changedEntries) {
+      items.push(`${key}: ${JSON.stringify(from)} → ${JSON.stringify(to)}`);
+    }
+
+    parts.push(`Changed: { ${items.join(", ")} }`);
+  }
+
+  if (Object.keys(diff.added).length > 0) {
+    parts.push(`Added: ${JSON.stringify(diff.added)}`);
+  }
+
+  if (Object.keys(diff.removed).length > 0) {
+    parts.push(`Removed: ${JSON.stringify(diff.removed)}`);
+  }
+
+  console.log(`[${context}]  ${parts.join(", ")}`);
+};

package/src/internal/performance-marks.ts

@@ -0,0 +1,67 @@
+// packages/logger-plugin/src/internal/performance-marks.ts
+
+/**
+ * Checks if Performance API is supported in the current environment.
+ */
+export const supportsPerformanceAPI = (): boolean => {
+  return (
+    typeof performance !== "undefined" &&
+    typeof performance.mark === "function" &&
+    typeof performance.measure === "function"
+  );
+};
+
+/**
+ * Performance tracker interface with mark and measure methods.
+ */
+export interface PerformanceTracker {
+  mark: (name: string) => void;
+  measure: (measureName: string, startMark: string, endMark: string) => void;
+}
+
+/**
+ * Creates a tracker for working with the Performance API.
+ * Ignores calls if the API is unavailable.
+ *
+ * @param enabled - Whether the functionality is enabled (from config)
+ * @param context - Context for error logging
+ * @returns Object with mark and measure methods
+ */
+export const createPerformanceTracker = (
+  enabled: boolean,
+  context: string,
+): PerformanceTracker => {
+  const isSupported = enabled && supportsPerformanceAPI();
+
+  return {
+    /**
+     * Creates a performance mark with the specified name.
+     */
+    mark(name: string): void {
+      if (!isSupported) {
+        return;
+      }
+
+      performance.mark(name);
+    },
+
+    /**
+     * Creates a performance measure between two marks.
+     * Logs a warning if the marks don't exist.
+     */
+    measure(measureName: string, startMark: string, endMark: string): void {
+      if (!isSupported) {
+        return;
+      }
+
+      try {
+        performance.measure(measureName, startMark, endMark);
+      } catch (error) {
+        console.warn(
+          `[${context}] Failed to create performance measure: ${measureName}`,
+          error,
+        );
+      }
+    },
+  };
+};

package/src/internal/timing.ts

@@ -0,0 +1,52 @@
+// packages/logger-plugin/src/internal/timing.ts
+
+/**
+ * Function that returns high-resolution timestamp in milliseconds.
+ */
+type TimeProvider = () => number;
+
+/**
+ * State for Date.now() monotonic emulation
+ */
+let lastTimestamp = 0;
+let timeOffset = 0;
+
+/**
+ * Creates monotonic Date.now() wrapper that ensures time never goes backwards.
+ *
+ * @returns Time provider function with monotonic guarantee
+ */
+function createMonotonicDateNow(): TimeProvider {
+  // eslint-disable-next-line unicorn/consistent-function-scoping -- closure over module-level lastTimestamp/timeOffset
+  return (): number => {
+    const current: number = Date.now();
+
+    if (current < lastTimestamp) {
+      timeOffset += lastTimestamp - current;
+    }
+
+    lastTimestamp = current;
+
+    return current + timeOffset;
+  };
+}
+
+/**
+ * Initialize time provider based on environment.
+ * Uses performance.now() in modern environments (Node.js 16+, all browsers),
+ * falls back to monotonic Date.now() wrapper for edge cases.
+ */
+const nowFn: TimeProvider =
+  typeof performance !== "undefined" && typeof performance.now === "function"
+    ? (): number => performance.now()
+    : createMonotonicDateNow();
+
+/**
+ * Returns high-resolution monotonic timestamp.
+ *
+ * Uses performance.now() in modern environments (Node.js 16+, all browsers).
+ * Falls back to monotonic Date.now() wrapper (~1ms precision) for edge cases.
+ *
+ * @returns Timestamp in milliseconds
+ */
+export const now = (): number => nowFn();

package/src/plugin.ts

@@ -0,0 +1,235 @@
+// packages/logger-plugin/src/plugin.ts
+
+import {
+  createGroupManager,
+  supportsConsoleGroups,
+} from "./internal/console-groups";
+import {
+  formatRouteName,
+  formatTiming,
+  createTransitionLabel,
+} from "./internal/formatting";
+import { getParamsDiff, logParamsDiff } from "./internal/params-diff";
+import { createPerformanceTracker } from "./internal/performance-marks";
+import { now } from "./internal/timing";
+
+import type { GroupManager } from "./internal/console-groups";
+import type { PerformanceTracker } from "./internal/performance-marks";
+import type { LoggerPluginConfig } from "./types";
+import type { Plugin, RouterError, State } from "@real-router/core";
+
+export class LoggerPlugin {
+  readonly #logLifecycle: boolean;
+  readonly #logTransition: boolean;
+  readonly #logError: boolean;
+
+  readonly #shouldLogParams: boolean;
+  readonly #shouldShowTiming: boolean;
+  readonly #usePerf: boolean;
+
+  readonly #prefix: string;
+  readonly #context: string;
+
+  readonly #groups: GroupManager;
+  readonly #perf: PerformanceTracker;
+
+  // Transition state
+  #transitionStartTime: number | null = null;
+  #transitionLabel = "";
+  #startMarkName = "";
+
+  constructor(config: Required<LoggerPluginConfig>) {
+    this.#logLifecycle = config.level === "all";
+    this.#logTransition = config.level !== "none" && config.level !== "errors";
+    this.#logError = config.level !== "none";
+
+    this.#shouldLogParams = this.#logTransition && config.showParamsDiff;
+    this.#shouldShowTiming = config.showTiming;
+    this.#usePerf = config.usePerformanceMarks;
+
+    this.#prefix = `[${config.context}]`;
+    this.#context = config.context;
+
+    this.#groups = createGroupManager(supportsConsoleGroups());
+    this.#perf = createPerformanceTracker(
+      config.usePerformanceMarks,
+      config.context,
+    );
+  }
+
+  getPlugin(): Plugin {
+    return {
+      onStart: () => {
+        this.#perf.mark("router:start");
+
+        if (this.#logLifecycle) {
+          console.log(`${this.#prefix} Router started`);
+        }
+      },
+
+      onStop: () => {
+        this.#groups.close();
+
+        this.#perf.mark("router:stop");
+        this.#perf.measure("router:lifetime", "router:start", "router:stop");
+
+        if (this.#logLifecycle) {
+          console.log(`${this.#prefix} Router stopped`);
+        }
+      },
+
+      onTransitionStart: (toState: State, fromState?: State) => {
+        this.#groups.open("Router transition");
+        this.#transitionStartTime = this.#shouldShowTiming ? now() : null;
+
+        const fromRoute = formatRouteName(fromState);
+        const toRoute = formatRouteName(toState);
+
+        if (this.#usePerf) {
+          this.#transitionLabel = createTransitionLabel(fromRoute, toRoute);
+          this.#startMarkName = `router:transition-start:${this.#transitionLabel}`;
+          this.#perf.mark(this.#startMarkName);
+        }
+
+        if (this.#logTransition) {
+          console.log(`${this.#prefix} Transition: ${fromRoute} → ${toRoute}`, {
+            from: fromState,
+            to: toState,
+          });
+
+          this.#logParamsIfNeeded(toState, fromState);
+        }
+      },
+
+      onTransitionLeaveApprove: (toState: State, fromState?: State) => {
+        if (this.#usePerf) {
+          this.#perf.mark(`router:leave-approved:${this.#transitionLabel}`);
+        }
+
+        if (this.#logTransition) {
+          console.log(`${this.#prefix} Leave approved`, {
+            to: toState,
+            from: fromState,
+          });
+        }
+      },
+
+      onTransitionSuccess: (toState: State, fromState?: State) => {
+        if (this.#usePerf) {
+          const label = this.#transitionLabel;
+          const endMark = `router:transition-end:${label}`;
+
+          this.#perf.mark(endMark);
+          this.#perf.measure(
+            `router:transition:${label}`,
+            this.#startMarkName,
+            endMark,
+          );
+        }
+
+        if (this.#logTransition) {
+          const timing = this.#shouldShowTiming
+            ? formatTiming(this.#transitionStartTime, now)
+            : "";
+
+          console.log(`${this.#prefix} Transition success${timing}`, {
+            to: toState,
+            from: fromState,
+          });
+        }
+
+        this.#resetTransitionState();
+      },
+
+      onTransitionCancel: (toState: State, fromState?: State) => {
+        if (this.#usePerf) {
+          const label = this.#transitionLabel;
+          const cancelMark = `router:transition-cancel:${label}`;
+
+          this.#perf.mark(cancelMark);
+          this.#perf.measure(
+            `router:transition-cancelled:${label}`,
+            this.#startMarkName,
+            cancelMark,
+          );
+        }
+
+        if (this.#logTransition) {
+          const timing = this.#shouldShowTiming
+            ? formatTiming(this.#transitionStartTime, now)
+            : "";
+
+          console.warn(`${this.#prefix} Transition cancelled${timing}`, {
+            to: toState,
+            from: fromState,
+          });
+        }
+
+        this.#resetTransitionState();
+      },
+
+      onTransitionError: (
+        toState: State | undefined,
+        fromState: State | undefined,
+        err: RouterError,
+      ) => {
+        if (this.#usePerf) {
+          const label = this.#transitionLabel;
+          const errorMark = `router:transition-error:${label}`;
+
+          this.#perf.mark(errorMark);
+          this.#perf.measure(
+            `router:transition-failed:${label}`,
+            this.#startMarkName,
+            errorMark,
+          );
+        }
+
+        if (this.#logError) {
+          const timing = this.#shouldShowTiming
+            ? formatTiming(this.#transitionStartTime, now)
+            : "";
+
+          console.error(
+            `${this.#prefix} Transition error: ${err.code}${timing}`,
+            {
+              error: err,
+              stack: err.stack,
+              to: toState,
+              from: fromState,
+            },
+          );
+        }
+
+        this.#resetTransitionState();
+      },
+
+      teardown: () => {
+        this.#resetTransitionState();
+      },
+    };
+  }
+
+  #logParamsIfNeeded(toState: State, fromState?: State): void {
+    if (!this.#shouldLogParams || !fromState) {
+      return;
+    }
+
+    if (toState.name !== fromState.name) {
+      return;
+    }
+
+    const diff = getParamsDiff(fromState.params, toState.params);
+
+    if (diff) {
+      logParamsDiff(diff, this.#context);
+    }
+  }
+
+  #resetTransitionState(): void {
+    this.#groups.close();
+    this.#transitionLabel = "";
+    this.#startMarkName = "";
+    this.#transitionStartTime = null;
+  }
+}

package/src/types.ts

@@ -0,0 +1,67 @@
+// packages/logger-plugin/src/types.ts
+
+/**
+ * Logging level for router events.
+ * Controls which events are logged to the console.
+ */
+export type LogLevel = "all" | "transitions" | "errors" | "none";
+
+/**
+ * Configuration options for the logger-plugin.
+ */
+export interface LoggerPluginConfig {
+  /**
+   * Use Performance API to create marks and measures.
+   * Enables integration with browser DevTools Performance tab.
+   *
+   * Creates marks:
+   * - `router:transition-start:{from}→{to}`
+   * - `router:transition-end:{from}→{to}` (success)
+   * - `router:transition-cancel:{from}→{to}` (cancelled)
+   * - `router:transition-error:{from}→{to}` (error)
+   *
+   * Creates measures:
+   * - `router:transition:{from}→{to}` (success)
+   * - `router:transition-cancelled:{from}→{to}` (cancelled)
+   * - `router:transition-failed:{from}→{to}` (error)
+   *
+   * @default false
+   */
+  usePerformanceMarks?: boolean;
+  /**
+   * Logging level - controls what router events to log.
+   *
+   * - 'all': Log all router events (default)
+   * - 'transitions': Log only transition-related events
+   * - 'errors': Log only transition errors
+   * - 'none': Disable all logging
+   *
+   * @default 'all'
+   */
+  level?: LogLevel;
+
+  /**
+   * Show execution time in milliseconds for transitions.
+   * Helps identify slow route changes.
+   *
+   * @default true
+   */
+  showTiming?: boolean;
+
+  /**
+   * Show diff of changed route parameters between transitions.
+   * Only applies when navigating within the same route.
+   * Helps identify which parameters changed during navigation.
+   *
+   * @default true
+   */
+  showParamsDiff?: boolean;
+
+  /**
+   * Custom context name for console.
+   * Useful when running multiple routers.
+   *
+   * @default 'logger-plugin'
+   */
+  context?: string;
+}

package/src/validation.ts

@@ -0,0 +1,61 @@
+// packages/logger-plugin/src/validation.ts
+
+import { ERROR_PREFIX } from "./constants";
+
+import type { LoggerPluginConfig } from "./types";
+
+const VALID_LEVELS = new Set(["all", "transitions", "errors", "none"]);
+
+export function validateOptions(options?: Partial<LoggerPluginConfig>): void {
+  if (options === undefined) {
+    return;
+  }
+
+  // Runtime defense: typeof null === "object", so check identity first.
+  // TypeScript excludes null from the parameter type, but JS callers may pass it.
+  if (options === (null as never) || typeof options !== "object") {
+    throw new TypeError(`${ERROR_PREFIX} Options must be an object`);
+  }
+
+  if (options.level !== undefined && !VALID_LEVELS.has(options.level)) {
+    throw new TypeError(
+      `${ERROR_PREFIX} Invalid level: "${options.level}". Expected: ${[...VALID_LEVELS].join(", ")}`,
+    );
+  }
+
+  if (
+    options.context !== undefined &&
+    (typeof options.context !== "string" || options.context.length === 0)
+  ) {
+    throw new TypeError(
+      `${ERROR_PREFIX} Option "context" must be a non-empty string`,
+    );
+  }
+
+  if (
+    options.showTiming !== undefined &&
+    typeof options.showTiming !== "boolean"
+  ) {
+    throw new TypeError(
+      `${ERROR_PREFIX} Option "showTiming" must be a boolean`,
+    );
+  }
+
+  if (
+    options.showParamsDiff !== undefined &&
+    typeof options.showParamsDiff !== "boolean"
+  ) {
+    throw new TypeError(
+      `${ERROR_PREFIX} Option "showParamsDiff" must be a boolean`,
+    );
+  }
+
+  if (
+    options.usePerformanceMarks !== undefined &&
+    typeof options.usePerformanceMarks !== "boolean"
+  ) {
+    throw new TypeError(
+      `${ERROR_PREFIX} Option "usePerformanceMarks" must be a boolean`,
+    );
+  }
+}