Kea 2.1 does two things:

• Continues the "let's make things simpler" trend started in Kea 2.0 by removing another bunch of squiggly bits that you will not need to type again: " ((((((()))))))===>>>{}"
• Adds support for accessing the state before an action was fired inside listeners.

It's also backwards compatible: Logic written for Kea version 1.0 will still run in 2.1.

The saga until now:​

This is Kea 1.0:

const logic = kea({
    actions: () => ({
        goUp: true,
        goDown: true,
        setFloor: floor => ({ floor })
    }),
    reducers: ({ actions }) => ({
        floor: [1, {
            [actions.goUp]: state => state + 1,
            [actions.goDown]: state => state - 1,
            [actions.setFloor]: (_, { floor }) => floor
        }]
    }),
    selectors: ({ selectors }) => ({
        systemState: [
            () => [selectors.floor],
            floor => floor < 1 || floor > 20 ? 'broken' : 'working'
        ]
    }),
    listeners: ({ actions, values }) => ({
        [actions.setFloor]: ({ floor }) => {
            console.log('set floor to:', floor)
            
            if (values.systemState === 'broken') {
                console.log('you broke the system!')
            }
        }
    })
})

In Kea 2.0 we can skip [actions.] and { actions }:

const logic = kea({
    actions: () => ({
        goUp: true,
        goDown: true,
        setFloor: floor => ({ floor })
    }),
    reducers: () => ({  // removed "{ actions }"
        floor: [1, {
            goUp: state => state + 1,  // removed "[actions.]"
            goDown: state => state - 1,  // removed "[actions.]"
            setFloor: (_, { floor }) => floor  // removed "[actions.]"
        }]
    }),
    selectors: ({ selectors }) => ({
        systemState: [
            () => [selectors.floor],
            floor => floor < 1 || floor > 20 ? 'broken' : 'working'
        ]
    }),
    listeners: ({ values }) => ({
        setFloor: ({ floor }) => { // changed
            console.log('set floor to:', floor)
            
            if (values.systemState === 'broken') {
                console.log('you broke the system!')
            }
        }
    })
})

You can still write [actions.] explicitly... and you do it mostly when using actions from another logic:

import { janitorLogic } from './janitorLogic'
 
const elevatorLogic = kea({
    reducers: ({ actions }) => ({
        floor: [1, {
            goUp: state => state + 1,  // local action
            [actions.goDown]: state => state - 1,  // no longer useful
            [janitorLogic.actions.setFloor]: (_, { floor }) => floor
        }]
    }),
})

... but you save 41 keystrokes in the default case:

"{ actions }[actions.][actions.][actions.]"  // byebye

Changed in Kea 2.1:​

Why stop there?

There's another low hanging fruit we can eliminate: () => ({}).

Gone!

const logic = kea({
    actions: {  // removed "() => ("
        goUp: true,
        goDown: true,
        setFloor: floor => ({ floor })
    },  // removed ")"
    reducers: {  // removed "() => ("
        floor: [1, {
            goUp: state => state + 1,
            goDown: state => state - 1,
            setFloor: (_, { floor }) => floor
        }]
    },  // removed ")"
    selectors: ({ selectors }) => ({
        systemState: [
            () => [selectors.floor],
            floor => floor < 1 || floor > 20 ? 'broken' : 'working'
        ]
    }),
    listeners: ({ values }) => ({
        setFloor: ({ floor }) => {
            console.log('set floor to:', floor)
            
            if (values.systemState === 'broken') {
                console.log('you broke the system!')
            }
        }
    })
})

16 units of squiggly bits gone! Here they are, in chronological and ascending order:

"() => ()() => ()" // chronological
"    (((())))==>>" // ascending

They are there if you need them, of course. For example when using props in reducers:

kea({
    reducers: ({ props }) => ({
        floor: [props.defaultFloor, {
            goUp: state => state + 1,
            goDown: state => state - 1,
        }]
    }),
})

What about the selectors? How can we simplify this?

kea({
    selectors: ({ selectors }) => ({
        systemState: [
            () => [selectors.floor],
            floor => floor < 1 || floor > 20 ? 'broken' : 'working'
        ]
    })
})

Here's the simplest backwards-compatible change that went into Kea 2.1:

kea({
    selectors: {  // spot
        systemState: [
            selectors => [selectors.floor],  // the
            floor => floor < 1 || floor > 20 ? 'broken' : 'working'
        ]
    } // difference
})

Goodbye another 14 spaces and squgglies:

"({  }) => ()()"

If you're really feeling the minimalist vibe, you could also simplify the object in listeners and events, but:

const elevatorLogic = kea({
    listeners: {
        setFloor: ({ floor }) => {
            console.log('set floor to:', floor)
 
            if (elevatorLogic.values.systemState === 'broken') {
                console.log('you broke the system!')
            }
        }
    }
})

You might get tired of writing thisLogic everywhere.

In general, the suggestion is to always write the simplest thing first:

kea({
    reducers: {
        poteito: // ...
    }
})

... and only when needed, extend it into a function to pull in objects and evaluate lazily:

kea({
    reducers: ({ props }) => ({
        potaato: // ...
    })
})

Previous State in Listeners​

There's a certain way listeners work:

kea({
    actions: {
        setFloor: floor => ({ floor })
    },
    reducers: {
        floor: {
            setFloor: (_, { floor }) => floor
        }
    },
    listeners: ({ values }) => ({
        setFloor: ({ floor }, breakpoint, action) => {
            // { floor } = payload of the action          
            // breakpoint = some cool stuff ;)
            // action = the full redux action, in case you need it

            console.log("floor in action payload: ", floor)
            console.log("floor in state: ", values.floor)

            if (floor === values.floor) {  // this is true
                console.log('the reducer already ran')
                console.log('before the listener started')
            }
        }
    }),
)

The action will first update the reducers and only then run the listener.

What if you really need the state before the action ran?

You could set up a two step system (setFloorStart & setFloorUpdate) ... or you could use previousState, the new 4th argument to listeners:

kea({
    actions: {
        setFloor: floor => ({ floor })
    },
    reducers: {
        floor: {
            setFloor: (_, { floor }) => floor
        }
    },
    listeners: ({ selectors, values }) => ({
        setFloor: ({ floor }, _, __, previousState) => {
            // { floor } = payload          
            // _ = breakpoint
            // __ = action
            // previousState = the state of the store before the action

            const lastFloor = selectors.floor(previousState)
   
            if (floor < lastFloor) {
                console.log('going down!')
            }
            if (floor > lastFloor) {
                console.log('going up!')
            }
        }
    }),
)

Take the store's previousState (new 4th argument) and run it through any selector you can get your hands on. Every value has a selector, so you have plenty to choose from.

Few more things got released all at once:

Funny Gists​

I added a playground page with three interesting code snippets for Kea:

• A quick Kea GraphQL client
• A plugin to measure the window's dimensions
• A rough sketch of the Kea DevTools

They are all too rough to be released as official plugins yet, but can already help in some situations.

If you have the time, feel free to contribute new gists or improve on the existing ones!

WaitFor​

The kea-waitfor plugin lets you await for actions.

It's great if you're writing tests and want to wait for something to happen before leaving the test

import { kea } from 'kea'
import { waitForAction } from 'kea-waitfor'

const logic = kea({
    actions: () => ({
        setValue: value => ({ value }),
        valueWasSet: value => ({ value })
    }),
    
    listeners: ({ actions }) => ({
        setValue: async ({ value }) => {
            await delay(300)
            actions.valueWasSet(value)
        }
    })
})

logic.mount()
logic.actions.setValue('hamburger')
const { value } = await waitForAction(logic.actions.valueWasSet)

console.log(value) 
// --> 'hamburger'

There's also a waitForCondition that lets you ask custom questions from the dispatched actions.

const { value } = await waitForCondition(action => {
    return action.type === logic.actions.valueWasSet.toString() && 
           action.payload.value === 'cheeseburger'
})

In addition, the plugin documentation includes examples for waiting for different cominations of actions:

• Wait for all to be dispatched
• Wait for the first one of many (race)
• Timeout on the waiting

Testing docs​

Inspired by a Github Issue, I wrote a quick doc about unit testing kea logic. Feedback and contributions are very welcome!

8 months after the release of Kea 1.0 I'm proud to announce version 2.0!

This version brings several convenience features. It's a rather small release, yet there were a few breaking changes, which warranted a new major version.

What changed? Read below!

But first! You are reading this blog post in the brand new documentation for Kea! Powered by docusaurus v2! Over 17000 new words were written for these docs in an effort to really clarify how Kea works.

Start with What is Kea? if you're new here. Then head on to the core concepts. Please also read them if you've been using Kea for a while. You might learn something you didn't know! Then check out additional concepts, debugging and other pages for more.

Anyway, where were we?

Oh yes, new stuff in Kea 2.0! 🤩

Listeners built in (1 Breaking Change)​

For years Kea has supported two different side effect libraries: sagas and thunks.

With Kea 1.0, I added a new lightweight one called listeners.

Listeners solve the main issue with thunks (you can't use thunks in reducers) and let you write much simpler code than sagas, while retaining the most commonly used features of sagas (debouncing and cancelling workers a'la takeLatest). Unless you're writing highly interactive applications, you will probably not need to use sagas anymore.

Before 2.0 listeners was an optional plugin, but now it's included by default. This enables two big things:

• Much easier to get started with Kea
• Plugin authors have a side-effect library that they can always rely on instead of writing bindings for 3 different systems.

Weighing at just 1.4KB (gzipped, 3.4KG minified), including listeners in kea doesn't add a lot of weight.

Yet if you wish to disable them, use skipPlugins when upgrading:

resetContext({ skipPlugins: ['listeners'] })

Breaking change, please note: If you were using listeners with Kea 1.0, make sure to remove listenersPlugin from your resetContext({ plugins: [] }) array or Kea will complain that it's being imported twice.

Writing [actions. and ] is now optional​

This used to be the only way to write reducers and listeners:

// Works in all versions of Kea
const logic = kea({
    actions: () => ({
        increment: (amount) => ({ amount }),
        setCounter: (counter) => ({ counter }),
        reset: true
    }),
    reducers: ({ actions }) => ({
        counter: [0, { 
            [actions.increment]: (state, { amount }) => state + amount,
            [actions.setCounter]: (_, { counter }) => counter,
            [actions.reset]: () => 0
        }]
    }),
    listeners: ({ actions }) => ({
        [actions.reset]: () => {
            console.log('reset called')
        }
    })
})

Now you can do this:

// Works with Kea 2.0+
const logic = kea({
    actions: () => ({
        increment: (amount) => ({ amount }),
        setCounter: (counter) => ({ counter }),
        reset: true
    }),
    reducers: () => ({
        counter: [0, { 
            increment: (state, { amount }) => state + amount,
            setCounter: (_, { counter }) => counter,
            reset: () => 0
        }]
    }),
    listeners: () => ({
        reset: () => {  
            console.log('reset called')
        }
    })
})

If your actions are defined in the same logic (or imported with connect), you can skip writing [actions. ] and also skip ({ actions }).

Writing [actions.increment] will still work, just like writing [otherLogic.actions.actionName].

This will be especially nice for TypeScript users, who were forced to write [actions.increment as any] to avoid constantly bumping into "error TS2464: A computed property name must be of type 'string', 'number', 'symbol', or 'any'".

Auto-Connect!​

Up to Kea 1.0, when you used actions or values from otherLogic inside your logic, you had to connect them together.

import { counterLogic } from './counterLogic'

// Works in all versions of Kea
const logic = kea({
    connect: {
        // pulling in actions from `counterLogic`
        actions: [counterLogic, ['increment', 'decrement']],
        // pull in values from `counterLogic`
        values: [counterLogic, ['counter']],
    },

    listeners: ({ actions, values }) => ({
        [actions.increment]: () => {
            console.log('Increment called!')
            console.log(`Counter: ${values.counter}`)
        }
    })
})

Now you can skip connect (if you want to) and call all actions and values directly on counterLogic:

import { counterLogic } from './counterLogic'

// Works in Kea 2.0+
const logic = kea({
    listeners: () => ({
        [counterLogic.actions.increment]: () => {
            console.log('Increment called!')
            console.log(`Counter: ${counterLogic.values.counter}`)
        }
    })
})

While this also works in Kea 1.0 under some conditions, the code above will always work with Kea 2.0.

In version 1.0 you had to manually assure that counterLogic was mounted before calling actions and values on it. Perhaps it was mounted via useValues in React or alternatively you could also write: connect: { logic: [counterLogic] } without specifying what exactly to connect. The code above would then also work.

In version 2.0 this is no longer necessary. When you:

• use counterLogic.actions.increment as a key in reducers or listeners
• use counterLogic.selectors.counter in selectors
• use counterLogic.anything.really inside a listener

... then counterLogic is automatically connected to logic and mounted/unmounted when needed.

This means the following code will also work:

import { counterLogic } from './counterLogic'

// Works in Kea 2.0+
const logic = kea({
    actions: () => ({
        showCount: true
    }),
    listeners: () => ({
        showCount: () => {
            console.log('Increment called!')
            console.log(`Counter: ${counterLogic.values.counter}`)
        }
    })
})

In this example, the first time you use counterLogic is inside a listener when getting a value from it.

If counterLogic was not already mounted, it will be mounted directly when you call showCount. It will stay mounted for as long as logic is still mounted. It will be unmounted together with logic in case no other mounted logic or component has a lock on it.

There is one caveat with autoConnect for when you want to manually call mount() and unmount() inside a listener. For that please read the section in the Using without React page.

To opt out of autoConnect, pass autoConnect: false to resetContext.

(Optional) Babel plugin to autogenerate paths​

If you have ever used the redux devtools, to debug your logic, you will have noticed that unless you specify a path in your logic, it will be automatically placed under kea.inline.[N] like so:

With the new babel-plugin-kea, these paths can be autogenerated from the filesystem, greatly enhancing your debugging experience:

What's more, this can be used in combination with plugins like kea-localstorage or in frameworks like next.js to persist values or hydrate server-rendered logic easier than ever before.

Other smaller improvements​

Those were the big ones. A few other things made it into Kea 2.0.

You can extend reducers​

Previously in this case:

// Works with Kea 1.0
const logic = kea({
    actions: () => ({
        doSomething: true,
        doSomethingMore: true,
    }),
    reducers: ({ actions }) => ({
        myValue: [0, {
            [actions.doSomething]: () => 100
        }]
    })
}) 
logic.extend({
    reducers: ({ actions }) => ({
        myValue: [0, {
            [actions.doSomethingMore]: () => 10000
        }]
    })
}) 

The entire reducer for myValue would be overridden. This means only the action doSomethingMore would have any effect on the value. This is no longer the case and the reducer mapping is merged when a reducer is extended.

In case of conflicts, later actions override previously defined ones. However the first default value is taken. To override a default, just specify it separately with defaults: { myValue: 100 } within kea({})

In resetContext, createStore is now true by default​

Previously when using resetContext and not using any other redux-specific middleware or libraries, you had to write:

// Works with all versions of Kea, but not needed in 2.0
resetContext({
    createStore: true // or {}
})

Omitting this createStore: true line would cause Kea to fail. This is no longer necessary. The redux store will be created when you call resetContext without any arguments. Pass false to createStore if you wish to avoid this.

The path in your logic can start with anything​

Previously you had to write:

// Works with all versions of Kea, but not needed in 2.0
resetContext({
    createStore: {
        // defaulted to ['kea', 'scenes']
        paths: ['kea', 'scenes', 'pages', 'components']
    }
})

... if you wanted your logic.path to start with pages or anything other than kea or scenes. The first part of the path had to be whitelisted.

This is no longer necessary. If you omit paths in createStore, you can use whatever string for the first part of your logic's path.

Specifying paths reverts to whitelisting and anything else is disallowed. Only now it will also throw an error instead of silently just not connecting the logic to redux.

Create a reducer without a default​

This used to be the only way to define reducers:

const counterLogic = kea({
    actions: () => ({
        increment: true,
        decrement: true,
    }),

    reducers: ({ actions }) => ({
        counter: [0, { // `0` as default
            [actions.increment]: (state) => state + 1,
            [actions.decrement]: (state) => state - 1
        }]
    })
})

Now if you prefer, you can omit the default value in reducers:

const counterLogic = kea({
    actions: () => ({
        increment: true,
        decrement: true,
    }),

    reducers: () => ({
        counter: { // `null` as default if not given in `defaults`
            increment: (state) => (state || 0) + 1,
            decrement: (state) => (state || 0) - 1
        }
    })
})

... and either define it in defaults or not at all. It'll just be null if not defined.

Action type string no longer skips scenes.​

This is a very minor tweak.

Previously if your action had a path that started with scenes, then it was skipped in the action type toString().

// before
homepageLogic.path == ['scenes', 'homepage', 'index']
homepageLogic.action.reloadPage.toString() === 'reload page (homepage.index)'

accountLogic.path == ['menu', 'account', 'index']
accountLogic.action.reloadAccount.toString() === 'reload account (menu.account.index)'

Now it's included:

// after
homepageLogic.path == ['scenes', 'homepage', 'index']
homepageLogic.action.reloadPage.toString() === 'reload page (scenes.homepage.index)'

accountLogic.path == ['menu', 'account', 'index']
accountLogic.action.reloadAccount.toString() === 'reload account (menu.account.index)'

I told you this was a very minor tweak!

That's it for new stuff in Kea 2.0. Please let me know what is your favourite new feature or if you have anything else to share! 👋

What's next? (Kea 2.1 and/or 3.0)​

There are two main things I'd like to explore in the next versions of Kea.

TypeScript support​

One of the most requested features for Kea has been proper TypeScript support. While you can get pretty far with Kea in TS if you manually create your interfaces, this is sub-optimal.

The goal for Kea 2.1 (or 3.0?) is to have full and automatic TypeScript support. In fact, many of the changes with 2.0 (namely eliminating the need for connect & no need to write [actions.__]) were done to pave the way.

Even if you don't use TypeScript, this will help IDEs offer proper autocomplete support when writing Kea in regular JavaScript.

Precomplication​

At the end of the day, Kea is just an engine that converts input into logic plus a framework to mount/unmount this logic when requested by React components.

What if we could do some of this conversion at compile-time, rather than at runtime?

Now that we have a babel plugin that automatically adds paths to logic, could this be extended to speed up runtime Kea by inlining some of these conversions where possible? Would it make a difference in runtime speed?

Kea's performance has never been an issue so far, but this is an interesting avenue for some exploration.

To be continued.