Type improvements

tolyo · tolyo · commit f28f0e121d3a · 2025-12-15T23:24:01.000+02:00
diff --git a/@types/router/state/interface.d.ts b/@types/router/state/interface.d.ts
@@ -14,7 +14,9 @@ import {
 } from "../resolve/interface.ts";
 import { Resolvable } from "../resolve/resolvable.js";
 import { TargetState } from "./target-state.js";
+import { Glob } from "../glob/glob.js";
 export type StateOrName = string | StateDeclaration | StateObject;
+export type StateStore = Record<string, StateObject | BuiltStateDeclaration>;
 export interface TransitionPromise extends Promise<StateObject> {
   transition: Transition;
 }
@@ -826,6 +828,9 @@ export type BuiltStateDeclaration = StateDeclaration & {
   parent?: BuiltStateDeclaration | null;
   /** Optional inherited data */
   data?: any;
+  _stateObjectCache?: {
+    nameGlob: Glob;
+  } | null;
 };
 /**
  * The return type of a [[StateDeclaration.lazyLoad]] function
diff --git a/@types/router/state/state-builder.d.ts b/@types/router/state/state-builder.d.ts
@@ -58,18 +58,22 @@ export function resolvablesBuilder(
 export class StateBuilder {
   /**
    * @param {import('./state-matcher.js').StateMatcher} matcher
-   * @param urlService
+   * @param {ng.UrlService} urlService
    */
   constructor(
     matcher: import("./state-matcher.js").StateMatcher,
-    urlService: any,
+    urlService: ng.UrlService,
   );
   matcher: import("./state-matcher.js").StateMatcher;
   $injector: any;
   builders: {
     name: ((state: any) => any)[];
     self: (typeof selfBuilder)[];
-    parent: ((state: any) => any)[];
+    parent: ((
+      state: any,
+    ) =>
+      | import("./state-object.js").StateObject
+      | import("./interface.ts").BuiltStateDeclaration)[];
     data: (typeof dataBuilder)[];
     url: ((stateObject: any) => any)[];
     navigable: ((state: any) => any)[];
diff --git a/@types/router/state/state-matcher.d.ts b/@types/router/state/state-matcher.d.ts
@@ -1,7 +1,15 @@
 export class StateMatcher {
-  constructor(_states: any);
-  _states: any;
+  /** @param {import("./interface.ts").StateStore} states */
+  constructor(states: import("./interface.ts").StateStore);
+  /** @type {import("./interface.ts").StateStore} */
+  _states: import("./interface.ts").StateStore;
   isRelative(stateName: any): boolean;
-  find(stateOrName: any, base: any, matchGlob?: boolean): any;
+  find(
+    stateOrName: any,
+    base: any,
+    matchGlob?: boolean,
+  ):
+    | import("./state-object.js").StateObject
+    | import("./interface.ts").BuiltStateDeclaration;
   resolvePath(name: any, base: any): string;
 }
diff --git a/@types/router/state/state-object.d.ts b/@types/router/state/state-object.d.ts
@@ -26,7 +26,7 @@ export class StateObject implements ng.StateDeclaration {
    * @type {ng.StateDeclaration|ng.BuiltStateDeclaration}
    */
   self: ng.StateDeclaration | ng.BuiltStateDeclaration;
-  __stateObjectCache: {
+  _stateObjectCache: {
     nameGlob: Glob;
   };
   /**
diff --git a/@types/router/state/state-queue-manager.d.ts b/@types/router/state/state-queue-manager.d.ts
@@ -2,29 +2,29 @@ export class StateQueueManager {
   /**
    * @param {import("./state-registry.js").StateRegistryProvider} stateRegistry
    * @param {import("../url/url-rules.js").UrlRules} urlServiceRules
-   * @param {Record<string, ng.StateObject>} states
+   * @param {import("./interface.js").StateStore} states
    * @param {*} builder
    * @param {*} listeners
    */
   constructor(
     stateRegistry: import("./state-registry.js").StateRegistryProvider,
     urlServiceRules: import("../url/url-rules.js").UrlRules,
-    states: Record<string, ng.StateObject>,
+    states: import("./interface.js").StateStore,
     builder: any,
     listeners: any,
   );
   stateRegistry: import("./state-registry.js").StateRegistryProvider;
   /** @type {import("../url/url-rules.js").UrlRules} */
   urlServiceRules: import("../url/url-rules.js").UrlRules;
-  states: Record<string, StateObject>;
+  states: import("./interface.js").StateStore;
   builder: any;
   listeners: any;
   /**
    * @type {Array<StateObject>}
    */
   queue: Array<StateObject>;
   register(stateDecl: any): StateObject;
-  flush(): Record<string, StateObject>;
+  flush(): import("./interface.js").StateStore;
   /**
    *
    * @param {ng.StateDeclaration} state
diff --git a/@types/router/state/state-registry.d.ts b/@types/router/state/state-registry.d.ts
@@ -19,8 +19,8 @@ export class StateRegistryProvider {
     globals: ng.RouterService,
     viewService: ng.ViewService,
   );
-  /** @type {Record<string, import("./state-object.js").StateObject>} */
-  states: Record<string, import("./state-object.js").StateObject>;
+  /** @type {import("./interface.ts").StateStore} */
+  states: import("./interface.ts").StateStore;
   urlService: import("../url/url-service.js").UrlService;
   urlServiceRules: import("../url/url-rules.js").UrlRules;
   $injector: any;
@@ -115,7 +115,16 @@ export class StateRegistryProvider {
    * @return {ng.BuiltStateDeclaration[]}
    */
   getAll(): ng.BuiltStateDeclaration[];
-  get(stateOrName: any, base: any, ...args: any[]): any;
+  get(
+    stateOrName: any,
+    base: any,
+    ...args: any[]
+  ):
+    | import("./interface.ts").StateDeclaration
+    | (
+        | import("./interface.ts").StateDeclaration
+        | import("./interface.ts").BuiltStateDeclaration
+      )[];
   /**
    * Registers a [[BuilderFunction]] for a specific [[StateObject]] property (e.g., `parent`, `url`, or `path`).
    * More than one BuilderFunction can be registered for a given property.
diff --git a/@types/router/url/url-service.d.ts b/@types/router/url/url-service.d.ts
@@ -24,16 +24,17 @@ export class UrlService {
   _urlRuleFactory: UrlRuleFactory;
   /**
    * The nested [[UrlRules]] API for managing URL rules and rewrites
+   * @ignore
    * @type {UrlRules}
    */
-  rules: UrlRules;
+  _rules: UrlRules;
   /**
    * The nested [[UrlConfig]] API to configure the URL and retrieve URL information
    * @type {import("./url-config.js").UrlConfigProvider}
    */
-  config: import("./url-config.js").UrlConfigProvider;
-  /** Creates a new [[Param]] for a given location (DefType) */
-  paramFactory: ParamFactory;
+  _config: import("./url-config.js").UrlConfigProvider;
+  /** @type {ParamFactory} Creates a new [[Param]] for a given location (DefType) */
+  _paramFactory: ParamFactory;
   _urlListeners: any[];
   /**
    * Gets the path part of the current url
diff --git a/src/router/state/interface.ts b/src/router/state/interface.ts
@@ -14,9 +14,12 @@ import {
 } from "../resolve/interface.ts";
 import { Resolvable } from "../resolve/resolvable.js";
 import { TargetState } from "./target-state.js";
+import { Glob } from "../glob/glob.js";
 
 export type StateOrName = string | StateDeclaration | StateObject;
 
+export type StateStore = Record<string, StateObject | BuiltStateDeclaration>;
+
 export interface TransitionPromise extends Promise<StateObject> {
   transition: Transition;
 }
@@ -1001,6 +1004,8 @@ export type BuiltStateDeclaration = StateDeclaration & {
 
   /** Optional inherited data */
   data?: any;
+
+  _stateObjectCache?: { nameGlob: Glob } | null;
 };
 
 /**
diff --git a/src/router/state/state-builder.js b/src/router/state/state-builder.js
@@ -299,7 +299,7 @@ export function resolvablesBuilder(state) {
 export class StateBuilder {
   /**
    * @param {import('./state-matcher.js').StateMatcher} matcher
-   * @param urlService
+   * @param {ng.UrlService} urlService
    */
   constructor(matcher, urlService) {
     this.matcher = matcher;
@@ -323,7 +323,7 @@ export class StateBuilder {
       // Keep track of the closest ancestor state that has a URL (i.e. is navigable)
       navigable: [getNavigableBuilder(isRoot)],
       // TODO
-      params: [getParamsBuilder(urlService.paramFactory)],
+      params: [getParamsBuilder(urlService._paramFactory)],
       // Each framework-specific ng-router implementation should define its own `views` builder
       // e.g., src/ng1/statebuilders/views.ts
       views: [],
diff --git a/src/router/state/state-matcher.js b/src/router/state/state-matcher.js
@@ -1,7 +1,9 @@
 import { isString } from "../../shared/utils.js";
 export class StateMatcher {
-  constructor(_states) {
-    this._states = _states;
+  /** @param {import("./interface.ts").StateStore} states */
+  constructor(states) {
+    /** @type {import("./interface.ts").StateStore} */
+    this._states = states;
   }
 
   isRelative(stateName) {
@@ -26,12 +28,12 @@ export class StateMatcher {
     ) {
       return state;
     } else if (isStr && matchGlob) {
-      const _states = Object.values(this._states);
+      const states = Object.values(this._states);
 
-      const matches = _states.filter(
-        (_state) =>
-          _state.__stateObjectCache.nameGlob &&
-          _state.__stateObjectCache.nameGlob.matches(name),
+      const matches = states.filter(
+        (stateObj) =>
+          stateObj._stateObjectCache.nameGlob &&
+          stateObj._stateObjectCache.nameGlob.matches(name),
       );
 
       if (matches.length > 1) {
diff --git a/src/router/state/state-object.js b/src/router/state/state-object.js
@@ -40,7 +40,7 @@ export class StateObject {
      */
     const nameGlob = this.name ? Glob.fromString(this.name) : null;
 
-    this.__stateObjectCache = { nameGlob };
+    this._stateObjectCache = { nameGlob };
   }
 
   /**
@@ -122,4 +122,4 @@ export class StateObject {
 /** Predicate which returns true if the object is a [[StateDeclaration]] object */
 StateObject.isStateDeclaration = (obj) => isFunction(obj.$$state);
 /** Predicate which returns true if the object is an internal [[StateObject]] object */
-StateObject.isState = (obj) => isObject(obj.__stateObjectCache);
+StateObject.isState = (obj) => isObject(obj._stateObjectCache);
diff --git a/src/router/state/state-queue-manager.js b/src/router/state/state-queue-manager.js
@@ -5,7 +5,7 @@ export class StateQueueManager {
   /**
    * @param {import("./state-registry.js").StateRegistryProvider} stateRegistry
    * @param {import("../url/url-rules.js").UrlRules} urlServiceRules
-   * @param {Record<string, ng.StateObject>} states
+   * @param {import("./interface.js").StateStore} states
    * @param {*} builder
    * @param {*} listeners
    */
diff --git a/src/router/state/state-registry.js b/src/router/state/state-registry.js
@@ -30,12 +30,12 @@ export class StateRegistryProvider {
    * @param {ng.ViewService} viewService
    */
   constructor(urlService, stateService, globals, viewService) {
-    /** @type {Record<string, import("./state-object.js").StateObject>} */
+    /** @type {import("./interface.ts").StateStore} */
     this.states = {};
 
     stateService.stateRegistry = this; // <- circular wiring
     this.urlService = urlService;
-    this.urlServiceRules = urlService.rules;
+    this.urlServiceRules = urlService._rules;
     this.$injector = undefined;
     this.listeners = [];
     this.matcher = new StateMatcher(this.states);
@@ -196,7 +196,7 @@ export class StateRegistryProvider {
   }
 
   _deregisterTree(state) {
-    const all = this.get().map((x) => x.$$state());
+    const all = this.getAll().map((x) => x.$$state());
 
     const getChildren = (states) => {
       const _children = all.filter((x) => states.indexOf(x.parent) !== -1);
@@ -235,11 +235,18 @@ export class StateRegistryProvider {
    * @returns {import('./state-object').StateObject[]} a list of removed states
    */
   deregister(stateOrName) {
-    const _state = this.get(stateOrName);
+    const state =
+      /** @type {import("./interface.ts").BuiltStateDeclaration} */ (
+        this.get(stateOrName)
+      );
 
-    if (!_state)
+    if (!state)
       throw new Error(`Can't deregister state; not found: ${stateOrName}`);
-    const deregisteredStates = this._deregisterTree(_state.$$state());
+    const deregisteredStates = this._deregisterTree(
+      /** @type {import("./interface.ts").BuiltStateDeclaration} */ (
+        state
+      ).$$state(),
+    );
 
     this.listeners.forEach((listener) =>
       listener(
diff --git a/src/router/url/url-service.js b/src/router/url/url-service.js
@@ -47,17 +47,18 @@ export class UrlService {
 
     /**
      * The nested [[UrlRules]] API for managing URL rules and rewrites
+     * @ignore
      * @type {UrlRules}
      */
-    this.rules = new UrlRules(this._urlRuleFactory);
+    this._rules = new UrlRules(this._urlRuleFactory);
     /**
      * The nested [[UrlConfig]] API to configure the URL and retrieve URL information
      * @type {import("./url-config.js").UrlConfigProvider}
      */
-    this.config = urlConfigProvider;
+    this._config = urlConfigProvider;
 
-    /** Creates a new [[Param]] for a given location (DefType) */
-    this.paramFactory = new ParamFactory(this.config);
+    /** @type {ParamFactory} Creates a new [[Param]] for a given location (DefType) */
+    this._paramFactory = new ParamFactory(this._config);
 
     this._urlListeners = [];
   }
@@ -319,7 +320,7 @@ export class UrlService {
    */
   match(url) {
     url = Object.assign({ path: "", search: {}, hash: "" }, url);
-    const rules = this.rules.rules();
+    const rules = this._rules.rules();
 
     // Checks a single rule. Returns { rule: rule, match: match, weight: weight } if it matched, or undefined
     /**
@@ -430,7 +431,7 @@ export class UrlService {
    * @returns The UrlMatcher.
    */
   compile(urlPattern, config) {
-    const urlConfig = this.config;
+    const urlConfig = this._config;
 
     // backward-compatible support for config.params -> config.state.params
     const params = config && !config.state && config.params;
@@ -444,7 +445,7 @@ export class UrlService {
     return new UrlMatcher(
       urlPattern,
       urlConfig.paramTypes,
-      this.paramFactory,
+      this._paramFactory,
       Object.assign(globalConfig, config),
     );
   }
diff --git a/src/router/url/url-service.spec.js b/src/router/url/url-service.spec.js
@@ -28,16 +28,16 @@ describe("UrlMatcher", () => {
 
   describe("provider", () => {
     it("should factory matchers with correct configuration", () => {
-      $url.config.caseInsensitive(false);
+      $url._config.caseInsensitive(false);
       expect($url.compile("/hello").exec("/HELLO")).toBeNull();
 
-      $url.config.caseInsensitive(true);
+      $url._config.caseInsensitive(true);
       expect($url.compile("/hello").exec("/HELLO")).toEqual({});
 
-      $url.config.strictMode(true);
+      $url._config.strictMode(true);
       expect($url.compile("/hello").exec("/hello/")).toBeNull();
 
-      $url.config.strictMode(false);
+      $url._config.strictMode(false);
       expect($url.compile("/hello").exec("/hello/")).toEqual({});
     });
 
@@ -328,23 +328,23 @@ describe("UrlMatcher", () => {
 
     it("should respect $urlProvider.strictMode", () => {
       let m = $url.compile("/");
-      $url.config.strictMode(false);
+      $url._config.strictMode(false);
       m = m.append($url.compile("foo"));
       expect(m.exec("/foo")).toEqual({});
       expect(m.exec("/foo/")).toEqual({});
     });
 
     it("should respect $urlProvider.caseInsensitive", () => {
       let m = $url.compile("/");
-      $url.config.caseInsensitive(true);
+      $url._config.caseInsensitive(true);
       m = m.append($url.compile("foo"));
       expect(m.exec("/foo")).toEqual({});
       expect(m.exec("/FOO")).toEqual({});
     });
 
     it("should respect $urlProvider.caseInsensitive when validating regex params", () => {
       let m = $url.compile("/");
-      $url.config.caseInsensitive(true);
+      $url._config.caseInsensitive(true);
       m = m.append($url.compile("foo/{param:bar}"));
       expect(m.validates({ param: "BAR" })).toEqual(true);
     });
