@typeroute/router 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,213 @@
+import * as react from "react";
+import { AnchorHTMLAttributes, CSSProperties, ComponentType, ReactNode, RefAttributes } from "react";
+import { RouteParams } from "regexparam";
+import { EmptyObject, Merge, Simplify } from "type-fest";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/utils/types.d.ts
+type ParsePattern<P extends string> = Simplify<RouteParams<P>>;
+type NormalizePath<P extends string> = RemoveTrailingSlash<DedupSlashes<`/${P}`>>;
+type DedupSlashes<P extends string> = P extends `${infer Prefix}//${infer Rest}` ? `${Prefix}${DedupSlashes<`/${Rest}`>}` : P;
+type RemoveTrailingSlash<P extends string> = P extends `${infer Prefix}/` ? Prefix extends "" ? "/" : Prefix : P;
+type MaybeKey<K extends string, T> = T extends EmptyObject ? { [P in K]?: EmptyObject } : {} extends T ? { [P in K]?: T } : { [P in K]: T };
+type OptionalOnUndefined<T extends object> = Simplify<{ [K in keyof T as undefined extends T[K] ? never : K]: T[K] } & { [K in keyof T as undefined extends T[K] ? K : never]?: T[K] }>;
+//#endregion
+//#region src/types.d.ts
+interface Register {}
+type RouteList = Register extends {
+  routes: infer RouteList extends ReadonlyArray<Route>;
+} ? RouteList : ReadonlyArray<Route>;
+type Handle = Register extends {
+  handle: infer Handle;
+} ? Handle : any;
+interface Middleware<S extends {} = any> {
+  use: <S2 extends {}>(middleware: Middleware<S2>) => Middleware<Merge<S, OptionalOnUndefined<S2>>>;
+  search: <S2 extends {}>(validate: Validator<S, S2>) => Middleware<Merge<S, OptionalOnUndefined<S2>>>;
+  handle: (handle: Handle) => Middleware<S>;
+  preload: (preload: (context: PreloadContext<{}, S>) => Promise<any>) => Middleware<S>;
+  component: (component: ComponentType) => Middleware<S>;
+  lazy: (loader: ComponentLoader) => Middleware<S>;
+  suspense: (fallback: ComponentType) => Middleware<S>;
+  error: (fallback: ComponentType<{
+    error: unknown;
+  }>) => Middleware<S>;
+}
+type Validator<S extends {}, S2 extends {}> = ((search: S & Record<string, unknown>) => S2) | StandardSchemaV1<Record<string, unknown>, S2>;
+interface PreloadContext<Ps extends {} = any, S extends {} = any> {
+  params: Ps;
+  search: S;
+}
+interface RouterOptions {
+  routes: RouteList;
+  basePath?: string;
+  history?: HistoryLike;
+  ssrContext?: SSRContext;
+  defaultLinkOptions?: LinkOptions;
+}
+type Pattern = RouteList[number]["_"]["pattern"];
+type GetRoute<P extends Pattern> = Extract<RouteList[number], {
+  _: {
+    pattern: P;
+  };
+}>;
+type Params<P extends Pattern> = GetRoute<P>["_types"]["params"];
+type Search<P extends Pattern> = GetRoute<P>["_types"]["search"];
+type MatchOptions<P extends Pattern> = {
+  from: P | GetRoute<P>;
+  strict?: boolean;
+  params?: Partial<Params<P>>;
+};
+type Match<P extends Pattern = Pattern> = {
+  route: GetRoute<P>;
+  params: Params<P>;
+};
+type NavigateOptions<P extends Pattern> = {
+  to: P | GetRoute<P>;
+  replace?: boolean;
+  state?: any;
+} & MaybeKey<"params", Params<P>> & MaybeKey<"search", Search<P>>;
+interface LinkOptions {
+  strict?: boolean;
+  preload?: "intent" | "render" | "viewport" | false;
+  preloadDelay?: number;
+  style?: CSSProperties;
+  className?: string;
+  activeStyle?: CSSProperties;
+  activeClassName?: string;
+}
+type SSRContext = {
+  redirect?: string;
+  statusCode?: number;
+};
+interface HistoryLike {
+  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;
+}>;
+//#endregion
+//#region src/route.d.ts
+declare function route<P extends string>(pattern: P): Route<NormalizePath<P>, ParsePattern<NormalizePath<P>>, {}>;
+declare function middleware(): Middleware<{}>;
+declare class Route<P extends string = string, Ps extends {} = any, S extends {} = any> implements Middleware<S> {
+  readonly _: {
+    pattern: P;
+    keys: string[];
+    regex: RegExp;
+    loose: RegExp;
+    weights: number[];
+    validate: (search: Record<string, unknown>) => S;
+    handles: Handle[];
+    components: ComponentType[];
+    preloads: ((context: PreloadContext) => Promise<any>)[];
+    p?: Route;
+  };
+  readonly _types: {
+    params: Ps;
+    search: S;
+  };
+  constructor(_: typeof this._);
+  route: <P2 extends string>(pattern: P2) => Route<NormalizePath<`${P}/${P2}`>, ParsePattern<NormalizePath<`${P}/${P2}`>>, S>;
+  use: <S2 extends {}>(middleware: Middleware<S2>) => Route<P, Ps, Merge<S, OptionalOnUndefined<S2>>>;
+  search: <S2 extends {}>(validate: Validator<S, S2>) => Route<P, Ps, Merge<S, OptionalOnUndefined<S2>>>;
+  handle: (handle: Handle) => Route<P, Ps, S>;
+  preload: (preload: (context: PreloadContext<Ps, S>) => Promise<any>) => Route<P, Ps, S>;
+  component: (component: ComponentType) => Route<P, Ps, S>;
+  lazy: (loader: ComponentLoader) => Route<P, Ps, S>;
+  suspense: (fallback: ComponentType) => Route<P, Ps, S>;
+  error: (fallback: ComponentType<{
+    error: unknown;
+  }>) => Route<P, Ps, S>;
+  toString: () => P;
+}
+//#endregion
+//#region src/router/router.d.ts
+declare class Router {
+  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;
+  matchAll: (path: string) => Match | null;
+  createUrl: <P extends Pattern>(options: NavigateOptions<P>) => string;
+  preload: <P extends Pattern>(options: NavigateOptions<P>) => Promise<void>;
+  navigate: <P extends Pattern>(options: NavigateOptions<P> | HistoryPushOptions | number) => void;
+}
+//#endregion
+//#region src/router/browser-history.d.ts
+declare class BrowserHistory implements HistoryLike {
+  private _?;
+  protected _loc: (path: string, search: string) => HistoryLocation;
+  constructor();
+  location: () => HistoryLocation;
+  go: (delta: number) => void;
+  push: (options: HistoryPushOptions) => void;
+  subscribe: (listener: () => void) => () => void;
+}
+//#endregion
+//#region src/router/memory-history.d.ts
+declare class MemoryHistory implements HistoryLike {
+  private stack;
+  private index;
+  private listeners;
+  constructor(url?: string);
+  location: () => HistoryLocation;
+  go: (delta: number) => void;
+  push: (options: HistoryPushOptions) => void;
+  subscribe: (listener: () => void) => () => void;
+}
+//#endregion
+//#region src/router/hash-history.d.ts
+declare class HashHistory extends BrowserHistory {
+  location: () => HistoryLocation;
+  push: (options: HistoryPushOptions) => void;
+}
+//#endregion
+//#region src/react/components.d.ts
+type RouterRootProps = RouterOptions | {
+  router: Router;
+};
+declare function RouterRoot(props: RouterRootProps): ReactNode;
+declare function Outlet(): ReactNode;
+type NavigateProps<P extends Pattern> = NavigateOptions<P>;
+declare function Navigate<P extends Pattern>(props: NavigateProps<P>): null;
+type LinkProps<P extends Pattern> = NavigateOptions<P> & LinkOptions & AnchorHTMLAttributes<HTMLAnchorElement> & RefAttributes<HTMLAnchorElement> & {
+  asChild?: boolean;
+};
+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>): Match<P> | null;
+declare function useOutlet(): ReactNode;
+declare function useNavigate(): <P extends Pattern>(options: number | HistoryPushOptions | NavigateOptions<P>) => void;
+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];
+//#endregion
+//#region src/react/contexts.d.ts
+declare const RouterContext: react.Context<Router | null>;
+declare const LocationContext: react.Context<HistoryLocation | null>;
+declare const MatchContext: react.Context<Match | null>;
+declare const OutletContext: react.Context<ReactNode>;
+//#endregion
+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

@@ -0,0 +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,loose:_(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(`[TypeRoute] Validation can't be async`);if(n.issues)throw Error(`[TypeRoute] 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({keys:e,regex:t,loose:n},r,i,a){let o=(r?t:n).exec(D(i,a));if(!o)return null;let s={};return e.forEach((e,t)=>{let n=o[t+1];n&&(s[e]=n)}),s}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(`[TypeRoute] useRouter must be within a router context`)}function L(){let e=c(N);if(e)return e;throw Error(`[TypeRoute] useLocation must be within a router context`)}function R(e){let t=I(),{path:n}=L();return f(()=>t.match(n,e),[t,n,e.from,e.strict,e.params])}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.params;throw Error(`[TypeRoute] Can't read params for non-matching route ${e}`)}function U(e){let t=I(),{search:n,path:r}=L(),i=t.getRoute(e),a=f(()=>i._.validate(n),[i,n]);return[a,Z((e,n)=>{e=typeof e==`function`?e(a):e;let i=O(r,{...a,...e});t.navigate({url:i,replace:n})})]}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(`[TypeRoute] Route not found for ${e}`);return t};match=(e,t)=>{let{from:n,strict:r,params:i}=t,a=this.getRoute(n),o=A(a._,r,e,this.basePath);return o&&(!i||Object.keys(i).every(e=>i[e]===o[e]))?{route:a,params:o}:null};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,{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(`[TypeRoute] 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:[]})}function ce(){return Q(``)}var $=class e{_;_types;constructor(e){this._=e}route=t=>new e({...this._,...b(y(`${this._.pattern}/${t}`)),p: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

@@ -0,0 +1,59 @@
+{
+  "name": "@typeroute/router",
+  "version": "0.7.0",
+  "license": "MIT",
+  "author": "strblr",
+  "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",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/strblr/typeroute.git"
+  },
+  "homepage": "https://typeroute.com",
+  "bugs": "https://github.com/strblr/typeroute/issues",
+  "keywords": [
+    "react",
+    "router",
+    "typescript",
+    "type",
+    "typed",
+    "strongly-typed",
+    "type-safe",
+    "navigate",
+    "navigation",
+    "route",
+    "history",
+    "search",
+    "params",
+    "simple",
+    "lightweight"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && tsdown",
+    "dev": "tsdown --watch",
+    "prepublishOnly": "bun run build && cp ../../README.md README.md",
+    "postpublish": "rm -f README.md"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.8",
+    "@types/react": "^19.2.11",
+    "tsdown": "^0.20.2",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "regexparam": "^3.0.0",
+    "type-fest": "5.4.1"
+  }
+}