waymark 0.4.0 → 0.5.0

package/README.md

@@ -3,10 +3,10 @@
 </p>
 
 <p align="center">
-  A lightweight, type-safe router for React that just works.
+  A type-safe router for React that just works.
 </p>
 
-<p align="center">
+<div align="center">
   <a href="https://www.npmjs.com/package/waymark">
     <img
       src="https://img.shields.io/npm/v/waymark?style=flat-square&color=0B0D0F&labelColor=0B0D0F"
@@ -37,28 +37,74 @@
       alt="sponsors"
     />
   </a>
-</p>
+</div>
 
 <p align="center">
-  <a href="https://waymarkrouter.com">📖 Documentation</a>
+  📖 <a href="https://waymarkrouter.com">Documentation</a> · 🎮 <a href="https://stackblitz.com/edit/waymark-demo?file=src%2Fapp.tsx">Live playground</a>
 </p>
 
 ---
 
 Waymark is a routing library for React built around three core ideas: **type safety**, **simplicity**, and **minimal overhead**.
 
-- **Fully type-safe** - Complete TypeScript inference for routes, path params, and search params
-- **Zero config** - No build plugins, no CLI, no codegen, no config files, very low boilerplate
-- **Familiar API** - If you've used React Router or TanStack Router, you'll feel at home
-- **3.7kB gzipped** - Extremely lightweight with just one 0.4kB dependency, so ~4kB total
-- **Feature packed** - Search param validation, lazy loading, data preloading, SSR, error boundaries, etc.
-- **Not vibe-coded** - Built with careful design and attention to detail by a human
-- **Just works** - Define routes, get autocomplete everywhere
+- 🔒 **Fully type-safe** - Complete TypeScript inference for routes, path params, search params, and more
+- ⚡ **Zero config** - No build plugins, no CLI, no codegen, no config files, very low boilerplate
+- 🪶 **4kB gzipped** - Extremely lightweight, dependency included
+- 🤝 **Familiar API** - If you've used React Router or TanStack Router, you'll feel at home
+- 🎯 **Feature packed** - Search param validation, lazy loading, data preloading, SSR, error boundaries, etc.
+- 🧠 **Not vibe-coded** - Built with careful design and attention to detail by a human
+- ✨ **Just works** - Simple setup, predictable behavior that never gets in your way
+
+---
+
+# Comparison
+
+| Feature                          | Waymark | React Router | TanStack Router | Wouter |
+| -------------------------------- | :-----: | :----------: | :-------------: | :----: |
+| **Bundle size (gzip)**\*         |  ~4kB   |    ~26kB+    |     ~19kB+      | ~2.2kB |
+| **Zero config**\*                |   ✅    |      ❌      |       ⚠️        |   ✅   |
+| **Full type inference**\*        |   ✅    |      ⚠️      |       ✅        |   ❌   |
+| **Nested routes**                |   ✅    |      ✅      |       ✅        |   ✅   |
+| **Search param validation**\*    |   ✅    |      ❌      |       ✅        |   ❌   |
+| **Lazy loading**                 |   ✅    |      ✅      |       ✅        |   ❌   |
+| **Data preloading**              |   ✅    |      ✅      |       ✅        |   ❌   |
+| **Built-in error boundaries**    |   ✅    |      ✅      |       ✅        |   ❌   |
+| **Built-in suspense boundaries** |   ✅    |      ❌      |       ✅        |   ❌   |
+| **Link preloading strategies**   |   ✅    |      ✅      |       ✅        |   ❌   |
+| **Active link detection**        |   ✅    |      ✅      |       ✅        |   ⚠️   |
+| **Browser/Hash/Memory history**  |   ✅    |      ✅      |       ✅        |   ✅   |
+| **SSR support**                  |   ✅    |      ✅      |       ✅        |   ✅   |
+| **Route middlewares**\*          |   ✅    |      ❌      |       ❌        |   ❌   |
+| **Route handles (metadata)**     |   ✅    |      ✅      |       ✅        |   ❌   |
+| **Route match ranking**\*        |   ✅    |      ✅      |       ✅        |   ❌   |
+| **View transitions**             |   ✅    |      ✅      |       ✅        |   ✅   |
+| **Devtools**                     |   ✅    |      ⚠️      |       ✅        |   ❌   |
+| **File-based routing**           |   ❌    |      ✅      |       ✅        |   ❌   |
+| **React Native**                 |   ❌    |      ✅      |       ❌        |   ❌   |
+
+<details>
+<summary><b>Comparison notes</b></summary>
+
+<br />
+
+If you believe there's a mistake in the comparison table, please [open an issue](https://github.com/strblr/waymark/issues) or [submit a PR](https://github.com/strblr/waymark/pulls) and it will be fixed.
+
+- ⚠️ indicates the feature is only partially supported, supported with heavy boilerplate, or requires external libraries.
+- 🔨 indicates the feature is not yet ready but being worked on.
+- **Bundle sizes** are approximate gzipped values. React Router and TanStack Router sizes can vary significantly based on imports and versions; Waymark's ~4kB includes its single ~0.4kB dependency ([regexparam](https://github.com/lukeed/regexparam)), before any tree shaking. Wouter is the smallest option but lacks features.
+- **Zero config** means no CLI tools, build plugins, code generation, or configuration files are required. React Router requires its typegen CLI or bundler plugin for full type safety. Same with TanStack Router for file-based routing. You can use code-based routing but it's more boilerplate.
+- **Full type inference** refers to automatic TypeScript inference for routes, params, search params, and navigation without manual type annotations.
+- **Search params validation** refers to built-in support for validating and typing URL search parameters. Wouter provides `useSearch()` but no validation layer. Same with React Router and `useSearchParams`.
+- **Route middlewares** are reusable configuration bundles (search validation, handles, preload functions, components) that can be applied to multiple routes. This is a Waymark-specific feature.
+- **Route match ranking** automatically picks the most specific route when multiple patterns match (e.g., `/users/new` wins over `/users/:id`). Without ranking, route definition order matters.
+
+</details>
 
 ---
 
 # Table of contents
 
+- [Comparison](#comparison)
 - [Showcase](#showcase)
 - [Installation](#installation)
 - [Defining routes](#defining-routes)
@@ -85,6 +131,7 @@ Waymark is a routing library for React built around three core ideas: **type saf
 - [Middlewares](#middlewares)
 - [Route matching and ranking](#route-matching-and-ranking)
 - [History implementations](#history-implementations)
+- [Devtools](#devtools)
 - [Cookbook](#cookbook)
   - [Quick start example](#quick-start-example)
   - [Server-side rendering (SSR)](#server-side-rendering-ssr)
@@ -150,6 +197,8 @@ declare module "waymark" {
 
 Everything autocompletes and type-checks automatically. No heavy setup, no magic, just a simple API that gets out of your way.
 
+👉 [Try it live in the StackBlitz playground](https://stackblitz.com/edit/waymark-demo?file=src%2Fapp.tsx)
+
 ---
 
 # Installation
@@ -192,31 +241,25 @@ const files = route("/files/*").component(FileBrowser);
 const optional = route("/books/*?").component(FileBrowser);
 ```
 
-Route building is immutable: every method on a route returns a new route instance, which means you can branch off at any point to create variations or nested routes without affecting the original.
+Route building is immutable: every method on a route returns a new route instance.
 
 ---
 
 # Nested routes and layouts
 
-Nesting is the core mechanism for building layouts and route hierarchies in Waymark. When you call `.route()` on an existing route, you create a child route that inherits everything from the parent: its path as a prefix, its params, its components, etc.
-
-Here's how it works. Start with any route:
+Any route can have child routes. Call `.route()` on an existing route to create one:
 
 ```tsx
 const dashboard = route("/dashboard").component(DashboardLayout);
-```
-
-Then create child routes by calling `.route()` on it:
 
-```tsx
 const overview = dashboard.route("/").component(Overview);
 const settings = dashboard.route("/settings").component(Settings);
 const profile = dashboard.route("/profile").component(Profile);
 ```
 
-The child routes combine the parent's path pattern with their own. So `overview` has the full pattern `/dashboard`, `settings` has `/dashboard/settings`, and `profile` has `/dashboard/profile`.
+Child routes build on their parent's path. So `overview` matches `/dashboard`, `settings` matches `/dashboard/settings`, and `profile` matches `/dashboard/profile`.
 
-The parent component must render an `<Outlet />` where child routes should appear:
+They also nest inside the parent's component. The parent renders an `<Outlet />` to mark where child routes should appears:
 
 ```tsx
 function DashboardLayout() {
@@ -231,7 +274,7 @@ function DashboardLayout() {
 }
 ```
 
-When the URL is `/dashboard/settings`, Waymark renders `DashboardLayout` with `Settings` inside the outlet. The layout stays mounted (and doesn't even rerender) as users navigate between child routes.
+When the URL is `/dashboard/settings`, Waymark renders `DashboardLayout` with `Settings` inside the outlet. This is how you build layouts - shared UI like navigation or sidebars that stays mounted as users navigate between child routes.
 
 You can nest as deep as you need:
 
@@ -253,6 +296,8 @@ AppShell
 
 Each level must include an `<Outlet />` to render the next level.
 
+Beyond paths and components, child routes also inherit search param validators, handles, and preload functions from their parent chain. While you can think of nesting as building a tree, every route is self-contained: it carries everything it needs to render, including all parent components.
+
 ---
 
 # Setting up the router
@@ -319,7 +364,9 @@ declare module "waymark" {
 }
 ```
 
-With this in place, `Link`, `navigate`, `useParams`, `useSearch`, and other APIs will know exactly which routes exist and what input they expect, and you're good to go.
+With this in place, `Link`, `navigate`, `useParams`, `useSearch`, and other APIs will know exactly which routes exist and what input they expect.
+
+**You're all set up!**
 
 ---
 
@@ -459,6 +506,9 @@ function SearchPage() {
   const [search, setSearch] = useSearch(searchPage);
   // search.q: string
   // search.page: number
+
+  const [search, setSearch] = useSearch("/search");
+  // Also works
 }
 ```
 
@@ -1015,6 +1065,16 @@ function UserPage() {
 }
 ```
 
+For parametrized middlewares, define a function that returns a middleware:
+
+```tsx
+const guard = (role: string) =>
+  middleware().handle({ requiredRole: role }).component(RoleGuard);
+
+const adminPage = route("/admin").use(guard("admin")).component(AdminPage);
+const editorPage = route("/editor").use(guard("editor")).component(EditorPage);
+```
+
 ---
 
 # Route matching and ranking
@@ -1103,6 +1163,53 @@ All history implementations conform to the `HistoryLike` interface, so you can c
 
 ---
 
+# Devtools
+
+Waymark has a companion devtools package for inspecting routes, matches, parameters, and navigation state.
+
+```bash
+npm install waymark-devtools
+```
+
+Render the `Devtools` component anywhere inside your routes. It displays a toggle button that opens a draggable and resizable floating panel:
+
+```tsx
+import { Devtools } from "waymark-devtools";
+
+const layout = route("/").component(Layout);
+
+function Layout() {
+  return (
+    <div>
+      <Outlet />
+      <Devtools />
+    </div>
+  );
+}
+```
+
+If you'd rather embed the panel directly into your layout instead of using the floating window, use `DevtoolsPanel`:
+
+```tsx
+import { DevtoolsPanel } from "waymark-devtools";
+
+function DebugSidebar() {
+  return (
+    <aside>
+      <DevtoolsPanel />
+    </aside>
+  );
+}
+```
+
+To exclude devtools from production builds (Vite example):
+
+```tsx
+import.meta.env.DEV && <Devtools />;
+```
+
+---
+
 # Cookbook
 
 ## Quick start example
@@ -1217,29 +1324,27 @@ function AppLayout() {
 
 ## Matching a route anywhere
 
-Use `useMatch` to check if a route matches the current path from anywhere in your component tree. You can pass either a route pattern string or a route object, just like with `Link` and `navigate`. This is useful for conditional rendering, styling, access control, and more. It's also used internally by `useParams` and `Link`.
+Use `useMatch` to check if a route is part of the current match. You can pass either a route pattern string or a route object, just like with `Link` and `navigate`. This is useful for conditional rendering, styling, access control, and more. It's also used internally by `useParams` and `Link`.
+
+The hook returns the matched params if there's a match, or `null` otherwise. There are two matching modes:
 
-By default, `useMatch` uses loose matching where the current path only needs to start with the route's path. To require an exact match instead, pass `strict: true`:
+- **Loose matching** (default): Matches if you're on the route or any of its child routes.
+- **Strict matching** (`strict: true`): Matches only if you're on the exact route.
 
 ```tsx
-import { useMatch } from "waymark";
+import { route, useMatch } from "waymark";
 
 const dashboard = route("/dashboard").component(Dashboard);
-const settings = route("/settings").component(Settings);
+const settings = dashboard.route("/settings").component(Settings);
 
 function Sidebar() {
-  // Loose matching: matches /dashboard and /dashboard/literally/anything
-  const dashboardMatch = useMatch({ from: "/dashboard" });
+  // Matches /dashboard and any child route like /dashboard/settings
+  const match = useMatch({ from: dashboard });
 
-  // Strict matching: matches only /settings
-  const settingsMatch = useMatch({ from: settings, strict: true });
+  // Matches only /dashboard exactly
+  const match = useMatch({ from: dashboard, strict: true });
 
-  return (
-    <nav>
-      {dashboardMatch && <DashboardMenu />}
-      {settingsMatch && <SettingsSubmenu />}
-    </nav>
-  );
+  return <nav>{match && <DashboardMenu />}</nav>;
 }
 ```
 
@@ -1407,15 +1512,15 @@ const url = router.createUrl({ to: userProfile, params: { id: "42" } });
 // Returns "/users/42"
 ```
 
-**`router.match(path, options)`** checks if a path matches a specific route.
+**`router.match(path, route)`** checks if a path matches a specific route.
 
 - `path` - `string` - The path to match against
-- `options` - `MatchOptions` - Matching options
+- `route` - `Route` - The route object to match against
 - Returns: `Match | null` - The match result or null if no match
 
 ```tsx
-const match = router.match("/users/42", { from: "/users/:id" });
-// Returns { route, params: { id: "42" } } or null
+const match = router.match("/users/42", userRoute);
+// Returns { route, params: { id: "42" } }
 ```
 
 **`router.matchAll(path)`** finds the best match from all registered routes.
@@ -1565,8 +1670,11 @@ const user = route("/users/:id")
 - Returns: `Middleware` - A new middleware object
 
 ```tsx
-const paginated = middleware().search(
-  z.object({ page: z.number(), limit: z.number() })
+const pagination = middleware().search(
+  z.object({
+    page: z.coerce.number().catch(1),
+    limit: z.coerce.number().catch(10)
+  })
 );
 const auth = middleware()
   .handle({ requiresAuth: true })
@@ -1597,7 +1705,7 @@ navigate(-1);
 
 **`useLocation()`** returns the current location, subscribes to changes.
 
-- Returns: `{ path: string, search: Record<string, unknown>, state: any }` - The current path, parsed search params, and history state
+- Returns: `HistoryLocation` - The current location with path, parsed search params, and history state
 
 ```tsx
 const { path, search, state } = useLocation();
@@ -1635,7 +1743,7 @@ setSearch({ page: 1 }, true); // Replace instead of push
 **`useMatch(options)`** checks if a route matches the current path.
 
 - `options` - `MatchOptions` - Matching options
-- Returns: `Match | null` - The match result or null if no match
+- Returns: `Params | null` - The extracted path params if matched, or null if no match
 
 ```tsx
 const match = useMatch({ from: "/users/:id" });
@@ -1706,31 +1814,15 @@ new MemoryHistory("/initial"); // In-memory only.
 
 See [History implementations](#history-implementations) for detailed usage.
 
-**`history.getPath()`** returns the current path.
-
-- Returns: `string` - The current path
-
-```tsx
-const path = history.getPath();
-// Returns "/users/42"
-```
-
-**`history.getSearch()`** returns the current search params as a parsed JSON object.
+**`history.location()`** returns the current location.
 
-- Returns: `Record<string, unknown>` - The parsed search params
+- Returns: `HistoryLocation` - The current location with path, parsed search params, and history state
 
 ```tsx
-const search = history.getSearch();
-// Returns { tab: "posts", page: 2 }
-```
-
-**`history.getState()`** returns the current history state.
-
-- Returns: `any` - The state passed during navigation, or undefined
-
-```tsx
-const state = history.getState();
-// Returns any state passed during navigation
+const { path, search, state } = history.location();
+// path: "/users/42"
+// search: { tab: "posts", page: 2 }
+// state: any state passed during navigation
 ```
 
 **`history.go(delta)`** navigates forward or back in history.
@@ -1793,6 +1885,16 @@ type NavigateOptions = {
 };
 ```
 
+**`HistoryLocation`** represents a history location.
+
+```tsx
+interface HistoryLocation {
+  path: string; // The current path
+  search: Record<string, unknown>; // Parsed search params
+  state: any; // History state passed during navigation
+}
+```
+
 **`HistoryPushOptions`** are options for untyped navigation.
 
 ```tsx
@@ -1808,7 +1910,7 @@ interface HistoryPushOptions {
 ```tsx
 type MatchOptions = {
   from: Pattern | Route; // The route to match against
-  strict?: boolean; // Require exact match (default: false, matches prefixes)
+  strict?: boolean; // Strict matching mode (default: false)
   params?: Partial<Params>; // Optional param values to filter by
 };
 ```
@@ -1859,9 +1961,8 @@ interface PreloadContext {
 # Roadmap
 
 - Possibility to pass an arbitrary context to the Router instance for later use in preloads?
-- Relative path navigation? Not sure it's indispensable given that users can export/import route objects and pass them as navigation option.
+- Relative path navigation? Not sure it's worth the extra bundle size given that users can export/import route objects and pass them as navigation option.
 - Document usage in test environments
-- Devtools? Let me know if needed.
 - Open to suggestions, we can discuss them [here](https://github.com/strblr/waymark/discussions).
 
 ---

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import * as react2 from "react";
+import * as react0 from "react";
 import { AnchorHTMLAttributes, CSSProperties, ComponentType, ReactNode, RefAttributes } from "react";
 import { RouteParams } from "regexparam";
 import { EmptyObject, Merge, Simplify } from "type-fest";
@@ -38,8 +38,8 @@ interface PreloadContext<Ps extends {} = any, S extends {} = any> {
   search: S;
 }
 interface RouterOptions {
-  basePath?: string;
   routes: RouteList;
+  basePath?: string;
   history?: HistoryLike;
   ssrContext?: SSRContext;
   defaultLinkOptions?: LinkOptions;
@@ -79,19 +79,22 @@ type SSRContext = {
   redirect?: string;
   statusCode?: number;
 };
-interface HistoryPushOptions {
-  url: string;
-  replace?: boolean;
-  state?: any;
-}
 interface HistoryLike {
-  getPath: () => string;
-  getSearch: () => Record<string, unknown>;
-  getState: () => any;
+  location: () => HistoryLocation;
   go: (delta: number) => void;
   push: (options: HistoryPushOptions) => void;
   subscribe: (listener: () => void) => () => void;
 }
+interface HistoryLocation {
+  path: string;
+  search: Record<string, unknown>;
+  state: any;
+}
+interface HistoryPushOptions {
+  url: string;
+  replace?: boolean;
+  state?: any;
+}
 type Updater<T extends object> = Partial<T> | ((prev: T) => Partial<T>);
 type ComponentLoader = () => Promise<ComponentType | {
   default: ComponentType;
@@ -105,12 +108,12 @@ declare class Route<P extends string = string, Ps extends {} = any, S extends {}
     pattern: P;
     keys: string[];
     regex: RegExp;
-    looseRegex: RegExp;
     weights: number[];
     validate: (search: Record<string, unknown>) => S;
     handles: Handle[];
     components: ComponentType[];
     preloads: ((context: PreloadContext) => Promise<any>)[];
+    chain: Set<Route>;
   };
   readonly _types: {
     params: Ps;
@@ -133,15 +136,15 @@ declare class Route<P extends string = string, Ps extends {} = any, S extends {}
 //#endregion
 //#region src/router/router.d.ts
 declare class Router {
-  readonly basePath: string;
   readonly routes: RouteList;
+  readonly basePath: string;
   readonly history: HistoryLike;
   readonly ssrContext?: SSRContext;
   readonly defaultLinkOptions?: LinkOptions;
   private readonly _;
   constructor(options: RouterOptions);
   getRoute: <P extends Pattern>(pattern: P | GetRoute<P>) => GetRoute<P>;
-  match: <P extends Pattern>(path: string, options: MatchOptions<P>) => Match<P> | null;
+  match: <P extends Pattern>(path: string, route: GetRoute<P>) => Match<P> | null;
   matchAll: (path: string) => Match | null;
   createUrl: <P extends Pattern>(options: NavigateOptions<P>) => string;
   preload: <P extends Pattern>(options: NavigateOptions<P>) => Promise<void>;
@@ -150,13 +153,10 @@ declare class Router {
 //#endregion
 //#region src/router/browser-history.d.ts
 declare class BrowserHistory implements HistoryLike {
-  private static patch;
-  private memo?;
+  private _?;
+  protected _loc: (path: string, search: string) => HistoryLocation;
   constructor();
-  protected getSearchMemo: (search: string) => Record<string, unknown>;
-  getPath: () => string;
-  getSearch: () => Record<string, unknown>;
-  getState: () => any;
+  location: () => HistoryLocation;
   go: (delta: number) => void;
   push: (options: HistoryPushOptions) => void;
   subscribe: (listener: () => void) => () => void;
@@ -168,10 +168,7 @@ declare class MemoryHistory implements HistoryLike {
   private index;
   private listeners;
   constructor(url?: string);
-  private getCurrent;
-  getPath: () => string;
-  getSearch: () => Record<string, unknown>;
-  getState: () => any;
+  location: () => HistoryLocation;
   go: (delta: number) => void;
   push: (options: HistoryPushOptions) => void;
   subscribe: (listener: () => void) => () => void;
@@ -179,9 +176,7 @@ declare class MemoryHistory implements HistoryLike {
 //#endregion
 //#region src/router/hash-history.d.ts
 declare class HashHistory extends BrowserHistory {
-  private getHashUrl;
-  getPath: () => string;
-  getSearch: () => Record<string, unknown>;
+  location: () => HistoryLocation;
   push: (options: HistoryPushOptions) => void;
 }
 //#endregion
@@ -200,22 +195,18 @@ declare function Link<P extends Pattern>(props: LinkProps<P>): ReactNode;
 //#endregion
 //#region src/react/hooks.d.ts
 declare function useRouter(): Router;
+declare function useLocation(): HistoryLocation;
+declare function useMatch<P extends Pattern>(options: MatchOptions<P>): Params<P> | null;
+declare function useOutlet(): ReactNode;
 declare function useNavigate(): <P extends Pattern>(options: number | HistoryPushOptions | NavigateOptions<P>) => void;
-declare function useLocation(): {
-  path: string;
-  search: Record<string, unknown>;
-  state: any;
-};
-declare function useOutlet(): react2.ReactNode;
+declare function useHandles(): Handle[];
 declare function useParams<P extends Pattern>(from: P | GetRoute<P>): Params<P>;
 declare function useSearch<P extends Pattern>(from: P | GetRoute<P>): readonly [Search<P>, (update: Updater<Search<P>>, replace?: boolean) => void];
-declare function useMatch<P extends Pattern>(options: MatchOptions<P>): Match<P> | null;
-declare function useHandles(): Handle[];
-declare function useSubscribe<T>(router: Router, getSnapshot: () => T): T;
 //#endregion
 //#region src/react/contexts.d.ts
-declare const RouterContext: react2.Context<Router | null>;
-declare const MatchContext: react2.Context<Match | null>;
-declare const OutletContext: react2.Context<ReactNode>;
+declare const RouterContext: react0.Context<Router | null>;
+declare const LocationContext: react0.Context<HistoryLocation | null>;
+declare const MatchContext: react0.Context<Match | null>;
+declare const OutletContext: react0.Context<ReactNode>;
 //#endregion
-export { BrowserHistory, ComponentLoader, GetRoute, Handle, HashHistory, HistoryLike, HistoryPushOptions, Link, LinkOptions, LinkProps, Match, MatchContext, MatchOptions, MemoryHistory, Middleware, Navigate, NavigateOptions, NavigateProps, Outlet, OutletContext, Params, Pattern, PreloadContext, Register, Route, RouteList, Router, RouterContext, RouterOptions, RouterRoot, RouterRootProps, SSRContext, Search, Updater, Validator, middleware, route, useHandles, useLocation, useMatch, useNavigate, useOutlet, useParams, useRouter, useSearch, useSubscribe };
+export { BrowserHistory, ComponentLoader, GetRoute, Handle, HashHistory, HistoryLike, HistoryLocation, HistoryPushOptions, Link, LinkOptions, LinkProps, LocationContext, Match, MatchContext, MatchOptions, MemoryHistory, Middleware, Navigate, NavigateOptions, NavigateProps, Outlet, OutletContext, Params, Pattern, PreloadContext, Register, Route, RouteList, Router, RouterContext, RouterOptions, RouterRoot, RouterRootProps, SSRContext, Search, Updater, Validator, middleware, route, useHandles, useLocation, useMatch, useNavigate, useOutlet, useParams, useRouter, useSearch };

package/dist/index.js

@@ -1 +1 @@
-import{Component as e,Suspense as t,cloneElement as n,createContext as r,isValidElement as i,lazy as a,memo as o,useCallback as s,useContext as c,useEffect as l,useInsertionEffect as u,useLayoutEffect as d,useMemo as f,useRef as p,useState as m,useSyncExternalStore as h}from"react";import{inject as g,parse as _}from"regexparam";import{jsx as v}from"react/jsx-runtime";function y(e){return`/${e}`.replaceAll(/\/+/g,`/`).replace(/(.+)\/$/,`$1`)}function b(e){let{keys:t,pattern:n}=_(e);return{pattern:e,keys:t,regex:n,looseRegex:_(e,!0).pattern,weights:e.split(`/`).slice(1).map(e=>e.includes(`*`)?0:e.includes(`:`)?1:2)}}function x(e){return typeof e==`function`?e:t=>{let n=e[`~standard`].validate(t);if(n instanceof Promise)throw Error(`[Waymark] Validation must be synchronous`);if(n.issues)throw Error(`[Waymark] Validation failed`,{cause:n.issues});return n.value}}function S(e){return Object.entries(e).filter(([e,t])=>t!==void 0).map(([e,t])=>`${e}=${encodeURIComponent(w(t))}`).join(`&`)}function C(e){let t=new URLSearchParams(e);return Object.fromEntries([...t.entries()].map(([e,t])=>(t=decodeURIComponent(t),[e,T(t)?JSON.parse(t):t])))}function w(e){return typeof e==`string`&&!T(e)?e:JSON.stringify(e)}function T(e){try{return JSON.parse(e),!0}catch{return!1}}function E(e,t){return y(`${t}/${e}`)}function D(e,t){return(e===t||e.startsWith(`${t}/`))&&(e=e.slice(t.length)||`/`),e}function O(e,t){return[e,S(t)].filter(Boolean).join(`?`)}function k(e){let{pathname:t,search:n}=new URL(e,`http://w`);return{path:t,search:C(n)}}function A(e,t,n,r){let i=e.exec(D(n,r));if(!i)return null;let a={};return t.forEach((e,t)=>{let n=i[t+1];n&&(a[e]=n)}),a}function j(e){return[...e].sort((e,t)=>{let n=e.route._.weights,r=t.route._.weights,i=Math.max(n.length,r.length);for(let e=0;e<i;e++){let t=n[e]??-1,i=r[e]??-1;if(t!==i)return i-t}return 0})}const M=r(null),N=r(null),P=r(null);function F(){let e=c(M);if(!e)throw Error(`[Waymark] useRouter must be used within a router context`);return e}function I(){return F().navigate}function L(){let e=F(),t=U(e,e.history.getPath),n=U(e,e.history.getSearch),r=U(e,e.history.getState);return f(()=>({path:t,search:n,state:r}),[t,n,r])}function R(){return c(P)}function z(e){let t=V({from:e});if(!t)throw Error(`[Waymark] Can't read params for non-matching route: ${e}`);return t.params}function B(e){let t=F(),n=t.getRoute(e),r=U(t,t.history.getSearch),i=f(()=>n._.validate(r),[n,r]);return[i,Z((e,n)=>{e=typeof e==`function`?e(i):e;let r={...i,...e},a=O(t.history.getPath(),r);t.navigate({url:a,replace:n})})]}function V(e){let t=F(),n=U(t,t.history.getPath);return f(()=>t.match(n,e),[t,n,e])}function H(){let e=c(N);return f(()=>e?.route._.handles??[],[e])}function U(e,t){return h(e.history.subscribe,t,t)}var W=class e{static patch=Symbol.for(`wmbhp01`);memo;constructor(){if(typeof history<`u`&&!(e.patch in window)){for(let e of[G,K]){let t=history[e];history[e]=function(...n){let r=t.apply(this,n),i=new Event(e);return i.arguments=n,dispatchEvent(i),r}}window[e.patch]=!0}}getSearchMemo=e=>this.memo?.search===e?this.memo.parsed:(this.memo={search:e,parsed:C(e)}).parsed;getPath=()=>location.pathname;getSearch=()=>this.getSearchMemo(location.search);getState=()=>history.state;go=e=>history.go(e);push=e=>{let{url:t,replace:n,state:r}=e;history[n?K:G](r,``,t)};subscribe=e=>(q.forEach(t=>window.addEventListener(t,e)),()=>{q.forEach(t=>window.removeEventListener(t,e))})};const G=`pushState`,K=`replaceState`,q=[`popstate`,G,K,`hashchange`];var J=class{basePath;routes;history;ssrContext;defaultLinkOptions;_;constructor(e){let{basePath:t=`/`,routes:n,history:r,ssrContext:i,defaultLinkOptions:a}=e;this.basePath=y(t),this.routes=n,this.history=r??new W,this.ssrContext=i,this.defaultLinkOptions=a,this._={routeMap:new Map(n.map(e=>[e._.pattern,e]))}}getRoute=e=>{if(typeof e!=`string`)return e;let t=this._.routeMap.get(e);if(!t)throw Error(`[Waymark] Route not found for pattern: ${e}`);return t};match=(e,t)=>{let{from:n,strict:r,params:i}=t,a=this.getRoute(n),o=A(r?a._.regex:a._.looseRegex,a._.keys,e,this.basePath);return!o||i&&Object.keys(i).some(e=>i[e]!==o[e])?null:{route:a,params:o}};matchAll=e=>j(this.routes.map(t=>this.match(e,{from:t,strict:!0})).filter(e=>!!e))[0]??null;createUrl=e=>{let{to:t,params:n={},search:r={}}=e,{pattern:i}=this.getRoute(t)._;return O(E(g(i,n),this.basePath),r)};preload=async e=>{let{to:t,params:n={},search:r={}}=e,i=this.getRoute(t);await Promise.all(i._.preloads.map(e=>e({params:n,search:r})))};navigate=e=>{if(typeof e==`number`)this.history.go(e);else if(`url`in e)this.history.push(e);else{let{replace:t,state:n}=e;this.history.push({url:this.createUrl(e),replace:t,state:n})}}},Y=class{stack=[];index=0;listeners=new Set;constructor(e=`/`){this.stack.push({...k(e),state:void 0})}getCurrent=()=>this.stack[this.index];getPath=()=>this.getCurrent().path;getSearch=()=>this.getCurrent().search;getState=()=>this.getCurrent().state;go=e=>{let t=this.index+e;this.stack[t]&&(this.index=t,this.listeners.forEach(e=>e()))};push=e=>{let{url:t,replace:n,state:r}=e,i={...k(t),state:r};this.stack=this.stack.slice(0,this.index+1),n?this.stack[this.index]=i:this.index=this.stack.push(i)-1,this.listeners.forEach(e=>e())};subscribe=e=>(this.listeners.add(e),()=>{this.listeners.delete(e)})},X=class extends W{getHashUrl=()=>new URL(location.hash.slice(1),`http://w`);getPath=()=>this.getHashUrl().pathname;getSearch=()=>this.getSearchMemo(this.getHashUrl().search);push=e=>{let{url:t,replace:n,state:r}=e;history[n?`replaceState`:`pushState`](r,``,`#${t}`)}};function ee(e){let[t]=m(()=>`router`in e?e.router:new J(e)),n=U(t,t.history.getPath),r=f(()=>t.matchAll(n),[t,n]);return r||console.error(`[Waymark] No matching route found for path:`,n),f(()=>v(M.Provider,{value:t,children:v(N.Provider,{value:r,children:r?.route._.components.reduceRight((e,t)=>v(P.Provider,{value:e,children:v(t,{})}),null)})}),[t,r])}function te(){return R()}function ne(e){let t=F();return d(()=>t.navigate(e),[]),t.ssrContext&&(t.ssrContext.redirect=t.createUrl(e)),null}function re(e){let t=F(),{to:r,replace:a,state:o,params:c,search:u,strict:d,preload:m,preloadDelay:h=50,style:g,className:_,activeStyle:y,activeClassName:b,asChild:x,children:S,...C}={...t.defaultLinkOptions,...e},w=p(null),T=p(null),E=t.createUrl(e),D=!!V({from:e.to,strict:d,params:c}),O=Z(()=>t.preload(e)),k=s(()=>{T.current!==null&&clearTimeout(T.current)},[]),A=s(()=>{k(),T.current=setTimeout(O,h)},[h,k]),j=f(()=>({"data-active":D,style:{...g,...D&&y},className:[_,D&&b].filter(Boolean).join(` `)||void 0}),[D,g,_,y,b]);l(()=>{if(m===`render`)A();else if(m===`viewport`&&w.current){let e=new IntersectionObserver(e=>e.forEach(e=>{e.isIntersecting?A():k()}));return e.observe(w.current),()=>{e.disconnect(),k()}}return k},[m,A,k]);let M=e=>{C.onClick?.(e),!(e.ctrlKey||e.metaKey||e.shiftKey||e.altKey||e.button!==0||e.defaultPrevented)&&(e.preventDefault(),t.navigate({url:E,replace:a,state:o}))},N=e=>{C.onFocus?.(e),m===`intent`&&!e.defaultPrevented&&A()},P=e=>{C.onBlur?.(e),m===`intent`&&k()},I=e=>{C.onPointerEnter?.(e),m===`intent`&&!e.defaultPrevented&&A()},L=e=>{C.onPointerLeave?.(e),m===`intent`&&k()},R={...C,...j,ref:ie(w,C.ref),href:E,onClick:M,onFocus:N,onBlur:P,onPointerEnter:I,onPointerLeave:L};return x&&i(S)?n(S,R):v(`a`,{...R,children:S})}function ie(e,t){return t?n=>{e.current=n;let r=typeof t==`function`?t(n):void(t.current=n);return r&&(()=>{e.current=null,r()})}:e}function Z(e){let t=p(e);return u(()=>{t.current=e},[e]),p(((...e)=>t.current(...e))).current}function ae(e){return()=>v(t,{fallback:v(e,{}),children:R()})}function oe(t){class n extends e{constructor(e){super(e),this.state={children:e.children,error:null}}static getDerivedStateFromError(e){return{error:[e]}}static getDerivedStateFromProps(e,t){return e.children===t.children?t:{children:e.children,error:null}}render(){return this.state.error?v(t,{error:this.state.error[0]}):this.props.children}}return()=>v(n,{children:R()})}function Q(e){return new $({...b(y(e)),validate:e=>e,handles:[],components:[],preloads:[]})}function se(){return Q(``)}var $=class e{_;_types;constructor(e){this._=e}route=t=>new e({...this._,...b(y(`${this._.pattern}/${t}`))});use=t=>{let{_:n}=t;return new e({...this._,handles:[...this._.handles,...n.handles],components:[...this._.components,...n.components],preloads:[...this._.preloads,...n.preloads]}).search(n.validate)};search=t=>(t=x(t),new e({...this._,validate:e=>{let n=this._.validate(e);return{...n,...t({...e,...n})}}}));handle=t=>new e({...this._,handles:[...this._.handles,t]});preload=t=>new e({...this._,preloads:[...this._.preloads,e=>t({params:e.params,search:this._.validate(e.search)})]});component=t=>new e({...this._,components:[...this._.components,o(t)]});lazy=e=>{let t=a(async()=>{let t=await e();return`default`in t?t:{default:t}});return this.preload(e).component(t)};suspense=e=>this.component(ae(e));error=e=>this.component(oe(e));toString=()=>this._.pattern};export{W as BrowserHistory,X as HashHistory,re as Link,N as MatchContext,Y as MemoryHistory,ne as Navigate,te as Outlet,P as OutletContext,$ as Route,J as Router,M as RouterContext,ee as RouterRoot,se as middleware,Q as route,H as useHandles,L as useLocation,V as useMatch,I as useNavigate,R as useOutlet,z as useParams,F as useRouter,B as useSearch,U as useSubscribe};
+import{Component as e,Suspense as t,cloneElement as n,createContext as r,isValidElement as i,lazy as a,memo as o,useCallback as s,useContext as c,useEffect as l,useInsertionEffect as u,useLayoutEffect as d,useMemo as f,useRef as p,useState as m,useSyncExternalStore as h}from"react";import{inject as g,parse as _}from"regexparam";import{jsx as v}from"react/jsx-runtime";function y(e){return`/${e}`.replaceAll(/\/+/g,`/`).replace(/(.+)\/$/,`$1`)}function b(e){let{keys:t,pattern:n}=_(e);return{pattern:e,keys:t,regex:n,weights:e.split(`/`).slice(1).map(e=>e.includes(`*`)?0:e.includes(`:`)?1:2)}}function x(e){return typeof e==`function`?e:t=>{let n=e[`~standard`].validate(t);if(n instanceof Promise)throw Error(`[Waymark] Validation must be synchronous`);if(n.issues)throw Error(`[Waymark] Validation failed`,{cause:n.issues});return n.value}}function S(e){return Object.entries(e).filter(([e,t])=>t!==void 0).map(([e,t])=>`${e}=${encodeURIComponent(w(t))}`).join(`&`)}function C(e){let t=new URLSearchParams(e);return Object.fromEntries([...t.entries()].map(([e,t])=>(t=decodeURIComponent(t),[e,T(t)?JSON.parse(t):t])))}function w(e){return typeof e==`string`&&!T(e)?e:JSON.stringify(e)}function T(e){try{return JSON.parse(e),!0}catch{return!1}}function E(e,t){return y(`${t}/${e}`)}function D(e,t){return(e===t||e.startsWith(`${t}/`))&&(e=e.slice(t.length)||`/`),e}function O(e,t){return[e,S(t)].filter(Boolean).join(`?`)}function k(e){let{pathname:t,search:n}=new URL(e,`http://w`);return{path:t,search:C(n)}}function A(e,t,n,r){let i=e.exec(D(n,r));if(!i)return null;let a={};return t.forEach((e,t)=>{let n=i[t+1];n&&(a[e]=n)}),a}function j(e){return[...e].sort((e,t)=>{let n=e.route._.weights,r=t.route._.weights,i=Math.max(n.length,r.length);for(let e=0;e<i;e++){let t=n[e]??-1,i=r[e]??-1;if(t!==i)return i-t}return 0})}const M=r(null),N=r(null),P=r(null),F=r(null);function I(){let e=c(M);if(e)return e;throw Error(`[Waymark] useRouter must be used within a router context`)}function L(){let e=c(N);if(e)return e;throw Error(`[Waymark] useLocation must be used within a router context`)}function R(e){let t=I(),n=c(P),{from:r,strict:i,params:a}=e,o=t.getRoute(r);return n&&(n.route===o||!i&&n.route._.chain.has(o))&&(!a||Object.keys(a).every(e=>a[e]===n.params[e]))?n.params:null}function z(){return c(F)}function B(){return I().navigate}function V(){let e=c(P);return f(()=>e?.route._.handles??[],[e])}function H(e){let t=R({from:e});if(t)return t;throw Error(`[Waymark] Can't read params for non-matching route: ${e}`)}function U(e){let t=I(),n=L(),r=t.getRoute(e),i=f(()=>r._.validate(n.search),[r,n.search]);return[i,Z((e,r)=>{e=typeof e==`function`?e(i):e;let a={...i,...e},o=O(n.path,a);t.navigate({url:o,replace:r})})]}var W=class{_;_loc=(e,t)=>{let{state:n}=history,[r,i]=this._??[];return i?.path===e&&r===t&&i.state===n?i:(this._=[t,{path:e,search:C(t),state:n}])[1]};constructor(){if(!window[G]){for(let e of[K,q]){let t=history[e];history[e]=function(...n){t.apply(this,n);let r=new Event(e);dispatchEvent(r)}}window[G]=1}}location=()=>this._loc(location.pathname,location.search);go=e=>history.go(e);push=e=>{let{url:t,replace:n,state:r}=e;history[n?q:K](r,``,t)};subscribe=e=>(J.forEach(t=>window.addEventListener(t,e)),()=>{J.forEach(t=>window.removeEventListener(t,e))})};const G=Symbol.for(`wmp01`),K=`pushState`,q=`replaceState`,J=[`popstate`,K,q,`hashchange`];var Y=class{routes;basePath;history;ssrContext;defaultLinkOptions;_;constructor(e){let{routes:t,basePath:n=`/`,history:r,ssrContext:i,defaultLinkOptions:a}=e;this.routes=t,this.basePath=y(n),this.history=r??new W,this.ssrContext=i,this.defaultLinkOptions=a,this._={routeMap:new Map(t.map(e=>[e._.pattern,e]))}}getRoute=e=>{if(typeof e!=`string`)return e;let t=this._.routeMap.get(e);if(!t)throw Error(`[Waymark] Route not found for pattern: ${e}`);return t};match=(e,t)=>{let{regex:n,keys:r}=t._,i=A(n,r,e,this.basePath);return i?{route:t,params:i}:null};matchAll=e=>j(this.routes.map(t=>this.match(e,t)).filter(e=>!!e))[0]??null;createUrl=e=>{let{to:t,params:n={},search:r={}}=e,{pattern:i}=this.getRoute(t)._;return O(E(g(i,n),this.basePath),r)};preload=async e=>{let{to:t,params:n={},search:r={}}=e,{preloads:i}=this.getRoute(t)._;await Promise.all(i.map(e=>e({params:n,search:r})))};navigate=e=>{if(typeof e==`number`)this.history.go(e);else if(`url`in e)this.history.push(e);else{let{replace:t,state:n}=e;this.history.push({url:this.createUrl(e),replace:t,state:n})}}},X=class{stack=[];index=0;listeners=new Set;constructor(e=`/`){this.stack.push({...k(e),state:void 0})}location=()=>this.stack[this.index];go=e=>{let t=this.index+e;this.stack[t]&&(this.index=t,this.listeners.forEach(e=>e()))};push=e=>{let{url:t,replace:n,state:r}=e,i={...k(t),state:r};this.stack=this.stack.slice(0,this.index+1),n?this.stack[this.index]=i:this.index=this.stack.push(i)-1,this.listeners.forEach(e=>e())};subscribe=e=>(this.listeners.add(e),()=>{this.listeners.delete(e)})},ee=class extends W{location=()=>{let{pathname:e,search:t}=new URL(location.hash.slice(1),`http://w`);return this._loc(e,t)};push=e=>{let{url:t,replace:n,state:r}=e;history[n?`replaceState`:`pushState`](r,``,`#${t}`)}};function te(e){let[t]=m(()=>`router`in e?e.router:new Y(e)),{subscribe:n,location:r}=t.history,i=h(n,r,r),a=f(()=>t.matchAll(i.path),[t,i.path]);return a||console.error(`[Waymark] No matching route for path`,i.path),f(()=>v(M.Provider,{value:t,children:v(N.Provider,{value:i,children:v(P.Provider,{value:a,children:a?.route._.components.reduceRight((e,t)=>v(F.Provider,{value:e,children:v(t,{})}),null)})})}),[t,i,a])}function ne(){return z()}function re(e){let t=I();return d(()=>t.navigate(e),[]),t.ssrContext&&(t.ssrContext.redirect=t.createUrl(e)),null}function ie(e){let t=I(),{to:r,replace:a,state:o,params:c,search:u,strict:d,preload:m,preloadDelay:h=50,style:g,className:_,activeStyle:y,activeClassName:b,asChild:x,children:S,...C}={...t.defaultLinkOptions,...e},w=p(null),T=p(null),E=t.createUrl(e),D=!!R({from:r,strict:d,params:c}),O=Z(()=>t.preload(e)),k=s(()=>{clearTimeout(T.current)},[]),A=s(()=>{k(),T.current=setTimeout(O,h)},[h,k]),j=f(()=>({"data-active":D,style:{...g,...D&&y},className:[_,D&&b].filter(Boolean).join(` `)||void 0}),[D,g,_,y,b]);l(()=>{if(m===`render`)A();else if(m===`viewport`&&w.current){let e=new IntersectionObserver(e=>e.forEach(e=>{e.isIntersecting?A():k()}));return e.observe(w.current),()=>{e.disconnect(),k()}}return k},[m,A,k]);let M=e=>{C.onClick?.(e),!(e.ctrlKey||e.metaKey||e.shiftKey||e.altKey||e.button!==0||e.defaultPrevented)&&(e.preventDefault(),t.navigate({url:E,replace:a,state:o}))},N=e=>{C.onFocus?.(e),m===`intent`&&!e.defaultPrevented&&A()},P=e=>{C.onBlur?.(e),m===`intent`&&k()},F=e=>{C.onPointerEnter?.(e),m===`intent`&&!e.defaultPrevented&&A()},L=e=>{C.onPointerLeave?.(e),m===`intent`&&k()},z={...C,...j,ref:ae(w,C.ref),href:E,onClick:M,onFocus:N,onBlur:P,onPointerEnter:F,onPointerLeave:L};return x&&i(S)?n(S,z):v(`a`,{...z,children:S})}function ae(e,t){return t?n=>{e.current=n;let r=typeof t==`function`?t(n):void(t.current=n);return r&&(()=>{e.current=null,r()})}:e}function Z(e){let t=p(e);return u(()=>{t.current=e},[e]),p(((...e)=>t.current(...e))).current}function oe(e){return()=>v(t,{fallback:v(e,{}),children:z()})}function se(t){class n extends e{constructor(e){super(e),this.state={children:e.children,error:null}}static getDerivedStateFromError(e){return{error:[e]}}static getDerivedStateFromProps(e,t){return e.children===t.children?t:{children:e.children,error:null}}render(){return this.state.error?v(t,{error:this.state.error[0]}):this.props.children}}return()=>v(n,{children:z()})}function Q(e){return new $({...b(y(e)),validate:e=>e,handles:[],components:[],preloads:[],chain:new Set})}function ce(){return Q(``)}var $=class e{_;_types;constructor(e){this._=e}route=t=>new e({...this._,...b(y(`${this._.pattern}/${t}`)),chain:new Set([...this._.chain,this])});use=t=>{let{_:n}=t;return new e({...this._,handles:[...this._.handles,...n.handles],components:[...this._.components,...n.components],preloads:[...this._.preloads,...n.preloads]}).search(n.validate)};search=t=>(t=x(t),new e({...this._,validate:e=>{let n=this._.validate(e);return{...n,...t({...e,...n})}}}));handle=t=>new e({...this._,handles:[...this._.handles,t]});preload=t=>new e({...this._,preloads:[...this._.preloads,e=>t({params:e.params,search:this._.validate(e.search)})]});component=t=>new e({...this._,components:[...this._.components,o(t)]});lazy=e=>{let t=a(async()=>{let t=await e();return`default`in t?t:{default:t}});return this.preload(e).component(t)};suspense=e=>this.component(oe(e));error=e=>this.component(se(e));toString=()=>this._.pattern};export{W as BrowserHistory,ee as HashHistory,ie as Link,N as LocationContext,P as MatchContext,X as MemoryHistory,re as Navigate,ne as Outlet,F as OutletContext,$ as Route,Y as Router,M as RouterContext,te as RouterRoot,ce as middleware,Q as route,V as useHandles,L as useLocation,R as useMatch,B as useNavigate,z as useOutlet,H as useParams,I as useRouter,U as useSearch};

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "waymark",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "author": "strblr",
-  "description": "Type-safe router for React",
+  "description": "Type-safe React router that just works - simple setup, full autocomplete, 4kB gzipped",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -38,6 +38,7 @@
   ],
   "scripts": {
     "build": "tsc --noEmit && tsdown",
+    "dev": "tsdown --watch",
     "prepublishOnly": "bun run build && cp ../../README.md README.md",
     "postpublish": "rm -f README.md"
   },