@avstantso/react-router-utils 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.2.1] - 2026-02-07
+
+### Changed
+
+- Updated README with comprehensive documentation for `AT` methods
+- Updated README with documentation for RouteCreator callback syntax
+- **RouteCreator callback syntax**: Nested routes now automatically use relative paths (`type='name'`), ensuring valid react-router nested route structures
+- RouteCreator callback syntax is now stable (no longer experimental)
+
+### Performance
+
+- RouteCreator: Added WeakMap caching for nested trees, improving performance when callbacks are invoked multiple times on the same route
+
+## [0.2.0] - 2026-02-05
+
+### Added
+
+- `AT` methods for `isUrl`, `isSubUrl`, `Links`, `NavLinks`, `Navigates` and `Navigates.useNavigate()`
+- New types internal structure based on `TypeMap`
+- RouteCreator: +`makeRouteObjectCallback` experimental overload
+
 ## [0.1.2] - 2026-02-05
 
 ### Fixed

package/README.md

@@ -174,6 +174,35 @@ Each link component has an `id` property derived from the route path, useful for
 console.log(Links.Profile.Settings.id); // HTML-safe id derived from "profile/settings"
 ```
 
+### AT Method (Direct Node Access)
+
+The `AT` method provides direct access to any node in the tree by passing a URL tree node reference. This is useful when you need to dynamically select routes or work with node references:
+
+```tsx
+const { Links, NavLinks } = ReactRouterTree(urlsTree);
+
+// Access a specific node directly
+const AboutLink = Links.AT(urlsTree.about);
+<AboutLink>About</AboutLink>
+
+// Access nested nodes
+const SettingsLink = Links.AT(urlsTree.profile.settings);
+<SettingsLink>Settings</SettingsLink>
+
+// Access parameterized nodes
+const UserLink = Links.AT(urlsTree.profile[':userId']);
+<UserLink params={{ userId: '42' }}>User</UserLink>
+
+// The returned node preserves its children
+const ProfileNode = Links.AT(urlsTree.profile);
+<ProfileNode.Settings>Settings</ProfileNode.Settings>
+<ProfileNode.$UserId params={{ userId: '99' }}>User</ProfileNode.$UserId>
+
+// Works the same for NavLinks
+const AboutNavLink = NavLinks.AT(urlsTree.about);
+<AboutNavLink>About</AboutNavLink>
+```
+
 ---
 
 ## Navigates
@@ -212,6 +241,27 @@ The `preserve` prop saves the current `search` and `hash` when redirecting:
 <Navigates.About preserve />
 ```
 
+#### AT Method (Direct Node Access)
+
+The `AT` method provides direct access to navigate components by node reference:
+
+```tsx
+const { Navigates } = ReactRouterTree(urlsTree);
+
+// Access a specific node directly
+const AboutNav = Navigates.AT(urlsTree.about);
+<AboutNav />
+
+// Access nested nodes
+const SettingsNav = Navigates.AT(urlsTree.profile.settings);
+<SettingsNav />
+
+// The returned node preserves its children
+const ProfileNav = Navigates.AT(urlsTree.profile);
+<ProfileNav.Settings />
+<ProfileNav.$UserId params={{ userId: '42' }} />
+```
+
 ### useNavigate Hook
 
 A proxy-enhanced `useNavigate` hook that provides the same tree-based navigation as the components, but as callable functions.
@@ -257,6 +307,35 @@ function MyComponent() {
 }
 ```
 
+#### AT Method (Direct Node Access)
+
+The `AT` method works with the `useNavigate` hook as well, allowing navigation by node reference:
+
+```tsx
+function MyComponent() {
+  const nav = Navigates.useNavigate();
+
+  return (
+    <div>
+      {/* Navigate using direct node access */}
+      <button onClick={() => nav.AT(urlsTree.about)()}>
+        Go to About
+      </button>
+
+      {/* With params */}
+      <button onClick={() => nav.AT(urlsTree.profile[':userId'])({ userId: '42' })}>
+        Go to User 42
+      </button>
+
+      {/* The returned node preserves its children */}
+      <button onClick={() => nav.AT(urlsTree.profile).Settings()}>
+        Go to Profile Settings
+      </button>
+    </div>
+  );
+}
+```
+
 ---
 
 ## isUrl & isSubUrl
@@ -324,6 +403,29 @@ isSubUrl.Profile('/about');                   // false
 isSubUrl.Home('/anything');                   // true
 ```
 
+### AT Method (Direct Node Access)
+
+Both `isUrl` and `isSubUrl` support the `AT` method for direct node access:
+
+```typescript
+const { isUrl, isSubUrl } = ReactRouterTree(urlsTree);
+
+// Access nodes directly
+isUrl.AT(urlsTree.about)('/about');                       // true
+isUrl.AT(urlsTree.profile.settings)('/profile/settings'); // true
+isUrl.AT(urlsTree.profile[':userId'])('/profile/123');    // true
+
+// The returned function preserves children
+const profile = isUrl.AT(urlsTree.profile);
+profile.Settings('/profile/settings');                    // true
+profile.$UserId('/profile/123');                          // true
+profile.$UserId.Posts('/profile/42/posts');               // true
+
+// Works the same for isSubUrl
+isSubUrl.AT(urlsTree.profile)('/profile');                // true
+isSubUrl.AT(urlsTree.profile)('/profile/settings');       // true
+```
+
 ---
 
 ## RouteCreator
@@ -386,6 +488,72 @@ route2.About({ element: <AboutPage /> });
 // { element: <AboutPage />, path: '/about' }
 ```
 
+### Callback Syntax
+
+RouteCreator supports a callback syntax for defining nested children routes. When using callbacks, **nested routes automatically use relative paths** (equivalent to `type='name'`), regardless of the parent's type setting.
+
+```typescript
+const route = RouteCreator('name');
+
+const profileRoute = route.Profile((RouteCreator) => ({
+  element: <ProfilePage />,
+  children: [
+    RouteCreator[':userId']((RouteCreator) => ({
+      element: <UserPage />,
+      children: [
+        RouteCreator.Posts({
+          element: <PostsPage />
+        })
+      ]
+    }))
+  ]
+}));
+
+// Produces:
+// {
+//   path: 'profile',
+//   element: <ProfilePage />,
+//   children: [
+//     {
+//       path: ':userId',
+//       element: <UserPage />,
+//       children: [
+//         { path: 'posts', element: <PostsPage /> }
+//       ]
+//     }
+//   ]
+// }
+```
+
+#### Mixing Types
+
+The parent route respects the `type` parameter, but children always use relative paths:
+
+```typescript
+const route = RouteCreator('url');
+
+const profileRoute = route.Profile((RouteCreator) => ({
+  element: <ProfilePage />,
+  children: [
+    RouteCreator.Settings({ element: <SettingsPage /> })
+  ]
+}));
+
+// Produces:
+// {
+//   path: '/profile',        // Parent uses 'url' type
+//   element: <ProfilePage />,
+//   children: [
+//     {
+//       path: 'settings',    // Child forced to relative path
+//       element: <SettingsPage />
+//     }
+//   ]
+// }
+```
+
+This ensures nested routes are always valid for react-router's nested route structure.
+
 ---
 
 ## Type Definitions

package/dist/core/binded-path.d.ts

@@ -5,6 +5,7 @@ export type BindProps<T extends {
     to?: To;
 }> = TS.ReplaceKeyOpt<'to', T, Partial<BindedPath>>;
 export declare function resolveParams(url: string, params?: object): string;
+export declare function Parts(url: string): string[];
 export declare function BindProps<P extends string, T extends {
     to?: To;
 }>(pathname: P, props: {

package/dist/impl/is-url.d.ts

@@ -1,2 +1,2 @@
-import type * as Types from '../types';
-export declare function IsUrlTreeFactory<TTree extends Types.UrlsTree>(urlsTree: TTree): Types.IsUrlTree.Methods<TTree>;
+import type { UrlsTree, IsUrlTree } from '../types';
+export declare function IsUrlTreeFactory<TTree extends UrlsTree>(urlsTree: TTree): IsUrlTree.Methods<TTree>;

package/dist/impl/links.d.ts

@@ -1,2 +1,2 @@
-import type * as Types from '../types';
-export declare function LinksFactory<TTree extends Types.UrlsTree>(urlsTree: TTree): Types.LinksTree.Set<TTree>;
+import type { UrlsTree, LinksTree } from '../types';
+export declare function LinksFactory<TTree extends UrlsTree>(urlsTree: TTree): LinksTree.Set<TTree>;

package/dist/impl/navigates.d.ts

@@ -1,2 +1,2 @@
-import type * as Types from '../types';
-export declare function NavigatesTreeFactory<TTree extends Types.UrlsTree>(urlsTree: TTree): Types.NavigatesTree<TTree>;
+import type { UrlsTree, NavigatesTree } from '../types';
+export declare function NavigatesTreeFactory<TTree extends UrlsTree>(urlsTree: TTree): NavigatesTree<TTree>;

package/dist/impl/tree-factory.d.ts

@@ -11,3 +11,4 @@ export declare namespace TreeFactory {
     };
 }
 export declare function TreeFactory<TTree extends UrlsTree, O extends TreeFactory.Options>(urlsTree: TTree, options: O): object | Function;
+export declare function TreeAT(tree: any, node: UrlsTree.Node): any;

package/dist/index.js

@@ -5,6 +5,30 @@ var utilsMisc = require('@avstantso/utils-misc');
 var require$$0 = require('react');
 var reactRouterDom = require('react-router-dom');
 
+var JS$4 = AVStantso.JS;
+const PARAMS_REPLACE_REGEXP = /:([^/]+)($|\/)/g;
+function resolveParams(url, params) {
+    return !params
+        ? url
+        : url.replace(PARAMS_REPLACE_REGEXP, (m, g, trail) => {
+            return `${g in params ? `${params[g]}` : `:${g}`}${trail}`;
+        });
+}
+function Parts(url) {
+    return url.split('/').pack();
+}
+function BindProps(pathname, props, params) {
+    const { to: outerTo, ...rest } = props;
+    const pn = resolveParams(pathname, params);
+    const to = !outerTo || JS$4.is.string(outerTo)
+        ? pn
+        : {
+            ...outerTo,
+            pathname: pn
+        };
+    return Object.assign(rest, { to });
+}
+
 var JS$3 = AVStantso.JS;
 var Func = AVStantso.Func;
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-function-type */
@@ -38,10 +62,19 @@ function recursiveCreateCmpByRoute(node, options, level = 0) {
 function TreeFactory(urlsTree, options) {
     return recursiveCreateCmpByRoute(urlsTree, options);
 }
+function TreeAT(tree, node) {
+    let current = tree;
+    for (const part of Parts(node._url))
+        current = current[part.startsWith(':')
+            ? PP$Camel.paramProcessor(part)
+            : utilsMisc.Cases.pascal(part)];
+    return current;
+}
 
 var JS$2 = AVStantso.JS;
 function CheckUrlFactory(urlsTree, callback) {
-    return TreeFactory(urlsTree, {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const tree = TreeFactory(urlsTree, {
         nodeFactory: (node) => (pathnameOrLocation, params) => {
             const pathname = JS$2.is.string(pathnameOrLocation)
                 ? pathnameOrLocation
@@ -50,9 +83,8 @@ function CheckUrlFactory(urlsTree, callback) {
         },
         ...PP$Camel
     });
-}
-function Parts(url) {
-    return url.split('/').pack();
+    tree.AT = (node) => TreeAT(tree, node);
+    return tree;
 }
 function DoIsUrl(strictMatch) {
     return (node, pathname, params) => {
@@ -1449,29 +1481,9 @@ function requireJsxRuntime () {
 
 var jsxRuntimeExports = requireJsxRuntime();
 
-var JS$1 = AVStantso.JS;
-const PARAMS_REPLACE_REGEXP = /:([^/]+)($|\/)/g;
-function resolveParams(url, params) {
-    return !params
-        ? url
-        : url.replace(PARAMS_REPLACE_REGEXP, (m, g, trail) => {
-            return `${g in params ? `${params[g]}` : `:${g}`}${trail}`;
-        });
-}
-function BindProps(pathname, props, params) {
-    const { to: outerTo, ...rest } = props;
-    const pn = resolveParams(pathname, params);
-    const to = !outerTo || JS$1.is.string(outerTo)
-        ? pn
-        : {
-            ...outerTo,
-            pathname: pn
-        };
-    return Object.assign(rest, { to });
-}
-
 function LinksKindFactory(urlsTree, Component) {
-    return TreeFactory(urlsTree, {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const tree = TreeFactory(urlsTree, {
         nodeFactory(node) {
             const id = utilsMisc.HTMLUtils.str2ValidId(node._path);
             return Object.assign(function BindedLink({ id: outerId, params, ...rest }) {
@@ -1480,6 +1492,8 @@ function LinksKindFactory(urlsTree, Component) {
         },
         ...PP$Camel
     });
+    tree.AT = (node) => TreeAT(tree, node);
+    return tree;
 }
 function LinksFactory(urlsTree) {
     return {
@@ -1488,9 +1502,10 @@ function LinksFactory(urlsTree) {
     };
 }
 
-var JS = AVStantso.JS;
+var JS$1 = AVStantso.JS;
 function NavigatesTreeFactory(urlsTree) {
-    return Object.assign(TreeFactory(urlsTree, {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const componentTree = TreeFactory(urlsTree, {
         nodeFactory(node) {
             /**
              * @avstantso: Reimplementation `Navigate` with `preserve`
@@ -1511,18 +1526,25 @@ function NavigatesTreeFactory(urlsTree) {
             return BindedNavigates;
         },
         ...PP$Camel
-    }), {
+    });
+    componentTree.AT = (node) => TreeAT(componentTree, node);
+    return Object.assign(componentTree, {
         useNavigate() {
             const navigate = reactRouterDom.useNavigate();
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             function createNavProxy(node, hasParams) {
                 return new Proxy(navigate, {
                     get(target, p) {
+                        if ('AT' === p)
+                            return (atNode) => {
+                                const hp = atNode._url.split('/').some((s) => s.startsWith(':'));
+                                return createNavProxy(atNode, hp);
+                            };
                         const r = Reflect.get(target, p);
                         if (undefined !== r)
                             return r;
                         for (const [k, v] of Object.entries(node))
-                            if (JS.is.structure(v)) {
+                            if (JS$1.is.structure(v)) {
                                 const hp = k.startsWith(':');
                                 if (hp
                                     ? PP$Camel.paramProcessor(k) === p
@@ -1537,13 +1559,13 @@ function NavigatesTreeFactory(urlsTree) {
                         const i = hasParams ? 1 : 0;
                         const params = argArray[i - 1];
                         const pathname = resolveParams(node._url, params);
-                        const hasTo = JS.switch(argArray[i], {
+                        const hasTo = JS$1.switch(argArray[i], {
                             string: true,
                             object: (o) => 'search' in o || 'hash' in o
                         });
                         return Reflect.apply(target, thisArg, hasTo
                             ? [
-                                JS.is.object(argArray[i]) ? { ...argArray[i], pathname } : pathname,
+                                JS$1.is.object(argArray[i]) ? { ...argArray[i], pathname } : pathname,
                                 argArray[i + 1]
                             ]
                             : [
@@ -1558,12 +1580,34 @@ function NavigatesTreeFactory(urlsTree) {
     });
 }
 
-const RouteCreatorFactory = (urlsTree) => (type, commonProps) => TreeFactory(urlsTree, {
-    nodeFactory: (node) => function CMRouteCreate(props) {
-        return { ...commonProps, ...props, path: node[`_${type}`] };
-    }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-});
+var JS = AVStantso.JS;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const RouteCreatorFactory = (urlsTree) => (type, commonProps) => {
+    const nestedTreeCache = new WeakMap();
+    const MetaFactory = (useCache, nodeField = type) => (rootNode) => {
+        if (useCache) {
+            const cached = nestedTreeCache.get(rootNode);
+            if (cached)
+                return cached;
+        }
+        const tree = TreeFactory(rootNode, {
+            nodeFactory: (node) => {
+                const RouteCreate = (param) => ({
+                    ...commonProps,
+                    ...(JS.is.function(param) ? param(createNestedTree(node)) : param),
+                    path: node[`_${nodeField}`]
+                });
+                return RouteCreate;
+            }
+        });
+        if (useCache)
+            nestedTreeCache.set(rootNode, tree);
+        return tree;
+    };
+    const createNestedTree = MetaFactory(true, 'name');
+    const treeFactory = MetaFactory();
+    return treeFactory(urlsTree);
+};
 
 function ReactRouterTree(urlsTree) {
     return {