@real-router/core 0.55.0 → 0.57.0

package/src/api/getRoutesApi.ts

@@ -1,546 +0,0 @@
-import { logger } from "@real-router/logger";
-
-import { throwIfDisposed } from "./helpers";
-import { guardRouteStructure } from "../guards";
-import { createInterceptable, getInternals } from "../internals";
-import {
-  clearConfigEntries,
-  removeFromDefinitions,
-} from "../namespaces/RoutesNamespace/helpers";
-import {
-  validateClearRoutes,
-  validateRemoveRoute,
-} from "../namespaces/RoutesNamespace/routeGuards";
-import {
-  adoptRouteArtifacts,
-  assertAddable,
-  buildAddArtifacts,
-  buildReplaceArtifacts,
-  refreshForwardMap,
-} 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,
-  TransitionMeta,
-} from "@real-router/types";
-import type { RouteDefinition, RouteTree } from "route-tree";
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-/**
- * 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,
-): Record<string, string> {
-  // Prepare-then-commit (issue #698): apply the change to CLONES of the forward
-  // maps, resolve the chain (a cycle throws here), and only then swap the clones
-  // in — so a rejected update never leaves config.forwardMap poisoned.
-  const forwardMap = Object.assign(
-    Object.create(null) as RouteConfig["forwardMap"],
-    config.forwardMap,
-  );
-  const forwardFnMap = Object.assign(
-    Object.create(null) as RouteConfig["forwardFnMap"],
-    config.forwardFnMap,
-  );
-
-  if (forwardTo === null) {
-    delete forwardMap[name];
-    delete forwardFnMap[name];
-  } else if (typeof forwardTo === "string") {
-    delete forwardFnMap[name];
-    forwardMap[name] = forwardTo;
-  } else {
-    delete forwardMap[name];
-    forwardFnMap[name] = forwardTo;
-  }
-
-  const resolved = refreshForwardMap({ ...config, forwardMap });
-
-  config.forwardMap = forwardMap;
-  config.forwardFnMap = forwardFnMap;
-
-  return resolved;
-}
-
-/**
- * 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 {
-  // Prepare-then-commit (issue #698): reject the silent-corruption cases
-  // up front (dup name vs existing, missing parent), build the merged tree /
-  // config into locals (async/circular forwardTo + invalid constraint throw
-  // here), then swap atomically. A rejected add leaves the store untouched.
-  assertAddable(store, routes, parentName);
-  adoptRouteArtifacts(store, buildAddArtifacts(store, routes, parentName));
-}
-
-/**
- * Atomically replaces all routes with a new set (HMR / code-splitting).
- * Prepare-then-commit (issue #698): the new set is fully built into locals
- * first — a circular/async forwardTo or invalid path throws here, leaving the
- * existing tree intact — then committed.
- */
-function replaceRoutes<
-  Dependencies extends DefaultDependencies = DefaultDependencies,
->(
-  store: RoutesStore<Dependencies>,
-  routes: Route<Dependencies>[],
-  ctx: RouterInternals<Dependencies>,
-  currentPath: string | undefined,
-  previousTransition: TransitionMeta | undefined,
-): void {
-  // Build the whole new set BEFORE touching the store.
-  const artifacts = buildReplaceArtifacts(
-    routes,
-    store.rootPath,
-    store.matcherOptions,
-  );
-
-  // Clear definition lifecycle handlers (preserve external guards), then swap.
-  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
-  store.lifecycleNamespace!.clearDefinitionGuards();
-  adoptRouteArtifacts(store, artifacts);
-
-  // Revalidate state (preserve transition from previous state)
-  if (currentPath !== undefined) {
-    const revalidated = ctx.matchPath(currentPath, ctx.getOptions());
-
-    if (revalidated) {
-      ctx.setState({
-        ...revalidated,
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- previousTransition is guaranteed defined: currentPath is only set when getState() returned a state, which always has transition
-        transition: previousTransition!,
-      });
-    } 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,
-    );
-  }
-
-  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 =>
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime fallback if user-provided decoder violates its return type
-        decoder(params) ?? 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 =>
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime fallback if user-provided encoder violates its return type
-        encoder(params) ?? 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 currentState = router.getState();
-
-      replaceRoutes(
-        store,
-        routeArray,
-        ctx,
-        currentState?.path,
-        currentState?.transition,
-      );
-    },
-  };
-}

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,101 +0,0 @@
-// packages/core/src/constants.ts
-
-import type {
-  EventToNameMap,
-  EventToPluginMap,
-  ErrorCodeToValueMap,
-  ErrorCodeKeys,
-  ErrorCodeValues,
-  TransitionMeta,
-} 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
-  CONTEXT_NAMESPACE_ALREADY_CLAIMED: "CONTEXT_NAMESPACE_ALREADY_CLAIMED", // Plugin tried to claim a context namespace already owned by another plugin
-});
-
-/**
- * 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({});
-
-const FROZEN_EMPTY_SEGMENTS = Object.freeze({
-  deactivated: Object.freeze([]) as unknown as string[],
-  activated: Object.freeze([]) as unknown as string[],
-  intersection: "",
-});
-
-export const DEFAULT_TRANSITION = Object.freeze({
-  phase: "activating",
-  reason: "success",
-  segments: FROZEN_EMPTY_SEGMENTS,
-}) as TransitionMeta;