@real-router/core 0.24.0 → 0.25.1

package/src/namespaces/MiddlewareNamespace/MiddlewareNamespace.ts

@@ -1,221 +0,0 @@
-// packages/core/src/namespaces/MiddlewareNamespace/MiddlewareNamespace.ts
-
-import { logger } from "@real-router/logger";
-
-import { LOGGER_CONTEXT } from "./constants";
-import {
-  validateMiddleware,
-  validateMiddlewareLimit,
-  validateNoDuplicates,
-  validateUseMiddlewareArgs,
-} from "./validators";
-import { DEFAULT_LIMITS } from "../../constants";
-import { computeThresholds } from "../../helpers";
-
-import type { InitializedMiddleware, MiddlewareDependencies } from "./types";
-import type { Router } from "../../Router";
-import type { Limits, MiddlewareFactory } from "../../types";
-import type {
-  DefaultDependencies,
-  Middleware,
-  Unsubscribe,
-} from "@real-router/types";
-
-/**
- * Independent namespace for managing middleware.
- *
- * Static methods handle validation (called by facade).
- * Instance methods handle storage and business logic.
- */
-export class MiddlewareNamespace<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> {
-  readonly #factories = new Set<MiddlewareFactory<Dependencies>>();
-  readonly #factoryToMiddleware = new Map<
-    MiddlewareFactory<Dependencies>,
-    Middleware
-  >();
-
-  #router!: Router<Dependencies>;
-  #deps!: MiddlewareDependencies<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 validateUseMiddlewareArgs<D extends DefaultDependencies>(
-    middlewares: unknown[],
-  ): asserts middlewares is MiddlewareFactory<D>[] {
-    validateUseMiddlewareArgs<D>(middlewares);
-  }
-
-  static validateMiddleware<D extends DefaultDependencies>(
-    middleware: unknown,
-    factory: MiddlewareFactory<D>,
-  ): asserts middleware is Middleware {
-    validateMiddleware<D>(middleware, factory);
-  }
-
-  static validateNoDuplicates<D extends DefaultDependencies>(
-    newFactories: MiddlewareFactory<D>[],
-    has: (factory: MiddlewareFactory<D>) => boolean,
-  ): void {
-    validateNoDuplicates<D>(newFactories, has);
-  }
-
-  static validateMiddlewareLimit(
-    currentCount: number,
-    newCount: number,
-    maxMiddleware?: number,
-  ): void {
-    validateMiddlewareLimit(currentCount, newCount, maxMiddleware);
-  }
-
-  // =========================================================================
-  // Dependency injection
-  // =========================================================================
-
-  setRouter(router: Router<Dependencies>): void {
-    this.#router = router;
-  }
-
-  setDependencies(deps: MiddlewareDependencies<Dependencies>): void {
-    this.#deps = deps;
-  }
-
-  setLimits(limits: Limits): void {
-    this.#limits = limits;
-  }
-
-  // =========================================================================
-  // Instance methods (trust input - already validated by facade)
-  // =========================================================================
-
-  /**
-   * Returns the current number of registered middleware.
-   */
-  count(): number {
-    return this.#factories.size;
-  }
-
-  /**
-   * Initializes middleware factories without committing to storage.
-   * Returns array of initialized middleware for validation by facade.
-   *
-   * @param factories - Already validated by facade
-   */
-  initialize(
-    ...factories: MiddlewareFactory<Dependencies>[]
-  ): InitializedMiddleware<Dependencies>[] {
-    const initialized: InitializedMiddleware<Dependencies>[] = [];
-
-    for (const factory of factories) {
-      // Middleware factories receive full router as part of their public API
-      const middleware = factory(this.#router, this.#deps.getDependency);
-
-      initialized.push({ factory, middleware });
-    }
-
-    return initialized;
-  }
-
-  /**
-   * Commits initialized middleware to storage.
-   * Returns unsubscribe function to remove all added middleware.
-   *
-   * @param initialized - Already validated by facade
-   */
-  commit(initialized: InitializedMiddleware<Dependencies>[]): Unsubscribe {
-    // Check count thresholds and log warnings if needed
-    this.#checkCountThresholds(initialized.length);
-
-    // Add to storage
-    for (const { factory, middleware } of initialized) {
-      this.#factories.add(factory);
-      this.#factoryToMiddleware.set(factory, middleware);
-    }
-
-    // Return unsubscribe function specific to THIS call's middleware
-    let unsubscribed = false;
-
-    return (): void => {
-      if (unsubscribed) {
-        return;
-      }
-
-      unsubscribed = true;
-
-      for (const { factory } of initialized) {
-        this.#factories.delete(factory);
-        this.#factoryToMiddleware.delete(factory);
-      }
-    };
-  }
-
-  /**
-   * Returns a copy of registered middleware factories.
-   * Preserves insertion order.
-   */
-  getFactories(): MiddlewareFactory<Dependencies>[] {
-    return [...this.#factories];
-  }
-
-  /**
-   * Checks if a middleware factory is registered.
-   * Used internally by validation to avoid array allocation.
-   */
-  has(factory: MiddlewareFactory<Dependencies>): boolean {
-    return this.#factories.has(factory);
-  }
-
-  /**
-   * Returns the actual middleware functions in execution order.
-   */
-  getFunctions(): Middleware[] {
-    return [...this.#factoryToMiddleware.values()];
-  }
-
-  /**
-   * Clears all registered middleware factories and their initialized functions.
-   * Unlike {@link disposeAll} in PluginsNamespace, no teardown is needed —
-   * middleware are pure functions with no event subscriptions or lifecycle.
-   * Named "clear" (not "dispose") because there is nothing active to dispose.
-   */
-  clearAll(): void {
-    this.#factories.clear();
-    this.#factoryToMiddleware.clear();
-  }
-
-  // =========================================================================
-  // Private methods
-  // =========================================================================
-
-  #checkCountThresholds(newCount: number): void {
-    const maxMiddleware = this.#limits.maxMiddleware;
-
-    if (maxMiddleware === 0) {
-      return;
-    }
-
-    const totalSize = newCount + this.#factories.size;
-
-    const { warn, error } = computeThresholds(maxMiddleware);
-
-    if (totalSize >= error) {
-      logger.error(
-        LOGGER_CONTEXT,
-        `${totalSize} middleware registered! ` +
-          `This is excessive and will impact performance. ` +
-          `Hard limit at ${maxMiddleware}.`,
-      );
-    } else if (totalSize >= warn) {
-      logger.warn(
-        LOGGER_CONTEXT,
-        `${totalSize} middleware registered. ` +
-          `Consider if all are necessary.`,
-      );
-    }
-  }
-}

package/src/namespaces/MiddlewareNamespace/constants.ts

@@ -1,3 +0,0 @@
-// packages/core/src/namespaces/MiddlewareNamespace/constants.ts
-
-export const LOGGER_CONTEXT = "router.useMiddleware";

package/src/namespaces/MiddlewareNamespace/index.ts

@@ -1,5 +0,0 @@
-// packages/core/src/namespaces/MiddlewareNamespace/index.ts
-
-export { MiddlewareNamespace } from "./MiddlewareNamespace";
-
-export type { MiddlewareDependencies } from "./types";

package/src/namespaces/MiddlewareNamespace/types.ts

@@ -1,28 +0,0 @@
-// packages/core/src/namespaces/MiddlewareNamespace/types.ts
-
-import type { MiddlewareFactory } from "../../types";
-import type { DefaultDependencies, Middleware } from "@real-router/types";
-
-/**
- * Dependencies injected into MiddlewareNamespace.
- *
- * Note: Middleware 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 MiddlewareDependencies<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
-> {
-  /** Get dependency value for middleware factory */
-  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K];
-}
-
-/**
- * Initialized middleware entry returned by initialize().
- */
-export interface InitializedMiddleware<
-  Dependencies extends DefaultDependencies,
-> {
-  factory: MiddlewareFactory<Dependencies>;
-  middleware: Middleware;
-}

package/src/namespaces/MiddlewareNamespace/validators.ts

@@ -1,95 +0,0 @@
-// packages/core/src/namespaces/MiddlewareNamespace/validators.ts
-
-/**
- * Static validation functions for MiddlewareNamespace.
- * Called by Router facade before instance methods.
- */
-
-import { getTypeDescription } from "type-guards";
-
-import { LOGGER_CONTEXT } from "./constants";
-import { DEFAULT_LIMITS } from "../../constants";
-
-import type { MiddlewareFactory } from "../../types";
-import type { DefaultDependencies, Middleware } from "@real-router/types";
-
-/**
- * Gets a displayable name for a factory function.
- */
-// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
-function getFactoryName(factory: Function): string {
-  return factory.name || "anonymous";
-}
-
-/**
- * Validates useMiddleware arguments - each must be a function.
- */
-export function validateUseMiddlewareArgs<D extends DefaultDependencies>(
-  middlewares: unknown[],
-): asserts middlewares is MiddlewareFactory<D>[] {
-  for (const [i, middleware] of middlewares.entries()) {
-    if (typeof middleware !== "function") {
-      throw new TypeError(
-        `[${LOGGER_CONTEXT}] Expected middleware factory function at index ${i}, ` +
-          `got ${getTypeDescription(middleware)}`,
-      );
-    }
-  }
-}
-
-/**
- * Validates that a middleware factory returned a valid middleware function.
- */
-export function validateMiddleware<D extends DefaultDependencies>(
-  middleware: unknown,
-  factory: MiddlewareFactory<D>,
-): asserts middleware is Middleware {
-  if (typeof middleware !== "function") {
-    throw new TypeError(
-      `[${LOGGER_CONTEXT}] Middleware factory must return a function, ` +
-        `got ${getTypeDescription(middleware)}. ` +
-        `Factory: ${getFactoryName(factory)}`,
-    );
-  }
-}
-
-/**
- * Validates that no duplicate factories are being registered.
- */
-export function validateNoDuplicates<D extends DefaultDependencies>(
-  newFactories: MiddlewareFactory<D>[],
-  has: (factory: MiddlewareFactory<D>) => boolean,
-): void {
-  for (const factory of newFactories) {
-    if (has(factory)) {
-      throw new Error(
-        `[${LOGGER_CONTEXT}] Middleware factory already registered. ` +
-          `To re-register, first unsubscribe the existing middleware. ` +
-          `Factory: ${getFactoryName(factory)}`,
-      );
-    }
-  }
-}
-
-/**
- * Validates that adding middleware won't exceed the hard limit.
- */
-export function validateMiddlewareLimit(
-  currentCount: number,
-  newCount: number,
-  maxMiddleware: number = DEFAULT_LIMITS.maxMiddleware,
-): void {
-  if (maxMiddleware === 0) {
-    return;
-  }
-
-  const totalSize = currentCount + newCount;
-
-  if (totalSize > maxMiddleware) {
-    throw new Error(
-      `[${LOGGER_CONTEXT}] Middleware limit exceeded (${maxMiddleware}). ` +
-        `Current: ${currentCount}, Attempting to add: ${newCount}. ` +
-        `This indicates an architectural problem. Consider consolidating middleware.`,
-    );
-  }
-}

package/src/namespaces/NavigationNamespace/transition/executeMiddleware.ts

@@ -1,56 +0,0 @@
-// packages/real-router/modules/transition/executeMiddleware.ts
-
-import { logger } from "@real-router/logger";
-import { isState } from "type-guards";
-
-import { rethrowAsRouterError } from "./makeError";
-import { mergeStates } from "./mergeStates";
-import { processLifecycleResult } from "./processLifecycleResult";
-import { errorCodes } from "../../../constants";
-import { RouterError } from "../../../RouterError";
-
-import type { State, ActivationFn } from "@real-router/types";
-
-// Helper: processing middleware
-export const executeMiddleware = async (
-  middlewareFunctions: ActivationFn[],
-  toState: State,
-  fromState: State | undefined,
-  isCancelled: () => boolean,
-): Promise<State> => {
-  let currentState = toState;
-
-  for (const middlewareFn of middlewareFunctions) {
-    if (isCancelled()) {
-      throw new RouterError(errorCodes.TRANSITION_CANCELLED);
-    }
-
-    try {
-      const result = middlewareFn(currentState, fromState);
-      const newState = await processLifecycleResult(result, currentState);
-
-      // Optimization: Early return for undefined newState (most common case ~90%+)
-      // This avoids isState() call and subsequent checks
-      if (newState !== currentState && isState(newState)) {
-        const hasChanged =
-          newState.name !== currentState.name ||
-          newState.params !== currentState.params ||
-          newState.path !== currentState.path;
-
-        if (hasChanged) {
-          logger.error(
-            "core:middleware",
-            "Warning: State mutated during middleware execution",
-            { from: currentState, to: newState },
-          );
-        }
-
-        currentState = mergeStates(newState, currentState);
-      }
-    } catch (error: unknown) {
-      rethrowAsRouterError(error, errorCodes.TRANSITION_ERR);
-    }
-  }
-
-  return currentState;
-};

package/src/namespaces/NavigationNamespace/transition/makeError.ts

@@ -1,37 +0,0 @@
-// packages/real-router/modules/transition/makeError.ts
-
-import { wrapSyncError } from "./wrapSyncError";
-import { RouterError } from "../../../RouterError";
-
-// Helper: Creating an error with code
-export const makeError = (
-  code: string,
-  err?: RouterError,
-): RouterError | undefined => {
-  if (!err) {
-    return undefined;
-  }
-
-  err.setCode(code);
-
-  return err;
-};
-
-/**
- * Re-throws a caught error as a RouterError with the given error code.
- * If the error is already a RouterError, sets the code directly.
- * Otherwise wraps it with wrapSyncError metadata.
- */
-export function rethrowAsRouterError(
-  error: unknown,
-  errorCode: string,
-  segment?: string,
-): never {
-  if (error instanceof RouterError) {
-    error.setCode(errorCode);
-
-    throw error;
-  }
-
-  throw new RouterError(errorCode, wrapSyncError(error, segment));
-}

package/src/namespaces/NavigationNamespace/transition/mergeStates.ts

@@ -1,54 +0,0 @@
-// packages/real-router/modules/transition/mergeStates.ts
-
-import type { Params, State, StateMeta } from "@real-router/types";
-
-/**
- * Merges two states with toState taking priority over fromState.
- *
- * Priority order for state fields: toState > fromState
- * Priority order for meta fields: toState.meta > fromState.meta > defaults
- *
- * Special case: meta.params are merged (not replaced):
- * { ...toState.meta.params, ...fromState.meta.params }
- *
- * @param toState - Target state (higher priority)
- * @param fromState - Source state (lower priority)
- * @returns New merged state object
- */
-export const mergeStates = (toState: State, fromState: State): State => {
-  const toMeta = toState.meta;
-  const fromMeta = fromState.meta;
-
-  // Optimization #1: Conditional merge for params
-  // Use spread only when both are defined
-  const toParams = toMeta?.params;
-  const fromParams = fromMeta?.params;
-
-  // Both have params - need to merge; otherwise use whichever is defined
-  const metaParams: Params =
-    toParams && fromParams
-      ? { ...toParams, ...fromParams }
-      : (toParams ?? fromParams ?? {});
-
-  // Optimization #2: Build meta with defaults, then apply fromMeta, then toMeta
-  // Note: StateMeta can have custom fields added by guards/middleware, so we preserve them
-  const resultMeta: StateMeta = {
-    // Defaults first
-    id: 1,
-    options: {},
-    // fromMeta fields (lower priority, may include custom fields)
-    ...fromMeta,
-    // toMeta fields (higher priority, may include custom fields)
-    ...toMeta,
-    // Explicitly set params to our merged version (override spread)
-    params: metaParams,
-  };
-
-  // Optimization #4: Copy all toState fields (including custom ones)
-  // then explicitly set meta to our merged version
-  // Note: State can have custom fields added by middleware, so we must preserve them
-  return {
-    ...toState,
-    meta: resultMeta,
-  };
-};

package/src/namespaces/NavigationNamespace/transition/processLifecycleResult.ts

@@ -1,69 +0,0 @@
-// packages/real-router/modules/transition/processLifecycleResult.ts
-
-import { isState } from "type-guards";
-
-import { errorCodes } from "../../../constants";
-import { RouterError } from "../../../RouterError";
-
-import type { SyncErrorMetadata } from "./wrapSyncError";
-import type { State, ActivationFn } from "@real-router/types";
-
-/**
- * Builds error metadata from a caught promise rejection.
- * Extracts message, stack, and cause from Error instances.
- */
-function buildErrorMetadata(
-  error: unknown,
-  errorData: SyncErrorMetadata,
-): SyncErrorMetadata {
-  if (error instanceof Error) {
-    return {
-      ...errorData,
-      message: error.message,
-      stack: error.stack,
-      // Error.cause requires ES2022+ - safely access it if present
-      ...("cause" in error &&
-        error.cause !== undefined && { cause: error.cause }),
-    };
-  }
-
-  if (error && typeof error === "object") {
-    return { ...errorData, ...error };
-  }
-
-  return errorData;
-}
-
-// Helper: Lifecycle results Processing Function
-export const processLifecycleResult = async (
-  result: ReturnType<ActivationFn>,
-  currentState: State,
-): Promise<State> => {
-  if (result === undefined) {
-    return currentState;
-  }
-
-  if (typeof result === "boolean") {
-    if (result) {
-      return currentState;
-    } else {
-      throw new RouterError(errorCodes.TRANSITION_ERR, {});
-    }
-  }
-
-  if (isState(result)) {
-    return result;
-  }
-
-  // Optimization: single try/catch instead of .then(onFulfill, onReject)
-  try {
-    const resVal = await (result as Promise<State | boolean | undefined>);
-
-    return await processLifecycleResult(resVal, currentState);
-  } catch (error: unknown) {
-    throw new RouterError(
-      errorCodes.TRANSITION_ERR,
-      buildErrorMetadata(error, {}),
-    );
-  }
-};