neighbor-peace / LiveStateDB

A real time state management library that allows for state to subscribe and update based on changes from a specific portion of a database.

LiveStateDB

Automatically update state based on database changes
Report Bug or Request Feature

About

LiveStateDB is a database subscription API that enables developers to make state reflect database changes in real time. Developers will have access to a custom hook, useSubscribe(), to implement in your front-end codebase, and a back-end library which allows the server to interface with your database. Currently, LiveStateDB only supports MongoDB.

Built With

Getting Started

LiveStateDB features a client side library and a server side library that can be installed via npm or yarn with the following commands. The libraries need to be installed on both sides in order to make use of LiveStateDB's real time updates.

npm install @livestatedb/client
yarn install @livestatedb/client

npm install @livestatedb/server
yarn install @livestatedb/server

Using the hook useSubscribe( )

First import the module into the file you wish to use it.

import { useSubscribe } from '@livestatedb/client';

When useSubscribe is called, it will open a web socket through which database updates get passed when changes occur that state is 'subscribed to'.

useSubscribe takes one argument: an object with three key-value pairs that correspond with the database name, collection name, and query to a database. Here's an example.

const options = {
  database: 'DBname',
  collection: 'someCollectionName',
  query: {}
};

useSubscribe returns the way to reference state in your front-end code, and a function that ends that piece of state's subscription to the database.

const [ state, endSubscription ] = useSubscribe(options);

NOTE!
useSubscribe will only receive updates from the database that match the options passed-in at the time it was called. If a database change occurs that would match the query parameters, it will not automatically be included in what useSubscribe is subscribed to. You would need to re-render the page to call useSubscribe again to capture this.

Additionally, your query filter parameters should be constant. For example, if you are building a dashboard for managing inventory, your filter parameters could include condition: (new, like new, fair, poor), but should not include parameters such as quantity: (>50, <=50). In this example, if you wanted to be subscribed to data that had a certain quantity, you would need write your options object, and specifically your query parameters, to include all of the data you're interested in, regardless of quantity. You would then be able to filter out only the data you're interested in in your front-end codebase.

Using the back-end library

useSubscribe won't work until you pass information about your MongoDB and Redis into a function that opens a web socket and connects everything. Require the module in wherever you instantiate an http server, for example server.js. Feel free to give it a label or to to simply invoke the required-in function with the necessary arguments.

const liveStateDB = require('@livestatedb/server');
liveStateDB(httpServer, databaseInfo);

OR

require('@livestatedb/server')(httpServer, databaseInfo);

The second paramater, databaseInfo, must be an object with two key-value pairs - these are for passing in information about your MongoDB database and Redis, respectively. The values are both objects that contain connection information for each database. See example below.

const databaseInfo = 
  {
    mongoDbOptions: 
      {
        uri: "mongodb+srv://name:[e-mail]/?retryWrites=true&w=majority"
      },
    redisDbOptions: 
      {
        host: 'redis-00000.c00.us-east-0-0.ec2.cloud.redislabs.com', 
        port: 15711, 
        password: 'lkajsdf092j3jlsdfmop3jfspdkgpoi',
        family: 4
      },
  }

That's it! Your front-end will now be able to display or work with the subscribed database data as it updates in real time - regardless of where the change originates from.

Thanks for your interest in LiveStateDB, and we hope this improves your development experience.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

Starting Notes

• Main branch is only for production
• Dev branch is for development. Two person review process for pull requests to the dev and main branch.

Starting off

1. Clone main repository to local machine
2. git checkout -b [name/feature] -> Create feature branch off of dev
3. Commit to your local feature branch often!

Pushing changes to the dev repo

1. 'Git checkout dev' (locally switch to dev branch)
2. 'Git pull origin dev' (Pull updates of dev down to your local system)
3. 'Git checkout [your branch] (switch back to your branch locally)
4. 'Git merge dev' (Brings dev into your local branch)
5. Resolve conflicts or :q if there aren't any
6. 'Git push origin ' (Push merged branch up to github)
7. Create a pull request in github from => dev
8. Repeat as needed
9. When ready to publish main, do step 7 but from dev => main

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

Kevin Richardson LinkedIn | GitHub

Stephanie Page LinkedIn | GitHub

David Cheng LinkedIn | GitHub

Evan Deam LinkedIn | GitHub

(back to top)