Hyperapp Middleware

A 0.4 KB utility belt to build higher-order apps (HOAp) for Hyperapp using higher-order actions (HOAc) known as middleware.

Installation

Node.js

Install with npm / Yarn.

npm i hyperapp-middleware

Then with a module bundler like rollup or webpack, use as you would anything else.

import { enhance } from "hyperapp-middleware"

Or using require.

const { enhance } = require("hyperapp-middleware")

Browser

Download the minified library from the CDN.

<script src="https://unpkg.com/hyperapp-middleware"></script>

You can find the library in window.middleware.

API

First, a few formal definitions with the shape of some common types of interest.

• An ActionResult is a State slice, Thunk, empty object, or falsy value
• An Action is a function that receives the current State, Actions, and data from the Action call. It returns an ActionResult
• ActionInfo is an object that describes a call to an Action by its name and what data was passed to the Action function
• An HOAc/Middleware is a function that takes an Action function as its argument and returns another Action function, or a falsy value to use the result of the original Action instead of the Middleware
• An HOAp is a function that takes an App function and returns another App function

ActionResult = Partial<State> | Thunk | {} | falsy
Action = function(State, Actions, data: any): ActionResult
ActionInfo = { name: string, data: any }
HOAc = Middleware = function(Action): Action | falsy
HOAp = function(App) : App

enhance

The most basic primitive used for applying middleware to actions in an app. This is a function that accepts either a singular middleware, or an array of such functions, and returns an HOAp.

enhance = function(
  Middleware | [ Middleware ]
): HOAp

Usage

Bear in mind that this option comes with the most power and therefore you have the most responsibility when using it.

// To pass multiple middleware, use an array
enhance(
  // This is the original action function
  // that would have been called
  // if not for the middleware
  action =>
  // This is the new action function being returned
  // If you decide to bail early on this action
  // then return something falsy instead.
  (state, actions, data) => {
    // Feel free to call any additional actions before or after the original action
    actions.foo()
 
    // The author of the middleware
    // is responsible for calling the action
    // If and when they so desire.
    // You can use modified state, actions,
    // or data if that's what you're into.
    const result = action(state, actions, data)
 
    // Make sure to return what you want
    // the result of the action to be
    return result
  }
)(app)({
...
})

makeResolve

This HOHOAc (higher-order higher-order action) is a helper for creating HOAcs that are used for reacting to/modifying the results ofActions. The Resolver passed to makeResolve is used to create the Resolve function that receives Action results or a falsy value to skip this entirely. An HOAc is returned which can be converted to a usable HOAp with enhance.

Resolve = function(State, Actions, result: any)
Resolver = function(ActionInfo) : Resolve | falsy
makeResolve = function(Resolver): HOAc

Usage

Here is an example of using makeResolve to support actions returning a Promise for async updates.

enhance([
  makeResolve(
    // Notice that action.name and action.data are available
    // to inform you about the action that returned this result.
    action =>
      // This is the Resolve function
      (state, actions, result) =>
        // Always return what the new result should be for this action
        result && typeof result.then === "function"
          ? update => result.then(update)
          : result
  ),
  // Other middleware for fun & profit
  ...
])(app)({
...
})

makeUpdate

This function works similiarly to makeResolve except that it is called after a sync/async Action completes and is requesting to update the State. The Updater passed to makeUpdate is used to create the Update function for validating/modifying state updates or a falsy value to skip this entirely. An HOAc is returned which can be converted to a usable HOAp with enhance.

Update = function(State, Actions, nextState: State)
Updater = function(ActionInfo) : Update | falsy
makeUpdate = function(Updater): HOAc

Usage

Here is an example of using makeUpdate to only allow state updates that include the valid property.

enhance(
  makeUpdate(
    // Notice that action.name and action.data are available
    // to inform you about the action that led to this state update.
    action =>
      // This is the Update function
      (state, actions, nextState) =>
        // Return what you want the updated state to be
        // Use state if you want to leave the current value unchanged
        // Use nextState if the update is valid
        // Use another value if you need to normalize
        // the new state value.
        nextState.valid ? nextState : state
  ),
  ...
)(app)({
...
})

License

Hyperapp Middleware is MIT licensed. See LICENSE.