@real-router/logger-plugin 0.2.24 → 0.2.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/logger-plugin",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "type": "commonjs",
   "description": "Development logging plugin with transition tracking and performance metrics",
   "main": "./dist/cjs/index.js",
@@ -8,6 +8,7 @@
   "types": "./dist/esm/index.d.mts",
   "exports": {
     ".": {
+      "development": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
         "require": "./dist/cjs/index.d.ts"
@@ -17,7 +18,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "repository": {
     "type": "git",
@@ -43,7 +45,7 @@
   "homepage": "https://github.com/greydragon888/real-router",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.21.0",
+    "@real-router/core": "^0.23.0",
     "@real-router/logger": "^0.2.0"
   },
   "scripts": {

package/src/constants.ts

@@ -0,0 +1,11 @@
+// packages/logger-plugin/modules/constants.ts
+
+import type { LoggerPluginConfig } from "./types";
+
+export const DEFAULT_CONFIG: Required<LoggerPluginConfig> = {
+  level: "all",
+  usePerformanceMarks: false,
+  showParamsDiff: true,
+  showTiming: true,
+  context: "logger-plugin",
+};

package/src/index.ts

@@ -0,0 +1,9 @@
+// packages/logger-plugin/modules/index.ts
+
+// Public API exports for real-router-logger-plugin
+
+// Main plugin factory and instance
+export { loggerPluginFactory, loggerPlugin } from "./plugin";
+
+// Types
+export type { LoggerPluginConfig, LogLevel } from "./types";

package/src/internal/console-groups.ts

@@ -0,0 +1,74 @@
+// packages/logger-plugin/modules/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
+ */
+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/modules/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,95 @@
+// packages/logger-plugin/modules/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(", ")} }`);
+  }
+
+  const addedEntries = Object.entries(diff.added);
+
+  if (addedEntries.length > 0) {
+    parts.push(`Added: ${JSON.stringify(diff.added)}`);
+  }
+
+  const removedEntries = Object.entries(diff.removed);
+
+  if (removedEntries.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/modules/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.
+ */
+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/modules/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,266 @@
+// packages/logger-plugin/modules/plugin.ts
+
+import { DEFAULT_CONFIG } from "./constants";
+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 { LoggerPluginConfig, LogLevel } from "./types";
+import type { PluginFactory, RouterError, State } from "@real-router/core";
+
+/**
+ * Checks if the given log type should be output based on the configured level.
+ *
+ * Level hierarchy:
+ * - 'all': log everything (start, stop, transitions, warnings, errors)
+ * - 'transitions': only transition events (start, success, cancel, error)
+ * - 'errors': only errors
+ * - 'none': nothing
+ */
+const shouldLog = (
+  level: LogLevel,
+  type: "lifecycle" | "transition" | "warning" | "error",
+): boolean => {
+  if (level === "none") {
+    return false;
+  }
+
+  if (level === "errors") {
+    return type === "error";
+  }
+
+  if (level === "transitions") {
+    return type === "transition" || type === "warning" || type === "error";
+  }
+
+  // level === 'all'
+  return true;
+};
+
+/**
+ * Creates a logger-plugin for real-router.
+ *
+ * @param options - Plugin configuration options
+ * @returns Plugin factory function for real-router
+ *
+ * @example
+ * ```ts
+ * import { loggerPluginFactory } from "@real-router/logger-plugin";
+ *
+ * // Use with default configuration
+ * router.usePlugin(loggerPluginFactory());
+ *
+ * // Use with custom configuration
+ * router.usePlugin(loggerPluginFactory({
+ *   level: 'errors',           // only log errors
+ *   usePerformanceMarks: true, // enable Performance API
+ *   showTiming: false,         // disable timing info
+ *   showParamsDiff: false,     // disable params diff
+ *   context: 'my-router',      // custom context name
+ * }));
+ * ```
+ */
+export function loggerPluginFactory(
+  options?: Partial<LoggerPluginConfig>,
+): PluginFactory {
+  // Merge options with defaults
+  const config: Required<LoggerPluginConfig> = {
+    ...DEFAULT_CONFIG,
+    ...options,
+  };
+
+  return () => {
+    // Create helper managers
+    const groups = createGroupManager(supportsConsoleGroups());
+    const perf = createPerformanceTracker(
+      config.usePerformanceMarks,
+      config.context,
+    );
+
+    // Transition state
+    let transitionStartTime: number | null = null;
+
+    /**
+     * Logs parameter differences when navigating within the same route.
+     */
+    const logParamsIfNeeded = (toState: State, fromState?: State): void => {
+      if (!config.showParamsDiff || !fromState) {
+        return;
+      }
+
+      // Show diff only for the same route
+      if (toState.name !== fromState.name) {
+        return;
+      }
+
+      const diff = getParamsDiff(fromState.params, toState.params);
+
+      if (diff) {
+        logParamsDiff(diff, config.context);
+      }
+    };
+
+    /**
+     * Formats timing string based on config.
+     */
+    const getTiming = (): string => {
+      if (!config.showTiming) {
+        return "";
+      }
+
+      return formatTiming(transitionStartTime, now);
+    };
+
+    return {
+      onStart() {
+        perf.mark("router:start");
+
+        if (shouldLog(config.level, "lifecycle")) {
+          console.log(`[${config.context}] Router started`);
+        }
+      },
+
+      onStop() {
+        groups.close();
+
+        perf.mark("router:stop");
+        perf.measure("router:lifetime", "router:start", "router:stop");
+
+        if (shouldLog(config.level, "lifecycle")) {
+          console.log(`[${config.context}] Router stopped`);
+        }
+      },
+
+      onTransitionStart(toState: State, fromState?: State) {
+        groups.open("Router transition");
+        transitionStartTime = now();
+
+        const fromRoute = formatRouteName(fromState);
+        const toRoute = formatRouteName(toState);
+        const label = createTransitionLabel(fromRoute, toRoute);
+
+        perf.mark(`router:transition-start:${label}`);
+
+        if (shouldLog(config.level, "transition")) {
+          console.log(
+            `[${config.context}] Transition: ${fromRoute} → ${toRoute}`,
+            {
+              from: fromState,
+              to: toState,
+            },
+          );
+
+          logParamsIfNeeded(toState, fromState);
+        }
+      },
+
+      onTransitionSuccess(toState: State, fromState?: State) {
+        const fromRoute = formatRouteName(fromState);
+        const toRoute = formatRouteName(toState);
+        const label = createTransitionLabel(fromRoute, toRoute);
+
+        perf.mark(`router:transition-end:${label}`);
+        perf.measure(
+          `router:transition:${label}`,
+          `router:transition-start:${label}`,
+          `router:transition-end:${label}`,
+        );
+
+        if (shouldLog(config.level, "transition")) {
+          const timing = getTiming();
+
+          console.log(`[${config.context}] Transition success${timing}`, {
+            to: toState,
+            from: fromState,
+          });
+        }
+
+        groups.close();
+        transitionStartTime = null;
+      },
+
+      onTransitionCancel(toState: State, fromState?: State) {
+        const fromRoute = formatRouteName(fromState);
+        const toRoute = formatRouteName(toState);
+        const label = createTransitionLabel(fromRoute, toRoute);
+
+        perf.mark(`router:transition-cancel:${label}`);
+        perf.measure(
+          `router:transition-cancelled:${label}`,
+          `router:transition-start:${label}`,
+          `router:transition-cancel:${label}`,
+        );
+
+        if (shouldLog(config.level, "warning")) {
+          const timing = getTiming();
+
+          console.warn(`[${config.context}] Transition cancelled${timing}`, {
+            to: toState,
+            from: fromState,
+          });
+        }
+
+        groups.close();
+        transitionStartTime = null;
+      },
+
+      onTransitionError(
+        toState: State | undefined,
+        fromState: State | undefined,
+        err: RouterError,
+      ) {
+        const fromRoute = formatRouteName(fromState);
+        const toRoute = formatRouteName(toState);
+        const label = createTransitionLabel(fromRoute, toRoute);
+
+        perf.mark(`router:transition-error:${label}`);
+        perf.measure(
+          `router:transition-failed:${label}`,
+          `router:transition-start:${label}`,
+          `router:transition-error:${label}`,
+        );
+
+        if (shouldLog(config.level, "error")) {
+          const timing = getTiming();
+
+          console.error(
+            `[${config.context}] Transition error: ${err.code}${timing}`,
+            {
+              error: err,
+              stack: err.stack,
+              to: toState,
+              from: fromState,
+            },
+          );
+        }
+
+        groups.close();
+        transitionStartTime = null;
+      },
+
+      teardown() {
+        groups.close();
+        transitionStartTime = null;
+      },
+    };
+  };
+}
+
+/**
+ * Default logger-plugin instance with standard configuration.
+ * Provided for backward compatibility with existing code.
+ *
+ * @example
+ * // Use default configuration
+ * router.usePlugin(loggerPlugin);
+ */
+export const loggerPlugin = loggerPluginFactory();

package/src/types.ts

@@ -0,0 +1,67 @@
+// packages/logger-plugin/modules/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 false
+   */
+  showParamsDiff?: boolean;
+
+  /**
+   * Custom context name for console.
+   * Useful when running multiple routers.
+   *
+   * @default 'logger-plugin'
+   */
+  context?: string;
+}