@real-router/core 0.22.0 → 0.23.0

package/src/RouterError.ts

@@ -0,0 +1,324 @@
+// packages/real-router/modules/RouterError.ts
+
+import { errorCodes } from "./constants";
+import { deepFreezeState } from "./helpers";
+
+import type { State } from "@real-router/types";
+
+// Pre-compute Set of error code values for O(1) lookup in setCode()
+// This avoids creating array and doing linear search on every setCode() call
+const errorCodeValues = new Set(Object.values(errorCodes));
+
+// Reserved built-in properties - throw error if user tries to set these
+const reservedProperties = new Set(["code", "segment", "path", "redirect"]);
+
+// Reserved method names - silently ignore attempts to overwrite these
+const reservedMethods = new Set([
+  "setCode",
+  "setErrorInstance",
+  "setAdditionalFields",
+  "hasField",
+  "getField",
+  "toJSON",
+]);
+
+export class RouterError extends Error {
+  [key: string]: unknown;
+
+  // Using public properties to ensure structural compatibility
+  // with RouterError interface in core-types
+  readonly segment: string | undefined;
+  readonly path: string | undefined;
+  readonly redirect: State | undefined;
+
+  // Note: code appears to be writable but setCode() should be used
+  // to properly update both code and message together
+  code: string;
+
+  /**
+   * Creates a new RouterError instance.
+   *
+   * The options object accepts built-in fields (message, segment, path, redirect)
+   * and any additional custom fields, which will all be attached to the error instance.
+   *
+   * @param code - The error code (e.g., "ROUTE_NOT_FOUND", "CANNOT_ACTIVATE")
+   * @param options - Optional configuration object
+   * @param options.message - Custom error message (defaults to code if not provided)
+   * @param options.segment - The route segment where the error occurred
+   * @param options.path - The full path where the error occurred
+   * @param options.redirect - Optional redirect state for navigation errors
+   *
+   * @example
+   * ```typescript
+   * // Basic error
+   * const err1 = new RouterError("ROUTE_NOT_FOUND");
+   *
+   * // Error with custom message
+   * const err2 = new RouterError("ERR", { message: "Something went wrong" });
+   *
+   * // Error with context and custom fields
+   * const err3 = new RouterError("CANNOT_ACTIVATE", {
+   *   message: "Insufficient permissions",
+   *   segment: "admin",
+   *   path: "/admin/users",
+   *   userId: "123"  // custom field
+   * });
+   *
+   * // Error with redirect
+   * const err4 = new RouterError("TRANSITION_ERR", {
+   *   redirect: { name: "home", path: "/", params: {} }
+   * });
+   * ```
+   */
+  constructor(
+    code: string,
+    {
+      message,
+      segment,
+      path,
+      redirect,
+      ...rest
+    }: {
+      [key: string]: unknown;
+      message?: string | undefined;
+      segment?: string | undefined;
+      path?: string | undefined;
+      redirect?: State | undefined;
+    } = {},
+  ) {
+    super(message ?? code);
+
+    this.code = code;
+    this.segment = segment;
+    this.path = path;
+    // Deep freeze redirect to prevent mutations (creates a frozen clone)
+    this.redirect = redirect ? deepFreezeState(redirect) : undefined;
+
+    // Assign custom fields, checking reserved properties and filtering out reserved method names
+    // Issue #39: Throw for reserved properties to match setAdditionalFields behavior
+    for (const [key, value] of Object.entries(rest)) {
+      if (reservedProperties.has(key)) {
+        throw new TypeError(
+          `[RouterError] Cannot set reserved property "${key}"`,
+        );
+      }
+
+      if (!reservedMethods.has(key)) {
+        this[key] = value;
+      }
+    }
+  }
+
+  /**
+   * Updates the error code and conditionally updates the message.
+   *
+   * If the current message is one of the standard error code values
+   * (e.g., "ROUTE_NOT_FOUND", "SAME_STATES"), it will be replaced with the new code.
+   * This allows keeping error messages in sync with codes when using standard error codes.
+   *
+   * If the message is custom (not a standard error code), it will be preserved.
+   *
+   * @param newCode - The new error code to set
+   *
+   * @example
+   * // Message follows code (standard error code as message)
+   * const err = new RouterError("ROUTE_NOT_FOUND", { message: "ROUTE_NOT_FOUND" });
+   * err.setCode("CUSTOM_ERROR"); // message becomes "CUSTOM_ERROR"
+   *
+   * @example
+   * // Custom message is preserved
+   * const err = new RouterError("ERR", { message: "Custom error message" });
+   * err.setCode("NEW_CODE"); // message stays "Custom error message"
+   */
+  setCode(newCode: string): void {
+    this.code = newCode;
+
+    // Only update message if it's a standard error code value (not a custom message)
+    if (errorCodeValues.has(this.message)) {
+      this.message = newCode;
+    }
+  }
+
+  /**
+   * Copies properties from another Error instance to this RouterError.
+   *
+   * This method updates the message, cause, and stack trace from the provided error.
+   * Useful for wrapping native errors while preserving error context.
+   *
+   * @param err - The Error instance to copy properties from
+   * @throws {TypeError} If err is null or undefined
+   *
+   * @example
+   * ```typescript
+   * const routerErr = new RouterError("TRANSITION_ERR");
+   * try {
+   *   // some operation that might fail
+   * } catch (nativeErr) {
+   *   routerErr.setErrorInstance(nativeErr);
+   *   throw routerErr;
+   * }
+   * ```
+   */
+  setErrorInstance(err: Error): void {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!err) {
+      throw new TypeError(
+        "[RouterError.setErrorInstance] err parameter is required and must be an Error instance",
+      );
+    }
+
+    this.message = err.message;
+    this.cause = err.cause;
+    this.stack = err.stack ?? "";
+  }
+
+  /**
+   * Adds custom fields to the error object.
+   *
+   * This method allows attaching arbitrary data to the error for debugging or logging purposes.
+   * All fields become accessible as properties on the error instance and are included in JSON serialization.
+   *
+   * Reserved method names (setCode, setErrorInstance, setAdditionalFields, hasField, getField, toJSON)
+   * are automatically filtered out to prevent accidental overwriting of class methods.
+   *
+   * @param fields - Object containing custom fields to add to the error
+   *
+   * @example
+   * ```typescript
+   * const err = new RouterError("CANNOT_ACTIVATE");
+   * err.setAdditionalFields({
+   *   userId: "123",
+   *   attemptedRoute: "/admin",
+   *   reason: "insufficient permissions"
+   * });
+   *
+   * console.log(err.userId); // "123"
+   * console.log(JSON.stringify(err)); // includes all custom fields
+   * ```
+   */
+  setAdditionalFields(fields: Record<string, unknown>): void {
+    // Assign fields, throwing for reserved properties, silently ignoring methods
+    for (const [key, value] of Object.entries(fields)) {
+      if (reservedProperties.has(key)) {
+        throw new TypeError(
+          `[RouterError.setAdditionalFields] Cannot set reserved property "${key}"`,
+        );
+      }
+
+      if (!reservedMethods.has(key)) {
+        this[key] = value;
+      }
+    }
+  }
+
+  /**
+   * Checks if a custom field exists on the error object.
+   *
+   * This method checks for both custom fields added via setAdditionalFields()
+   * and built-in fields (code, message, segment, etc.).
+   *
+   * @param key - The field name to check
+   * @returns `true` if the field exists, `false` otherwise
+   *
+   * @example
+   * ```typescript
+   * const err = new RouterError("ERR", { segment: "users" });
+   * err.setAdditionalFields({ userId: "123" });
+   *
+   * err.hasField("userId");  // true
+   * err.hasField("segment"); // true
+   * err.hasField("unknown"); // false
+   * ```
+   */
+  hasField(key: string): boolean {
+    return key in this;
+  }
+
+  /**
+   * Retrieves a custom field value from the error object.
+   *
+   * This method can access both custom fields and built-in fields.
+   * Returns `undefined` if the field doesn't exist.
+   *
+   * @param key - The field name to retrieve
+   * @returns The field value, or `undefined` if it doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const err = new RouterError("ERR");
+   * err.setAdditionalFields({ userId: "123", role: "admin" });
+   *
+   * err.getField("userId"); // "123"
+   * err.getField("role");   // "admin"
+   * err.getField("code");   // "ERR" (built-in field)
+   * err.getField("unknown"); // undefined
+   * ```
+   */
+  getField(key: string): unknown {
+    return this[key];
+  }
+
+  /**
+   * Serializes the error to a JSON-compatible object.
+   *
+   * This method is automatically called by JSON.stringify() and includes:
+   * - Built-in fields: code, message, segment (if set), path (if set), redirect (if set)
+   * - All custom fields added via setAdditionalFields() or constructor
+   * - Excludes: stack trace (for security/cleanliness)
+   *
+   * @returns A plain object representation of the error, suitable for JSON serialization
+   *
+   * @example
+   * ```typescript
+   * const err = new RouterError("ROUTE_NOT_FOUND", {
+   *   message: "Route not found",
+   *   path: "/admin/users/123"
+   * });
+   * err.setAdditionalFields({ userId: "123" });
+   *
+   * JSON.stringify(err);
+   * // {
+   * //   "code": "ROUTE_NOT_FOUND",
+   * //   "message": "Route not found",
+   * //   "path": "/admin/users/123",
+   * //   "userId": "123"
+   * // }
+   * ```
+   */
+  toJSON(): Record<string, unknown> {
+    const result: Record<string, unknown> = {
+      code: this.code,
+      message: this.message,
+    };
+
+    if (this.segment !== undefined) {
+      result.segment = this.segment;
+    }
+    if (this.path !== undefined) {
+      result.path = this.path;
+    }
+    if (this.redirect !== undefined) {
+      result.redirect = this.redirect;
+    }
+
+    // add all public fields
+    // Using Set.has() for O(1) lookup instead of Array.includes() O(n)
+    // Overall complexity: O(n) instead of O(n*m)
+    const excludeKeys = new Set([
+      "code",
+      "message",
+      "segment",
+      "path",
+      "redirect",
+      "stack",
+    ]);
+
+    for (const key in this) {
+      if (Object.hasOwn(this, key) && !excludeKeys.has(key)) {
+        result[key] = this[key];
+      }
+    }
+
+    return result;
+  }
+}

package/src/constants.ts

@@ -0,0 +1,112 @@
+// packages/real-router/modules/constants.ts
+
+import type {
+  EventName,
+  EventToNameMap,
+  EventToPluginMap,
+  ErrorCodeToValueMap,
+  ErrorCodeKeys,
+  ErrorCodeValues,
+} from "@real-router/types";
+
+export type ConstantsKeys = "UNKNOWN_ROUTE";
+
+export type Constants = Record<ConstantsKeys, string>;
+
+// =============================================================================
+// Error Codes (migrated from router-error)
+// =============================================================================
+
+export type ErrorCodes = Record<ErrorCodeKeys, ErrorCodeValues>;
+
+/**
+ * Error codes for router operations.
+ * Used to identify specific failure scenarios in navigation and lifecycle.
+ * Frozen to prevent accidental modifications.
+ */
+export const errorCodes: ErrorCodeToValueMap = Object.freeze({
+  ROUTER_NOT_STARTED: "NOT_STARTED", // navigate() called before start()
+  NO_START_PATH_OR_STATE: "NO_START_PATH_OR_STATE", // start() without initial route
+  ROUTER_ALREADY_STARTED: "ALREADY_STARTED", // start() called twice
+  ROUTE_NOT_FOUND: "ROUTE_NOT_FOUND", // Navigation to non-existent route
+  SAME_STATES: "SAME_STATES", // Navigate to current route without reload
+  CANNOT_DEACTIVATE: "CANNOT_DEACTIVATE", // canDeactivate guard blocked navigation
+  CANNOT_ACTIVATE: "CANNOT_ACTIVATE", // canActivate guard blocked navigation
+  TRANSITION_ERR: "TRANSITION_ERR", // Generic transition failure
+  TRANSITION_CANCELLED: "CANCELLED", // Navigation cancelled by user or new navigation
+  ROUTER_DISPOSED: "DISPOSED", // Router has been disposed
+});
+
+/**
+ * General router constants.
+ * Special route names and identifiers.
+ */
+export const constants: Constants = {
+  UNKNOWN_ROUTE: "@@router/UNKNOWN_ROUTE", // Special route for 404/not found states
+};
+
+/**
+ * Plugin method names.
+ * Maps to methods that plugins can implement to hook into router lifecycle.
+ */
+export const plugins: EventToPluginMap = {
+  ROUTER_START: "onStart", // Plugin method called when router starts
+  ROUTER_STOP: "onStop", // Plugin method called when router stops
+  TRANSITION_START: "onTransitionStart", // Plugin method called when navigation begins
+  TRANSITION_CANCEL: "onTransitionCancel", // Plugin method called when navigation cancelled
+  TRANSITION_SUCCESS: "onTransitionSuccess", // Plugin method called when navigation succeeds
+  TRANSITION_ERROR: "onTransitionError", // Plugin method called when navigation fails
+};
+
+/**
+ * Event names for router event system.
+ * Used with addEventListener/removeEventListener for reactive subscriptions.
+ */
+export const events: EventToNameMap = {
+  ROUTER_START: "$start", // Emitted when router.start() succeeds
+  ROUTER_STOP: "$stop", // Emitted when router.stop() is called
+  TRANSITION_START: "$$start", // Emitted when navigation begins
+  TRANSITION_CANCEL: "$$cancel", // Emitted when navigation is cancelled
+  TRANSITION_SUCCESS: "$$success", // Emitted when navigation completes successfully
+  TRANSITION_ERROR: "$$error", // Emitted when navigation fails
+};
+
+/**
+ * Valid event names for validation.
+ */
+export const validEventNames = new Set<EventName>([
+  events.ROUTER_START,
+  events.TRANSITION_START,
+  events.TRANSITION_SUCCESS,
+  events.TRANSITION_ERROR,
+  events.TRANSITION_CANCEL,
+  events.ROUTER_STOP,
+]);
+
+/**
+ * Default limits configuration for the router.
+ * These values match the hardcoded constants from the current codebase.
+ */
+export const DEFAULT_LIMITS = {
+  maxDependencies: 100,
+  maxPlugins: 50,
+  maxMiddleware: 50,
+  maxListeners: 10_000,
+  warnListeners: 1000,
+  maxEventDepth: 5,
+  maxLifecycleHandlers: 200,
+} as const;
+
+/**
+ * Bounds for each limit - defines min and max allowed values.
+ * Used for runtime validation in setLimit/withLimits.
+ */
+export const LIMIT_BOUNDS = {
+  maxDependencies: { min: 0, max: 10_000 },
+  maxPlugins: { min: 0, max: 1000 },
+  maxMiddleware: { min: 0, max: 1000 },
+  maxListeners: { min: 0, max: 100_000 },
+  warnListeners: { min: 0, max: 100_000 },
+  maxEventDepth: { min: 0, max: 100 },
+  maxLifecycleHandlers: { min: 0, max: 10_000 },
+} as const;

package/src/createRouter.ts

@@ -0,0 +1,32 @@
+// packages/core/src/createRouter.ts
+
+import { Router } from "./Router";
+
+import type { Route } from "./types";
+import type { DefaultDependencies, Options } from "@real-router/types";
+
+/**
+ * Creates a new router instance.
+ *
+ * @param routes - Array of route definitions
+ * @param options - Router configuration options
+ * @param dependencies - Dependencies to inject into the router
+ * @returns A new Router instance
+ *
+ * @example
+ * const router = createRouter([
+ *   { name: 'home', path: '/' },
+ *   { name: 'users', path: '/users' },
+ * ]);
+ *
+ * router.start('/');
+ */
+export const createRouter = <
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  routes: Route<Dependencies>[] = [],
+  options: Partial<Options> = {},
+  dependencies: Dependencies = {} as Dependencies,
+): Router<Dependencies> => {
+  return new Router<Dependencies>(routes, options, dependencies);
+};

package/src/fsm/index.ts

@@ -0,0 +1,5 @@
+// packages/core/src/fsm/index.ts
+
+export { createRouterFSM, routerStates, routerEvents } from "./routerFSM";
+
+export type { RouterEvent, RouterPayloads, RouterState } from "./routerFSM";

package/src/fsm/routerFSM.ts

@@ -0,0 +1,129 @@
+// packages/core/src/fsm/routerFSM.ts
+
+import { FSM } from "@real-router/fsm";
+
+import type { FSMConfig } from "@real-router/fsm";
+import type { NavigationOptions, State } from "@real-router/types";
+
+/**
+ * Router FSM states.
+ *
+ * - IDLE: Router not started or stopped
+ * - STARTING: Router is initializing
+ * - READY: Router is ready for navigation
+ * - TRANSITIONING: Navigation in progress
+ * - DISPOSED: Router has been disposed (R2+)
+ */
+export const routerStates = {
+  IDLE: "IDLE",
+  STARTING: "STARTING",
+  READY: "READY",
+  TRANSITIONING: "TRANSITIONING",
+  DISPOSED: "DISPOSED",
+} as const;
+
+export type RouterState = (typeof routerStates)[keyof typeof routerStates];
+
+/**
+ * Router FSM events.
+ *
+ * - START: Begin router initialization
+ * - STARTED: Router initialization complete
+ * - NAVIGATE: Begin navigation
+ * - COMPLETE: Navigation completed successfully
+ * - FAIL: Navigation or initialization failed
+ * - CANCEL: Navigation cancelled
+ * - STOP: Stop router
+ * - DISPOSE: Dispose router (R2+)
+ */
+export const routerEvents = {
+  START: "START",
+  STARTED: "STARTED",
+  NAVIGATE: "NAVIGATE",
+  COMPLETE: "COMPLETE",
+  FAIL: "FAIL",
+  CANCEL: "CANCEL",
+  STOP: "STOP",
+  DISPOSE: "DISPOSE",
+} as const;
+
+export type RouterEvent = (typeof routerEvents)[keyof typeof routerEvents];
+
+/**
+ * Typed payloads for router FSM events.
+ *
+ * Events without entries have no payload.
+ */
+export interface RouterPayloads {
+  NAVIGATE: {
+    toState: State;
+    fromState: State | undefined;
+  };
+  COMPLETE: {
+    state: State;
+    fromState: State | undefined;
+    opts: NavigationOptions;
+  };
+  FAIL: {
+    toState?: State | undefined;
+    fromState?: State | undefined;
+    error?: unknown;
+  };
+  CANCEL: {
+    toState: State;
+    fromState: State | undefined;
+  };
+}
+
+/**
+ * Router FSM configuration.
+ *
+ * Transitions:
+ * - IDLE → STARTING (START), DISPOSED (DISPOSE)
+ * - STARTING → READY (STARTED), IDLE (FAIL)
+ * - READY → TRANSITIONING (NAVIGATE), READY (FAIL, self-loop for early validation errors), IDLE (STOP)
+ * - TRANSITIONING → TRANSITIONING (NAVIGATE, self-loop for canSend), READY (COMPLETE, CANCEL, FAIL)
+ * - DISPOSED → (no transitions)
+ */
+const routerFSMConfig: FSMConfig<RouterState, RouterEvent, null> = {
+  initial: routerStates.IDLE,
+  context: null,
+  transitions: {
+    [routerStates.IDLE]: {
+      [routerEvents.START]: routerStates.STARTING,
+      [routerEvents.DISPOSE]: routerStates.DISPOSED,
+    },
+    [routerStates.STARTING]: {
+      [routerEvents.STARTED]: routerStates.READY,
+      [routerEvents.FAIL]: routerStates.IDLE,
+    },
+    [routerStates.READY]: {
+      [routerEvents.NAVIGATE]: routerStates.TRANSITIONING,
+      [routerEvents.FAIL]: routerStates.READY,
+      [routerEvents.STOP]: routerStates.IDLE,
+    },
+    [routerStates.TRANSITIONING]: {
+      [routerEvents.NAVIGATE]: routerStates.TRANSITIONING,
+      [routerEvents.COMPLETE]: routerStates.READY,
+      [routerEvents.CANCEL]: routerStates.READY,
+      [routerEvents.FAIL]: routerStates.READY,
+    },
+    [routerStates.DISPOSED]: {},
+  },
+};
+
+/**
+ * Factory function to create a router FSM instance.
+ *
+ * @returns FSM instance with initial state "IDLE"
+ */
+export function createRouterFSM(): FSM<
+  RouterState,
+  RouterEvent,
+  null,
+  RouterPayloads
+> {
+  return new FSM<RouterState, RouterEvent, null, RouterPayloads>(
+    routerFSMConfig,
+  );
+}

package/src/getNavigator.ts

@@ -0,0 +1,15 @@
+import type { Router } from "./Router";
+import type { Navigator, DefaultDependencies } from "@real-router/types";
+
+export const getNavigator = <
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  router: Router<Dependencies>,
+): Navigator =>
+  Object.freeze({
+    navigate: router.navigate,
+    getState: router.getState,
+    isActiveRoute: router.isActiveRoute,
+    canNavigateTo: router.canNavigateTo,
+    subscribe: router.subscribe,
+  });