NANNY STATE is a small reactive state library that makes it simple to build speedy web apps.

It does everything React does, but without the build process, JSX or a virutal DOM ... and it's a fraction of the size!

• SMALL - less than 4kb minified and zipped
• SIMPLE - a single state object with some useful helper methods
• SPEEDY - automatic page renders that are blazingly fast

It uses a purely declarative notation and everything is written in Vanilla JS and HTML. To get started, just set the initial state and write the view - check out the example below:

// A single import is all that's needed
import Nanny from "nanny-state"

// View is a tag function that accepts the state as a parameter and returns plain old HTML
const View = state => state.HTML`
  <h1>❤️ ${state.count}</h1>
  <div>
    <button onclick=${event => state.Decrement("count")}>👎</button>
    <button onclick=${event => state.Increment("count")}>👍</button>
  </div>`

// the initial State is just a plain old object 
const State = { 
  count: 0, 
  View
}

// Start the Nanny State!
Nanny(State)

NANNY STATE stores everything in a single state object and automatically re-renders the view whenever the state changes. This helps to keep your code more organized and easier to maintain without the bloat of other libraries.

• Centralized state object that is shared across the whole app
• Built-in router makes it easy to build single page web apps
• Local storage can be added with a single line of code
• Calculations and Effects
• Sequential updates in a single line of code
• Everything is written in vanilla JS and HTML
• A single import and no build process

NANNY STATE uses a one-way data flow model between the state and view:

In NANNY STATE, the state is everything. It is a single object that is the ultimate source of truth in the application where all the app data is stored. This means that any changes to the application remain consistent and easier to keep track of. The view is an HTML representation of the state and the Nanny State's helper methods ensure that any updates are deterministic with predictable outcomes. When the state is updated, the view is automatically re-rendered to reflect the changes that were made.

NANNY STATE was inspired by Hyperapp and Redux and uses the amazing µhtml library for rendering. It is open source software; please feel free to help out or contribute.

The name is a British phrase for an overly protective, centralised government. In a similar way, NANNY STATE stores all the app data centrally and controls how it is used.

Install nanny-state from NPM.

npm install nanny-state

Then import like this:

import Nanny from "nanny-state"

If you use ES Modules, you don't need NPM. You can import from a CDN URL in your browser or on CodePen.

<script type="module">
  import Nanny from "https://esm.sh/nanny-state"
</script>

import Nanny from 'nanny-state'

const State = { 
  View: state => state.HTML`<h1>Hello World</h1>`
}

Nanny(State)

const View = state => state.HTML`<h1>Hello ${state.name}</h1>`

State = {
  name: "World",
  View
}

const View = state => 
  state.HTML`<h1>Hello ${state.name}</h1>
             <button onclick=${e => state.Update({name: "Nanny State"})}>Hello</button>`

const View = state => {
  const changeName = event => state.Update({name: event.target.value})
  return state.HTML`<h1>Hello ${state.name}</h1>
  <input oninput=${changeName}>`
}

 const State = {
  name: "World",
  View
} 

import Nanny from 'nanny-state'

const View = state => {
  const salutation = state.salutation === "Hello" ? "Goodbye" : "Hello"
  const changeSalutation = event => state.Update({salutation})
  return state.HTML`<h1>${state.salutation} World</h1><button onclick=${changeSalutation}>${salutation}</button>`
}

const State = {
  salutation: "Hello",
  View
}

Nanny(State)

import Nanny from 'nanny-state'

const View = state => state.HTML`<button onclick=${e => state.Update({count: state.count + 1})}>${state.count}</button>`

const State = {
  count: 0,
  View
}

Nanny(State)

const handler = params => event => newState

const incrementCount = n => event => state.Update({count: state.count + n})

const View = state => {
  const incrementCount = n => event => state.Update({count: state.count + n})
  return state.HTML`
  <h1>${state.count}</h1>
  <div>
    <button onclick=${incrementCount(1)}>+1</button>
    <button onclick=${incrementCount(2)}>+2</button>
    <button onclick=${incrementCount(-1)}>-1</button>
  </div>`
}

import Nanny from 'nanny-state'

const Button = (state,props) => {
  const incrementCount = n => event => state.Update({count: state.count + n})
  return state.HTML`<button onclick=${incrementCount(props.n)}>${props.text}</button>`
}

const View = state => state.HTML`
<h1>${state.count}</h1>
<div>
  ${Button(state,{text: "+1",n: 1})}
  ${Button(state,{text: "+2",n: 2})}
  ${Button(state,{text: "-1",n: -1})}
</div>`

const State = {
  count: 0,
  View
}

Nanny(State)

const Button = (state,props) => {
  const incrementCount = n => event => state.Update({count: state.count + n})
  return state.HTML`<button onclick=${incrementCount(props.n)}>${props.text}</button>`
}

${Button(state,{text: "-1",n: -1})}

The state has a number of methods that can be used . Built-in methods or properties are always written in PascalCase (starting with an upper-case letter), so it's recommended to only define properties that start with a lower-case letter in the state to avoid clashes with any of the built-in methods.

These are the only 3 methods you need to get started and the ones that are used in every NANNY STATE app:

Note that this is actually just the html function imported from µhtml, so you can learn a lot more about its intricacies by reading the full docs there.

The basics are that the state.HTML method is a tag function that accepts a backtick string of HTML that will be re-rendered every time the state changes.

Example:

state.HTML`<h1>Hello World</h1>`

Any valid HTML is acceptable. State properties and any other values can be inserted into the HTML by placing them inside ${}.

Example:

state = {
  name: "Nanny State"
}
state.HTML`<h1>Hello ${state.name}</h1>`

A function that accepts the state and returns a string of HTML based on the state. The return value must be generated using the state.HTML function described above.

Update is the only way to update the state.

It accepts an object as a parameter. Any properties in this object will be updated in the state with the values provided. If the property doesn't already exist in the state, then it will be added to the state.

Example:

state = {
  count: 1
}

state.Update({count: 5, name: "Nanny State"})

state = {
  count: 5,
  name: "Nanny State"
}

The update can also be passed a transformer function instead of an object. A transformer function accepts the current state as an argument and returns a new representation of the state. They are basically a mapping function from the current state to a new state as shown in the diagram below:

ES6 arrow functions are perfect for transformer functions as they visually show the mapping of the current state to a new representation of the state.

Transformer functions must be pure functions. They should always return the same value given the same arguments and should not cause any side-effects. They take the following structure:

state => newState

Here's an example of a transformer function that would change the case of the name property to uppercase:

const upCase = state => ({name: state.name.toUpperCase()})

Transformer functions are passed by reference to the Update function. The current state is implicityly passed as an argument to any transformer function (similiar to the way the event object is implicitly passed to event handlers when they are called).

The state.Update method accepts multiple arguments and will update the state in the order they are provided. The state after updating with the previous argument will be used in to update with subsequent arguments.

For example:

State = {
  likes: 0,
  popular: false
}

state.update({likes: state.likes + 1, popular: state.likes > 10 ? true : false })

This will cause a problem when the value of state.likes is 10. After this update state.likes will increment to 11, but the test in the ternary operator will still be using the previous value of 10 to check if it should change. This means that even though the number of likes will increase to 11 and display this, the value of state.popular will remain as false.

This can be overcome by sending the updates sequentially:

state.update({likes: state.likes + 1}, popular: state.likes > 10 ? true : false })

This will update the value of state.likes to 11 and then update the value of state.popular using the just updated value of 11 for state.likes.

Note it would be better to use the state.Calculate method to update the value of state.popular whenever state.likes changes.

Returns the current value of any property of the state provided as a parameter. These values can be queried but can't be changed (you need to use the Update method to actually change any properties of the state).

Example:

const State = {
  count: 10
}

state.Evaluate("count") = 10

Returns a JSON string representation of the current state.

Example:

const State = {
  count: 10
}

state.JSON() = "{'count':10}"

The Calculate method adds a function that will calculate the value of a property of the state based on other properties of the state whenever the state changes, or when only specific properties of the state change:

state.Calculate(state = > ({ doubleCount: state.count * 2 }))

This will update the property state.doubleCount to double the value of state.count whenever the state changes.

State.Calculate also accepts a second argument, which is a comma-seperated list of properties. The calculation will only run when these properties change. If this is left empty, then the calculation will run after every update to the state.

state.Calculate(state = > ({ doubleCount: state.count * 2 }),"count")

This will now only recalculate when the state.count property changes.

The Effect method adds a function that causes any side-effects and runs after any update to the state, or when only specific properties change.

state.Effect(state = > console.log(state.count))

This will log the value of state.count to the console whenever the state changes.

State.Effect also accepts a second argument, which is a comma-seperated list of properties. The effect will only run when these properties change. If this is left empty, then the effect will run after every update to the state.

state.Effect(state = > console.log(state.count), "count")

This will now only log the value of state.count to the console when the state.count property changes.

The state.Every method will continually update the state after a given number of milliseconds.

Example:

State = {
  time: 0,
}

The state.Delay method will update the state after a specified number of milliseconds.

The state.Increment method is a convenience method that will increase the value of a property by a given value that defaults to 1. The name of the property is provided as the first argument as a string, the second argument is a number that the property should increase by.

Example:

State = {
  count: 10
}

// increase the count by 1
state.Increment("count")

// increase the count by 5
state.Increment("count",5)

The state.Decrement method is a convenience method that will decrease the value of a numerical property of the state by a given value that defaults to 1. The name of the property is provided as the first argument as a string, the second argument is a number that the property should decrease by.

Example:

State = {
  count: 10
}
// decrease the count by 3
state.Decrement("count",3)

The state.Toggle method is a convenience method that will toggle the value of a Boolean property by a given value that defaults to 1. The name of the property to toggle is provided as a string as the only argument.

Example:

State = {
  darkMode: true
}
// turn off dark mode
state.Toggle("darkMode")

Initiate is a method of the state object that is called once before the initial render. It has access to the state and works in the same way as the Update function in that its return value updates the state.

For example, adding the following method to the State object in the counter example will set the start value of the count property to 42:

State.Initiate = state => ({count: 42})

Of course this could have just been hard coded into the State object directly, but sometimes it's useful to programatically set the initial state using a funciton when the app is initialized.

Before and After are methods of the state object that are called before or after a state update respectively. They have access to the state and work in the same way as the Update function in that their return value update the state.

For example, try adding the following methods to the State object in the 'Hello Nanny State' example to the following:

State.Before = state => console.log('Before:', state.name)
State.After = state => console.log('After:', state.name)

Now, when you press the Hello button, the following is logged to the console, showing how the state has changed:

"Before:"
{
  "name": "World"
}
"After:"
{
  "name": "Nanny State"
}

By Default the view will be rendered inside the body element of the page. This can be changed using the Element property of the state object or by providing it as part of the options object of the Nanny function. For example, if you wanted the view to be rendered inside an element with the id of 'app', you just need to specify this as an option when you call the Nanny function:

State.Element = document.getElementById('app')

Debug is a property of the state that is false by default, but if you set it to true, then the value of the state will be logged to the console as a JSON string after the initial render and after any changes to the state.

State.Debug = true

LocalStorageKey is a property of the state that ensures that the state is automatically persisted using the browser's local storage API. It will also retrieve the state from the user's local storage every time they visit the site, ensuring persitance of the state between sessions. To use it, simply set this property to the string value that you want to be used as the local storage key. For example, the following setting will use the string "nanny" as the local storage key and ensure that the state is saved to local storage after every update:

State.LocalStorageKey = 'nanny'

LocalStorageBlackList is a property of the state that is a comma-separated string of values that should not be stored in local storage and will therefore not persist between sessions.

Example:

State.LocalStorageBlackList = "name,count"

The state.name and state.count properties will not be saved to local storage.

Routing is baked in to NANNY STATE. Remember that the State Is Everything, so all the routes are set up in the State object. Simply define a property called Routes as an array of route objects. Route objects contain the following properties:

• path: the path used to access the route
• title: the title property of the route
• view: a function that works exactly like the main View function (a bit like a sub-view) and accepts the current state as an argument and returns a string of HTML

Here's a basic example:

Routes: [
    { path: "/", title: "Home", view: state => state.HTML`<h1>Home</h1>` },
    { path: "about", title: "About", view: state => state.HTML`<h1>About Us</h1>` },
    { path: "contact", title: "Contact", view: state => state.HTML`<h1>Contact Us</h1>` }
  ]

Let's use those route objects to build a mini single-page website.

First of all we need to create the main View. When using routes, this takes the form of a template layout for all pages and we use the special Content property of the State to indicate where the specific content from each route will be displayed in the layout. Here's a basic example:

const View = state => state.HTML` <h1>Nanny State</h1>
  <h2>Router</h2>
  <nav>
    <ul>
      <li><a href="/" onclick=${state.Link()}>Home</a></li>
      <li><a href="/about" onclick=${state.Link()}>About</a></li>
      <li><a href="/contact" onclick=${state.Link()}>Contact</a></li>
    </ul>
  </nav>
  <main>${state.Content}</main>`

The first thing to notice here are the state.Content property inside the <main> tags. This will render a different view, depending on the route. This is the function that is provided as the view property in the route object.

The other thing to notice is the built-in state.Link() method. This will update the current route to the argument provided. If no argument is provided then it will automatically use the value of the href attribute. So, in the example above, clicking on the 'About' link will update the route to '/about'.

Now we just need to create the initial State object. This needs to contain the Routes array that contains a route object for each route as well as the View:

const State = {
   Routes: [
    { path: "/", title: "Home", view: state => state.HTML`<h1>Home</h1>` },
    { path: "about", title: "About", view: state => state.HTML`<h1>About Us</h1>` },
    { path: "contact", title: "Contact", view: state => state.HTML`<h1>Contact Us</h1>` }
  ],
  View
}  

Last of all we just need to start the Nanny State:

Nanny(State)

You can see this example on CodeSandbox (note that routing won't work on CodePen).

You can create nested routes by adding a routes property to a route object. This is an array that acts in the same way as the top-level Routes property and contains nested route objects.

For example, if you wanted the route '/about/us' to go to display the About page, you could update the Routes array above to the following:

Routes: [
    { path: "/", title: "Home", view: state => html`<h1>Home</h1>` },
    { path: "about", 
        routes: [ 
          { path: "us", title: "About Us", view: state => html`<h1>About Us</h1>` }
        ] 
    },
    { path: "contact", title: "Contact", view: state => html`<h1>Contact Us</h1>` }
]

The routes array in any route object can contain as many nested routes as required.

The : symbol can be used to denote a wildcard route. For example, the following route object using a wildcard called :name in its path property:

    { path: ":name", title: "Programming Languages", view: state => html`<h1>${state.language)</h1>` }

When the user visits the URL path '/javascript' a params object will be created with the a key of "name" and value of "javascript". This can then be used in an update function that can be added to the route object and works in exactly the same way as the NANNY STATE Update function, it accepts the current state and returns a new state. The different is that this also accepts the params object as its first parameter (this is passed automatically to the update function along with the state.

In this example we could add the following update function to the route object:

    { path: ":name", title: "Programming Languages", view: state => html`<h1>${state.language)</h1>`, update: params => state => ({ language: params.name})  }

This will set the language property of the state to be the same as the name property of the params object, in other words it will be set to whatever was entered into the URL. This property is then displayed as a heading in the view for this route.

Released under Unlicense by @daz4126.