The graph database for delightful React state management
Homebase React makes state management painless by enabling you to plug a relational graph database into your React application with just 3 lines of code. This is the same database that powers Roam Research and many other ClojureScript applications, but with an API that's familiar to React and JS developers.
# NPM
npm install homebase-react --save
# Yarn
yarn add homebase-react- The simplest and most declarative state management solution
- The power of a backend relational graph database, but without having to wait on the network
- Convenient JSON query syntax
- Powerful Clojure style Datalog query syntax if you need it
- Traverse your data graph like it's a big JSON object
- Backup your data to the cloud
- Document integration with more backends
- Swap Datascript out for Datahike
- Immutability
- History / Change Tracking
- Persist to IndexedDB
- Local-first conflict resolution for offline caching and sync between multiple devices
You can see our hosted live demos here
You can clone and run our React code examples here.
The HomebaseProvider wraps your React app and makes a relational database accessible to all of your components. Configure it with schema and initialData.
import { HomebaseProvider, useEntity, useTransact, useQuery } from 'homebase-react'
const config = {
// Schema is not a type system,
// it's a way to simplify relational queries at query time.
// The schema currently supported is:
// `type: 'ref'` which is a relationship and
// `unique: 'identity` which enforces a uniqueness constraint
// and lets you lookup entities by their unique attributes.
schema: {
todo: {
project: { type: 'ref' },
name: { unique: 'identity' }
}
},
// Initial data is what it sounds like.
// It's a transaction that runs on component mount.
// Use it to hydrate your app.
initialData: [
{ project: { id: -1, name: 'Do it', owner: -2 } },
{ todo: { project: -1, name: 'Make it' } },
{ user: { id: -2, name: 'Arpegius' } }
]
}
const RootComponent = () => (
<HomebaseProvider config={config}>
<App/>
</HomebaseProvider>
)Entities are the building blocks of the Homebase data model. They are like JSON objects with bonus features. In particular you can traverse arbitrarily deep relationship without actually denormalizing and nesting your data.
// You can get an entity by its id and get attributes off of it.
const [todo] = useEntity(2)
todo.get('id') // => 2
todo.get('name') // => 'Make it'
// Entities with unique attributes can also be retrieved by those attributes.
const [sameTodo] = useEntity({ todo: { name: 'Make it' } })
sameTodo.get('id') // => 2
// And most importantly you can traverse arbitrarily deep relationships.
sameTodo.get('project', 'owner', 'name') // => 'Arpegius'Transactions let you create, update and delete multiple entities simultaneously. All changes will reactively update any components that depend on the changed data.
const transact = useTransact()
// A transaction is an array of nested objects and or arrays.
// Leaving the id blank will create a new entity.
transact([{ todo: { name: 'New Todo', project: 1 } }])
// Setting the id to a negative number is a temp id which
// allows multiple entities to be related to each other on creation.
transact([
{ project: { id: -123, name: 'New Project' } },
{ todo: { project: -123, name: 'New Todo' } },
])
// Update an entity by including its id.
// NOTE: that only the included attributes will be updated.
transact([{ project: { id: 1, name: 'Changed Project Title' } }])
// To remove an attribute you have to explicitly set it to null.
transact([{ project: { id: 1, name: null } }])
// To delete an entire entity use retractEntity and its id
transact([['retractEntity', 1]])Use queries to return an array of entities that meet a given criteria. Our query API is powered by Datalog, but exposed as JSON similar to a JS SQL driver or MongoDB. Datalog is similar to SQL and is incredibly powerful. However, only a subset of features are currently available in JSON.
We will prioritize features based on community feedback so please open an issue if there's something you need. In the meantime you can further filter results with JS filter() and sort().
// Finds all todos with a name
const [todos] = useQuery({
$find: 'todo',
$where: { todo: { name: '$any' } }
})
// Returns an array of todo entities
todos
.sort((todo1, todo2) => todo1.get('name') > todo2.get('name') ? 1 : -1)
.map(todo => todo.get('name'))This hook returns the current database client with some helpful functions for syncing data with a backend.
client.dbToString()serializes the whole db including the schema to a stringclient.dbFromString('a serialized db string')replaces the current dbclient.dbToDatoms()returns an array of all the facts aka datoms saved in the db- datoms are the smallest unit of data in the database, like a key value pair but better
- they are arrays of
[entityId, attribute, value, transactionId, isAddedBoolean]
client.addTransactListener((changedDatoms) => ...)adds a listener function to all transactions- use this to save data to your backend
client.removeTransactListener()removes the transaction listener- please note that only 1 listener can be added per useClient scope
client.transactSilently([{item: {name: ...}}])liketransact()only it will not trigger any listeners- use this to sync data from your backend into the client
Check out the Firebase example for a demonstration of how you might integrate a backend.
Homebase React tracks the attributes consumed in each component via the entity.get function and scopes those attributes to their respective useEntity or useQuery hook. Re-renders are only triggered when an attribute changes.
The default caching reduces unnecessary re-renders and virtual DOM thrashing a lot. That said, it is still possible to trigger more re-renders than you might want.
One top level useQuery + prop drilling the entities it returns will cause all children to re-render on any change to the parent or their siblings.
To fix this we recommend passing ids to children, not whole entities. Instead get the entity in the child with useEntity(id). This creates a new scope for each child so they are not affected by changes in the state of the parent or sibling components.
const TodoList = () => {
const [todos] = useQuery({
$find: 'todo',
$where: { todo: { name: '$any' } }
})
return (todos.map(t => <Todo key={t.get('id')} id={t.get('id')} />))
}
// Good
const Todo = React.memo(({ id }) => {
const [todo] = useEntity(id)
// ...
})
// Bad
const Todo = React.memo(({ todo }) => {
// ...
})https://www.notion.so/Homebase-Alpha-Docs-0f0e22f3adcd4e9d87a13440ab0c7a0b
yarn install
yarn devyarn install
yarn testWelcome and thank you! Writing docs, patches and features are all incredibly helpful and appreciated.
We only ask that you provide test coverage for code changes, and conform to our commit guidelines.
- Chris Smothers (@csmothers) – Homebase
- JB Rubinovitz (@rubinovitz) – Homebase