## API

### navaid(base, on404)

Returns: `Navaid`

#### base
Type: `String`

Default: `'/'`

The base pathname for your application. By default, Navaid assumes it's operating on the root.

All routes will be processed _relative to_ this path (see [`on()`](#onpattern-handler)). Similarly, while [`listen`](#listen)ing, Navaid **will not** intercept any links that don't lead with this `base` pathname.

> **Note:** Navaid will accept a `base` with or without a leading and/or trailing slash, as all cases are handled identically.

#### on404
Type: `Function`

Default: `undefined`

The function to run if the incoming pathname did not match any of your defined defined patterns.

When defined, this function will receive the formatted `uri` as its only parameter; see [`format()`](#formaturi).

> **Important:** Navaid ***only*** processes routes that match your `base` path!

Put differently, `on404` will never run for URLs that do not begin with `base`.

This allows you to mount _multiple_ Navaid instances on the same page, each with different `base` paths. :wink:

### format(uri)
Returns: `String` or `false`

Formats and returns a pathname relative to the [`base`](#base) path.

If the `uri` **does not** begin with the `base`, then `false` will be returned instead.

Otherwise, the return value will always lead with a slash (`/`).

> **Note:** This is called automatically within the [`listen()`](#listen) and [`run()`](#runuri) methods.

#### uri
Type: `String`

The path to format.

> **Note:** Much like [`base`](#base), paths with or without leading and trailing slashes are handled identically.

### route(uri, replace)
Returns: `undefined`

Programmatically route to a path whilst modifying & using the `history` events.

#### uri
Type: `String`

The desired path to navigate.

> **Important:** Navaid will prefix your `uri` with the [`base`](#base), if/when defined.

#### replace
Type: `Boolean`

Default: `false`

If `true`, then [`history.replaceState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#The_replaceState()_method) will be used. Otherwise [`history.pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Adding_and_modifying_history_entries) will be used.

This is generally used for redirects; for example, redirecting a user away from a login page if they're already logged in.

### on(pattern, handler)
Returns: `Navaid`

Define a function `handler` to run when a route matches the given `pattern` string.

#### pattern
Type: `String`

The supported pattern types are:

* static (`/users`)
* named parameters (`/users/:id`)
* nested parameters (`/users/:id/books/:title`)
* optional parameters (`/users/:id?/books/:title?`)
* any match / wildcards (`/users/*`)

> **Note:** It does not matter if your pattern begins with a `/` — it will be added if missing.

#### handler
Type: `Function`

The function to run when its `pattern` is matched.

> **Note:** This can also be a `Promise` or `async` function, but it's up to you to handle its result/error.

For `pattern`s with named parameters and/or wildcards, the `handler` will receive an "params" object containing the parsed values.

When wildcards are used, the "params" object will fill a `wild` key with the URL segment(s) that match from that point & onward.

```js
let r = new Navaid();

r.on('/users/:id', console.log).run('/users/lukeed');
//=> { id: 'lukeed' }

r.on('/users/:id/books/:title?', console.log).run('/users/lukeed/books/narnia');
//=> { id: 'lukeed', title: 'narnia' }

r.on('/users/:id/jobs/*').run('/users/lukeed/jobs/foo/bar/baz/bat');
//=> { id: 'lukeed', wild: 'foo/bar/baz/bat' }
```

### run(uri)
Returns: `Navaid`

Executes the matching handler for the specified path.

Unlike `route()`, this does not pass through the `history` state nor emit any events.

> **Note:** You'll generally want to use `listen()` instead, but `run()` may be useful in Node.js/SSR contexts.

#### uri
Type: `String`

Default: `location.pathname`

The pathname to process. Its matching `handler` (as defined by [`on()`](#onpattern-handler)) will be executed.

### listen(uri?)
Returns: `Navaid`

Attaches global listeners to synchronize your router with URL changes, which allows Navaid to respond consistently to your browser's BACK and FORWARD buttons.

These are the (global) events that Navaid creates and/or responds to:

* popstate
* replacestate
* pushstate