Types

These types are all exported for use within TypeScript codebases.

The request object passed to your matcher functions if of type NaviRequest, and contains information about the last requested URL.

interface NaviRequest {
  /**
   * The path at which the matcher is mounted.
   */
  mountpath: string

  /**
   * The values of any URL parameters matched from parameter segments in the
   * URLs, pathname, along with information from the URL's query string.
   */
  params: { [name: string]: string }

  /**
   * An object containing the information from the URL's query string.
   */
  query: { [name: string]: string }

  /**
   * The raw URL query string, including any "?" character. E.g. "?q=test".
   */
  search: string

  /**
   * The URL hash string, including any "#" character. E.g. "#top".
   */
  hash: string

  /**
   * A HTTP method as an uppercase string. This defaults to "GET".
   */
  method: string

  /**
   * Contains the unmatched part of the request URL.
   */
  path: string

  /**
   * Contains the unmatched part of the request URL, as a string.
   * 
   * This is a string instead of a URLDescriptor, to be consistent
   * with the Request type for Express.
   */
  url: string

  /**
   * The originally requested URL.
   */
  originalUrl: string

  /**
   * The most recent routing context.
   */
  context: any

  /**
   * Contains the history state (from window.history.state) that was used
   * when processing this request in the browser.
   */
  state: any

  /**
   * When using the `crawl()` function, this will contain the function
   * that is used to map patterns within a `mount()` to more requests.
   */
  crawler?: Crawler

  body: any
  hostname: string
  headers: { [name: string]: string }
}

Route

Your app’s navigation state at any single time is represented by a Route object.

type RouteType =
  | 'busy'
  | 'ready'
  | 'error'
  | 'redirect'

interface Route<Data = any> {
  type: RouteType
  url: URLDescriptor
  chunks: Chunk[]
  lastChunk: Chunk
  
  /**
   * When "type" is "redirect", contains the redirected to URL.
   */
  to?: string

  /**
   * When "type" is "error", contains the error object.
   */
  error?: any

  /**
   * An object containing merged values from all data chunks.
   */
  data?: Data

  /**
   * An object contains HTTP headers added by header chunks. 
   */
  headers: { [name: string]: string }

  /**
   * An array containing information meant to be added to the page <head>.
   */
  heads: any[]

  /**
   * Any state from window.history.state that was used associated with the
   * route.
   */
  state?: any

  /**
   * A HTTP status code.
   */
  status?: number

  /**
   * The title that should be set on `document.title`.
   */
  title?: string

  /**
   * An array of components or elements for rendering the route's view.
   */
  views: any[]
}

Chunk

Within your Route object, state for each individual matcher is available through the route.chunks array. There are a number of possible chunk types.

/**
 * This is used in place of a chunk of another type whose final result is
 * not yet known.
 */
export interface BusyChunk extends GenericChunk {
  type: 'busy'
  promise: PromiseLike<any>
}

/**
 * A chunk that is added for each crawled pattern.
 */
export interface CrawlChunk extends GenericChunk {
  type: 'crawl'
}

/**
 * Data chunks contain information that will be available on the produced
 * route object, but isn't meant to be rendered with the page itself.
 */
export interface DataChunk<Data=any> extends GenericChunk {
  type: 'data'
  data: Data
}

/**
 * When encountered in a route by a `<NavView>`, this will be thrown, and
 * can then be handled by an Error Boundary. Behavior for handling error
 * chunks on the server side is undefined.
 */
export interface ErrorChunk extends GenericChunk {
  type: 'error'
  error: any
}

/**
 * Can be used to specify data for your page's <head> separately from
 * the view content.
 */
export interface HeadChunk extends GenericChunk {
  type: 'head'
  head: any
}

/**
 * Used to specify any headers for your HTTP response.
 */
export interface HeadersChunk extends GenericChunk {
  type: 'headers'
  headers: { [name: string]: string }
}

/**
 * Mount chunks are added for each mount that is routed through. They're
 * useful for building site maps, as they hold metadata on other possible
 * paths.
 */
export interface MountChunk extends GenericChunk {
  type: 'mount'
  patterns: string[]
}

/**
 * When added to a route, indicates that the client should follow the redirect
 * to the given address.
 */
export interface RedirectChunk extends GenericChunk {
  type: 'redirect'
  to: string
}

/**
 * Specifies that history.state for this request should be set to the given
 * value.
 */
export interface StateChunk extends GenericChunk {
  type: 'state'
  state: any
}

/**
 * Used to specify the status of your HTTP response.
 */
export interface StatusChunk extends GenericChunk {
  type: 'status'
  status: number
}

/**
 * Allows matchers to specify a <title> tag, or document title.
 */
export interface TitleChunk extends GenericChunk {
  type: 'title'
  title: string
}

/**
 * Contains the full URL that should be used for the route, including any hash.
 */
export interface URLChunk extends GenericChunk {
  type: 'url'
  url: URLDescriptor
}

/**
 * View chunks contain data that will be used in a response on the
 * server, or that will be rendered in the browser. They can contain error
 * or redirect information, but they'll still be rendered as-is in the client.
 */
export interface ViewChunk<View=any> extends GenericChunk {
  type: 'view'
  view: View
}

URLDescriptor

Most url objects within Navi are URL Descriptor objects, which have the following shape:

type URLDescriptor = {
  /**
   * The URL's pathname part, starting from the first `/`, and ending
   * before any search string.
   * 
   * E.g. `/documents/hidden/`
   */
  pathname: string,

  /**
   * The URL's query part, including any `?` character. When there
   * is no query, it defaults to an empty string.
   * 
   * E.g. `?q=pants`.
   */
  search: string,

  /**
   * The URL's hash part, including any `#` character. When there
   * is no hash, it defaults to an empty string.
   * 
   * E.g. `#top`.
   */
  hash: string,

  /**
   * An object containing string values of parameters extracted from
   * the `pathname` or `search` properties. 
   */
  query: Params,

  /**
   * The full string URL. If this URL Descriptor was created from a
   * string that you passed in, then this will match your provided
   * string.
   */
  href: string,
}

When you’re supplying a URL to Navi, you don’t need to supply the entire object. You can just supply a Partial URL Descriptor that contains only some of the above properties, and the remaining properties will be given sane defaults.

In fact, you don’t even need to supply objects at all — whenever you need to pass Navi a URL, you can also pass it a URL string, like /my-great-page?q=icecream#top, and Navi will convert it into a URL object for internal use.