gt3 / ultra-router

Router for component-based web apps. Pair with React or <BYOF />.

npm i ultra

Add pushstate navigation to your component-based web app. Integrate seamlessly with React, Preact, and Vue.

download	dependencies
4.6 kb	none

Benefits

• Embrace component paradigm, stay framework agnostic
  • Use conventions to map url string to component (sub)trees
  • Independent of rendering or view layer
    • Routing should be immune to complexity introduced by framework-level abstractions (context in React for e.g.)
• Co-locate routes to support scalability
  • Routes are data. Similar types of information are best understood if they exist in the same space.
  • On the other end, as relationships between components get more complex, it is best to leave route matching logic out of the mix.
• Extensible
  • Composable API provides clear separation between route configuration and runtime to avail maximum reuse and target different environments
• Compact
  • Ideal for mobile/progressive web apps
    • No runtime dependencies
    • 4.6 kb > ultra (> preact)
    • Code splitting friendly

Trade-offs

• For modern browsers with pushstate support
• Does not render component or fetch data
• Relies on use of path keys (strings) to derive result
  • More complex update process involves replacing path keys throughout the app
  • Path keys (non-minified) may contribute to bloated bundles
    • Concern for apps with multiple deeply nested routes, e.g. Amazon
• For the Developer: Overcome the notion of changing your routing code again this season, and actually following through. No pun intended.

Resources

• Quick start (build navigation for a news website tutorial)
• React bindings: react-ultra
• Code examples in /examples directory
  • Vehicle shop: jsfiddle
  • Tap (intercept routing): jsfiddle
  • Loading modules and routes dynamically

To-dos

• Create automated cross-browser test suite
• Add Preact and Vue.js examples
• Implement Node.js container for ultra-router

License

MIT

---

Handle a route or two without breaking a sweat. ⚔️ ULTRA

ultra-router's Issues

remove trailing slash before executing match

/a/999
/a/999/

should produce identical match result

add support to handle spec rejections

spec reject

• gets called after something resolved (exact or partial)
• spec that was resolved obviously should not be rejected
• unless the resolving handler returns false => skip rejection processing completely

spec function should accept (next, err, fail)
container should run reject only after matchers are matched/resolved

container dispatch should return on first true result

use actions.some

connect push/replace to popstate

• dipatch custom event in push, replace
• generate a proxy listener that listens on custom event, fires actual popstate handlers

remove defaultProps from Link

use defaultStyle variable, overridable by style prop

add mismatch support

miss(action, '/x', '/x/xx')

pass mismatchers to container, execute after rejects

pull out history from router, move to new Container class

catch exceptions in decoding

decodeURIComponent('%') //URIError: URI malformed
use try catch:

make matchers accept loc object

• matchers should accept loc object { pathname, ?ultra }
• convert string location to object in container

add redirect method on ultra that calls replace on next tick

add pause feature to override transitions, save visited

• record and save route id to history state
• check if route has been visited to navigate back or forward

confirm(ok, cancel, msg) {
  return window.confirm('Are you sure you want to navigate away?') ? ok() : cancel()
}
render() {
  ultra.pause(this.confirm)
  return <>
}

optimize for fast tap

default style if tag == 'a' and no style prop provided
use: {cursor: 'pointer', touchAction: 'manipulation', msTouchAction: 'manipulation'}

ref

identify paths with query params and parse qs/fragment

make checks more sophisticated

• return flattened obj instead of array
• rename to check

match: should accept single object instead of array

c1 = check(v1,v2,v3,rx) // => {v1: f1, v2: f2, v3: f3}
c2 = check(v4,rx2) // => {v4: f4}

let m1 = match(specs, Object.assign({}, c1, c2))

make api more functional

spec('/user/:id/details')(next)
spec('/user', '/user/:id', '/user/:id/show', '/user/:id/edit')(next, err)
spec('')(next)
let c1 = checks(':id', ':date')(/\d/)
let c2 = checks(':xxx')(/\w/)
let m1 = match(<<base>>, specs, [...c1, ...c2])

let ultra = container(m1, m2, ...)(<history>)
let {stop, push, replace} = utlra

/user/abc - :id not valid, stop matching in current spec, call error of current spec

/user/007/blah - :id valid, does not match any route in current spec EXACTLY, call error of current spec

/user/007/show - :id valid, matches some route exactly, call success

/user/abc/details - matches details but fails :id validation, call error of details spec

/zzz - none of the specs match, use default

add support for querystring params

additional parameters for key value pairs
user_path(Endpoint, :show, 17, admin: true, active: false)
"/users/17?admin=true&active=false"

add redirect with timer support in resolve, reject

resolve reject should return timer instance
if time is active, abandon processing (rejections)

fix identifiers in prefix paths

pass matched value to strip method in PrefixSpec instead of the prefix pathkey

refactor path normalization

• create path normalize function
• call before processing specs
• move path fixing code from PrefixSpec class to normalize

perform input validation in clickHandler

• check which == left click
• check defaultPrevented
• if (event.metaKey || event.ctrlKey || event.shiftKey)

simplify result shape

flatten values, add ids

/:year : {exact, match, passed}
/:year/:make : {exact, match, passed}
/:year/:make/:vid : {exact, match, passed}
ids: [':year',':make', ':model']
values: ['2017','bmw','m5']

escape literals before passing to RegEx constructor

new RegExp(`^${substitute(literals, subs)}`, 'i')`

provide api for pre-match mapper

• match function accepts a mapper func
• mapper func always returns a pathname
  • for e.g. mapper could return pathname.concat(query/hash)
• matcher calls mapper fn to get new pathname

checks for query string, uri fragments in pathname

before push

• do not run encodeURI on query string and hash
• warn if
  • /? query string or /# fragment are not encoded properly

fix trailing slash regex

leave out path: "/"

accept validator in prefix spec match

remove key from match, put on toggle

pathspec match should run submatches only if primary did not match exactly

handle two consecutive identifiers in a pathKey

rectify identifier regex to match two consecutive identifiers as one

retain history, query string, hash

props.retain = 'history' or 'qs' or 'hash'
props.retain = 'history, qs' //multi

also remove need for navAction prop

do not mutate literals, values in substitute make copy

add support for full url

check same origin in click handler

parseHref should be able to parse full url

white-list path characters

depends on #22 (encodeURI)
URIComponentBlacklist = ([^\s#$&+,/:;=?@]*)
to
([^\s/]*) (space or forward slash)

check function should receive param value and all values

'/:x/:y' => match({':x': checkx}, '/xxx/yyy')
function checkx(value, mappedValues) {
  //value = 'xxx'
  //mappedValues = {':x': 'xxx', ':y': 'yyy'}
}

naming use p, qs, h for pathname, querystring, hash

all path creation thru dispatch should go through a parser

add path prefix

ability to add prefix per match(er)

let specs1 = [
 spec('/:id/details')(next),
 spec('/', '/:id', '/:id/show', '/:id/edit')(next, err)
]
let c1 = checks(':id', ':date')(/\d/)
let c2 = checks(':xxx')(/\w/)
let m1 = match(specs1, [...c1, ...c2], prefix = '/user')

let specs2 = [
 spec('/:id/details')(next),
 spec('/list')(next, err)
]
let c3 = checks(':id')(/\d/)
let m2 = match(specs2, c3, prefix = '/product')

let spec3 = [ spec('/error')(next), spec('')(next) ]
let m3 = match(specs3)

let ultra = container(m1, m2, m3)(<history>)

rename p to href, h to hash, and add path to loc

add advice - ability to intercept matching process

add validator for multiple pathKeys
ultra.advice(someValidateFn, '/a/:level1', '/a/:level1/:level2')

use encodeURI for pathnames

function fixedEncodeURI(str) {
    return encodeURI(str).replace(/%5B/g, '[').replace(/%5D/g, ']');
}

add leading slash in normalizePath

add a leading /

• path is empty
• path begins with ? or # OR path does not begin with /

refactor to Path class

• handle match and validation in Path object
• make Path object and pathKey string semantics clearer

add wait for redirect with timer in resolve

optimize warning messages for prod

In all bundles:

• prefix warning calls with /*@__PURE__*/
  In minified:
• set process.env.NODE_ENV to "production"

customEvent constructor unsupported IE11

https://gist.github.com/gt3/787767e8cbf0451716a189cdcb2a0d08

provide option to create new ultra from existing one with new matchers

current solution:

ultra.stop()
container(...ultra.matchers, ...newMatchers)(ultra.history)

provide simplified version:

container(...newMatchers)(ultra)

check should be able to accept multiple rx

let specB = spec('/')(routeB)
let level1Checks = check(':level1')(/^.{2}$/, /^[^\]]*$/)
match(specB, level1Checks, '/:level1')
// errors on href="b]" or href="bbbbb"

prevent possible deadlock in listeners

client code tries to delete a handler (element of the set) while proxy is iterating over the same handlers

this may leave the app in unexpected state

• handle this by doing soft deletes
• use weakset to hold "deleted" handlers
• implement custom iterator that will filter out the deleted handlers, and actually remove them from the set

support dynamic anchor tags

• late bind on ultra push in Anchor

createListener(ultra.push.bind(null, loc))

createListener(() => getUltra().push.bind(null, loc))

accept state, title from link and pass state to handlers