@real-router/search-schema-plugin 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/search-schema-plugin",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "commonjs",
   "description": "Runtime search parameter validation via Standard Schema for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -18,8 +18,7 @@
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "repository": {
     "type": "git",
@@ -46,7 +45,7 @@
   "homepage": "https://github.com/greydragon888/real-router",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.56.0"
+    "@real-router/core": "^0.57.0"
   },
   "scripts": {
     "test": "vitest",

package/src/constants.ts

@@ -1,3 +0,0 @@
-// packages/search-schema-plugin/src/constants.ts
-
-export const ERROR_PREFIX = "[search-schema-plugin]";

package/src/factory.ts

@@ -1,25 +0,0 @@
-import { getPluginApi, getRoutesApi } from "@real-router/core/api";
-
-import { SearchSchemaPlugin } from "./plugin";
-import { validateOptions } from "./validation";
-
-import type { SearchSchemaPluginOptions } from "./types";
-import type { PluginFactory, Plugin } from "@real-router/core";
-
-export function searchSchemaPlugin(
-  options: SearchSchemaPluginOptions = {},
-): PluginFactory {
-  validateOptions(options);
-
-  const frozenOptions: SearchSchemaPluginOptions = Object.freeze({
-    ...options,
-  });
-
-  return (router): Plugin => {
-    const pluginApi = getPluginApi(router);
-    const routesApi = getRoutesApi(router);
-    const plugin = new SearchSchemaPlugin(pluginApi, routesApi, frozenOptions);
-
-    return plugin.getPlugin();
-  };
-}

package/src/helpers.ts

@@ -1,40 +0,0 @@
-// packages/search-schema-plugin/src/helpers.ts
-
-import type { StandardSchemaV1Issue } from "./types";
-import type { Params } from "@real-router/core";
-
-/**
- * Extract top-level keys from validation issues.
- * Only processes issues with a non-empty path — issues without path
- * affect the whole object and can't be stripped by key.
- */
-export function getInvalidKeys(
-  issues: readonly StandardSchemaV1Issue[],
-): Set<string> {
-  const keys = new Set<string>();
-
-  for (const issue of issues) {
-    if (issue.path && issue.path.length > 0) {
-      const segment = issue.path[0];
-      const key =
-        typeof segment === "object" && "key" in segment ? segment.key : segment;
-
-      keys.add(String(key));
-    }
-  }
-
-  return keys;
-}
-
-/** Create a shallow copy of params without the specified keys. */
-export function omitKeys(params: Params, keys: Set<string>): Params {
-  const result: Params = {};
-
-  for (const key of Object.keys(params)) {
-    if (!keys.has(key)) {
-      result[key] = params[key];
-    }
-  }
-
-  return result;
-}

package/src/index.ts

@@ -1,16 +0,0 @@
-import type { StandardSchemaV1 } from "./types";
-
-export { searchSchemaPlugin } from "./factory";
-
-declare module "@real-router/core" {
-  interface Route {
-    searchSchema?: StandardSchemaV1;
-  }
-}
-
-export type {
-  SearchSchemaPluginOptions,
-  StandardSchemaV1,
-  StandardSchemaV1Issue,
-  StandardSchemaV1Result,
-} from "./types";

package/src/plugin.ts

@@ -1,215 +0,0 @@
-import { ERROR_PREFIX } from "./constants";
-import { getInvalidKeys, omitKeys } from "./helpers";
-
-import type {
-  SearchSchemaPluginOptions,
-  StandardSchemaV1,
-  StandardSchemaV1Issue,
-} from "./types";
-import type { Params, Plugin, TreeChangedEvent } from "@real-router/core";
-import type { PluginApi, RoutesApi } from "@real-router/core/api";
-
-export class SearchSchemaPlugin {
-  readonly #pluginApi: PluginApi;
-  readonly #routesApi: RoutesApi;
-  readonly #mode: "development" | "production";
-  readonly #strict: boolean;
-  readonly #onError:
-    | ((
-        routeName: string,
-        params: Params,
-        issues: readonly StandardSchemaV1Issue[],
-      ) => Params)
-    | undefined;
-  readonly #removeForwardStateInterceptor: () => void;
-  readonly #removeChangesSubscription: () => void;
-
-  constructor(
-    pluginApi: PluginApi,
-    routesApi: RoutesApi,
-    options: SearchSchemaPluginOptions,
-  ) {
-    this.#pluginApi = pluginApi;
-    this.#routesApi = routesApi;
-    this.#mode = options.mode ?? "development";
-    this.#strict = options.strict ?? false;
-    this.#onError = options.onError;
-
-    this.#validateExistingDefaultParams();
-
-    this.#removeForwardStateInterceptor = this.#pluginApi.addInterceptor(
-      "forwardState",
-      (next, routeName, routeParams) => {
-        const result = next(routeName, routeParams);
-
-        return this.#validateState(result);
-      },
-    );
-
-    // Dev-time defaultParams validation for runtime tree mutations. Replaces the
-    // old `add` interceptor: TREE_CHANGED additionally covers `update` (changed
-    // defaultParams) and `replace` (new route set) — the gap the interceptor
-    // could not reach. Production mode skips the subscription entirely.
-    this.#removeChangesSubscription =
-      this.#mode === "development"
-        ? this.#routesApi.subscribeChanges((event) => {
-            this.#onTreeChanged(event);
-          })
-        : () => {};
-  }
-
-  getPlugin(): Plugin {
-    return {
-      teardown: () => {
-        this.#removeForwardStateInterceptor();
-        this.#removeChangesSubscription();
-      },
-    };
-  }
-
-  #onTreeChanged(event: TreeChangedEvent): void {
-    switch (event.op) {
-      case "add":
-      case "replace": {
-        // `added` is FLAT (full dotted names, descendants included).
-        for (const route of event.added) {
-          this.#validateSingleRouteDefaultParams(route.name);
-        }
-
-        break;
-      }
-      case "update": {
-        // Only a defaultParams change can newly violate the schema.
-        if (event.patch.defaultParams !== undefined) {
-          this.#validateSingleRouteDefaultParams(event.name);
-        }
-
-        break;
-      }
-      // "remove" / "clear": the routes are gone — nothing to validate.
-    }
-  }
-
-  #getSchema(routeName: string): StandardSchemaV1 | undefined {
-    return this.#pluginApi.getRouteConfig(routeName)?.searchSchema as
-      | StandardSchemaV1
-      | undefined;
-  }
-
-  #validateState(result: { name: string; params: Params }): {
-    name: string;
-    params: Params;
-  } {
-    const schema = this.#getSchema(result.name);
-
-    if (!schema) {
-      return result;
-    }
-
-    const validation = schema["~standard"].validate(result.params);
-
-    if (validation instanceof Promise) {
-      throw new TypeError(
-        `${ERROR_PREFIX} Async schema validation is not supported. Route "${result.name}" returned a Promise from ~standard.validate().`,
-      );
-    }
-
-    if ("value" in validation) {
-      const params = this.#strict
-        ? (validation.value as Params)
-        : { ...result.params, ...(validation.value as Params) };
-
-      return { ...result, params };
-    }
-
-    if (this.#onError) {
-      return {
-        ...result,
-        params: this.#onError(result.name, result.params, validation.issues),
-      };
-    }
-
-    if (this.#mode === "development") {
-      console.error(
-        `${ERROR_PREFIX} Route "${result.name}": invalid search params`,
-        validation.issues,
-      );
-    }
-
-    const invalidKeys = getInvalidKeys(validation.issues);
-    const stripped = omitKeys(result.params, invalidKeys);
-    const route = this.#routesApi.get(result.name);
-    const defaults = route?.defaultParams;
-    const restored = defaults ? { ...defaults, ...stripped } : stripped;
-
-    return { ...result, params: restored };
-  }
-
-  #validateExistingDefaultParams(): void {
-    if (this.#mode !== "development") {
-      return;
-    }
-
-    const tree = this.#pluginApi.getTree() as unknown as
-      | { fullName?: string; children?: ReadonlyMap<string, unknown> }
-      | undefined;
-
-    /* v8 ignore next -- @preserve: getTree() always returns a RouteTree, defensive check */
-    if (!tree) {
-      return;
-    }
-
-    this.#walkTree(tree);
-  }
-
-  #walkTree(node: {
-    fullName?: string;
-    children?: ReadonlyMap<string, unknown>;
-  }): void {
-    if (node.fullName) {
-      this.#validateSingleRouteDefaultParams(node.fullName);
-    }
-
-    /* v8 ignore next 3 -- @preserve: children is always a Map in RouteTree */
-    if (node.children instanceof Map) {
-      for (const child of node.children.values()) {
-        if (child && typeof child === "object") {
-          this.#walkTree(
-            child as {
-              fullName?: string;
-              children?: ReadonlyMap<string, unknown>;
-            },
-          );
-        }
-      }
-    }
-  }
-
-  #validateSingleRouteDefaultParams(routeName: string): void {
-    const schema = this.#getSchema(routeName);
-
-    if (!schema) {
-      return;
-    }
-
-    const route = this.#routesApi.get(routeName);
-    const defaultParams = route?.defaultParams;
-
-    if (!defaultParams) {
-      return;
-    }
-
-    const validation = schema["~standard"].validate(defaultParams);
-
-    if (validation instanceof Promise) {
-      return;
-    }
-
-    if ("issues" in validation) {
-      console.warn(
-        `${ERROR_PREFIX} Route "${routeName}": defaultParams do not pass searchSchema`,
-        validation.issues,
-      );
-    }
-  }
-}

package/src/types.ts

@@ -1,91 +0,0 @@
-// packages/search-schema-plugin/src/types.ts
-
-import type { Params } from "@real-router/core";
-
-// =============================================================================
-// Standard Schema V1 (inline — zero external deps)
-// https://github.com/standard-schema/standard-schema
-// =============================================================================
-
-/** A single validation issue from Standard Schema V1. */
-export interface StandardSchemaV1Issue {
-  readonly message: string;
-  readonly path?:
-    | readonly (PropertyKey | { readonly key: PropertyKey })[]
-    | undefined;
-}
-
-/** Validation result — either success or failure. */
-export type StandardSchemaV1Result<Output = unknown> =
-  | { readonly value: Output }
-  | { readonly issues: readonly StandardSchemaV1Issue[] };
-
-/**
- * Standard Schema V1 interface.
- *
- * Supported by Zod 3.24+, Valibot 1.0+, ArkType.
- * The plugin doesn't depend on any specific schema library.
- */
-export interface StandardSchemaV1<Input = unknown, Output = Input> {
-  readonly "~standard": {
-    readonly version: 1;
-    readonly vendor: string;
-    readonly validate: (
-      value: unknown,
-    ) =>
-      | StandardSchemaV1Result<Output>
-      | Promise<StandardSchemaV1Result<Output>>;
-    readonly types?:
-      | {
-          readonly input: Input;
-          readonly output: Output;
-        }
-      | undefined;
-  };
-}
-
-// =============================================================================
-// Plugin Options
-// =============================================================================
-
-export interface SearchSchemaPluginOptions {
-  /**
-   * Error handling mode.
-   * - "development" (default): strip invalid + console.error
-   * - "production": silent strip
-   *
-   * For recovery of invalid params use defaultParams (strip + merge + diagnostics).
-   * For filling absent params use .default() in schema (no diagnostics).
-   * .catch() is not recommended — suppresses errors, mode: "development" won't see the issue.
-   */
-  readonly mode?: "development" | "production";
-
-  /**
-   * Strip search params not described in schema.
-   * - false (default): unknown params pass through
-   * - true: unknown params are removed
-   *
-   * Per-route override: .strict() / .passthrough() in Zod schema.
-   */
-  readonly strict?: boolean;
-
-  /**
-   * Custom error handler (overrides mode completely).
-   * Must return cleaned params.
-   *
-   * Contract:
-   * - Returned params are used as-is, without re-validation.
-   *   Responsibility for correctness is on the callback author.
-   *   (Re-validation would risk infinite loops.)
-   * - Exceptions from onError propagate up without suppression.
-   *   Consistent with interceptor behavior in core.
-   * - When onError is set, neither console.error (mode: "development"),
-   *   nor silent strip (mode: "production") are executed.
-   *   All responsibility for diagnostics and recovery is on the callback.
-   */
-  readonly onError?: (
-    routeName: string,
-    params: Params,
-    issues: readonly StandardSchemaV1Issue[],
-  ) => Params;
-}

package/src/validation.ts

@@ -1,25 +0,0 @@
-import { ERROR_PREFIX } from "./constants";
-
-import type { SearchSchemaPluginOptions } from "./types";
-
-const VALID_MODES = new Set(["development", "production"]);
-
-export function validateOptions(options: SearchSchemaPluginOptions): void {
-  if (options.mode !== undefined && !VALID_MODES.has(options.mode)) {
-    throw new TypeError(
-      `${ERROR_PREFIX} Invalid mode: "${options.mode}". Must be "development" or "production".`,
-    );
-  }
-
-  if (options.strict !== undefined && typeof options.strict !== "boolean") {
-    throw new TypeError(
-      `${ERROR_PREFIX} Invalid strict option: expected boolean, got ${typeof options.strict}.`,
-    );
-  }
-
-  if (options.onError !== undefined && typeof options.onError !== "function") {
-    throw new TypeError(
-      `${ERROR_PREFIX} Invalid onError: expected function, got ${typeof options.onError}.`,
-    );
-  }
-}