@real-router/lifecycle-plugin 0.0.1

package/README.md

@@ -0,0 +1,130 @@
+# @real-router/lifecycle-plugin
+
+[![npm](https://img.shields.io/npm/v/@real-router/lifecycle-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/lifecycle-plugin)
+[![npm downloads](https://img.shields.io/npm/dm/@real-router/lifecycle-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/lifecycle-plugin)
+[![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.
+
+```typescript
+// Without plugin — scattered subscribe() calls with route checks:
+router.subscribe(({ route, previousRoute }) => {
+  if (route.name === "dashboard") trackPageView("dashboard");
+  if (previousRoute?.name === "editor") saveEditorState();
+});
+
+// With plugin — declarative, per-route:
+{ name: "dashboard", path: "/dashboard", onEnter: () => trackPageView("dashboard") }
+{ name: "editor", path: "/editor", onLeave: () => saveEditorState() }
+```
+
+## Installation
+
+```bash
+npm install @real-router/lifecycle-plugin
+```
+
+**Peer dependency:** `@real-router/core`
+
+## Quick Start
+
+```typescript
+import { createRouter } from "@real-router/core";
+import { lifecyclePluginFactory } from "@real-router/lifecycle-plugin";
+
+const routes = [
+  {
+    name: "home",
+    path: "/",
+    onLeave: (toState, fromState) => {
+      console.log("Leaving home for", toState.name);
+    },
+  },
+  {
+    name: "users.view",
+    path: "/users/:id",
+    onEnter: (toState) => {
+      analytics.track("user_profile_viewed", { userId: toState.params.id });
+    },
+    onStay: (toState, fromState) => {
+      console.log("User changed:", fromState.params.id, "→", toState.params.id);
+    },
+  },
+];
+
+const router = createRouter(routes);
+router.usePlugin(lifecyclePluginFactory());
+
+await router.start("/");
+```
+
+## 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 |
+
+All hooks receive `(toState: State, fromState: State | undefined) => void`.
+
+### Execution order
+
+`onLeave` fires first (at leave-approve phase), then `onEnter` or `onStay` (at transition success).
+
+## Use Cases
+
+### Analytics tracking
+
+```typescript
+{
+  name: "product",
+  path: "/products/:id",
+  onEnter: (toState) => {
+    analytics.track("product_viewed", { productId: toState.params.id });
+  },
+}
+```
+
+### Cleanup on leave
+
+```typescript
+{
+  name: "editor",
+  path: "/editor/:docId",
+  onLeave: () => {
+    autosaveTimer.clear();
+    webSocket.disconnect();
+  },
+}
+```
+
+### React to param changes
+
+```typescript
+{
+  name: "search",
+  path: "/search?q",
+  onStay: (toState) => {
+    searchStore.setQuery(toState.params.q);
+  },
+}
+```
+
+## Documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — Design decisions and data flow
+- [Plugin Architecture](https://github.com/greydragon888/real-router/wiki/plugin-architecture) — How plugins integrate with the router
+
+## Related Packages
+
+| Package                                                                                  | Description                            |
+| ---------------------------------------------------------------------------------------- | -------------------------------------- |
+| [@real-router/core](https://www.npmjs.com/package/@real-router/core)                     | Core router (required peer dependency) |
+| [@real-router/browser-plugin](https://www.npmjs.com/package/@real-router/browser-plugin) | Browser History API integration        |
+| [@real-router/logger-plugin](https://www.npmjs.com/package/@real-router/logger-plugin)   | Development logging                    |
+
+## License
+
+[MIT](../../LICENSE) © [Oleg Ivanov](https://github.com/greydragon888)

package/dist/cjs/index.d.ts

@@ -0,0 +1,30 @@
+import { PluginFactory, State } from "@real-router/core";
+
+//#region src/types.d.ts
+/**
+ * Lifecycle hook callback for route transitions.
+ * Fire-and-forget: return values are ignored, errors are caught and warned.
+ */
+type LifecycleHook = (toState: State, fromState: State | undefined) => void;
+//#endregion
+//#region src/factory.d.ts
+declare function lifecyclePluginFactory(): PluginFactory;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Module augmentation for real-router.
+ * Extends Route interface with lifecycle hooks.
+ */
+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;
+  }
+}
+//#endregion
+export { type LifecycleHook, lifecyclePluginFactory };
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.js

@@ -0,0 +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;
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +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"}

package/dist/esm/index.d.mts

@@ -0,0 +1,30 @@
+import { PluginFactory, State } from "@real-router/core";
+
+//#region src/types.d.ts
+/**
+ * Lifecycle hook callback for route transitions.
+ * Fire-and-forget: return values are ignored, errors are caught and warned.
+ */
+type LifecycleHook = (toState: State, fromState: State | undefined) => void;
+//#endregion
+//#region src/factory.d.ts
+declare function lifecyclePluginFactory(): PluginFactory;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Module augmentation for real-router.
+ * Extends Route interface with lifecycle hooks.
+ */
+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;
+  }
+}
+//#endregion
+export { type LifecycleHook, lifecyclePluginFactory };
+//# sourceMappingURL=index.d.mts.map

package/dist/esm/index.mjs

@@ -0,0 +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};
+//# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@real-router/lifecycle-plugin",
+  "version": "0.0.1",
+  "type": "commonjs",
+  "description": "Route-level lifecycle hooks: onEnter, onStay, onLeave",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/esm/index.d.mts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": {
+        "import": "./dist/esm/index.d.mts",
+        "require": "./dist/cjs/index.d.ts"
+      },
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/greydragon888/real-router.git"
+  },
+  "keywords": [
+    "real-router",
+    "lifecycle",
+    "hooks",
+    "onEnter",
+    "onStay",
+    "onLeave"
+  ],
+  "author": {
+    "name": "Oleg Ivanov",
+    "email": "greydragon888@gmail.com",
+    "url": "https://github.com/greydragon888"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/greydragon888/real-router/issues"
+  },
+  "homepage": "https://github.com/greydragon888/real-router",
+  "scripts": {
+    "build": "tsdown --config-loader unrun",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
+    "lint:package": "publint",
+    "lint:types": "attw --pack .",
+    "build:dist-only": "tsdown --config-loader unrun"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@real-router/core": "workspace:^"
+  }
+}

package/src/factory.ts

@@ -0,0 +1,47 @@
+import { getPluginApi } from "@real-router/core/api";
+
+import type { LifecycleHook } 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",
+    routeName: string,
+    toState: State,
+    fromState: State | undefined,
+  ): void => {
+    const hook = api.getRouteConfig(routeName)?.[hookName];
+
+    if (typeof hook === "function") {
+      (hook as LifecycleHook)(toState, fromState);
+    }
+  };
+}
+
+function createPlugin(router: Parameters<PluginFactory>[0]) {
+  const invokeHook = createInvokeHook(getPluginApi(router));
+
+  return {
+    onTransitionLeaveApprove: (
+      toState: State,
+      fromState: State | undefined,
+    ) => {
+      if (fromState && toState.name !== fromState.name) {
+        invokeHook("onLeave", fromState.name, toState, fromState);
+      }
+    },
+
+    onTransitionSuccess: (toState: State, fromState: State | undefined) => {
+      if (toState.name === fromState?.name) {
+        invokeHook("onStay", toState.name, toState, fromState);
+      } else {
+        invokeHook("onEnter", toState.name, toState, fromState);
+      }
+    },
+  };
+}
+
+export function lifecyclePluginFactory(): PluginFactory {
+  return createPlugin;
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+import type { LifecycleHook } from "./types";
+
+export { lifecyclePluginFactory } from "./factory";
+
+/**
+ * Module augmentation for real-router.
+ * Extends Route interface with lifecycle hooks.
+ */
+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;
+  }
+}
+
+export type { LifecycleHook } from "./types";

package/src/types.ts

@@ -0,0 +1,10 @@
+import type { State } from "@real-router/core";
+
+/**
+ * Lifecycle hook callback for route transitions.
+ * Fire-and-forget: return values are ignored, errors are caught and warned.
+ */
+export type LifecycleHook = (
+  toState: State,
+  fromState: State | undefined,
+) => void;