@real-router/core 0.56.0 → 0.57.0

package/src/namespaces/OptionsNamespace/helpers.ts

@@ -1,50 +0,0 @@
-// packages/core/src/namespaces/OptionsNamespace/helpers.ts
-
-import type { Options, Params } from "@real-router/types";
-
-/**
- * Recursively freezes an object and all nested objects.
- * Only freezes plain objects, not primitives or special objects.
- */
-export function deepFreeze<T extends object>(obj: T): Readonly<T> {
-  Object.freeze(obj);
-
-  for (const key of Object.keys(obj)) {
-    const value = (obj as Record<string, unknown>)[key];
-
-    if (value && typeof value === "object" && value.constructor === Object) {
-      deepFreeze(value);
-    }
-  }
-
-  return obj;
-}
-
-/**
- * Resolves an option value that can be static or a callback.
- * If the value is a function, calls it with getDependency and returns the result.
- * Otherwise, returns the value as-is.
- */
-export function resolveOption(
-  value: Options["defaultRoute"],
-  getDependency: (name: string) => unknown,
-): string;
-
-export function resolveOption(
-  value: Options["defaultParams"],
-  getDependency: (name: string) => unknown,
-): Params;
-
-export function resolveOption(
-  value: Options["defaultRoute"] | Options["defaultParams"],
-  getDependency: (name: string) => unknown,
-): string | Params {
-  if (typeof value === "function") {
-    // Runtime getDependency is (name: string) => unknown, but DefaultRouteCallback<object>
-    // expects <K extends keyof object>(name: K) => object[K] where keyof object = never.
-    // Cast needed to bridge generic constraint mismatch.
-    return value(getDependency as never);
-  }
-
-  return value;
-}

package/src/namespaces/OptionsNamespace/index.ts

@@ -1,7 +0,0 @@
-// packages/core/src/namespaces/OptionsNamespace/index.ts
-
-export { OptionsNamespace } from "./OptionsNamespace";
-
-export { defaultOptions } from "./constants";
-
-export { deepFreeze, resolveOption } from "./helpers";

package/src/namespaces/OptionsNamespace/validators.ts

@@ -1,13 +0,0 @@
-// packages/core/src/namespaces/OptionsNamespace/validators.ts
-
-/**
- * Minimal crash guard for options.
- * Full DX validation moved to @real-router/validation-plugin (retrospective pattern).
- */
-export function validateOptionsIsObject(
-  options: unknown,
-): asserts options is Record<string, unknown> {
-  if (!options || typeof options !== "object" || Array.isArray(options)) {
-    throw new TypeError("[router.constructor] options must be a plain object");
-  }
-}

package/src/namespaces/PluginsNamespace/PluginsNamespace.ts

@@ -1,291 +0,0 @@
-// 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 } from "./validators";
-import { DEFAULT_LIMITS } from "../../constants";
-
-import type { PluginsDependencies } from "./types";
-import type { Limits, PluginFactory } from "../../types";
-import type { RouterValidator } from "../../types/RouterValidator";
-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>();
-
-  #deps!: PluginsDependencies<Dependencies>;
-  #limits: Limits = DEFAULT_LIMITS;
-  #getValidator: (() => RouterValidator | null) | null = null;
-
-  // =========================================================================
-  // Static validation methods (called by facade before instance methods)
-  // Proxy to functions in validators.ts for separation of concerns
-  // =========================================================================
-
-  static validatePlugin(plugin: Plugin): void {
-    validatePlugin(plugin);
-  }
-
-  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
-  // =========================================================================
-
-  setDependencies(deps: PluginsDependencies<Dependencies>): void {
-    this.#deps = deps;
-  }
-
-  setLimits(limits: Limits): void {
-    this.#limits = limits;
-    // eslint-disable-next-line sonarjs/void-use -- @preserve: limits passed to validator via RouterInternals; void suppresses TS6133 until plugin implements validateCountThresholds
-    void this.#limits;
-  }
-
-  setValidatorGetter(getter: () => RouterValidator | null): void {
-    this.#getValidator = getter;
-  }
-
-  // =========================================================================
-  // Instance methods (trust input - already validated by facade)
-  // =========================================================================
-
-  /**
-   * Returns the number of registered plugins.
-   * Used by facade for limit validation.
-   */
-  /* v8 ignore next 3 -- @preserve: only called via validator interface (ctx.validator?.plugins.validatePluginLimit), not reachable without validation plugin */
-  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.#getValidator?.()?.plugins.validateCountThresholds(
-      this.#plugins.size + 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.
-   */
-  /* v8 ignore next 3 -- @preserve: only called via validator interface, not reachable without validation plugin */
-  has(factory: PluginFactory<Dependencies>): boolean {
-    return this.#plugins.has(factory);
-  }
-
-  /**
-   * Disposes all registered plugins by running their teardown callbacks
-   * and removing event listener subscriptions.
-   * Active disposal is required because plugins have an active lifecycle
-   * (event subscriptions, teardown hooks).
-   * Named "dispose" (not "clear") because there is active cleanup to perform.
-   */
-  disposeAll(): void {
-    for (const unsubscribe of this.#unsubscribes) {
-      unsubscribe();
-    }
-
-    this.#plugins.clear();
-    this.#unsubscribes.clear();
-  }
-
-  // =========================================================================
-  // Private methods
-  // =========================================================================
-
-  /**
-   * 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)) {
-        this.#getValidator?.()?.plugins.warnBatchDuplicates(plugins);
-      } else {
-        seenInBatch.add(plugin);
-      }
-    }
-
-    return seenInBatch;
-  }
-
-  #startPlugin(pluginFactory: PluginFactory<Dependencies>): Unsubscribe {
-    const appliedPlugin = this.#deps.compileFactory(pluginFactory);
-
-    PluginsNamespace.validatePlugin(appliedPlugin);
-    this.#getValidator?.()?.plugins.validatePluginKeys(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()) {
-            this.#getValidator?.()?.plugins.warnPluginAfterStart(methodName);
-          }
-        } else {
-          this.#getValidator?.()?.plugins.warnPluginMethodType(methodName);
-        }
-      }
-    }
-
-    // Return composite cleanup function
-    return () => {
-      for (const removeListener of removeEventListeners) {
-        removeListener();
-      }
-
-      if (typeof appliedPlugin.teardown === "function") {
-        appliedPlugin.teardown();
-      }
-    };
-  }
-}

package/src/namespaces/PluginsNamespace/constants.ts

@@ -1,34 +0,0 @@
-// packages/core/src/namespaces/PluginsNamespace/constants.ts
-
-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_LEAVE_APPROVE]:
-    EVENTS_CONST.TRANSITION_LEAVE_APPROVE,
-  [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,
-) as (keyof typeof EVENTS_MAP)[];
-
-export const LOGGER_CONTEXT = "router.usePlugin";

package/src/namespaces/PluginsNamespace/index.ts

@@ -1,7 +0,0 @@
-// 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

@@ -1,22 +0,0 @@
-// packages/core/src/namespaces/PluginsNamespace/types.ts
-
-import type { EventMethodMap, PluginFactory } from "../../types";
-import type {
-  DefaultDependencies,
-  EventName,
-  Plugin,
-  Unsubscribe,
-} from "@real-router/types";
-
-export interface PluginsDependencies<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> {
-  addEventListener: <E extends EventName>(
-    eventName: E,
-    cb: Plugin[EventMethodMap[E]],
-  ) => Unsubscribe;
-
-  canNavigate: () => boolean;
-
-  compileFactory: (factory: PluginFactory<Dependencies>) => Plugin;
-}

package/src/namespaces/PluginsNamespace/validators.ts

@@ -1,28 +0,0 @@
-// packages/core/src/namespaces/PluginsNamespace/validators.ts
-
-/**
- * Static validation functions for PluginsNamespace.
- * Called by Router facade before instance methods.
- */
-
-import type { Plugin } from "@real-router/types";
-
-/**
- * Validates that a plugin factory returned a valid plugin object.
- */
-export function validatePlugin(plugin: Plugin): void {
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-  if (!(plugin && typeof plugin === "object") || Array.isArray(plugin)) {
-    throw new TypeError(
-      `[router.usePlugin] Plugin factory must return an object, got ${typeof plugin}`,
-    );
-  }
-
-  // Detect async factory (returns Promise)
-  if (typeof (plugin as unknown as { then?: unknown }).then === "function") {
-    throw new TypeError(
-      `[router.usePlugin] Async plugin factories are not supported. ` +
-        `Factory returned a Promise instead of a plugin object.`,
-    );
-  }
-}