@real-router/core 0.22.0 → 0.23.0

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

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

@@ -0,0 +1,81 @@
+// packages/real-router/modules/transition/processLifecycleResult.ts
+
+import { isPromise, 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,
+  segment?: string,
+): Promise<State> => {
+  const errorData = segment ? { segment } : {};
+
+  if (result === undefined) {
+    return currentState;
+  }
+
+  if (typeof result === "boolean") {
+    if (result) {
+      return currentState;
+    } else {
+      throw new RouterError(errorCodes.TRANSITION_ERR, errorData);
+    }
+  }
+
+  if (isState(result)) {
+    return result;
+  }
+
+  if (isPromise<State | boolean | undefined>(result)) {
+    // Optimization: single try/catch instead of .then(onFulfill, onReject)
+    try {
+      const resVal = await result;
+
+      return await processLifecycleResult(resVal, currentState, segment);
+    } catch (error_: unknown) {
+      throw new RouterError(
+        errorCodes.TRANSITION_ERR,
+        buildErrorMetadata(error_, errorData),
+      );
+    }
+  }
+
+  // This should never be reached - all valid ActivationFn return types are handled above
+  // If we get here, it means the activation function returned an unexpected type
+  throw new RouterError(errorCodes.TRANSITION_ERR, {
+    ...errorData,
+    message: `Invalid lifecycle result type: ${typeof result}`,
+  });
+};

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

@@ -0,0 +1,82 @@
+// packages/real-router/modules/transition/wrapSyncError.ts
+
+/**
+ * Error metadata structure for transition errors.
+ * Contains information extracted from caught exceptions.
+ */
+export interface SyncErrorMetadata {
+  [key: string]: unknown;
+  message?: string;
+  stack?: string | undefined;
+  cause?: unknown;
+  segment?: string;
+}
+
+// Reserved properties that conflict with RouterError constructor
+// Issue #39: Filter these when wrapping sync errors to avoid TypeError
+const reservedRouterErrorProps = new Set([
+  "code",
+  "segment",
+  "path",
+  "redirect",
+]);
+
+/**
+ * Wraps a synchronously thrown value into structured error metadata.
+ *
+ * This helper extracts useful debugging information from various thrown values:
+ * - Error instances: extracts message, stack, and cause (ES2022+)
+ * - Plain objects: spreads properties into metadata
+ * - Primitives (string, number, etc.): returns minimal metadata
+ *
+ * @param thrown - The value caught in a try-catch block
+ * @param segment - Optional route segment name (for lifecycle hooks)
+ * @returns Structured error metadata for RouterError
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   hookFn();
+ * } catch (error) {
+ *   const metadata = wrapSyncError(error, "users.profile");
+ *   throw new RouterError(errorCodes.TRANSITION_ERR, metadata);
+ * }
+ * ```
+ */
+export function wrapSyncError(
+  thrown: unknown,
+  segment?: string,
+): SyncErrorMetadata {
+  // Base metadata - always include segment if provided
+  const base: SyncErrorMetadata = segment ? { segment } : {};
+
+  // Handle Error instances - extract all useful properties
+  if (thrown instanceof Error) {
+    return {
+      ...base,
+      message: thrown.message,
+      stack: thrown.stack,
+      // Error.cause requires ES2022+ - safely access if present
+      ...("cause" in thrown &&
+        thrown.cause !== undefined && { cause: thrown.cause }),
+    };
+  }
+
+  // Handle plain objects - spread properties into metadata, filtering reserved props
+  if (thrown && typeof thrown === "object") {
+    const filtered: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(thrown)) {
+      // Issue #39: Skip reserved properties to avoid RouterError constructor TypeError
+      if (!reservedRouterErrorProps.has(key)) {
+        filtered[key] = value;
+      }
+    }
+
+    return { ...base, ...filtered };
+  }
+
+  // Primitives (string, number, boolean, null, undefined, symbol, bigint)
+  // Return base metadata only - the primitive value isn't useful as metadata
+  return base;
+}

package/src/namespaces/NavigationNamespace/types.ts

@@ -0,0 +1,129 @@
+// packages/core/src/namespaces/NavigationNamespace/types.ts
+
+import type { BuildStateResultWithSegments } from "../../types";
+import type {
+  ActivationFn,
+  Middleware,
+  NavigationOptions,
+  Options,
+  Params,
+  State,
+  StateMetaInput,
+  TransitionPhase,
+} from "@real-router/types";
+
+/**
+ * Dependencies injected into NavigationNamespace.
+ *
+ * These are function references from other namespaces/facade,
+ * avoiding the need to pass the entire Router object.
+ */
+export interface NavigationDependencies {
+  /** Get router options */
+  getOptions: () => Options;
+
+  /** Check if route exists */
+  hasRoute: (name: string) => boolean;
+
+  /** Get current state */
+  getState: () => State | undefined;
+
+  /** Set router state */
+  setState: (state?: State) => void;
+
+  /** Build state with segments from route name and params */
+  buildStateWithSegments: <P extends Params = Params>(
+    routeName: string,
+    routeParams: P,
+  ) => BuildStateResultWithSegments<P> | undefined;
+
+  /** Make state object with path and meta */
+  makeState: <P extends Params = Params, MP extends Params = Params>(
+    name: string,
+    params?: P,
+    path?: string,
+    meta?: StateMetaInput<MP>,
+  ) => State<P, MP>;
+
+  /** Build path from route name and params */
+  buildPath: (route: string, params?: Params) => string;
+
+  /** Check if states are equal */
+  areStatesEqual: (
+    state1: State | undefined,
+    state2: State | undefined,
+    ignoreQueryParams?: boolean,
+  ) => boolean;
+
+  /** Get a dependency by name (untyped — used only for resolveOption) */
+  getDependency: (name: string) => unknown;
+
+  /** Start transition and send NAVIGATE event to routerFSM */
+  startTransition: (toState: State, fromState: State | undefined) => void;
+
+  /** Cancel navigation if transition is running */
+  cancelNavigation: () => void;
+
+  /** Send COMPLETE event to routerFSM */
+  sendTransitionDone: (
+    state: State,
+    fromState: State | undefined,
+    opts: NavigationOptions,
+  ) => void;
+
+  /** Send FAIL event to routerFSM (transition blocked) */
+  sendTransitionBlocked: (
+    toState: State,
+    fromState: State | undefined,
+    error: unknown,
+  ) => void;
+
+  /** Send FAIL event to routerFSM (transition error) */
+  sendTransitionError: (
+    toState: State,
+    fromState: State | undefined,
+    error: unknown,
+  ) => void;
+
+  /** Emit TRANSITION_ERROR event to listeners */
+  emitTransitionError: (
+    toState: State | undefined,
+    fromState: State | undefined,
+    error: unknown,
+  ) => void;
+}
+
+export interface TransitionOutput {
+  state: State;
+  meta: {
+    phase: TransitionPhase;
+    segments: {
+      deactivated: string[];
+      activated: string[];
+      intersection: string;
+    };
+  };
+}
+
+/**
+ * Dependencies required for the transition function.
+ */
+export interface TransitionDependencies {
+  /** Get lifecycle functions (canDeactivate, canActivate maps) */
+  getLifecycleFunctions: () => [
+    Map<string, ActivationFn>,
+    Map<string, ActivationFn>,
+  ];
+
+  /** Get middleware functions array */
+  getMiddlewareFunctions: () => Middleware[];
+
+  /** Check if router is active (for cancellation check on stop()) */
+  isActive: () => boolean;
+
+  /** Check if a transition is currently in progress */
+  isTransitioning: () => boolean;
+
+  /** Clear canDeactivate guard for a route */
+  clearCanDeactivate: (name: string) => void;
+}

package/src/namespaces/NavigationNamespace/validators.ts

@@ -0,0 +1,87 @@
+// packages/core/src/namespaces/NavigationNamespace/validators.ts
+
+/**
+ * Static validation functions for NavigationNamespace.
+ * Called by Router facade before instance methods.
+ */
+
+import { getTypeDescription, isNavigationOptions } from "type-guards";
+
+import type { NavigationOptions, State } from "@real-router/types";
+
+/**
+ * Validates navigate route name argument.
+ */
+export function validateNavigateArgs(name: unknown): asserts name is string {
+  if (typeof name !== "string") {
+    throw new TypeError(
+      `[router.navigate] Invalid route name: expected string, got ${getTypeDescription(name)}`,
+    );
+  }
+}
+
+/**
+ * Validates navigateToState arguments.
+ */
+export function validateNavigateToStateArgs(
+  toState: unknown,
+  fromState: unknown,
+  opts: unknown,
+): void {
+  // toState must be a valid state object
+  if (
+    !toState ||
+    typeof toState !== "object" ||
+    typeof (toState as State).name !== "string" ||
+    typeof (toState as State).path !== "string"
+  ) {
+    throw new TypeError(
+      `[router.navigateToState] Invalid toState: expected State object with name and path`,
+    );
+  }
+
+  // fromState can be undefined or a valid state
+  if (
+    fromState !== undefined &&
+    (!fromState ||
+      typeof fromState !== "object" ||
+      typeof (fromState as State).name !== "string")
+  ) {
+    throw new TypeError(
+      `[router.navigateToState] Invalid fromState: expected State object or undefined`,
+    );
+  }
+
+  // opts must be an object
+  if (typeof opts !== "object" || opts === null) {
+    throw new TypeError(
+      `[router.navigateToState] Invalid opts: expected NavigationOptions object, got ${getTypeDescription(opts)}`,
+    );
+  }
+}
+
+/**
+ * Validates navigateToDefault arguments.
+ */
+export function validateNavigateToDefaultArgs(opts: unknown): void {
+  // If opts is provided, it must be an object (NavigationOptions)
+  if (opts !== undefined && (typeof opts !== "object" || opts === null)) {
+    throw new TypeError(
+      `[router.navigateToDefault] Invalid options: ${getTypeDescription(opts)}. Expected NavigationOptions object.`,
+    );
+  }
+}
+
+/**
+ * Validates that opts is a valid NavigationOptions object.
+ */
+export function validateNavigationOptions(
+  opts: unknown,
+  methodName: string,
+): asserts opts is NavigationOptions {
+  if (!isNavigationOptions(opts)) {
+    throw new TypeError(
+      `[router.${methodName}] Invalid options: ${getTypeDescription(opts)}. Expected NavigationOptions object.`,
+    );
+  }
+}

package/src/namespaces/OptionsNamespace/OptionsNamespace.ts

@@ -0,0 +1,50 @@
+// packages/core/src/namespaces/OptionsNamespace/OptionsNamespace.ts
+
+import { defaultOptions } from "./constants";
+import { deepFreeze } from "./helpers";
+import { validateOptions } from "./validators";
+
+import type { Options } from "@real-router/types";
+
+/**
+ * Independent namespace for managing router options.
+ *
+ * Options are immutable after construction.
+ * Static methods handle validation (called by facade).
+ * Instance methods provide read-only access.
+ */
+export class OptionsNamespace {
+  readonly #options: Readonly<Options>;
+
+  constructor(initialOptions: Partial<Options> = {}) {
+    // Note: validation should be done by facade before calling constructor
+    this.#options = deepFreeze({
+      ...defaultOptions,
+      ...initialOptions,
+    });
+  }
+
+  // =========================================================================
+  // Static validation methods (called by facade before instance methods)
+  // Proxy to functions in validators.ts for separation of concerns
+  // =========================================================================
+
+  static validateOptions(
+    options: unknown,
+    methodName: string,
+  ): asserts options is Partial<Options> {
+    validateOptions(options, methodName);
+  }
+
+  // =========================================================================
+  // Instance methods (read-only access)
+  // =========================================================================
+
+  /**
+   * Returns the frozen options object.
+   * Safe to return directly - mutations will throw in strict mode.
+   */
+  get(): Readonly<Options> {
+    return this.#options;
+  }
+}

package/src/namespaces/OptionsNamespace/constants.ts

@@ -0,0 +1,41 @@
+// packages/core/src/namespaces/OptionsNamespace/constants.ts
+
+import type { Options } from "@real-router/types";
+
+/**
+ * Default options for the router.
+ */
+export const defaultOptions: Options = {
+  defaultRoute: "",
+  defaultParams: {},
+  trailingSlash: "preserve",
+  queryParamsMode: "loose",
+  queryParams: {
+    arrayFormat: "none",
+    booleanFormat: "none",
+    nullFormat: "default",
+  },
+  urlParamsEncoding: "default",
+  allowNotFound: true,
+  rewritePathOnMatch: true,
+  noValidate: false,
+} satisfies Options;
+
+/**
+ * Valid values for string enum options.
+ * Used for runtime validation in constructor options.
+ */
+export const VALID_OPTION_VALUES = {
+  trailingSlash: ["strict", "never", "always", "preserve"] as const,
+  queryParamsMode: ["default", "strict", "loose"] as const,
+  urlParamsEncoding: ["default", "uri", "uriComponent", "none"] as const,
+} as const;
+
+/**
+ * Valid keys and values for queryParams option.
+ */
+export const VALID_QUERY_PARAMS = {
+  arrayFormat: ["none", "brackets", "index", "comma"] as const,
+  booleanFormat: ["none", "string", "empty-true"] as const,
+  nullFormat: ["default", "hidden"] as const,
+} as const;

package/src/namespaces/OptionsNamespace/helpers.ts

@@ -0,0 +1,51 @@
+// 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;
+
+// eslint-disable-next-line sonarjs/function-return-type -- overloads: string for defaultRoute, Params for defaultParams
+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

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