@askrjs/askr/router

AccessDecisiontype

AccessDecision: AccessAllowDecision | AccessRedirectDecision | AccessDenyDecision

Outcome of a {@link RoutePolicy} evaluation: allow, redirect, or deny.

AccessDenyDecisiontype

AccessDenyDecision: any

Policy decision produced by {@link deny }/{@link unauthorized }/{@link forbidden }/{@link notFound }.

kind

kind: 'deny';

status

status: AccessDenyStatus;

AccessRedirectDecisiontype

AccessRedirectDecision: any

Policy decision produced by {@link redirect }: sends the visitor to another URL.

kind

kind: 'redirect';

to

to: string;

status

status?: AccessRedirectStatus;

replace

replace?: boolean;

allowtype

allow: () => AccessAllowDecision

Policy decision: allow the route to render.

AuthContexttype

AuthContext: any

Authentication state resolved for one request.

authenticated

Whether a valid principal was resolved.

principal

Resolved principal, or null for anonymous requests.

session

Resolved session, or null when no session is active.

tenant

Resolved tenant identifier, or null when unavailable.

scopes

Optional scopes carried by the credential.

AuthRequirementtype

AuthRequirement: (context: AuthContext<P, S>) => AuthDecision | PromiseLike<AuthDecision>

Predicate that allows or rejects an authentication context.

createRouteRegistrytype

createRouteRegistry: (definition: RouteDefinition, options?: RouteRegistryOptions) => RouteRegistry

Run `definition` to declare routes (via `route`/`page`/`group`/`fallback`) and build a {@link RouteRegistry} to pass to `createSPA`/`hydrateSPA`.

currentAuthtype

currentAuth: () => AuthContext$1

Return the identity resolved for the route currently being rendered.

currentRoutetype

currentRoute: <TParams extends RouteParams = RouteParams>() => RouteSnapshot<TParams>

Read the currently active route's {@link RouteSnapshot}; reactive during component render.

defertype

defer: <T>(promise: PromiseLike<T>) => Deferred<T>

Wrap a promise as a {@link Deferred} value that tracks its settled state and result.

Deferredtype

Deferred: any

A promise-backed value that can be read synchronously once settled, produced by {@link defer}.

state

readonly state: DeferredState;

value

readonly value: T | undefined;

error

readonly error: unknown;

promise

readonly promise: Promise<T>;

DeferredStatetype

DeferredState: 'pending' | 'fulfilled' | 'rejected'

Lifecycle state of a {@link Deferred} value.

denytype

deny: (status: AccessDenyStatus) => AccessDenyDecision

Policy decision: deny the request with the given HTTP status.

fallbacktype

fallback: (Component: RouteComponent) => void

Declare the catch-all `/*` fallback route for the enclosing scope.

forbiddentype

forbidden: () => AccessDenyDecision

Policy decision: deny with 403 Forbidden.

grouptype

group: (options: GroupHelperOptions, fn: RouteDefinition) => void

Declare a group of routes sharing `options` (auth, policies, layout, meta).

GroupHelperOptionstype

GroupHelperOptions: any

Options accepted by the `group()` route-declaration helper.

layout

layout?: (props: { children?: RenderableChild; }) => RenderableChild;

meta

meta?: RouteMetaSource;

HistoryScrollBehaviortype

HistoryScrollBehavior: 'restore' | 'top' | 'preserve'

Scroll behavior for browser back/forward (popstate) navigations.

indextype

index: (Component: RouteComponent, options?: RouteOptions) => void

Declare the index route for the enclosing `page()` scope.

isDeferredtype

isDeferred: <T = unknown>(value: unknown) => value is Deferred<T>

Check whether `value` is a {@link Deferred} produced by {@link defer}.

LayoutScopeRecordtype

LayoutScopeRecord: any

Resolved layout component as stored in a route record's layout chain.

component

component: (props: { children?: RenderableChild; }) => RenderableChild;

lazytype

lazy: <TComponent extends AnyRouteComponent>(factory: () => Promise<{ default: TComponent; } | TComponent>) => LazyRouteComponent<TComponent>

Wrap a dynamic-import factory as a {@link LazyRouteComponent}, loaded on first use.

LazyRouteComponenttype

LazyRouteComponent: TComponent & {
  preload(): Promise<void>;
}

A route component loaded on demand via {@link lazy}, with an explicit `preload()`.

lazyRouteDatatype

lazyRouteData: <TModule, TData = TModule>(factory: () => PromiseLike<TModule>, select?: (module: TModule, context: RouteContext & { request?: Request; }) => TData | PromiseLike<TData>) => LazyRouteDataLoader<TModule, TData>

Create a cached route loader backed by a dynamic import. The module is only requested when the owning route matches, unless preload() is called.

LazyRouteDataLoadertype

LazyRouteDataLoader: ((context: RouteContext & {
  request?: Request;
}) => Promise<TData>) & {
  preload(): Promise<void>;
}

A route data loader loaded on demand via {@link lazyRouteData}, with an explicit `preload()`.

Linktype

Link: ({ href: suppliedHref, to, class: className, children, rel, target, "aria-current": ariaCurrent, "aria-label": ariaLabel, onPress, onClick, ...rest }: LinkProps) => JSXElement

Link component that prevents default navigation and uses navigate() Provides declarative way to navigate between routes Accessibility features: - Proper semantic <a> element (not a button) - Supports aria-current for indicating active page - Supports aria-label for descriptive labels - Keyboard accessible (Enter key handled by native <a> element) Respects native browser behaviors: - Middle-click (opens in new tab) - Ctrl/Cmd+click (opens in new tab) - Shift+click (opens in new window) - Alt+click (downloads link) - Right-click context menu Best practices: - Use target="_blank" with rel="noopener noreferrer" for external links - Use aria-current="page" for the current page in navigation - Provide descriptive link text or aria-label - For a styled link with automatic active-route state, install `@askrjs/themes` and use `NavLink` from `@askrjs/themes/components` Uses applyInteractionPolicy to enforce pit-of-success principles: - Interaction behavior centralized in foundations - Keyboard handling automatic - Composable via mergeProps

LinkPropstype

LinkProps: LinkBaseProps & ({
  href: string;
  to?: never;
} | {
  href?: never;
  to: RouteDestination;
})

Props for {@link Link}: either a raw `href` or a typed route `to` destination.

aria-current

Optional aria-current attribute for indicating current page/location. Use "page" for the current page in navigation.

aria-label

Optional aria-label for accessibility when link text isn't descriptive enough.

children

children?: RenderableChild;

class

class?: string | undefined;

href

href?: string | undefined;

onClick

onClick?: ((event: MouseEvent) => void) | undefined;

onPress

onPress?: ((event: Event) => void) | undefined;

rel

Optional rel attribute for link relationships. Common values: "noopener", "noreferrer", "nofollow"

target

Optional target attribute. Use "_blank" for new tab/window.

to

to?: RouteDestination | undefined;

navigatetype

navigate: (path: string, options?: NavigateOptions) => void

Navigate the client-side router to `path` using the History API.

NavigateOptionstype

NavigateOptions: {
  history?: 'push' | 'replace';
  replace?: boolean;
  scroll?: NavigationScrollBehavior;
}

Options for {@link navigate}.

NavigationScrollBehaviortype

NavigationScrollBehavior: 'top' | 'preserve'

Scroll behavior for programmatic navigations (`navigate()`).

notFoundtype

notFound: () => AccessDenyDecision

Policy decision: deny with 404 Not Found.

onRouteChangetype

onRouteChange: (fn: (current: RouteSnapshot, previous: RouteSnapshot | null) => RouteChangeCleanup, options?: RouteChangeOptions) => void

Register a callback to run whenever the active route changes, with optional cleanup.

Outlettype

Outlet: () => JSXElement

Renders the nested route content for the enclosing layout or page scope.

pagetype

page: { <const TPath extends string>(path: TPath, Component: RouteComponent<RoutePathParams<TPath>>, fn: RouteDefinition): void; <const TPath extends string, TComponent extends AnyRouteComponent>(path: TPath, Component: CompatibleRouteComponent<TPath, TComponent>, fn: RouteDefinition): void; <const TPath extends string>(path: TPath, Component: RouteComponent<RoutePathParams<TPath>>, options: PageHelperOptions, fn: RouteDefinition): void; <const TPath extends string, TComponent extends AnyRouteComponent>(path: TPath, Component: CompatibleRouteComponent<TPath, TComponent>, options: PageHelperOptions, fn: RouteDefinition): void; }

Declare a route page at `path`, nesting a sub-scope for `index`/`page`/`fallback` declarations and options like `preload`/`meta`/`auth`.

PageHelperOptionstype

PageHelperOptions: any

Options accepted by the `page()` route-declaration helper.

preload

preload?: (context: RouteContext & { request?: Request; data: QueryPrefetchContext; }) => unknown;

meta

meta?: RouteMetaSource;

PageScopeRecordtype

PageScopeRecord: any

Resolved page host component as stored in a route record's page chain.

component

component: RouteComponent;

ParsedSegmenttype

ParsedSegment: any

A single parsed segment from a route path. - `static`: a literal path segment, e.g. `"users"` in `/users/{id}` - `param`: a `{name}` capture group — `value` holds the param name - `wildcard`: a bare `*` segment that captures exactly one segment - `splat`: a `{*name}` capture group that captures the remaining path - `catchall`: the `/*` catch-all that matches any depth

kind

kind: 'static' | 'param' | 'wildcard' | 'splat' | 'catchall';

value

For static/wildcard/catchall: the literal text; for param: the param name.

reconcileRouteMetatype

reconcileRouteMeta: (meta: Readonly<RouteMeta>, target?: Document) => void

Replace only Askr-owned head nodes after a successful client navigation.

redirecttype

redirect: (to: string, init?: { status?: AccessRedirectStatus; replace?: boolean; }) => AccessRedirectDecision

Policy decision: redirect the visitor to `to`.

Resolvetype

Resolve: <T>(props: ResolveProps<T>) => JSXElement

Render a {@link Deferred} value's fulfilled state, a pending placeholder, or a rejected fallback.

resolveDeferredValuestype

resolveDeferredValues: <T>(input: T, signal?: AbortSignal) => Promise<T>

Recursively await any {@link Deferred} values nested within `input`, returning it once fully resolved.

ResolvePropstype

ResolveProps: any

Props for {@link Resolve}.

children

children: (value: T) => RenderableChild;

pending

pending?: RenderableChild;

rejected

rejected?: RenderableChild | ((error: unknown) => RenderableChild);

value

value: Deferred<T>;

resolveRouteMetatype

resolveRouteMeta: (record: RouteRecord, context: RouteContext) => Promise<Readonly<RouteMeta>>

Resolve a route's merged {@link RouteMeta} by running its metadata chain against `context`.

resolveRouteRequesttype

resolveRouteRequest: (target: string, options: RouteRequestOptions) => RouteRequestResult | Promise<RouteRequestResult>

Resolve `target` against a route registry, applying auth/policies to produce a render/redirect/deny result.

routetype

route: { <const TPath extends string, const TSearchSchema extends ObjectSchema<RouteSearch> | undefined = undefined, TLoaderData = unknown, TDehydratedData = TLoaderData>(path: TPath, Component: RouteComponent<RoutePathParams<TPath>>, options?: RouteOptions<RoutePathParams<TPath>, TSearchSchema, TLoaderData, TDehydratedData>): RouteRef<RoutePathParams<TPath>, RouteRefSearch<TSearchSchema>>; <const TPath extends string, TComponent extends AnyRouteComponent, const TSearchSchema extends ObjectSchema<RouteSearch> | undefined = undefined, TLoaderData = unknown, TDehydratedData = TLoaderData>(path: TPath, Component: CompatibleRouteComponent<TPath, TComponent>, options?: RouteOptionsForComponent<TPath, TComponent, TSearchSchema, TLoaderData, TDehydratedData>): RouteRef<RoutePathParams<TPath>, RouteRefSearch<TSearchSchema>>; }

Declare a route at `path` rendering `Component`, returning a typed {@link RouteRef} for building destinations.

Routetype

Route: any

A single path-to-handler binding as seen by low-level navigation code.

path

path: string;

handler

handler: RouteHandler<TParams>;

namespace

namespace?: string;

RouteAuthOptionstype

RouteAuthOptions: any

Auth configuration shared across a route registry or a single route.

resolve

resolve: RouteAuthResolver;

loginPath

loginPath?: string | ((context: RouteContext) => string | PromiseLike<string>);

authenticatedRedirectTo

authenticatedRedirectTo?: string | ((context: RouteContext) => string | PromiseLike<string>);

RouteAuthResolvertype

RouteAuthResolver: (context: Omit<RouteContext, 'auth'>) => AuthContext | PromiseLike<AuthContext>

Resolves the {@link AuthContext} for a route request.

RouteChangeCleanuptype

RouteChangeCleanup: void | (() => void)

Optional cleanup returned by an {@link onRouteChange} callback, run before the next change.

RouteChangeOptionstype

RouteChangeOptions: any

Options for {@link onRouteChange}.

immediate

immediate?: boolean;

RouteComponenttype

RouteComponent: (props: TParams) => RenderableChild

A route page component: a regular component that receives route params as props derived from the URL pattern. Components may accept no params at all — zero-argument components are still assignable.

RouteContexttype

RouteContext: any

Context passed to route policies, auth resolvers, and loaders.

mode

mode: RouteMode;

params

params: TParams;

pathname

pathname: string;

search

search: string;

hash

hash: string;

href

href: string;

auth

auth: AuthContext;

signal

signal: AbortSignal;

routeDatatype

routeData: <T>() => T

Read the current route's server loader data during render or hydration.

RouteDataLoadErrortype

RouteDataLoadError: typeof RouteDataLoadError

Thrown when a route's `loader` rejects; wraps the original `cause`.

route

readonly route: string;

phase

readonly phase: RouteDataLoadPhase;

cause

readonly cause: unknown;

RouteDataLoadPhasetype

RouteDataLoadPhase: 'client' | 'server' | 'ssg'

Which environment a route's data loader ran (or failed) in.

RouteDefinitiontype

RouteDefinition: () => void

A callback that declares routes via `route()`/`page()`/`group()`, passed to {@link createRouteRegistry }.

RouteDestinationtype

RouteDestination: any

A resolved navigation target with a computed `href`, produced by {@link to }.

href

readonly href: string;

RouteHandlertype

RouteHandler: any

A function rendering a matched route's page content, with layouts already composed.

RouteManifesttype

RouteManifest: any

The normalized route manifest produced by registered route definitions. declarations. Pass it to `createSPA`, `hydrateSPA`, or `renderToString` instead of assembling plain `Route[]` arrays. ```ts import { createRouteRegistry } from '@askrjs/askr/router'; const registry = createRouteRegistry(() => { ... }); await createSPA({ root: '#app', registry }); ```

records

records: RouteRecord[];

auth

auth?: RouteAuthOptions;

basePath

Normalized public pathname prefix. Empty and root mounts omit it.

RouteMatchtype

RouteMatch: any

A single matched route, as reported by {@link currentRoute } and activity predicates.

path

path: string;

params

params: Readonly<TParams>;

name

name?: string;

namespace

namespace?: string;

RouteMetatype

RouteMeta: any

title

title?: string;

description

description?: string;

canonical

canonical?: string;

robots

robots?: string;

openGraph

openGraph?: Record<string, string>;

links

links?: readonly { rel: string; href: string; [key: string]: string; }[];

jsonLd

jsonLd?: unknown | readonly unknown[];

html

html?: { lang?: string; dir?: 'ltr' | 'rtl' | 'auto'; };

RouteMetaSourcetype

RouteMetaSource: RouteMeta | ((context: RouteContext<TParams>) => RouteMeta | PromiseLike<RouteMeta>)

A route's metadata, or a function computing it from the resolved context.

RouteModetype

RouteMode: 'spa' | 'ssr' | 'ssg'

The rendering mode a route is currently being evaluated under.

RouteOptionstype

RouteOptions: any

Options for `route()` declarations. - `loader`: server data loader called before render, result passed as SSR data - `entries`: SSG entry generator — returns one param map per static page - `title`: page title hint used by SSG and document-meta integrations - `namespace`: MFE namespace key for grouped route management

loader

loader?: (context: RouteContext<TParams> & { request?: Request; }) => TLoaderData | PromiseLike<TLoaderData>;

dehydrate

Select the loader data transported to the browser for initial hydration. Server rendering still receives the complete loader value. The selector must be synchronous; client navigations rerun the loader and receive its complete result.

preload

preload?: (context: RouteContext<TParams> & { request?: Request; data: QueryPrefetchContext; }) => unknown;

entries

entries?: () => Array<TParams> | Promise<Array<TParams>>;

invalidationKeys

Optional invalidation keys used by incremental SSG generation.

title

title?: string;

namespace

namespace?: string;

search

search?: TSearchSchema;

meta

meta?: RouteMetaSource<TParams>;

actions

actions?: readonly ActionDescriptor[];

RouteParamstype

RouteParams: Record<string, string>

Path parameters captured for a matched route, keyed by parameter name.

RoutePathParamstype

RoutePathParams: [ExtractRoutePathParamNames<Path>] extends [never] ? Record<never, string> : { [Key in ExtractRoutePathParamNames<Path>]: string; }

Statically infers the param record shape from a route path string literal, e.g. `/posts/{id}`.

RoutePolicytype

RoutePolicy: (context: RouteContext) => AccessDecision | PromiseLike<AccessDecision>

A route access-control check, evaluated against {@link RouteContext} to produce an {@link AccessDecision}.

RouteQuerytype

RouteQuery: any

Read-only accessor for the current route's query-string parameters.

get

get(key: string): string | null;

getAll

getAll(key: string): string[];

has

has(key: string): boolean;

toJSON

toJSON(): Record<string, string | string[]>;

RouteQueryParamInputtype

RouteQueryParamInput: RouteQueryParamValue | readonly RouteQueryParamValue[]

A query-string value, or an array of them for a repeated param.

RouteQueryParamValuetype

RouteQueryParamValue: string | number | boolean | null | undefined

A single query-string value accepted by {@link updateRouteQuery}.

RouteQueryUpdatertype

RouteQueryUpdater: (searchParams: URLSearchParams) => void

A function that mutates a `URLSearchParams` directly, for {@link updateRouteQuery}.

RouteQueryUpdatestype

RouteQueryUpdates: Record<string, RouteQueryParamInput>

A map of query param updates for {@link updateRouteQuery}; `null`/`undefined` removes the key.

RouteRecordtype

RouteRecord: any

A fully normalized route record produced by `route(path, Component, options?)`. This is the canonical representation shared by: - SPA matching and navigation - SSR request resolution - SSG manifest expansion

path

Canonical normalized absolute path, e.g. `/posts/{slug}`

component

The page component to render when this route is active

segments

Pre-parsed segment list for fast matching and typed param extraction

rank

Pre-computed specificity rank (higher = more specific)

layoutChain

Layout chain from outermost to innermost, applied automatically on render

pageChain

Page chain from outermost to innermost, composed through Outlet before layouts apply

options

Route metadata: loader, entries, policies, title, namespace

metaChain

Metadata sources ordered from outermost group/page to the route leaf.

isFallback

True when this is the `/*` catch-all fallback route

handler

Runtime-ready handler with layout composition baked in. Compatible with the low-level `RouteHandler` signature so that navigation and SSR rendering do not need to know about layout chains.

RouteReftype

RouteRef: any

Stable, typed reference to a route returned by `route()`, used to build destinations.

path

readonly path: string;

searchSchema

readonly searchSchema?: ObjectSchema<TSearch & RouteSearch>;

basePath

readonly basePath?: string;

__params

readonly __params?: TParams;

__search

readonly __search?: TSearch;

RouteRegistrytype

RouteRegistry: any

Opaque handle produced by {@link createRouteRegistry }, required by `createSPA`/`hydrateSPA`.

manifest

manifest: RouteManifest;

routes

routes: readonly Route[];

RouteRegistryOptionstype

RouteRegistryOptions: any

Options for {@link createRouteRegistry }.

auth

auth?: RouteAuthOptions;

basePath

Public pathname prefix for applications mounted below the origin root.

RouteRenderResulttype

RouteRenderResult: any

A resolved route request that should render `handler` with `params`.

kind

kind: 'render';

handler

handler: RouteHandler<TParams>;

params

params: TParams;

record

record?: RouteRecord;

RouteRequestOptionstype

RouteRequestOptions: any

Options for resolving a route request (used internally by `createSPA`/`hydrateSPA`/SSR).

registry

Explicit route source shared by the application renderers.

mode

mode?: RouteMode;

load

load?: boolean;

auth

auth?: RouteAuthOptions;

authContext

authContext?: AuthContext;

signal

signal?: AbortSignal;

request

request?: Request;

telemetry

telemetry?: CoreTelemetry;

RouteRequestResulttype

RouteRequestResult: RouteRenderResult<TParams> | AccessRedirectDecision | AccessDenyDecision | null

Outcome of resolving a route request: render, redirect, deny, or no match.

RouteSearchtype

RouteSearch: Record<string, RouteSearchValue>

A route's query-string parameters, keyed by name.

RouteSearchValuetype

RouteSearchValue: string | number | boolean | null | undefined | readonly (string | number | boolean | null)[]

A stable, typed reference returned by route() for destination construction.

RouteSnapshottype

RouteSnapshot: any

Full description of the currently active route, returned by {@link currentRoute }.

path

path: string;

params

params: Readonly<TParams>;

query

query: Readonly<RouteQuery>;

hash

hash: string | null;

name

name?: string;

namespace

namespace?: string;

matches

matches: readonly RouteMatch<TParams>[];

ScrollRestorationOptionstype

ScrollRestorationOptions: {
  navigation?: NavigationScrollBehavior;
  history?: HistoryScrollBehavior;
}

Options for {@link configureScrollRestoration }.

serializeRouteMetatype

serializeRouteMeta: (meta: RouteMeta) => string

Render a {@link RouteMeta} to the `<title>`/`<meta>`/`<link>`/JSON-LD markup for the document `<head>`.

totype

to$1: <TParams extends RouteParams, TSearch extends RouteSearch = RouteSearch>(route: RouteRef<TParams, TSearch>, params: TParams, search?: TSearch) => RouteDestination

Build a {@link RouteDestination} (with a computed `href`) for a {@link RouteRef} and params/search.

unauthorizedtype

unauthorized: () => AccessDenyDecision

Policy decision: deny with 401 Unauthorized.

updateRouteQuerytype

updateRouteQuery: (updates: RouteQueryUpdates | RouteQueryUpdater, options?: UpdateRouteQueryOptions) => void

UpdateRouteQueryOptionstype

UpdateRouteQueryOptions: {
  /**
   * Defaults to replace so high-frequency controls such as search inputs do not
   * create one browser-history entry per character.
   */
  history?: 'push' | 'replace';
  replace?: boolean;
}

Options for {@link updateRouteQuery}.