@real-router/core 0.45.1 → 0.45.3

package/src/api/getRoutesApi.ts

@@ -0,0 +1,573 @@
+import { logger } from "@real-router/logger";
+
+import { throwIfDisposed } from "./helpers";
+import { guardRouteStructure } from "../guards";
+import { createInterceptable, getInternals } from "../internals";
+import {
+  clearConfigEntries,
+  removeFromDefinitions,
+  sanitizeRoute,
+} from "../namespaces/RoutesNamespace/helpers";
+import {
+  validateClearRoutes,
+  validateRemoveRoute,
+} from "../namespaces/RoutesNamespace/routeGuards";
+import {
+  clearRouteData,
+  refreshForwardMap,
+  registerAllRouteHandlers,
+} from "../namespaces/RoutesNamespace/routesStore";
+
+import type { RoutesApi } from "./types";
+import type { RouterInternals } from "../internals";
+import type { RouteLifecycleNamespace, RouteConfig } from "../namespaces";
+import type { RoutesStore } from "../namespaces/RoutesNamespace";
+import type { GuardFnFactory, Route } from "../types";
+import type {
+  DefaultDependencies,
+  ForwardToCallback,
+  Params,
+  Router,
+} from "@real-router/types";
+import type { RouteDefinition, RouteTree } from "route-tree";
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Recursively finds a route definition by its full dotted name.
+ */
+function findDefinition(
+  definitions: RouteDefinition[],
+  fullName: string,
+  parentPrefix = "",
+): RouteDefinition | undefined {
+  for (const def of definitions) {
+    const currentFullName = parentPrefix
+      ? `${parentPrefix}.${def.name}`
+      : def.name;
+
+    if (currentFullName === fullName) {
+      return def;
+    }
+
+    if (def.children && fullName.startsWith(`${currentFullName}.`)) {
+      return findDefinition(def.children, fullName, currentFullName);
+    }
+  }
+
+  /* v8 ignore next -- @preserve: defensive return, callers validate route exists before calling */
+  return undefined;
+}
+
+/**
+ * Clears all config entries and lifecycle handlers for a removed route
+ * (and all its descendants).
+ */
+function clearRouteConfigurations<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  routeName: string,
+  config: RouteConfig,
+  routeCustomFields: Record<string, Record<string, unknown>>,
+  lifecycleNamespace: RouteLifecycleNamespace<Dependencies>,
+): void {
+  const shouldClear = (name: string): boolean =>
+    name === routeName || name.startsWith(`${routeName}.`);
+
+  clearConfigEntries(config.decoders, shouldClear);
+  clearConfigEntries(config.encoders, shouldClear);
+  clearConfigEntries(config.defaultParams, shouldClear);
+  clearConfigEntries(config.forwardMap, shouldClear);
+  clearConfigEntries(config.forwardFnMap, shouldClear);
+  clearConfigEntries(routeCustomFields, shouldClear);
+
+  // Clear forwardMap entries pointing TO the deleted route (or its descendants)
+  clearConfigEntries(config.forwardMap, (key) =>
+    shouldClear(config.forwardMap[key]),
+  );
+
+  // Clear lifecycle handlers
+  const [canDeactivateFactories, canActivateFactories] =
+    lifecycleNamespace.getFactories();
+
+  for (const name of Object.keys(canActivateFactories)) {
+    if (shouldClear(name)) {
+      lifecycleNamespace.clearCanActivate(name);
+    }
+  }
+
+  for (const name of Object.keys(canDeactivateFactories)) {
+    if (shouldClear(name)) {
+      lifecycleNamespace.clearCanDeactivate(name);
+    }
+  }
+}
+
+/**
+ * Updates forwardTo for a route in config and returns the refreshed resolved
+ * forward map (REPLACE semantics — caller must call ctx.setResolvedForwardMap).
+ */
+function updateForwardTo<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  name: string,
+  forwardTo: string | ForwardToCallback<Dependencies> | null,
+  config: RouteConfig,
+  refreshForwardMapFn: (config: RouteConfig) => Record<string, string>,
+): Record<string, string> {
+  if (forwardTo === null) {
+    delete config.forwardMap[name];
+    delete config.forwardFnMap[name];
+  } else if (typeof forwardTo === "string") {
+    delete config.forwardFnMap[name];
+    config.forwardMap[name] = forwardTo;
+  } else {
+    delete config.forwardMap[name];
+    config.forwardFnMap[name] = forwardTo;
+  }
+
+  return refreshForwardMapFn(config);
+}
+
+/**
+ * Builds a full Route object from a bare RouteDefinition by re-attaching
+ * config entries and lifecycle factories.
+ *
+ * RECURSIVE — call with the factories tuple obtained ONCE from
+ * `lifecycleNamespace.getFactories()` and pass it through to children.
+ */
+function enrichRoute<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  routeDef: RouteDefinition,
+  routeName: string,
+  config: RouteConfig,
+  factories: [
+    Record<string, GuardFnFactory<Dependencies>>,
+    Record<string, GuardFnFactory<Dependencies>>,
+  ],
+): Route<Dependencies> {
+  const route: Route<Dependencies> = {
+    name: routeDef.name,
+    path: routeDef.path,
+  };
+
+  const forwardToFn = config.forwardFnMap[routeName];
+  const forwardToStr = config.forwardMap[routeName];
+
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (forwardToFn !== undefined) {
+    route.forwardTo = forwardToFn;
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  } else if (forwardToStr !== undefined) {
+    route.forwardTo = forwardToStr;
+  }
+
+  if (routeName in config.defaultParams) {
+    route.defaultParams = config.defaultParams[routeName];
+  }
+
+  if (routeName in config.decoders) {
+    route.decodeParams = config.decoders[routeName];
+  }
+
+  if (routeName in config.encoders) {
+    route.encodeParams = config.encoders[routeName];
+  }
+
+  const [canDeactivateFactories, canActivateFactories] = factories;
+
+  if (routeName in canActivateFactories) {
+    route.canActivate = canActivateFactories[routeName];
+  }
+
+  if (routeName in canDeactivateFactories) {
+    route.canDeactivate = canDeactivateFactories[routeName];
+  }
+
+  if (routeDef.children) {
+    route.children = routeDef.children.map((child) =>
+      enrichRoute(child, `${routeName}.${child.name}`, config, factories),
+    );
+  }
+
+  return route;
+}
+
+// ============================================================================
+// CRUD operations
+// ============================================================================
+
+/**
+ * Adds one or more routes to the router.
+ * Input already validated by facade.
+ */
+function addRoutes<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  store: RoutesStore<Dependencies>,
+  routes: Route<Dependencies>[],
+  parentName?: string,
+): void {
+  if (parentName) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const parentDef = findDefinition(store.definitions, parentName)!;
+
+    parentDef.children ??= [];
+
+    for (const route of routes) {
+      parentDef.children.push(sanitizeRoute(route));
+    }
+  } else {
+    for (const route of routes) {
+      store.definitions.push(sanitizeRoute(route));
+    }
+  }
+
+  registerAllRouteHandlers(
+    routes,
+    store.config,
+    store.routeCustomFields,
+    store.pendingCanActivate,
+    store.pendingCanDeactivate,
+    store.depsStore,
+    parentName ?? "",
+  );
+
+  store.treeOperations.commitTreeChanges(store);
+}
+
+/**
+ * Atomically replaces all routes with a new set.
+ * Follows RFC 6-step semantics for HMR support.
+ */
+function replaceRoutes<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  store: RoutesStore<Dependencies>,
+  routes: Route<Dependencies>[],
+  ctx: RouterInternals<Dependencies>,
+  currentPath: string | undefined,
+): void {
+  // Step 2: Clear route data (WITHOUT tree rebuild)
+  clearRouteData(store);
+
+  // Step 3: Clear definition lifecycle handlers (preserve external guards)
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
+  store.lifecycleNamespace!.clearDefinitionGuards();
+
+  // Step 4: Register new routes
+  for (const route of routes) {
+    store.definitions.push(sanitizeRoute(route));
+  }
+
+  registerAllRouteHandlers(
+    routes,
+    store.config,
+    store.routeCustomFields,
+    store.pendingCanActivate,
+    store.pendingCanDeactivate,
+    store.depsStore,
+    "",
+  );
+
+  // Step 5: One tree rebuild
+  store.treeOperations.commitTreeChanges(store);
+
+  // Step 6: Revalidate state
+  if (currentPath !== undefined) {
+    const revalidated = ctx.matchPath(currentPath, ctx.getOptions());
+
+    if (revalidated) {
+      ctx.setState(revalidated);
+    } else {
+      ctx.clearState();
+    }
+  }
+}
+
+/**
+ * Removes a route and all its children.
+ *
+ * @returns true if removed, false if not found
+ */
+function removeRoute<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(store: RoutesStore<Dependencies>, name: string): boolean {
+  const wasRemoved = removeFromDefinitions(store.definitions, name);
+
+  if (!wasRemoved) {
+    return false;
+  }
+
+  clearRouteConfigurations(
+    name,
+    store.config,
+    store.routeCustomFields,
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    store.lifecycleNamespace!,
+  );
+
+  store.treeOperations.commitTreeChanges(store);
+
+  return true;
+}
+
+/**
+ * Updates a route's configuration in place.
+ */
+function updateRouteConfig<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  store: RoutesStore<Dependencies>,
+  name: string,
+  updates: {
+    forwardTo?: string | ForwardToCallback<Dependencies> | null | undefined;
+    defaultParams?: Params | null | undefined;
+    decodeParams?: ((params: Params) => Params) | null | undefined;
+    encodeParams?: ((params: Params) => Params) | null | undefined;
+  },
+): void {
+  if (updates.forwardTo !== undefined) {
+    store.resolvedForwardMap = updateForwardTo(
+      name,
+      updates.forwardTo,
+      store.config,
+      (config) => refreshForwardMap(config),
+    );
+  }
+
+  if (updates.defaultParams !== undefined) {
+    if (updates.defaultParams === null) {
+      delete store.config.defaultParams[name];
+    } else {
+      store.config.defaultParams[name] = updates.defaultParams;
+    }
+  }
+
+  if (updates.decodeParams !== undefined) {
+    if (updates.decodeParams === null) {
+      delete store.config.decoders[name];
+    } else {
+      const decoder = updates.decodeParams;
+
+      store.config.decoders[name] = (params: Params): Params =>
+        (decoder(params) as Params | undefined) ?? params;
+    }
+  }
+
+  if (updates.encodeParams !== undefined) {
+    if (updates.encodeParams === null) {
+      delete store.config.encoders[name];
+    } else {
+      const encoder = updates.encodeParams;
+
+      store.config.encoders[name] = (params: Params): Params =>
+        (encoder(params) as Params | undefined) ?? params;
+    }
+  }
+}
+
+/**
+ * Gets a route by name with all its configuration.
+ */
+function getRoute<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  store: RoutesStore<Dependencies>,
+  name: string,
+): Route<Dependencies> | undefined {
+  const segments = store.matcher.getSegmentsByName(name);
+
+  if (!segments) {
+    return undefined;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- segments is non-empty (checked above)
+  const targetNode = segments.at(-1)! as RouteTree;
+  const definition = store.treeOperations.nodeToDefinition(targetNode);
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const factories = store.lifecycleNamespace!.getFactories();
+
+  return enrichRoute(definition, name, store.config, factories);
+}
+
+// ============================================================================
+// API factory
+// ============================================================================
+
+export function getRoutesApi<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(router: Router<Dependencies>): RoutesApi<Dependencies> {
+  const ctx = getInternals(router);
+
+  const store = ctx.routeGetStore();
+
+  const interceptableAdd = createInterceptable(
+    "add",
+    (routeArray: Route<Dependencies>[], options?: { parent?: string }) => {
+      addRoutes(store, routeArray, options?.parent);
+    },
+    ctx.interceptors,
+  );
+
+  return {
+    add: (routes, options) => {
+      throwIfDisposed(ctx.isDisposed);
+
+      const routeArray = Array.isArray(routes) ? routes : [routes];
+      const parentName = options?.parent;
+
+      guardRouteStructure(routeArray, ctx.validator);
+
+      if (parentName !== undefined) {
+        ctx.validator?.routes.validateParentOption(parentName, store.tree);
+      }
+
+      ctx.validator?.routes.throwIfInternalRouteInArray(routeArray, "addRoute");
+      ctx.validator?.routes.validateAddRouteArgs(routeArray);
+      ctx.validator?.routes.validateRoutes(routeArray, store);
+
+      interceptableAdd(
+        routeArray,
+        parentName === undefined ? undefined : { parent: parentName },
+      );
+    },
+
+    remove: (name) => {
+      throwIfDisposed(ctx.isDisposed);
+
+      ctx.validator?.routes.validateRemoveRouteArgs(name);
+      ctx.validator?.routes.throwIfInternalRoute(name, "removeRoute");
+
+      const canRemove = validateRemoveRoute(
+        name,
+        ctx.getStateName(),
+        ctx.isTransitioning(),
+      );
+
+      if (!canRemove) {
+        return;
+      }
+
+      const wasRemoved = removeRoute(store, name);
+
+      if (!wasRemoved) {
+        logger.warn(
+          "router.removeRoute",
+          `Route "${name}" not found. No changes made.`,
+        );
+      }
+    },
+
+    update: (name, updates) => {
+      throwIfDisposed(ctx.isDisposed);
+
+      ctx.validator?.routes.validateUpdateRouteBasicArgs(name, updates);
+      ctx.validator?.routes.throwIfInternalRoute(name, "updateRoute");
+
+      const {
+        forwardTo,
+        defaultParams,
+        decodeParams,
+        encodeParams,
+        canActivate,
+        canDeactivate,
+      } = updates;
+
+      ctx.validator?.routes.validateUpdateRoutePropertyTypes(name, updates);
+
+      /* v8 ignore next 6 -- @preserve: race condition guard, mirrors Router.updateRoute() same-path guard tested via Router.ts unit tests */
+      if (ctx.isTransitioning()) {
+        logger.error(
+          "router.updateRoute",
+          `Updating route "${name}" while navigation is in progress. This may cause unexpected behavior.`,
+        );
+      }
+
+      ctx.validator?.routes.validateUpdateRoute(name, updates, store);
+
+      updateRouteConfig(store, name, {
+        forwardTo,
+        defaultParams,
+        decodeParams,
+        encodeParams,
+      });
+
+      if (canActivate !== undefined) {
+        if (canActivate === null) {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
+          store.lifecycleNamespace!.clearCanActivate(name);
+        } else {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
+          store.lifecycleNamespace!.addCanActivate(name, canActivate, true);
+        }
+      }
+
+      if (canDeactivate !== undefined) {
+        if (canDeactivate === null) {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
+          store.lifecycleNamespace!.clearCanDeactivate(name);
+        } else {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
+          store.lifecycleNamespace!.addCanDeactivate(name, canDeactivate, true);
+        }
+      }
+    },
+
+    clear: () => {
+      throwIfDisposed(ctx.isDisposed);
+
+      const canClear = validateClearRoutes(ctx.isTransitioning());
+
+      /* v8 ignore next 3 -- @preserve: race condition guard, mirrors Router.clearRoutes() same-path guard tested via validateClearRoutes unit tests */
+      if (!canClear) {
+        return;
+      }
+
+      store.treeOperations.resetStore(store);
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
+      store.lifecycleNamespace!.clearAll();
+      ctx.clearState();
+    },
+
+    has: (name) => {
+      ctx.validator?.routes.validateRouteName(name, "hasRoute");
+
+      return store.matcher.hasRoute(name);
+    },
+
+    get: (name) => {
+      ctx.validator?.routes.validateRouteName(name, "getRoute");
+
+      return getRoute(store, name);
+    },
+
+    replace: (routes) => {
+      throwIfDisposed(ctx.isDisposed);
+
+      const routeArray = Array.isArray(routes) ? routes : [routes];
+
+      const canReplace = validateClearRoutes(ctx.isTransitioning());
+
+      if (!canReplace) {
+        return;
+      }
+
+      guardRouteStructure(routeArray, ctx.validator);
+
+      ctx.validator?.routes.throwIfInternalRouteInArray(
+        routeArray,
+        "replaceRoutes",
+      );
+      ctx.validator?.routes.validateAddRouteArgs(routeArray);
+      ctx.validator?.routes.validateRoutes(routeArray, store);
+
+      const currentPath = router.getState()?.path;
+
+      replaceRoutes(store, routeArray, ctx, currentPath);
+    },
+  };
+}

package/src/api/helpers.ts

@@ -0,0 +1,10 @@
+// packages/core/src/api/helpers.ts
+
+import { errorCodes } from "../constants";
+import { RouterError } from "../RouterError";
+
+export function throwIfDisposed(isDisposed: () => boolean): void {
+  if (isDisposed()) {
+    throw new RouterError(errorCodes.ROUTER_DISPOSED);
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,16 @@
+export { getPluginApi } from "./getPluginApi";
+
+export { getRoutesApi } from "./getRoutesApi";
+
+export { getDependenciesApi } from "./getDependenciesApi";
+
+export { getLifecycleApi } from "./getLifecycleApi";
+
+export { cloneRouter } from "./cloneRouter";
+
+export type {
+  PluginApi,
+  RoutesApi,
+  DependenciesApi,
+  LifecycleApi,
+} from "./types";

package/src/api/types.ts

@@ -0,0 +1,12 @@
+import type { PluginApi as BasePluginApi } from "@real-router/types";
+import type { RouteTree } from "route-tree";
+
+export interface PluginApi extends Omit<BasePluginApi, "getTree"> {
+  getTree: () => RouteTree;
+}
+
+export {
+  type RoutesApi,
+  type LifecycleApi,
+  type DependenciesApi,
+} from "@real-router/types";

package/src/constants.ts

@@ -0,0 +1,87 @@
+// packages/core/src/constants.ts
+
+import type {
+  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
+  PLUGIN_CONFLICT: "PLUGIN_CONFLICT", // Plugin tried to extend router with already-existing property
+});
+
+/**
+ * General router constants.
+ * Special route names and identifiers.
+ */
+export const UNKNOWN_ROUTE = "@@router/UNKNOWN_ROUTE";
+
+export const constants: Constants = {
+  UNKNOWN_ROUTE,
+};
+
+/**
+ * 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_LEAVE_APPROVE: "onTransitionLeaveApprove", // Plugin method called when deactivation guards pass
+  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_LEAVE_APPROVE: "$$leaveApprove", // Emitted when deactivation guards pass
+  TRANSITION_CANCEL: "$$cancel", // Emitted when navigation is cancelled
+  TRANSITION_SUCCESS: "$$success", // Emitted when navigation completes successfully
+  TRANSITION_ERROR: "$$error", // Emitted when navigation fails
+};
+
+export const DEFAULT_LIMITS = {
+  maxDependencies: 100,
+  maxPlugins: 50,
+  maxListeners: 10_000,
+  warnListeners: 1000,
+  maxEventDepth: 5,
+  maxLifecycleHandlers: 200,
+} as const;
+
+export const EMPTY_PARAMS: Readonly<Record<string, never>> = Object.freeze({});