Skip to content

Commit 88488aa

Browse files
crs48crs48
authored
docs(docs): add docs dir
1 parent 3e69c05 commit 88488aa

11 files changed

+933
-104
lines changed

‎.github/pull_request_template.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@
88
- [ ] no tests needed
99

1010
### Docs
11-
- [ ] added relevant docs
11+
- [ ] added relevant docs
12+
- preview them at https://homebase.io/docs/homebase-react/{BRANCH_NAME}/overview
1213
- [ ] updated relevant sections in the README.md
1314
- [ ] updated relevant docstrings in index.d.ts
1415
- [ ] no docs needed

‎README.md

Lines changed: 5 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@ npm install homebase-react --save
2222
# Yarn
2323
yarn add homebase-react
2424
```
25+
26+
## Docs
27+
https://homebase.io/docs/homebase-react
28+
2529
## Features
2630
- The simplest and most declarative state management solution
2731
- The power of a backend relational graph database, but without having to wait on the network
@@ -103,7 +107,7 @@ const RootComponent = () => (
103107

104108
### `useEntity` and `entity.get`
105109

106-
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**.
110+
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 relationships without actually denormalizing and nesting your data**.
107111

108112
```js
109113
// You can get an entity by its id and get attributes off of it.
@@ -185,107 +189,6 @@ This hook returns the current database client with some helpful functions for sy
185189

186190
Check out the [Firebase example](https://homebaseio.github.io/homebase-react/#!/example.todo_firebase) for a demonstration of how you might integrate a backend.
187191

188-
### Arrays & Nested JSON
189-
190-
Arrays and arbitrary JSON are partially supported for convenience. However in most cases its better to avoid arrays. Using a query and then sorting by an attribute is simpler and more flexible. This is because arrays add extra overhead to keep track of order.
191-
192-
```js
193-
const config = {
194-
schema: {
195-
company: {
196-
numbers: { type: 'ref', cardinality: 'many' },
197-
projects: { type: 'ref', cardinality: 'many' },
198-
}
199-
}
200-
}
201-
202-
transact([
203-
{ project: { id: -1, name: 'a' } },
204-
{
205-
company: {
206-
numbers: [1, 2, 3],
207-
projects: [
208-
{ project: { id: -1 } },
209-
{ project: { name: 'b' } },
210-
]
211-
}
212-
}
213-
])
214-
215-
// Index into arrays
216-
company.get('numbers', 1, 'value') // => 2
217-
company.get('projects', 0, 'ref', 'name') // => 'a'
218-
// Get the automatically assigned order
219-
// Order starts at 1 and increments by 1
220-
company.get('numbers', 0, 'order') // => 1
221-
company.get('projects', 0, 'order') // => 1
222-
company.get('projects', 1, 'order') // => 2
223-
// Map over individual attributes
224-
company.get('numbers', 'value') // => [1, 2, 3]
225-
company.get('projects', 'ref', 'name') // => ['a', 'b']
226-
```
227-
228-
The `entity.get` API is flexible and supports indexing into arrays as well as automatically mapping over individual attributes.
229-
230-
Array items are automatically assigned an `order` and either a `value` or a `ref` depending on if item in the array is an entity or not. To reorder an array item change its `order`.
231-
232-
```js
233-
transact([
234-
{
235-
id: company.get('numbers', 2, 'id'),
236-
order: (company.get('numbers', 0, 'order')
237-
+ company.get('numbers', 1, 'order')) / 2
238-
}
239-
])
240-
241-
company.get('numbers', 'value') // => [1 3 2]
242-
```
243-
244-
If you need to transact complex JSON like arrays of arrays then you're better off serializing it to a string first.
245-
246-
```js
247-
// NOT supported
248-
transact([{ company: { matrix: [[1, 2, 3], [4, 5, 6]] } }])
249-
250-
// Better
251-
transact([{ company: { matrix: JSON.stringify([[1, 2, 3], [4, 5, 6]]) } }])
252-
JSON.parse(company.get('matrix'))
253-
```
254-
255-
## Performance
256-
257-
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.
258-
259-
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.
260-
261-
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.
262-
263-
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.
264-
265-
```js
266-
const TodoList = () => {
267-
const [todos] = useQuery({
268-
$find: 'todo',
269-
$where: { todo: { name: '$any' } }
270-
})
271-
return (todos.map(t => <Todo key={t.get('id')} id={t.get('id')} />))
272-
}
273-
274-
// Good
275-
const Todo = React.memo(({ id }) => {
276-
const [todo] = useEntity(id)
277-
// ...
278-
})
279-
280-
// Bad
281-
const Todo = React.memo(({ todo }) => {
282-
// ...
283-
})
284-
```
285-
286-
287-
## Docs
288-
https://www.notion.so/Homebase-Alpha-Docs-0f0e22f3adcd4e9d87a13440ab0c7a0b
289192
## Development
290193

291194
```bash

‎docs/0100|Overview.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
## Homebase React
2+
3+
[![CI](https://github.com/homebaseio/homebase-react/workflows/CI/badge.svg)](https://github.com/homebaseio/homebase-react/actions?query=workflow%3ACI)
4+
[![CD](https://github.com/homebaseio/homebase-react/workflows/CD/badge.svg)](https://github.com/homebaseio/homebase-react/actions?query=workflow%3ACD)
5+
[![NPM Version](https://img.shields.io/npm/v/homebase-react)](https://www.npmjs.com/package/homebase-react)
6+
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/homebase-react)](https://www.npmjs.com/package/homebase-react)
7+
[![License](https://img.shields.io/github/license/homebaseio/homebase-react.svg)](LICENSE)
8+
[![GitHub Repo stars](https://img.shields.io/github/stars/homebaseio/homebase-react?style=social)](https://github.com/homebaseio/homebase-react)
9+
[![Twitter Follow](https://img.shields.io/twitter/follow/homebase__io?label=Follow&style=social)](https://twitter.com/homebase__io)
10+
11+
*The graph database for delightful React state management*
12+
13+
14+
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.
15+
16+
## Install
17+
18+
```bash
19+
# NPM
20+
npm install homebase-react --save
21+
22+
# Yarn
23+
yarn add homebase-react
24+
```
25+
## Features
26+
- The simplest and most declarative state management solution
27+
- The power of a backend relational graph database, but without having to wait on the network
28+
- Convenient JSON query syntax
29+
- Powerful Clojure style [Datalog](https://docs.datomic.com/on-prem/query.html) query syntax if you need it
30+
- Traverse your data graph like it's a big JSON object
31+
- Backup your data to the cloud
32+
33+
## Roadmap
34+
35+
1. Document integration with more backends
36+
1. Swap [Datascript](https://github.com/tonsky/datascript) out for [Datahike](https://github.com/replikativ/datahike)
37+
1. Immutability
38+
1. History / Change Tracking
39+
2. Persist to IndexedDB
40+
3. [Local-first](https://www.inkandswitch.com/local-first.html) conflict resolution for offline caching and sync between multiple devices

‎docs/0200|Quick_Start.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
Homebase React creates a local relational database for your React app.
2+
3+
```js
4+
import { HomebaseProvider } from 'homebase-react'
5+
6+
const RootComponent = () => (
7+
<HomebaseProvider>
8+
<App/>
9+
</HomebaseProvider>
10+
)
11+
```
12+
13+
Read from and write to that database via hooks.
14+
15+
```js
16+
import { useCallback } from 'react'
17+
import { useEntity, useTransact } from 'homebase-react'
18+
19+
const App = () => {
20+
const [counter] = useEntity(1)
21+
const [transact] = useTransact()
22+
23+
const handleClick = useCallback(() => {
24+
transact([{ counter: {
25+
id: 1, count: counter.get('count') + 1
26+
} }])
27+
}, [counter, transact])
28+
29+
return (
30+
<button onClick={handleClick}>
31+
Increment
32+
{counter.get('count')}
33+
</button>
34+
)
35+
}
36+
```

0 commit comments

Comments
 (0)