@real-router/memory-plugin 0.2.0 → 0.3.0

package/README.md

@@ -32,6 +32,8 @@ await router.start("/");
 await router.navigate("users", { id: "1" });
 await router.navigate("users", { id: "2" });
 
+// Fire-and-forget: each call schedules a navigation and returns immediately.
+// Subscribe to state changes to detect completion.
 router.back(); // navigate to users/1
 router.forward(); // navigate to users/2
 router.go(-2); // navigate to home

package/dist/cjs/index.d.ts

@@ -1,6 +1,11 @@
 import { PluginFactory } from "@real-router/core";
 
 //#region src/types.d.ts
+type MemoryDirection = "back" | "forward" | "navigate";
+interface MemoryContext {
+  direction: MemoryDirection;
+  historyIndex: number;
+}
 interface MemoryPluginOptions {
   maxHistoryLength?: number;
 }
@@ -9,6 +14,11 @@ interface MemoryPluginOptions {
 declare function memoryPluginFactory(options?: MemoryPluginOptions): PluginFactory;
 //#endregion
 //#region src/index.d.ts
+declare module "@real-router/types" {
+  interface StateContext {
+    memory?: MemoryContext;
+  }
+}
 declare module "@real-router/core" {
   interface Router {
     back: () => void;
@@ -19,5 +29,5 @@ declare module "@real-router/core" {
   }
 } //# sourceMappingURL=index.d.ts.map
 //#endregion
-export { type MemoryPluginOptions, memoryPluginFactory };
+export { type MemoryContext, type MemoryDirection, type MemoryPluginOptions, memoryPluginFactory };
 //# 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":";;;UAEiB,mBAAA;EACf,gBAAA;AAAA;;;iBCIc,mBAAA,CACd,OAAA,GAAS,mBAAA,GACR,aAAA;;;;YCJS,MAAA;IACR,IAAA;IACA,OAAA;IACA,EAAA,GAAK,KAAA;IACL,SAAA;IACA,YAAA;EAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types.ts","../../src/factory.ts","../../src/index.ts"],"mappings":";;;KAEY,eAAA;AAAA,UAEK,aAAA;EACf,SAAA,EAAW,eAAA;EACX,YAAA;AAAA;AAAA,UAGe,mBAAA;EACf,gBAAA;AAAA;;;iBCHc,mBAAA,CACd,OAAA,GAAS,mBAAA,GACR,aAAA;;;;YCAS,YAAA;IACR,MAAA,GAJa,aAAA;EAAA;AAAA;AAAA;EAAA,UASL,MAAA;IACR,IAAA;IACA,OAAA;IACA,EAAA,GAAK,KAAA;IACL,SAAA;IACA,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`);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;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@real-router/core/api`);var t=class{#e;#t;#n=[];#r;#i;#a=-1;#o=!1;#s=`navigate`;#c=0;#l=!1;constructor(e,t,n){this.#e=e,this.#t=n.maxHistoryLength??1e3,this.#i=t.claimContextNamespace(`memory`),this.#r=t.extendRouter({back:()=>{this.#d(-1)},forward:()=>{this.#d(1)},go:e=>{this.#d(e)},canGoBack:()=>this.#a>0,canGoForward:()=>this.#a<this.#n.length-1})}getPlugin(){return{onTransitionSuccess:(e,t,n)=>{if(this.#o){this.#u(e,this.#s);return}let r={name:e.name,params:e.params,path:e.path};if(n.replace&&this.#a>=0)this.#n[this.#a]=r;else if(this.#n.length=this.#a+1,this.#n.push(r),this.#a=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.#a=Math.max(0,this.#a-e)}this.#u(e,`navigate`)},onStop:()=>{this.#f()},teardown:()=>{this.#l||(this.#l=!0,this.#r(),this.#i.release(),this.#f())}}}#u(e,t){this.#i.write(e,Object.freeze({direction:t,historyIndex:this.#a}))}#d(e){if(e===0||!Number.isFinite(e)||!Number.isInteger(e))return;let t=this.#a+e;if(t<0||t>=this.#n.length)return;let n=this.#n[t],r=this.#e.getState();if(n.path===r?.path){this.#a=t;return}let i=this.#a,a=++this.#c;this.#s=e>0?`forward`:`back`,this.#o=!0,this.#a=t,this.#e.navigate(n.name,n.params,{replace:!0}).catch(()=>{this.#c===a&&(this.#a=i)}).finally(()=>{this.#c===a&&(this.#o=!1)})}#f(){this.#n.length=0,this.#a=-1}};function n(n={}){if(n.maxHistoryLength!==void 0){let e=n.maxHistoryLength;if(typeof e!=`number`||!Number.isFinite(e)||!Number.isInteger(e)||e<0)throw TypeError(`[memory-plugin] Invalid maxHistoryLength: expected non-negative integer, got ${String(e)}.`)}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

@@ -1 +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"}
+{"version":3,"file":"index.js","names":["#router","#maxHistory","#entries","#removeExtensions","#claim","#go","#index","#navigatingFromHistory","#writeMemoryContext","#pendingDirection","#clear","#disposed","#goGeneration"],"sources":["../../src/plugin.ts","../../src/factory.ts"],"sourcesContent":["import type {\n  HistoryEntry,\n  MemoryContext,\n  MemoryDirection,\n  MemoryPluginOptions,\n} 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\n/** @internal — instantiated by `memoryPluginFactory`; not part of the public API. */\nexport class MemoryPlugin {\n  readonly #router: Router;\n  readonly #maxHistory: number;\n  readonly #entries: HistoryEntry[] = [];\n  readonly #removeExtensions: () => void;\n  readonly #claim: {\n    write: (state: State, value: MemoryContext) => void;\n    release: () => void;\n  };\n  #index = -1;\n  #navigatingFromHistory = false;\n  #pendingDirection: MemoryDirection = \"navigate\";\n  #goGeneration = 0;\n  #disposed = false;\n\n  constructor(router: Router, api: PluginApi, options: MemoryPluginOptions) {\n    this.#router = router;\n    this.#maxHistory = options.maxHistoryLength ?? DEFAULT_MAX_HISTORY;\n    this.#claim = api.claimContextNamespace(\"memory\");\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          this.#writeMemoryContext(toState, this.#pendingDirection);\n\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.length = 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        this.#writeMemoryContext(toState, \"navigate\");\n      },\n\n      onStop: () => {\n        this.#clear();\n      },\n\n      teardown: () => {\n        /* v8 ignore next 3 -- @preserve: core's unsubscribe() already guards via `unsubscribed` flag; this idempotency check covers router.dispose() + unsubscribe() ordering edge cases */\n        if (this.#disposed) {\n          return;\n        }\n\n        this.#disposed = true;\n        this.#removeExtensions();\n        this.#claim.release();\n        this.#clear();\n      },\n    };\n  }\n\n  #writeMemoryContext(toState: State, direction: MemoryDirection): void {\n    this.#claim.write(\n      toState,\n      Object.freeze({ direction, historyIndex: this.#index }),\n    );\n  }\n\n  #go(delta: number): void {\n    if (delta === 0 || !Number.isFinite(delta) || !Number.isInteger(delta)) {\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.#pendingDirection = delta > 0 ? \"forward\" : \"back\";\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 (options.maxHistoryLength !== undefined) {\n    const length = options.maxHistoryLength;\n\n    if (\n      typeof length !== \"number\" ||\n      !Number.isFinite(length) ||\n      !Number.isInteger(length) ||\n      length < 0\n    ) {\n      throw new TypeError(\n        `[memory-plugin] Invalid maxHistoryLength: expected non-negative integer, got ${String(length)}.`,\n      );\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":"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"}

package/dist/esm/index.d.mts

@@ -1,6 +1,11 @@
 import { PluginFactory } from "@real-router/core";
 
 //#region src/types.d.ts
+type MemoryDirection = "back" | "forward" | "navigate";
+interface MemoryContext {
+  direction: MemoryDirection;
+  historyIndex: number;
+}
 interface MemoryPluginOptions {
   maxHistoryLength?: number;
 }
@@ -9,6 +14,11 @@ interface MemoryPluginOptions {
 declare function memoryPluginFactory(options?: MemoryPluginOptions): PluginFactory;
 //#endregion
 //#region src/index.d.ts
+declare module "@real-router/types" {
+  interface StateContext {
+    memory?: MemoryContext;
+  }
+}
 declare module "@real-router/core" {
   interface Router {
     back: () => void;
@@ -19,5 +29,5 @@ declare module "@real-router/core" {
   }
 } //# sourceMappingURL=index.d.ts.map
 //#endregion
-export { type MemoryPluginOptions, memoryPluginFactory };
+export { type MemoryContext, type MemoryDirection, type MemoryPluginOptions, memoryPluginFactory };
 //# 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":";;;UAEiB,mBAAA;EACf,gBAAA;AAAA;;;iBCIc,mBAAA,CACd,OAAA,GAAS,mBAAA,GACR,aAAA;;;;YCJS,MAAA;IACR,IAAA;IACA,OAAA;IACA,EAAA,GAAK,KAAA;IACL,SAAA;IACA,YAAA;EAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/types.ts","../../src/factory.ts","../../src/index.ts"],"mappings":";;;KAEY,eAAA;AAAA,UAEK,aAAA;EACf,SAAA,EAAW,eAAA;EACX,YAAA;AAAA;AAAA,UAGe,mBAAA;EACf,gBAAA;AAAA;;;iBCHc,mBAAA,CACd,OAAA,GAAS,mBAAA,GACR,aAAA;;;;YCAS,YAAA;IACR,MAAA,GAJa,aAAA;EAAA;AAAA;AAAA;EAAA,UASL,MAAA;IACR,IAAA;IACA,OAAA;IACA,EAAA,GAAK,KAAA;IACL,SAAA;IACA,YAAA;EAAA;AAAA"}

package/dist/esm/index.mjs

@@ -1,2 +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};
+import{getPluginApi as e}from"@real-router/core/api";var t=class{#e;#t;#n=[];#r;#i;#a=-1;#o=!1;#s=`navigate`;#c=0;#l=!1;constructor(e,t,n){this.#e=e,this.#t=n.maxHistoryLength??1e3,this.#i=t.claimContextNamespace(`memory`),this.#r=t.extendRouter({back:()=>{this.#d(-1)},forward:()=>{this.#d(1)},go:e=>{this.#d(e)},canGoBack:()=>this.#a>0,canGoForward:()=>this.#a<this.#n.length-1})}getPlugin(){return{onTransitionSuccess:(e,t,n)=>{if(this.#o){this.#u(e,this.#s);return}let r={name:e.name,params:e.params,path:e.path};if(n.replace&&this.#a>=0)this.#n[this.#a]=r;else if(this.#n.length=this.#a+1,this.#n.push(r),this.#a=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.#a=Math.max(0,this.#a-e)}this.#u(e,`navigate`)},onStop:()=>{this.#f()},teardown:()=>{this.#l||(this.#l=!0,this.#r(),this.#i.release(),this.#f())}}}#u(e,t){this.#i.write(e,Object.freeze({direction:t,historyIndex:this.#a}))}#d(e){if(e===0||!Number.isFinite(e)||!Number.isInteger(e))return;let t=this.#a+e;if(t<0||t>=this.#n.length)return;let n=this.#n[t],r=this.#e.getState();if(n.path===r?.path){this.#a=t;return}let i=this.#a,a=++this.#c;this.#s=e>0?`forward`:`back`,this.#o=!0,this.#a=t,this.#e.navigate(n.name,n.params,{replace:!0}).catch(()=>{this.#c===a&&(this.#a=i)}).finally(()=>{this.#c===a&&(this.#o=!1)})}#f(){this.#n.length=0,this.#a=-1}};function n(n={}){if(n.maxHistoryLength!==void 0){let e=n.maxHistoryLength;if(typeof e!=`number`||!Number.isFinite(e)||!Number.isInteger(e)||e<0)throw TypeError(`[memory-plugin] Invalid maxHistoryLength: expected non-negative integer, got ${String(e)}.`)}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

@@ -1 +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"}
+{"version":3,"file":"index.mjs","names":["#router","#maxHistory","#entries","#removeExtensions","#claim","#go","#index","#navigatingFromHistory","#writeMemoryContext","#pendingDirection","#clear","#disposed","#goGeneration"],"sources":["../../src/plugin.ts","../../src/factory.ts"],"sourcesContent":["import type {\n  HistoryEntry,\n  MemoryContext,\n  MemoryDirection,\n  MemoryPluginOptions,\n} 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\n/** @internal — instantiated by `memoryPluginFactory`; not part of the public API. */\nexport class MemoryPlugin {\n  readonly #router: Router;\n  readonly #maxHistory: number;\n  readonly #entries: HistoryEntry[] = [];\n  readonly #removeExtensions: () => void;\n  readonly #claim: {\n    write: (state: State, value: MemoryContext) => void;\n    release: () => void;\n  };\n  #index = -1;\n  #navigatingFromHistory = false;\n  #pendingDirection: MemoryDirection = \"navigate\";\n  #goGeneration = 0;\n  #disposed = false;\n\n  constructor(router: Router, api: PluginApi, options: MemoryPluginOptions) {\n    this.#router = router;\n    this.#maxHistory = options.maxHistoryLength ?? DEFAULT_MAX_HISTORY;\n    this.#claim = api.claimContextNamespace(\"memory\");\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          this.#writeMemoryContext(toState, this.#pendingDirection);\n\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.length = 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        this.#writeMemoryContext(toState, \"navigate\");\n      },\n\n      onStop: () => {\n        this.#clear();\n      },\n\n      teardown: () => {\n        /* v8 ignore next 3 -- @preserve: core's unsubscribe() already guards via `unsubscribed` flag; this idempotency check covers router.dispose() + unsubscribe() ordering edge cases */\n        if (this.#disposed) {\n          return;\n        }\n\n        this.#disposed = true;\n        this.#removeExtensions();\n        this.#claim.release();\n        this.#clear();\n      },\n    };\n  }\n\n  #writeMemoryContext(toState: State, direction: MemoryDirection): void {\n    this.#claim.write(\n      toState,\n      Object.freeze({ direction, historyIndex: this.#index }),\n    );\n  }\n\n  #go(delta: number): void {\n    if (delta === 0 || !Number.isFinite(delta) || !Number.isInteger(delta)) {\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.#pendingDirection = delta > 0 ? \"forward\" : \"back\";\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 (options.maxHistoryLength !== undefined) {\n    const length = options.maxHistoryLength;\n\n    if (\n      typeof length !== \"number\" ||\n      !Number.isFinite(length) ||\n      !Number.isInteger(length) ||\n      length < 0\n    ) {\n      throw new TypeError(\n        `[memory-plugin] Invalid maxHistoryLength: expected non-negative integer, got ${String(length)}.`,\n      );\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":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/memory-plugin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "commonjs",
   "description": "In-memory history engine for Real-Router — non-browser environments and benchmarks",
   "main": "./dist/cjs/index.js",
@@ -45,15 +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": {
     "test": "vitest",
     "test:properties": "vitest --config vitest.config.properties.mts --run",
-    "build": "tsdown --config-loader unrun",
+    "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

@@ -8,14 +8,19 @@ 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)}.`,
-    );
+  if (options.maxHistoryLength !== undefined) {
+    const length = options.maxHistoryLength;
+
+    if (
+      typeof length !== "number" ||
+      !Number.isFinite(length) ||
+      !Number.isInteger(length) ||
+      length < 0
+    ) {
+      throw new TypeError(
+        `[memory-plugin] Invalid maxHistoryLength: expected non-negative integer, got ${String(length)}.`,
+      );
+    }
   }
 
   const frozenOptions: MemoryPluginOptions = Object.freeze({ ...options });

package/src/index.ts

@@ -1,6 +1,16 @@
 export { memoryPluginFactory } from "./factory";
 
-export type { MemoryPluginOptions } from "./types";
+export type {
+  MemoryPluginOptions,
+  MemoryContext,
+  MemoryDirection,
+} from "./types";
+
+declare module "@real-router/types" {
+  interface StateContext {
+    memory?: import("./types").MemoryContext;
+  }
+}
 
 declare module "@real-router/core" {
   interface Router {

package/src/plugin.ts

@@ -1,4 +1,9 @@
-import type { HistoryEntry, MemoryPluginOptions } from "./types";
+import type {
+  HistoryEntry,
+  MemoryContext,
+  MemoryDirection,
+  MemoryPluginOptions,
+} from "./types";
 import type {
   NavigationOptions,
   Plugin,
@@ -9,18 +14,26 @@ import type { PluginApi } from "@real-router/core/api";
 
 const DEFAULT_MAX_HISTORY = 1000;
 
+/** @internal — instantiated by `memoryPluginFactory`; not part of the public API. */
 export class MemoryPlugin {
   readonly #router: Router;
   readonly #maxHistory: number;
   readonly #entries: HistoryEntry[] = [];
   readonly #removeExtensions: () => void;
+  readonly #claim: {
+    write: (state: State, value: MemoryContext) => void;
+    release: () => void;
+  };
   #index = -1;
   #navigatingFromHistory = false;
+  #pendingDirection: MemoryDirection = "navigate";
   #goGeneration = 0;
+  #disposed = false;
 
   constructor(router: Router, api: PluginApi, options: MemoryPluginOptions) {
     this.#router = router;
     this.#maxHistory = options.maxHistoryLength ?? DEFAULT_MAX_HISTORY;
+    this.#claim = api.claimContextNamespace("memory");
 
     this.#removeExtensions = api.extendRouter({
       back: () => {
@@ -45,6 +58,8 @@ export class MemoryPlugin {
         opts: NavigationOptions,
       ) => {
         if (this.#navigatingFromHistory) {
+          this.#writeMemoryContext(toState, this.#pendingDirection);
+
           return;
         }
 
@@ -57,7 +72,7 @@ export class MemoryPlugin {
         if (opts.replace && this.#index >= 0) {
           this.#entries[this.#index] = entry;
         } else {
-          this.#entries.splice(this.#index + 1);
+          this.#entries.length = this.#index + 1;
           this.#entries.push(entry);
           this.#index = this.#entries.length - 1;
 
@@ -68,6 +83,8 @@ export class MemoryPlugin {
             this.#index = Math.max(0, this.#index - overflow);
           }
         }
+
+        this.#writeMemoryContext(toState, "navigate");
       },
 
       onStop: () => {
@@ -75,14 +92,28 @@ export class MemoryPlugin {
       },
 
       teardown: () => {
+        /* v8 ignore next 3 -- @preserve: core's unsubscribe() already guards via `unsubscribed` flag; this idempotency check covers router.dispose() + unsubscribe() ordering edge cases */
+        if (this.#disposed) {
+          return;
+        }
+
+        this.#disposed = true;
         this.#removeExtensions();
+        this.#claim.release();
         this.#clear();
       },
     };
   }
 
+  #writeMemoryContext(toState: State, direction: MemoryDirection): void {
+    this.#claim.write(
+      toState,
+      Object.freeze({ direction, historyIndex: this.#index }),
+    );
+  }
+
   #go(delta: number): void {
-    if (delta === 0) {
+    if (delta === 0 || !Number.isFinite(delta) || !Number.isInteger(delta)) {
       return;
     }
 
@@ -104,6 +135,7 @@ export class MemoryPlugin {
     const previousIndex = this.#index;
     const generation = ++this.#goGeneration;
 
+    this.#pendingDirection = delta > 0 ? "forward" : "back";
     this.#navigatingFromHistory = true;
     this.#index = targetIndex;
 

package/src/types.ts

@@ -1,5 +1,12 @@
 import type { Params } from "@real-router/core";
 
+export type MemoryDirection = "back" | "forward" | "navigate";
+
+export interface MemoryContext {
+  direction: MemoryDirection;
+  historyIndex: number;
+}
+
 export interface MemoryPluginOptions {
   maxHistoryLength?: number;
 }