reactjrx 1.28.2 → 1.29.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -148
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,151 +1,5 @@
|
|
|
1
|
-
#
|
|
1
|
+
#reactjrx
|
|
2
2
|
|
|
3
3
|
`reactjrx` is a javascript library which provides a simple and efficient API for handling global state, flow control, and queries in React applications using RxJS. With a small footprint and scalability to suit any project size, it is a great alternative to other popular libraries such as Recoil, Redux, React Query, Zustand, etc.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
# Installation
|
|
8
|
-
|
|
9
|
-
To install Reactjrx, simply run:
|
|
10
|
-
|
|
11
|
-
```
|
|
12
|
-
npm install reactjrx
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
# Overview
|
|
16
|
-
|
|
17
|
-
## Low level API: RxJS bindings
|
|
18
|
-
|
|
19
|
-
The low level API provide all the building blocks to bind rxjs to react and the higher API. For example let's assume
|
|
20
|
-
you have a package that expose observables, you can bind them easily:
|
|
21
|
-
|
|
22
|
-
```typescript
|
|
23
|
-
const interval$ = interval(100)
|
|
24
|
-
|
|
25
|
-
const App = () => {
|
|
26
|
-
// observe the returned value of an observable
|
|
27
|
-
const counter = useObserve(interval$)
|
|
28
|
-
|
|
29
|
-
// subscribe to an observable. Similar to observe but
|
|
30
|
-
// does not sync nor return the observable output with react.
|
|
31
|
-
useSubscribe(
|
|
32
|
-
() =>
|
|
33
|
-
interval$.pipe(
|
|
34
|
-
tap((value) => {
|
|
35
|
-
console.log("counter", value)
|
|
36
|
-
})
|
|
37
|
-
),
|
|
38
|
-
[]
|
|
39
|
-
)
|
|
40
|
-
|
|
41
|
-
return <>Counter {counter}</>
|
|
42
|
-
}
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
You may also want to use rxjs intentionally with react to have greater flow control.
|
|
46
|
-
`useObserveCallback` is a version of `useCallback` which use `useSubscribe`:
|
|
47
|
-
|
|
48
|
-
```typescript
|
|
49
|
-
/**
|
|
50
|
-
* useObserveCallback is a version of useCallback which use useSubscribe
|
|
51
|
-
* internally to provide a convenient flow control.
|
|
52
|
-
* In this scenario we have a callback which sync user settings
|
|
53
|
-
* but also:
|
|
54
|
-
* - Cancel any previous request when the user start a new one together
|
|
55
|
-
* - Retry 3 times the request in case of error.
|
|
56
|
-
*
|
|
57
|
-
* This is already a lot in a few lines.
|
|
58
|
-
*/
|
|
59
|
-
const App = () => {
|
|
60
|
-
const [saveSettings] = useObserveCallback(
|
|
61
|
-
(trigger$) =>
|
|
62
|
-
trigger$.pipe(switchMap((options) => from(sync(options)).pipe(retry(3)))),
|
|
63
|
-
[]
|
|
64
|
-
)
|
|
65
|
-
|
|
66
|
-
return (
|
|
67
|
-
<>
|
|
68
|
-
User settings
|
|
69
|
-
<button onClick={() => saveSettings(/** ... */)}>save settings</button>
|
|
70
|
-
</>
|
|
71
|
-
)
|
|
72
|
-
}
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
It is recommended to use native hooks as much as possible but observables can help dealing with more complex use case when needed.
|
|
76
|
-
|
|
77
|
-
## Higher level API: Queries & Mutations
|
|
78
|
-
|
|
79
|
-
Realistically you are unlikely to use the low level API since react already provide convenient way to dea
|
|
80
|
-
|
|
81
|
-
## Global State
|
|
82
|
-
|
|
83
|
-
Because observables are by design observable, well, they are already a perfect candidate for state which is exactly what `signal` is:
|
|
84
|
-
|
|
85
|
-
```typescript
|
|
86
|
-
const [useColorMode, setColorMode] = signal({ default: "day" })
|
|
87
|
-
|
|
88
|
-
const AppBar = () => {
|
|
89
|
-
return (
|
|
90
|
-
<>
|
|
91
|
-
<button
|
|
92
|
-
onClick={() =>
|
|
93
|
-
setColorMode((mode) => (mode === "day" ? "night" : "day"))
|
|
94
|
-
}
|
|
95
|
-
>
|
|
96
|
-
switch mode
|
|
97
|
-
</button>
|
|
98
|
-
</>
|
|
99
|
-
)
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
const App = () => {
|
|
103
|
-
const colorMode = useColorMode()
|
|
104
|
-
|
|
105
|
-
return (
|
|
106
|
-
<>
|
|
107
|
-
<AppBar />
|
|
108
|
-
You are using {colorMode}
|
|
109
|
-
</>
|
|
110
|
-
)
|
|
111
|
-
}
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
# Side effects, mutations and their scopes
|
|
115
|
-
|
|
116
|
-
`reactjrx` provide convenient way or running mutation or side effect both locally or globally.
|
|
117
|
-
`useMutation` is designed to run locally in a component scope and will by default cancel any ongoing mutation
|
|
118
|
-
once you run the same mutation again or if the component unmount. `useSubscribeEffect` and `trigger` however will give
|
|
119
|
-
you a base to build global long running side effects.
|
|
120
|
-
|
|
121
|
-
# Here is a couple of use case to understand what to use and when:
|
|
122
|
-
|
|
123
|
-
## I have a global state that needs to be shared
|
|
124
|
-
|
|
125
|
-
You can use `signal`.
|
|
126
|
-
|
|
127
|
-
## I want to trigger an action from somewhere else in the code
|
|
128
|
-
|
|
129
|
-
You can use `trigger`.
|
|
130
|
-
|
|
131
|
-
## I want to have side effect which runs when a specific action is triggered
|
|
132
|
-
|
|
133
|
-
If your side effect is scoped or local to your component you can use `useMutation`.
|
|
134
|
-
If your side effect needs to be triggered from anywhere and or your side effect is a long
|
|
135
|
-
running process you can use `trigger` and `useSubscribeEffect`.
|
|
136
|
-
|
|
137
|
-
# Low level functions
|
|
138
|
-
|
|
139
|
-
`useObserve` and `useSubscribe` are both the fundamental building blocks of this library. They are exported
|
|
140
|
-
and can be used to easily bind rxjs with react but we recommend you to use higher level function which
|
|
141
|
-
are more suited to use with react. For example `useQuery` replaces `useObserve` and will add error handling,
|
|
142
|
-
automatic retry, logging, loading state, etc. `useSubscribeEffect` is similar to `useSubscribe` but will
|
|
143
|
-
make sure to retry on error, log errors, etc.
|
|
144
|
-
|
|
145
|
-
# Author
|
|
146
|
-
|
|
147
|
-
Maxime Bret (bret.maxime@gmail.com).
|
|
148
|
-
|
|
149
|
-
# License
|
|
150
|
-
|
|
151
|
-
Open source and available under the MIT License.
|
|
5
|
+
Please visit the [documentation](https://bret-maxime.gitbook.io/reactjrx/) for more information on how to use.
|