lenrix

🔎 + Redux + RxJS + TypeScript = ❤️

Motivation
Features
Quickstart
- Install
API
Testing
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 you like double curry...
   .updates(lens => ({
      setName: lens.focusPath('name').setValue()
   }))

`dispatch()`

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

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

Consuming the state

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

The store provides the observable properties state$ and computedState$. 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$`

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

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

`computedState$`

Like state$, but the store's state is augmented with its computed values.

`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

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 component or group of components.

All focus operations return a full-fledged store. But remember that a focused store is just a proxy for the root store, there always is a single source of truth.

`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 }>

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.

`compute()`

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

`computeFromFields()`

Specify the fields used for the computation in order 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/operators'

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}>

`computeFromFields$()`

import { map } from 'rxjs/operators'

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

`computeFrom$()`

import { map } from 'rxjs/operators'

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

`defaultValues()`

Define default values for asynchronously computed values.

import { map } from 'rxjs/operators'

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/operators'

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

`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)
   })

`dependencies()`

The simplest dependency injection mechanism we could think of. Dependencies will be accessible in various operators. Those dependencies can then be overriden in test setups.

createStore({ name: '' })
   .dependencies({
      greeter: (name: string) => 'Hello, ' + name
   })

Injected `store` and `dependencies`

A light version of the store and its registered dependencies are available when using the following operators :

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

createStore({ name: '' })
   .dependencies({
      greeter: (name: string) => 'Hello, ' + name
   })
   .compute((state, store, {greeter}) => ({
      message: greeter(store.currentState.name)
   }))

import { mapTo } from 'rxjs/operators'

createStore({name: '', greeting: ''})
   .actionTypes<{
      setName: string
      setGreeting: string
   }>()
   .updates(lens => ({
      setName: name => lens.setFields({name}),
      setGreeting: greeting => lens.setFields({greeting})
   }))
   .dependencies({
      greeter: (name: string) => 'Hello, ' + name
   })
   .epics({
      setName: (payload$, store, {greeter}) => payload$.pipe(
         mapTo({setGreeting: greeter(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 :

Initializing state
Injecting dependencies (http, localStorage...)
Dispatching actions
Asserting state (normalized state + computed values)

In some cases, testing might also consist in :

Asserting dispatched actions
Asserting calls on dependencies

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: RootState = 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()
   })
})

Focused stores

Focused stores provide a way to separate your state management code into vertical, functional slices. Therefore, focused stores should be tested in isolation of their sibling stores. However, since a focused store explicitely depends on their parent store, the whole store's ascending hierarchy will be active, up to the root store.

UserStore.ts

import { createStore } from 'lenrix'
import { RootStore } from './RootStore'

export const createUserStore = (rootStore: RootStore) => rootStore.focusPath('user')

export type UserStore = ReturnType<typeof createUserStore>

UserStore.spec.ts

import 'jest'
import { createRootStore, initialRootState, RootStore } from './RootStore'
import { createUserStore, UserStore } from './UserStore'

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

   beforeEach(() => {
      const rootStore = createRootStore()
      store = createUserStore(rootStore)
   })
})

Asserting state

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

The distinction between normalized state and computed values should be kept hidden as an implementation detail. Tests should not make assumptions about a value being either computed 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')
   })
})

charjac/lenrix

lenrix

🔎 + Redux + RxJS + TypeScript = ❤️

Table of Contents

Motivation

Features

Quickstart

Install

API

Create

createStore()

createFocusableStore()

Actions and Updates

actionTypes()

updates()

dispatch()

Consuming the state

state$

computedState$

pluck()

pick()

cherryPick()

Focus

focusPath()

focusFields()

recompose()

Computed values (synchronous)

compute()

computeFromFields()

computeFrom()