@real-router/core 0.22.0 → 0.23.0

package/src/helpers.ts

@@ -0,0 +1,194 @@
+// packages/real-router/modules/helpers.ts
+
+import { DEFAULT_LIMITS } from "./constants";
+
+import type { Limits } from "./types";
+import type { State, LimitsConfig } from "@real-router/types";
+
+export { getTypeDescription } from "type-guards";
+
+// =============================================================================
+// State Helpers
+// =============================================================================
+
+/**
+ * Structural type guard for State object.
+ * Only checks required fields exist with correct types.
+ * Does NOT validate params serializability (allows circular refs).
+ *
+ * Use `isState` from type-guards for full validation (serializable params).
+ * Use this for internal operations like deepFreezeState that handle any object structure.
+ *
+ * @param value - Value to check
+ * @returns true if value has State structure
+ * @internal
+ */
+function isStateStructural(value: unknown): value is State {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+
+  const obj = value as Record<string, unknown>;
+
+  return (
+    typeof obj.name === "string" &&
+    typeof obj.path === "string" &&
+    typeof obj.params === "object" &&
+    obj.params !== null
+  );
+}
+
+/**
+ * Deep freezes State object to prevent mutations.
+ * Creates a deep clone first, then recursively freezes the clone and all nested objects.
+ * Uses simple recursive freezing after cloning (no need for WeakSet since clone has no circular refs).
+ *
+ * @param state - The State object to freeze
+ * @returns A frozen deep clone of the state
+ * @throws {TypeError} If state is not a valid State object
+ *
+ * @example
+ * const state = { name: 'home', params: {}, path: '/' };
+ * const frozen = deepFreezeState(state);
+ * // frozen.params is now immutable
+ * // original state is unchanged
+ */
+export function deepFreezeState<T extends State>(state: T): T {
+  // Early return for null/undefined
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!state) {
+    return state;
+  }
+
+  // Validate State structure (structural check, allows circular refs)
+  if (!isStateStructural(state)) {
+    throw new TypeError(
+      `[deepFreezeState] Expected valid State object, got: ${typeof state}`,
+    );
+  }
+
+  // Create a deep clone to avoid mutating the original
+  // structuredClone preserves circular references, so we need to track visited objects
+  const clonedState = structuredClone(state);
+
+  // WeakSet to track visited objects (prevent infinite recursion with circular refs)
+  const visited = new WeakSet<object>();
+
+  // Recursive freeze function with circular reference protection
+  function freezeClonedRecursive(obj: unknown): void {
+    // Skip primitives, null, undefined
+    // Note: typeof undefined === "undefined" !== "object", so checking undefined is redundant
+    if (obj === null || typeof obj !== "object") {
+      return;
+    }
+
+    // Skip already visited objects (circular reference protection)
+    if (visited.has(obj)) {
+      return;
+    }
+
+    // Mark as visited
+    visited.add(obj);
+
+    // Freeze the object/array itself
+    Object.freeze(obj);
+
+    // Get all values to freeze recursively
+    const values = Array.isArray(obj) ? obj : Object.values(obj);
+
+    // Recursively freeze nested values
+    for (const value of values) {
+      freezeClonedRecursive(value);
+    }
+  }
+
+  // Freeze the entire cloned state tree
+  freezeClonedRecursive(clonedState);
+
+  return clonedState;
+}
+
+// WeakSet to track already frozen root objects for O(1) re-freeze check
+const frozenRoots = new WeakSet<object>();
+
+// Module-scope recursive freeze function - better JIT optimization, no allocation per call
+function freezeRecursive(obj: unknown): void {
+  // Skip primitives, null
+  if (obj === null || typeof obj !== "object") {
+    return;
+  }
+
+  // Skip already frozen objects (handles potential shared refs)
+  if (Object.isFrozen(obj)) {
+    return;
+  }
+
+  // Freeze the object/array
+  Object.freeze(obj);
+
+  // Iterate without Object.values() allocation
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      freezeRecursive(item);
+    }
+  } else {
+    for (const key in obj) {
+      freezeRecursive((obj as Record<string, unknown>)[key]);
+    }
+  }
+}
+
+/**
+ * Freezes State object in-place without cloning.
+ * Optimized for hot paths where state is known to be a fresh object.
+ *
+ * IMPORTANT: Only use this when you know the state is a fresh object
+ * that hasn't been exposed to external code yet (e.g., from makeState()).
+ *
+ * @param state - The State object to freeze (must be a fresh object)
+ * @returns The same state object, now frozen
+ * @internal
+ */
+export function freezeStateInPlace<T extends State>(state: T): T {
+  // Early return for null/undefined - state from makeState() is never null
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!state) {
+    return state;
+  }
+
+  // Fast path: already processed root object - O(1) check
+  if (frozenRoots.has(state)) {
+    return state;
+  }
+
+  // Freeze the entire state tree
+  freezeRecursive(state);
+
+  // Mark root as processed for future calls
+  frozenRoots.add(state);
+
+  return state;
+}
+
+/**
+ * Computes warning and error thresholds for a given limit.
+ * WARN threshold: 20% of limit
+ * ERROR threshold: 50% of limit
+ */
+export function computeThresholds(limit: number): {
+  warn: number;
+  error: number;
+} {
+  return {
+    warn: Math.floor(limit * 0.2),
+    error: Math.floor(limit * 0.5),
+  };
+}
+
+/**
+ * Merges user limits with defaults.
+ * Returns frozen object for immutability.
+ */
+export function createLimits(userLimits: Partial<LimitsConfig> = {}): Limits {
+  return { ...DEFAULT_LIMITS, ...userLimits };
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+// packages/real-router/modules/index.ts
+
+// Router-dependent types (defined in core)
+export type {
+  ActivationFnFactory,
+  BuildStateResultWithSegments,
+  MiddlewareFactory,
+  PluginFactory,
+  Route,
+  RouteConfigUpdate,
+} from "./types";
+
+// Router class (replaces Router interface from core-types)
+export { Router } from "./Router";
+
+// Types (re-exported from core-types - no Router dependency)
+export type {
+  ActivationFn,
+  Config,
+  DefaultDependencies,
+  Listener,
+  Middleware,
+  Navigator,
+  NavigationOptions,
+  Options,
+  Params,
+  Plugin,
+  SimpleState,
+  State,
+  StateMeta,
+  SubscribeFn,
+  SubscribeState,
+  Subscription,
+  Unsubscribe,
+} from "@real-router/types";
+
+export type { ErrorCodes, Constants } from "./constants";
+
+export { events, constants, errorCodes } from "./constants";
+
+// RouterError class (migrated from router-error package)
+export { RouterError } from "./RouterError";
+
+export { createRouter } from "./createRouter";
+
+export { getNavigator } from "./getNavigator";

package/src/namespaces/CloneNamespace/CloneNamespace.ts

@@ -0,0 +1,120 @@
+// packages/core/src/namespaces/CloneNamespace/CloneNamespace.ts
+
+import { getTypeDescription } from "type-guards";
+
+import type { ApplyConfigFn, CloneData, RouterFactory } from "./types";
+import type { Router } from "../../Router";
+import type { DefaultDependencies } from "@real-router/types";
+
+/**
+ * Independent namespace for router cloning operations.
+ *
+ * This namespace handles the logic of collecting data from a source router
+ * and creating a configured clone. It requires a factory function to create
+ * the new router instance.
+ */
+export class CloneNamespace<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  // =========================================================================
+  // Instance fields
+  // =========================================================================
+
+  /**
+   * Function to get cloning data from the source router.
+   */
+  #getCloneData!: () => CloneData<Dependencies>;
+
+  // =========================================================================
+  // Static validation methods (called by facade before instance methods)
+  // =========================================================================
+
+  /**
+   * Validates clone arguments.
+   * Dependencies can be undefined or a plain object without getters.
+   */
+  static validateCloneArgs(dependencies: unknown): void {
+    // undefined is valid (no new dependencies)
+    if (dependencies === undefined) {
+      return;
+    }
+
+    // Must be a plain object
+    if (
+      !(
+        dependencies &&
+        typeof dependencies === "object" &&
+        dependencies.constructor === Object
+      )
+    ) {
+      throw new TypeError(
+        `[router.clone] Invalid dependencies: expected plain object or undefined, received ${getTypeDescription(dependencies)}`,
+      );
+    }
+
+    // Getters can throw, return different values, or have side effects
+    for (const key in dependencies) {
+      if (Object.getOwnPropertyDescriptor(dependencies, key)?.get) {
+        throw new TypeError(
+          `[router.clone] Getters not allowed in dependencies: "${key}"`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Sets the function to collect clone data.
+   */
+  setGetCloneData(getCloneData: () => CloneData<Dependencies>): void {
+    this.#getCloneData = getCloneData;
+  }
+
+  /**
+   * Creates a clone of the router with optional new dependencies.
+   *
+   * @param dependencies - Optional new dependencies for the cloned router
+   * @param factory - Factory function to create the new router instance
+   * @param applyConfig - Function to apply route config to the new router
+   */
+  clone(
+    dependencies: Dependencies | undefined,
+    factory: RouterFactory<Dependencies>,
+    applyConfig: ApplyConfigFn<Dependencies>,
+  ): Router<Dependencies> {
+    // Collect all data from source router
+    const data = this.#getCloneData();
+
+    // Merge dependencies
+    const mergedDeps = {
+      ...data.dependencies,
+      ...dependencies,
+    } as Dependencies;
+
+    // Create new router instance
+    const newRouter = factory(data.routes, data.options, mergedDeps);
+
+    // Copy lifecycle factories
+    for (const [name, handler] of Object.entries(data.canDeactivateFactories)) {
+      newRouter.addDeactivateGuard(name, handler);
+    }
+
+    for (const [name, handler] of Object.entries(data.canActivateFactories)) {
+      newRouter.addActivateGuard(name, handler);
+    }
+
+    // Copy middleware factories
+    if (data.middlewareFactories.length > 0) {
+      newRouter.useMiddleware(...data.middlewareFactories);
+    }
+
+    // Copy plugin factories
+    if (data.pluginFactories.length > 0) {
+      newRouter.usePlugin(...data.pluginFactories);
+    }
+
+    // Apply route config (decoders, encoders, defaultParams, forwardMap)
+    applyConfig(newRouter, data.routeConfig, data.resolvedForwardMap);
+
+    return newRouter;
+  }
+}

package/src/namespaces/CloneNamespace/index.ts

@@ -0,0 +1,3 @@
+export { CloneNamespace } from "./CloneNamespace";
+
+export type { ApplyConfigFn, CloneData, RouterFactory } from "./types";

package/src/namespaces/CloneNamespace/types.ts

@@ -0,0 +1,46 @@
+// packages/core/src/namespaces/CloneNamespace/types.ts
+
+import type { Router } from "../../Router";
+import type {
+  ActivationFnFactory,
+  MiddlewareFactory,
+  PluginFactory,
+  Route,
+} from "../../types";
+import type { RouteConfig } from "../RoutesNamespace";
+import type { DefaultDependencies, Options } from "@real-router/types";
+
+/**
+ * Data collected from source router for cloning.
+ */
+export interface CloneData<Dependencies extends DefaultDependencies> {
+  routes: Route<Dependencies>[];
+  options: Options;
+  dependencies: Partial<Dependencies>;
+  canDeactivateFactories: Record<string, ActivationFnFactory<Dependencies>>;
+  canActivateFactories: Record<string, ActivationFnFactory<Dependencies>>;
+  middlewareFactories: MiddlewareFactory<Dependencies>[];
+  pluginFactories: PluginFactory<Dependencies>[];
+  routeConfig: RouteConfig;
+  resolvedForwardMap: Record<string, string>;
+}
+
+/**
+ * Factory function to create a new router instance.
+ */
+export type RouterFactory<Dependencies extends DefaultDependencies> = (
+  routes: Route<Dependencies>[],
+  options: Partial<Options>,
+  dependencies: Dependencies,
+) => Router<Dependencies>;
+
+/**
+ * Function to apply route config to a new router.
+ */
+export type ApplyConfigFn<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> = (
+  router: Router<Dependencies>,
+  config: RouteConfig,
+  resolvedForwardMap: Record<string, string>,
+) => void;

package/src/namespaces/DependenciesNamespace/DependenciesNamespace.ts

@@ -0,0 +1,250 @@
+// packages/core/src/namespaces/DependenciesNamespace/DependenciesNamespace.ts
+
+import { logger } from "@real-router/logger";
+import { getTypeDescription } from "type-guards";
+
+import {
+  validateDependencyExists,
+  validateDependencyLimit,
+  validateDependencyName,
+  validateDependenciesObject,
+  validateSetDependencyArgs,
+} from "./validators";
+import { DEFAULT_LIMITS } from "../../constants";
+import { computeThresholds } from "../../helpers";
+
+import type { Limits } from "../../types";
+import type { DefaultDependencies } from "@real-router/types";
+
+/**
+ * Independent namespace for managing router dependencies.
+ *
+ * Static methods handle validation (called by facade).
+ * Instance methods handle storage and business logic (limits, warnings).
+ */
+export class DependenciesNamespace<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> {
+  readonly #dependencies: Partial<Dependencies> = Object.create(
+    null,
+  ) as Partial<Dependencies>;
+
+  #limits: Limits = DEFAULT_LIMITS;
+
+  constructor(initialDependencies: Partial<Dependencies> = {} as Dependencies) {
+    this.setMultiple(initialDependencies);
+  }
+
+  // =========================================================================
+  // Static validation methods (called by facade before instance methods)
+  // Proxy to functions in validators.ts for separation of concerns
+  // =========================================================================
+
+  static validateName(
+    name: unknown,
+    methodName: string,
+  ): asserts name is string {
+    validateDependencyName(name, methodName);
+  }
+
+  static validateSetDependencyArgs(name: unknown): asserts name is string {
+    validateSetDependencyArgs(name);
+  }
+
+  static validateDependenciesObject(
+    deps: unknown,
+    methodName: string,
+  ): asserts deps is Record<string, unknown> {
+    validateDependenciesObject(deps, methodName);
+  }
+
+  static validateDependencyExists(
+    value: unknown,
+    dependencyName: string,
+  ): asserts value is NonNullable<unknown> {
+    validateDependencyExists(value, dependencyName);
+  }
+
+  static validateDependencyLimit(
+    currentCount: number,
+    newCount: number,
+    methodName: string,
+    maxDependencies?: number,
+  ): void {
+    validateDependencyLimit(
+      currentCount,
+      newCount,
+      methodName,
+      maxDependencies,
+    );
+  }
+
+  setLimits(limits: Limits): void {
+    this.#limits = limits;
+  }
+
+  // =========================================================================
+  // Instance methods (trust input - already validated by facade)
+  // =========================================================================
+
+  /**
+   * Sets a single dependency.
+   * Returns true if set, false if value was undefined (no-op).
+   *
+   * @param dependencyName - Already validated by facade
+   * @param dependencyValue - Value to set
+   */
+  set<K extends keyof Dependencies & string>(
+    dependencyName: K,
+    dependencyValue: Dependencies[K],
+  ): boolean {
+    // undefined = "don't set" (feature for conditional setting)
+    if (dependencyValue === undefined) {
+      return false;
+    }
+
+    const isNewKey = !Object.hasOwn(this.#dependencies, dependencyName);
+
+    if (isNewKey) {
+      // Only check limit when adding new keys (overwrites don't increase count)
+      this.#checkDependencyCount("setDependency");
+    } else {
+      const oldValue = this.#dependencies[dependencyName];
+      const isChanging = oldValue !== dependencyValue;
+      // Special case for NaN idempotency (NaN !== NaN is always true)
+      const bothAreNaN =
+        Number.isNaN(oldValue) && Number.isNaN(dependencyValue);
+
+      if (isChanging && !bothAreNaN) {
+        logger.warn(
+          "router.setDependency",
+          "Router dependency already exists and is being overwritten:",
+          dependencyName,
+        );
+      }
+    }
+
+    this.#dependencies[dependencyName] = dependencyValue;
+
+    return true;
+  }
+
+  /**
+   * Sets multiple dependencies at once.
+   * Limit check should be done by facade before calling this method.
+   *
+   * @param deps - Already validated by facade
+   */
+  setMultiple(deps: Partial<Dependencies>): void {
+    const overwrittenKeys: string[] = [];
+
+    for (const key in deps) {
+      if (deps[key] !== undefined) {
+        if (Object.hasOwn(this.#dependencies, key)) {
+          overwrittenKeys.push(key);
+        }
+
+        this.#dependencies[key] = deps[key];
+      }
+    }
+
+    if (overwrittenKeys.length > 0) {
+      logger.warn(
+        "router.setDependencies",
+        "Overwritten:",
+        overwrittenKeys.join(", "),
+      );
+    }
+  }
+
+  /**
+   * Gets a single dependency.
+   * Throws if not found.
+   *
+   * @param dependencyName - Already validated by facade
+   */
+  get<K extends keyof Dependencies>(dependencyName: K): Dependencies[K] {
+    return this.#dependencies[dependencyName] as Dependencies[K];
+  }
+
+  /**
+   * Gets all dependencies as a shallow copy.
+   */
+  getAll(): Partial<Dependencies> {
+    return { ...this.#dependencies };
+  }
+
+  /**
+   * Gets the current number of dependencies.
+   */
+  count(): number {
+    return Object.keys(this.#dependencies).length;
+  }
+
+  /**
+   * Removes a dependency by name.
+   * Logs warning if dependency doesn't exist.
+   */
+  remove(dependencyName: keyof Dependencies): void {
+    if (!Object.hasOwn(this.#dependencies, dependencyName)) {
+      logger.warn(
+        `router.removeDependency`,
+        `Attempted to remove non-existent dependency: "${getTypeDescription(dependencyName)}"`,
+      );
+    }
+
+    delete this.#dependencies[dependencyName];
+  }
+
+  /**
+   * Checks if a dependency exists.
+   */
+  has(dependencyName: keyof Dependencies): boolean {
+    return Object.hasOwn(this.#dependencies, dependencyName);
+  }
+
+  /**
+   * Removes all dependencies.
+   */
+  reset(): void {
+    for (const key in this.#dependencies) {
+      delete this.#dependencies[key];
+    }
+  }
+
+  // =========================================================================
+  // Private methods (business logic)
+  // =========================================================================
+
+  #checkDependencyCount(methodName: string): void {
+    const maxDependencies = this.#limits.maxDependencies;
+
+    if (maxDependencies === 0) {
+      return;
+    }
+
+    const currentCount = Object.keys(this.#dependencies).length;
+
+    const { warn, error } = computeThresholds(maxDependencies);
+
+    if (currentCount === warn) {
+      logger.warn(
+        `router.${methodName}`,
+        `${warn} dependencies registered. ` + `Consider if all are necessary.`,
+      );
+    } else if (currentCount === error) {
+      logger.error(
+        `router.${methodName}`,
+        `${error} dependencies registered! ` +
+          `This indicates architectural problems. ` +
+          `Hard limit at ${maxDependencies}.`,
+      );
+    } else if (currentCount >= maxDependencies) {
+      throw new Error(
+        `[router.${methodName}] Dependency limit exceeded (${maxDependencies}). ` +
+          `Current: ${currentCount}. This is likely a bug in your code. ` +
+          `If you genuinely need more dependencies, your architecture needs refactoring.`,
+      );
+    }
+  }
+}

package/src/namespaces/DependenciesNamespace/index.ts

@@ -0,0 +1,3 @@
+// packages/core/src/namespaces/DependenciesNamespace/index.ts
+
+export { DependenciesNamespace } from "./DependenciesNamespace";