@real-router/lifecycle-plugin 0.2.0 → 0.3.0

package/README.md

@@ -15,8 +15,8 @@ router.subscribe(({ route, previousRoute }) => {
 });
 
 // With plugin — declarative, per-route:
-{ name: "dashboard", path: "/dashboard", onEnter: () => trackPageView("dashboard") }
-{ name: "editor", path: "/editor", onLeave: () => saveEditorState() }
+{ name: "dashboard", path: "/dashboard", onEnter: () => () => trackPageView("dashboard") }
+{ name: "editor", path: "/editor", onLeave: () => () => saveEditorState() }
 ```
 
 ## Installation
@@ -37,17 +37,17 @@ const routes = [
   {
     name: "home",
     path: "/",
-    onLeave: (toState, fromState) => {
+    onLeave: () => (toState, fromState) => {
       console.log("Leaving home for", toState.name);
     },
   },
   {
     name: "users.view",
     path: "/users/:id",
-    onEnter: (toState) => {
+    onEnter: () => (toState) => {
       analytics.track("user_profile_viewed", { userId: toState.params.id });
     },
-    onStay: (toState, fromState) => {
+    onStay: () => (toState, fromState) => {
       console.log("User changed:", fromState.params.id, "→", toState.params.id);
     },
   },
@@ -67,7 +67,18 @@ await router.start("/");
 | `onStay`  | Same route, params changed | Refresh data, update UI    |
 | `onLeave` | Route is left              | Cleanup timers, save state |
 
-All hooks receive `(toState: State, fromState: State | undefined) => void`.
+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:
+
+```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
 
@@ -81,7 +92,7 @@ All hooks receive `(toState: State, fromState: State | undefined) => void`.
 {
   name: "product",
   path: "/products/:id",
-  onEnter: (toState) => {
+  onEnter: () => (toState) => {
     analytics.track("product_viewed", { productId: toState.params.id });
   },
 }
@@ -93,7 +104,7 @@ All hooks receive `(toState: State, fromState: State | undefined) => void`.
 {
   name: "editor",
   path: "/editor/:docId",
-  onLeave: () => {
+  onLeave: () => () => {
     autosaveTimer.clear();
     webSocket.disconnect();
   },
@@ -106,7 +117,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,18 @@ 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>;
   }
 }
 //#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;;;iBC2CW,sBAAA,CAAA,GAA0B,aAAA;;;;AD1D1C;;;;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;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)}}}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\",\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  };\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,EAG/D,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,18 @@ 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>;
   }
 }
 //#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;;;iBC2CW,sBAAA,CAAA,GAA0B,aAAA;;;;AD1D1C;;;;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;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)}}}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\",\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  };\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,EAG/D,CAGH,SAAgB,GAAwC,CACtD,OAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/lifecycle-plugin",
-  "version": "0.2.0",
+  "version": "0.3.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.47.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 (
+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",
     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,15 +49,15 @@ 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);
       }
     },
   };

package/src/index.ts

@@ -1,20 +1,21 @@
-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>;
   }
 }
 
-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;