@ovineko/react-router 0.0.1

package/README.md

@@ -0,0 +1,287 @@
+# @ovineko/react-router
+
+Type-safe wrapper for React Router v7 with valibot schema validation, automatic error handling, and typed params.
+
+## Install
+
+```bash
+pnpm add @ovineko/react-router valibot
+```
+
+Peer dependencies: `react@^19`, `react-router@^7`, `valibot@^1`.
+
+## Features
+
+- ✅ **Valibot schema validation** - Runtime validation for URL params and search params
+- ✅ **Two hook variants** - Normal hooks (auto-redirect on error) and Raw hooks (manual error handling)
+- ✅ **Smart validation** - Ignores extra query params and invalid optional params
+- ✅ **Global error handling** - Configure fallback redirect URLs globally or per-route
+- ✅ **Type-safe** - Full TypeScript support with inferred types
+- ✅ **Hash support** - Generate paths with hash fragments
+
+## Quick Start
+
+```tsx
+import { createRouteWithParams } from "@ovineko/react-router";
+import * as v from "valibot";
+
+const userRoute = createRouteWithParams("/users/:id", {
+  params: v.object({ id: v.pipe(v.string(), v.uuid()) }),
+  searchParams: v.object({
+    tab: v.optional(v.string()),
+    page: v.optional(v.pipe(v.string(), v.transform(Number), v.number())),
+  }),
+  errorRedirect: "/404", // Optional: redirect on validation error
+});
+
+// Normal hooks - auto-redirect on validation error
+function UserPage() {
+  const params = userRoute.useParams(); // Readonly<{ id: string }>
+  const [searchParams, setSearchParams] = userRoute.useSearchParams();
+
+  return (
+    <div>
+      User {params.id}, Page {searchParams.page ?? 1}
+    </div>
+  );
+}
+
+// Raw hooks - manual error handling
+function AdvancedUserPage() {
+  const [params, error] = userRoute.useParamsRaw();
+  const { data, error: searchError } = userRoute.useSearchParamsRaw();
+
+  if (error) return <div>Invalid user ID</div>;
+  if (searchError) console.warn("Invalid search params", searchError);
+
+  return <div>User {params?.id}</div>;
+}
+```
+
+## Global Error Redirect
+
+Configure a global fallback URL for validation errors:
+
+```tsx
+import { setGlobalErrorRedirect } from "@ovineko/react-router";
+
+// In your app entry point
+setGlobalErrorRedirect("/error");
+
+// Priority: route-level > global > default "/"
+const route = createRouteWithParams("/users/:id", {
+  params: v.object({ id: v.string() }),
+  errorRedirect: "/404", // Overrides global
+});
+```
+
+## Validation Behavior
+
+### Path Params
+
+- Always strict validation
+- Redirect on any validation error
+
+### Search Params
+
+- **Extra params** (not in schema) → ignored
+- **Invalid optional params** → ignored (treated as undefined)
+- **Invalid required params** → error (triggers redirect)
+
+```tsx
+const route = createRouteWithParams("/search", {
+  params: v.object({}),
+  searchParams: v.object({
+    q: v.string(), // required
+    page: v.optional(v.pipe(v.string(), v.transform(Number), v.number())),
+  }),
+});
+
+// URL: /search?q=react&page=invalid&debug=true
+// Result: { q: "react", page: undefined }
+// - page=invalid ignored (optional + invalid)
+// - debug=true ignored (not in schema)
+```
+
+## API Reference
+
+### Route Creation
+
+#### `createRouteWithParams`
+
+```tsx
+const route = createRouteWithParams<TParams, TSearchParams>(pattern, config);
+```
+
+**Config:**
+
+- `params` - Valibot schema for URL params (required)
+- `searchParams?` - Valibot schema for search params (optional)
+- `errorRedirect?` - Redirect URL on validation error (optional)
+
+**Returns:**
+
+- `path(params, searchParams?, hash?)` - Generate URL path
+- `parseURLParams(url)` - Parse and validate URL params
+- `Link` - Type-safe Link component
+- `useParams()` - Get validated params (auto-redirect on error)
+- `useParamsRaw()` - Get params with error info `[data, error]`
+- `useSearchParams()` - Get validated search params (auto-redirect on error)
+- `useSearchParamsRaw()` - Get search params with error info `{data, error, setter}`
+- `pattern` - Original route pattern
+
+#### `createRouteWithoutParams`
+
+```tsx
+const route = createRouteWithoutParams<TSearchParams>(pattern, config?);
+```
+
+**Config:**
+
+- `searchParams?` - Valibot schema for search params
+- `errorRedirect?` - Redirect URL on validation error
+
+**Returns:**
+
+- `path(searchParams?, hash?)` - Generate URL path
+- `Link` - Type-safe Link component
+- `useSearchParams()` - Get validated search params
+- `useSearchParamsRaw()` - Get search params with error info
+- `pattern` - Original route pattern
+
+### Examples
+
+#### Path Generation
+
+```tsx
+const userRoute = createRouteWithParams("/users/:id", {
+  params: v.object({ id: v.string() }),
+  searchParams: v.object({
+    tab: v.optional(v.string()),
+  }),
+});
+
+userRoute.path({ id: "42" });
+// "/users/42"
+
+userRoute.path({ id: "42" }, { tab: "settings" });
+// "/users/42?tab=settings"
+
+userRoute.path({ id: "42" }, { tab: "settings" }, "profile");
+// "/users/42?tab=settings#profile"
+```
+
+#### Type-safe Links
+
+```tsx
+<userRoute.Link params={{ id: "42" }} queryParams={{ tab: "profile" }}>
+  View Profile
+</userRoute.Link>
+
+// Automatically includes prevPath in navigation state
+```
+
+#### Parse URL Params
+
+```tsx
+const params = userRoute.parseURLParams("https://example.com/users/42");
+// { id: "42" }
+
+// Throws URLParseError on invalid URL or validation error
+```
+
+#### Update Search Params
+
+```tsx
+const [searchParams, setSearchParams] = route.useSearchParams();
+
+// Set new params
+setSearchParams({ q: "react", page: 1 });
+
+// Update based on previous
+setSearchParams((prev) => ({ ...prev, page: prev.page + 1 }));
+
+// With navigation options
+setSearchParams({ q: "vue" }, { replace: true });
+```
+
+### Utilities
+
+#### `setGlobalErrorRedirect(url)`
+
+Set global fallback redirect URL for validation errors.
+
+```tsx
+setGlobalErrorRedirect("/error");
+```
+
+#### `replaceState(state)`
+
+Update browser history state without navigation.
+
+```tsx
+import { replaceState } from "@ovineko/react-router";
+
+replaceState({ scrollTop: window.scrollY });
+```
+
+#### `URLParseError`
+
+Error class thrown when URL parsing fails.
+
+```tsx
+try {
+  route.parseURLParams("invalid-url");
+} catch (error) {
+  if (error instanceof URLParseError) {
+    console.log(error.context); // { pattern, url, ... }
+  }
+}
+```
+
+## TypeScript
+
+All types are automatically inferred from valibot schemas:
+
+```tsx
+const route = createRouteWithParams("/users/:id", {
+  params: v.object({ id: v.string() }),
+  searchParams: v.object({
+    page: v.optional(v.pipe(v.string(), v.transform(Number), v.number())),
+  }),
+});
+
+// Inferred types:
+const params = route.useParams(); // Readonly<{ id: string }>
+const [searchParams] = route.useSearchParams(); // Readonly<{ page?: number }>
+```
+
+## Migration from v0.x
+
+The library now uses valibot for validation instead of TypeScript generics:
+
+**Before:**
+
+```tsx
+const route = createRouteWithParams<{ id: string }, { q: string }>("/users/:id");
+```
+
+**After:**
+
+```tsx
+const route = createRouteWithParams("/users/:id", {
+  params: v.object({ id: v.string() }),
+  searchParams: v.object({ q: v.string() }),
+});
+```
+
+**Benefits:**
+
+- Runtime validation
+- Automatic error handling
+- Schema transformations (e.g., string → number)
+- Better type inference
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import * as v from "valibot";
+import type { InferSearchParams, RouteWithoutParams, RouteWithParams, State } from "./types";
+export type { RouteBase, RouteWithoutParams, RouteWithParams, State, UseParamsRawResult, UseSearchParamsRawResult, } from "./types";
+export { URLParseError } from "./validation";
+export declare const setGlobalErrorRedirect: (url: string) => void;
+export declare const createRouteWithParams: <TParams extends v.GenericSchema, TSearchParams extends undefined | v.GenericSchema = undefined>(pattern: string, config: {
+    errorRedirect?: string;
+    params: TParams;
+    searchParams?: TSearchParams;
+}) => Readonly<RouteWithParams<v.InferOutput<TParams>, InferSearchParams<TSearchParams>>>;
+export declare const createRouteWithoutParams: <TSearchParams extends undefined | v.GenericSchema = undefined>(pattern: string, config?: {
+    errorRedirect?: string;
+    searchParams?: TSearchParams;
+}) => Readonly<RouteWithoutParams<InferSearchParams<TSearchParams>>>;
+export declare const replaceState: (state: State) => void;

package/dist/index.js

@@ -0,0 +1,303 @@
+// src/index.tsx
+import { memo, useCallback, useEffect, useMemo } from "react";
+import {
+  generatePath,
+  Link,
+  useLocation,
+  useNavigate,
+  useParams,
+  useSearchParams
+} from "react-router";
+import * as v2 from "valibot";
+
+// src/utils.ts
+import * as v from "valibot";
+
+// src/validation.ts
+var URLParseError = class extends Error {
+  context;
+  constructor(message, context = {}) {
+    super(message);
+    this.name = "URLParseError";
+    this.context = context;
+  }
+};
+function safeDecodeURIComponent(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch (error) {
+    console.warn(`Failed to decode URI component: ${value}`, error);
+    return value;
+  }
+}
+
+// src/utils.ts
+var queryParamsToString = (params) => {
+  if (!params || typeof params !== "object" || Array.isArray(params)) {
+    return "";
+  }
+  const query = new URLSearchParams();
+  Object.entries(params).forEach(([key, value]) => {
+    if (value === void 0 || value === null) {
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((el) => {
+        if (el !== void 0 && el !== null) {
+          query.append(key, String(el));
+        }
+      });
+      return;
+    }
+    query.set(key, String(value));
+  });
+  const queryString = query.toString();
+  return queryString ? `?${queryString}` : "";
+};
+var searchParamsToObject = (params) => {
+  const obj = {};
+  for (const key of new Set(params.keys())) {
+    const values = params.getAll(key);
+    obj[key] = values.length > 1 ? values : values[0];
+  }
+  return obj;
+};
+var objectToSearchParams = (obj) => {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item) => {
+        if (item !== void 0 && item !== null) {
+          params.append(key, String(item));
+        }
+      });
+    } else {
+      params.set(key, String(value));
+    }
+  }
+  return params;
+};
+var parseURLParamsRaw = (pattern, url) => {
+  let pathname;
+  try {
+    pathname = new URL(url).pathname;
+  } catch {
+    throw new URLParseError(`Invalid URL: "${url}"`, { pattern, url });
+  }
+  const urlParts = pathname.split("/").filter(Boolean);
+  const patternParts = pattern.split("/").filter(Boolean);
+  const params = {};
+  for (const [i, patternPart] of patternParts.entries()) {
+    const urlValue = urlParts[i];
+    if (patternPart.startsWith(":")) {
+      const paramKey = patternPart.slice(1);
+      if (!urlValue) {
+        throw new URLParseError(`Missing required parameter "${paramKey}" in URL "${pathname}"`, {
+          paramKey,
+          pathname,
+          pattern,
+          url
+        });
+      }
+      params[paramKey] = safeDecodeURIComponent(urlValue);
+    } else if (patternPart !== urlValue) {
+      throw new URLParseError(
+        `URL path "${pathname}" doesn't match pattern "${pattern}": expected "${patternPart}" at position ${i}, got "${urlValue}"`,
+        { actual: urlValue, expected: patternPart, pathname, pattern, position: i, url }
+      );
+    }
+  }
+  return params;
+};
+var filterBySchemaKeys = (obj, schema) => {
+  const entries = schema.entries;
+  const filtered = {};
+  for (const key in entries) {
+    if (key in obj) {
+      filtered[key] = obj[key];
+    }
+  }
+  return filtered;
+};
+var cleanOptionalParams = (obj, schema) => {
+  const entries = schema.entries;
+  const cleaned = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const fieldSchema = entries[key];
+    if (fieldSchema) {
+      const isOptional = fieldSchema.type === "optional";
+      if (isOptional) {
+        const result = v.safeParse(fieldSchema, value);
+        if (result.success) {
+          cleaned[key] = value;
+        }
+      } else {
+        cleaned[key] = value;
+      }
+    }
+  }
+  return cleaned;
+};
+
+// src/index.tsx
+import { jsx } from "react/jsx-runtime";
+var globalErrorRedirect = "/";
+var setGlobalErrorRedirect = (url) => {
+  globalErrorRedirect = url;
+};
+var getErrorRedirectUrl = (routeLevel) => {
+  return routeLevel ?? globalErrorRedirect;
+};
+var createSearchParamsHook = (schema) => {
+  const useSearchParamsRaw = () => {
+    const [rawSearchParams, setRawSearchParams] = useSearchParams();
+    const { data, error } = useMemo(() => {
+      const obj = searchParamsToObject(rawSearchParams);
+      const filtered = filterBySchemaKeys(obj, schema);
+      const cleaned = cleanOptionalParams(filtered, schema);
+      const result = v2.safeParse(schema, cleaned);
+      if (result.success) {
+        return { data: result.output, error: void 0 };
+      }
+      return { data: void 0, error: result.issues };
+    }, [rawSearchParams]);
+    const setter = useCallback(
+      (nextInit, navigateOpts) => {
+        if (typeof nextInit === "function") {
+          setRawSearchParams((prev) => {
+            const prevObj = searchParamsToObject(prev);
+            const filtered = filterBySchemaKeys(
+              prevObj,
+              schema
+            );
+            const cleaned = cleanOptionalParams(
+              filtered,
+              schema
+            );
+            const result = v2.safeParse(schema, cleaned);
+            const prevParsed = result.success ? result.output : {};
+            const nextObj = nextInit(prevParsed);
+            return objectToSearchParams(nextObj);
+          }, navigateOpts);
+        } else {
+          setRawSearchParams(
+            objectToSearchParams(nextInit),
+            navigateOpts
+          );
+        }
+      },
+      [setRawSearchParams]
+    );
+    return { data, error, setter };
+  };
+  const useSearchParamsHook = (errorRedirectUrl) => {
+    const navigate = useNavigate();
+    const { data, error, setter } = useSearchParamsRaw();
+    useEffect(() => {
+      if (error) {
+        const redirectUrl = getErrorRedirectUrl(errorRedirectUrl);
+        navigate(redirectUrl, { replace: true });
+      }
+    }, [error, navigate, errorRedirectUrl]);
+    return [data ?? {}, setter];
+  };
+  return { useSearchParamsHook, useSearchParamsRaw };
+};
+var createRouteWithParams = (pattern, config) => {
+  const getPath = (params, searchParams, hash) => `${generatePath(pattern, params)}${queryParamsToString(searchParams)}${hash ? `#${hash}` : ""}`;
+  const searchParamsHooks = config.searchParams ? createSearchParamsHook(config.searchParams) : null;
+  const LinkComponent = memo(
+    ({
+      children,
+      params,
+      queryParams,
+      state,
+      ...props
+    }) => {
+      const { pathname } = useLocation();
+      const mergedState = useMemo(
+        () => ({ prevPath: pathname, ...state }),
+        [pathname, state]
+      );
+      return /* @__PURE__ */ jsx(Link, { ...props, state: mergedState, to: getPath(params, queryParams), children });
+    }
+  );
+  const useParamsRaw = () => {
+    const params = useParams();
+    const result = v2.safeParse(config.params, params);
+    if (result.success) {
+      return [result.output, void 0];
+    }
+    return [void 0, result.issues];
+  };
+  const useParamsHook = () => {
+    const navigate = useNavigate();
+    const [params, error] = useParamsRaw();
+    useEffect(() => {
+      if (error) {
+        const redirectUrl = getErrorRedirectUrl(config.errorRedirect);
+        navigate(redirectUrl, { replace: true });
+      }
+    }, [error, navigate]);
+    return params ?? {};
+  };
+  return {
+    Link: LinkComponent,
+    parseURLParams: (url) => {
+      const rawParams = parseURLParamsRaw(pattern, url);
+      return v2.parse(config.params, rawParams);
+    },
+    path: getPath,
+    pattern,
+    useParams: useParamsHook,
+    useParamsRaw,
+    useSearchParams: searchParamsHooks ? () => searchParamsHooks.useSearchParamsHook(config.errorRedirect) : void 0,
+    useSearchParamsRaw: searchParamsHooks ? searchParamsHooks.useSearchParamsRaw : void 0
+  };
+};
+var createRouteWithoutParams = (pattern, config) => {
+  const getPath = (searchParams, hash) => `${pattern}${queryParamsToString(searchParams)}${hash ? `#${hash}` : ""}`;
+  const searchParamsHooks = config?.searchParams ? createSearchParamsHook(config.searchParams) : null;
+  const LinkComponent = memo(
+    ({ children, queryParams, state, ...props }) => {
+      const { pathname } = useLocation();
+      const mergedState = useMemo(
+        () => ({ prevPath: pathname, ...state }),
+        [pathname, state]
+      );
+      return /* @__PURE__ */ jsx(Link, { ...props, state: mergedState, to: getPath(queryParams), children });
+    }
+  );
+  return {
+    Link: LinkComponent,
+    path: getPath,
+    pattern,
+    useSearchParams: searchParamsHooks ? () => searchParamsHooks.useSearchParamsHook(config?.errorRedirect) : void 0,
+    useSearchParamsRaw: searchParamsHooks ? searchParamsHooks.useSearchParamsRaw : void 0
+  };
+};
+var replaceState = (state) => {
+  if (!globalThis.window) {
+    return;
+  }
+  globalThis.window.history.replaceState(
+    {
+      ...globalThis.window.history.state,
+      usr: {
+        ...globalThis.window.history.state?.usr,
+        ...state
+      }
+    },
+    ""
+  );
+};
+export {
+  URLParseError,
+  createRouteWithParams,
+  createRouteWithoutParams,
+  replaceState,
+  setGlobalErrorRedirect
+};

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+import type { LinkProps as LinkPropsLib, NavigateOptions } from "react-router";
+import type * as v from "valibot";
+export type InferSearchParams<T> = T extends v.GenericSchema ? v.InferOutput<T> : undefined;
+export interface LinkPropsWithoutParams<SearchParams> extends Omit<LinkPropsLib, "to"> {
+    children: React.ReactNode | string;
+    className?: string;
+    queryParams?: SearchParams;
+    state?: State;
+    style?: React.CSSProperties;
+}
+export interface LinkPropsWithParams<Params, SearchParams> extends LinkPropsWithoutParams<SearchParams> {
+    params: Params;
+}
+export interface RouteBase {
+    pattern: string;
+}
+export interface RouteWithoutParams<SearchParams = undefined> extends RouteBase {
+    Link: (props: LinkPropsWithoutParams<SearchParams>) => React.ReactNode;
+    path: (searchParams?: SearchParams, hash?: string) => string;
+    useSearchParams: SearchParamsHook<SearchParams>;
+    useSearchParamsRaw: SearchParamsHook<SearchParams> extends undefined ? undefined : () => UseSearchParamsRawResult<SearchParams>;
+}
+export interface RouteWithParams<Params, SearchParams = undefined> extends RouteBase {
+    Link: (props: LinkPropsWithParams<Params, SearchParams>) => React.ReactNode;
+    parseURLParams: (url: string) => Params;
+    path: (params: Params, searchParams?: SearchParams, hash?: string) => string;
+    useParams: () => Readonly<Params>;
+    useParamsRaw: () => UseParamsRawResult<Params>;
+    useSearchParams: SearchParamsHook<SearchParams>;
+    useSearchParamsRaw: SearchParamsHook<SearchParams> extends undefined ? undefined : () => UseSearchParamsRawResult<SearchParams>;
+}
+export type SearchParamsHook<SearchParams> = SearchParams extends undefined ? undefined : () => readonly [Readonly<SearchParams>, SetSearchParams<SearchParams>];
+export type SearchParamsInput = Record<string, string | string[]>;
+export type SetSearchParams<SearchParams> = (nextInit: ((prev: Readonly<SearchParams>) => SearchParams) | SearchParams, navigateOpts?: NavigateOptions) => void;
+export interface State {
+    prevPath?: string;
+    scrollTop?: number;
+}
+export type UseParamsRawResult<Params> = readonly [
+    Readonly<Params> | undefined,
+    undefined | v.BaseIssue<unknown>[]
+];
+export interface UseSearchParamsRawResult<SearchParams> {
+    data: Readonly<SearchParams> | undefined;
+    error: undefined | v.BaseIssue<unknown>[];
+    setter: SetSearchParams<SearchParams>;
+}

package/dist/utils.d.ts

@@ -0,0 +1,17 @@
+import * as v from "valibot";
+import type { SearchParamsInput } from "./types";
+export declare const queryParamsToString: (params?: SearchParamsInput) => string;
+export declare const searchParamsToObject: (params: URLSearchParams) => Record<string, string | string[]>;
+export declare const objectToSearchParams: (obj: Record<string, unknown>) => URLSearchParams;
+export declare const parseURLParamsRaw: (pattern: string, url: string) => Record<string, string>;
+/**
+ * Filters an object to only include keys that exist in the valibot object schema.
+ * Ignores extra query parameters not defined in the schema.
+ */
+export declare const filterBySchemaKeys: <T extends v.ObjectSchema<any, any>>(obj: Record<string, unknown>, schema: T) => Record<string, unknown>;
+/**
+ * Removes invalid optional parameters from an object.
+ * Optional parameters with invalid values are ignored (treated as undefined).
+ * Required parameters are kept as-is for subsequent validation.
+ */
+export declare const cleanOptionalParams: <T extends v.ObjectSchema<any, any>>(obj: Record<string, unknown>, schema: T) => Record<string, unknown>;

package/dist/validation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Custom error class for URL parsing failures
+ */
+export declare class URLParseError extends Error {
+    readonly context: Record<string, unknown>;
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Decodes URL component safely, handling special characters
+ */
+export declare function safeDecodeURIComponent(value: string): string;

package/dist/validation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@ovineko/react-router",
+  "version": "0.0.1",
+  "description": "Type-safe wrapper for React Router v7 with typed params, query params, and Link components",
+  "keywords": [
+    "react",
+    "react-router",
+    "router",
+    "type-safe",
+    "typed-routes",
+    "typed-params",
+    "query-params",
+    "routing",
+    "typescript",
+    "react19",
+    "link"
+  ],
+  "homepage": "https://github.com/ovineko/ovineko/tree/main/packages/react-router",
+  "bugs": {
+    "url": "https://github.com/ovineko/ovineko/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ovineko/ovineko.git",
+    "directory": "packages/react-router"
+  },
+  "license": "MIT",
+  "author": "Alexander Svinarev <shibanet0@gmail.com> (shibanet0.com)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": "^19",
+    "react-router": "^7",
+    "valibot": "^1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}