@real-router/core 0.25.4 → 0.26.0

package/src/api/cloneRouter.ts

@@ -0,0 +1,106 @@
+import { routeTreeToDefinitions } from "route-tree";
+import { getTypeDescription } from "type-guards";
+
+import { errorCodes } from "../constants";
+import { getInternals } from "../internals";
+import { Router as RouterClass } from "../Router";
+import { RouterError } from "../RouterError";
+import { getLifecycleApi } from "./getLifecycleApi";
+
+import type { Route } from "../types";
+import type { DefaultDependencies, Router } from "@real-router/types";
+
+function validateCloneArgs(dependencies: unknown): void {
+  if (dependencies === undefined) {
+    return;
+  }
+
+  if (
+    !(
+      dependencies &&
+      typeof dependencies === "object" &&
+      dependencies.constructor === Object
+    )
+  ) {
+    throw new TypeError(
+      `[cloneRouter] Invalid dependencies: expected plain object or undefined, received ${getTypeDescription(dependencies)}`,
+    );
+  }
+
+  for (const key in dependencies) {
+    if (Object.getOwnPropertyDescriptor(dependencies, key)?.get) {
+      throw new TypeError(
+        `[cloneRouter] Getters not allowed in dependencies: "${key}"`,
+      );
+    }
+  }
+}
+
+export function cloneRouter<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(
+  router: Router<Dependencies>,
+  dependencies?: Dependencies,
+): RouterClass<Dependencies> {
+  const ctx = getInternals(router);
+
+  if (ctx.isDisposed()) {
+    throw new RouterError(errorCodes.ROUTER_DISPOSED);
+  }
+
+  if (!ctx.noValidate) {
+    validateCloneArgs(dependencies);
+  }
+
+  // Get source store directly
+  const sourceStore = ctx.routeGetStore();
+  const routes = routeTreeToDefinitions(sourceStore.tree);
+  const routeConfig = sourceStore.config;
+  const resolvedForwardMap = sourceStore.resolvedForwardMap;
+  const routeCustomFields = sourceStore.routeCustomFields;
+
+  const options = ctx.cloneOptions();
+  const sourceDeps = ctx.cloneDependencies();
+  const [canDeactivateFactories, canActivateFactories] =
+    ctx.getLifecycleFactories();
+  const pluginFactories = ctx.getPluginFactories();
+
+  const mergedDeps = {
+    ...sourceDeps,
+    ...dependencies,
+  } as Dependencies;
+
+  const newRouter = new RouterClass<Dependencies>(
+    routes as Route<Dependencies>[],
+    options,
+    mergedDeps,
+  );
+
+  const lifecycle = getLifecycleApi(newRouter);
+
+  for (const [name, handler] of Object.entries(canDeactivateFactories)) {
+    lifecycle.addDeactivateGuard(name, handler);
+  }
+
+  for (const [name, handler] of Object.entries(canActivateFactories)) {
+    lifecycle.addActivateGuard(name, handler);
+  }
+
+  if (pluginFactories.length > 0) {
+    newRouter.usePlugin(...pluginFactories);
+  }
+
+  const newCtx = getInternals(newRouter);
+  const newStore = newCtx.routeGetStore();
+
+  // Apply cloned config directly to new store
+  Object.assign(newStore.config.decoders, routeConfig.decoders);
+  Object.assign(newStore.config.encoders, routeConfig.encoders);
+  Object.assign(newStore.config.defaultParams, routeConfig.defaultParams);
+  Object.assign(newStore.config.forwardMap, routeConfig.forwardMap);
+  Object.assign(newStore.config.forwardFnMap, routeConfig.forwardFnMap);
+  Object.assign(newStore.resolvedForwardMap, resolvedForwardMap);
+  Object.assign(newStore.routeCustomFields, routeCustomFields);
+
+  return newRouter;
+}

package/src/api/getDependenciesApi.ts

@@ -0,0 +1,216 @@
+import { logger } from "@real-router/logger";
+import { getTypeDescription } from "type-guards";
+
+import { errorCodes } from "../constants";
+import { computeThresholds } from "../helpers";
+import { getInternals } from "../internals";
+import {
+  validateDependenciesObject,
+  validateDependencyExists,
+  validateDependencyLimit,
+  validateDependencyName,
+  validateSetDependencyArgs,
+} from "../namespaces/DependenciesNamespace/validators";
+import { RouterError } from "../RouterError";
+
+import type { DependenciesApi } from "./types";
+import type { DependenciesStore } from "../namespaces/DependenciesNamespace/dependenciesStore";
+import type { DefaultDependencies, Router } from "@real-router/types";
+
+function throwIfDisposed(isDisposed: () => boolean): void {
+  if (isDisposed()) {
+    throw new RouterError(errorCodes.ROUTER_DISPOSED);
+  }
+}
+
+// =============================================================================
+// Module-private CRUD functions
+// =============================================================================
+
+function checkDependencyCount(
+  store: DependenciesStore,
+  methodName: string,
+): void {
+  const maxDependencies = store.limits.maxDependencies;
+
+  if (maxDependencies === 0) {
+    return;
+  }
+
+  const currentCount = Object.keys(store.dependencies).length;
+
+  const { warn, error } = computeThresholds(maxDependencies);
+
+  if (currentCount === warn) {
+    logger.warn(
+      `router.${methodName}`,
+      `${warn} dependencies registered. ` + `Consider if all are necessary.`,
+    );
+  } else if (currentCount === error) {
+    logger.error(
+      `router.${methodName}`,
+      `${error} dependencies registered! ` +
+        `This indicates architectural problems. ` +
+        `Hard limit at ${maxDependencies}.`,
+    );
+  } else if (currentCount >= maxDependencies) {
+    throw new Error(
+      `[router.${methodName}] Dependency limit exceeded (${maxDependencies}). ` +
+        `Current: ${currentCount}. This is likely a bug in your code. ` +
+        `If you genuinely need more dependencies, your architecture needs refactoring.`,
+    );
+  }
+}
+
+function setDependency(
+  store: DependenciesStore,
+  dependencyName: string,
+  dependencyValue: unknown,
+): boolean {
+  // undefined = "don't set" (feature for conditional setting)
+  if (dependencyValue === undefined) {
+    return false;
+  }
+
+  const isNewKey = !Object.hasOwn(store.dependencies, dependencyName);
+
+  if (isNewKey) {
+    // Only check limit when adding new keys (overwrites don't increase count)
+    checkDependencyCount(store, "setDependency");
+  } else {
+    const oldValue = (store.dependencies as Record<string, unknown>)[
+      dependencyName
+    ];
+    const isChanging = oldValue !== dependencyValue;
+    // Special case for NaN idempotency (NaN !== NaN is always true)
+    const bothAreNaN = Number.isNaN(oldValue) && Number.isNaN(dependencyValue);
+
+    if (isChanging && !bothAreNaN) {
+      logger.warn(
+        "router.setDependency",
+        "Router dependency already exists and is being overwritten:",
+        dependencyName,
+      );
+    }
+  }
+
+  (store.dependencies as Record<string, unknown>)[dependencyName] =
+    dependencyValue;
+
+  return true;
+}
+
+function setMultipleDependencies(
+  store: DependenciesStore,
+  deps: Record<string, unknown>,
+): void {
+  const overwrittenKeys: string[] = [];
+
+  for (const key in deps) {
+    if (deps[key] !== undefined) {
+      if (Object.hasOwn(store.dependencies, key)) {
+        overwrittenKeys.push(key);
+      }
+
+      (store.dependencies as Record<string, unknown>)[key] = deps[key];
+    }
+  }
+
+  if (overwrittenKeys.length > 0) {
+    logger.warn(
+      "router.setDependencies",
+      "Overwritten:",
+      overwrittenKeys.join(", "),
+    );
+  }
+}
+
+// =============================================================================
+// Public API factory
+// =============================================================================
+
+export function getDependenciesApi<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(router: Router<Dependencies>): DependenciesApi<Dependencies> {
+  const ctx = getInternals(router);
+
+  return {
+    get: (name) => {
+      if (!ctx.noValidate) {
+        validateDependencyName(name, "getDependency");
+      }
+
+      const store = ctx.dependenciesGetStore();
+      const value = (store.dependencies as Record<string, unknown>)[
+        name as string
+      ];
+
+      if (!ctx.noValidate) {
+        validateDependencyExists(value, name as string);
+      }
+
+      return value as Dependencies[typeof name];
+    },
+    getAll: () => ({ ...ctx.dependenciesGetStore().dependencies }),
+    set: (name, value) => {
+      throwIfDisposed(ctx.isDisposed);
+
+      if (!ctx.noValidate) {
+        validateSetDependencyArgs(name);
+      }
+
+      setDependency(ctx.dependenciesGetStore(), name as string, value);
+    },
+    setAll: (deps) => {
+      throwIfDisposed(ctx.isDisposed);
+
+      const store = ctx.dependenciesGetStore();
+
+      if (!ctx.noValidate) {
+        validateDependenciesObject(deps, "setDependencies");
+        validateDependencyLimit(
+          Object.keys(store.dependencies).length,
+          Object.keys(deps).length,
+          "setDependencies",
+          store.limits.maxDependencies,
+        );
+      }
+
+      setMultipleDependencies(store, deps as Record<string, unknown>);
+    },
+    remove: (name) => {
+      throwIfDisposed(ctx.isDisposed);
+
+      if (!ctx.noValidate) {
+        validateDependencyName(name, "removeDependency");
+      }
+
+      const store = ctx.dependenciesGetStore();
+
+      if (!Object.hasOwn(store.dependencies, name as string)) {
+        logger.warn(
+          `router.removeDependency`,
+          `Attempted to remove non-existent dependency: "${getTypeDescription(name)}"`,
+        );
+      }
+
+      delete (store.dependencies as Record<string, unknown>)[name as string];
+    },
+    reset: () => {
+      throwIfDisposed(ctx.isDisposed);
+      const store = ctx.dependenciesGetStore();
+
+      store.dependencies = Object.create(null) as Partial<Dependencies>;
+    },
+    has: (name) => {
+      if (!ctx.noValidate) {
+        validateDependencyName(name, "hasDependency");
+      }
+
+      return Object.hasOwn(
+        ctx.dependenciesGetStore().dependencies,
+        name as string,
+      );
+    },
+  };
+}

package/src/api/getLifecycleApi.ts

@@ -0,0 +1,67 @@
+import { validateRouteName } from "type-guards";
+
+import { errorCodes } from "../constants";
+import { getInternals } from "../internals";
+import { validateHandler } from "../namespaces/RouteLifecycleNamespace/validators";
+import { RouterError } from "../RouterError";
+
+import type { LifecycleApi } from "./types";
+import type { DefaultDependencies, Router } from "@real-router/types";
+
+function throwIfDisposed(isDisposed: () => boolean): void {
+  if (isDisposed()) {
+    throw new RouterError(errorCodes.ROUTER_DISPOSED);
+  }
+}
+
+export function getLifecycleApi<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(router: Router<Dependencies>): LifecycleApi<Dependencies> {
+  const ctx = getInternals(router);
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring
+  const lifecycleNamespace = ctx.routeGetStore().lifecycleNamespace!;
+
+  return {
+    addActivateGuard(name, handler) {
+      throwIfDisposed(ctx.isDisposed);
+
+      if (!ctx.noValidate) {
+        validateRouteName(name, "addActivateGuard");
+        validateHandler(handler, "addActivateGuard");
+      }
+
+      lifecycleNamespace.addCanActivate(name, handler, ctx.noValidate);
+    },
+
+    addDeactivateGuard(name, handler) {
+      throwIfDisposed(ctx.isDisposed);
+
+      if (!ctx.noValidate) {
+        validateRouteName(name, "addDeactivateGuard");
+        validateHandler(handler, "addDeactivateGuard");
+      }
+
+      lifecycleNamespace.addCanDeactivate(name, handler, ctx.noValidate);
+    },
+
+    removeActivateGuard(name) {
+      throwIfDisposed(ctx.isDisposed);
+
+      if (!ctx.noValidate) {
+        validateRouteName(name, "removeActivateGuard");
+      }
+
+      lifecycleNamespace.clearCanActivate(name);
+    },
+
+    removeDeactivateGuard(name) {
+      throwIfDisposed(ctx.isDisposed);
+
+      if (!ctx.noValidate) {
+        validateRouteName(name, "removeDeactivateGuard");
+      }
+
+      lifecycleNamespace.clearCanDeactivate(name);
+    },
+  };
+}

package/src/api/getPluginApi.ts

@@ -0,0 +1,118 @@
+import { errorCodes } from "../constants";
+import { getInternals } from "../internals";
+import { validateListenerArgs } from "../namespaces/EventBusNamespace/validators";
+import { validateNavigateToStateArgs } from "../namespaces/NavigationNamespace/validators";
+import {
+  validateMatchPathArgs,
+  validateSetRootPathArgs,
+  validateStateBuilderArgs,
+} from "../namespaces/RoutesNamespace/validators";
+import { validateMakeStateArgs } from "../namespaces/StateNamespace/validators";
+import { RouterError } from "../RouterError";
+
+import type { PluginApi } from "./types";
+import type { DefaultDependencies, Router } from "@real-router/types";
+
+function throwIfDisposed(isDisposed: () => boolean): void {
+  if (isDisposed()) {
+    throw new RouterError(errorCodes.ROUTER_DISPOSED);
+  }
+}
+
+export function getPluginApi<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+>(router: Router<Dependencies>): PluginApi {
+  const ctx = getInternals(router);
+
+  return {
+    makeState: (name, params, path, meta, forceId) => {
+      if (!ctx.noValidate) {
+        validateMakeStateArgs(name, params, path, forceId);
+      }
+
+      return ctx.makeState(name, params, path, meta, forceId);
+    },
+    buildState: (routeName, routeParams) => {
+      if (!ctx.noValidate) {
+        validateStateBuilderArgs(routeName, routeParams, "buildState");
+      }
+
+      const { name, params } = ctx.forwardState(routeName, routeParams);
+
+      return ctx.buildStateResolved(name, params);
+    },
+    forwardState: (routeName, routeParams) => {
+      if (!ctx.noValidate) {
+        validateStateBuilderArgs(routeName, routeParams, "forwardState");
+      }
+
+      return ctx.forwardState(routeName, routeParams);
+    },
+    matchPath: (path) => {
+      if (!ctx.noValidate) {
+        validateMatchPathArgs(path);
+      }
+
+      return ctx.matchPath(path, ctx.getOptions());
+    },
+    setRootPath: (rootPath) => {
+      throwIfDisposed(ctx.isDisposed);
+
+      if (!ctx.noValidate) {
+        validateSetRootPathArgs(rootPath);
+      }
+
+      ctx.setRootPath(rootPath);
+    },
+    getRootPath: ctx.getRootPath,
+    navigateToState: (toState, fromState, opts) => {
+      throwIfDisposed(ctx.isDisposed);
+
+      if (!ctx.noValidate) {
+        validateNavigateToStateArgs(toState, fromState, opts);
+      }
+
+      return ctx.navigateToState(toState, fromState, opts);
+    },
+    addEventListener: (eventName, cb) => {
+      throwIfDisposed(ctx.isDisposed);
+
+      if (!ctx.noValidate) {
+        validateListenerArgs(eventName, cb);
+      }
+
+      return ctx.addEventListener(eventName, cb);
+    },
+    buildNavigationState: (name, params = {}) => {
+      if (!ctx.noValidate) {
+        validateStateBuilderArgs(name, params, "buildNavigationState");
+      }
+
+      const { name: resolvedName, params: resolvedParams } = ctx.forwardState(
+        name,
+        params,
+      );
+      const routeInfo = ctx.buildStateResolved(resolvedName, resolvedParams);
+
+      if (!routeInfo) {
+        return;
+      }
+
+      return ctx.makeState(
+        routeInfo.name,
+        routeInfo.params,
+        ctx.buildPath(routeInfo.name, routeInfo.params),
+        {
+          params: routeInfo.meta,
+          options: {},
+        },
+      );
+    },
+    getOptions: ctx.getOptions,
+    getTree: ctx.getTree,
+    getForwardState: () => ctx.forwardState,
+    setForwardState: (fn) => {
+      ctx.forwardState = fn;
+    },
+  };
+}