@real-router/core 0.22.0 → 0.23.0

package/src/namespaces/OptionsNamespace/validators.ts

@@ -0,0 +1,252 @@
+// packages/core/src/namespaces/OptionsNamespace/validators.ts
+
+/**
+ * Static validation functions for OptionsNamespace.
+ * Called by Router facade before instance methods.
+ */
+
+import { isObjKey, getTypeDescription } from "type-guards";
+
+import {
+  defaultOptions,
+  VALID_OPTION_VALUES,
+  VALID_QUERY_PARAMS,
+} from "./constants";
+import { LIMIT_BOUNDS } from "../../constants";
+
+import type { LimitsConfig, Options } from "@real-router/types";
+
+/**
+ * Validates that value is a plain object without getters.
+ */
+export function validatePlainObject(
+  value: unknown,
+  optionName: string,
+  methodName: string,
+): asserts value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || value.constructor !== Object) {
+    throw new TypeError(
+      `[router.${methodName}] Invalid type for "${optionName}": ` +
+        `expected plain object, got ${getTypeDescription(value)}`,
+    );
+  }
+
+  // Getters can throw, return different values, or have side effects
+  for (const key in value) {
+    if (Object.getOwnPropertyDescriptor(value, key)?.get) {
+      throw new TypeError(
+        `[router.${methodName}] Getters not allowed in "${optionName}": "${key}"`,
+      );
+    }
+  }
+}
+
+/**
+ * Validates queryParams keys and values against allowed enums.
+ */
+export function validateQueryParams(
+  value: Record<string, unknown>,
+  methodName: string,
+): void {
+  for (const key in value) {
+    if (!isObjKey(key, VALID_QUERY_PARAMS)) {
+      const validKeys = Object.keys(VALID_QUERY_PARAMS)
+        .map((k) => `"${k}"`)
+        .join(", ");
+
+      throw new TypeError(
+        `[router.${methodName}] Unknown queryParams key: "${key}". ` +
+          `Valid keys: ${validKeys}`,
+      );
+    }
+
+    const paramValue = value[key];
+    const validValues = VALID_QUERY_PARAMS[key];
+    const isValid = (validValues as readonly string[]).includes(
+      paramValue as string,
+    );
+
+    if (!isValid) {
+      const allowedValues = validValues.map((v) => `"${v}"`).join(", ");
+
+      throw new TypeError(
+        `[router.${methodName}] Invalid value for queryParams.${key}: ` +
+          `expected one of ${allowedValues}, got "${String(paramValue)}"`,
+      );
+    }
+  }
+}
+
+/**
+ * Validates string enum options against allowed values.
+ */
+export function validateEnumOption(
+  optionName: keyof typeof VALID_OPTION_VALUES,
+  value: unknown,
+  methodName: string,
+): void {
+  const validValues = VALID_OPTION_VALUES[optionName];
+  const isValid = (validValues as readonly string[]).includes(value as string);
+
+  if (!isValid) {
+    const allowedValues = validValues.map((v) => `"${v}"`).join(", ");
+
+    throw new TypeError(
+      `[router.${methodName}] Invalid value for "${optionName}": ` +
+        `expected one of ${allowedValues}, got "${String(value)}"`,
+    );
+  }
+}
+
+/**
+ * Validates a single option value against expected type and constraints.
+ * Skips validation for unknown options - validateOptionExists handles that.
+ */
+export function validateOptionValue(
+  optionName: keyof Options,
+  value: unknown,
+  methodName: string,
+): void {
+  // Allow callback functions for dynamic default route/params options
+  // MUST be first check — before object branch (L140) which would reject
+  // functions via validatePlainObject for defaultParams (default = {})
+  if (
+    typeof value === "function" &&
+    (optionName === "defaultRoute" || optionName === "defaultParams")
+  ) {
+    return; // Valid — callback resolved at runtime
+  }
+
+  const expectedValue = defaultOptions[optionName];
+
+  // For object options - ensure plain objects only (not null, arrays, Date, etc)
+  if (expectedValue && typeof expectedValue === "object") {
+    validatePlainObject(value, optionName, methodName);
+
+    if (optionName === "queryParams") {
+      validateQueryParams(value, methodName);
+    }
+
+    return;
+  }
+
+  // For primitives - typeof check first
+  if (typeof value !== typeof expectedValue) {
+    throw new TypeError(
+      `[router.${methodName}] Invalid type for "${optionName}": ` +
+        `expected ${typeof expectedValue}, got ${typeof value}`,
+    );
+  }
+
+  // For string enum options - validate against allowed values
+  if (optionName in VALID_OPTION_VALUES) {
+    validateEnumOption(
+      optionName as keyof typeof VALID_OPTION_VALUES,
+      value,
+      methodName,
+    );
+  }
+}
+
+/**
+ * Validates optional fields not in defaultOptions.
+ * Note: logger is handled before validateOptions in Router constructor.
+ */
+function validateOptionalField(
+  key: string,
+  value: unknown,
+  methodName: string,
+): boolean {
+  if (key === "limits") {
+    if (value !== undefined) {
+      validateLimits(value, methodName);
+    }
+
+    return true;
+  }
+
+  throw new TypeError(`[router.${methodName}] Unknown option: "${key}"`);
+}
+
+/**
+ * Validates a partial options object.
+ * Called by facade before constructor/withOptions.
+ */
+export function validateOptions(
+  options: unknown,
+  methodName: string,
+): asserts options is Partial<Options> {
+  if (
+    !options ||
+    typeof options !== "object" ||
+    options.constructor !== Object
+  ) {
+    throw new TypeError(
+      `[router.${methodName}] Invalid options: expected plain object, got ${getTypeDescription(options)}`,
+    );
+  }
+
+  for (const [key, value] of Object.entries(options)) {
+    // Skip optional fields that aren't in defaultOptions (limits, logger, etc.)
+    if (!isObjKey(key, defaultOptions)) {
+      validateOptionalField(key, value, methodName);
+      continue;
+    }
+
+    // Skip undefined values for conditional configuration
+    if (value === undefined) {
+      continue;
+    }
+
+    validateOptionValue(key, value, methodName);
+  }
+}
+
+/**
+ * Validates that a limit value is within bounds.
+ */
+export function validateLimitValue(
+  limitName: keyof LimitsConfig,
+  value: unknown,
+  methodName: string,
+): void {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new TypeError(
+      `[router.${methodName}]: limit "${limitName}" must be an integer, got ${String(value)}`,
+    );
+  }
+
+  const bounds = LIMIT_BOUNDS[limitName];
+
+  if (value < bounds.min || value > bounds.max) {
+    throw new RangeError(
+      `[router.${methodName}]: limit "${limitName}" must be between ${bounds.min} and ${bounds.max}, got ${value}`,
+    );
+  }
+}
+
+/**
+ * Validates a partial limits object.
+ */
+export function validateLimits(
+  limits: unknown,
+  methodName: string,
+): asserts limits is Partial<LimitsConfig> {
+  if (!limits || typeof limits !== "object" || limits.constructor !== Object) {
+    throw new TypeError(
+      `[router.${methodName}]: invalid limits: expected plain object, got ${typeof limits}`,
+    );
+  }
+
+  for (const [key, value] of Object.entries(limits)) {
+    if (!Object.hasOwn(LIMIT_BOUNDS, key)) {
+      throw new TypeError(`[router.${methodName}]: unknown limit: "${key}"`);
+    }
+
+    if (value === undefined) {
+      continue;
+    }
+
+    validateLimitValue(key as keyof LimitsConfig, value, methodName);
+  }
+}

package/src/namespaces/PluginsNamespace/PluginsNamespace.ts

@@ -0,0 +1,325 @@
+// packages/core/src/namespaces/PluginsNamespace/PluginsNamespace.ts
+
+import { logger } from "@real-router/logger";
+
+import { EVENTS_MAP, EVENT_METHOD_NAMES, LOGGER_CONTEXT } from "./constants";
+import {
+  validatePlugin,
+  validatePluginLimit,
+  validateUsePluginArgs,
+} from "./validators";
+import { DEFAULT_LIMITS } from "../../constants";
+import { computeThresholds } from "../../helpers";
+
+import type { PluginsDependencies } from "./types";
+import type { Router } from "../../Router";
+import type { Limits, PluginFactory } from "../../types";
+import type {
+  DefaultDependencies,
+  Plugin,
+  Unsubscribe,
+} from "@real-router/types";
+
+/**
+ * Independent namespace for managing plugins.
+ *
+ * Static methods handle validation (called by facade).
+ * Instance methods handle storage and business logic.
+ */
+export class PluginsNamespace<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  readonly #plugins = new Set<PluginFactory<Dependencies>>();
+  readonly #unsubscribes = new Set<Unsubscribe>();
+
+  #router!: Router<Dependencies>;
+  #deps!: PluginsDependencies<Dependencies>;
+  #limits: Limits = DEFAULT_LIMITS;
+
+  // =========================================================================
+  // Static validation methods (called by facade before instance methods)
+  // Proxy to functions in validators.ts for separation of concerns
+  // =========================================================================
+
+  static validateUsePluginArgs<D extends DefaultDependencies>(
+    plugins: unknown[],
+  ): asserts plugins is PluginFactory<D>[] {
+    validateUsePluginArgs<D>(plugins);
+  }
+
+  static validatePlugin(plugin: Plugin): void {
+    validatePlugin(plugin);
+  }
+
+  static validatePluginLimit(
+    currentCount: number,
+    newCount: number,
+    maxPlugins?: number,
+  ): void {
+    validatePluginLimit(currentCount, newCount, maxPlugins);
+  }
+
+  static validateNoDuplicatePlugins<D extends DefaultDependencies>(
+    newFactories: PluginFactory<D>[],
+    hasPlugin: (factory: PluginFactory<D>) => boolean,
+  ): void {
+    for (const factory of newFactories) {
+      if (hasPlugin(factory)) {
+        throw new Error(
+          `[router.usePlugin] Plugin factory already registered. ` +
+            `To re-register, first unsubscribe the existing plugin.`,
+        );
+      }
+    }
+  }
+
+  // =========================================================================
+  // Dependency injection
+  // =========================================================================
+
+  setRouter(router: Router<Dependencies>): void {
+    this.#router = router;
+  }
+
+  setDependencies(deps: PluginsDependencies<Dependencies>): void {
+    this.#deps = deps;
+  }
+
+  setLimits(limits: Limits): void {
+    this.#limits = limits;
+  }
+
+  // =========================================================================
+  // Instance methods (trust input - already validated by facade)
+  // =========================================================================
+
+  /**
+   * Returns the number of registered plugins.
+   * Used by facade for limit validation.
+   */
+  count(): number {
+    return this.#plugins.size;
+  }
+
+  /**
+   * Registers one or more plugin factories.
+   * Returns unsubscribe function to remove all added plugins.
+   * Input already validated by facade (limit, duplicates).
+   *
+   * @param factories - Already validated by facade
+   */
+  use(...factories: PluginFactory<Dependencies>[]): Unsubscribe {
+    // Emit warnings for count thresholds (not validation, just warnings)
+    this.#checkCountThresholds(factories.length);
+
+    // Fast path for single plugin (common case)
+    if (factories.length === 1) {
+      const factory = factories[0];
+      const cleanup = this.#startPlugin(factory);
+
+      this.#plugins.add(factory);
+
+      let unsubscribed = false;
+
+      const unsubscribe: Unsubscribe = () => {
+        if (unsubscribed) {
+          return;
+        }
+
+        unsubscribed = true;
+        this.#plugins.delete(factory);
+        this.#unsubscribes.delete(unsubscribe);
+        try {
+          cleanup();
+        } catch (error) {
+          logger.error(LOGGER_CONTEXT, "Error during cleanup:", error);
+        }
+      };
+
+      this.#unsubscribes.add(unsubscribe);
+
+      return unsubscribe;
+    }
+
+    // Deduplicate batch with warning (validation already done by facade)
+    const seenInBatch = this.#deduplicateBatch(factories);
+
+    // Track successfully initialized plugins for cleanup
+    const initializedPlugins: {
+      factory: PluginFactory<Dependencies>;
+      cleanup: Unsubscribe;
+    }[] = [];
+
+    // Initialize deduplicated plugins sequentially
+    try {
+      for (const plugin of seenInBatch) {
+        const cleanup = this.#startPlugin(plugin);
+
+        initializedPlugins.push({ factory: plugin, cleanup });
+      }
+    } catch (error) {
+      // Rollback on failure - cleanup all initialized plugins
+      for (const { cleanup } of initializedPlugins) {
+        try {
+          cleanup();
+        } catch (cleanupError) {
+          logger.error(LOGGER_CONTEXT, "Cleanup error:", cleanupError);
+        }
+      }
+
+      throw error;
+    }
+
+    // Commit phase - add to registry
+    for (const { factory } of initializedPlugins) {
+      this.#plugins.add(factory);
+    }
+
+    // Return unsubscribe function
+    let unsubscribed = false;
+
+    const unsubscribe: Unsubscribe = () => {
+      if (unsubscribed) {
+        return;
+      }
+
+      unsubscribed = true;
+      this.#unsubscribes.delete(unsubscribe);
+
+      for (const { factory } of initializedPlugins) {
+        this.#plugins.delete(factory);
+      }
+
+      for (const { cleanup } of initializedPlugins) {
+        try {
+          cleanup();
+        } catch (error) {
+          logger.error(LOGGER_CONTEXT, "Error during cleanup:", error);
+        }
+      }
+    };
+
+    this.#unsubscribes.add(unsubscribe);
+
+    return unsubscribe;
+  }
+
+  /**
+   * Returns registered plugin factories.
+   */
+  getAll(): PluginFactory<Dependencies>[] {
+    return [...this.#plugins];
+  }
+
+  /**
+   * Checks if a plugin factory is registered.
+   * Used internally by validation to avoid array allocation.
+   */
+  has(factory: PluginFactory<Dependencies>): boolean {
+    return this.#plugins.has(factory);
+  }
+
+  disposeAll(): void {
+    for (const unsubscribe of this.#unsubscribes) {
+      unsubscribe();
+    }
+
+    this.#plugins.clear();
+    this.#unsubscribes.clear();
+  }
+
+  // =========================================================================
+  // Private methods
+  // =========================================================================
+
+  #checkCountThresholds(newCount: number): void {
+    const maxPlugins = this.#limits.maxPlugins;
+
+    if (maxPlugins === 0) {
+      return;
+    }
+
+    const totalCount = newCount + this.#plugins.size;
+
+    const { warn, error } = computeThresholds(maxPlugins);
+
+    if (totalCount >= error) {
+      logger.error(LOGGER_CONTEXT, `${totalCount} plugins registered!`);
+    } else if (totalCount >= warn) {
+      logger.warn(LOGGER_CONTEXT, `${totalCount} plugins registered`);
+    }
+  }
+
+  /**
+   * Deduplicates batch with warning for duplicates within batch.
+   * Validation (existing duplicates) is done by facade.
+   */
+  #deduplicateBatch(
+    plugins: PluginFactory<Dependencies>[],
+  ): Set<PluginFactory<Dependencies>> {
+    const seenInBatch = new Set<PluginFactory<Dependencies>>();
+
+    for (const plugin of plugins) {
+      if (seenInBatch.has(plugin)) {
+        logger.warn(
+          LOGGER_CONTEXT,
+          "Duplicate factory in batch, will be registered once",
+        );
+      } else {
+        seenInBatch.add(plugin);
+      }
+    }
+
+    return seenInBatch;
+  }
+
+  #startPlugin(pluginFactory: PluginFactory<Dependencies>): Unsubscribe {
+    // Bind getDependency to preserve 'this' context when called from factory
+    // Plugin factories receive full router as part of their public API
+    const appliedPlugin = pluginFactory(this.#router, this.#deps.getDependency);
+
+    PluginsNamespace.validatePlugin(appliedPlugin);
+
+    Object.freeze(appliedPlugin);
+
+    // Collect all unsubscribe functions
+    const removeEventListeners: Unsubscribe[] = [];
+
+    // Subscribe plugin methods to corresponding router events
+    for (const methodName of EVENT_METHOD_NAMES) {
+      if (methodName in appliedPlugin) {
+        if (typeof appliedPlugin[methodName] === "function") {
+          removeEventListeners.push(
+            this.#deps.addEventListener(
+              EVENTS_MAP[methodName],
+              appliedPlugin[methodName],
+            ),
+          );
+
+          if (methodName === "onStart" && this.#deps.canNavigate()) {
+            logger.warn(
+              LOGGER_CONTEXT,
+              "Router already started, onStart will not be called",
+            );
+          }
+        } else {
+          logger.warn(
+            LOGGER_CONTEXT,
+            `Property '${methodName}' is not a function, skipping`,
+          );
+        }
+      }
+    }
+
+    // Return composite cleanup function
+    return () => {
+      for (const removeListener of removeEventListeners) {
+        removeListener();
+      }
+
+      if (typeof appliedPlugin.teardown === "function") {
+        appliedPlugin.teardown();
+      }
+    };
+  }
+}

package/src/namespaces/PluginsNamespace/constants.ts

@@ -0,0 +1,35 @@
+// packages/core/src/namespaces/PluginsNamespace/constants.ts
+
+import { isObjKey } from "type-guards";
+
+import {
+  events as EVENTS_CONST,
+  plugins as PLUGINS_CONST,
+} from "../../constants";
+
+import type { EventName } from "@real-router/types";
+
+/**
+ * Maps plugin method names to router event names.
+ */
+export const EVENTS_MAP = {
+  [PLUGINS_CONST.ROUTER_START]: EVENTS_CONST.ROUTER_START,
+  [PLUGINS_CONST.ROUTER_STOP]: EVENTS_CONST.ROUTER_STOP,
+  [PLUGINS_CONST.TRANSITION_SUCCESS]: EVENTS_CONST.TRANSITION_SUCCESS,
+  [PLUGINS_CONST.TRANSITION_START]: EVENTS_CONST.TRANSITION_START,
+  [PLUGINS_CONST.TRANSITION_ERROR]: EVENTS_CONST.TRANSITION_ERROR,
+  [PLUGINS_CONST.TRANSITION_CANCEL]: EVENTS_CONST.TRANSITION_CANCEL,
+} as const satisfies Record<
+  (typeof PLUGINS_CONST)[keyof typeof PLUGINS_CONST],
+  EventName
+>;
+
+/**
+ * Plugin method names that correspond to router events.
+ */
+export const EVENT_METHOD_NAMES = Object.keys(EVENTS_MAP).filter(
+  (eventName): eventName is keyof typeof EVENTS_MAP =>
+    isObjKey<typeof EVENTS_MAP>(eventName, EVENTS_MAP),
+);
+
+export const LOGGER_CONTEXT = "router.usePlugin";

package/src/namespaces/PluginsNamespace/index.ts

@@ -0,0 +1,7 @@
+// packages/core/src/namespaces/PluginsNamespace/index.ts
+
+export { PluginsNamespace } from "./PluginsNamespace";
+
+export { EVENTS_MAP, EVENT_METHOD_NAMES } from "./constants";
+
+export type { PluginsDependencies } from "./types";

package/src/namespaces/PluginsNamespace/types.ts

@@ -0,0 +1,32 @@
+// packages/core/src/namespaces/PluginsNamespace/types.ts
+
+import type { EventMethodMap } from "../../types";
+import type {
+  DefaultDependencies,
+  EventName,
+  Plugin,
+  Unsubscribe,
+} from "@real-router/types";
+
+/**
+ * Dependencies injected into PluginsNamespace.
+ *
+ * Note: Plugin factories still receive the router object directly
+ * as they need access to various router methods. This interface
+ * only covers the internal namespace operations.
+ */
+export interface PluginsDependencies<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  /** Add event listener for plugin subscription */
+  addEventListener: <E extends EventName>(
+    eventName: E,
+    cb: Plugin[EventMethodMap[E]],
+  ) => Unsubscribe;
+
+  /** Check if navigation is possible (for warning about late onStart) */
+  canNavigate: () => boolean;
+
+  /** Get dependency value for plugin factory */
+  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K];
+}