API

Primary Operations

check(...identifiers)(...checks)

identifier: string, check: regex literal/object

Create a validation object to check one or more identifiers with one or more regular expressions (literal/object form). The returned object has keys that are identifiers and values are corresponding regex checks wrapped in an executable function.

let yearChk = check(':year')(/^201[0-7]$/) // 2010 - 2017
let typeColorChk = check(':type', ':color')(/.{3}/, /^[a-z]+$/) // at least 3 characters

spec(...pathKeys)(next, err?, fail?)

pathKey: string, next,err,fail: function

Create a spec over one or more path keys and actions.

// show vehicle "type" by "year" or "color"
let vehicleSpec = spec('/:type', '/:type/:year', '/:type/:color')(next, err, fail)

match(specs, checks?, matchCheck?)

specs: object or [object], checks: object, matchCheck: function

Create a matcher object from one or more specs. Pass checks object to validate identifiers. Pass matchCheck function to modify current route path before specs are executed.

let vehicleMatcher = match(vehicleSpec, {...yearChk, ...typeColorChk})

container(matchers, mismatchers?, instance?, scheduleDispatch?)

matchers, mismatchers: object or [object], instance: object, scheduleDispatch: boolean

Create an ultra instance that runs provided matchers for the current url and registers a listener to handle pushstate routing. Pass ultra instance to update that instance with new matchers. scheduleDispatch controls if current url should be dispatched. scheduleDispatch is true by default if an instance is not provided or if the provided instance has not dispatched yet. Override the default value by providing true/false.

let ultra = container(vehicleMatcher)

/*** example run ***/
/*

next: called on exact match for sample routes
  /automobile or /motorcycle
  /automobile/red or /automobile/2017
  /motorcycle/blue or /motorcycle/2017

err: called on partial match
  /automobile/2020 or /motorcycle/z

fail: called after matching is complete and spec did not match
  /z

*/

---

Other Operations

prefixMatch(prefixKey, matcher, prematchCheck?)

prefixKey: string, matcher: object, prematchCheck: function

Create a prefixed matcher. prefixKey can contain literals and identifiers. matcher is invoked only if prefixKey matches the path (exactly or partially). Pass prematchCheck function to modify current route path before matcher is executed.

toggle(matcher, newKey?, replacement?)

newKey: string, matcher, replacement: object

Dectivate/reactivate a matcher. Use newKey to identify the matcher later. Replace original matcher with replacement matcher.

toggleSelected(matchers, key, replacements?)

matchers: [object], key: string, replacements: object or [object]

Toggle multiple matchers identified by key. Provide replacements to sequentially replace identified matchers.

miss(next, ...pathKeys)

next: function, pathKey: string

Create a missMatcher to invoke next if none of the provided pathKeys matched.

---

Helpers

assignValues(pathKey, values = [])

pathKey: string, values: [string]

Create an object by extracting identifiers from pathKey and assigning values sequentially.

parseQS(qs, ids, options?)

qs: string, ids: [string], options: { delim = ',', defaults = [], decodeValues = false }

Extract values for provided ids from qs (query string). Provide defaults for given ids in options object. Transform values with decodeURIComponent by providing decodeValues=true. Multiples values of the same id are delimited with ,. Use delim option to override default character.

prependPath(values, path)

values: [string], path: string

Create a joined path by appending list of values to path.

appendPath(values, path)

values: [string], path: string

Create a joined path by prepending list of values to path.

scheduleTask(cb, wait = false, ms = 0)

cb: function, wait: boolean, ms: number

Create a timer object to schedule a task (cb) to run after a certain period (ms) of time. Prevent auto schedule with wait=true.

Returned timer object provides run and stop methods. To schedule task manually call run() on the timer object. To stop a scheduled timer call stop() on the timer object. Use active property of the timer object to check if the timer is running.

---

DOM Helpers

a.link(props)

props = { createElement, getUltra, href, style?, state?, docTitle?, retain?, ...others }

Create anchor (a) element or a representation of it (vdom) by calling createElement with transformed props.

createElement: function - callback function that receives string "a" as first argument followed by props object.

getUltra: function - return ultra instance used to perform navigation (when anchor element is clicked).

href: string - provide href attribute's value for the anchor tag and use it as the last argument tohistory.pushstate.

state: object - first argument to history.pushstate.

docTitle: string - second argument (title) to history.pushstate.

style: object - inline style attribute's value as JavaScript object

retain: string - meta prop to identify the data to retain. Use combination of: qs, hash, and history (e.g. retain: 'qs history')

• qs: retain query string from current url
• hash: retain hash fragment from current url
• history: retain history by using replaceState instead of pushState

other: object - these key/value pairs will be passed as-is (e.g. { title: 'see product details', children: <value> }).

Transformed props object passed to createElement contains href, style, and onClick as well as other attributes provided in the original props parameter. Configuration props - createElement, getUltra, state, docTitle, retain - are filtered out and won't be passed to createElement.

onClick is a click event handler function that performs navigation when the element is clicked.

Default values {touchAction: 'manipulation', msTouchAction: 'manipulation'} are applied to style. Override the defaults by setting them to empty string explicitly (e.g. style: { touchAction: '', msTouchAction: '' }).

a.link is a mixin for your DOM library's element factory function (e.g. React.createElement).

---