@real-router/core 0.139.0 → 0.140.0

package/dist/cjs/dependenciesStore.d.ts

@@ -7,8 +7,8 @@ import { Limits } from "./types/internal.js";
  * sake lives in this module; the edits a caller asks for live in
  * `getDependenciesApi`.
  *
- * ⚠ `limits` is read by `@real-router/validation-plugin` off the store it is
- * handed, and by nothing in core.
+ * ⚠ `limits` is read by `getDependenciesApi` for the count check and handed
+ * out as `PluginApi.getResolvedLimits()`.
  */
 export interface DependenciesStore<Dependencies extends DefaultDependencies = DefaultDependencies> {
   dependencies: Partial<Dependencies>;

package/dist/cjs/index.js

@@ -1,2 +1,2 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./RouterError-C-p1yaby.js"),t=require("./Router-NcUbf7cb.js"),n=(e=[],n={},r={})=>new t.t(e,n,r),r=Object.freeze,i=new WeakMap,a=e=>{let t=i.get(e);return t||(t=r({navigate:e.navigate,getState:e.getState,isActiveRoute:e.isActiveRoute,canNavigateTo:e.canNavigateTo,subscribe:e.subscribe,subscribeLeave:e.subscribeLeave,isLeaveApproved:e.isLeaveApproved}),i.set(e,t)),t};exports.Router=t.t,exports.RouterError=e.t,exports.UNKNOWN_ROUTE=e.p,exports.constants=e.h,exports.createRouter=n,exports.errorCodes=e.g,exports.events=e._,exports.getNavigator=a,exports.resolveForwardChain=t.v;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./RouterError-C-p1yaby.js"),t=require("./Router-C2cC4TOn.js"),n=(e=[],n={},r={})=>new t.t(e,n,r),r=Object.freeze,i=new WeakMap,a=e=>{let t=i.get(e);return t||(t=r({navigate:e.navigate,getState:e.getState,isActiveRoute:e.isActiveRoute,canNavigateTo:e.canNavigateTo,subscribe:e.subscribe,subscribeLeave:e.subscribeLeave,isLeaveApproved:e.isLeaveApproved}),i.set(e,t)),t};exports.Router=t.t,exports.RouterError=e.t,exports.UNKNOWN_ROUTE=e.p,exports.constants=e.h,exports.createRouter=n,exports.errorCodes=e.g,exports.events=e._,exports.getNavigator=a,exports.resolveForwardChain=t.v;
 //# sourceMappingURL=index.js.map

package/dist/cjs/types/RouterValidator.d.ts

@@ -6,7 +6,10 @@
  * When ctx.validator is null (default), validation is skipped.
  * When ctx.validator is set (by validation plugin), all methods are called.
  *
- * All parameters use `unknown` type to avoid coupling to internal type names.
+ * Parameters that carry a caller-supplied value use `unknown`, to avoid coupling
+ * to internal type names. ⚠ That is not a blanket rule: where core already holds
+ * the fact the analyser judges, the fact travels — a number, a name, a value —
+ * rather than the container it was read from (#2382).
  */
 export interface RouterValidator {
   /**
@@ -19,12 +22,24 @@ export interface RouterValidator {
     validateShouldUpdateNodeArgs: (name: unknown) => void;
     validateStateBuilderArgs: (name: unknown, params: unknown, caller: string) => void;
     validateAddRouteArgs: (routes: unknown) => void;
-    validateRoutes: (routes: unknown[], tree: unknown, parentName?: string) => void;
+    /**
+     * ⚑ Takes no store (#2382). The analyser reads the three facts it judges
+     * from `PluginApi`: the path slots and the ONE-HOP forward map come back as
+     * frozen values, and the tree is the published one `getTree()` already hands
+     * out — no container travels that the curated surface does not.
+     */
+    validateRoutes: (routes: unknown[], parentName?: string) => void;
     validateRemoveRouteArgs: (name: unknown) => void;
     validateUpdateRouteBasicArgs: (name: unknown, updates: unknown) => void;
     validateUpdateRoutePropertyTypes: (name: string, updates: unknown) => void;
-    validateUpdateRoute: (name: string, updates: unknown, tree: unknown) => void;
-    validateParentOption: (parent: unknown, tree: unknown) => void;
+    /** Reads the same three facts from `PluginApi` as `validateRoutes` (#2382). */
+    validateUpdateRoute: (name: string, updates: unknown) => void;
+    /**
+     * ⚑ Takes no tree (#2382): the analyser reads it from `PluginApi.getTree()`,
+     * which hands out the same object — the tree is published already, so
+     * passing it as an argument added a second address and nothing else.
+     */
+    validateParentOption: (parent: unknown) => void;
     validateRouteName: (name: unknown, caller: string) => void;
     throwIfInternalRoute: (name: unknown, caller: string) => void;
     throwIfInternalRouteInArray: (routes: unknown[], caller: string) => void;
@@ -37,7 +52,8 @@ export interface RouterValidator {
    */
   options: {
     validateOptions: (options: unknown, methodName: string) => void;
-    validateResolvedDefaultRoute: (routeName: unknown, store: unknown) => void;
+    /** Reads the tree from `PluginApi.getTree()`, like `validateParentOption` (#2382). */
+    validateResolvedDefaultRoute: (routeName: unknown) => void;
   };
   /**
    * Dependencies validation methods
@@ -46,8 +62,22 @@ export interface RouterValidator {
     validateDependencyName: (name: unknown, caller: string) => void;
     validateSetDependencyArgs: (name: unknown, value: unknown, caller: string) => void;
     validateDependenciesObject: (deps: unknown, caller: string) => void;
-    validateDependencyExists: (name: string, store: unknown) => void;
-    validateDependencyCount: (store: unknown, methodName: string) => void;
+    /**
+     * ⚑ Takes the VALUE core read, not the store that holds it (#2382). The
+     * question is whether the name resolved to anything, and core has the answer
+     * one line earlier: `readDependency` performs exactly that lookup.
+     */
+    validateDependencyExists: (name: string, value: unknown) => void;
+    /**
+     * ⚑ Takes the two NUMBERS it judges, not the store that holds them (#2382).
+     * `maxDependencies` arrives already resolved by `createLimits`, which takes
+     * this path out of the default-drift #1879 names.
+     *
+     * ⚠ Both arguments sit inside the optional chain on purpose: with no
+     * validator installed the `?.` short-circuits the whole chain, arguments
+     * included, so the key count is never walked.
+     */
+    validateDependencyCount: (currentCount: number, maxDependencies: number, methodName: string) => void;
     validateCloneArgs: (dependencies: unknown) => void;
     warnOverwrite: (name: string, methodName: string) => void;
     warnBatchOverwrite: (keys: string[], methodName: string) => void;

package/dist/cjs/types/RouterValidator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RouterValidator.d.ts","names":[],"sources":["../../../src/types/RouterValidator.ts"],"mappings":";;;;;;;;;;iBAUiB;;;;EAIf;IACE,wBAAwB,gBAAgB;IACxC,wBAAwB;IACxB,4BACE,eACA,iBACA,iBACA;IAEF,+BAA+B;IAC/B,2BACE,eACA,iBACA;IAEF,uBAAuB;IACvB,iBACE,mBACA,eACA;IAEF,0BAA0B;IAC1B,+BAA+B,eAAe;IAC9C,mCAAmC,cAAc;IACjD,sBACE,cACA,kBACA;IAEF,uBAAuB,iBAAiB;IACxC,oBAAoB,eAAe;IACnC,uBAAuB,eAAe;IACtC,8BAA8B,mBAAmB;IACjD,0BAA0B;IAC1B,sBAAsB;IACtB,wBAAwB;;;;;EAM1B;IACE,kBAAkB,kBAAkB;IACpC,+BAA+B,oBAAoB;;;;;EAMrD;IACE,yBAAyB,eAAe;IACxC,4BACE,eACA,gBACA;IAEF,6BAA6B,eAAe;IAC5C,2BAA2B,cAAc;IACzC,0BAA0B,gBAAgB;IAC1C,oBAAoB;IACpB,gBAAgB,cAAc;IAC9B,qBAAqB,gBAAgB;IACrC,wBAAwB;;;;;EAM1B;IACE,sBAAsB,eAAe;IACrC,6BACE,kBACA;IAEF,qBAAqB;IACrB,0BAA0B;IAC1B,sBAAsB;IACtB,uBAAuB;IACvB,uBAAuB;;;;;EAMzB;IACE,kBAAkB,kBAAkB;IACpC,uBAAuB,eAAe;IACtC,0BAA0B,eAAe;IACzC,gBAAgB,cAAc,cAAc;IAC5C,qBAAqB,cAAc;;;;;EAMrC;IACE,uBAAuB;IACvB,gCAAgC;IAChC,8BAA8B;IAC9B,4BAA4B,kBAAkB;IAC9C,iBAAiB,iBAAiB;;;;;;;;IAQlC,sBAAsB,iBAAiB;;;;;;;;IAQvC,iBAAiB,iBAAiB;IAClC,oBAAoB;;;;;EAMtB;IACE,wBACE,eACA,iBACA;IAEF,6BACE,aACA,aACA;;;;;;;;;;;;IAaF,wBAAwB,mBAAmB;;IAG3C,2BAA2B,mBAAmB;;;;;EAMhD;IACE,uBAAuB,eAAe;IACtC,0BACE,eACA,mBACA"}
+{"version":3,"file":"RouterValidator.d.ts","names":[],"sources":["../../../src/types/RouterValidator.ts"],"mappings":";;;;;;;;;;;;;iBAaiB;;;;EAIf;IACE,wBAAwB,gBAAgB;IACxC,wBAAwB;IACxB,4BACE,eACA,iBACA,iBACA;IAEF,+BAA+B;IAC/B,2BACE,eACA,iBACA;IAEF,uBAAuB;;;;;;;IAOvB,iBAAiB,mBAAmB;IACpC,0BAA0B;IAC1B,+BAA+B,eAAe;IAC9C,mCAAmC,cAAc;;IAEjD,sBAAsB,cAAc;;;;;;IAMpC,uBAAuB;IACvB,oBAAoB,eAAe;IACnC,uBAAuB,eAAe;IACtC,8BAA8B,mBAAmB;IACjD,0BAA0B;IAC1B,sBAAsB;IACtB,wBAAwB;;;;;EAM1B;IACE,kBAAkB,kBAAkB;;IAEpC,+BAA+B;;;;;EAMjC;IACE,yBAAyB,eAAe;IACxC,4BACE,eACA,gBACA;IAEF,6BAA6B,eAAe;;;;;;IAM5C,2BAA2B,cAAc;;;;;;;;;;IAUzC,0BACE,sBACA,yBACA;IAEF,oBAAoB;IACpB,gBAAgB,cAAc;IAC9B,qBAAqB,gBAAgB;IACrC,wBAAwB;;;;;EAM1B;IACE,sBAAsB,eAAe;IACrC,6BACE,kBACA;IAEF,qBAAqB;IACrB,0BAA0B;IAC1B,sBAAsB;IACtB,uBAAuB;IACvB,uBAAuB;;;;;EAMzB;IACE,kBAAkB,kBAAkB;IACpC,uBAAuB,eAAe;IACtC,0BAA0B,eAAe;IACzC,gBAAgB,cAAc,cAAc;IAC5C,qBAAqB,cAAc;;;;;EAMrC;IACE,uBAAuB;IACvB,gCAAgC;IAChC,8BAA8B;IAC9B,4BAA4B,kBAAkB;IAC9C,iBAAiB,iBAAiB;;;;;;;;IAQlC,sBAAsB,iBAAiB;;;;;;;;IAQvC,iBAAiB,iBAAiB;IAClC,oBAAoB;;;;;EAMtB;IACE,wBACE,eACA,iBACA;IAEF,6BACE,aACA,aACA;;;;;;;;;;;;IAaF,wBAAwB,mBAAmB;;IAG3C,2BAA2B,mBAAmB;;;;;EAMhD;IACE,uBAAuB,eAAe;IACtC,0BACE,eACA,mBACA"}

package/dist/cjs/types/api.d.ts

@@ -1,4 +1,5 @@
 import { Params, SearchParams, SimpleState, State, Unsubscribe } from "./base.js";
+import { LimitsConfig } from "./limits.js";
 import { AdoptedOrigins, AnyOptions, DefaultDependencies, GuardFnFactory, Plugin, Route, RouteConfigUpdate, RouterLogger } from "./router.js";
 import { EventMethodMap, EventName } from "./constants.js";
 import { TreeChangedEvent } from "./tree-changed.js";
@@ -157,6 +158,52 @@ export interface PluginApi {
    * cannot grow the registry.
    */
   getDeclaredQueryNames: (name: string) => readonly string[];
+  /**
+   * The route's PATH slot names, ancestors included — the registry
+   * `buildPath` prints from. Answers `[]` for a route the tree does not hold;
+   * a name is not a claim that the route exists.
+   *
+   * ⚠ Handed out BY REFERENCE and frozen where it lives, with the same caveat as
+   * {@link getDeclaredQueryNames}: a held array describes the tree as it was
+   * when read, and a rebuild mints a new one (#2255).
+   */
+  getUrlParams: (name: string) => readonly string[];
+  /**
+   * The ONE-HOP forward map — each source route's STRING `forwardTo` target; a
+   * callback `forwardTo` is not in it — as a fresh frozen copy per call.
+   *
+   * ⚠ **One hop, not resolved.** A consumer that checks a PENDING forward for
+   * cycles overlays it onto this map and resolves the chain itself. A resolved
+   * map collapses each chain to its last hop, so a cycle closing through a
+   * source that ALREADY forwards is not constructible there, and the check
+   * would miss it silently. `resolveForwardChain` takes exactly this shape.
+   *
+   * ⚑ A copy, so writing to it reaches nothing — and frozen, so the write does
+   * not land either; strict-mode code (every ES module) gets a `TypeError`.
+   */
+  getForwardMap: () => Readonly<Record<string, string>>;
+  /**
+   * The resolved limits: the caller's `limits` over core's defaults, each
+   * coerced to a number once at construction. The frozen object core's own
+   * dependency-count check reads, handed out by reference.
+   */
+  getResolvedLimits: () => Readonly<LimitsConfig>;
+  /**
+   * The dependency names the router holds, as `Object.keys` lists them —
+   * `"__proto__"` included, a symbol key not. A fresh frozen array per call.
+   *
+   * ⚠ Not `Object.keys(getDependenciesApi(router).getAll())`: that container
+   * withholds `"__proto__"`, so a count taken from it comes out one short.
+   */
+  getDependencyKeys: () => readonly string[];
+  /**
+   * Route names carrying a guard added through `addActivateGuard` /
+   * `addDeactivateGuard` — deactivate first, each name once, including names
+   * the route tree does not hold. A fresh frozen array per call.
+   *
+   * ⚠ A guard declared on a route definition does not put its name here.
+   */
+  getExternalGuardNames: () => readonly string[];
   addEventListener: <E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]) => Unsubscribe;
   /**
    * Builds the State `navigate` would commit, without committing it: resolves

package/dist/cjs/types/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","names":[],"sources":["../../../src/types/api.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;iBA6CiB;EACf,QAAQ,kBAAkB,QAAQ;EAClC,eACE,mBACA,aAAa,QACb,cAAc,iBACX;;;;;;YAOK,cAAc,gBAAgB,2BACxC,MAAM,uBAAuB,OAC1B,MAAM,WAAW,uBAAuB,QACxC,WAAW,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwCtB,sBAAsB;EACrC,QAAQ,OAAO,OAAO,OAAO;EAC7B;;;;;;iBAOe;EACf,YAAY,UAAU,SAAS,QAAQ,UAAU,eAAe,cAC9D,cACA,SAAS,GACT,SAAS,GACT,kBACG,MAAM,GAAG;EAEd,eACE,UAAU,SAAS,QACnB,UAAU,eAAe,cAEzB,mBACA,aAAa,GACb,cAAc,MACX,YAAY,GAAG;EAEpB,YAAY,UAAU,SAAS,QAAQ,iBAAiB,MAAM;;;;;;;;;;;EAY9D,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCzB,kBACE,OAAO,OACP,UAAU,sBACP,QAAQ;;;;;;;EAQb,cAAc;EACd;;;;;;;;;EAUA,QAAQ;;;;;;;;;;;;;;;;EAiBR,wBAAwB;EAExB,mBAAmB,UAAU,WAC3B,WAAW,GACX,IAAI,OAAO,eAAe,QACvB;;;;;;;;;;;;EAaL,uBACE,cACA,SAAS,QACT,SAAS,iBACN;;;;;;;;;;;;;;;;EAiBL,oBACE,cACA,SAAS,QACT,SAAS;EAGX,kBAAkB;EAElB;EAEA,iBAAiB,gBAAgB,wBAC/B,QAAQ,GACR,IAAI,cAAc,OACf;EAEL,eAAe,YAAY,4BAA4B;;;;;;;;;;;;;;;EAgBvD,sBAAsB,OAAO;EAE7B;KAEG,gBAAgB,uBACf,WAAW,IACV,sBAAsB,aAAa;KACrC,oBAAoB;;;;;;;;;;;;;;;;;;;EAoBvB,iBAAiB,iBAAiB;;;;;iBAMnB,UACf,qBAAqB,sBAAsB;EAE3C,MACE,QAAQ,MAAM,kBAAkB,MAAM,eACtC;IAAY;;EAGd,SAAS;;;;;;;;;;;EAYT,SAAS,cAAc,SAAS,kBAAkB;EAElD;EAEA,UAAU,QAAQ,MAAM,kBAAkB,MAAM;EAEhD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BN,MAAM,iBAAiB,MAAM;;;;;;;;;;;;;EAc7B,mBACE,UAAU,OAAO,iBAAiB,2BAC/B;;;;;iBAMU,gBACf,qBAAqB,sBAAsB;EAE3C,MAAM,gBAAgB,cAAc,KAAK,MAAM,aAAa;EAC5D,cAAc,QAAQ;EACtB,MAAM,gBAAgB,uBACpB,MAAM,GACN,OAAO,aAAa;EAEtB,SAAS,MAAM;EACf,SAAS,YAAY;EACrB;EACA,MAAM,YAAY;;;;;iBAMH,aACf,qBAAqB,sBAAsB;EAE3C,mBACE,cACA,oBAAoB,eAAe;EAErC,qBACE,cACA,sBAAsB,eAAe;EAEvC,sBAAsB;EACtB,wBAAwB"}
+{"version":3,"file":"api.d.ts","names":[],"sources":["../../../src/types/api.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;iBA8CiB;EACf,QAAQ,kBAAkB,QAAQ;EAClC,eACE,mBACA,aAAa,QACb,cAAc,iBACX;;;;;;YAOK,cAAc,gBAAgB,2BACxC,MAAM,uBAAuB,OAC1B,MAAM,WAAW,uBAAuB,QACxC,WAAW,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwCtB,sBAAsB;EACrC,QAAQ,OAAO,OAAO,OAAO;EAC7B;;;;;;iBAOe;EACf,YAAY,UAAU,SAAS,QAAQ,UAAU,eAAe,cAC9D,cACA,SAAS,GACT,SAAS,GACT,kBACG,MAAM,GAAG;EAEd,eACE,UAAU,SAAS,QACnB,UAAU,eAAe,cAEzB,mBACA,aAAa,GACb,cAAc,MACX,YAAY,GAAG;EAEpB,YAAY,UAAU,SAAS,QAAQ,iBAAiB,MAAM;;;;;;;;;;;EAY9D,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkCzB,kBACE,OAAO,OACP,UAAU,sBACP,QAAQ;;;;;;;EAQb,cAAc;EACd;;;;;;;;;EAUA,QAAQ;;;;;;;;;;;;;;;;EAiBR,wBAAwB;;;;;;;;;;EAWxB,eAAe;;;;;;;;;;;;;;EAef,qBAAqB,SAAS;;;;;;EAO9B,yBAAyB,SAAS;;;;;;;;EASlC;;;;;;;;EASA;EAEA,mBAAmB,UAAU,WAC3B,WAAW,GACX,IAAI,OAAO,eAAe,QACvB;;;;;;;;;;;;EAaL,uBACE,cACA,SAAS,QACT,SAAS,iBACN;;;;;;;;;;;;;;;;EAiBL,oBACE,cACA,SAAS,QACT,SAAS;EAGX,kBAAkB;EAElB;EAEA,iBAAiB,gBAAgB,wBAC/B,QAAQ,GACR,IAAI,cAAc,OACf;EAEL,eAAe,YAAY,4BAA4B;;;;;;;;;;;;;;;EAgBvD,sBAAsB,OAAO;EAE7B;KAEG,gBAAgB,uBACf,WAAW,IACV,sBAAsB,aAAa;KACrC,oBAAoB;;;;;;;;;;;;;;;;;;;EAoBvB,iBAAiB,iBAAiB;;;;;iBAMnB,UACf,qBAAqB,sBAAsB;EAE3C,MACE,QAAQ,MAAM,kBAAkB,MAAM,eACtC;IAAY;;EAGd,SAAS;;;;;;;;;;;EAYT,SAAS,cAAc,SAAS,kBAAkB;EAElD;EAEA,UAAU,QAAQ,MAAM,kBAAkB,MAAM;EAEhD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BN,MAAM,iBAAiB,MAAM;;;;;;;;;;;;;EAc7B,mBACE,UAAU,OAAO,iBAAiB,2BAC/B;;;;;iBAMU,gBACf,qBAAqB,sBAAsB;EAE3C,MAAM,gBAAgB,cAAc,KAAK,MAAM,aAAa;EAC5D,cAAc,QAAQ;EACtB,MAAM,gBAAgB,uBACpB,MAAM,GACN,OAAO,aAAa;EAEtB,SAAS,MAAM;EACf,SAAS,YAAY;EACrB;EACA,MAAM,YAAY;;;;;iBAMH,aACf,qBAAqB,sBAAsB;EAE3C,mBACE,cACA,oBAAoB,eAAe;EAErC,qBACE,cACA,sBAAsB,eAAe;EAEvC,sBAAsB;EACtB,wBAAwB"}