@real-router/memory-plugin 0.0.1

package/README.md

@@ -0,0 +1,122 @@
+# @real-router/memory-plugin
+
+[![npm](https://img.shields.io/npm/v/@real-router/memory-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/memory-plugin)
+[![npm downloads](https://img.shields.io/npm/dm/@real-router/memory-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/memory-plugin)
+[![bundle size](https://deno.bundlejs.com/?q=@real-router/memory-plugin&treeshake=[*]&badge=detailed)](https://bundlejs.com/?q=@real-router/memory-plugin&treeshake=[*])
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](../../LICENSE)
+
+> In-memory history stack for [Real-Router](https://github.com/greydragon888/real-router). Back/forward/go navigation without browser History API.
+
+## Installation
+
+```bash
+npm install @real-router/memory-plugin
+```
+
+**Peer dependency:** `@real-router/core`
+
+## Quick Start
+
+```typescript
+import { createRouter } from "@real-router/core";
+import { memoryPluginFactory } from "@real-router/memory-plugin";
+
+const router = createRouter([
+  { name: "home", path: "/" },
+  { name: "users", path: "/users/:id" },
+]);
+
+router.usePlugin(memoryPluginFactory());
+await router.start("/");
+
+await router.navigate("users", { id: "1" });
+await router.navigate("users", { id: "2" });
+
+router.back(); // navigate to users/1
+router.forward(); // navigate to users/2
+router.go(-2); // navigate to home
+```
+
+## Options
+
+```typescript
+router.usePlugin(
+  memoryPluginFactory({
+    maxHistoryLength: 50, // Keep at most 50 entries
+  }),
+);
+```
+
+| Option             | Type     | Default | Description                                                   |
+| ------------------ | -------- | ------- | ------------------------------------------------------------- |
+| `maxHistoryLength` | `number` | `1000`  | Maximum entries. `0` = unlimited, negative throws `TypeError` |
+
+## Router Extensions
+
+The plugin extends the router instance with five methods via [`extendRouter()`](https://github.com/greydragon888/real-router/wiki/plugin-architecture):
+
+| Method           | Returns   | Description                                                     |
+| ---------------- | --------- | --------------------------------------------------------------- |
+| `back()`         | `void`    | Navigate to the previous history entry                          |
+| `forward()`      | `void`    | Navigate to the next history entry                              |
+| `go(delta)`      | `void`    | Navigate by `delta` steps (negative = back, positive = forward) |
+| `canGoBack()`    | `boolean` | `true` if there is a previous entry                             |
+| `canGoForward()` | `boolean` | `true` if there is a next entry                                 |
+
+All navigation methods are fire-and-forget (`void`). To detect completion, subscribe to state changes before calling.
+
+```typescript
+router.subscribe(({ route }) => {
+  console.log("navigated to", route.name);
+});
+
+router.back();
+```
+
+Guards can block back/forward navigation. If a guard rejects, the history index stays unchanged and `canGoBack()`/`canGoForward()` continue to reflect the actual position.
+
+## Use Cases
+
+### React Native / non-browser environments
+
+No `window.history` required. Drop in `memoryPluginFactory()` and get full back/forward support anywhere JavaScript runs.
+
+### Testing and benchmarks
+
+Deterministic navigation without browser globals. Start the router at any path, navigate programmatically, assert state.
+
+```typescript
+const router = createRouter(routes);
+router.usePlugin(memoryPluginFactory());
+await router.start("/");
+
+await router.navigate("dashboard");
+expect(router.canGoBack()).toBe(true);
+
+router.back();
+// wait for state change, then assert
+```
+
+### SSR navigation simulation
+
+Simulate multi-step user flows on the server without a browser environment.
+
+## Documentation
+
+Full documentation: [Wiki — memory-plugin](https://github.com/greydragon888/real-router/wiki/memory-plugin)
+
+## 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/hash-plugin](https://www.npmjs.com/package/@real-router/hash-plugin)       | Hash-based routing (`#/path`)          |
+
+## Contributing
+
+See [contributing guidelines](../../CONTRIBUTING.md) for development setup and PR process.
+
+## License
+
+[MIT](../../LICENSE) © [Oleg Ivanov](https://github.com/greydragon888)

package/dist/cjs/index.d.ts

@@ -0,0 +1,23 @@
+import { PluginFactory } from "@real-router/core";
+
+//#region src/types.d.ts
+interface MemoryPluginOptions {
+  maxHistoryLength?: number;
+}
+//#endregion
+//#region src/factory.d.ts
+declare function memoryPluginFactory(options?: MemoryPluginOptions): PluginFactory;
+//#endregion
+//#region src/index.d.ts
+declare module "@real-router/core" {
+  interface Router {
+    back: () => void;
+    forward: () => void;
+    go: (delta: number) => void;
+    canGoBack: () => boolean;
+    canGoForward: () => boolean;
+  }
+}
+//#endregion
+export { type MemoryPluginOptions, memoryPluginFactory };
+//# 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`);var t=class{#e;#t;#n=[];#r;#i=-1;#a=!1;#o=0;constructor(e,t,n){this.#e=e,this.#t=n.maxHistoryLength??1e3,this.#r=t.extendRouter({back:()=>{this.#s(-1)},forward:()=>{this.#s(1)},go:e=>{this.#s(e)},canGoBack:()=>this.#i>0,canGoForward:()=>this.#i<this.#n.length-1})}getPlugin(){return{onTransitionSuccess:(e,t,n)=>{if(this.#a)return;let r={name:e.name,params:e.params,path:e.path};if(n.replace&&this.#i>=0)this.#n[this.#i]=r;else if(this.#n.splice(this.#i+1),this.#n.push(r),this.#i=this.#n.length-1,this.#t>0&&this.#n.length>this.#t){let e=this.#n.length-this.#t;this.#n.splice(0,e),this.#i=Math.max(0,this.#i-e)}},onStop:()=>{this.#c()},teardown:()=>{this.#r(),this.#c()}}}#s(e){if(e===0)return;let t=this.#i+e;if(t<0||t>=this.#n.length)return;let n=this.#n[t],r=this.#e.getState();if(n.path===r?.path){this.#i=t;return}let i=this.#i,a=++this.#o;this.#a=!0,this.#i=t,this.#e.navigate(n.name,n.params,{replace:!0}).catch(()=>{this.#o===a&&(this.#i=i)}).finally(()=>{this.#o===a&&(this.#a=!1)})}#c(){this.#n.length=0,this.#i=-1}};function n(n={}){if(n.maxHistoryLength!==void 0&&(typeof n.maxHistoryLength!=`number`||n.maxHistoryLength<0))throw TypeError(`[memory-plugin] Invalid maxHistoryLength: expected non-negative number, got ${String(n.maxHistoryLength)}.`);let r=Object.freeze({...n});return n=>new t(n,(0,e.getPluginApi)(n),r).getPlugin()}exports.memoryPluginFactory=n;
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#router","#maxHistory","#entries","#removeExtensions","#go","#index","#navigatingFromHistory","#clear","#goGeneration"],"sources":["../../src/plugin.ts","../../src/factory.ts"],"sourcesContent":["import type { HistoryEntry, MemoryPluginOptions } from \"./types\";\nimport type {\n  NavigationOptions,\n  Plugin,\n  Router,\n  State,\n} from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nconst DEFAULT_MAX_HISTORY = 1000;\n\nexport class MemoryPlugin {\n  readonly #router: Router;\n  readonly #maxHistory: number;\n  readonly #entries: HistoryEntry[] = [];\n  readonly #removeExtensions: () => void;\n  #index = -1;\n  #navigatingFromHistory = false;\n  #goGeneration = 0;\n\n  constructor(router: Router, api: PluginApi, options: MemoryPluginOptions) {\n    this.#router = router;\n    this.#maxHistory = options.maxHistoryLength ?? DEFAULT_MAX_HISTORY;\n\n    this.#removeExtensions = api.extendRouter({\n      back: () => {\n        this.#go(-1);\n      },\n      forward: () => {\n        this.#go(1);\n      },\n      go: (delta: number) => {\n        this.#go(delta);\n      },\n      canGoBack: () => this.#index > 0,\n      canGoForward: () => this.#index < this.#entries.length - 1,\n    });\n  }\n\n  getPlugin(): Plugin {\n    return {\n      onTransitionSuccess: (\n        toState: State,\n        _fromState: State | undefined,\n        opts: NavigationOptions,\n      ) => {\n        if (this.#navigatingFromHistory) {\n          return;\n        }\n\n        const entry: HistoryEntry = {\n          name: toState.name,\n          params: toState.params,\n          path: toState.path,\n        };\n\n        if (opts.replace && this.#index >= 0) {\n          this.#entries[this.#index] = entry;\n        } else {\n          this.#entries.splice(this.#index + 1);\n          this.#entries.push(entry);\n          this.#index = this.#entries.length - 1;\n\n          if (this.#maxHistory > 0 && this.#entries.length > this.#maxHistory) {\n            const overflow = this.#entries.length - this.#maxHistory;\n\n            this.#entries.splice(0, overflow);\n            this.#index = Math.max(0, this.#index - overflow);\n          }\n        }\n      },\n\n      onStop: () => {\n        this.#clear();\n      },\n\n      teardown: () => {\n        this.#removeExtensions();\n        this.#clear();\n      },\n    };\n  }\n\n  #go(delta: number): void {\n    if (delta === 0) {\n      return;\n    }\n\n    const targetIndex = this.#index + delta;\n\n    if (targetIndex < 0 || targetIndex >= this.#entries.length) {\n      return;\n    }\n\n    const entry = this.#entries[targetIndex];\n    const currentState = this.#router.getState();\n\n    if (entry.path === currentState?.path) {\n      this.#index = targetIndex;\n\n      return;\n    }\n\n    const previousIndex = this.#index;\n    const generation = ++this.#goGeneration;\n\n    this.#navigatingFromHistory = true;\n    this.#index = targetIndex;\n\n    void this.#router\n      .navigate(entry.name, entry.params, { replace: true })\n      .catch(() => {\n        if (this.#goGeneration === generation) {\n          this.#index = previousIndex;\n        }\n      })\n      .finally(() => {\n        if (this.#goGeneration === generation) {\n          this.#navigatingFromHistory = false;\n        }\n      });\n  }\n\n  #clear(): void {\n    this.#entries.length = 0;\n    this.#index = -1;\n  }\n}\n","import { getPluginApi } from \"@real-router/core/api\";\n\nimport { MemoryPlugin } from \"./plugin\";\n\nimport type { MemoryPluginOptions } from \"./types\";\nimport type { PluginFactory, Plugin, Router } from \"@real-router/core\";\n\nexport function memoryPluginFactory(\n  options: MemoryPluginOptions = {},\n): PluginFactory {\n  if (\n    options.maxHistoryLength !== undefined &&\n    (typeof options.maxHistoryLength !== \"number\" ||\n      options.maxHistoryLength < 0)\n  ) {\n    throw new TypeError(\n      `[memory-plugin] Invalid maxHistoryLength: expected non-negative number, got ${String(options.maxHistoryLength)}.`,\n    );\n  }\n\n  const frozenOptions: MemoryPluginOptions = Object.freeze({ ...options });\n\n  return (router): Plugin => {\n    const api = getPluginApi(router);\n    const plugin = new MemoryPlugin(router as Router, api, frozenOptions);\n\n    return plugin.getPlugin();\n  };\n}\n"],"mappings":"0GAWA,IAAa,EAAb,KAA0B,CACxB,GACA,GACA,GAAoC,EAAE,CACtC,GACA,GAAS,GACT,GAAyB,GACzB,GAAgB,EAEhB,YAAY,EAAgB,EAAgB,EAA8B,CACxE,MAAA,EAAe,EACf,MAAA,EAAmB,EAAQ,kBAAoB,IAE/C,MAAA,EAAyB,EAAI,aAAa,CACxC,SAAY,CACV,MAAA,EAAS,GAAG,EAEd,YAAe,CACb,MAAA,EAAS,EAAE,EAEb,GAAK,GAAkB,CACrB,MAAA,EAAS,EAAM,EAEjB,cAAiB,MAAA,EAAc,EAC/B,iBAAoB,MAAA,EAAc,MAAA,EAAc,OAAS,EAC1D,CAAC,CAGJ,WAAoB,CAClB,MAAO,CACL,qBACE,EACA,EACA,IACG,CACH,GAAI,MAAA,EACF,OAGF,IAAM,EAAsB,CAC1B,KAAM,EAAQ,KACd,OAAQ,EAAQ,OAChB,KAAM,EAAQ,KACf,CAED,GAAI,EAAK,SAAW,MAAA,GAAe,EACjC,MAAA,EAAc,MAAA,GAAe,UAE7B,MAAA,EAAc,OAAO,MAAA,EAAc,EAAE,CACrC,MAAA,EAAc,KAAK,EAAM,CACzB,MAAA,EAAc,MAAA,EAAc,OAAS,EAEjC,MAAA,EAAmB,GAAK,MAAA,EAAc,OAAS,MAAA,EAAkB,CACnE,IAAM,EAAW,MAAA,EAAc,OAAS,MAAA,EAExC,MAAA,EAAc,OAAO,EAAG,EAAS,CACjC,MAAA,EAAc,KAAK,IAAI,EAAG,MAAA,EAAc,EAAS,GAKvD,WAAc,CACZ,MAAA,GAAa,EAGf,aAAgB,CACd,MAAA,GAAwB,CACxB,MAAA,GAAa,EAEhB,CAGH,GAAI,EAAqB,CACvB,GAAI,IAAU,EACZ,OAGF,IAAM,EAAc,MAAA,EAAc,EAElC,GAAI,EAAc,GAAK,GAAe,MAAA,EAAc,OAClD,OAGF,IAAM,EAAQ,MAAA,EAAc,GACtB,EAAe,MAAA,EAAa,UAAU,CAE5C,GAAI,EAAM,OAAS,GAAc,KAAM,CACrC,MAAA,EAAc,EAEd,OAGF,IAAM,EAAgB,MAAA,EAChB,EAAa,EAAE,MAAA,EAErB,MAAA,EAA8B,GAC9B,MAAA,EAAc,EAET,MAAA,EACF,SAAS,EAAM,KAAM,EAAM,OAAQ,CAAE,QAAS,GAAM,CAAC,CACrD,UAAY,CACP,MAAA,IAAuB,IACzB,MAAA,EAAc,IAEhB,CACD,YAAc,CACT,MAAA,IAAuB,IACzB,MAAA,EAA8B,KAEhC,CAGN,IAAe,CACb,MAAA,EAAc,OAAS,EACvB,MAAA,EAAc,KCtHlB,SAAgB,EACd,EAA+B,EAAE,CAClB,CACf,GACE,EAAQ,mBAAqB,IAAA,KAC5B,OAAO,EAAQ,kBAAqB,UACnC,EAAQ,iBAAmB,GAE7B,MAAU,UACR,+EAA+E,OAAO,EAAQ,iBAAiB,CAAC,GACjH,CAGH,IAAM,EAAqC,OAAO,OAAO,CAAE,GAAG,EAAS,CAAC,CAExE,MAAQ,IAES,IAAI,EAAa,GAAA,EAAA,EAAA,cADP,EAAO,CACuB,EAAc,CAEvD,WAAW"}

package/dist/esm/index.d.mts

@@ -0,0 +1,23 @@
+import { PluginFactory } from "@real-router/core";
+
+//#region src/types.d.ts
+interface MemoryPluginOptions {
+  maxHistoryLength?: number;
+}
+//#endregion
+//#region src/factory.d.ts
+declare function memoryPluginFactory(options?: MemoryPluginOptions): PluginFactory;
+//#endregion
+//#region src/index.d.ts
+declare module "@real-router/core" {
+  interface Router {
+    back: () => void;
+    forward: () => void;
+    go: (delta: number) => void;
+    canGoBack: () => boolean;
+    canGoForward: () => boolean;
+  }
+}
+//#endregion
+export { type MemoryPluginOptions, memoryPluginFactory };
+//# sourceMappingURL=index.d.mts.map

package/dist/esm/index.mjs

@@ -0,0 +1,2 @@
+import{getPluginApi as e}from"@real-router/core/api";var t=class{#e;#t;#n=[];#r;#i=-1;#a=!1;#o=0;constructor(e,t,n){this.#e=e,this.#t=n.maxHistoryLength??1e3,this.#r=t.extendRouter({back:()=>{this.#s(-1)},forward:()=>{this.#s(1)},go:e=>{this.#s(e)},canGoBack:()=>this.#i>0,canGoForward:()=>this.#i<this.#n.length-1})}getPlugin(){return{onTransitionSuccess:(e,t,n)=>{if(this.#a)return;let r={name:e.name,params:e.params,path:e.path};if(n.replace&&this.#i>=0)this.#n[this.#i]=r;else if(this.#n.splice(this.#i+1),this.#n.push(r),this.#i=this.#n.length-1,this.#t>0&&this.#n.length>this.#t){let e=this.#n.length-this.#t;this.#n.splice(0,e),this.#i=Math.max(0,this.#i-e)}},onStop:()=>{this.#c()},teardown:()=>{this.#r(),this.#c()}}}#s(e){if(e===0)return;let t=this.#i+e;if(t<0||t>=this.#n.length)return;let n=this.#n[t],r=this.#e.getState();if(n.path===r?.path){this.#i=t;return}let i=this.#i,a=++this.#o;this.#a=!0,this.#i=t,this.#e.navigate(n.name,n.params,{replace:!0}).catch(()=>{this.#o===a&&(this.#i=i)}).finally(()=>{this.#o===a&&(this.#a=!1)})}#c(){this.#n.length=0,this.#i=-1}};function n(n={}){if(n.maxHistoryLength!==void 0&&(typeof n.maxHistoryLength!=`number`||n.maxHistoryLength<0))throw TypeError(`[memory-plugin] Invalid maxHistoryLength: expected non-negative number, got ${String(n.maxHistoryLength)}.`);let r=Object.freeze({...n});return n=>new t(n,e(n),r).getPlugin()}export{n as memoryPluginFactory};
+//# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["#router","#maxHistory","#entries","#removeExtensions","#go","#index","#navigatingFromHistory","#clear","#goGeneration"],"sources":["../../src/plugin.ts","../../src/factory.ts"],"sourcesContent":["import type { HistoryEntry, MemoryPluginOptions } from \"./types\";\nimport type {\n  NavigationOptions,\n  Plugin,\n  Router,\n  State,\n} from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nconst DEFAULT_MAX_HISTORY = 1000;\n\nexport class MemoryPlugin {\n  readonly #router: Router;\n  readonly #maxHistory: number;\n  readonly #entries: HistoryEntry[] = [];\n  readonly #removeExtensions: () => void;\n  #index = -1;\n  #navigatingFromHistory = false;\n  #goGeneration = 0;\n\n  constructor(router: Router, api: PluginApi, options: MemoryPluginOptions) {\n    this.#router = router;\n    this.#maxHistory = options.maxHistoryLength ?? DEFAULT_MAX_HISTORY;\n\n    this.#removeExtensions = api.extendRouter({\n      back: () => {\n        this.#go(-1);\n      },\n      forward: () => {\n        this.#go(1);\n      },\n      go: (delta: number) => {\n        this.#go(delta);\n      },\n      canGoBack: () => this.#index > 0,\n      canGoForward: () => this.#index < this.#entries.length - 1,\n    });\n  }\n\n  getPlugin(): Plugin {\n    return {\n      onTransitionSuccess: (\n        toState: State,\n        _fromState: State | undefined,\n        opts: NavigationOptions,\n      ) => {\n        if (this.#navigatingFromHistory) {\n          return;\n        }\n\n        const entry: HistoryEntry = {\n          name: toState.name,\n          params: toState.params,\n          path: toState.path,\n        };\n\n        if (opts.replace && this.#index >= 0) {\n          this.#entries[this.#index] = entry;\n        } else {\n          this.#entries.splice(this.#index + 1);\n          this.#entries.push(entry);\n          this.#index = this.#entries.length - 1;\n\n          if (this.#maxHistory > 0 && this.#entries.length > this.#maxHistory) {\n            const overflow = this.#entries.length - this.#maxHistory;\n\n            this.#entries.splice(0, overflow);\n            this.#index = Math.max(0, this.#index - overflow);\n          }\n        }\n      },\n\n      onStop: () => {\n        this.#clear();\n      },\n\n      teardown: () => {\n        this.#removeExtensions();\n        this.#clear();\n      },\n    };\n  }\n\n  #go(delta: number): void {\n    if (delta === 0) {\n      return;\n    }\n\n    const targetIndex = this.#index + delta;\n\n    if (targetIndex < 0 || targetIndex >= this.#entries.length) {\n      return;\n    }\n\n    const entry = this.#entries[targetIndex];\n    const currentState = this.#router.getState();\n\n    if (entry.path === currentState?.path) {\n      this.#index = targetIndex;\n\n      return;\n    }\n\n    const previousIndex = this.#index;\n    const generation = ++this.#goGeneration;\n\n    this.#navigatingFromHistory = true;\n    this.#index = targetIndex;\n\n    void this.#router\n      .navigate(entry.name, entry.params, { replace: true })\n      .catch(() => {\n        if (this.#goGeneration === generation) {\n          this.#index = previousIndex;\n        }\n      })\n      .finally(() => {\n        if (this.#goGeneration === generation) {\n          this.#navigatingFromHistory = false;\n        }\n      });\n  }\n\n  #clear(): void {\n    this.#entries.length = 0;\n    this.#index = -1;\n  }\n}\n","import { getPluginApi } from \"@real-router/core/api\";\n\nimport { MemoryPlugin } from \"./plugin\";\n\nimport type { MemoryPluginOptions } from \"./types\";\nimport type { PluginFactory, Plugin, Router } from \"@real-router/core\";\n\nexport function memoryPluginFactory(\n  options: MemoryPluginOptions = {},\n): PluginFactory {\n  if (\n    options.maxHistoryLength !== undefined &&\n    (typeof options.maxHistoryLength !== \"number\" ||\n      options.maxHistoryLength < 0)\n  ) {\n    throw new TypeError(\n      `[memory-plugin] Invalid maxHistoryLength: expected non-negative number, got ${String(options.maxHistoryLength)}.`,\n    );\n  }\n\n  const frozenOptions: MemoryPluginOptions = Object.freeze({ ...options });\n\n  return (router): Plugin => {\n    const api = getPluginApi(router);\n    const plugin = new MemoryPlugin(router as Router, api, frozenOptions);\n\n    return plugin.getPlugin();\n  };\n}\n"],"mappings":"qDAWA,IAAa,EAAb,KAA0B,CACxB,GACA,GACA,GAAoC,EAAE,CACtC,GACA,GAAS,GACT,GAAyB,GACzB,GAAgB,EAEhB,YAAY,EAAgB,EAAgB,EAA8B,CACxE,MAAA,EAAe,EACf,MAAA,EAAmB,EAAQ,kBAAoB,IAE/C,MAAA,EAAyB,EAAI,aAAa,CACxC,SAAY,CACV,MAAA,EAAS,GAAG,EAEd,YAAe,CACb,MAAA,EAAS,EAAE,EAEb,GAAK,GAAkB,CACrB,MAAA,EAAS,EAAM,EAEjB,cAAiB,MAAA,EAAc,EAC/B,iBAAoB,MAAA,EAAc,MAAA,EAAc,OAAS,EAC1D,CAAC,CAGJ,WAAoB,CAClB,MAAO,CACL,qBACE,EACA,EACA,IACG,CACH,GAAI,MAAA,EACF,OAGF,IAAM,EAAsB,CAC1B,KAAM,EAAQ,KACd,OAAQ,EAAQ,OAChB,KAAM,EAAQ,KACf,CAED,GAAI,EAAK,SAAW,MAAA,GAAe,EACjC,MAAA,EAAc,MAAA,GAAe,UAE7B,MAAA,EAAc,OAAO,MAAA,EAAc,EAAE,CACrC,MAAA,EAAc,KAAK,EAAM,CACzB,MAAA,EAAc,MAAA,EAAc,OAAS,EAEjC,MAAA,EAAmB,GAAK,MAAA,EAAc,OAAS,MAAA,EAAkB,CACnE,IAAM,EAAW,MAAA,EAAc,OAAS,MAAA,EAExC,MAAA,EAAc,OAAO,EAAG,EAAS,CACjC,MAAA,EAAc,KAAK,IAAI,EAAG,MAAA,EAAc,EAAS,GAKvD,WAAc,CACZ,MAAA,GAAa,EAGf,aAAgB,CACd,MAAA,GAAwB,CACxB,MAAA,GAAa,EAEhB,CAGH,GAAI,EAAqB,CACvB,GAAI,IAAU,EACZ,OAGF,IAAM,EAAc,MAAA,EAAc,EAElC,GAAI,EAAc,GAAK,GAAe,MAAA,EAAc,OAClD,OAGF,IAAM,EAAQ,MAAA,EAAc,GACtB,EAAe,MAAA,EAAa,UAAU,CAE5C,GAAI,EAAM,OAAS,GAAc,KAAM,CACrC,MAAA,EAAc,EAEd,OAGF,IAAM,EAAgB,MAAA,EAChB,EAAa,EAAE,MAAA,EAErB,MAAA,EAA8B,GAC9B,MAAA,EAAc,EAET,MAAA,EACF,SAAS,EAAM,KAAM,EAAM,OAAQ,CAAE,QAAS,GAAM,CAAC,CACrD,UAAY,CACP,MAAA,IAAuB,IACzB,MAAA,EAAc,IAEhB,CACD,YAAc,CACT,MAAA,IAAuB,IACzB,MAAA,EAA8B,KAEhC,CAGN,IAAe,CACb,MAAA,EAAc,OAAS,EACvB,MAAA,EAAc,KCtHlB,SAAgB,EACd,EAA+B,EAAE,CAClB,CACf,GACE,EAAQ,mBAAqB,IAAA,KAC5B,OAAO,EAAQ,kBAAqB,UACnC,EAAQ,iBAAmB,GAE7B,MAAU,UACR,+EAA+E,OAAO,EAAQ,iBAAiB,CAAC,GACjH,CAGH,IAAM,EAAqC,OAAO,OAAO,CAAE,GAAG,EAAS,CAAC,CAExE,MAAQ,IAES,IAAI,EAAa,EADpB,EAAa,EAAO,CACuB,EAAc,CAEvD,WAAW"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@real-router/memory-plugin",
+  "version": "0.0.1",
+  "type": "commonjs",
+  "description": "In-memory history engine for Real-Router — non-browser environments and benchmarks",
+  "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",
+    "memory",
+    "history",
+    "in-memory",
+    "react-native",
+    "benchmark"
+  ],
+  "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": {
+    "test": "vitest",
+    "test:properties": "vitest --config vitest.config.properties.mts --run",
+    "build": "tsdown --config-loader unrun",
+    "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,29 @@
+import { getPluginApi } from "@real-router/core/api";
+
+import { MemoryPlugin } from "./plugin";
+
+import type { MemoryPluginOptions } from "./types";
+import type { PluginFactory, Plugin, Router } from "@real-router/core";
+
+export function memoryPluginFactory(
+  options: MemoryPluginOptions = {},
+): PluginFactory {
+  if (
+    options.maxHistoryLength !== undefined &&
+    (typeof options.maxHistoryLength !== "number" ||
+      options.maxHistoryLength < 0)
+  ) {
+    throw new TypeError(
+      `[memory-plugin] Invalid maxHistoryLength: expected non-negative number, got ${String(options.maxHistoryLength)}.`,
+    );
+  }
+
+  const frozenOptions: MemoryPluginOptions = Object.freeze({ ...options });
+
+  return (router): Plugin => {
+    const api = getPluginApi(router);
+    const plugin = new MemoryPlugin(router as Router, api, frozenOptions);
+
+    return plugin.getPlugin();
+  };
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { memoryPluginFactory } from "./factory";
+
+export type { MemoryPluginOptions } from "./types";
+
+declare module "@real-router/core" {
+  interface Router {
+    back: () => void;
+    forward: () => void;
+    go: (delta: number) => void;
+    canGoBack: () => boolean;
+    canGoForward: () => boolean;
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,128 @@
+import type { HistoryEntry, MemoryPluginOptions } from "./types";
+import type {
+  NavigationOptions,
+  Plugin,
+  Router,
+  State,
+} from "@real-router/core";
+import type { PluginApi } from "@real-router/core/api";
+
+const DEFAULT_MAX_HISTORY = 1000;
+
+export class MemoryPlugin {
+  readonly #router: Router;
+  readonly #maxHistory: number;
+  readonly #entries: HistoryEntry[] = [];
+  readonly #removeExtensions: () => void;
+  #index = -1;
+  #navigatingFromHistory = false;
+  #goGeneration = 0;
+
+  constructor(router: Router, api: PluginApi, options: MemoryPluginOptions) {
+    this.#router = router;
+    this.#maxHistory = options.maxHistoryLength ?? DEFAULT_MAX_HISTORY;
+
+    this.#removeExtensions = api.extendRouter({
+      back: () => {
+        this.#go(-1);
+      },
+      forward: () => {
+        this.#go(1);
+      },
+      go: (delta: number) => {
+        this.#go(delta);
+      },
+      canGoBack: () => this.#index > 0,
+      canGoForward: () => this.#index < this.#entries.length - 1,
+    });
+  }
+
+  getPlugin(): Plugin {
+    return {
+      onTransitionSuccess: (
+        toState: State,
+        _fromState: State | undefined,
+        opts: NavigationOptions,
+      ) => {
+        if (this.#navigatingFromHistory) {
+          return;
+        }
+
+        const entry: HistoryEntry = {
+          name: toState.name,
+          params: toState.params,
+          path: toState.path,
+        };
+
+        if (opts.replace && this.#index >= 0) {
+          this.#entries[this.#index] = entry;
+        } else {
+          this.#entries.splice(this.#index + 1);
+          this.#entries.push(entry);
+          this.#index = this.#entries.length - 1;
+
+          if (this.#maxHistory > 0 && this.#entries.length > this.#maxHistory) {
+            const overflow = this.#entries.length - this.#maxHistory;
+
+            this.#entries.splice(0, overflow);
+            this.#index = Math.max(0, this.#index - overflow);
+          }
+        }
+      },
+
+      onStop: () => {
+        this.#clear();
+      },
+
+      teardown: () => {
+        this.#removeExtensions();
+        this.#clear();
+      },
+    };
+  }
+
+  #go(delta: number): void {
+    if (delta === 0) {
+      return;
+    }
+
+    const targetIndex = this.#index + delta;
+
+    if (targetIndex < 0 || targetIndex >= this.#entries.length) {
+      return;
+    }
+
+    const entry = this.#entries[targetIndex];
+    const currentState = this.#router.getState();
+
+    if (entry.path === currentState?.path) {
+      this.#index = targetIndex;
+
+      return;
+    }
+
+    const previousIndex = this.#index;
+    const generation = ++this.#goGeneration;
+
+    this.#navigatingFromHistory = true;
+    this.#index = targetIndex;
+
+    void this.#router
+      .navigate(entry.name, entry.params, { replace: true })
+      .catch(() => {
+        if (this.#goGeneration === generation) {
+          this.#index = previousIndex;
+        }
+      })
+      .finally(() => {
+        if (this.#goGeneration === generation) {
+          this.#navigatingFromHistory = false;
+        }
+      });
+  }
+
+  #clear(): void {
+    this.#entries.length = 0;
+    this.#index = -1;
+  }
+}

package/src/types.ts

@@ -0,0 +1,11 @@
+import type { Params } from "@real-router/core";
+
+export interface MemoryPluginOptions {
+  maxHistoryLength?: number;
+}
+
+export interface HistoryEntry {
+  readonly name: string;
+  readonly params: Params;
+  readonly path: string;
+}