8000 docs(readme): add clarity and disambiguation (#6) · homebaseio/homebase-react@ca8d651 · GitHub
[go: up one dir, main page]
Skip to content

Commit ca8d651

Browse files
becomingbabymanbecomingbabyman
committed
docs(readme): add clarity and disambiguation (#6)
1 parent e0f1e6f commit ca8d651

File tree

1 file changed

+59
-24
lines changed

1 file changed

+59
-24
lines changed

‎README.md

Lines changed: 59 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Homebase React
22

3-
> The graph database for simple React state management
3+
> The graph database for delightful React state management
44
55
## Installation
66

@@ -24,38 +24,51 @@ You can clone and run our React code examples [here](https://github.com/homebase
2424

2525
## Purpose
2626

27-
We want software to be [local-first](https://news.ycombinator.com/item?id=21581444). That means we need to make it more convenient to work with complex data on clients.
27+
We want data to be a first class citizen on the client. We love relational databases in our servers and we want that same experience in our React apps. In other words, we want our applications to be [local-first](https://news.ycombinator.com/item?id=21581444). That means we need to make it easier to work with complex data on clients.
2828

29-
Homebase React lets you plug a relational database into your React app.
29+
Homebase React lets you plug a relational database into your React app with 3 lines of code. In fact it's the same database that powers Roam Research and many other ClojureScript applications, but with an API that's familiar to React and JS developers.
3030

3131
- Replace Redux with something simpler and more declarative
3232
- Gain all the benefits of relational data like a single source of truth
3333
- Query your database with a convenient JSON query syntax
34-
- Query your database with datalog if you need more power
34+
- Query your database with Clojure style datalog if you need more power
3535
- Traverse your data graph like it's one big JSON object
36+
- Stop spending time wiring up custom datatypes, reducers, caches and other bespoke state mumbo jumbo
37+
- It's just data
3638

37-
It is immediately more intuitive than a denormalized JSON store, and over time it will get better as we add more local-first features to it.
39+
We think that Homebase React is immediately more intuitive than any denormalized JSON store, and over time it will get better as we eliminate all the tedious aspects of manipulating data on clients.
3840

3941
## API Overview
4042

4143
### `HomebaseProvider`
4244

45+
The HomebaseProvider wraps your React app and makes a relational database accessible to all of your components. Configure it with `schema` and `initialData`.
46+
4347
```js
4448
import { HomebaseProvider, useEntity, useTransact, useQuery } from 'homebase-react'
4549

4650
const config = {
47-
// Schema is optional
48-
// ref indicates a relationship
49-
// unique enforces a uniqueness constraint
51+
// Schema is not a type system like in most DBs.
52+
// That is something we're considering, but for now it is
53+
// mainly applied at query time to simplify relational queries.
54+
// The only schema currently supported is:
55+
// `type: 'ref'` which is a relationship and
56+
// `unique: 'identity` which enforces a uniqueness constraint
57+
// and let's you lookup entities by their unique attributes.
5058
schema: {
5159
todo: {
5260
project: { type: 'ref' },
5361
name: { unique: 'identity' }
5462
}
5563
},
64+
65+
// Initial data is what it sounds like.
66+
// It's a transaction that runs on component mount.
67+
// Use it to hydrate your app.
5668
initialData: [
57-
{ project: { id: -1, name: 'Do it' } }
58-
{ todo: { project: -1, name: 'Make it' }}
69+
{ project: { id: -1, name: 'Do it', owner: -2 } },
70+
{ todo: { project: -1, name: 'Make it' } },
71+
{ user: { id: -2, name: 'Arpegius' } }
5972
]
6073
}
6174

@@ -68,52 +81,74 @@ const RootComponent = () => (
6881

6982
### `useEntity` and `entity.get`
7083

71-
```js
72-
// Entities with unique attributes can be retrieved by those attributes
73-
const [todo] = useEntity({ todo: { name: 'Make it' } })
84+
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**.
7485

75-
// Get attributes off an entity
76-
todo.get('name') // => 'Make it'
86+
```js
87+
// You can get an entity by its id and get attributes off of it.
88+
const [todo] = useEntity(2)
7789
todo.get('id') // => 2
90+
todo.get('name') // => 'Make it'
7891

79-
// You can also get an entity by its id
80-
const [sameTodo] = useEntity(2)
92+
// Entities with unique attributes can also be retrieved by those attributes.
93+
const [sameTodo] = useEntity({ todo: { name: 'Make it' } })
94+
sameTodo.get('id') // => 2
8195

82-
// And traverse relationships
83-
todo.get('project', 'name') // => 'Do it'
96+
// And most importantly you can traverse arbitrarily deep relationships.
97+
sameTodo.get('project', 'owner', 'name') // => 'Arpegius'
8498
```
8599

86100
### `useTransact`
87101

102+
Transactions let you create, update and delete multiple entities simultaneously. All changes will reactively update any components that depend on the changed data.
103+
88104
```js
89105
const transact = useTransact()
90106

91-
// A transaction is an array of nested objects
107+
// A transaction is an array of nested objects and or arrays.
108+
// Leaving the id blank will create a new entity.
92109
transact([{ todo: { name: 'New Todo', project: 1 } }])
93110

94-
// Update an entity by including its id
111+
// Setting the id to a negative number is a temp id which
112+
// allows multiple entities to be related to each other on creation.
113+
transact([
114+
{ project: { id: -123, name: 'New Project' } },
115+
{ todo: { project: -123, name: 'New Todo' } },
116+
])
117+
118+
// Update an entity by including its id.
119+
// NOTE: that only the included attributes will be updated.
95120
transact([{ project: { id: 1, name: 'Changed Project Title' } }])
96121

97-
// Delete an entity with retractEntity and its id
122+
// To remove an attribute you have to explicitly set it to null.
123+
transact([{ project: { id: 1, name: null } }])
124+
125+
// To delete an entire entity use retractEntity and its id
98126
transact([['retractEntity', 1]])
99127
```
100128

101129
### `useQuery`
102130

131+
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 Mongo DB. Datalog is similar to SQL and is incredibly powerful. However only a subset of features are currently available in JSON.
132+
133+
We are very interested in what features the community wants, and will prioritize based on feedback. In the meantime you can further filter results with JS `filter()` and `sort()`.
134+
103135
```js
104-
// Finds any todo with a name
136+
// Finds all todos with a name
105137
const [todos] = useQuery({
106138
$find: 'todo',
107139
$where: { todo: { name: '$any' } }
108140
})
109141

110142
// Returns an array of todo entities
111-
todos.map(todo => todo.get('name'))
143+
todos
144+
.sort((todo1, todo2) => todo1.get('name') > todo2.get('name') ? 1 : -1)
145+
.map(todo => todo.get('name'))
112146
```
113147

114148
## Development
115149

116150
```bash
151+
npm install
117152
npx shadow-cljs watch :dev
118153
```
119154

0 commit comments

Comments
 (0)
0