@real-router/lifecycle-plugin 0.2.1 → 0.4.0

package/README.md

@@ -5,18 +5,18 @@
 [![bundle size](https://deno.bundlejs.com/?q=@real-router/lifecycle-plugin&treeshake=[*]&badge=detailed)](https://bundlejs.com/?q=@real-router/lifecycle-plugin&treeshake=[*])
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](../../LICENSE)
 
-> Route-level lifecycle hooks for [Real-Router](https://github.com/greydragon888/real-router). Add `onEnter`, `onStay`, `onLeave` callbacks directly to route definitions.
+> Route-level lifecycle hooks for [Real-Router](https://github.com/greydragon888/real-router). Add `onNavigate`, `onEnter`, `onStay`, `onLeave` callbacks directly to route definitions.
 
 ```typescript
 // Without plugin — scattered subscribe() calls with route checks:
 router.subscribe(({ route, previousRoute }) => {
-  if (route.name === "dashboard") trackPageView("dashboard");
+  if (route.name === "catalog") loadServices(route.params);
   if (previousRoute?.name === "editor") saveEditorState();
 });
 
 // With plugin — declarative, per-route:
-{ name: "dashboard", path: "/dashboard", onEnter: () => trackPageView("dashboard") }
-{ name: "editor", path: "/editor", onLeave: () => saveEditorState() }
+{ name: "catalog", path: "/catalog?q&sort", onNavigate: () => (s) => loadServices(s.params) }
+{ name: "editor", path: "/editor", onLeave: () => () => saveEditorState() }
 ```
 
 ## Installation
@@ -35,20 +35,26 @@ import { lifecyclePluginFactory } from "@real-router/lifecycle-plugin";
 
 const routes = [
   {
-    name: "home",
-    path: "/",
-    onLeave: (toState, fromState) => {
-      console.log("Leaving home for", toState.name);
+    name: "services.catalog",
+    path: "/catalog?q&sort&dir",
+    // Fires on entry AND on param-change — recommended default
+    onNavigate: () => (toState) => {
+      loadServices(toState.params);
     },
   },
   {
-    name: "users.view",
-    path: "/users/:id",
-    onEnter: (toState) => {
-      analytics.track("user_profile_viewed", { userId: toState.params.id });
+    name: "chat",
+    path: "/chat/:roomId",
+    // Orthogonal: onEnter covers entry-only setup, onNavigate covers
+    // every navigation (including entry). Both fire on entry.
+    onEnter: () => (toState) => {
+      chatSocket.connect(toState.params.roomId);
     },
-    onStay: (toState, fromState) => {
-      console.log("User changed:", fromState.params.id, "→", toState.params.id);
+    onNavigate: () => (toState) => {
+      loadMessages(toState.params.roomId);
+    },
+    onLeave: () => () => {
+      chatSocket.disconnect();
     },
   },
 ];
@@ -59,15 +65,31 @@ router.usePlugin(lifecyclePluginFactory());
 await router.start("/");
 ```
 
+> **Start with `onNavigate`.** It covers the most common case — running the same logic whenever the route is the navigation target (data loading, analytics, UI reset). Add `onEnter` or `onStay` for extra case-specific logic.
+
 ## Hook Reference
 
-| Hook      | Fires when                 | Typical use case           |
-| --------- | -------------------------- | -------------------------- |
-| `onEnter` | Route is entered           | Analytics, data prefetch   |
-| `onStay`  | Same route, params changed | Refresh data, update UI    |
-| `onLeave` | Route is left              | Cleanup timers, save state |
+| Hook         | Fires when                              | Typical use case                            |
+| ------------ | --------------------------------------- | ------------------------------------------- |
+| `onNavigate` | Any successful navigation to the route  | Data loading, analytics, UI reset (default) |
+| `onEnter`    | Route is entered                        | Entry-only setup (open socket, scroll top)  |
+| `onStay`     | Same route, params changed              | Stay-only logic (incremental updates)       |
+| `onLeave`    | Route is left                           | Cleanup timers, save state                  |
+
+**Orthogonal dispatch:** `onEnter` / `onStay` / `onNavigate` fire independently based on their own conditions. On entry, `onEnter` **and** `onNavigate` fire. On param-change, `onStay` **and** `onNavigate` fire. Each hook is composable — declaring one never silences another.
+
+Each hook field is a **factory function** `(router, getDependency) => (toState, fromState?) => void`. The factory runs once per route; the returned callback is cached and invoked on each matching transition. When you don't need DI, omit the factory params:
 
-All hooks receive `(toState: State, fromState: State | undefined) => void`.
+```typescript
+// Without DI — ignore factory params:
+onEnter: () => (toState) => { console.log("entered", toState.name); }
+
+// With DI — access router and dependencies:
+onEnter: (router, getDependency) => (toState) => {
+  const analytics = getDependency("analytics");
+  analytics.track("page_viewed", { route: toState.name });
+}
+```
 
 ### Execution order
 
@@ -75,13 +97,26 @@ All hooks receive `(toState: State, fromState: State | undefined) => void`.
 
 ## Use Cases
 
+### Data loading (onNavigate — recommended default)
+
+```typescript
+{
+  name: "services.catalog",
+  path: "/catalog?q&sort&dir",
+  onNavigate: () => (toState) => {
+    // Fires on entry from another route AND on filter/sort param changes
+    loadServices(toState.params);
+  },
+}
+```
+
 ### Analytics tracking
 
 ```typescript
 {
   name: "product",
   path: "/products/:id",
-  onEnter: (toState) => {
+  onEnter: () => (toState) => {
     analytics.track("product_viewed", { productId: toState.params.id });
   },
 }
@@ -93,7 +128,7 @@ All hooks receive `(toState: State, fromState: State | undefined) => void`.
 {
   name: "editor",
   path: "/editor/:docId",
-  onLeave: () => {
+  onLeave: () => () => {
     autosaveTimer.clear();
     webSocket.disconnect();
   },
@@ -106,7 +141,7 @@ All hooks receive `(toState: State, fromState: State | undefined) => void`.
 {
   name: "search",
   path: "/search?q",
-  onStay: (toState) => {
+  onStay: () => (toState) => {
     searchStore.setQuery(toState.params.q);
   },
 }

package/dist/cjs/index.d.ts

@@ -1,11 +1,18 @@
-import { PluginFactory, State } from "@real-router/core";
+import { DefaultDependencies, PluginFactory, State } from "@real-router/core";
+import { DefaultDependencies as DefaultDependencies$1, Router } from "@real-router/types";
 
 //#region src/types.d.ts
 /**
  * Lifecycle hook callback for route transitions.
- * Fire-and-forget: return values are ignored, errors are caught and warned.
+ * Fire-and-forget: return values are ignored, errors propagate to EventEmitter (logged to stderr).
  */
 type LifecycleHook = (toState: State, fromState: State | undefined) => void;
+/**
+ * Factory function for creating lifecycle hooks.
+ * Receives the router instance and a dependency getter (same pattern as GuardFnFactory).
+ * Factory runs once at first invocation; the returned hook is cached per route.
+ */
+type LifecycleHookFactory<Dependencies extends DefaultDependencies$1 = DefaultDependencies$1> = (router: Router<Dependencies>, getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K]) => LifecycleHook;
 //#endregion
 //#region src/factory.d.ts
 declare function lifecyclePluginFactory(): PluginFactory;
@@ -13,18 +20,24 @@ declare function lifecyclePluginFactory(): PluginFactory;
 //#region src/index.d.ts
 /**
  * Module augmentation for real-router.
- * Extends Route interface with lifecycle hooks.
+ * Extends Route interface with lifecycle hook factories.
  */
 declare module "@real-router/core" {
-  interface Route {
-    /** Called when this route segment is newly activated (entered). */
-    onEnter?: LifecycleHook;
-    /** Called when this route segment stays active but params changed. */
-    onStay?: LifecycleHook;
-    /** Called when this route segment is deactivated (left). */
-    onLeave?: LifecycleHook;
+  interface Route<Dependencies extends DefaultDependencies> {
+    /** Factory that returns a hook called when this route segment is newly activated (entered). */
+    onEnter?: LifecycleHookFactory<Dependencies>;
+    /** Factory that returns a hook called when this route segment stays active but params changed. */
+    onStay?: LifecycleHookFactory<Dependencies>;
+    /** Factory that returns a hook called when this route segment is deactivated (left). */
+    onLeave?: LifecycleHookFactory<Dependencies>;
+    /**
+     * Factory that returns a hook called on every successful navigation to this route
+     * (both entry and param-change). Acts as a fallback when `onEnter` or `onStay`
+     * is not defined for the corresponding case.
+     */
+    onNavigate?: LifecycleHookFactory<Dependencies>;
   }
 }
 //#endregion
-export { type LifecycleHook, lifecyclePluginFactory };
+export { type LifecycleHook, type LifecycleHookFactory, lifecyclePluginFactory };
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types.ts","../../src/factory.ts","../../src/index.ts"],"mappings":";;;;;AAMA;;KAAY,aAAA,IACV,OAAA,EAAS,KAAA,EACT,SAAA,EAAW,KAAA;;;iBCoCG,sBAAA,CAAA,GAA0B,aAAA;;;;ADtC1C;;;;YEGY,KAAA;IFFV;IEIE,OAAA,GAAU,aAAA;IFHZ;IEKE,MAAA,GAAS,aAAA;IFLiB;IEO1B,OAAA,GAAU,aAAA;EAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types.ts","../../src/factory.ts","../../src/index.ts"],"mappings":";;;;;;AAOA;;KAAY,aAAA,IACV,OAAA,EAAS,KAAA,EACT,SAAA,EAAW,KAAA;;;;;;KAQD,oBAAA,sBACW,qBAAA,GAAsB,qBAAA,KAE3C,MAAA,EAAQ,MAAA,CAAO,YAAA,GACf,aAAA,mBAAgC,YAAA,EAAc,GAAA,EAAK,CAAA,KAAM,YAAA,CAAa,CAAA,MACnE,aAAA;;;iBC6CW,sBAAA,CAAA,GAA0B,aAAA;;;;AD5D1C;;;;YEGY,KAAA,sBAA2B,mBAAA;IFFrC;IEIE,OAAA,GAAU,oBAAA,CAAqB,YAAA;IFHjC;IEKE,MAAA,GAAS,oBAAA,CAAqB,YAAA;IFLJ;IEO1B,OAAA,GAAU,oBAAA,CAAqB,YAAA;IFCH;;;;;IEK5B,UAAA,GAAa,oBAAA,CAAqB,YAAA;EAAA;AAAA"}

package/dist/cjs/index.js

@@ -1,2 +1,2 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@real-router/core/api`);function t(e){return(t,n,r,i)=>{let a=e.getRouteConfig(n)?.[t];typeof a==`function`&&a(r,i)}}function n(n){let r=t((0,e.getPluginApi)(n));return{onTransitionLeaveApprove:(e,t)=>{t&&e.name!==t.name&&r(`onLeave`,t.name,e,t)},onTransitionSuccess:(e,t)=>{e.name===t?.name?r(`onStay`,e.name,e,t):r(`onEnter`,e.name,e,t)}}}function r(){return n}exports.lifecyclePluginFactory=r;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@real-router/core/api`);function t(...t){let[n,r]=t,i=(0,e.getPluginApi)(n),a=new Map;function o(e,t){let o=`${e}:${t}`,s=i.getRouteConfig(t),c=typeof s?.[e]==`function`?s[e]:void 0;if(!c){a.delete(o);return}let l=a.get(o);if(l?.factory===c)return l.hook;let u=c(n,r);return a.set(o,{hook:u,factory:c}),u}return{onTransitionLeaveApprove:(e,t)=>{t&&e.name!==t.name&&o(`onLeave`,t.name)?.(e,t)},onTransitionSuccess:(e,t)=>{e.name===t?.name?o(`onStay`,e.name)?.(e,t):o(`onEnter`,e.name)?.(e,t),o(`onNavigate`,e.name)?.(e,t)}}}function n(){return t}exports.lifecyclePluginFactory=n;
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/factory.ts"],"sourcesContent":["import { getPluginApi } from \"@real-router/core/api\";\n\nimport type { LifecycleHook } from \"./types\";\nimport type { PluginFactory, State } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nfunction createInvokeHook(api: PluginApi) {\n  return (\n    hookName: \"onEnter\" | \"onStay\" | \"onLeave\",\n    routeName: string,\n    toState: State,\n    fromState: State | undefined,\n  ): void => {\n    const hook = api.getRouteConfig(routeName)?.[hookName];\n\n    if (typeof hook === \"function\") {\n      (hook as LifecycleHook)(toState, fromState);\n    }\n  };\n}\n\nfunction createPlugin(router: Parameters<PluginFactory>[0]) {\n  const invokeHook = createInvokeHook(getPluginApi(router));\n\n  return {\n    onTransitionLeaveApprove: (\n      toState: State,\n      fromState: State | undefined,\n    ) => {\n      if (fromState && toState.name !== fromState.name) {\n        invokeHook(\"onLeave\", fromState.name, toState, fromState);\n      }\n    },\n\n    onTransitionSuccess: (toState: State, fromState: State | undefined) => {\n      if (toState.name === fromState?.name) {\n        invokeHook(\"onStay\", toState.name, toState, fromState);\n      } else {\n        invokeHook(\"onEnter\", toState.name, toState, fromState);\n      }\n    },\n  };\n}\n\nexport function lifecyclePluginFactory(): PluginFactory {\n  return createPlugin;\n}\n"],"mappings":"0GAMA,SAAS,EAAiB,EAAgB,CACxC,OACE,EACA,EACA,EACA,IACS,CACT,IAAM,EAAO,EAAI,eAAe,EAAU,GAAG,GAEzC,OAAO,GAAS,YACjB,EAAuB,EAAS,EAAU,EAKjD,SAAS,EAAa,EAAsC,CAC1D,IAAM,EAAa,GAAA,EAAA,EAAA,cAA8B,EAAO,CAAC,CAEzD,MAAO,CACL,0BACE,EACA,IACG,CACC,GAAa,EAAQ,OAAS,EAAU,MAC1C,EAAW,UAAW,EAAU,KAAM,EAAS,EAAU,EAI7D,qBAAsB,EAAgB,IAAiC,CACjE,EAAQ,OAAS,GAAW,KAC9B,EAAW,SAAU,EAAQ,KAAM,EAAS,EAAU,CAEtD,EAAW,UAAW,EAAQ,KAAM,EAAS,EAAU,EAG5D,CAGH,SAAgB,GAAwC,CACtD,OAAO"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/factory.ts"],"sourcesContent":["import { getPluginApi } from \"@real-router/core/api\";\n\nimport type { LifecycleHook, LifecycleHookFactory } from \"./types\";\nimport type { PluginFactory, State } from \"@real-router/core\";\n\nfunction createPlugin(\n  ...args: Parameters<PluginFactory>\n): ReturnType<PluginFactory> {\n  const [router, getDependency] = args;\n  const api = getPluginApi(router);\n  const compiledHooks = new Map<\n    string,\n    { hook: LifecycleHook; factory: LifecycleHookFactory }\n  >();\n\n  function compileHook(\n    hookName: \"onEnter\" | \"onStay\" | \"onLeave\" | \"onNavigate\",\n    routeName: string,\n  ): LifecycleHook | undefined {\n    const key = `${hookName}:${routeName}`;\n    const config = api.getRouteConfig(routeName);\n    const factory =\n      typeof config?.[hookName] === \"function\"\n        ? (config[hookName] as LifecycleHookFactory)\n        : undefined;\n\n    if (!factory) {\n      compiledHooks.delete(key);\n\n      return undefined;\n    }\n\n    const cached = compiledHooks.get(key);\n\n    if (cached?.factory === factory) {\n      return cached.hook;\n    }\n\n    const hook = factory(router, getDependency);\n\n    compiledHooks.set(key, { hook, factory });\n\n    return hook;\n  }\n\n  return {\n    onTransitionLeaveApprove: (\n      toState: State,\n      fromState: State | undefined,\n    ) => {\n      if (fromState && toState.name !== fromState.name) {\n        compileHook(\"onLeave\", fromState.name)?.(toState, fromState);\n      }\n    },\n\n    onTransitionSuccess: (toState: State, fromState: State | undefined) => {\n      if (toState.name === fromState?.name) {\n        compileHook(\"onStay\", toState.name)?.(toState, fromState);\n      } else {\n        compileHook(\"onEnter\", toState.name)?.(toState, fromState);\n      }\n\n      compileHook(\"onNavigate\", toState.name)?.(toState, fromState);\n    },\n  };\n}\n\nexport function lifecyclePluginFactory(): PluginFactory {\n  return createPlugin;\n}\n"],"mappings":"0GAKA,SAAS,EACP,GAAG,EACwB,CAC3B,GAAM,CAAC,EAAQ,GAAiB,EAC1B,GAAA,EAAA,EAAA,cAAmB,EAAO,CAC1B,EAAgB,IAAI,IAK1B,SAAS,EACP,EACA,EAC2B,CAC3B,IAAM,EAAM,GAAG,EAAS,GAAG,IACrB,EAAS,EAAI,eAAe,EAAU,CACtC,EACJ,OAAO,IAAS,IAAc,WACzB,EAAO,GACR,IAAA,GAEN,GAAI,CAAC,EAAS,CACZ,EAAc,OAAO,EAAI,CAEzB,OAGF,IAAM,EAAS,EAAc,IAAI,EAAI,CAErC,GAAI,GAAQ,UAAY,EACtB,OAAO,EAAO,KAGhB,IAAM,EAAO,EAAQ,EAAQ,EAAc,CAI3C,OAFA,EAAc,IAAI,EAAK,CAAE,OAAM,UAAS,CAAC,CAElC,EAGT,MAAO,CACL,0BACE,EACA,IACG,CACC,GAAa,EAAQ,OAAS,EAAU,MAC1C,EAAY,UAAW,EAAU,KAAK,GAAG,EAAS,EAAU,EAIhE,qBAAsB,EAAgB,IAAiC,CACjE,EAAQ,OAAS,GAAW,KAC9B,EAAY,SAAU,EAAQ,KAAK,GAAG,EAAS,EAAU,CAEzD,EAAY,UAAW,EAAQ,KAAK,GAAG,EAAS,EAAU,CAG5D,EAAY,aAAc,EAAQ,KAAK,GAAG,EAAS,EAAU,EAEhE,CAGH,SAAgB,GAAwC,CACtD,OAAO"}

package/dist/esm/index.d.mts

@@ -1,11 +1,18 @@
-import { PluginFactory, State } from "@real-router/core";
+import { DefaultDependencies, PluginFactory, State } from "@real-router/core";
+import { DefaultDependencies as DefaultDependencies$1, Router } from "@real-router/types";
 
 //#region src/types.d.ts
 /**
  * Lifecycle hook callback for route transitions.
- * Fire-and-forget: return values are ignored, errors are caught and warned.
+ * Fire-and-forget: return values are ignored, errors propagate to EventEmitter (logged to stderr).
  */
 type LifecycleHook = (toState: State, fromState: State | undefined) => void;
+/**
+ * Factory function for creating lifecycle hooks.
+ * Receives the router instance and a dependency getter (same pattern as GuardFnFactory).
+ * Factory runs once at first invocation; the returned hook is cached per route.
+ */
+type LifecycleHookFactory<Dependencies extends DefaultDependencies$1 = DefaultDependencies$1> = (router: Router<Dependencies>, getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K]) => LifecycleHook;
 //#endregion
 //#region src/factory.d.ts
 declare function lifecyclePluginFactory(): PluginFactory;
@@ -13,18 +20,24 @@ declare function lifecyclePluginFactory(): PluginFactory;
 //#region src/index.d.ts
 /**
  * Module augmentation for real-router.
- * Extends Route interface with lifecycle hooks.
+ * Extends Route interface with lifecycle hook factories.
  */
 declare module "@real-router/core" {
-  interface Route {
-    /** Called when this route segment is newly activated (entered). */
-    onEnter?: LifecycleHook;
-    /** Called when this route segment stays active but params changed. */
-    onStay?: LifecycleHook;
-    /** Called when this route segment is deactivated (left). */
-    onLeave?: LifecycleHook;
+  interface Route<Dependencies extends DefaultDependencies> {
+    /** Factory that returns a hook called when this route segment is newly activated (entered). */
+    onEnter?: LifecycleHookFactory<Dependencies>;
+    /** Factory that returns a hook called when this route segment stays active but params changed. */
+    onStay?: LifecycleHookFactory<Dependencies>;
+    /** Factory that returns a hook called when this route segment is deactivated (left). */
+    onLeave?: LifecycleHookFactory<Dependencies>;
+    /**
+     * Factory that returns a hook called on every successful navigation to this route
+     * (both entry and param-change). Acts as a fallback when `onEnter` or `onStay`
+     * is not defined for the corresponding case.
+     */
+    onNavigate?: LifecycleHookFactory<Dependencies>;
   }
 }
 //#endregion
-export { type LifecycleHook, lifecyclePluginFactory };
+export { type LifecycleHook, type LifecycleHookFactory, lifecyclePluginFactory };
 //# sourceMappingURL=index.d.mts.map

package/dist/esm/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/types.ts","../../src/factory.ts","../../src/index.ts"],"mappings":";;;;;AAMA;;KAAY,aAAA,IACV,OAAA,EAAS,KAAA,EACT,SAAA,EAAW,KAAA;;;iBCoCG,sBAAA,CAAA,GAA0B,aAAA;;;;ADtC1C;;;;YEGY,KAAA;IFFV;IEIE,OAAA,GAAU,aAAA;IFHZ;IEKE,MAAA,GAAS,aAAA;IFLiB;IEO1B,OAAA,GAAU,aAAA;EAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/types.ts","../../src/factory.ts","../../src/index.ts"],"mappings":";;;;;;AAOA;;KAAY,aAAA,IACV,OAAA,EAAS,KAAA,EACT,SAAA,EAAW,KAAA;;;;;;KAQD,oBAAA,sBACW,qBAAA,GAAsB,qBAAA,KAE3C,MAAA,EAAQ,MAAA,CAAO,YAAA,GACf,aAAA,mBAAgC,YAAA,EAAc,GAAA,EAAK,CAAA,KAAM,YAAA,CAAa,CAAA,MACnE,aAAA;;;iBC6CW,sBAAA,CAAA,GAA0B,aAAA;;;;AD5D1C;;;;YEGY,KAAA,sBAA2B,mBAAA;IFFrC;IEIE,OAAA,GAAU,oBAAA,CAAqB,YAAA;IFHjC;IEKE,MAAA,GAAS,oBAAA,CAAqB,YAAA;IFLJ;IEO1B,OAAA,GAAU,oBAAA,CAAqB,YAAA;IFCH;;;;;IEK5B,UAAA,GAAa,oBAAA,CAAqB,YAAA;EAAA;AAAA"}

package/dist/esm/index.mjs

@@ -1,2 +1,2 @@
-import{getPluginApi as e}from"@real-router/core/api";function t(e){return(t,n,r,i)=>{let a=e.getRouteConfig(n)?.[t];typeof a==`function`&&a(r,i)}}function n(n){let r=t(e(n));return{onTransitionLeaveApprove:(e,t)=>{t&&e.name!==t.name&&r(`onLeave`,t.name,e,t)},onTransitionSuccess:(e,t)=>{e.name===t?.name?r(`onStay`,e.name,e,t):r(`onEnter`,e.name,e,t)}}}function r(){return n}export{r as lifecyclePluginFactory};
+import{getPluginApi as e}from"@real-router/core/api";function t(...t){let[n,r]=t,i=e(n),a=new Map;function o(e,t){let o=`${e}:${t}`,s=i.getRouteConfig(t),c=typeof s?.[e]==`function`?s[e]:void 0;if(!c){a.delete(o);return}let l=a.get(o);if(l?.factory===c)return l.hook;let u=c(n,r);return a.set(o,{hook:u,factory:c}),u}return{onTransitionLeaveApprove:(e,t)=>{t&&e.name!==t.name&&o(`onLeave`,t.name)?.(e,t)},onTransitionSuccess:(e,t)=>{e.name===t?.name?o(`onStay`,e.name)?.(e,t):o(`onEnter`,e.name)?.(e,t),o(`onNavigate`,e.name)?.(e,t)}}}function n(){return t}export{n as lifecyclePluginFactory};
 //# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/factory.ts"],"sourcesContent":["import { getPluginApi } from \"@real-router/core/api\";\n\nimport type { LifecycleHook } from \"./types\";\nimport type { PluginFactory, State } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nfunction createInvokeHook(api: PluginApi) {\n  return (\n    hookName: \"onEnter\" | \"onStay\" | \"onLeave\",\n    routeName: string,\n    toState: State,\n    fromState: State | undefined,\n  ): void => {\n    const hook = api.getRouteConfig(routeName)?.[hookName];\n\n    if (typeof hook === \"function\") {\n      (hook as LifecycleHook)(toState, fromState);\n    }\n  };\n}\n\nfunction createPlugin(router: Parameters<PluginFactory>[0]) {\n  const invokeHook = createInvokeHook(getPluginApi(router));\n\n  return {\n    onTransitionLeaveApprove: (\n      toState: State,\n      fromState: State | undefined,\n    ) => {\n      if (fromState && toState.name !== fromState.name) {\n        invokeHook(\"onLeave\", fromState.name, toState, fromState);\n      }\n    },\n\n    onTransitionSuccess: (toState: State, fromState: State | undefined) => {\n      if (toState.name === fromState?.name) {\n        invokeHook(\"onStay\", toState.name, toState, fromState);\n      } else {\n        invokeHook(\"onEnter\", toState.name, toState, fromState);\n      }\n    },\n  };\n}\n\nexport function lifecyclePluginFactory(): PluginFactory {\n  return createPlugin;\n}\n"],"mappings":"qDAMA,SAAS,EAAiB,EAAgB,CACxC,OACE,EACA,EACA,EACA,IACS,CACT,IAAM,EAAO,EAAI,eAAe,EAAU,GAAG,GAEzC,OAAO,GAAS,YACjB,EAAuB,EAAS,EAAU,EAKjD,SAAS,EAAa,EAAsC,CAC1D,IAAM,EAAa,EAAiB,EAAa,EAAO,CAAC,CAEzD,MAAO,CACL,0BACE,EACA,IACG,CACC,GAAa,EAAQ,OAAS,EAAU,MAC1C,EAAW,UAAW,EAAU,KAAM,EAAS,EAAU,EAI7D,qBAAsB,EAAgB,IAAiC,CACjE,EAAQ,OAAS,GAAW,KAC9B,EAAW,SAAU,EAAQ,KAAM,EAAS,EAAU,CAEtD,EAAW,UAAW,EAAQ,KAAM,EAAS,EAAU,EAG5D,CAGH,SAAgB,GAAwC,CACtD,OAAO"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/factory.ts"],"sourcesContent":["import { getPluginApi } from \"@real-router/core/api\";\n\nimport type { LifecycleHook, LifecycleHookFactory } from \"./types\";\nimport type { PluginFactory, State } from \"@real-router/core\";\n\nfunction createPlugin(\n  ...args: Parameters<PluginFactory>\n): ReturnType<PluginFactory> {\n  const [router, getDependency] = args;\n  const api = getPluginApi(router);\n  const compiledHooks = new Map<\n    string,\n    { hook: LifecycleHook; factory: LifecycleHookFactory }\n  >();\n\n  function compileHook(\n    hookName: \"onEnter\" | \"onStay\" | \"onLeave\" | \"onNavigate\",\n    routeName: string,\n  ): LifecycleHook | undefined {\n    const key = `${hookName}:${routeName}`;\n    const config = api.getRouteConfig(routeName);\n    const factory =\n      typeof config?.[hookName] === \"function\"\n        ? (config[hookName] as LifecycleHookFactory)\n        : undefined;\n\n    if (!factory) {\n      compiledHooks.delete(key);\n\n      return undefined;\n    }\n\n    const cached = compiledHooks.get(key);\n\n    if (cached?.factory === factory) {\n      return cached.hook;\n    }\n\n    const hook = factory(router, getDependency);\n\n    compiledHooks.set(key, { hook, factory });\n\n    return hook;\n  }\n\n  return {\n    onTransitionLeaveApprove: (\n      toState: State,\n      fromState: State | undefined,\n    ) => {\n      if (fromState && toState.name !== fromState.name) {\n        compileHook(\"onLeave\", fromState.name)?.(toState, fromState);\n      }\n    },\n\n    onTransitionSuccess: (toState: State, fromState: State | undefined) => {\n      if (toState.name === fromState?.name) {\n        compileHook(\"onStay\", toState.name)?.(toState, fromState);\n      } else {\n        compileHook(\"onEnter\", toState.name)?.(toState, fromState);\n      }\n\n      compileHook(\"onNavigate\", toState.name)?.(toState, fromState);\n    },\n  };\n}\n\nexport function lifecyclePluginFactory(): PluginFactory {\n  return createPlugin;\n}\n"],"mappings":"qDAKA,SAAS,EACP,GAAG,EACwB,CAC3B,GAAM,CAAC,EAAQ,GAAiB,EAC1B,EAAM,EAAa,EAAO,CAC1B,EAAgB,IAAI,IAK1B,SAAS,EACP,EACA,EAC2B,CAC3B,IAAM,EAAM,GAAG,EAAS,GAAG,IACrB,EAAS,EAAI,eAAe,EAAU,CACtC,EACJ,OAAO,IAAS,IAAc,WACzB,EAAO,GACR,IAAA,GAEN,GAAI,CAAC,EAAS,CACZ,EAAc,OAAO,EAAI,CAEzB,OAGF,IAAM,EAAS,EAAc,IAAI,EAAI,CAErC,GAAI,GAAQ,UAAY,EACtB,OAAO,EAAO,KAGhB,IAAM,EAAO,EAAQ,EAAQ,EAAc,CAI3C,OAFA,EAAc,IAAI,EAAK,CAAE,OAAM,UAAS,CAAC,CAElC,EAGT,MAAO,CACL,0BACE,EACA,IACG,CACC,GAAa,EAAQ,OAAS,EAAU,MAC1C,EAAY,UAAW,EAAU,KAAK,GAAG,EAAS,EAAU,EAIhE,qBAAsB,EAAgB,IAAiC,CACjE,EAAQ,OAAS,GAAW,KAC9B,EAAY,SAAU,EAAQ,KAAK,GAAG,EAAS,EAAU,CAEzD,EAAY,UAAW,EAAQ,KAAK,GAAG,EAAS,EAAU,CAG5D,EAAY,aAAc,EAAQ,KAAK,GAAG,EAAS,EAAU,EAEhE,CAGH,SAAgB,GAAwC,CACtD,OAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/lifecycle-plugin",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "commonjs",
   "description": "Route-level lifecycle hooks: onEnter, onStay, onLeave",
   "main": "./dist/cjs/index.js",
@@ -45,16 +45,17 @@
   "homepage": "https://github.com/greydragon888/real-router",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.48.0"
+    "@real-router/core": "^0.48.0",
+    "@real-router/types": "^0.34.0"
   },
   "scripts": {
-    "build": "tsdown --config-loader unrun",
     "test": "vitest run",
     "test:properties": "vitest run --config vitest.config.properties.mts",
     "test:stress": "vitest --config vitest.config.stress.mts --run",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
     "lint:package": "publint",
-    "lint:types": "attw --pack ."
+    "lint:types": "attw --pack .",
+    "bundle": "tsdown --config-loader unrun"
   }
 }

package/src/factory.ts

@@ -1,26 +1,47 @@
 import { getPluginApi } from "@real-router/core/api";
 
-import type { LifecycleHook } from "./types";
+import type { LifecycleHook, LifecycleHookFactory } from "./types";
 import type { PluginFactory, State } from "@real-router/core";
-import type { PluginApi } from "@real-router/core/api";
 
-function createInvokeHook(api: PluginApi) {
-  return (
-    hookName: "onEnter" | "onStay" | "onLeave",
+function createPlugin(
+  ...args: Parameters<PluginFactory>
+): ReturnType<PluginFactory> {
+  const [router, getDependency] = args;
+  const api = getPluginApi(router);
+  const compiledHooks = new Map<
+    string,
+    { hook: LifecycleHook; factory: LifecycleHookFactory }
+  >();
+
+  function compileHook(
+    hookName: "onEnter" | "onStay" | "onLeave" | "onNavigate",
     routeName: string,
-    toState: State,
-    fromState: State | undefined,
-  ): void => {
-    const hook = api.getRouteConfig(routeName)?.[hookName];
+  ): LifecycleHook | undefined {
+    const key = `${hookName}:${routeName}`;
+    const config = api.getRouteConfig(routeName);
+    const factory =
+      typeof config?.[hookName] === "function"
+        ? (config[hookName] as LifecycleHookFactory)
+        : undefined;
+
+    if (!factory) {
+      compiledHooks.delete(key);
 
-    if (typeof hook === "function") {
-      (hook as LifecycleHook)(toState, fromState);
+      return undefined;
     }
-  };
-}
 
-function createPlugin(router: Parameters<PluginFactory>[0]) {
-  const invokeHook = createInvokeHook(getPluginApi(router));
+    const cached = compiledHooks.get(key);
+
+    if (cached?.factory === factory) {
+      return cached.hook;
+    }
+
+    const hook = factory(router, getDependency);
+
+    compiledHooks.set(key, { hook, factory });
+
+    return hook;
+  }
 
   return {
     onTransitionLeaveApprove: (
@@ -28,16 +49,18 @@ function createPlugin(router: Parameters<PluginFactory>[0]) {
       fromState: State | undefined,
     ) => {
       if (fromState && toState.name !== fromState.name) {
-        invokeHook("onLeave", fromState.name, toState, fromState);
+        compileHook("onLeave", fromState.name)?.(toState, fromState);
       }
     },
 
     onTransitionSuccess: (toState: State, fromState: State | undefined) => {
       if (toState.name === fromState?.name) {
-        invokeHook("onStay", toState.name, toState, fromState);
+        compileHook("onStay", toState.name)?.(toState, fromState);
       } else {
-        invokeHook("onEnter", toState.name, toState, fromState);
+        compileHook("onEnter", toState.name)?.(toState, fromState);
       }
+
+      compileHook("onNavigate", toState.name)?.(toState, fromState);
     },
   };
 }

package/src/index.ts

@@ -1,20 +1,27 @@
-import type { LifecycleHook } from "./types";
+import type { LifecycleHookFactory } from "./types";
+import type { DefaultDependencies } from "@real-router/core";
 
 export { lifecyclePluginFactory } from "./factory";
 
 /**
  * Module augmentation for real-router.
- * Extends Route interface with lifecycle hooks.
+ * Extends Route interface with lifecycle hook factories.
  */
 declare module "@real-router/core" {
-  interface Route {
-    /** Called when this route segment is newly activated (entered). */
-    onEnter?: LifecycleHook;
-    /** Called when this route segment stays active but params changed. */
-    onStay?: LifecycleHook;
-    /** Called when this route segment is deactivated (left). */
-    onLeave?: LifecycleHook;
+  interface Route<Dependencies extends DefaultDependencies> {
+    /** Factory that returns a hook called when this route segment is newly activated (entered). */
+    onEnter?: LifecycleHookFactory<Dependencies>;
+    /** Factory that returns a hook called when this route segment stays active but params changed. */
+    onStay?: LifecycleHookFactory<Dependencies>;
+    /** Factory that returns a hook called when this route segment is deactivated (left). */
+    onLeave?: LifecycleHookFactory<Dependencies>;
+    /**
+     * Factory that returns a hook called on every successful navigation to this route
+     * (both entry and param-change). Acts as a fallback when `onEnter` or `onStay`
+     * is not defined for the corresponding case.
+     */
+    onNavigate?: LifecycleHookFactory<Dependencies>;
   }
 }
 
-export type { LifecycleHook } from "./types";
+export type { LifecycleHook, LifecycleHookFactory } from "./types";

package/src/types.ts

@@ -1,10 +1,23 @@
 import type { State } from "@real-router/core";
+import type { DefaultDependencies, Router } from "@real-router/types";
 
 /**
  * Lifecycle hook callback for route transitions.
- * Fire-and-forget: return values are ignored, errors are caught and warned.
+ * Fire-and-forget: return values are ignored, errors propagate to EventEmitter (logged to stderr).
  */
 export type LifecycleHook = (
   toState: State,
   fromState: State | undefined,
 ) => void;
+
+/**
+ * Factory function for creating lifecycle hooks.
+ * Receives the router instance and a dependency getter (same pattern as GuardFnFactory).
+ * Factory runs once at first invocation; the returned hook is cached per route.
+ */
+export type LifecycleHookFactory<
+  Dependencies extends DefaultDependencies = DefaultDependencies,
+> = (
+  router: Router<Dependencies>,
+  getDependency: <K extends keyof Dependencies>(key: K) => Dependencies[K],
+) => LifecycleHook;