@real-router/memory-plugin 0.4.5 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/memory-plugin",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "type": "commonjs",
   "description": "In-memory history engine for Real-Router — non-browser environments and benchmarks",
   "main": "./dist/cjs/index.js",
@@ -18,8 +18,7 @@
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "repository": {
     "type": "git",
@@ -45,7 +44,7 @@
   "homepage": "https://github.com/greydragon888/real-router",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.56.0",
+    "@real-router/core": "^0.57.0",
     "@real-router/types": "^0.36.0"
   },
   "scripts": {

package/src/factory.ts

@@ -1,34 +0,0 @@
-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) {
-    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 });
-
-  return (router): Plugin => {
-    const api = getPluginApi(router);
-    const plugin = new MemoryPlugin(router as Router, api, frozenOptions);
-
-    return plugin.getPlugin();
-  };
-}

package/src/index.ts

@@ -1,23 +0,0 @@
-export { memoryPluginFactory } from "./factory";
-
-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 {
-    back: () => void;
-    forward: () => void;
-    go: (delta: number) => void;
-    canGoBack: () => boolean;
-    canGoForward: () => boolean;
-  }
-}

package/src/plugin.ts

@@ -1,188 +0,0 @@
-import type {
-  MemoryContext,
-  MemoryDirection,
-  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;
-
-/** @internal — instantiated by `memoryPluginFactory`; not part of the public API. */
-export class MemoryPlugin {
-  readonly #router: Router;
-  readonly #api: PluginApi;
-  readonly #maxHistory: number;
-  // Stored entries are full State snapshots (#561). Snapshot semantics for
-  // back/forward replay: api.navigateToState commits the stored State as-is,
-  // immune to post-recording route mutations (routes.update / routes.replace
-  // changing defaultParams or meta) and to non-idempotent dynamic
-  // forwardFn / buildPath interceptors. Activation guards still run at
-  // replay time — that is where current-world-state checks belong, not in
-  // the navigation pipeline.
-  readonly #entries: State[] = [];
-  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.#api = api;
-    this.#maxHistory = options.maxHistoryLength ?? DEFAULT_MAX_HISTORY;
-    this.#claim = api.claimContextNamespace("memory");
-
-    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) {
-          this.#writeMemoryContext(toState, this.#pendingDirection);
-
-          return;
-        }
-
-        if (opts.replace && this.#index >= 0) {
-          this.#entries[this.#index] = toState;
-        } else {
-          this.#entries.length = this.#index + 1;
-          this.#entries.push(toState);
-          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);
-          }
-        }
-
-        this.#writeMemoryContext(toState, "navigate");
-      },
-
-      onStop: () => {
-        // Bump generation so any in-flight #go settler observes a mismatch
-        // and skips its revert / flag reset — writing into cleared state
-        // would otherwise leave #index pointing into an empty #entries (#505).
-        this.#goGeneration++;
-        this.#clear();
-      },
-
-      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;
-        // Same generation bump as onStop — pre-teardown in-flight #go settlers
-        // must not write into a released plugin (#505).
-        this.#goGeneration++;
-        this.#removeExtensions();
-        this.#claim.release();
-        this.#clear();
-      },
-    };
-  }
-
-  #writeMemoryContext(toState: State, direction: MemoryDirection): void {
-    this.#claim.write(toState, { direction, historyIndex: this.#index });
-  }
-
-  #go(delta: number): void {
-    if (!Number.isInteger(delta) || 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) {
-      // Short-circuit: landing on an entry whose path matches the current
-      // state skips api.navigateToState. Still rewrite state.context.memory
-      // so subscribers see the new historyIndex + direction — otherwise
-      // UI animation driven by `direction` sees a stale "navigate" value
-      // and `state.context.memory.historyIndex` diverges from `#index`
-      // until the next full transition (#508).
-      this.#index = targetIndex;
-      this.#writeMemoryContext(currentState, delta > 0 ? "forward" : "back");
-
-      return;
-    }
-
-    const previousIndex = this.#index;
-    const generation = ++this.#goGeneration;
-
-    this.#pendingDirection = delta > 0 ? "forward" : "back";
-    this.#navigatingFromHistory = true;
-    this.#index = targetIndex;
-
-    // navigateToState commits the stored snapshot verbatim — same primitive
-    // every URL-driven flow uses (start, popstate, navigate-event). Skips
-    // forwardState + buildPath re-resolution and their interceptors; route
-    // mutations between record and replay do not retroactively change what
-    // back/forward commits (#561).
-    void this.#api.navigateToState(entry, { replace: true }).then(
-      () => {
-        if (this.#goGeneration === generation) {
-          this.#navigatingFromHistory = false;
-        }
-      },
-      () => {
-        if (this.#goGeneration === generation) {
-          this.#index = previousIndex;
-          this.#navigatingFromHistory = false;
-        }
-      },
-    );
-  }
-
-  #clear(): void {
-    this.#entries.length = 0;
-    this.#index = -1;
-    // Reset transient #go state as well: if #clear runs while a #go is in
-    // flight, the reject-handler skips (generation mismatch) and would
-    // otherwise leave #navigatingFromHistory stuck at true — the next
-    // onTransitionSuccess after restart would take the history-restore
-    // branch and silently skip pushing a new entry. Both fields are
-    // "current #go intent", not persistent history, so resetting them on
-    // clear is always correct (#505).
-    this.#navigatingFromHistory = false;
-    this.#pendingDirection = "navigate";
-  }
-}

package/src/types.ts

@@ -1,21 +0,0 @@
-export type MemoryDirection = "back" | "forward" | "navigate";
-
-export interface MemoryContext {
-  readonly direction: MemoryDirection;
-  readonly historyIndex: number;
-}
-
-export interface MemoryPluginOptions {
-  /**
-   * Maximum number of entries retained in the in-memory history stack.
-   *
-   * @description
-   * When set, the oldest entries are dropped once the stack grows past this
-   * length. The sentinel value `0` disables trimming (unlimited). Negatives,
-   * `NaN`, `±Infinity`, and fractional numbers are rejected at factory time
-   * with a `TypeError`.
-   *
-   * @default 1000
-   */
-  maxHistoryLength?: number;
-}