npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

abstract-state-router

v7.5.2

Published

Like ui-router, but without all the Angular. The best way to structure a single-page webapp.

Downloads

906

Readme

ChangelogJoin the chat on DiscordAPI documentation

Brief explanation

abstract-state-router lets you build single-page webapps using nested routes/states. Your code doesn't reference routes directly, like /app/users/josh, but by name and properties, like app.user + { name: 'josh' }.

To find out why you should be using this kind of router, read Why Your Webapp Needs a State-Based Router.

abstract-state-router is heavily inspired by the original ui-router. The biggest difference is: you can use abstract-state-router with whatever templating/component library you like.

It is similar in that way to the new ui-router, except that abstract-state-router is smaller, its documentation is more readable, and it is easier to create new renderers for arbitrary view libraries.

To see an example app implemented with a couple of different browser rendering libraries, click here to visit the state-router-example on Github Pages.

Project status

This project is stable and has been used in production for years.

The last major version bump change was in July of 2021 when the project started shipping modern JS instead of ES5. There have been no breaking changes to the library's function APIs since 2015.

abstract-state-router is extensible without much work, so very few feature additions have been necessary.

I occasionally have dreams of a rewrite, but it's hard to justify when the current version works so well for my main target use case (business software).

Browser compatibility

This project is currently published as CommonJS with modern JS syntax. If you're targeting browsers more than 2-3 years old, I assume you're already compiling your code for your target environments.

If you're supporting really old browsers pre-ES2015 browsers, you'll need polyfills for Promise and Object.assign. Check out polyfill.io for automatic polyfills, it makes life super-easy.

Current renderer implementations

If you want to use the state router with any other templating/dom manipulation library, read these docs! It's not too bad to get started.

Install

npm i abstract-state-router

Your CommonJS-supporting bundler should be able to import make_state_router from 'abstract-state-router' without issue.

API

Instantiate

var createStateRouter = require('abstract-state-router')

var stateRouter = createStateRouter(makeRenderer, rootElement, options)

The makeRenderer should be a function that returns an object with these properties: render, destroy, and getChildElement. Documentation is here - see test/support/renderer-mock.js for an example implementation.

The rootElement is the element where the first-generation states will be created.

options

Possible properties of the options object are:

  • pathPrefix defaults to '#'. If you're using HTML5 routing/pushState, you'll most likely want to set this to an empty string.
  • router defaults to an instance of a hash brown [email protected]. The abstract-state-router unit tests use the hash brown router stub. To use pushState, pass in a hash brown router created with sausage-router.
  • throwOnError defaults to true, because you get way better stack traces in Chrome when you throw than if you console.log(err) or emit 'error' events. The unit tests disable this.

stateRouter.addState({name, route, defaultChild, data, template, resolve, activate, querystringParameters, defaultParameters, canLeaveState})

The addState function takes a single object of options. All of them are optional, unless stated otherwise.

name is parsed in the same way as ui-router's dot notation, so 'contacts.list' is a child state of 'contacts'. Required.

route is an express-style url string that is parsed with a fork of path-to-regexp. If the state is a child state, this route string will be concatenated to the route string of its parent (e.g. if 'contacts' state has route ':user/contacts' and 'contacts.list' has a route of '/list', you could visit the child state by browsing to '/tehshrike/contacts/list').

defaultChild is a string (or a function that returns a string) of the default child's name. Use the short name (list), not the fully qualified name with all its parents (contacts.list).

If the viewer navigates to a state that has a default child, the router will redirect to the default child. (For example, if 'list' is the default child of 'contacts', state.go('contacts') will actually be equivalent to state.go('contacts.list'). Likewise, browsing to '/tehshrike/contacts' would take the viewer to '/tehshrike/contacts/list'.)

data is an object that can hold whatever you want - it will be passed in to the resolve and activate functions.

template is a template string/object/whatever to be interpreted by the render function. Required.

resolve is a function called when the selected state begins to be transitioned to, allowing you to accomplish the same objective as you would with ui-router's resolve.

activate is a function called when the state is made active - the equivalent of the AngularJS controller to the ui-router.

querystringParameters is an array of query string parameters that will be watched by this state.

defaultParameters is an object whose properties should correspond to parameters defined in the querystringParameters option or the route parameters. Whatever values you supply here will be used as the defaults in case the url does not contain any value for that parameter. If you pass a function for a default parameter, the return of that function will be used as the default value.

For backwards compatibility reasons, defaultQuerystringParameters will work as well (though it does not function any differently).

canLeaveState is an optional function with the state's domApi as its sole argument. If it returns false, navigation from the state will be prevented. If it is returns true or is left undefined, state changes will not be prevented.

resolve(data, parameters, callback(err, content).redirect(stateName, [stateParameters]))

data is the data object you passed to the addState call. parameters is an object containing the parameters that were parsed out of the route and the query string.

Returning values

Your resolve function can either return a promise, or call the callback.

Properties on the returned object will be set as attributes on the state's component.

async function resolve(data, parameters) {
	const [ user, invoice ] = await Promise.all([
		fetchUser(parameters.userId),
		fetchInvoice(parameters.invoiceId),
	])

	return {
		user,
		invoice,
	}
}

Errors/redirecting

If you return a rejected promise or call callback(err, content) with a truthy err value, the state change will be cancelled and the previous state will remain active.

If you call callback.redirect(stateName, [stateParameters]), the state router will begin transitioning to that state instead. The current destination will never become active, and will not show up in the browser history.

To cause a redirect with promises, return a rejected promise with an object containing a redirectTo property with name and params values for the state to redirect to:

function resolve(data, parameters) {
	return Promise.reject({
		redirectTo: {
			name: 'otherCoolState',
			params: {
				extraCool: true
			}
		}
	})
}

activate(context)

The activate function is called when the state becomes active. It is passed an event emitter named context with four properties:

  • domApi: the DOM API returned by the renderer
  • data: the data object given to the addState call
  • parameters: the route/querystring parameters
  • content: the object passed into the resolveFunction's callback

The context object is also an event emitter that emits a 'destroy' event when the state is being transitioned away from. You should listen to this event to clean up any workers that may be ongoing.

addState examples

stateRouter.addState({
	name: 'app',
	data: {},
	route: '/app',
	template: '',
	defaultChild: 'tab1',
	async resolve(data, parameters) {
		return isLoggedIn()
	},
	activate(context) {
		// Normally, you would set data in your favorite view library
		var isLoggedIn = context.content
		var ele = document.getElementById('status')
		ele.innerText = isLoggedIn ? 'Logged In!' : 'Logged Out!'
	}
})

stateRouter.addState({
	name: 'app.tab1',
	data: {},
	route: '/tab_1',
	template: '',
	async resolve(data, parameters) {
		return getTab1Data()
	},
	activate(context) {
		document.getElementById('tab').innerText = context.content

		var intervalId = setInterval(function() {
			document.getElementById('tab').innerText = 'MORE CONTENT!'
		}, 1000)

		context.on('destroy', function() {
			clearInterval(intervalId)
		})
	}
})

stateRouter.addState({
	name: 'app.tab2',
	data: {},
	route: '/tab_2',
	template: '',
	async resolve(data, parameters) {
		return getTab2Data()
	},
	activate(context) {
		document.getElementById('tab').innerText = context.content
	}
})

stateRouter.go(stateName, [stateParameters, [options]])

Browses to the given state, with the current parameters. Changes the url to match.

The options object currently supports two options:

  • replace - if it is truthy, the current state is replaced in the url history.
  • inherit - if true, querystring parameters are inherited from the current state. Defaults to false.

If a state change is triggered during a state transition, and the DOM hasn't been manipulated yet, then the current state change is discarded, and the new one replaces it. Otherwise, it is queued and applied once the current state change is done.

If stateName is null, the current state is used as the destination.

stateRouter.go('app')
// This actually redirects to app.tab1, because the app state has the default child: 'tab1'

stateRouter.evaluateCurrentRoute(fallbackStateName, [fallbackStateParameters])

You'll want to call this once you've added all your initial states. It causes the current path to be evaluated, and will activate the current state. If no route is set, abstract-state-router will change the url to to the fallback state.

stateRouter.evaluateCurrentRoute('app.home')

stateRouter.stateIsActive([stateName, [stateParameters]])

Returns true if stateName is the current active state, or an ancestor of the current active state...

...And all of the properties of stateParameters match the current state parameter values.

You can pass in null as the state name to see if the current state is active with a given set of parameters.

// Current state name: app.tab1
// Current parameters: { fancy: 'yes', thing: 'hello' }
stateRouter.stateIsActive('app.tab1', { fancy: 'yes' }) // => true
stateRouter.stateIsActive('app.tab1', { fancy: 'no' }) // => false
stateRouter.stateIsActive('app') // => true
stateRouter.stateIsActive(null, { fancy: 'yes' }) // => true

stateRouter.makePath(stateName, [stateParameters, [options]])

Returns a path to the state, starting with an optional octothorpe #, suitable for inserting straight into the href attribute of a link.

The options object supports one property: inherit - if true, querystring parameters are inherited from the current state. Defaults to false.

If stateName is null, the current state is used.

stateRouter.makePath('app.tab2', { pants: 'no' })

stateRouter.getActiveState()

Returns the last completely loaded state

// Current state name: app.tab1
// Current state params: pants: 'no'
stateRouter.getActiveState() // => { name: 'app.tab1', parameters: { pants: 'no' }}

Events

These are all emitted on the state router object.

State change

  • stateChangeAttempt(functionThatBeginsTheStateChange) - used by the state transition manager, probably not useful to anyone else at the moment
  • stateChangeStart(state, parameters, states) - emitted after the state name and parameters have been validated
  • stateChangeCancelled(err) - emitted if a redirect is issued in a resolve function
  • stateChangeEnd(state, parameters, states) - after all activate functions are called
  • stateChangeError(err) - emitted if an error occurs while trying to navigate to a new state - including if you try to navigate to a state that doesn't exist
  • stateError(err) - emitted if an error occurs in an activation function, or somewhere else that doesn't directly interfere with changing states. Should probably be combined with stateChangeError at some point since they're not that different?
  • routeNotFound(route, parameters) - emitted if the user or some errant code changes the location hash to a route that does not have any states associated with it. If you have a generic "not found" page you want to redirect people to, you can do so like this:
stateRouter.on('routeNotFound', function(route, parameters) {
	stateRouter.go('not-found', {
		route: route,
		parameters: parameters
	})
})

DOM API interactions

  • beforeCreateState({state, content, parameters})
  • afterCreateState({state, domApi, content, parameters})
  • beforeDestroyState({state, domApi})
  • afterDestroyState({state})

Testing/development

To run the unit tests:

  • clone this repository
  • run npm install
  • run npm test

State change flow

  • emit stateChangeStart
  • call all resolve functions
  • resolve functions return
  • NO LONGER AT PREVIOUS STATE
  • destroy the contexts of all "destroy" states
  • destroy appropriate dom elements
  • call render functions for "create"ed states
  • call all activate functions
  • emit stateChangeEnd

Every state change does this to states

  • destroy: states that are no longer active at all. The contexts are destroyed, and the DOM elements are destroyed.
  • create: states that weren't active at all before. The DOM elements are rendered, and resolve/activate are called.

HTML5/pushState routing

pushState routing is technically supported. To use it, pass in an options object with a router hash-brown-router constructed with a sausage-router, and then set the pathPrefix option to an empty string.

var makeStateRouter = require('abstract-state-router')
var sausage = require('sausage-router')
var makeRouter = require('hash-brown-router')

var stateRouter = makeStateRouter(makeRenderer, rootElement, {
	pathPrefix: '',
	router: makeRouter(sausage())
})

However to use it in the real world, there are two things you probably want to do:

Intercept link clicks

To get all the benefits of navigating around nested states, you'll need to intercept every click on a link and block the link navigation, calling go(path) on the sausage-router instead.

You would need to add these click handlers whenever a state change happened.

Server-side rendering

You would also need to be able to render the correct HTML on the server-side.

For this to even be possible, your chosen rendering library needs to be able to work on the server-side to generate static HTML. I know at least Ractive.js and Riot support this.

The abstract-state-router would need to be changed to supply the list of nested DOM API objects for your chosen renderer.

Then to generate the static HTML for the current route, you would create an abstract-state-router, tell it to navigate to that route, collect all the nested DOM API objects, render them as HTML strings, embedding the children inside of the parents.

You would probably also want to send the client the data that was returned by the resolve functions, so that when the JavaScript app code started running the abstract-state-router on the client-side, it wouldn't hit the server to fetch all the data that had already been fetched on the server to generate the original HTML.

Who's adding this?

Track development progress in #48.

It could be added by me, but probably not in the near future, since I will mostly be using this for form-heavy business apps where generating static HTML isn't any benefit.

If I use the abstract-state-router on an app where I want to support clients without JS, then I'll start working through those tasks in the issue above.

If anyone else has need of this functionality and wants to get keep making progress on it, I'd be happy to help. Stop by the chat room to ask any questions.

Maintainers

License

WTFPL