@real-router/persistent-params-plugin 0.1.49 → 0.1.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/persistent-params-plugin",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "type": "commonjs",
   "description": "Persist query parameters across route transitions",
   "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.45.0"
+    "@real-router/core": "^0.45.1"
   },
   "devDependencies": {
     "type-guards": "^0.4.5"
@@ -56,7 +55,7 @@
     "build": "tsdown --config-loader unrun",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
-    "lint:package": "publint",
+    "lint:package": "bash ../../scripts/publint-filter.sh",
     "lint:types": "attw --pack .",
     "build:dist-only": "tsdown --config-loader unrun"
   }

package/src/constants.ts

@@ -1,5 +0,0 @@
-// packages/persistent-params-plugin/src/constants.ts
-
-export const LOGGER_CONTEXT = "persistent-params-plugin";
-
-export const ERROR_PREFIX = `[@real-router/${LOGGER_CONTEXT}]`;

package/src/factory.ts

@@ -1,98 +0,0 @@
-// packages/persistent-params-plugin/src/factory.ts
-
-import { getPluginApi } from "@real-router/core/api";
-
-import { PersistentParamsPlugin } from "./plugin";
-import { validateConfig } from "./validation";
-
-import type { PersistentParamsConfig } from "./types";
-import type { Params, PluginFactory, Plugin } from "@real-router/core";
-
-// Shared singleton — frozen by core on first use. Do not add properties.
-const EMPTY_PLUGIN: Plugin = {};
-const noop: PluginFactory = () => EMPTY_PLUGIN;
-
-/**
- * Factory for the persistent parameters' plugin.
- *
- * This plugin allows you to specify certain route parameters to be persisted across
- * all navigation transitions. Persisted parameters are automatically merged into
- * route parameters when building paths or states.
- *
- * Key features:
- * - Automatic persistence of query parameters across navigations
- * - Support for default values
- * - Type-safe (only primitives: string, number, boolean)
- * - Immutable internal state
- * - Protection against prototype pollution
- * - Full teardown support (can be safely unsubscribed)
- *
- * If a persisted parameter is explicitly set to `undefined` during navigation,
- * it will be removed from the persisted state and omitted from subsequent URLs.
- *
- * The plugin also adjusts the router's root path to include query parameters for
- * all persistent params, ensuring correct URL construction.
- *
- * @param params - Either an array of parameter names (strings) to persist,
- *                 or an object mapping parameter names to initial values.
- *                 If an array, initial values will be `undefined`.
- *
- * @returns A PluginFactory that creates the persistent params plugin instance.
- *
- * @example
- * // Persist parameters without default values
- * router.usePlugin(persistentParamsPlugin(['mode', 'lang']));
- *
- * @example
- * // Persist parameters with default values
- * router.usePlugin(persistentParamsPlugin({ mode: 'dev', lang: 'en' }));
- *
- * @example
- * // Removing a persisted parameter
- * router.navigate('route', { mode: undefined }); // mode will be removed
- *
- * @example
- * // Unsubscribing (full cleanup)
- * const unsubscribe = router.usePlugin(persistentParamsPlugin(['mode']));
- * unsubscribe(); // Restores original router state
- *
- * @throws {TypeError} If params is not a valid array of strings or object with primitives
- * @throws {Error} If plugin is already initialized on this router instance
- */
-export function persistentParamsPluginFactory(
-  params: PersistentParamsConfig = {},
-): PluginFactory {
-  validateConfig(params);
-
-  const paramNames = Array.isArray(params) ? params : Object.keys(params);
-
-  if (paramNames.length === 0) {
-    return noop;
-  }
-
-  const initialParams: Params = {};
-
-  if (Array.isArray(params)) {
-    for (const param of params) {
-      initialParams[param] = undefined;
-    }
-  } else {
-    Object.assign(initialParams, params);
-  }
-
-  Object.freeze(initialParams);
-
-  const paramNamesSet = new Set<string>(paramNames);
-
-  return (router): Plugin => {
-    const api = getPluginApi(router);
-    const plugin = new PersistentParamsPlugin(
-      api,
-      initialParams,
-      new Set(paramNamesSet),
-      api.getRootPath(),
-    );
-
-    return plugin.getPlugin();
-  };
-}

package/src/index.ts

@@ -1,5 +0,0 @@
-// packages/persistent-params-plugin/src/index.ts
-
-export type { PersistentParamsConfig } from "./types";
-
-export { persistentParamsPluginFactory } from "./factory";

package/src/param-utils.ts

@@ -1,62 +0,0 @@
-// packages/persistent-params-plugin/src/param-utils.ts
-
-import type { Params } from "@real-router/core";
-
-/**
- * Safely extracts own properties from params object.
- * Uses Object.hasOwn to prevent prototype pollution attacks.
- *
- * @param params - Parameters object (may contain inherited properties)
- * @returns New object with only own properties
- *
- * @example
- * const malicious = Object.create({ __proto__: { admin: true } });
- * malicious.mode = 'dev';
- * const safe = extractOwnParams(malicious); // { mode: 'dev' } (no __proto__)
- */
-export function extractOwnParams(params: Params): Params {
-  const result: Params = {};
-
-  for (const key in params) {
-    /* v8 ignore next -- @preserve: core validates params prototype — inherited keys never reach here */
-    if (Object.hasOwn(params, key)) {
-      result[key] = params[key];
-    }
-  }
-
-  return result;
-}
-
-/**
- * Merges persistent and current parameters into a single Params object.
- *
- * IMPORTANT: `current` must be pre-sanitized via `extractOwnParams()` by the caller.
- * This function does NOT perform prototype pollution protection on its own.
- *
- * @param persistent - Frozen persistent parameters
- * @param current - Pre-sanitized current parameters (own properties only)
- */
-export function mergeParams(
-  persistent: Readonly<Params>,
-  current: Params,
-): Params {
-  const result: Params = {};
-
-  for (const key in persistent) {
-    if (Object.hasOwn(persistent, key) && persistent[key] !== undefined) {
-      result[key] = persistent[key];
-    }
-  }
-
-  for (const key of Object.keys(current)) {
-    const value = current[key];
-
-    if (value === undefined) {
-      delete result[key];
-    } else {
-      result[key] = value;
-    }
-  }
-
-  return result;
-}

package/src/plugin.ts

@@ -1,148 +0,0 @@
-// packages/persistent-params-plugin/src/plugin.ts
-
-import { ERROR_PREFIX } from "./constants";
-import { extractOwnParams, mergeParams } from "./param-utils";
-import { validateParamValue } from "./validation";
-
-import type { Params, State, Plugin } from "@real-router/core";
-import type { PluginApi } from "@real-router/core/api";
-
-export class PersistentParamsPlugin {
-  readonly #api: PluginApi;
-  readonly #paramNamesSet: Set<string>;
-  readonly #originalRootPath: string;
-  readonly #removeBuildPathInterceptor: () => void;
-  readonly #removeForwardStateInterceptor: () => void;
-
-  #persistentParams: Readonly<Params>;
-
-  constructor(
-    api: PluginApi,
-    persistentParams: Readonly<Params>,
-    paramNamesSet: Set<string>,
-    originalRootPath: string,
-  ) {
-    this.#api = api;
-    this.#persistentParams = persistentParams;
-    this.#paramNamesSet = paramNamesSet;
-    this.#originalRootPath = originalRootPath;
-
-    let removeBuildPath: (() => void) | undefined;
-    let removeForwardState: (() => void) | undefined;
-
-    try {
-      api.setRootPath(`${originalRootPath}?${[...paramNamesSet].join("&")}`);
-
-      removeBuildPath = api.addInterceptor(
-        "buildPath",
-        (next, route, navParams) =>
-          next(route, this.#withPersistentParams(navParams ?? {})),
-      );
-
-      removeForwardState = api.addInterceptor(
-        "forwardState",
-        (next, routeName, routeParams) => {
-          const result = next(routeName, routeParams);
-
-          return {
-            ...result,
-            params: this.#withPersistentParams(result.params),
-          };
-        },
-      );
-    } /* v8 ignore start -- @preserve: rollback on partial initialization failure */ catch (error) {
-      removeBuildPath?.();
-      removeForwardState?.();
-      api.setRootPath(originalRootPath);
-
-      throw new Error(
-        `${ERROR_PREFIX} Failed to initialize: ${error instanceof Error ? error.message : String(error)}`,
-        { cause: error },
-      );
-    } /* v8 ignore stop */
-
-    this.#removeBuildPathInterceptor = removeBuildPath;
-    this.#removeForwardStateInterceptor = removeForwardState;
-  }
-
-  getPlugin(): Plugin {
-    return {
-      onTransitionSuccess: (toState) => {
-        this.#onTransitionSuccess(toState);
-      },
-      teardown: () => {
-        this.#teardown();
-      },
-    };
-  }
-
-  #withPersistentParams(additionalParams: Params): Params {
-    const safeParams = extractOwnParams(additionalParams);
-    let newParams: Params | undefined;
-
-    for (const key of Object.keys(safeParams)) {
-      const value = safeParams[key];
-
-      if (value === undefined && this.#paramNamesSet.has(key)) {
-        this.#paramNamesSet.delete(key);
-        newParams ??= { ...this.#persistentParams };
-        delete newParams[key];
-      } else {
-        validateParamValue(key, value);
-      }
-    }
-
-    if (newParams) {
-      this.#persistentParams = Object.freeze(newParams);
-    }
-
-    return mergeParams(this.#persistentParams, safeParams);
-  }
-
-  #onTransitionSuccess(toState: State): void {
-    let newParams: Params | undefined;
-
-    for (const key of this.#paramNamesSet) {
-      const value = toState.params[key];
-
-      if (!Object.hasOwn(toState.params, key) || value === undefined) {
-        /* v8 ignore next 4 -- @preserve: defensive removal for states committed via navigateToState bypassing forwardState */
-        if (
-          Object.hasOwn(this.#persistentParams, key) &&
-          this.#persistentParams[key] !== undefined
-        ) {
-          newParams ??= { ...this.#persistentParams };
-          delete newParams[key];
-        }
-
-        continue;
-      }
-
-      validateParamValue(key, value);
-
-      if (this.#persistentParams[key] !== value) {
-        newParams ??= { ...this.#persistentParams };
-        newParams[key] = value;
-      }
-    }
-
-    if (newParams) {
-      this.#persistentParams = Object.freeze(newParams);
-    }
-  }
-
-  #teardown(): void {
-    this.#removeBuildPathInterceptor();
-    this.#removeForwardStateInterceptor();
-
-    /* v8 ignore start -- @preserve: setRootPath throws RouterError(ROUTER_DISPOSED) during router.dispose() */
-    try {
-      this.#api.setRootPath(this.#originalRootPath);
-    } catch {
-      // Expected during router.dispose(): FSM enters DISPOSED before plugin teardown,
-      // so setRootPath's throwIfDisposed() check throws. Restoring rootPath on a
-      // destroyed router is unnecessary — swallow silently.
-    }
-    /* v8 ignore stop */
-  }
-}

package/src/types.ts

@@ -1,17 +0,0 @@
-// packages/persistent-params-plugin/src/types.ts
-
-/**
- * Configuration for persistent parameters' plugin.
- * Can be either an array of parameter names or an object with default values.
- *
- * @example
- * // Array of parameter names (initial values undefined)
- * persistentParamsPlugin(['lang', 'theme'])
- *
- * @example
- * // Object with default values
- * persistentParamsPlugin({ lang: 'en', theme: 'light' })
- */
-export type PersistentParamsConfig =
-  | string[]
-  | Record<string, string | number | boolean>;

package/src/validation.ts

@@ -1,130 +0,0 @@
-// packages/persistent-params-plugin/src/validation.ts
-
-import { isPrimitiveValue } from "type-guards";
-
-import { ERROR_PREFIX } from "./constants";
-
-import type { PersistentParamsConfig } from "./types";
-
-const INVALID_PARAM_KEY_REGEX = /[\s#%&/=?\\]/;
-const INVALID_CHARS_MESSAGE = String.raw`Cannot contain: = & ? # % / \ or whitespace`;
-
-export function validateParamKey(key: string): void {
-  if (INVALID_PARAM_KEY_REGEX.test(key)) {
-    throw new TypeError(
-      `${ERROR_PREFIX} Invalid parameter name "${key}". ${INVALID_CHARS_MESSAGE}`,
-    );
-  }
-}
-
-/**
- * Validates params configuration structure and values.
- * Ensures all parameter names are non-empty strings and all default values are primitives.
- *
- * @param config - Configuration to validate
- * @returns true if configuration is valid
- */
-export function isValidParamsConfig(
-  config: unknown,
-): config is PersistentParamsConfig {
-  if (config === null || config === undefined) {
-    return false;
-  }
-
-  // Array configuration: all items must be non-empty strings
-  if (Array.isArray(config)) {
-    return config.every((item) => {
-      if (typeof item !== "string" || item.length === 0) {
-        return false;
-      }
-
-      try {
-        validateParamKey(item);
-
-        return true;
-      } catch {
-        return false;
-      }
-    });
-  }
-
-  // Object configuration: must be plain object with primitive values
-  if (typeof config === "object") {
-    // Reject non-plain objects (Date, Map, etc.)
-    if (Object.getPrototypeOf(config) !== Object.prototype) {
-      return false;
-    }
-
-    // All keys must be non-empty strings, all values must be primitives
-    return Object.entries(config).every(([key, value]) => {
-      // Check key is non-empty string
-      if (typeof key !== "string" || key.length === 0) {
-        return false;
-      }
-
-      // Validate key doesn't contain special characters
-      try {
-        validateParamKey(key);
-      } catch {
-        return false;
-      }
-
-      // Validate value is primitive (NaN/Infinity already rejected by isPrimitiveValue)
-      return isPrimitiveValue(value);
-    });
-  }
-
-  return false;
-}
-
-/**
- * Validates parameter value before persisting.
- * Throws descriptive TypeError if value is not valid for URL parameters.
- *
- * @param key - Parameter name for error messages
- * @param value - Value to validate
- * @throws {TypeError} If value is null, array, object, or other non-primitive type
- */
-export function validateParamValue(key: string, value: unknown): void {
-  if (value === null) {
-    throw new TypeError(
-      `${ERROR_PREFIX} Parameter "${key}" cannot be null. ` +
-        `Use undefined to remove the parameter from persistence.`,
-    );
-  }
-
-  if (value !== undefined && !isPrimitiveValue(value)) {
-    const actualType = Array.isArray(value) ? "array" : typeof value;
-
-    throw new TypeError(
-      `${ERROR_PREFIX} Parameter "${key}" must be a primitive value ` +
-        `(string, number, or boolean), got ${actualType}. ` +
-        `Objects and arrays are not supported in URL parameters.`,
-    );
-  }
-}
-
-/**
- * Validates the params configuration and throws a descriptive error if invalid.
- *
- * @param params - Configuration to validate
- * @throws {TypeError} If params is not a valid configuration
- */
-export function validateConfig(params: unknown): void {
-  if (!isValidParamsConfig(params)) {
-    let actualType: string;
-
-    if (params === null) {
-      actualType = "null";
-    } else if (Array.isArray(params)) {
-      actualType = "array with invalid items";
-    } else {
-      actualType = typeof params;
-    }
-
-    throw new TypeError(
-      `${ERROR_PREFIX} Invalid params configuration. ` +
-        `Expected array of non-empty strings or object with primitive values, got ${actualType}.`,
-    );
-  }
-}