npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

lenrix

v0.10.0-alpha.18

Published

Type-safe, reactive, lens-focused, immutable state management

Downloads

154

Readme

lenrix

🔎 + Redux + RxJS + TypeScript = ❤️

Table of Contents

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 :

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.

Man in three pieces. Legs running in place. Torso doing push-ups. Head reading.

"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 :

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

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