@mpen/rerouter 0.1.9 → 0.3.0

package/README.md

@@ -1,31 +1,89 @@
 # @mpen/rerouter
 
-An implementation of [RFC 6570: URI Template](https://tools.ietf.org/html/rfc6570).
-    
+A lightweight, type-safe router for React with a CLI for generating URL helpers.
+
+## Features
+
+- **Small footprint**: Focuses only on the essentials of routing.
+- **Type-safe URL generation**: CLI tool imports your route file and generates helper functions, ensuring you never have broken links.
+- **Support for `path-to-regexp`**: Familiar syntax for route patterns.
+- **Native `URLPattern` support**: Can use the browser's native `URLPattern` API.
+- **Hooks-based**: Easy access to current path and search parameters.
+
 ## Installation
 
-```sh
+```bash
 bun add @mpen/rerouter
 ```
 
-## API
+## CLI: `rerouter`
+
+The package includes a CLI tool to generate type-safe route helpers from your route definitions.
+
+### Usage
+
+1. Define your routes in a dedicated `.ts` file:
 
 ```ts
-const templ = new UriTemplate('/query{?firstName,lastName}')
-console.log(templ.match('/query?firstName=Bj%c3%b6rk&lastName=Gu%c3%b0mundsd%c3%b3ttir'))
-// {
-//   score: 7,
-//   params: {
-//     firstName: "Björk",
-//     lastName: "Guðmundsdóttir"
-//   }
-// }
-console.log(templ.expand({firstName: 'Mark', lastName: 'Penner'}))
-// /query?firstName=Mark&lastName=Penner
+// routes.ts
+export default [
+    { name: 'home', pattern: '/', component: () => import('./pages/Home') },
+    { name: 'userProfile', pattern: '/user/:id', component: () => import('./pages/UserProfile') },
+    { pattern: '/user/:id/settings', component: () => import('./pages/UserProfile') },
+]
 ```
 
-That's it. That's the whole API. 2 methods.
+Keep this file side-effect-free. The CLI imports and evaluates the route file to extract route names and patterns, so avoid top-level browser access, data fetching, app bootstrapping, or eager page component imports. Put route components behind `() => import('./pages/...')` loaders so generation does not pull page modules into the CLI process.
+
+The `name` field is optional. Named string-pattern routes are included in generated URL helpers; unnamed routes still match at runtime but are skipped by the generator.
 
-It's been tested against https://github.com/uri-templates/uritemplate-test and all 157 tests pass.
+2. Run the generator:
+
+```bash
+bunx @mpen/rerouter routes.ts -o src/routes.gen.ts
+```
+
+3. Use the generated helpers:
+
+```tsx
+import { userProfile } from './routes.gen'
+
+// Returns "/user/123"
+const url = userProfile({ id: 123 })
+```
 
-The `score` is still experimental. The idea is that you can run a URL against multiple templates and if multiple match, you should use the one with the highest score. Higher score means more matching parts, i.e. more specific match.
+## Library Usage
+
+### Router
+
+```tsx
+import { Router } from '@mpen/rerouter'
+import ROUTES from './routes'
+
+function App() {
+    return <Router routes={ROUTES} loading={<div>Loading...</div>} />
+}
+```
+
+### Link
+
+```tsx
+import { Link } from '@mpen/rerouter'
+import { userProfile } from './routes.gen'
+
+function Navigation() {
+    return <Link href={userProfile({ id: 'me' })}>My Profile</Link>
+}
+```
+
+### Hooks
+
+```tsx
+import { useUrlPath, useUrlSearchParams } from '@mpen/rerouter'
+
+function MyComponent() {
+    const path = useUrlPath()
+    const searchParams = useUrlSearchParams()
+    // ...
+}
+```

package/dist/bin.d.ts

@@ -0,0 +1,29 @@
+//#region src/bin.d.ts
+type RunOptions = {
+  cwd?: string;
+  commandName?: string;
+  commandArgs?: readonly string[];
+};
+type RunResult = {
+  exitCode?: number;
+  stdout: string;
+  stderr: string;
+};
+/**
+ * Runs the rerouter CLI implementation without spawning a separate process.
+ *
+ * @param args - Command line arguments, excluding the binary name.
+ * @param options - Runtime options used to resolve paths and render the command comment.
+ * @returns Captured stdout, stderr, and an optional process exit code.
+ *
+ * @example
+ * ```ts
+ * const result = await runRerouterBin(['./routes.ts'])
+ * process.stdout.write(result.stdout)
+ * ```
+ *
+ * @internal
+ */
+declare function runRerouterBin(args: readonly string[], options?: RunOptions): Promise<RunResult>;
+//#endregion
+export { runRerouterBin };

package/dist/bin.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+import { n as normalizeRoutes, t as normalizeLegacyPathToRegexpSyntax } from "./routes-Hpf6cwcZ.js";
+import { parse } from "path-to-regexp";
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+//#region src/bin.ts
+const PARSE_CONFIG = {
+	options: {
+		output: {
+			type: "string",
+			short: "o"
+		},
+		write: {
+			type: "boolean",
+			short: "w"
+		},
+		"wildcard-delimiter": { type: "string" },
+		"encode-function": { type: "string" }
+	},
+	allowPositionals: true,
+	strict: true
+};
+function escapeString(value) {
+	return JSON.stringify(value);
+}
+function shellEscape(arg) {
+	if (/^[a-z0-9/_.-]+$/i.test(arg)) return arg;
+	return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+function compilePathGenerator(pattern, { delimiter = "/", encode = "encodeURIComponent", functionName = "generate" } = {}) {
+	const { tokens } = parse(normalizeLegacyPathToRegexpSyntax(pattern));
+	const baseProps = [];
+	const groupTypes = [];
+	const typeOfParam = (t) => t.type === "wildcard" ? "WildcardType" : "ParamType";
+	const makeProp = (name, t) => ({
+		name,
+		type: typeOfParam(t)
+	});
+	function collectGroupProps(ts2) {
+		const props = [];
+		for (const t of ts2) if (t.type === "param" || t.type === "wildcard") props.push(makeProp(t.name, t));
+		else if (t.type === "group") props.push(...collectGroupProps(t.tokens));
+		return props;
+	}
+	function collectTypes(ts2, intoBase = true) {
+		for (const t of ts2) if ((t.type === "param" || t.type === "wildcard") && intoBase) baseProps.push(makeProp(t.name, t));
+		else if (t.type === "group") {
+			const groupProps = collectGroupProps(t.tokens);
+			if (groupProps.length) {
+				const some = [
+					"{",
+					...groupProps.map((p) => `    ${escapeString(p.name)}: ${p.type}`),
+					"}"
+				].join("\n");
+				groupTypes.push(`AllOrNone<${some}>`);
+			}
+			collectTypes(t.tokens, false);
+		}
+	}
+	collectTypes(tokens);
+	const baseParamsType = [
+		"{",
+		...baseProps.map((p) => `    ${escapeString(p.name)}: ${p.type}`),
+		"}"
+	].join("\n");
+	const paramsType = groupTypes.length ? `${baseParamsType} & ${groupTypes.join(" & ")}` : baseParamsType;
+	const lines = [];
+	const indentUnit = "    ";
+	const line = (indentLevel, text = "") => {
+		if (text === "") lines.push("");
+		else lines.push(indentUnit.repeat(indentLevel) + text);
+	};
+	const hasAnyParams = baseProps.length > 0 || groupTypes.length > 0;
+	if (hasAnyParams) {
+		lines.push(`export function ${functionName}(`);
+		lines.push(`    params: ${paramsType}`);
+		lines.push(`): string {`);
+	} else lines.push(`export function ${functionName}(): string {`);
+	line(1, `let sb = ""`);
+	line(0);
+	const delim = escapeString(delimiter);
+	function collectNames(ts2) {
+		const names = [];
+		for (const t of ts2) if (t.type === "param" || t.type === "wildcard") names.push(t.name);
+		else if (t.type === "group") names.push(...collectNames(t.tokens));
+		return names;
+	}
+	function emitTokens(ts2, indentLevel, optional = false) {
+		if (!optional && hasAnyParams) {
+			for (const t of ts2) if (t.type === "param" || t.type === "wildcard") line(indentLevel, `if (params[${escapeString(t.name)}] == null) throw new Error(${escapeString(`Missing param: ${t.name}`)})`);
+		}
+		for (const t of ts2) if (t.type === "text") line(indentLevel, `sb += ${escapeString(t.value)}`);
+		else if (t.type === "param") line(indentLevel, `sb += (${encode})(String(params[${escapeString(t.name)}]))`);
+		else if (t.type === "wildcard") line(indentLevel, `sb += Array.from(params[${escapeString(t.name)}], v => (${encode})(String(v))).join(${delim})`);
+		else if (t.type === "group") {
+			const names = collectNames(t.tokens).map((name) => escapeString(name));
+			if (!names.length) continue;
+			const all = names.map((n) => `params[${n}] != null`).join(" && ");
+			const none = names.map((n) => `params[${n}] == null`).join(" && ");
+			const list = names.join(", ");
+			line(indentLevel, `if (${all}) {`);
+			emitTokens(t.tokens, indentLevel + 1, true);
+			line(indentLevel, `} else if (!(${none})) {`);
+			line(indentLevel + 1, `throw new Error(${escapeString(`Group requires all-or-none: ${list}`)})`);
+			line(indentLevel, `}`);
+		}
+	}
+	emitTokens(tokens, 1);
+	line(0);
+	line(1, `return sb`);
+	lines.push(`}`);
+	return lines.join("\n");
+}
+function toRouteFunctionName(routeName) {
+	return routeName.trim().replace(/[^a-zA-Z0-9_]/g, "_").replace(/^[^a-zA-Z_]+/, "") || "route";
+}
+async function importRoutes(routesPath) {
+	const mod = await import(pathToFileURL(routesPath).href);
+	if (!Array.isArray(mod.default)) throw new Error("Routes file must default export an array of routes.");
+	return mod.default;
+}
+function extractRoutes(routes) {
+	return normalizeRoutes(routes).flatMap((route) => {
+		if (!route.name || typeof route.pattern !== "string") return [];
+		return [{
+			name: route.name,
+			pattern: route.pattern
+		}];
+	});
+}
+async function main(options, positionals, { cwd = process.cwd(), commandName = "rerouter", commandArgs = process.argv.slice(2) } = {}) {
+	const [routesPathArg] = positionals;
+	if (!routesPathArg) return {
+		exitCode: 1,
+		stdout: "",
+		stderr: "Usage: rerouter <routes-file> [-o <output-file>] [-w] [--wildcard-delimiter <string>] [--encode-function <identifier>]\n"
+	};
+	const routesPath = path.resolve(cwd, routesPathArg);
+	let outputPath;
+	if (options.output) outputPath = path.resolve(cwd, options.output);
+	else if (options.write) outputPath = path.join(path.dirname(routesPath), path.basename(routesPath, path.extname(routesPath)) + ".gen.ts");
+	const routes = extractRoutes(await importRoutes(routesPath)).map((r) => ({
+		...r,
+		pattern: r.pattern.trim()
+	})).filter((r) => r.pattern.startsWith("/") && r.pattern !== "*");
+	const wildcardDelimiter = options["wildcard-delimiter"] ?? "/";
+	const encodeFunction = options["encode-function"] ?? "encodeURIComponent";
+	const commandText = [commandName, ...commandArgs.map(shellEscape)].join(" ");
+	const out = [];
+	out.push(`// Do not modify this file. It was auto-generated with the following command:`);
+	out.push(`// $ ${commandText}`);
+	out.push(``);
+	out.push(`type AllOrNone<T> =`);
+	out.push(`    | Required<T>`);
+	out.push(`    | { [K in keyof T]?: never }`);
+	out.push(``);
+	out.push(`type ParamType = string | number | boolean`);
+	out.push(`type WildcardType = Iterable<ParamType>`);
+	out.push(``);
+	if (!routes.length) {
+		out.push(`// No string route patterns found in the default export.`);
+		out.push(``);
+	} else {
+		const usedNames = /* @__PURE__ */ new Set();
+		for (const route of routes) {
+			const base = toRouteFunctionName(route.name);
+			let name = base;
+			let i = 2;
+			while (usedNames.has(name)) name = `${base}_${i++}`;
+			usedNames.add(name);
+			out.push(compilePathGenerator(route.pattern, {
+				functionName: name,
+				delimiter: wildcardDelimiter,
+				encode: encodeFunction
+			}));
+			out.push(``);
+		}
+	}
+	const finalOutput = out.join("\n");
+	if (outputPath) {
+		await fs.writeFile(outputPath, finalOutput, "utf8");
+		return {
+			stdout: "",
+			stderr: `Wrote ${outputPath}\n`
+		};
+	} else return {
+		stdout: finalOutput,
+		stderr: ""
+	};
+}
+/**
+* Runs the rerouter CLI implementation without spawning a separate process.
+*
+* @param args - Command line arguments, excluding the binary name.
+* @param options - Runtime options used to resolve paths and render the command comment.
+* @returns Captured stdout, stderr, and an optional process exit code.
+*
+* @example
+* ```ts
+* const result = await runRerouterBin(['./routes.ts'])
+* process.stdout.write(result.stdout)
+* ```
+*
+* @internal
+*/
+async function runRerouterBin(args, options = {}) {
+	const { values, positionals } = parseArgs({
+		...PARSE_CONFIG,
+		args: [...args]
+	});
+	return main(values, positionals, {
+		...options,
+		commandArgs: args
+	});
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) runRerouterBin(process.argv.slice(2)).then((result) => {
+	if (result.stdout) process.stdout.write(result.stdout);
+	if (result.stderr) process.stderr.write(result.stderr);
+	if (typeof result.exitCode === "number") process.exitCode = result.exitCode;
+}, (err) => {
+	console.error(err ?? "An unknown error occurred");
+	process.exitCode = 1;
+});
+//#endregion
+export { runRerouterBin };

package/dist/hooks-Dlwcb0sV.js

@@ -0,0 +1,20 @@
+import { useMemo, useSyncExternalStore } from "react";
+//#region src/hooks/useUrl.ts
+const getPathname = () => window.location.pathname;
+const getSearch = () => window.location.search;
+function subscribe(cb) {
+	const handler = () => cb();
+	window.addEventListener("popstate", handler);
+	return () => {
+		window.removeEventListener("popstate", handler);
+	};
+}
+function useUrlPath() {
+	return useSyncExternalStore(subscribe, getPathname, getPathname);
+}
+function useUrlSearchParams() {
+	const search = useSyncExternalStore(subscribe, getSearch, getSearch);
+	return useMemo(() => new URLSearchParams(search), [search]);
+}
+//#endregion
+export { useUrlSearchParams as n, useUrlPath as t };

package/dist/hooks.d.ts

@@ -0,0 +1,2 @@
+import { n as useUrlSearchParams, t as useUrlPath } from "./index-BYXpNitc.js";
+export { useUrlPath, useUrlSearchParams };

package/dist/hooks.js

@@ -0,0 +1,2 @@
+import { n as useUrlSearchParams, t as useUrlPath } from "./hooks-Dlwcb0sV.js";
+export { useUrlPath, useUrlSearchParams };

package/dist/index-BYXpNitc.d.ts

@@ -0,0 +1,5 @@
+//#region src/hooks/useUrl.d.ts
+declare function useUrlPath(): string;
+declare function useUrlSearchParams(): URLSearchParams;
+//#endregion
+export { useUrlSearchParams as n, useUrlPath as t };

package/dist/index.d.ts

@@ -0,0 +1,265 @@
+import { n as useUrlSearchParams, t as useUrlPath } from "./index-BYXpNitc.js";
+import { ClassValue } from "@mpen/classcat";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import { ComponentType, ReactNode } from "react";
+import { OverrideProps } from "@mpen/ts-types/react";
+import { Override } from "@mpen/ts-types";
+
+//#region src/components/Link.d.ts
+/**
+ * Values accepted by [`Link`]{@link Link} for building query strings.
+ *
+ * @example
+ * ```tsx
+ * <Link to="/matches" search={{ page: 2, sort: 'desc' }}>
+ *     Matches
+ * </Link>
+ * ```
+ */
+type SearchParamsInit = string | string[][] | Record<string, string | number | boolean | undefined | null> | URLSearchParams;
+/**
+ * Props for [`Link`]{@link Link}.
+ */
+type LinkProps = OverrideProps<'a', {
+  /**
+   * Classes to apply to the rendered anchor.
+   */
+  className?: ClassValue;
+  /**
+   * Destination URL passed to the rendered anchor's `href` attribute.
+   */
+  to: string;
+  /**
+   * Query parameters to merge into [`LinkProps.to`]{@link LinkProps#to}.
+   */
+  search?: SearchParamsInit;
+  /**
+   * Whether navigation should replace the current history entry instead of pushing a new one.
+   */
+  replace?: boolean;
+  href: never;
+  onClick: never;
+}>;
+/**
+ * Renders an anchor that navigates with rerouter history updates on ordinary clicks.
+ *
+ * @example
+ * ```tsx
+ * <Link to="/matches/42" search={{ tab: 'details' }}>
+ *     View match
+ * </Link>
+ * ```
+ *
+ * @param props - Anchor props plus rerouter navigation options.
+ * @returns An anchor element that pushes or replaces the browser URL.
+ */
+declare function Link({
+  to,
+  search,
+  children,
+  className,
+  replace,
+  ...rest
+}: LinkProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/components/NavLink.d.ts
+type NavLinkMatch = 'exact' | 'prefix';
+/**
+ * Props for [`NavLink`]{@link NavLink}.
+ */
+type NavLinkProps = Override<LinkProps, {
+  /**
+   * Classes to apply when the link target matches the current path.
+   */
+  activeClass?: ClassValue;
+  /**
+   * Classes to apply when the link target does not match the current path.
+   */
+  inactiveClass?: ClassValue;
+  /**
+   * How to compare the link target to the current path.
+   *
+   * @defaultValue `'exact'`
+   */
+  match?: NavLinkMatch;
+}>;
+/**
+ * Renders a [`Link`]{@link Link} with classes selected from the current route.
+ *
+ * @example
+ * ```tsx
+ * <NavLink
+ *     activeClass={['pill', 'active']}
+ *     inactiveClass={['pill', { muted: true }]}
+ *     to="/settings"
+ * >
+ *     Settings
+ * </NavLink>
+ * ```
+ *
+ * @param props - Link props plus active and inactive class values.
+ * @returns An anchor element that navigates through rerouter.
+ */
+declare function NavLink({
+  activeClass,
+  className,
+  inactiveClass,
+  match,
+  to,
+  ...props
+}: NavLinkProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/lib/routes.d.ts
+/**
+ * Route params captured from the current URL pathname.
+ */
+type RouteParams = Record<string, string | undefined>;
+/**
+ * A React component that receives URL params captured for its route.
+ *
+ * @example
+ * ```tsx
+ * const UserPage: RouteComponent<{ id: string }> = ({ id }) => <div>{id}</div>
+ * ```
+ */
+type RouteComponent<TParams extends RouteParams = RouteParams> = ComponentType<TParams>;
+/**
+ * A dynamically imported route component module.
+ *
+ * @example
+ * ```tsx
+ * export default function UserPage({ id }: { id: string }) {
+ *     return <div>{id}</div>
+ * }
+ * ```
+ */
+type RouteComponentModule<TParams extends RouteParams = RouteParams> = {
+  default: RouteComponent<TParams>;
+};
+/**
+ * Loads a route component on demand.
+ *
+ * @example
+ * ```tsx
+ * const loadUserPage: RouteComponentLoader<{ id: string }> = () => import('./pages/UserPage')
+ * ```
+ */
+type RouteComponentLoader<TParams extends RouteParams = RouteParams> = () => Promise<RouteComponentModule<TParams>>;
+/**
+ * Object route definition consumed by [`Router`]{@link Router}.
+ *
+ * @example
+ * ```tsx
+ * const route: RouteObject = {
+ *     name: 'userProfile',
+ *     pattern: '/users/:id',
+ *     component: () => import('./pages/UserProfile'),
+ * }
+ * ```
+ */
+type RouteObject = {
+  /**
+   * Optional route name used by the CLI to generate a URL helper.
+   *
+   * Routes without a name still participate in runtime matching, but are skipped by the
+   * helper generator.
+   */
+  name?: string;
+  pattern: string | URLPattern;
+  component: RouteComponentLoader<any>;
+};
+/**
+ * Route definition consumed by [`Router`]{@link Router}.
+ *
+ * @example
+ * ```tsx
+ * const routes: readonly Route[] = [
+ *     { name: 'home', pattern: '/', component: () => import('./pages/Home') },
+ *     { pattern: '/users/:id', component: () => import('./pages/UserLayout') },
+ * ]
+ * ```
+ */
+type Route = RouteObject;
+/**
+ * Route definition normalized into a single object shape with a pathname matcher.
+ */
+type NormalizedRoute = {
+  name?: string;
+  pattern: string | URLPattern;
+  component: RouteComponentLoader<any>;
+  matches(pathname: string): RouteParams | null;
+};
+/**
+ * Converts legacy `path-to-regexp` syntax that is ignored by URL generation into syntax accepted
+ * by the current parser.
+ *
+ * @param pattern - The route pattern to normalize.
+ * @returns The pattern with custom regexp constraints stripped and optional group suffixes removed.
+ *
+ * @example
+ * ```ts
+ * normalizeLegacyPathToRegexpSyntax('/blog/:id(\\d+){-:title}?')
+ * // '/blog/:id{-:title}'
+ * ```
+ *
+ * @internal
+ */
+declare function normalizeLegacyPathToRegexpSyntax(pattern: string): string;
+/**
+ * Normalizes routes into objects with a shared matcher implementation.
+ *
+ * @param routes - The route definitions to normalize.
+ * @returns Routes with stable `name`, `pattern`, `component`, and `matches` fields.
+ *
+ * @example
+ * ```tsx
+ * const normalized = normalizeRoutes(routes)
+ * const match = normalized[0]?.matches('/users/123')
+ * ```
+ */
+declare function normalizeRoutes(routes: readonly Route[]): NormalizedRoute[];
+//#endregion
+//#region src/components/Router.d.ts
+/**
+ * Props for [`Router`]{@link Router}.
+ *
+ * @example
+ * ```tsx
+ * <Router routes={routes} loading={<div>Loading...</div>} />
+ * ```
+ */
+interface RouterProps {
+  /**
+   * Route definitions to match against the current URL pathname.
+   */
+  routes: readonly Route[];
+  /**
+   * Optional fallback rendered while a matched route component module is loading.
+   */
+  loading?: ReactNode;
+}
+/**
+ * Renders the first route that matches the current URL pathname.
+ *
+ * @param props - The router props.
+ * @returns The matched lazy route component, the loading fallback, or `null`.
+ *
+ * @example
+ * ```tsx
+ * import routes from './routes'
+ *
+ * function App() {
+ *     return <Router routes={routes} loading={<div>Loading...</div>} />
+ * }
+ * ```
+ */
+declare function Router({
+  routes,
+  loading
+}: RouterProps): _$react_jsx_runtime0.JSX.Element | null;
+//#endregion
+//#region src/lib/url.d.ts
+declare function pushUrl(next: string, state?: unknown): void;
+declare function replaceUrl(next: string, state?: unknown): void;
+//#endregion
+export { Link, LinkProps, NavLink, NavLinkMatch, NavLinkProps, NormalizedRoute, Route, RouteComponent, RouteComponentLoader, RouteComponentModule, RouteObject, RouteParams, Router, RouterProps, SearchParamsInit, normalizeLegacyPathToRegexpSyntax, normalizeRoutes, pushUrl, replaceUrl, useUrlPath, useUrlSearchParams };