Git Product home page Git Product logo

unistore's Introduction

unistore
npm travis

unistore

A tiny 350b centralized state container with component bindings for Preact & React.

  • Small footprint complements Preact nicely (unistore + unistore/preact is ~650b)
  • Familiar names and ideas from Redux-like libraries
  • Useful data selectors to extract properties from state
  • Portable actions can be moved into a common place and imported
  • Functional actions are just reducers
  • NEW: seamlessly run Unistore in a worker via Stockroom

Table of Contents

Install

This project uses node and npm. Go check them out if you don't have them locally installed.

npm install --save unistore

Then with a module bundler like webpack or rollup, use as you would anything else:

// The store:
import createStore from 'unistore'

// Preact integration
import { Provider, connect } from 'unistore/preact'

// React integration
import { Provider, connect } from 'unistore/react'

Alternatively, you can import the "full" build for each, which includes both createStore and the integration for your library of choice:

import { createStore, Provider, connect } from 'unistore/full/preact'

The UMD build is also available on unpkg:

<!-- just unistore(): -->
<script src="https://unpkg.com/unistore/dist/unistore.umd.js"></script>
<!-- for preact -->
<script src="https://unpkg.com/unistore/full/preact.umd.js"></script>
<!-- for react -->
<script src="https://unpkg.com/unistore/full/react.umd.js"></script>

You can find the library on window.unistore.

Usage

import createStore from 'unistore'
import { Provider, connect } from 'unistore/preact'

let store = createStore({ count: 0, stuff: [] })

let actions = {
  // Actions can just return a state update:
  increment(state) {
    // The returned object will be merged into the current state
    return { count: state.count+1 }
  },

  // The above example as an Arrow Function:
  increment2: ({ count }) => ({ count: count+1 }),

  // Actions receive current state as first parameter and any other params next
  // See the "Increment by 10"-button below
  incrementBy: ({ count }, incrementAmount) => {
    return { count: count+incrementAmount }
  },
}

// If actions is a function, it gets passed the store:
let actionFunctions = store => ({
  // Async actions can be pure async/promise functions:
  async getStuff(state) {
    const res = await fetch('/foo.json')
    return { stuff: await res.json() }
  },

  // ... or just actions that call store.setState() later:
  clearOutStuff(state) {
    setTimeout(() => {
      store.setState({ stuff: [] }) // clear 'stuff' after 1 second
    }, 1000)
  }

  // Remember that the state passed to the action function could be stale after
  // doing async work, so use getState() instead:
  async incrementAfterStuff(state) {
    const res = await fetch('foo.json')
    const resJson = await res.json()
    // the variable 'state' above could now be old,
    // better get a new one from the store
    const upToDateState = store.getState()

    return {
      stuff: resJson,
      count: upToDateState.count + resJson.length,
    }
  }
})

// Connecting a react/preact component to get current state and to bind actions
const App1 = connect('count', actions)(
  ({ count, increment, incrementBy }) => (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
      <button onClick={() => incrementBy(10)}>Increment by 10</button>
    </div>
  )
)

// First argument to connect can also be a string, array or function while
// second argument can be an object or a function. Here we pass an array and
// a function.
const App2 = connect(['count', 'stuff'], actionFunctions)(
  ({ count, stuff, getStuff, clearOutStuff, incrementAfterStuff }) => (
    <div>
      <p>Count: {count}</p>
      <p>Stuff:
        <ul>{stuff.map(s => (
         <li>{s.name}</li>
        ))}</ul>
      </p>
      <button onClick={getStuff}>Get some stuff!</button>
      <button onClick={clearOutStuff}>Remove all stuff!</button>
      <button onClick={incrementAfterStuff}>Get and count stuff!</button>
    </div>
  )
)

export const getApp1 = () => (
  <Provider store={store}>
    <App1 />
  </Provider>
)

export const getApp2 = () => (
  <Provider store={store}>
    <App2 />
  </Provider>
)

Debug

Make sure to have Redux devtools extension previously installed.

import createStore from 'unistore'
import devtools    from 'unistore/devtools'

let initialState = { count: 0 };
let store = process.env.NODE_ENV === 'production' ?  createStore(initialState) : devtools(createStore(initialState));

// ...

Examples

README Example on CodeSandbox

API

createStore

Creates a new store, which is a tiny evented state container.

Parameters

  • state Object Optional initial state (optional, default {})

Examples

let store = createStore();
store.subscribe( state => console.log(state) );
store.setState({ a: 'b' });   // logs { a: 'b' }
store.setState({ c: 'd' });   // logs { a: 'b', c: 'd' }

Returns store

store

An observable state container, returned from createStore

action

Create a bound copy of the given action function. The bound returned function invokes action() and persists the result back to the store. If the return value of action is a Promise, the resolved value will be used as state.

Parameters

  • action Function An action of the form action(state, ...args) -> stateUpdate

Returns Function boundAction()

setState

Apply a partial state object to the current state, invoking registered listeners.

Parameters

  • update Object An object with properties to be merged into state
  • overwrite Boolean If true, update will replace state instead of being merged into it (optional, default false)
subscribe

Register a listener function to be called whenever state is changed. Returns an unsubscribe() function.

Parameters

  • listener Function A function to call when state changes. Gets passed the new state.

Returns Function unsubscribe()

unsubscribe

Remove a previously-registered listener function.

Parameters

  • listener Function The callback previously passed to subscribe() that should be removed.
getState

Retrieve the current state object.

Returns Object state

connect

Wire a component up to the store. Passes state as props, re-renders on change.

Parameters

  • mapStateToProps (Function | Array | String) A function mapping of store state to prop values, or an array/CSV of properties to map.
  • actions (Function | Object)? Action functions (pure state mappings), or a factory returning them. Every action function gets current state as the first parameter and any other params next

Examples

const Foo = connect('foo,bar')( ({ foo, bar }) => <div /> )
const actions = { someAction }
const Foo = connect('foo,bar', actions)( ({ foo, bar, someAction }) => <div /> )

Returns Component ConnectedComponent

Provider

Extends Component

Provider exposes a store (passed as props.store) into context.

Generally, an entire application is wrapped in a single <Provider> at the root.

Parameters

  • props Object
    • props.store Store A {Store} instance to expose via context.

Reporting Issues

Found a problem? Want a new feature? First of all, see if your issue or idea has already been reported. If not, just open a new clear and descriptive issue.

License

MIT License ยฉ Jason Miller

unistore's People

Contributors

developit avatar namankheterpal avatar vincentaudebert avatar heldr avatar kokjinsam avatar eduardoborges avatar marvinhagemeister avatar kadmil avatar solarliner avatar goblindegook avatar srph avatar joseluisq avatar cfenzo avatar metonym avatar notpushkin avatar 38elements avatar ouzhenkun avatar cj avatar wuweiweiwu avatar tbroadley avatar smably avatar pmkroeker avatar mathiasbynens avatar timer avatar jaredpalmer avatar jakearchibald avatar farskid avatar danielrosenwasser avatar dan-lee avatar iamclaytonray avatar

Watchers

James Cloos avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.