@real-router/core 0.45.0 → 0.45.1

package/src/api/getRoutesApi.ts

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

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

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

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

@@ -1,87 +0,0 @@
-// 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({});