DEV Community: Zacharias Enochsson

A better useReducer: useHyperState

Zacharias Enochsson — Wed, 08 Mar 2023 23:57:58 +0000

I'd like to introduce you to useHyperstate – a custom react hook for state management. Simply put, it's a better useReducer.

Being dissatisfied with React's built in hooks for state management – and being a huge fan of Hyperapp – I took Hyperapp's state management code and packaged it as a hook.

"But I've never even heard of Hyperapp!", I hear you say, "... so why should I care about useHyperState?". Well, friend, that's what I'm here to explain. I've taken a just-complex-enough app and implemented it four different ways:

PlainApp.js uses the basic approach with useState and useEffect
ReducerApp.js replaces useState with useReducer, but can't quite shake off the need for useEffect.
HyperApp.js replaces useReducer with useHyperState (and finally eliminates useEffect)
SubApp.js illustrates how we leverage the subscriptions-feature for an even more elegant solution.

Looking at each one in turn, I aim to demonstrate how it improves incrementally on the ones before.

The example we'll be looking at is a countdown timer with adjustable duration and start/stop buttons.

(The runnable example is on codesandbox here)

The Plain Solution

We use useState to keep track of the duration that the timer should run, as well as the timestamp when the timer was started (in started) and the curren timestamp (in now). With those two and the duration state variable, we can calculate remaining.

When the timer starts, we use setInterval to start getting regular updates on the current time. With useEffect we check the remaining time, so that when the time is up, we clearInterval() to stop getting updates. This requires us to also keep the interval reference (timerInterval) in a state variable.

All told, it looks like this:

function App() {
  const [duration, setDuration] = useState(5000)
  const [started, setStarted] = useState(0)
  const [now, setNow] = useState(0)
  const [timerInterval, setTimerInterval] = useState(null)

  const remaining = !!started ? duration + started - now : 0

  const handleStop = () => {
    if (timerInterval) {
      clearInterval(timerInterval)
    }
    setStarted(0)
    setNow(0)
  }

  useEffect(() => {
    if (remaining <= 0) {
      handleStop()
    }
  }, [remaining])

  const handleStart = (now) => {
    setStarted(now)
    setNow(now)
    setTimerInterval(
      setInterval(() => {
        setNow(performance.now())
      }),
      50
    )
  }

  const handleInputDuration = (value) => {
    setDuration(value * 1000)
  }

  return (
    <div className="App">
      <TimerDemo
        duration={duration}
        remaining={remaining}
        onStart={handleStart}
        onStop={handleStop}
        onDurationInput={handleInputDuration}
      />
    </div>
  )
}

The plain Solution on codesandbox.io

This is pretty compact, but there is a lot going on in the component function scope that will be redefined every render.

If the logic were more complex, it would be hard to follow. Testing the logic requires testing the entire component (in a mock-DOM environment) as well as mocking setInterval - even though it's just the logic we're concerned about.

The Solution with `useReducer`

With useReducer, logic is easier to understand and more robust since the reducer clearly outlines the limited number of ways the state can change - the actions. It is a pure function and can be lifted out of the component scope.

But because the reducer must be pure, we need to put side effects somewhere else. No problem - we just define a function for each action, which both dispatches the action and runs associated side effects.

const initialState = {
  duration: 5000,
  started: 0,
  now: 0,
  timerInterval: null,
}

const reducer = (state, action) => {
  switch (action.type) {
    case "SET_DURATION":
      return { ...state, duration: action.duration }
    case "SET_NOW":
      return { ...state, now: action.now }
    case "START":
      return {
        ...state,
        started: action.now,
        now: action.now,
        timerInterval: action.timerInterval,
      }
    case "STOP":
      return { ...state, now: 0, started: 0, timerInterval: null }
    default:
      return state
  }
}

const calcRemaining = ({ started, duration, now }) =>
  !!started ? duration + started - now : 0

const stop = (dispatch, timerInterval) => {
  if (timerInterval) {
    clearInterval(timerInterval)
  }
  dispatch({ type: "STOP" })
}

const setDuration = (dispatch, value) => {
  dispatch({ type: "SET_DURATION", duration: value * 1000 })
}

const updateNow = (dispatch, now) => {
  dispatch({
    type: "SET_NOW",
    now: now,
  })
}

const start = (dispatch, now) => {
  const timerInterval = setInterval(
    () => updateNow(dispatch, performance.now()),
    50
  )
  dispatch({ type: "START", now, timerInterval })
}

function App() {
  const [state, dispatch] = useReducer(reducer, initialState)
  const remaining = calcRemaining(state)

  useEffect(() => {
    if (remaining <= 0) handleStop()
  }, [remaining])

  const handleStart = (now) => start(dispatch, now)
  const handleStop = () => stop(dispatch, state.timerInterval)
  const handleInputDuration = (value) => setDuration(dispatch, value)

  return (
    <div className="App">
      <TimerDemo
        duration={state.duration}
        remaining={remaining}
        onStart={handleStart}
        onStop={handleStop}
        onDurationInput={handleInputDuration}
      />
    </div>
  )
}

the useReducer solution on codesandbox.io

It is a lot less compact now, though. And we still need one useEffect in the component scope since it requires access to the state. But mainly: the testing story hasn't improved at all.

The Solution with `useHyperState`

With userHyperState there is no reducer. Instead each action is its own reducer in a sense. An action is a function that takes the current state (+ possible payload) and returns the new state.

Or, an action may return an array [newState, effect1, effect2, ...] where each effect is a function or a [function, payload] tuple that will be executed besides the state being updated.

A third return type is simply another action, which will be dispatched instead. In the solution below we can use that for the updateNow action - if the time is up we return the stop action instead of a new state.



//this is reusable library code

const startIntervalEffect = (dispatch, opts) =>
  dispatch(
    opts.setInterval,
    setInterval(() => dispatch(opts.onTick, performance.now()), opts.interval)
  )

const stopIntervalEffect = (_, timerInterval) => clearInterval(timerInterval)

// app-specific logic modelled here
const calcRemaining = ({ started, duration, now }) =>
  !!started ? duration + started - now : 0

const stop = (state) => [
  { ...state, started: 0, now: 0, intervalTimer: null },
  [stopIntervalEffect, state.timerInterval],
]

const setDuration = (state, value) => ({ ...state, duration: value * 1000 })

const updateNow = (state, now) => {
  const next = { ...state, now }
  return calcRemaining(next) <= 0 ? stop : next
}

const setTimerInterval = (state, timerInterval) => ({ ...state, timerInterval })

const start = (state, now) => [
  {
    ...state,
    started: now,
    now: now,
  },
  [
    startIntervalEffect,
    { setInterval: setTimerInterval, onTick: updateNow, interval: 50 },
  ],
]

const init = {
  duration: 5000,
  started: 0,
  now: 0,
  timerInterval: null,
}

function App() {
  const [state, _] = useHyperState({ init })
  return (
    <div className="App">
      <TimerDemo
        duration={state.duration}
        remaining={calcRemaining(state)}
        onStart={_(start)}
        onStop={_(stop)}
        onDurationInput={_(setDuration)}
      />
    </div>
  )
}

A useHyperState solution on codesandbox.io

Wins:

Easy to grasp, self-describing logic.
...entirely outside of the component scope.
set/clear interval encapsulated in generic reusable effects that can be tested & shipped separately
all the rest 100% pure and dead easy to test.

But wait - there's more!

The only reason we keep intervalTimer in the state is so we will be able to stop the timer later. Not for rendering anything. This is the perfect situation to reach for the subscriptions feature.

The `useHyperState` solution with subscriptions


//this is reusable library code
const interval = (dispatch, opts) => {
  const handler = () => dispatch(opts.onTick, performance.now())
  const interval = setInterval(handler, opts.tick)
  return () => clearInterval(interval)
}

// app-specific logic modelled here

const calcRemaining = ({ started, duration, now }) =>
  !!started ? duration + started - now : 0

const stop = (state) => ({ ...state, started: 0, now: 0 })

const setDuration = (state, value) => ({ ...state, duration: value * 1000 })

const updateNow = (state, now) => {
  const next = { ...state, now }
  return calcRemaining(next) <= 0 ? stop : next
}

const start = (state, now) => ({
  ...state,
  started: now,
  now: now,
})

const init = {
  duration: 5000,
  started: 0,
  now: 0,
}

const subscriptions = (state) => [
  state.started > 0 && [
    interval,
    {
      onTick: updateNow,
      tick: 50,
    },
  ],
]

function App() {
  const [state, _] = useHyperState({ init, subscriptions })
  return (
    <div className="App">
      <TimerDemo
        duration={state.duration}
        remaining={calcRemaining(state)}
        onStart={_(start)}
        onStop={_(stop)}
        onDurationInput={_(setDuration)}
      />
    </div>
  )
}

useHyperState with subscriptions on codesandbox.io

All the same benefits as before, but now it's about as compact as the original solution again.

In conclusion:

useHyperState has roughly the same use case & benefits as useReducer, but has a stronger story in terms of side effects and testing. Visit https://github.com/zaceno/usehyperstate for more info.

Kudos & thanks to @jorgebucaran and the Hyperapp community for developing this state-management pattern. If you like this, you may also enjoy an incredibly tiny, fast and simple frontend framework. Visit http://hyperapp.dev

Working with DOM elements of view components in Hyperapp

Zacharias Enochsson — Wed, 20 Apr 2022 23:59:50 +0000

Hyperapp's snappy and declarative virtual DOM engine is an excellent way to control your DOM most of the time. Yet there are the occasional moments when you need to work directly with the real DOM. No problem: you just use native browser apis to find and manipulate elements as needed – wrapped up in effects or subscriptions.

But sometimes I find myself wishing I could access a view-component's element within the component-definition itself. That way, I could encapsulate a component's behavior without having to burden my already creaky apps with more complexity in state, actions, effects and subscriptions. I find myself wishing there was some kind of Hyperapp-equivalent to React's useRef-hook

As it turns out, it's possible using an unsupported implementation detail of Hyperapp (in other words: it's a hack). Here's how:

Magical properties

First, let me remind you of Object.defineProperty. Among many other uses, it allows you to define a property on an object, as a pair of get & set functions. This means you can define a property that runs some code when it is accessed or assigned:


const obj = {}

let normalVal
Object.defineProperty(obj, 'normal', {
  get () { return normalVal },
  set (val) { normalVal = val }
})

Object.defineProperty(obj, 'wacky', {
  get () { return -99 },
  set (val) { console.log(val + ' ... really?!') } 
})

obj.normal = 42
obj.normal     // is 42
obj.wacky = 42 // logs "42 ... really?!"
obj.wacky      // is always -99 regardless

You can't hide your secrets from me, Hyperapp!

Now have a look at Hyperapp's source code. Specifically this line

return (vdom.node = node)

... and this line

return (newVNode.node = node)

At two places in the patching process, hyperapp mutates your vnodes by assigning a node property to them. Conveniently for us, the thing that gets assigned is the DOM element that corresponds to the vnode.

A VNode Decorator

This means we can make a decorator for vnodes like this:


const withElement = (vnode, fn) => {
  let element
  Object.defineProperty(vnode, 'node', {
    get () { return element },
    set (e) {
      element = e
      fn(element)
    }
  })
  return vnode
}

And it will allow us to solve the example they use in the React docs for useRef – a component with an input and a button. When the button gets clicked the associated input gets focused.

const TextInputWithFocusButton = () => withElement(
  h('span', {}, [
    h('input', {type: 'text'}),
    h('button', {}, text('Focus input')),
  ]),
  span => {
    let [input, button] = span.childNodes
    button.addEventListener('click', () => input.focus())
  }
)

The function where we work with the real DOM elements (I'm going to call it the "element processor") will be called with its own corresponding span-element as input, for each instance where the component is used in the view.

Don't waste cycles

It's not perfect though, because the the element processor will be called every time the view is patched. Actually twice the first time the element is created. After we've hooked up the button click to input focus we don't need to do it again for that span. So we add a guard to make sure it only happens once.

span => {
  // make sure we only do this once in the lifetime of
  // each component like this:
  if (span._seen) return
  span._seen = true
  let [input, button] = span.childNodes
  button.addEventListener('click', () => input.focus())
}

Of key importance:

For this component to work correctly, it is crucial that Hyperapp continues to associates the same element with it. That is not guaranteed unless we add a key property to the components root virtual node.

const TextInputWithFocusButton = (key) => withElem(
  h('span', {key}, [
  ...

Try the full example live here!

Dispatch actions from Real-DOM-land?

You might still be wondering: how can we get back from DOM-land to hyper-land? How can we dispatch an action from our element-processing function?

First: it's very rare you would ever need to do that. (Technically you don't need any of this, but especially not that)

Second: Be careful you don't cause an infinite loop. Dispatching actions can change the state which causes the view to get patched, which will cause your element-processor function to get called again, again dispatching an action and so on.

Those caveats out of the way, here's what you do: You simply bind the action to a made up event in the a virtual node. In the element processor you dispatch the made up event. Piece of cake :)

const TextInputWithFocusButton = ({id, OnButtonFocus}) => withElement(
  h('span', {key: id, onbuttonfocus: OnButtonFocus}, [
    h('input', {type: 'text'}),
    h('button', {}, text('Focus input')),
  ]),
  span => {
    if (span._seen) return
    span._seen = true
    let [input, button] = span.childNodes
    button.addEventListener('click', () => {
      span.dispatchEvent(new Event('buttonfocus'))
      input.focus()
    })
  }
)

Here's the live example again, this time with an action that moves button-focused inputs to the top. (Verify that by entering different text in the different inputs)

Note: We need to add a requestAnimationFrame around input.focus() now because when we dispatch the OnButtonFocus it causes the elements to be moved in the DOM. That causes them to lose focus so we wait to focus() until after they have moved.

A Fresh Take on Modular Hyperapp

Zacharias Enochsson — Fri, 10 Dec 2021 11:00:19 +0000

Back in the summer of 2020 I wrote an article series on how to make your Hyperapp-apps modular. The ideas & concepts discussed are still valid, but the method was cumbersome and my explanation dense. I've since refined how I componentize apps, so it's time for an update!

Domains of the Counter Game

Here's a game. It goes like this. Click the plus and minus buttons to increase and decrease a value. When it reaches ten the game is over. You score one point for each button-click. Give it a try!

Yes, it's the dumbest game ever made. But it's a simple example of an app having some distinct domains – parts that make sense to think about in isolation from the rest.

Take the counter for example. You could imagine replacing the counter for a different (more interesting!) game while the scoring system, and the flow of screens from "play a game?" to "game over", could remain the same.

Implementations designed to make removing/replacing domains easy tend to be very maintainable. So let's see how maintainable the implementation is.

Domains have their own State

Have a look in the JS tab above. We find that replacing is the counter for something else isn't exactly easy, because all the domains and their interactions are tangled up in a compact set of actions.

What we want is that actions belonging to a certain domain, should only affect the state of that domain. Take the Decr action for example:

const Decr = (state) =>
  state.mode !== "play"
    ? state
    : {
        ...state,
        counter: state.counter - 1,
        score: state.score + 1
      };

Decr is for decrementing the counter, so it belongs to the counter domain. It should only affect the counter state:

const Decr = state => ({ ...state, counter: state.counter - 1 })

But then what about scoring points? That belongs to the score domain, so there should be a separate action for that:

const ScorePoint = state => ({ ...state, score: state.score + 1 })

But Decr still needs to make ScorePoint happen. To do that, we add an in-line effect in Decr which dispatches ScorePoint:

const Decr = state => [
  { ...state, counter: state.counter - 1 },
  dispatch => dispatch(ScorePoint)
]

Effects for dispatching other actions

Using Hyperapp's effect system this way, to only dispatch another action, might seem like a hack (and maybe it is?). I think it makes sense, and here's why:

Imagine your app logic as a circuit board. There are points where you connect inputs such as sensors, buttons, et.c. Pressing a button connected to a certain point, is analogous to dispatching a certain action. Also, there are points where you send outgoing signals to activate whatever is connected – analogous to effects.

Let's say that instead of building your own circuit board from scratch, you source several smaller circuit-boards that do the various things you need, and hook them up. That means some output-connectors (effects) will need to signal (dispatch) some input connectors (actions) on other boards.

Dividing actions by Domains

Let's keep doing this to untangle the actions from each other.

The Incr action of the counter can be treated in the same way we changed Decr, but also we need to end the game once the value becomes 10:

const Incr = state => [
  { ...state, counter: state.counter + 1 },
  dispatch => dispatch(ScorePoint),
  state.counter === 9 && (dispatch => dispatch(EndGame)),
]

Of course we need to implement the EndGame action, for affecting the mode state – another domain:

const EndGame = state => ({ ...state, mode: 'finish' })

The Play action:

const Play = state => ({
  mode: "play",
  counter: 0,
  score: 0
})

... also belongs to the mode domain. It represents the game starting, so it also needs to make sure to initialize the score and counter:

const Play = state => [
  {...state, mode: 'play'},
  dispatch => {
    dispatch(InitScore)
    dispatch(InitCounter)
  }
]

And now those actions need to be defined as well.

const InitScore = state => ({...state, score: 0})
const InitCounter = state => ({...state, counter: 0})

Now each of the three domains – mode, score and counter – each have a set of actions for managing their domain's state with full sovereignty.

A Counter Component

Our goal is to be able to change stuff in one domain, without breaking anything outside it. So let's start with the counter an bundle everything that belongs there separately from the rest:

const Counter = () => {
  const Init = state => ({ ...state, counter: 0 })

  const Decr = state => [
    { ...state, counter: state.counter - 1 },
    dispatch => dispatch(ScorePoint)
  ]

  const Incr = state => [
    { ...state, counter: state.counter + 1 },
    dispatch => dispatch(ScorePoint),
    state.counter === 9 && (dispatch => dispatch(EndGame)),
  ]

  return {Init, Incr, Decr}
}

There is also this part from the view:

<div>
  <h1>${state.counter}</h1>
  <button onclick=${Decr}>-</button>
  <button onclick=${Incr}>+</button>
</div>

Let's put it in the component as well.

const Counter = () => {

  //...

  const view = state => html`
    <div>
      <h1>${state.counter}</h1>
      <button onclick=${Decr}>-</button>
      <button onclick=${Incr}>+</button>
    </div>`

  return {Init, view}
}

Now for the app to use this component, we need to instantiate it :

const counter = Counter()

(Why though? – We'll get to that in a sec)

In the Play action we replace InitCounter with counter.Init, and in the view we replace the counter-html with: ${counter.view(state)}

This way everything related to both behavior and appearance of a counter is defined in one place. As long as we return the same interface ({Init, view}) we can change whatever we want about the counter without affecting the rest of the app.

However, that same assurance doesn't hold in the other direction! This component is dependent on keeping its state in state.counter. Also on the EndGame and ScorePoint actions being available in the scope.

A Reusable Counter Component

Instead of relying on certain external facts to be true, the necessary information should be provided to the component from whoever consumes.

We will need to be given a get function that can extract the counter state from the full app state.

We will also need a set function that can produce a new full app state given the current full state and a new counter state.

Also, we need an onChange action we can dispatch when the value changes. That way it can be up to the consumer wether to score a point, end the game or do something else entirely.

Adapting the counter component to these changes, it looks like:

const Counter = ({get, set, onChange}) => {
  const Init = state => set(state, 0)

  const Decr = state => [
    set(state, get(state) - 1),
    dispatch => dispatch(onChange, get(state) - 1)
  ]

  const Incr = state => [
    set(state, get(state) + 1),
    dispatch => dispatch(onChange, get(state) + 1)
  ]

  const view = state => html`
    <div>
      <h1>${get(state}</h1>
      <button onclick=${Decr}>-</button>
      <button onclick=${Incr}>+</button>
    </div>`

  return { Init, view }
}

Instantiating the component now looks like:

const counter = Counter({
  get: state => state.counter,
  set: (state, counter) => ({...state, counter}),
  onChange: (state, value) => [
    state,
    dispatch => dispatch(ScorePoint),
    value === 10 && (dispatch => dispatch(EndGame))
  ]
})

Since everything the counter needs to know about the outside world is provided in this instantiation, it is no longer sensitive to changes outside of it. Moreover, we can easily have multiple counters in the same app, for different purposes without implementing them separately. We just instantiate the counter component multiple times for different states. In other words, this component is reusable!

Composing App Components

I started calling this thing a 'component' because it is composable. Several components like this could be combined together to define our app.

Rather than walk you through how to componentize the other domains, here's the same fun game again – this time with different domains componentized and composed to define the app:

Especially notice how the counter is instantiated as a sub-component of game. Also how the game's two views are passed as arguments to the flow component.

There's nothing remarkable about this structure in particular – it could be done in a myriad of ways. This one just made sense to me.

If something is unclear please drop a question in the comment section!

Final Thoughts

So, am I suggesting you go refactor your entire app now? No, definitely not. I made the game fully componentized just for illustrative purposes. As you can see it can get a bit boilerplaty and besides, it's not always so clear how to draw the line between domains.

So when should you use this approach? The main win is the separation that makes it safe to work on one thing without accidentally breaking something else. So if you have some especially tricky logic that you don't want getting in the way of your other work, you could tuck it away in a component. Another example might be if your app has several different pages with different things going on in each, you could make it easier for a team to work on different pages in parallell without merge-conflicts. Also: reusability is a big win. If you have multiple instances of the same behavior, you want to reuse it one way or another.

If you find it useful, I'd love to hear about it!

Special thanks to @mdkq on the Hyperapp Discord, for reminding me I needed to publish this, and also inspiring me to reconsider some things i had dismissed earlier.

Modular Hyperapp - Part 7

Zacharias Enochsson — Tue, 25 Aug 2020 20:00:56 +0000

NOTE: this article series is superceded by this article

Welcome to this last part of my series on Modular Hyperapp. I'll summarize what we've gone over so far, then complete the picture before signing off with some final reflections.

Recap

Views

Reusable parts of the view can be broken out as functions called views or view-components. Views are provided the values and actions they need through an object I call the model for the view.

Primitive Transforms

In the same vein, reusable bits of logic can be broken out from actions in the form of primitive transforms. They take a value, and return a new value – not the full state.

Domains

We brought up the concept of "domains" - an area/feature/aspect of your app that makes sense to think about in isolation from the rest. All logic pertaining to a certain domain makes sense to gather in a module.

Models

A module could have several views and subscription-components. Since they belong to the same domain, they need roughly the same models. It makes sense to have one common model format for all view- and subscription-components of a module.

Wired Actions / Models

In order to move action- and model-definitions to the modules for their respective domains, they need to be defined dynamically in a function I've been calling wire.

Actions in a wire function know how to operate on a particular value through the getter and a setter, given as arguments. wire return a function which, given the current state, returns the model for the module's views.

App Modules

The value that a module's actions operate on is often complex, Therefore modules should also export a value-initializer I've called init.

Modules containing an init plus all the actions and views (and subscriptions) a domain needs, I call "app modules" since they can be run as standalone apps.

Wiring App Modules to Others

A wire may also take mapped transforms as arguments – functions that tell it what to do when "something happens". wire can also return mapped transform besides the model-function for passing as arguments to other wires. In this way, modules can be wired together to form a more complicated app.

Make Modules from Modules

But not just apps! modules could be wired together to form other modules too:

import * as foo from './foo.js'
import * as bar from './bar.js'

export const init = () => ({
    myfoo: foo.init()
    mybar: bar.init()     
}

export const wire = ({getter, setter}) => {

    const myfoo = foo.wire({
        getter: state => getter(state).myfoo,
        setter: (state, myfoo) => setter(state, {
            ...getter(state),
            myfoo,
        }),
        onSnap: bar.crackle,
    })

    const mybar = bar.wire({
        getter: state => getter(state).mybar,
        setter: (state, mybar) => setter(state. {
            ...getter(state),
            mybar,
        }),
    })

    return {
        pop: foo.pop,
        model:  state => ({
            myfoo: myfoo.model(state),
            mybar: mybar.model(state),
        })
    }
}

export const view = (model) => h('div', {}, [
    h('p', {}, [ text('Foo:'), foo.view(model.myfoo) ]),
    h('p', {}, [ text('Bar:'), bar.view(model.mybar) ]),
])

In this way, an app can be structured as a tree app-modules. Even tiny things that repeat a lot, like a button with some recurring behavior, could be defined once and reused in many places.

Dynamic Instances

There is just one more thing we need to add to complete the picture: What if there can be multiple instances of some module's values in the state, and we don't know them from the start?

For instance: task-items in a to-do list. – How could we define getters and setters for a task we don't yet know will exist? We could parameterize the getters and setters, like this:

// this is task-list.js

import * as task from './task.js'

const tasks = task.wire({
    getter: (state, id) => state.tasks[id],
    setter: (state, todo, id) => ({
        ...state,
        tasks: {...state.tasks, [id]: todo}
    }),
})

The id parameter refers to a specific instance of a task.
Actions in task.js will need to get id in the payload, in order to pass it on to getter and setter.

//this is task.js

export const wire = ({getter, setter}) => {

    const SetText = (state, {id, text}) => setter(
        state,
        {...getter(state, id), text},
        id
    )
    //...

The only way actions for actions to get the id as a payload, is through the model function:

//this is task.js

export const wire = ({getter, setter}) => {

    return {
        model: (state, id) => ({
            ...getter(state, id),
            SetText: (_, event) =>
                [SetText, {id, text: event.target.value}],
            //...
        })
        //...
    }
}
//...

The task-list.js model can now create a sub-model for each task that happens to exist, each time the state updates:

//this is task-list.js

//...

const model = (state) => ({
    //...
    tasks: Object.keys(state.tasks).map(id =>    
        tasks.model(state, id)
    )
})

//...

id doesn't have to be a number or a string. It could be a complex object representing a path through a whole tree of dynamic instances. That way you could even have dynamic lists in dynamic lists!

Finally!

And here we finally are, at the end of the series! Congratulations and well done for sticking it out all the way!

It's been a long and abstract journey to this point, where we finally see that any app – no matter how large or complex – can be made up of self-contained, manageable modules, developed individually and later combined.

Closing Thoughts

Such structure is similar to what you'd have with React or Vue – which begs the question: Why not just use React or Vue? After all, this app-module pattern I've presented is rather verbose with all its getters, setters, states and ids.

I wouldn't presume to tell you the right framework to use in your particular situation, but allow me to make a case for Hyperapp:

First, I wrote this series to show how far you could take modularization if you need to. Hyperapp leaves it up to you to use just the techniques and patterns that help you.

If you want to dig in to a really over-modular example, I threw everything I had at this multi-todo-list app

Contrast that with more rigid frameworks where everything needs to be a component. You need to decide what each component should do before making it. It seems easy at first, but as you add more components, sharing state between them gets more convoluted – an issue which has led to the development of central-state-stores like Redux and Vuex. All the mechanisms for coordinating components and state come with their own APIs to learn. How much time have you spent pouring over docs and tutorials to figure out React-hooks, redux-saga, et.c? – And making the pieces fit together?

Hyperapp starts from the other end: state is global and shared by default. Nothing is encapsulated until you want to make it that way. The API is minimal and dead simple – it doesn't do everything you'd want, but it also doesn't get in the way. You have the full power of javascript at your disposal to structure your app however you please. If you have a bug, odds are it's because you used javascript wrong, not Hyperapp.

The examples here could be made much more concise and readable with some library code. But then I'd be explaining how to use my library code, and not conveying the ideas behind it.

I expect you will figure out patterns and helpers that suit your style. They will probably look different from mine, and that's fine! Regardless of what you get up to, I hope and believe that the ideas I've presented here will help!

Modular Hyperapp - Part 6

Zacharias Enochsson — Mon, 24 Aug 2020 23:34:50 +0000

NOTE: this article series is superceded by this article

In the last couple parts I've focused a lot on actions, but haven't said anything about how to handle effects or subscriptions. There isn't all that much to say, but for the sake of completeness:

Subscriptions

Every time the state changes, Hyperapp calls the subscriptions property you provide to app({...}), and expects it to return an array of all the subscriptions your app needs to respond to.

This is similar to how Hyperapp calls the view every time the state updates, to find out how the DOM should look. We can break out subscriptions in a very similar way to how we broke out views in part 2.

const counterSubs = model => [
    onKeyDown('ArrowUp', model.Increment),
    onKeyDown('ArrowDown', model.Decrement),
]

//...

app({
    //...
    subscriptions: state => [
        ...counterSubs({
            Increment: IncrementFoo,
            Decrement: DecrementFoo,
        }),
        // other subs...
    ]
})

The list of subscriptions doesn't typically grow as fast as the view does – or even actions. There is no strong reason to do anything about it until you start breaking out actions in separate modules (parts 4-5).

If your subscriptions need actions that have been moved in to a module, you should break the subscriptions out as a subscription-component, and move it to the same module. It should receive the actions in the same way view-components in the module do: via a model. That way the model and its contents becomes a secret known only to the module.

import * from './counter.js'

const foo = counter.wire({/* getter, setter, et.c.*/})

app({
    //...
    subscriptions: state => [
        ...counter.subs(foo.model(state)),
        // other subs...
    ]
})

Effects

Effects are returned from actions and that doesn't need to change – even if/when you've moved your actions from a monolith to a wire function.


const wire = ({getter, setter, onData}) => {

    const GetNewData = state => [
        setter(state, {...getter(state), fetching: true}),
        httpGet('https://example.com/data', GotData) // <-- 
    ]

    // this action doesn't need to be part
    // of a model since only GetNewData needs it.
    const GotData = (state, data) => onData(
        setter(state, {
            ...getter(state), 
            fetching: false,
            data,
        })
     )

     //...
}

Effects and Mapped Transforms though...

The only trouble, really, is when you want an effect to run with a mapped transform.

Mapped transforms, as you'll recall from part 5, are similar to actions, but aren't dispatched in response to events. They are functions that one module makes available to be called from another module's actions.

Their similarity to actions means that you sometimes want them to be able to return effects.

Say you have a mapped transform for "dealing cards". Some other action which knows more about the rules of the game will call this transform. However, the domain-logic of cards (a secret of cards.js) say that when the deck is used up, a new deck needs to be shuffled and dealt. It might look like this:

//this is cards.js

//...

const wire = ({getter, setter, ...other}) => {

    //...

    const _deal = (state) => {
         if (!cardsRemaining(getter(state))) {
             return [state, shuffle(DECK, DealNewDeck)
         } else {
             return setter(state, deal(getter(state)))
         }
    }

    return {
        deal: _deal
        //...
    }
}
//...

Whichever action is going to call deal, it will need to handle that it sometimes returns a state-effect-tuple rather than just a new state. That action then needs to make sure it returns a state-effect-tuple which includes the effect that deal returned.

That will make the action pretty cumbersome to implement. Besides, the modular separation would be better if this wasn't something other modules needed to think about.

Most often (I think) it is possible to avoid this situation by design. Try that first. Otherwise, just accept that nothing can be perfect, make peace with breaking modular purity and move on.

Meanwhile, on the Dark Side...

Or...? Well, there is a hack (strong emphasis on "hack") that lets you run effects without needing to return them from actions. I'm not recommending it, but it might at least be interesting to know about.

Taking the example above, instead of deal returning a tuple, you would implementent it as:

const _deal = (state) => setter(state, 
    cardsRemaining(getter(state))
    ? deal(getter(state))
    : {...getter(state), needsNewDeck: true}
)

You'll also need an action for what to do when we need a new deck:

const GetNewDeck = (state) => [
    setter(state, {...getter(state), needsNewDeck: false}),
    shuffle(DECK, DealNewDeck)
]

See how we no longer return the effect from the mapped transform? Instead we moved it to a proper action that is meant to be dispatched. But how to dispatch it? – That's where the hack comes in:

You can create a custom subscription function which takes the model as a parameter. That will get the subscription function to run every time the model changes. From there you can dispatch GetNewDeck:

const mySub = (dispatch, model) => {
    requestAnimationFrame(() => {
        model.needsNewDeck && dispatch(model.GetNewDeck)
    })
    return () => {} //noop
}

const subs = model => [
    [mySub, model],
    //...other, real subscriptions I might need
]

A subscription function that executes every time the state changes is definitely not how subscriptions are meant to be used. The requestAnimationFrame is there only to work around implementation details of how Hyperapp schedules subscription updates internally.

So, if you really need to run effects without returning them from an action, that's how you could do it. Just be aware that Hyperapp does not intentionally support this usage.

Almost Done

We have discussed how to divide-and-conquer the view with view components, the business-logic with primitive transforms – and even the wiring of it all with getters, setters and mapped transforms. The final pieces and some helpful closing words await you in part 7.

Modular Hyperapp - Part 5

Zacharias Enochsson — Tue, 18 Aug 2020 14:10:49 +0000

NOTE: this article series is superceded by this article

In part 4 we defined a module that encapsulated the actions and view of a counter. It looked like this.

import {h, text} from 'https://unpkg.com/hyperapp'

const init = x => x

const increment = x => x + 1
const decrement = x => x - 1

const model = ({getter, setter}) => {

    const Increment = state =>
         setter(state, increment(getter(state)))

    const Decrement = state =>
         setter(state, decrement(getter(state)))

    return state => ({
        value: getter(state),
        Increment,
        Decrement,
    })
}

const view = model => h('span', {class: 'counter'}, [
    h('button', {onclick: model.Decrement}, [ text('-') ]),
    text(model.value),
    h('button', {onclick: model.Increment}, [ text('+') ]),
])

export {init, model, view}

We saw how an app can integrate this module with just three easy steps:

init the counter state in some slot in the app state.
get the model function for a counter instance, by providing the getter and setter for accessing the state.
put the counter view somewhere in the main view, passing it model(currentState) as an argument.

The pattern is easy, but still practically useless, since a counter can't affect the app and vice versa. It would just sit there being a counter with no purpose (unless you happen to find counters amusing).

Useful App Modules

In this article we'll expand on the pattern to make useful app modules. We'll keep using the counter as an example, but we need to make it a bit more advanced first. We'll need it to respect a maximum and minimum value:

//...

const increment = (x, max) => Math.min(max, x + 1)
const decrement = (x, min) => Math.max(min, x - 1)

const model = ({getter, setter, min, max}) => {

    const Increment = state =>
         setter(state, increment(getter(state), max))

    const Decrement = state =>
         setter(state, decrement(getter(state), min))

    //...
})

//...

Alright! Now: how can we make this module interact with the rest of the app?

Writing

The module already encapsulates its own views and actions for users to increment or decrement the counter. But could we allow the app to increment/decrement programatically, from some other action? Yes, we just need to provide functions for that. Here's what I suggest:

//...

//the function formerly known as model:
const wire = ({getter, setter, min, max}) => {

    const _increment = state =>
        setter(state, increment(getter(state), max))

    const _decrement = state =>
         setter(state, decrement(getter(state), min))

    const Increment = state => _increment(state)
    const Decrement = state => _decrement(state)

    return {
        increment: _increment,
        decrement: _decrement,
        model: state => ({
            value: getter(state),
            Increment,
            Decrement,
        })
    }
}
//...
export {init, wire, view}

I changed the name of model to wire. Instead of returning a function, it returns an object containing the original function, now named model. That's just moving things around and not important. The big news is the increment and decrement functions now also returned from wire.

increment and decrement are like primitive transforms, but defined using getter and setter so they operate on the full app state. I call this kind of functions "mapped transforms".

Because mapped transforms operate on the full app state, they can be called from within any action anywhere in the app, without violating the principle of loose coupling.

Reading

Another module might want to access the value of a counter. It's already possible by calling foo.model(state).value, but if we like we could also add a more direct way:

//...
const wire = ({getter, setter}) => {

    const _value = state => getter(state)

    //...

    return {
        value: _value,
        increment: _increment,
        decrement: _decrement,
        model: state => ({
            value: _value(state),
            Increment,
            Decrement,
        })
    }
}
//...

That way another action could call foo.value(state) to get the value, rather than foo.model(state).value.

Reacting

Finally, an app using our module might need to react to something that happen in our module. In this particular case, we want let the app to know when a user incremented or decremented the value.

By requiring the app to pass an onIncrement and an onDecrement function alongside getter and setter, it tells the module what to do in those events.

//...
const wire = ({
    getter,
    setter,
    min,
    max,
    onIncrement,
    onDecrement
}) => {

    //...

    const Increment = state => {
        let old = _value(state)
        state = _increment(state)
        if (_value(state) === old) return state
        else return onIncrement(state)
    }

    const Decrement = state => {
        let old = _value(state)
        state = _increment(state)
        if(_value(state) === old) return state
        else return onDecrement(state)
    }

    //...
}
//...

We only need to call onIncrement when a user clicked the "+" button (not for calls to increment by other actions). And we only call it if the value actually changed. If it was already at the max then no increment really happened so we leave it alone.

Wiring Modules Together

Now that our module has inputs and outputs, let's wire together an app with it!

Say we are making an app for creating character-sheets for a role-playing game (the old-school kind with dice, pencil & paper, et.c.) A character can have between one and five points for each of the four attributes: strength (STR), dexterity (DEX), intelligence (INT) and charisma (CHA). You have 12 points to spend on your character attributes however you see fit.

We'll use counters for the spending/unspending of points. That means we'll hook the counters together so that we never spend more than 12 points total.

Here's one way we could do it:

import * as counter from './counter.js'

const init = () => ({
    points: 8,
    strength: counter.init(1),
    dexterity: counter.init(1),
    intelligence: counter.init(1),
    charisma: counter.init(1),
})

const spendPoint = (state, orElse) =>
    !state.points
    ? orElse(state)
    : {
        ...state,
        points: state.points - 1,
    }

const returnPoint = state => ({
    ...state,
    points: state.points + 1
})

const strength = counter.wire({
    getter: state => state.strength,
    setter: (state, strength) => ({...state, strength}),
    onIncrement: state =>
        spendPoint(state, strength.decrement),
    onDecrement: returnPoint,
    min: 1,
    max: 5,
})

//... ditto for dexterity, intelligence & charisma

And just to prove it works:

Of course you could reduce repetition in those counter-wirings with just a little more effort. I opted to leave as is to keep it more clear.

Closing Remarks, Part 5

Our introduction of "mapped transforms" seem close to calling methods on objects in OOP. And our talk about "reacting to events" in modules might lead you to think of emitting and listening for events.

I used that language because it fits the mental model of interacting modules. But what is really going on?

When the user clicks the "+" button in the STR-column, then if the strength points were already 5, nothing happens.
If strength was just 2 it would go up to 3, and onIncrement is called.
onIncrement, is a reference to the mapped transform spendPoint.
If there happen not to be any more points to spend, the orElse function is called.
orElse refers to the mapped transform strength.decrement. That brings the strength value back down to 2.

All of those functions were defined in separate places for the sake of modularity. But they are actually executed as a sequence of state transformations entirely within the Increment action of the strength counter.

Before we can wrap up (in part 7) we should take a look at how subscriptions and effects play in to things. That will be the topic of part 6.

Modular Hyperapp - Part 4

Zacharias Enochsson — Tue, 18 Aug 2020 13:44:02 +0000

NOTE: this article series is superceded by this article

In part 1, I brought up the Internal Space Station as an illustration of the idea of modules. I described how the ISS is not a massive structure, but rather an assemblage of self-sufficient segments that had been built and tested in isolation on earth. Once ready, they were shot in to space and snapped together.

Applying the analogy to developing an app, one would develop and test each feature on it's own like a "mini-app". Then build the actual app by hooking the features together with preferably not too much code.

Recap

Let's say we wanted to make such a mini-app for a counter. One that could easily be hooked in to another app. Given the patterns we've gone over so far, what would it look like?

In part 2 we talked about breaking out a view, and in part 3 we talked about breaking out the primitive transforms. We also mentioned the need for an init function and queries in order to keep the way we represent the counter-state a secret. It could look something like this:

//this is counter.js

import {h, text} from 'https://unpkg.com/hyperapp'

//initializer
const init = x => x

//primitive transforms
const increment = x => x + 1
const decrement = x => x - 1

//query function
const getValue = x => x

//view
const view = model => h('p', {class: 'counter'}, [
    h('button', {onclick: model.Decrement}, [ text('-') ]),
    text(model.value),
    h('button', {onclick: model.Increment}, [ text('+') ]),
])

export {init, increment, decrement, getValue, view}

And what does hooking it in to an app look like? Say we have an app with a value foo somewhere in the state, and that is what we want to use the counter for. It would look like this:

import {app, h, text} from 'https://unpkg.com/hyperapp'
import * as counter from 'counter.js'

IncrementFoo = state => ({
    ...state,
    foo: counter.increment(state.foo)
})

DecrementFooBar = state => ({
    ...state,
    foo: counter.decrement(state.foo)
})

//...many more actions related to other things

app({
    init: {/* ...lots of stuff */},
    view: state => h('main', {}, [
        //...
        counter.view({
            value: counter.getValue(state.foo),
            Increment: IncrementFoo,
            Decrement: DecrementFoo,
        }),
        //...
    ]),
    node: document.getElementById('app'),
})

Hmm... this isn't exactly bad but it's far from what I was envisioning when I talked about modules "snapping together".

The thing is, even though we simplified the implementation of actions by breaking out the details (primitive transforms), every action and model our app ever needs will have to be defined here in this one central place.

Setters and Getters

The problem with breaking out the actions and models is that they need to know how to find foo in the full app state. If modules had that knowledge, it would make them all tightly coupled to eachother. Tightly coupled modules are considered harmful.

What we can do, is define the state-accessor-logic separately from the actions:

const getter = state => state.foo
const setter = (state, newFoo) => ({...state, foo: newFoo})

Action-definitions can use those functions instead of explicit access:

const IncrementFoo = state =>
    setter(state, counter.increment(getter(state)))

Dynamically Defined Actions

With the accessor functions separated from the action definitions, we can move the action definitions in to counter.js:

//this is counter.js
import {h, text} from 'https://unpkg.com/hyperapp'

const init = x => x

const increment = x => x + 1
const decrement = x => x - 1

const model = ({getter, setter}) => {

    const Increment = state =>
         setter(state, increment(getter(state)))

    const Decrement = state =>
         setter(state, decrement(getter(state)))

    return state => ({
        value: getter(state),
        Increment,
        Decrement,
    })
}

const view = model => h('p', {class: 'counter'}, [
    h('button', {onclick: model.Decrement}, [ text('-') ]),
    text(model.value),
    h('button', {onclick: model.Increment}, [ text('+') ]),
])

export {init, model, view}

Hooking up that module looks like this:

import {app, h, text} from 'https://unpkg.com/hyperapp'
import * as counter from 'counter.js'

const foo = counter.model({
    getter: state => state.foo,
    setter: (state, newFoo) => ({...state, foo: newFoo})
})

//...

app({
    init: {/* ...lots of stuff */},
    view: state => h('main', {}, [
        //...
        counter.view(foo(state)),
        //...
    ]),
    node: document.getElementById('app'),
})

Now that's more like it!

Adding a second counter to the app is a piece of cake:

import {app, h, text} from 'https://unpkg.com/hyperapp'
import * as counter from 'counter.js'

const foo = counter.model({
    getter: state => state.foo,
    setter: (state, newFoo) => ({...state, foo: newFoo})
})

const bar = counter.model({
    getter: state => state.bar,
    setter: (state, newBar) => ({...state, bar: newBar})
})

//...

app({
    init: {/* ...lots of stuff */},
    view: state => h('main', {}, [
        //...
        counter.view(foo(state)),
        //...
        counter.view(bar(state)),
        //...
    ]),
    node: document.getElementById('app'),
})

App Modules

It would be equally easy to hook up counter.js up to an empty app for verification during development. And if you want to change how counters work – for instance adding a third button that increments by 2 – you can do all that in counter.js without fear of breaking anything outside.

I call this sort of modules which encapsulate domain related actions and views "app modules", because they define all the "parts" of an app.

Closing Remarks, Part 4

Unfortunately this pattern is not complete. Unless there is some way for app modules to interact, apps will just be a collections of independent widgets. In part 5 I'll expand this pattern, adding connectors so that we can hook modules together.

Modular Hyperapp - Part 3

Zacharias Enochsson — Mon, 17 Aug 2020 12:33:38 +0000

NOTE: this article series is superceded by this article

In part 1 we talked about managing complexity in software development with modules, and in part 2 applied the ideas to views. In this article, we set our sights on the "business-logic".

Entangled Actions

If the view is the face of your app, the business-logic is the brain - and actions are the neurons that hold it together. As your app becomes more featureific, actions get more complex and interconnected.

Take these as an example:


const StartNewGame = (state) => ({
    ...state,
    chips: 10,
})

const NewRound = (state) =>
    (!state.chips == 0 || state.bet > 0) ? state : [
        {
            ...state,
            chips: state.chips - 1,
            bet: 1,
        },
        shuffle([1, 2, 3, 4, 5], Deal)
    ]

const Deal = (state, deck) => ({
    ...state,
    dealer: deck[0],
    hand: deck[1],
})

const Bet = (state) =>
    (state.bet !== 1 || state.chips == 0) ? state : {
        ...state,
        chips: state.chips - 1,
        bet: 2
    }

const Showdown = (state) =>
    state.bet == 0 ? state : {
        ...state,
        chips: state.chips + (
            state.hand > state.dealer
            ? state.bet * 2
            : 0
        ),
        bet: 0,
    }

Here, shuffle is an effect that dispatches the given action with a shuffled copy of the given array.

Unless you wrote them, it's hard to tell what these actions are supposed to do. They define a simple betting game with the following rules:

Each round the player "buys in" (= bets one chip) for the dealer to shuffle the deck, deal one card face up to the player and one card face down to themselves. The "deck" is just five cards numbered 1-5.
Before the dealer reveals their card, the player may chose to bet an additional chip.
When the dealer's card is revealed, whoever has the highest card wins. If the player wins, they get their bet back times two. If they lose the bet is forfeit.
The rounds repeat as long as the player has chips.

Domains

Someone who needs to change the rules later will likely be bit worried about breaking something. We can help them by breaking out the logic in to separate domains.

How you slice domains is up to you. What matters is that you find it natural and convenient to think about each domain in isolation. Me, I see two domains in there: the "chips" and the "cards".

Primitive Transforms

What is the domain of chips? – Betting, and winning or losing the bet. The domain logic defining these processes could be formulated as:

// this is chips.js

const bet = (state) => 
    !state.chips ? state : {
        chips: state.chips - 1,
        bet: state.bet + 1
    }

const win = (state) => ({
   chips: state.chips + state.bet * 2,
   bet: 0,
})

const lose = (state) => ({
   chips: state.chips,
   bet: 0,
})

export {bet, win, lose}

Those functions, bet win and lose look like Hyperapp actions – but they are not! They take a state and return a transformed version of it, but it is not the full app state – just something specific to this domain. They are not meant to be dispatched as actions in their own right. Instead they are meant to be used within action-implementations. I call these sorts of functions "primitive transforms".

Encapsulation

The chip-state needs to be kept in the full app state, since there is no where else to put it. The mathematical operations have been moved in chips.js but the actions still have the job of moving the chip-state in and out of the full app state.

Ideally, actions shouldn't know what chip-state looks like. It should be treated as just some kind of value, and any operation you might need for changing the value should be defined as a primitive transform in chips.js. Likewise, any kind of information we want to get out of the chip-state, needs to be defined as a function:

//this is `chips.js`

...

const getBet = state => state.bet

export {bet, win, lose, getBet}

Finally, chips.js needs to export an init function for creating a new chip-state, or we'd never have anything to pass to the transforms:

//this is `chips.js`

const init = (startWith) => ({
    chips: startWith,
    bet: 0,
})

...

export {init, bet, win, lose, getBet}

That sufficiently encapsulates everything to do with chips. Now let's do the same for cards:

// this is cards.js

const DECK = [1, 2, 3, 4, 5]

const init = (deck) => ({
    player: deck[0],
    dealer: deck[1],
})

const isWin = state => state.player > state.dealer

export {DECK, init, isWin}

Better?

Our new cards.js and chips.js modules let us refactor the actions we started with as:

import * as chips from './chips.js'
import * as cards from './cards.js'

const StartNewGame = (state) => ({
    ...state,
    chips: chips.init(10),
})

const NewRound = (state) =>
    chips.getBet(state.chips)
    ? state
    : [
        {...state, chips: chips.bet(state.chips)},
        shuffle(cards.DECK, Deal)
    ]

const Deal = (state, deck) => ({
    ...state,
    cards: cards.init(deck)
})

const Bet = (state) => 
    chips.getBet(state.chips) != 1 ? state : {
        ...state,
        chips: chips.bet(state.chips)
    }
}

const Showdown = (state) => 
    !chips.getBet(state.chips)) ? state : {
        ...state,
        chips: (
            cards.isWin(state.cards)
            ? chips.win
            : chips.lose
        )(state.chips) 
    }
}

Is this better? It's not less code ...

The intent of domains and operations is conveyed more clearly, since they are expressed with english words instead of math. The math is tucked away in modules, so there is less risk of introducing a bugs when refactoring actions (like a - where it should be +, for example). In other words it will be easier to add more features to the app in the future. –Complexity managed!

Furthermore, if you wanted to change just how cards work – say, you want to turn this into a kind of simple poker-game – you can do most of that work just in cards.js. Primitive transforms are easy to combine and reuse, so you could make a library of general transforms for yourself, to speed up future development.

Conclusion, Part 3

If you find your Actions are a confusing tangle of operations, replace those operations with functions that transform just a subset of the state.

Gather the functions that operate on the same subset of state in modules. Each such module describes a "domain" of the business logic. Give the module an init function and whatever query-functions that make sense.

Now, even if you dutifully broke out every single h call from the main view as we described in part 2, and replaced every expression in your actions with primitive transforms and queries, you are still left with a monolithic list of actions, and a monlithic view passing them around.

That may be absolutely fine for you! But if you're looking for a way to break up that monolith, go on to part 4.

Modular Hyperapp - Part 2

Zacharias Enochsson — Mon, 17 Aug 2020 12:32:10 +0000

NOTE: this article series is superceded by this article

In the first part of this series, we acknowledged that modules can be tricky. In particular, it's not easy to know from the start what modules you'll need down the road.

Thankfully, Hyperapp doesn't force you to think about modules up front. You simply start writing your app in the most straightforward way possible, with all the code in a single file.

It is only when that main file gets large and unwieldy that you need to start looking around for potential modules to break out. Usually you will start looking in the view, because that is the code that tends to grow the fastest.

View components

To give an example of breaking out a piece of view into a module, let's start with this app, which contains a counter:

import {app, h, text} from 'https://unpkg.com/hyperapp'

const Increment: state => ({
    ...state,
    counter: state.counter + 1
})

const Decrement: state => ({
    ...state,
    counter: state.counter - 1
})

app({
    init: {counter: 0},
    view: state => h('main', {}, [
        h('h1', {}, [text('My Counter:')]),
        h('p', {class: 'counter'}, [ 
            h('button', {onclick: Decrement}, [ text('-') ]),
            text(state),
            h('button', {onclick: Increment}, [ text('+') ]),
        ])
   ]),
   node: document.getElementById('app')   
})

You wouldn't actually bother breaking out modules from an app this simple, but a realistic example would be harder to follow. Just pretend it is messier than it really is ;)

Since each node is defined by a call to h, breaking out just the counter is as easy as cut-n-pasteing the node you want into a new function:

const counterView = state => h('p', {class: 'counter'}, [
    h('button', {onclick: Decrement}, [ text('-') ]),
    text(state.counter),
    h('button', {onclick: Increment}, [ text('+') ]),
])

I call functions like this "view components" – or "views" for short – because they are composable bits of view. (In the Hyperapp community they are often called "components")

This counterView allows us to express the main view in a more compact way:

state => h('main', {}, [
    h('h1', {}, [ text('My Counter:') ]),
    counterView(state),
])

View components in modules

When we move counterView into a separate module (counter.js) it loses its references to Increment and Decrement, since they are still in the scope of the main module (main.js). There are three ways to fix that:

Option A: Move the actions to counter.js as well

The downside is that the actions are dependent on the full app state, so we would need to keep revisiting counter.js to update Increment and Decrement as we add new features.

Moreover we couldn't reuse this module for a second counter in the app, because it is bound specifically to these two actions.

Option B: Export the actions from main.js and import them in counter.js

This makes counter.js dependent on main.js, and has the same reusability issue as option A.

Option C: Pass the actions as arguments to counterView

This is the one we'll go with.

Speaking of which, we can't have counterView dependent on the full app state as an argument. It should expect the most concise and well defined set of arguments that provide just the values and actions it needs. It could look something like this:

// this is counter.js
import {h, text} from 'https://unpkg.com/hyperapp'

const view = ({value, Increment, Decrement}) =>
    h('p', {class: 'counter'}, [
        h('button', {onclick: Decrement}, [ text('-') ]),
        text(value), // <--- !!! not `state.counter`
        h('button', {onclick: Increment}, [ text('+') ]),
    ])

export {view}

Models

With that, main.js becomes:

import {app, h, text} from 'https://unpkg.com/hyperapp'
import {view as counterView} from './counter.js'

const Increment = state => ({
    ...state,
    counter: state.counter + 1
})

const Decrement = state => ({
    ...state,
    counter: state.counter - 1
})

app({
    init: {counter: 0},
    view: state => h('main', {}, [
        h('h1', {}, [text('My Counter:')]),
        counterView({
            value: state.counter, // <-- 
            Increment,
            Decrement,
        })
   ]),
   node: document.getElementById('app')   
})

The object {value, Increment, Decrement} is what I call the "model" for this particular view. It is up to the main view to map the current state and in-scope actions to the required model.

That's a bit more effort than just counterView(state) but modularization is about saving effort later at the cost of a bit more code now.

Reusability

With our counter in such a loosely coupled module, we can make it fancier with animated SVGs and what not, only by editing counter.js. More importantly, we can add a second counter with the same look but different behavior – without changing or duplicating counter.js!

import {app, h, text} from 'https://unpkg.com/hyperapp'
import {view as counterView} from './counter.js'

const IncrA: state => ({...state, A: state.A + 1})
const DecrA: state => ({...state, A: state.A - 1})
const IncrB: (state, x) => ({...state, B: state.B + x})
const DecrB: (state, x) => ({...state, B: state.B - x})

app({
    init: {A: 0, B: 0},
    view: state => h('main', {}, [
        h('h1', {}, [text('My Counter:')]),
        counterView({
            value: state.A,
            Increment: IncrA,
            Decrement: DecrA,
        }),
        h('h1', {}, [text('My Other Counter:')]),
        counterView({
            value: state.B,
            Increment: [IncrB, 3],
            Decrement: [DecrB, 3],
        }), 
   ]),
   node: document.getElementById('app')   
})

Conclusion, Part 2

In summary: Manage your complex view by breaking it apart into view components, in separate modules. If those get too big, break them down further.

A view component takes a model as its argument, which is an object containing all of the values, as well as all of the actions it needs.

The most effective approach is to target repetitive chunks of view, as well as large chunks that can be hidden behind concise models.

That should keep your view code in check as your app continues to grow. Taming the other side of your app – the business logic – is what we'll focus on for the rest of the series.

Modular Hyperapp - Part 1

Zacharias Enochsson — Mon, 17 Aug 2020 12:31:10 +0000

NOTE: this article series is superceded by this article

When a codebase grows larger, splitting it into manageable chunks becomes important to keep up momentum. You want bite-sized pieces of app that you can edit and test independently, without impacting the rest of your code.

Some frameworks are built entirely around this principle. In React and Vue you code the various "parts" of your app in the form of "components". Hyperapp does not have any such constructs to guide you – how you structure your app is entirely up to you.

That can be bewildering, but it is also one of the strengths of such a minimalistic framework. General problems are solved using general programming techniques – not framework specific helpers. Experienced programmers can rely on what they already know, while the novice can be confident what they learn will be useful in future projects and domains.

Nevertheless, it can be bewildering. In this series of articles, I'll present several plain javascript techniques you can use to structure your Hyperapp apps in a modular way.

I'll kick off the series with a closer look at modules and modularity. It will be fairly high-level and not Hyperapp-specific, but it forms the foundation for the concrete patterns we'll look at in future installments.

Modules

Simply put, a module is something that you can easily "plug in" to add some new feature. Think of the International Space Station. When it needs more room to house more astronauts, a living-space module is built on earth and launched in to orbit. In space, all they need to do is plug it in to an available port, and voilá – the space station can now sustain more astronauts. Over time the ISS has handled wear and changing use cases simply by adding and removing modules.

In programming, what we typically mean by a module is a code-file which exports some values, functions, classes et c. Other modules can import these things to gain new powers.

Much of our discussion about modules and modularity applies to classes and object-oriented programming as well. But since Hyperapp is rooted in the functional programming paradigm, we'll stick to that.

To be able to use modules in javascript, add the type "module" to the script tag which starts your app. Then it can import whatever it needs from other modules.

<html>
  <head>
    <script type="module">
        import {h, text, app} from 'https://unpkg.com/hyperapp'
        import {foo, bar} from './foo.js'
        /*
          ...
          do stuff using, h, text, app
          as well as foo and bar
          ...
        */
    </script>
    ...

For a complete reference on the syntax of exporting/importing from modules, see this MDN guide

Complexity

While space-engineers use modules to avoid the dangers and difficulties of monkey-patching live systems in space, programmers use modules to manage complexity.

Once your app gets big enough, looking at your own code can start to feel like looking at an unintelligible tangle of wires. When even the people who wrote it can't understand it, further development is effectively halted. Modules can help avert this fate by breaking the complexity up into smaller chunks, where each module on it's own is manageable.

//This is foo.js

// some reasonably complex stuff:
const zip = ...
const zap = ...
const zorp = ... 

//...hidden behind this simpler interface:
const foo = ... // uses zip, zap & zorp
const bar = ... // uses zip, zap & zorp

export {foo, bar}

Every module carries its own scope, meaning you can freely assign variables within the module without fear of naming conflicts in other modules. This is an essential feature of modules: they don't know anything about each other besides what they export.

The exports constitute an interface for other modules. As long as you fulfill this contract, it doesn't matter how you do it. Like an ISS module, as long as the docking-port has the right size and shape, with the right connectors in the right places, you can build the rest of the module however you like.

The Crux

Just hiding some complicated code behind an interface is not necessarily enough to actually manage complexity. Take this example:

const zip = (zipthing, index) => ...
const zap = (zapthing, value) => ...
const zorp = (zorpthing, options) => ...

const foo = (app) => {
    let zapthing = zip(app.theZipper, app.current) 
    let zapResult = zap(zapthing, app.settings.zapopts.value)
    return zorp(app.theZipper.zorp, {
        ...app.zorpopts,
        zap: zapResult,
    })
}
export {foo}

Notice how sensitive it is to the contents of app! The idea behind a module like this, was probably to move the logic out of the way to simplify logic elsewhere in the app. But any change to app risks breaking the module, so nothing was actually untangled. Instead, parts of the tangle were just hidden away, which only makes matters worse.

Any assumptions about the rest of your app that a module relies on, is technically a part of the interface. If the interface is broad, diffuse and sensitive then you aren't really creating the separation between complexities that would help you deal with them.

This is the trick to using modularity to its full advantage: keeping the interfaces small, simple and robust. Ideally they should be similar between modules as well. This means implementing your modules with as few assumptions as possible on the external.

Keeping interfaces small and simple is commonly referred to as "loose coupling", and making as few assumptions as possible is known as "the principle of least knowledge" or the "Law of Demeter"

Conclusion, Part 1

In summary there is more to modularity than just export and import. Knowing when it is time to break something out into a module, what to put in that module, and how to design the interface is a subtle art. Like anything, experience is the best teacher.

In the following installments we'll explore some specific cases and concrete patterns with discussions of their pros and cons.

DEV Community: Zacharias Enochsson

A better useReducer: useHyperState

The Plain Solution

The Solution with useReducer

The Solution with useHyperState

The useHyperState solution with subscriptions

In conclusion:

Working with DOM elements of view components in Hyperapp

Magical properties

You can't hide your secrets from me, Hyperapp!

A VNode Decorator

Don't waste cycles

Of key importance:

Dispatch actions from Real-DOM-land?

A Fresh Take on Modular Hyperapp

Domains of the Counter Game

Domains have their own State

Effects for dispatching other actions

Dividing actions by Domains

A Counter Component

A Reusable Counter Component

Composing App Components

Final Thoughts

Modular Hyperapp - Part 7

NOTE: this article series is superceded by this article

Recap

Views

Primitive Transforms

Domains

Models

Wired Actions / Models

App Modules

Wiring App Modules to Others

Make Modules from Modules

Dynamic Instances

Finally!

Closing Thoughts

Modular Hyperapp - Part 6

NOTE: this article series is superceded by this article

Subscriptions

Effects

Effects and Mapped Transforms though...

Meanwhile, on the Dark Side...

Almost Done

Modular Hyperapp - Part 5

NOTE: this article series is superceded by this article

Useful App Modules

Writing

Reading

Reacting

Wiring Modules Together

Closing Remarks, Part 5

Modular Hyperapp - Part 4

NOTE: this article series is superceded by this article

Recap

Setters and Getters

Dynamically Defined Actions

App Modules

Closing Remarks, Part 4

Modular Hyperapp - Part 3

NOTE: this article series is superceded by this article

Entangled Actions

Domains

Primitive Transforms

Encapsulation

Better?

Conclusion, Part 3

Modular Hyperapp - Part 2

NOTE: this article series is superceded by this article

View components

View components in modules

Models

Reusability

Conclusion, Part 2

Modular Hyperapp - Part 1

NOTE: this article series is superceded by this article

Modules

Complexity

The Crux

Conclusion, Part 1

The Solution with `useReducer`

The Solution with `useHyperState`

The `useHyperState` solution with subscriptions