@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.

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.

createSessionAuthtype

createSessionAuth: (options?: SessionAuthOptions) => SessionAuth

Bind server provider sessions to router auth in SSR and the browser.

currentAuthtype

currentAuth: () => AuthContext$1

Return the identity resolved for the route currently being rendered.

currentRoutetype

currentRoute: <TParams extends RouteParams = RouteParams, TState = unknown, TAppMeta = unknown>() => RouteSnapshot<TParams, TState, TAppMeta>

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;

appMeta

appMeta?: TAppMeta;

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}.

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;

matchRoutetype

matchRoute: <TAppMeta = unknown>(pathname: string, options: { registry: RouteRegistry; }) => RouteMatch<RouteParams, TAppMeta> | null

Match a path against a route registry without resolving route policies or loading data.

navigatetype

navigate: (target: string | RouteDestination, options?: NavigateOptions) => void

Navigate the client-side router using the History API. A string is a logical path: a root-relative path gains the registry basePath. A typed destination from to() already carries its public href. A target on another origin is handed to the browser.

NavigateOptionstype

NavigateOptions: {
  history?: 'push' | 'replace';
  replace?: boolean;
  scroll?: NavigationScrollBehavior;
  /** Entry-local browser history state. It is not serialized into the URL or sent to the server. */
  state?: unknown;
}

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;

appMeta

appMeta?: TAppMeta;

reconcileRouteMetatype

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

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

redirecttype

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

Policy decision: redirect the visitor to to. A string is a logical path that gains the registry basePath; a to() destination is used as-is.

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 the identity for a request. When omitted, requests are anonymous unless the caller supplies an identity (for example `authContext` on the server, or an opted-in hydration snapshot for the initial client route).

dehydrate

Opt in to sending a minimal identity snapshot to the browser for hydration. Called on the server with the identity that authorized the page. `authenticated`, `principal`, `tenant`, and `scopes` of the result are serialized verbatim into the page, so return only what the client needs; the session is never sent. The client uses the snapshot to resolve the initial route and, without `resolve`, as its identity for navigations. Nothing crosses without this hook.

loginPath

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

authenticatedRedirectTo

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

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

Rejection of a lazyRouteData() loader whose import or select failed; 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 typed navigation target with a computed public href, produced by {@link to }. Branded so that only to() creates one: its href already includes the registry basePath and is never prefixed again.

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;

appMeta

readonly appMeta?: TAppMeta;

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>;

appMeta

Immutable application declaration data; never automatically serialized for hydration.

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;

hasState

Whether the current browser history entry was given explicit location state.

state

Entry-local state supplied to navigate(); absent during SSR and when no state was supplied.

name

name?: string;

namespace

namespace?: string;

matches

matches: readonly RouteMatch<TParams, TAppMeta>[];

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>.

SessionAuthtype

SessionAuth: any

Pass this exact object as the registry or boot auth configuration.

resolve

Resolve the identity for a request. When omitted, requests are anonymous unless the caller supplies an identity (for example `authContext` on the server, or an opted-in hydration snapshot for the initial client route).

dehydrate

Opt in to sending a minimal identity snapshot to the browser for hydration. Called on the server with the identity that authorized the page. `authenticated`, `principal`, `tenant`, and `scopes` of the result are serialized verbatim into the page, so return only what the client needs; the session is never sent. The client uses the snapshot to resolve the initial route and, without `resolve`, as its identity for navigations. Nothing crosses without this hook.

loginHref

loginHref(provider: string, options: SessionLoginOptions): string;

logout

Local logout; provider logout/revocation remains an explicit server action.

handleAuthFailure

Handle a decoded 401 problem or an

SessionAuthOptionstype

SessionAuthOptions: any

Client binding for the same-origin askr-server provider-session routes.

loginPath

App-owned login page, default `/login`.

fetch

Native transport for session resolution and logout.

SessionLoginOptionstype

SessionLoginOptions: any

returnTo

readonly returnTo: string;

resource

readonly resource?: string;

scopes

readonly scopes?: readonly string[];

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}.