API

addRoute()

Registers a route into the RouteStore.

/**
 * addRoute(fromPattern: string, toPattern: string, transition: string): void
 */
taxi.addRoute('/blog/.*', '/', 'blogToHome')

Perform a manual navigation to the provided URL.

If a transition name is not provided then Taxi will try and find a match in the RouteStore, otherwise the default transition will be used.

/**
 * navigateTo(url: string, transition?: string = false): Promise
 */
taxi.navigateTo('/contact')

taxi.navigateTo('/contact', 'explcitTransition').then(() => { ... })

Navigate back in the browser history. Respects the allowInterruption setting — if a transition is in progress and allowInterruption is false, the call is ignored with a console warning.

/**
 * navigateBack(): void
 */
taxi.navigateBack()

Navigate forward in the browser history. Respects the allowInterruption setting.

/**
 * navigateForward(): void
 */
taxi.navigateForward()

preload()

Prefetch the provided URL and add it to the cache ahead of any user navigation.

Returns a Promise that resolves to the CacheEntry so you can inspect the preloaded data.

/**
 * preload(url: string, preloadAssets?: boolean = false): Promise<CacheEntry>
 */
taxi.preload('/path/to/preload')

You can pass a second argument to indicate you want to preload the assets on the target URL as well (images, media, etc):

taxi.preload('/path/to/preload', true)

As preload returns a Promise that resolves to the CacheEntry, you can inspect the preloaded page or handle failures:

taxi.preload('/path/to/page')
    .then((entry) => console.log('preloaded:', entry.title))
    .catch(err => {
        // Rejects on non-2xx responses (e.g. 404 with no error page),
        // network errors, or if the fetched page has no [data-taxi-view].
        console.warn('preload failed', err)
    })

currentCacheEntry

A read-only property that returns the CacheEntry for the currently active page.

console.log(taxi.currentCacheEntry.title)     // page <title>
console.log(taxi.currentCacheEntry.finalUrl)  // resolved URL after redirects
console.log(taxi.currentCacheEntry.renderer)  // active Renderer instance

This is updated at the end of every navigation (after NAVIGATE_END fires). On first load it reflects the initial page.

updateCache()

Updates the cached HTML for the provided URL. If no URL is provided, update cache for the current URL.

Useful when adding/removing content via AJAX such as a search page or infinite scroll.

When updating the current page, the active Renderer instance is kept (so any state you set up in onEnter is still there when onLeave runs) and currentCacheEntry is updated to the new entry. If enablePrefetch is 'visible', any newly added links are also picked up.

/**
 * updateCache(url?: string): void
 */
taxi.updateCache()

clearCache()

Remove the cached HTML for the provided URL. If no URL is provided, remove cache for the current URL.

/**
 * clearCache(url?: string): void
 */
taxi.clearCache('/path/to/delete')

destroy()

Removes every event listener and observer Taxi has added, aborts any in-flight request, and clears the cache. The current page’s content is left as-is.

Useful for hot module reloading, tests, or when handing the page over to something else.

/**
 * destroy(): void
 */
taxi.destroy()

Listeners you added with taxi.on() are not removed, use taxi.off() for those.

setDefaultRenderer()

If you don’t like “default” as the name of your default renderer, you can change the default renderer to be anything you like here.

/**
 * setDefaultRenderer(renderer: string): void
 */
taxi.setDefaultRenderer('myRenderer')

setDefaultTransition()

Same as setDefaultRenderer, but for the transitions instead.

/**
 * setDefaultTransition(transition: string): void
 */
taxi.setDefaultTransition('myTransition')

Events

Events are handled by @unseenco/e.

Adding Listeners

import { Core } from '@unseenco/taxi'

const taxi = new Core({ ... })

// Sent before the current page's leave transition begins.
// Includes both the page being left (from) and the destination URL (to).
taxi.on('NAVIGATE_OUT', ({ from, to, trigger }) => {
  // from: the current CacheEntry
  // to:   a CacheEntry if the page was preloaded/cached; otherwise a stub with the
  //       same keys but null values (except finalUrl which holds the target URL string)
  // ...
})

// Sent once the new data-taxi-view has been added to the DOM
taxi.on('NAVIGATE_IN', ({ to, from, trigger }) => {
  // ...
})

// Sent after the enter transition has fully completed
taxi.on('NAVIGATE_END', ({ to, from, trigger }) => {
  // ...
})

If you use TypeScript, on() and off() only accept the three event names above, and the callback’s { from, to, trigger } payload is typed.

Removing Listeners

You can call taxi.off(event_name) to remove all listeners for an event, or pass the callback to remove just that listener instead:

function foo() {
	... 
}

taxi.on('NAVIGATE_OUT', foo)

// Remove just the foo listener
taxi.off('NAVIGATE_OUT', foo)

// Remove all listeners
taxi.off('NAVIGATE_IN')