undb

Simple JSON in-memory auto-persistent database for server and client.

Features

• Simple JS object, no extraneous API
• Auto-persisted using on-change
• Saves to a json file on server, and uses localStorage in browser
• Works in browser, with React or Preact, or without

Note: Uses ES6 features (Proxy), use only where browser/env supports it

Install

npm i undb

Usage

const undb = require('undb')

const [db, onChange] = undb({
  path: './store.json', /* in node */
  path: 'namespace',    /* in browser */
  initial: {
    something: false
  }
})

onChange(() => {
  // Fires whenever db changes
})

API

undb

const undb = require('undb')

const [db, onChange] = undb(options)

• db Deeply observed JS object that triggers auto-save feature when modified

• onChange [fn] Called whenever db changes

• options

  • path [str] Path to use for persistence. Should be a filename on server, or a "namespace" on client

  • initial [obj] Initial database structure

  • clear [bool] Deletes all localstorage items except current path

  • debounce [num] Debounce onChange

  • before [bool] Make onChange fire before the value has been updated in db

  • read [fn=>obj] Intercept the read function. Must return a data object. fn is the default read function

  • write [cb=>null] Intercept the write function. Must call cb

  • onChange [obj] Options passed to on-change

link

const { link } = require('undb/common/utils')
const state1Tuple = undb(options)
const state2Tuple = undb(options)
link(state1Tuple, state2Tuple);

const { link } = require('undb/common/utils')
const [ state1, state2 ] = link({}, {});

const [state1, onChange, link] = undb(options)
const [state2] = link({})

• link [fn] Link 2 or more states. Changing one will change the other(s).

  • @param {...[state, onChange]|initial} Takes either the [state, onChange] tuple or an initial object to create a new reactive state object from.

  • @returns state[] Returns an array corresponding to the input arguments, each item either being the input [state] (from the tuple) or a newly created one.

Browser specific

connect

• connect [fn=>fn=>Component] Connects the onChange to a <Component> so that it re-renders whenever onChange is fired

const connect = require('undb/browser/connect')

const ReactiveComponent = connect(onChange)(<Component>)

useState

• useState [obj=>obj] React State Hook alternative that updates when state object is modified

const { useState } = require('undb/browser/hooks')

const state = useState({ counter: 0 })

createUseState

• createUseState [fn=>fn] Create a useState hook for existing state

const { createUseState } = require('undb/browser/hooks')

const [state, onChange] = undb(options)
const useState = createUseState(onChange)

Examples

Global persistent store

Note: Re-renders entire React App

• store.js

  const undb = require('undb')
  
  const [store, onChange] = undb({ path: 'my-app' })
  
  exports.store = store
  exports.onChange = onChange

• components/App.js

  const { store } = require('../store')
  
  module.exports = () => [
    <h1>Hello {store.name}!</h1>,
    <input onChange={e => store.name = e.target.value}>
  ]

• main.js

  const React = require('react')
  const { onChange } = require('./store')
  const App = require('./components/App')
  
  onChange(() => React.render(<App>))

Local volatile state

• components/App.js

  const undb = require('undb')
  const connect = require('undb/browser/connect')
  
  const [state, onChange] = undb()
  
  const App = () => [
    <h1>Hello {state.name}!</h1>,
    <input onInput={e => state.name = e.target.value}>
  ]
  
  module.exports = connect(onChange)(App)

• main.js

  const React = require('react')
  const App = require('./components/App')
  
  React.render(<App>)

React State Hook Alternative

• components/App.js

  const { useState } = require('undb/browser/hooks')
  
  const App = () => {
    const state = useState({ counter: 0 })
    return (
      <button onClick={ () => state.counter++ }>
        `You have pressed this button ${state.counter} times`
      </button>
    )
  }

Similar libraries

• unurl
• mobx
• react-easy-state