Skip to content
/ amnis Public

πŸ”° Minimal yet complete state and effect management solution for JavaScript applications

Notifications You must be signed in to change notification settings

pshev/amnis

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

11 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Minimal yet complete state and effect management solution

✨ Features:

  • Tiny in size.
  • Complete. Handles both state and effects
  • Redux pattern
  • Familiar interface

πŸ’‘ Motivation

Redux is great. But out of the box it only deals with synchronous actions.
We know of a great way to model asynchronous actions - that is with Observables. That is exactly what redux-observable does. But it turns out that if you are armed with observables you can model the whole redux pattern in pretty much one line of code:

// pseudo code
const state$ = action$
  .scan(rootReducer, initialState)

This is not a new idea and many different proposals have been made that replace redux with something like rxjs. However they usually require you to completely change the way you write your redux applications. For example you would have to write actions and reducers as observables, while they are better of staying as pure simple functions. Those approaches are also usually tied to a specific observable library, like rxjs which introduces bloat into your application.

With amnis you get to write your redux applications like you're used to. Except without redux. Create your store, actions, and reducers like you always have. But then use any observable library where it makes sense - for effect management. Better yet, you get all of that in 1.7KB gzipped.

πŸ”§ Installation

Assuming you use npm as your package manager:

npm install --save amnis

Then you can use it from Node environment or if you are building for the browser you can use a module bundler like Webpack, Browserify, or Rollup.

If you want to experiment and play around with Amnis without a module bundler or you don't use one - that's OK. Amnis npm package includes precompiled production and development UMD builds. You can just drop a UMD build as a <script> tag on a page. The UMD builds make amnis available as a window.amnis.

πŸ”¨ Usage

First, let's look at an example that doesn't use effects.

Counter

You start by creating a reducer function just like you would in redux:

export function counter(state = 0, action) {
  switch (action.type) {
    case 'INCREMENT':
      return state + 1
    case 'DECREMENT':
      return state - 1
    default:
      return state
  }
}

Then you create a store
createStore accepts the rootReducer and an optional initialState parameter.
There is no concept of middleware in Amnis since there is no need for it.

import {createStore} from 'amnis'
import {counter} from './counter'

const store = createStore(counter)

It returns an object with 3 properties:
state$ - an observable of states
action$ - an observable of actions dispatched
dispatch - a function to call to dispatch new actions
Now we can dispatch actions, subscribe to actions being dispatched, and get notified of every state change.

store.state$.subscribe(state => console.log(state))
store.action$.subscribe(action => console.log(action))

store.dispatch({type: 'INCREMENT'})
store.dispatch({type: 'INCREMENT'})
store.dispatch({type: 'DECREMENT'})

Now let's see how we manage effects.

Effects example

Things to note here:
First - reducer is not relevant for this example.
Second - we use stream-lite library to work with observables but you don't have to.

 import {createStore, runEffects} from 'amnis'
 import {filter, tap, switchMap, mapTo} from 'stream-lite/operators'
 import {never} from 'stream-lite/statics'
  
 const logAll = action$ => action$.pipe(
	 tap(console.log),
	 switchMap(never),
 )
 
 const pong = action$ => action$.pipe(
	 filter(a => a.type === 'PING'),
	 mapTo(({type: 'PONG'})),
 )
 
 const rootReducer = (state, action) => 'irrelevant'
 
 const store = createStore(rootReducer)

runEffects({
  store,  
  effects: [logAll, pong]
})
 
 store.dispatch({type: 'PING'})

πŸš€ Choose your own observable library

Internally amnis uses stream-lite. Mostly because it's core is only about 1KB, but also because of it's RxJS-like interface and support for pipeable operators.
But you can use any observable library that you want!
The observables that Amnis returns implement a [Symbol.observable] method as per Observable proposal specification.
All you need to do is supply runEffects with a function it can use to convert a standard observable to an observable of your favorite library:

import {from} from 'rxjs/observable/from'

runEffects({  
  store,  
  effects: [logAll, pong],  
  adapter: from
})

πŸ““ Examples

Stay tuned. Examples are coming.

πŸ™ License

MIT

About

πŸ”° Minimal yet complete state and effect management solution for JavaScript applications

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published