@real-router/search-schema-plugin 0.1.1 → 0.1.3

package/README.md

@@ -54,6 +54,20 @@ router.usePlugin(searchSchemaPlugin({ mode: "development" }));
 
 > **Schema libraries:** Any library implementing [Standard Schema V1](https://github.com/standard-schema/standard-schema) works — Zod 3.24+, Valibot 1.0+, ArkType. Install and configure your chosen library separately; the plugin has no schema-library dependency.
 
+## TypeScript Support
+
+Import `@real-router/search-schema-plugin` to enable TypeScript support for `searchSchema` on route definitions:
+
+```typescript
+import "@real-router/search-schema-plugin"; // enables Route.searchSchema type
+
+const routes = [
+  { name: "users", path: "/users", searchSchema: z.object({ page: z.number() }) },
+];
+```
+
+This works via [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) — the package extends the `Route` interface from `@real-router/core`.
+
 ## Configuration
 
 | Option    | Type                                    | Default         | Description                                                                                                                                                                                    |

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/types.ts","../../src/factory.ts","../../src/index.ts"],"mappings":";;;;UAUiB,qBAAA;EAAA,SACN,OAAA;EAAA,SACA,IAAA,aACK,WAAA;IAAA,SAAyB,GAAA,EAAK,WAAA;EAAA;AAAA;;KAKlC,sBAAA;EAAA,SACG,KAAA,EAAO,MAAA;AAAA;EAAA,SACP,MAAA,WAAiB,qBAAA;AAAA;AAFhC;;;;;;AAAA,UAUiB,gBAAA,2BAA2C,KAAA;EAAA,SACjD,WAAA;IAAA,SACE,OAAA;IAAA,SACA,MAAA;IAAA,SACA,QAAA,GACP,KAAA,cAEE,sBAAA,CAAuB,MAAA,IACvB,OAAA,CAAQ,sBAAA,CAAuB,MAAA;IAAA,SAC1B,KAAA;MAAA,SAEM,KAAA,EAAO,KAAA;MAAA,SACP,MAAA,EAAQ,MAAA;IAAA;EAAA;AAAA;AAAA,UAUV,yBAAA;EAdD;;;;;;;;;EAAA,SAwBL,IAAA;EA9BE;;;;;;;EAAA,SAuCF,MAAA;EAjC4B;;;;;;;;AAcvC;;;;;;EAduC,SAiD5B,OAAA,IACP,SAAA,UACA,MAAA,EAAQ,MAAA,EACR,MAAA,WAAiB,qBAAA,OACd,MAAA;AAAA;;;iBCjFS,kBAAA,CACd,OAAA,GAAS,yBAAA,GACR,aAAA;;;;YCLS,KAAA;IACR,YAAA,GAAe,gBAAA;EAAA;AAAA"}

package/dist/esm/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/types.ts","../../src/factory.ts","../../src/index.ts"],"mappings":";;;;UAUiB,qBAAA;EAAA,SACN,OAAA;EAAA,SACA,IAAA,aACK,WAAA;IAAA,SAAyB,GAAA,EAAK,WAAA;EAAA;AAAA;;KAKlC,sBAAA;EAAA,SACG,KAAA,EAAO,MAAA;AAAA;EAAA,SACP,MAAA,WAAiB,qBAAA;AAAA;AAFhC;;;;;;AAAA,UAUiB,gBAAA,2BAA2C,KAAA;EAAA,SACjD,WAAA;IAAA,SACE,OAAA;IAAA,SACA,MAAA;IAAA,SACA,QAAA,GACP,KAAA,cAEE,sBAAA,CAAuB,MAAA,IACvB,OAAA,CAAQ,sBAAA,CAAuB,MAAA;IAAA,SAC1B,KAAA;MAAA,SAEM,KAAA,EAAO,KAAA;MAAA,SACP,MAAA,EAAQ,MAAA;IAAA;EAAA;AAAA;AAAA,UAUV,yBAAA;EAdD;;;;;;;;;EAAA,SAwBL,IAAA;EA9BE;;;;;;;EAAA,SAuCF,MAAA;EAjC4B;;;;;;;;AAcvC;;;;;;EAduC,SAiD5B,OAAA,IACP,SAAA,UACA,MAAA,EAAQ,MAAA,EACR,MAAA,WAAiB,qBAAA,OACd,MAAA;AAAA;;;iBCjFS,kBAAA,CACd,OAAA,GAAS,yBAAA,GACR,aAAA;;;;YCLS,KAAA;IACR,YAAA,GAAe,gBAAA;EAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/search-schema-plugin",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "commonjs",
   "description": "Runtime search parameter validation via Standard Schema for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -8,7 +8,6 @@
   "types": "./dist/esm/index.d.mts",
   "exports": {
     ".": {
-      "development": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
         "require": "./dist/cjs/index.d.ts"
@@ -18,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "repository": {
     "type": "git",
@@ -45,7 +45,7 @@
   "homepage": "https://github.com/greydragon888/real-router",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.45.1"
+    "@real-router/core": "^0.46.0"
   },
   "scripts": {
     "test": "vitest",
@@ -53,7 +53,7 @@
     "build": "tsdown --config-loader unrun",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
-    "lint:package": "bash ../../scripts/publint-filter.sh",
+    "lint:package": "publint",
     "lint:types": "attw --pack .",
     "build:dist-only": "tsdown --config-loader unrun"
   }

package/src/constants.ts

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

package/src/factory.ts

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,40 @@
+// 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

@@ -0,0 +1,16 @@
+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

@@ -0,0 +1,208 @@
+import { ERROR_PREFIX } from "./constants";
+import { getInvalidKeys, omitKeys } from "./helpers";
+
+import type {
+  SearchSchemaPluginOptions,
+  StandardSchemaV1,
+  StandardSchemaV1Issue,
+} from "./types";
+import type { Params, Plugin, Route } 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 #removeAddInterceptor: () => 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);
+      },
+    );
+
+    this.#removeAddInterceptor = this.#pluginApi.addInterceptor(
+      "add",
+      (next, routes, addOptions) => {
+        next(routes, addOptions);
+        this.#validateRoutesDefaultParams(routes, addOptions?.parent);
+      },
+    );
+  }
+
+  getPlugin(): Plugin {
+    return {
+      teardown: () => {
+        this.#removeForwardStateInterceptor();
+        this.#removeAddInterceptor();
+      },
+    };
+  }
+
+  #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,
+      );
+    }
+  }
+
+  #validateRoutesDefaultParams(routes: Route[], prefix = ""): void {
+    if (this.#mode !== "development") {
+      return;
+    }
+
+    for (const route of routes) {
+      /* v8 ignore next -- @preserve: Route.name is always a non-empty string */
+      if (route.name) {
+        const fullName = prefix ? `${prefix}.${route.name}` : route.name;
+
+        this.#validateSingleRouteDefaultParams(fullName);
+
+        if (route.children) {
+          this.#validateRoutesDefaultParams(route.children, fullName);
+        }
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,91 @@
+// 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

@@ -0,0 +1,25 @@
+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}.`,
+    );
+  }
+}