Undb NPM | npm.io

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