lenrix v0.10.0-alpha.18

lenrix

🔎 + Redux + RxJS + TypeScript = ❤️

Table of Contents

• Motivation
• Features
• Quickstart
  • Install
• API
  • Create
    • createStore()
    • createFocusableStore()
  • Actions and Updates
    • actionTypes()
    • updates()
    • dispatch()
    • action()
  • Consuming the state
    • state$
    • currentState
    • pluck()
    • pick()
    • cherryPick()
  • Focus
    • focusPath()
    • focusFields()
    • recompose()
    • Passing fields as readonly values
  • Computed values (synchronous)
    • computeFromField()
    • computeFromFields()
    • computeFrom()
  • Computed values (asynchronous)
    • compute$()
    • computeFromField$()
    • computeFromFields$()
    • computeFrom$()
    • defaultValues()
  • epics()
  • pureEpics()
  • sideEffects()
  • Injected store
• Testing
  • Test Setup
    • Root store
  • Asserting state
  • Asserting calls on dependencies
  • Asserting dispatched actions
• Logger

Motivation

A lot of people have complained about redux, some with good reason. Many have been drawn to other state management solutions.

Don't throw the baby with the bathwater.

Although we agree there must be a better way than classical redux, we are not willing to sacrifice all of the redux goodness you've heard so much about.

Making redux great again !

lenrix is a redux store wrapper that :

• Dramatically reduces boilerplate
• Eliminates the need for thunky middleware and selector libraries
• Makes no compromise on type-safety
• Embraces reactive programming
• Prevents unnecessary re-rendering

Features

• Declarative API for deep state manipulation, powered by immutable-lens
• Reactive state and selectors, powered by rxjs
• Relevant reference equality checks performed out of the box
• Separate functional slices with Focused Stores
• Epics, just like redux-observable, our favorite redux middleware

Quickstart

Install

npm install --save lenrix redux rxjs immutable-lens

rootStore.ts

import { createStore } from 'lenrix'

const initialRootState = {
   message: ''
}

export const rootStore = createStore(initialRootState)
      .actionTypes<{ // DECLARE ACTION AND PAYLOAD TYPES
         setMessage: string
      }>()
      .updates({ // REGISTER UPDATES (~= CURRIED REDUCERS)
         setMessage: (message) => (state) => ({...state, message})
      }))

storeConsumer.ts

import { rootStore } from './rootStore'

const message$ = rootStore.pluck('message') // Observable<string>
const slice$ = rootStore.pick('message') // Observable<{message: string}>

rootStore.dispatch({ setMessage: 'Hello !!!' })

API

Create

createStore()

import { createStore } from 'lenrix'

const rootStore = createStore({
   user: {
      id: 123,
      name: 'John Doe'
   }
})

createFocusableStore()

Provides the same API as createStore() from redux.

import {createFocusableStore} from 'lenrix'

const initialRootState = { ... }

export type RootState = typeof initialRootState

export const store = createFocusableStore(
   (state: RootState) => state, // You can use your old redux reducer here
   initialRootState,
   (window as any).__REDUX_DEVTOOLS_EXTENSION__ && (window as any).__REDUX_DEVTOOLS_EXTENSION__()
)

Actions and Updates

actionTypes()

Declare the store's actions and associated payload types. Calling this method will have absolutely no runtime effect, all it does is provide information to the TypeScript compiler.

const store = createStore({ name: 'Bob' }).actionTypes<{
   setName: string
}>()

updates()

Once action types are defined, it is possible to register type-safe updates. See immutable-lens for lens API documentation.

const store = createStore({ name: 'Bob' })
   .actionTypes<{ setName: string }>()
   // THESE FOUR CALLS TO updates() ARE ALL EQUIVALENT AND 100% TYPE SAFE
   // PICK THE ONE YOU PREFER
   .updates({
      setName: name => state => ({ ...state, name })
   })
   .updates(lens => ({
      setName: name => lens.setFields({ name })
   }))
   .updates(lens => ({
      setName: name => lens.focusPath('name').setValue(name)
   }))
   // And if really like curry...
   .updates(lens => ({
      setName: lens.focusPath('name').setValue()
   }))

Only ONE updater can be registered for a single action type. Failing to comply with that rule will result in an error:

Error: Cannot register two updaters for the same action type

When an action needs to update the state at a wider scope, move your updater to a store that has larger focus.

dispatch()

Dispatching an action can trigger an update, an epic, or a side effect.

store.dispatch({ setName: 'John' }) // Next state will be : {name: 'John'}

action()

Create an action dispatcher, which can be handily used in a React component for example.

const setName = store.action('setName')
setName('John') // Same as store.dispatch({setName: 'John'})

Consuming the state

lenrix performs reference equality checks to prevent any unnecessary re-rendering.

The store provides the properties state$ and currentState. However, we recommend you to use either pluck(), pick() or cherryPick() to select as little data as necessary. It will prevent components to re-render because an irrelevant slice of the state has changed.

state$

The store's normalized state augmented with its readonly values.

const store = createStore({ name: 'Bob' })

store.state$ // Observable<{name: string}>

currentState

Handy for testing.

const store = createStore({ name: 'Bob' })

store.currentState.name // 'Bob'

pluck()

Conceptually equivalent to focusPath(...).state$

const rootStore = createStore({
   user: {
      name: 'Bob'
   }
})

const userName$ = rootStore.pluck('user', 'name') // Observable<string>

pick()

Conceptually equivalent to focusFields().state$

const rootStore = createStore({
   counter: 0,
   user: 'Bob',
   todoList: ['Write README']
})

const pick$ = rootStore.pick('user', 'todoList') // Observable<{ user: string, todoList: string[] }>

cherryPick()

Conceptually equivalent to recompose().state$. See immutable-lens for lens API documentation.

const rootStore = createStore({
   counter: 0,
   user: {
      name: 'Bob'
   }
})

const cherryPick$ = rootStore.cherryPick(lens => ({
   // immutable-lens
   counter: lens.focusPath('counter'),
   userName: lens.focusPath('user', 'name')
})) // Observable<{ counter: number, userName: string }>

Focus

A focused store is just a proxy for the root store; there always is a single source of truth.

Most UI components only interact with a small part of the whole state tree. A focused store provides read and update access to a precise subset of the full state.

Typically, you will create a focused store for a specific page (1st level routable component). Then, if the page is functionnally rich, more stores can be derived from the page-focused store. These deep-focused stores will probably be tailored for specific components or groups of components within the page.

All these stores form a tree of stores, with the one returned by createStore() at its root. All dispatched actions are propagated to the root store, where updates are applied. The updated state then flows down the tree of stores, with values computed at some of the nodes and made available to their children.

However, that propagation stops at the stores for which the state slice in their scope has not changed.

focusPath()

const rootStore = createStore({
   user: {
      id: 123,
      name: 'John Doe'
   }
})

const userStore = rootStore.focusPath('user')
const userNameStore = userStore.focusPath('name')
// OR
const userNameStore = rootStore.focusPath('user', 'name')

userNameStore.state$ // Observable<string>

focusFields()

const rootStore = createStore({
   counter: 0,
   username: 'Bob'
})

const counterStore = rootStore.focusFields('counter')

counterStore.state$ // Observable<{counter: number}>

recompose()

Most powerful focus operator. It allows you to create state representations composed of deep properties from distinct state subtrees. See immutable-lens for lens API documentation.

const rootStore = createStore({
   a: {
      b: {
         c: {
            d: string
         }
      }
   },
   e: {
      f: {
         g: {
            h: string
         }
      }
   }
})

rootStore.recompose(lens => ({
   // immutable-lens
   d: lens.focusPath('a', 'b', 'c', 'd'),
   h: lens.focusPath('e', 'f', 'g', 'h')
})).state$ // Observable<{ d: string, h: string }>

Passing fields as readonly values

All three focus operators focusPath(), focusFields() and recompose() support passing fields as readonly values.

const rootStore = createStore({
   a: {
      b: {
         c: 'c'
      }
   },
   user: 'Bob'
})

const focusedStore = rootStore.focusPath(['a', 'b', 'c'], ['user'])
focusedStore.state$ // Observable<{ c: string, user: string }>

Note that in this example, updates registered on the focused store can't modify the user value

Computed values (synchronous)

State should be normalized, derived data should be declared as computed values. In traditional redux, you would probably use selectors for that.

lenrix performs reference equality checks to prevent unnecessary recomputation.

computeFromField()

Specify the field used for the computation to avoid useless re-computations.

createStore({ name: 'Bob', irrelevant: 'whatever' })
   .computeFromField('name', name => ({ message: 'Hello, ' + name }))
   .pick('message') // Observable<{message: string}>

computeFromFields()

Specify the fields used for the computation to avoid useless re-computations.

createStore({ name: 'Bob', irrelevant: 'whatever' })
   .computeFromFields(['name'], ({ name }) => ({ message: 'Hello, ' + name }))
   .pick('message') // Observable<{message: string}>

computeFrom()

Define computed values from state slices focused by lenses. The signature is similar to recompose() and cherryPick().

createStore({ name: 'Bob', irrelevant: 'whatever' })
   .computeFrom(
      lens => ({ name: lens.focusPath('name') }),
      ({ name }) => ({ message: 'Hello, ' + name })
   )
   .pick('message') // Observable<{message: string}>

Computed values (asynchronous)

Every synchronous value-computing operator has an asynchronous equivalent.

Note that asynchronously computed values are initially undefined. If you want them to be non-nullable, see defaultValues().

compute$()

import { map, pipe } from 'rxjs'

createStore({name: 'Bob'})
   .compute$(
      // WITH SINGLE OPERATOR...
      map(state => ({message: 'Hello, ' + state.name}))
      // ... OR WITH MULTIPLE OPERATORS
      pipe(
         map(state => state.name),
         map(name => ({message: 'Hello, ' + name}))
      )
   )
   .pick('message') // Observable<{message: string | undefined}>

computeFromField$()

import { map } from 'rxjs'

createStore({ name: 'Bob', irrelevant: 'whatever' })
   .computeFromField$(
      'name',
      map(name => ({ message: 'Hello, ' + name }))
   )
   .pick('message') // Observable<{message: string | undefined}>

computeFromFields$()

import { map } from 'rxjs'

createStore({ name: 'Bob', irrelevant: 'whatever' })
   .computeFromFields$(
      ['name'],
      map(({ name }) => ({ message: 'Hello, ' + name }))
   )
   .pick('message') // Observable<{message: string | undefined}>

computeFrom$()

import { map } from 'rxjs'

createStore({name: 'Bob', irrelevant: 'whatever'})
   .computeFrom$(
      lens => ({name: lens.focusPath('name')}),
      map(({name}) => ({message: 'Hello, ' + name}))
   .pick('message') // Observable<{message: string | undefined}>

defaultValues()

Define defaults for read-only values.

import { map } from 'rxjs'

createStore({ name: 'Bob' })
   .compute$(map(({ name }) => ({ message: 'Hello, ' + name })))
   .defaultValues({
      message: ''
   })
   .pick('message') // Observable<{message: string}>

epics()

Let an action dispatch another action, asynchronously. Since this feature is heavily inspired from redux-observable, we encourage you to go check their documentation.

import { pipe } from 'rxjs'
import { map } from 'rxjs'

createStore({name: '', message: ''})
   .actionTypes<{
      setName: string
      setMessage: string
   }>()
   .updates(lens => ({
      setName: name => lens.setFields({name}),
      setMessage: message => lens.setFields({message})
   }))
   .epics(store => ({
      // WITH SINGLE OPERATOR...
      setName: map(name => ({setMessage: 'Hello, ' + name}))
      // ... OR WITH MULTIPLE OPERATORS
      setName: pipe(
         map(name => 'Hello, ' + name),
         map(message => ({setMessage: message}))
      )
   }))

pureEpics()

Same as epics(), without the injected store instance.

...
   .pureEpics({
      setName: map(name => ({setMessage: 'Hello, ' + name}))
   })

sideEffects()

Declare synchronous side effects to be executed in response to actions. Useful for pushing to browser history, stuff like that...

createStore({ name: '' })
   .actionTypes<{
      setName: string
   }>()
   .updates(lens => ({
      setName: name => lens.setFields({ name })
   }))
   .sideEffects({
      setName: name => console.log(name)
   })

Injected store

A light version of the store is made available when using the following operators :

• compute$()
• computeFrom$()
• computeFromFields$()
• epics()
• sideEffects()

import { map } from 'rxjs'

createStore({ name: '', greeting: '' })
   .actionTypes<{
      setName: string
      setGreeting: string
   }>()
   .updates(lens => ({
      setName: name => lens.setFields({ name }),
      setGreeting: greeting => lens.setFields({ greeting })
   }))
   .epics(store => ({
      setName: map(() => ({ setGreeting: store.currentState.name }))
   }))

Testing

Testing an action creator, a reducer and a selector in isolation.

"Looks like it’s working !"

Testing in redux usually implies testing in isolation the pieces that together form the application's state management system. It seems reasonable, since they are supposed to be pure functions.

Testing in lenrix follows a different approach. Well, technically, in most cases it would still be possible to write tests the redux way, but that's not what we had in mind when we designed it.

A lenrix store is to be considered a cohesive unit of functionality. We want to test it as a whole, by interacting with its public API. We do not want to test its internal implementation details.

As a consequence, we believe store testing should essentially consist in :

• Dispatching actions
• Asserting state (normalized state + computed values)

In some less frequent cases, testing might also consist in :

• Asserting calls on dependencies
• Asserting dispatched actions

Test Setup

Each test should run in isolation, therefore we need to create a new store for each test. The most straightforward way is to wrap all store creation code in factory functions.

Root store

RootStore.ts

import { createStore } from 'lenrix'

export const initialRootState = {
   user: {
      name: ''
   }
}

export type RootState = typeof initialRootState

export const createRootStore = (initialState = initialRootState) =>
   createStore(initialState)

export type RootStore = ReturnType<typeof createRootStore>

RootStore.spec.ts

import 'jest'
import { createRootStore, RootStore } from './RootStore'

describe('RootStore', () => {
   let store: RootStore

   beforeEach(() => {
      store = createRootStore()
   })
})

Asserting state

Most tests should limit themselves to dispatching actions and verifying that the state has correctly updated.

The distinction between normalized state and readonly values should be kept hidden as an implementation detail. Tests should not make assumptions about a value being either readonly or part of the normalized state, as it is subject to change without breaking public API nor general behavior.

RootStore.ts

import { createStore } from 'lenrix'

export const createRootStore = (initialState = { name: '' }) =>
   createStore(initialState)
      .actionTypes<{
         setName: string
      }>()
      .updates(lens => ({
         setName: name => lens.setFields({ name })
      }))
      .compute(({ name }) => ({
         message: 'Hello, ' + name
      }))

export type RootStore = ReturnType<typeof createRootStore>

RootStore.spec.ts

import 'jest'
import { createRootStore, RootStore } from './RootStore'

describe('RootStore', () => {
   let store: RootStore

   beforeEach(() => {
      store = createRootStore()
   })

   test('updates name when "setName" dispatched', () => {
      store.dispatch({ setName: 'Bob' })

      expect(store.currentState.name).toEqual('Bob')
   })

   test('updates message when "setName" dispatched', () => {
      store.dispatch({ setName: 'Steve' })

      expect(store.currentState.message).toEqual('Hello, Steve')
   })
})

Asserting calls on dependencies

Asserting dispatched actions

Logger