react-traph v0.0.5
Traph
Installation
yarn add react-traphExample
import React from 'react'
import traph from 'react-traph'
import ReactDOM from 'react-dom'
const Graph = traph({
user: {
firstName: "Tormod",
lastName: "Haugland"
},
toasts: traph({
items: [],
addToast(message){
this.updateGraph({
items: this.items.concat({message})
})
}
})
})
function Toast({message}){
const [lastName, setLastName] = Graph.useGraph("user.lastName")
return (
<div onClick={() => setLastName(message)}>
{message}
</div>
)
}
function ToastContainer(){
const [user] = Graph.useGraph("user")
const [toasts] = Graph.useGraph("toasts")
return (
<div onClick={() => toasts.addToast(user.firstName + ", " + user.lastName)}>
Hey {user.firstName}! Click me!
{toasts.items.map(toast => <Toast message={toast.message} />)}
</div>
)
}
function UserForm(){
const [user, setUser] = Graph.useGraph("user")
return (
<form>
<input value={user.firstName} onChange={e => setUser({firstName: e.target.value})} />
<input value={user.lastName} onChange={e => setUser({lastName: e.target.value})} />
</form>
)
}
ReactDOM.render(
<Graph.Provider>
<UserForm />
<ToastContainer />
</Graph.Provider>
)User guide
Creating and using a traph tree
The primary function of this library is traph. It creates a new store-like object we refer to as a graph (although it is technically a tree). The two primary fields exposed by a graph is the Provider React node and the useGraph-hook.
When traph is called, a new React Context used to contain all the data for the graph is created. All subgraphs are also recursively instantiated.
Let's use traph to create a very simple TODO-app. First we create the graph:
// TodoGraph.js
import traph from 'traph'
const TodoGraph = traph({
items: [],
nextId: 0
})
export default TodoGraphThen we create our components:
import React, { useState } from 'react'
// Todo.jsx
function Todo({
id,
text,
done,
onClick
}){
<Todo
className={done ? "done" : ""}
onClick={onClick}
>
{text}
</Todo>
}
export default Todo
// Todos.jsx
function Todos(){
// This fetches the entire graph-data, i.e.
// { items: Array }
const [todos, setTodos] = TodoGraph.useGraph()
function handleClick(item){
setTodos({
items: todos.items.map(_item => {
if (_item.id === item.id) {
return {...item, done: !item.done}
}
return _item
})
})}
}
return (
<ul>
{todos.items.map(item => (
<Todo
key={item.id}
onClick={handleClick}
>
{item.text}
</Todo>
))}
</ul>
)
}
export default Todos// CreateTodoForm.jsx
function CreateTodoForm(){
const [todos, setTodos] = TodoGraph.useGraph()
const [todoText, setTodoText] = useState("")
function handleSubmit(e){
e.preventDefault();
if (!todoText) return
setTodos({
items: items.concat({
id: todos.nextId + 1,
text: todoText,
done: false
}),
nextId: todos.nextId + 1
})
}
return (
<form onSubmit={handleSubmit}>
<input type="text" value={todoText} onChange={e => setTodoText(e.target.value)} />
<button>Add new Todo</button>
</form>
)
}
export default CreateTodoFormAnd finally we wrap the components in a provider and render it
// index.jsx
import React from 'react'
import ReactDOM from 'react-dom'
import CreateTodoForm from './CreateTodoForm'
import Todos from './Todos'
import TodoGraph from './TodoGraph'
return ReactDOM.render(
<TodoGraph.Provider>
<CreateTodoForm />
<Todos />
</TodoGraph.Provider>
)Querying specific parts of the graph
In the example above, the <Todos />-component only really cares about the items-entry of the state. We can query this part of the graph specifically, by supplying an argument to the useGraph-function:
// Todos.jsx
function Todos(){
const [items, setItems] = TodoGraph.useGraph("items")
function handleClick(item){
setItems(todos.items.map(_item => {
if (_item.id === item.id) {
return {...item, done: !item.done}
}
return _item
}))
}
return (
<ul>
{items.map(item => (
<Todo
key={item.id}
onClick={handleClick}
>
{item.text}
</Todo>
))}
</ul>
)
}
export default Todostraph ensures that when setItems is called, the correct part of the graph is updated.
For more deeply nested structures, we can use a dot to separate what part to query. Internally, lodash get is used here. Hence for a structure like
const Graph = traph({
top: {
middle: {
bottom: [
{name: "User 1"},
{name: "User 2"},
]
}
}
})We could now get the second user by executing
const [user, setUser] = Graph.useGraph("top.middle.bottom[2]")Updating the user with setUser will merge the new data into the graph as expected.
Member functions
When calling useGraph, we automatically get a function to update the state we have just received.
However, some people (yes, I'm looking at you) prefer to use member functions of their state to mutate this. To avoid having to implement an observer-observable pattern on all attributes of a state, traph rebinds all functions in a graph, and makes available an updateGraph-method on this:
const Toasts = traph({
nextToastId: 0,
toasts: [],
addToast({type, message}){
this.updateGraph({
toasts: this.toasts.concat({type, message})
})
}
})Note also that all the graph's current values are injected into this.
The updateGraph-method is literally the same method as is returned when calling Toasts.useGraph().
Using non-objects as values
In the above examples, we have used objects as the initial value to traph. However, traph can store any data you wish to throw at it.
const Users = traph([
{name: "Mike"},
{name: "James"},
])
const IsOffline = traph(false)
const MeasurementData = traph([1.3, 1.2, 1.15, 3.4, 3.2, 2.8])
const NumberOfUsersOnline = traph(123)Nested trees
Basic usage
One of the strengths of traph is the ability to nest graphs. Nested graphs can be used both independently and jointly.
Suppose we have:
const SidebarGraph = traph({
open: false,
toggle(){
this.updateGraph({open: !this.open})
}
set(open){
this.updateGraph({open})
}
})
const ToastGraph = traph({
toasts: [],
addToast({type, message}){
this.updateGraph({
toasts: this.toasts.concat({type, message})
})
}
})
const Graph = traph({
someTopLevelValue: 42,
toasts: ToastGraph,
sidebar: SidebarGraph,
})One of the advantages of nesting the graphs inside a top-level graph, is that the top-level Provider automatically will create the context-providers of the subgraphs:
<Graph.Provider>
{/* Graph.Provider renders ToastGraph.Provider and
SidebarGraph.Provider automatically */}
<ComponentConsumingAllGraphData />
</Graph.Provider>Within <ComponentConsumingAllGraphData />, we can query, for instance, the data in ToastGraph in two distinct ways:
function ComponentConsumingAllGraphData(){
const [toastGraph, setToastGraph] = ToastGraph.useGraph()
// or
const [toastGraph, setToastGraph] = Graph.useGraph("toasts")
...
}These are, in this scenario, equivalent. However, they may return differing results if the top-level Graph store is altered in a way which removes the toasts subgraph.
Querying into sub-graphs
We can query into subgraphs in the expected manner. Suppose we are given the Graph above.
function Component(){
// Will return the first element of the `toasts` property in the `toasts`-subgraph.
const [firstToast, setFirstToast] = Graph.useGraph("toasts.toasts[0]")
...
}Automatic propagation of updated subgraph values
Suppose we have the following Graph:
const Graph = traph({
top: traph({
topValue: 103993/33102,
middle: traph({
middleValue: 1337,
bottom: traph({
deepValue: 41
})
})
})
})and the following components:
function ComponentUsingTop(){
const [top, setTop] = Graph.useGraph("top")
return (
<div>
{top.middle.bottom.deepValue}
</div>
)
}
function ComponentUsingMiddle(){
const [middle, setMiddle] = Graph.useGraph("top.middle")
return (
<div>
{middle.bottom.deepValue}
</div>
)
}
function ComponentUsingBottom(){
const [bottom, setBottom] = Graph.useGraph("top.middle.bottom")
return (
<div onClick={() => setBottom({deepValue: bottom.deepValue + 1})}>
{bottom.deepValue}
</div>
)
}If the <div> in <ComponentUsingBottom> is clicked, all components receives the updated deepValue automatically.
Any consumer of any graph above a graph being altered will also have its values updated.
Updating slices spanning multiple sub graphs
Expanding on the above example, we can wonder what happens if we update a slice of the entire graph from the consumer of the top graph. traph will in this scenario ensure that the data is propagated down into the subgraphs:
function ComponentUsingTop(){
const [top, setTop] = Graph.useGraph("top")
return (
<div onClick={() => setTop({
topValue: Math.PI, // Should be more precise
middle: {
// middleValue is fine as is. Omitting it in the update object will simply let it
// stay put
bottom: {
deepValue: top.middle.bottom.deepValue + 1
}
}
})}>
{top.middle.bottom.deepValue}
</div>
)
}
function ComponentUsingMiddle(){
const [middle, setMiddle] = Graph.useGraph("top.middle")
return (
<div>
{middle.bottom.deepValue}
</div>
)
}
function ComponentUsingBottom(){
const [bottom, setBottom] = Graph.useGraph("top.middle.bottom")
return (
<div onClick={() => setBottom({deepValue: bottom.deepValue + 1})}>
{bottom.deepValue}
</div>
)
}As is expected, the Context in all the subgraphs are updated appropriately.
Overriding contexts
As traph is powered by React Contexts at its core, it is possible to have different values for a graph at different locations in the component hierarchy.
const Graph = traph({
message: "hello"
})
function Component(){
const [message, setMessage] = Graph.useGraph("message")
return (
<div onClick={() => setMessage("updated")}>
{message}
</div>
)
}
ReactDOM.render(
<Graph.Provider>
<Component />
<Graph.Provider graphData={{message: "override"}}>
<Component />
</Graph.Provider>
</Graph.Provider>
)This would render two divs, the first with inner text "hello", and the second with inner text "override". Note that the graphData property overrides the Graph initial data.
If the second div is clicked, only the second <Component> has its value updated.
Attaching graphs to multiple locations
While the Graph data-structure returned by traph is technically a tree, it exhibits one piece of graph-like cyclic behavior, and that is the possibility to attach a graph to multiple locations within a tree.
const UserOne = traph({
name: "UserOne",
life: 10
})
const UserTwo = traph({
name: "UserOne",
life: 10
})
const Users = traph([
UserOne,
UserTwo
])
const HouseOne = traph({
inhabitant: UserOne,
size: 500
})
const HouseTwo = traph({
inhabitant: UserTwo,
size: 600
})
const Houses = traph([HouseOne, HouseTwo])
const Game = traph({
users: Users,
houses: Houses
})This is perfectly valid — altough rather strange — and is handled appropriately by traph. If one of the users is consumed in any manner, and altered; this change is propagated to all other graphs/subgraphs which uses the user.
function UserList(){
const [users] = Game.useGraph("users")
return (
<div>
{users.map(user => <div>{user.name}</div>)}
</div>
)
}
function UserOneArea(){
const [userOne, setUserOne] = Game.userGraph("users[0]")
return (
<div>
<h2>First users area</h2>
<span>Name: {userOne.name}</span>
<span onClick={() => setUserOne({life: userOne.life - 1})}>Life: {userOne.life}</span>
</div>
)
}
function Houses(){
const [houses] = Game.useGraph("houses")
return (
<div>
{houses.map(house => (
<div>
<div>{house.name}</div>
{house.users.map(user => (
<div key={user.name}>
{user.name} lives here and has {user.life} life left.
</div>
))}
</div>
))}
</div>
)
}Clicking the life on the first users area will automatically update the UserOne graph's value in all the places where the graph is mounted.
Removing subgraphs
The structure of a graph's data is partially immutable after creation. Specifically,
the initial structure is stored separately from the mutated data. When a graph's data is consumed using useGraph, this structure is used when resolving subgraph state. Hence,
you cannot really replace a subgraph with other data.
You can however disable the subgraph, by setting the corresponding key to null.
const Graph = traph({
top: "value",
subgraph: traph({
bottom: "value2"
})
})
function Component(){
const [graph, setGraph] = Graph.useGraph()
return (
<div onClick={() => setGraph({
subgraph: null
})}>
{graph.subgraph ? "Subgraph exists" : "Subgraph does not exist"}
</div>
)
}Clicking the <div> will make the subgraph disappear from the top-level graph's resolved data. Note that the Graph instance itself still exists, and setting the value back to something non-null (i.e. true) will re-enable the subgraph.
All the structure of the graph state which is not a subgraph is replaceable.
The third entry returned by useGraph
useGraph actually returns three values, and not two. The third value is another updating function, which overwrites the data of the returned graph state, instead of doing a smarter merge.
const Store = traph({
firstName: "Tormod",
lastName: "Haugland"
})
function Component(){
const [user, setUser, replaceUser] = dataGraph.useGraph("user.firstName")
return (
<div>
<button onClick={() => setUser({newKey: "newValue"})}>Update</button>
<button onClick={() => replaceUser({newKey: "anotherNewValue"})}>Replace</button>
<div>
{user.firstName}
{user.lastName}
{user.newKey}
</div>
</div>
)
}When clicking the first button, the new graph state will be
{
firstName: "Tormod",
lastName: "Tormod",
newKey: "newValue",
}But when clicking the second button, the new graph state will be
{
newKey: "anotherNewValue",
}The object passed to replaceUser is accepted as the complete new state.
Quirks
There are a few quirks to be wary off when using this library:
- If you mount a Graph at multiple locations in an above Graph, it's Provider will only be rendered once, as the traph deduplicates providers.
- There are two locations where you can supply initial data to a graph: As the first argument to it's constructor, but also in the
graphDataprop of the graph's Provider. The latter will always dominate. - The internal data store (which is separate from the graph initial structure) is treated as immutable. Updating a complex data type (Object, Array), will always create a new object of the same type. However, in cases where new entries are added, these are added as-supplied to the graph.
- Functions located deeply within some data structure which is not a graph, will not be rebound to take the
updateGraphmethod.
Behaviours explicitly listed as undefined by the library
The following behaviours are (currently) listed as undefined. Use at your own peril:
- Injecting subgraphs into a graph's state after creation.
- Adding complex object types (e.g. classes) with graphs located somewhere within the class.
- Adding functions as the initial data to a graph (the issue here is related to the fact that functions sent to React's useState internally calls the function).
TODOS
- Dynamically adding subgraphs.
- Rebinding of deeply nested functions.