84 | )
85 | }
86 | })
87 | ```
88 |
89 | ## Replacing Redux Connect
90 | If you are using Redux,
91 | Recycle component can also be used as a container (an alternative to Redux `connect`).
92 |
93 | The advantage of this approach is that you have full control over component rerendering (components will not be "forceUpdated" magically).
94 |
95 | Also, you can listen to a specific part of the state and update your component only if that property is changed.
96 |
97 | ```javascript
98 | export default recycle({
99 | dispatch (sources) {
100 | return [
101 | sources.select('div')
102 | .addListener('onClick')
103 | .mapTo({ type: 'REDUX_ACTION_TYPE', text: 'hello from recycle' })
104 | ]
105 | },
106 |
107 | update (sources) {
108 | return [
109 | sources.store
110 | .reducer(function (state, store) {
111 | return store
112 | })
113 |
114 | /**
115 | * Example of a subscription on a specific store property
116 | * with distinctUntilChanged() component will be updated only when that property is changed
117 | *
118 | * sources.store
119 | * .map(s => s.specificProperty)
120 | * .distinctUntilChanged()
121 | * .reducer(function (state, specificProperty) {
122 | * state.something = specificProperty
123 | * return state
124 | * })
125 | */
126 | ]
127 | },
128 |
129 | view (props, state) {
130 | return
Number of todos: {store.todos.length}
131 | }
132 | })
133 | ```
134 |
135 | ## Effects
136 | If you don't need to update a component local state or dispatch Redux action,
137 | but you still need to react to some kind of async operation, you can use `effects`.
138 |
139 | Recycle will subscribe to this stream but it will not use it.
140 | It is intended for making side effects (like calling callback functions passed from a parent component)
141 |
142 | ```javascript
143 | const Timer = recycle({
144 |
145 | effects (sources) {
146 | return [
147 | sources.select('input')
148 | .addListener('onKeyPress')
149 | .withLatestFrom(sources.props)
150 | .map(([e, props]) => {
151 | props.callParentFunction(e.target.value)
152 | })
153 | ]
154 | },
155 |
156 | view (props) {
157 | return (
158 |
159 | )
160 | }
161 | })
162 | ```
163 |
164 | ## API
165 | Component description object accepts following properties:
166 |
167 | ```javascript
168 | {
169 | propTypes: { name: PropTypes.string },
170 | displayName: 'ComponentName',
171 | initialState: {},
172 | dispatch: function(sources) { return Observable },
173 | update: function(sources) { return Observable },
174 | effects: function(sources) { return Observable },
175 | view: function(props, state) { return JSX }
176 | }
177 | ```
178 |
179 | In `update`, `dispatch` and `effects` functions, you can use the following sources:
180 |
181 | ```javascript
182 | /**
183 | * sources.select
184 | *
185 | * select node by tag name or child component
186 | */
187 | sources.select('tag')
188 | .addListener('event')
189 |
190 | sources.select(ChildComponent)
191 | .addListener('event')
192 |
193 | /**
194 | * sources.selectClass
195 | *
196 | * select node by class name
197 | */
198 | sources.selectClass('classname')
199 | .addListener('event')
200 |
201 | /**
202 | * sources.selectId
203 | *
204 | * select node by its id
205 | */
206 | sources.selectId('node-id')
207 | .addListener('event')
208 |
209 | /**
210 | * sources.store
211 | *
212 | * If you are using redux (component is inside Provider)
213 | * sources.store will emit its state changes
214 | */
215 | sources.store
216 | .reducer(...)
217 |
218 | /**
219 | * sources.state
220 | *
221 | * Stream of current local component state
222 | */
223 | sources.select('input')
224 | .addListener('onKeyPress')
225 | .filter(e => e.key === 'Enter')
226 | .withLatestFrom(sources.state)
227 | .map(([e, state]) => state.someStateValue)
228 | .map(someStateValue => using(someStateValue))
229 |
230 | /**
231 | * sources.props
232 | *
233 | * Stream of current local component props
234 | */
235 | sources.select('input')
236 | .addListener('onKeyPress')
237 | .filter(e => e.key === 'Enter')
238 | .withLatestFrom(sources.props)
239 | .map(([e, props]) => props.somePropsValue)
240 | .map(somePropsValue => using(somePropsValue))
241 |
242 | /**
243 | * sources.lifecycle
244 | *
245 | * Stream of component lifecycle events
246 | */
247 | sources.lifecycle
248 | .filter(e => e === 'componentDidMount')
249 | .do(something)
250 | ```
251 |
252 | ## FAQ
253 |
254 | ### Why would I use it?
255 | - Greater separation of concerns between component presentation and component logic
256 | - You don't need classes so each part of a component can be defined and tested separately.
257 | - Component description is more consistent.
258 | There is no custom `handleClick` events or `this.setState` statements that you need to worry about.
259 | - The State is calculated the same way as for redux store: `state = reducer(state, action)`.
260 | - Redux container looks like a normal component and it's more clear what it does.
261 | - Easy to use in an existing React application (choose components which you wish to convert).
262 |
263 | ### Why would I NOT use it?
264 | - Observables are not your thing.
265 | - You need more control over component lifecycle (like `shouldComponentUpdate`)
266 |
267 | ### What is this? jQuery?
268 | No.
269 |
270 | Although it resembles [query selectors](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector), Recycle uses React’s inline event handlers and doesn’t rely on the DOM. Since selection is isolated per component, no child nodes can ever be accessed.
271 |
272 | ### Can I use CSS selectors?
273 | No.
274 |
275 | Since Recycle doesn't query over your nodes, selectors like `div .class` will not work.
276 |
277 | ### How does it then find selected nodes?
278 | It works by monkeypatching `React.createElement`.
279 | Before a component is rendered, for each element,
280 | if a select query is matched, recycle sets inline event listener.
281 |
282 | Each time event handler dispatches an event,
283 | it calls `selectedNode.rxSubject.next(e)`
284 |
285 | ### Can I use it with React Native?
286 | Yes.
287 |
288 | Recycle creates classical React component which can be safely used in React Native.
289 |
--------------------------------------------------------------------------------
/index.d.ts:
--------------------------------------------------------------------------------
1 | import { Observable } from 'rxjs'
2 | import React from 'react'
3 | import * as PropTypes from 'prop-types'
4 | import { AnyAction } from 'redux'
5 |
6 |
7 | export declare const recycle: recycle.Recycle
8 | export default recycle
9 | export as namespace recycle
10 |
11 |
12 | type ReducerFn = (state: S, value?: any, store?: R) => S
13 | type ReducerObservableFn = (stream: Observable) => Observable<{ reducer: ReducerFn, event: Event }>
14 |
15 |
16 | type DomEvent =
17 | 'onClick' |
18 | 'onKeyUp' |
19 | 'onKeyDown' |
20 | 'onKeyPress' |
21 | 'onBlur' |
22 | 'onChange' |
23 | 'onClose' |
24 | 'onFocus' |
25 | 'onInput' |
26 | 'onMouseMove' |
27 | 'onMouseDown' |
28 | 'onMouseUp' |
29 | 'onMouseOut' |
30 | 'onMouseOver' |
31 | 'onScroll' |
32 | 'onSubmit' |
33 | 'onSelect' |
34 | 'onTouchMove' |
35 | 'onTouchCancel' |
36 | 'onTouchStart' |
37 | 'onWheel'
38 |
39 |
40 | declare module 'rxjs/Observable' {
41 | interface Observable {
42 | /**
43 | * Acts like a Redux reducer, it receives you local component state (and your Redux state, if you are using Redux),
44 | * and returns a new local state
45 | *
46 | * @template S Your Component local state
47 | * @template R Your Redux state
48 | * @param {(state: S, store: R) => S} reducerFn PS: Param store only appears if you are using Redux (Component is inside Provider)
49 | * @example
50 | *
51 | * sources.select('button')
52 | * .addListener('onClick')
53 | * .reducer((state, eventValue) => {
54 | * ...state,
55 | * counter: state.counter + eventValue
56 | * })
57 | *
58 | */
59 | reducer(reducerFn: ReducerFn): ReducerObservableFn
60 | }
61 | }
62 |
63 |
64 | declare namespace recycle {
65 |
66 | interface Listeners {
67 |
68 | /**
69 | * Register a new DOM listener and returns a stream of DOM events
70 | *
71 | * @param event DOM Event to listen to
72 | * @returns {Observable}
73 | * @example
74 | *
75 | * sources.select('button')
76 | * .addListener('onClick')
77 | * .reducer(state => {
78 | * ...state,
79 | * counter: state.counter + 1
80 | * }),
81 | *
82 | */
83 | addListener: (event: T) => Observable
84 | }
85 |
86 | type ReactLifeCycle =
87 | 'componentWillMount' |
88 | 'componentDidMount' |
89 | 'componentWillReceiveProps' |
90 | 'shouldComponentUpdate' |
91 | 'componentWillUpdate' |
92 | 'componentDidUpdate' |
93 | 'componentWillUnmount'
94 |
95 | interface Sources {
96 |
97 | /**
98 | * This method selects a element by tagName or a ChildComponent and returns a recycle.Listeners
99 | *
100 | * @param param
101 | * @returns {recycle.Listeners} Returns { addListener: (event: DomEvent) => Observable }
102 | * @example
103 | *
104 | * PS: Assuming i have a
105 | * sources.select('button')
106 | *
107 | * or
108 | *
109 | * PS: Assuming i have a as a child element.
110 | * sources.select(ChildComponent)
111 | *
112 | */
113 | select: (param: string | React.Component | React.StatelessComponent) => recycle.Listeners;
114 |
115 | /**
116 | * This method selects a element by a CSS class and returns a recycle.Listeners
117 | *
118 | * @param className
119 | * @returns {recycle.Listeners} Returns { addListener: (event: DomEvent) => Observable }
120 | * @example
121 | *
122 | * * PS: Assuming i have a as a child element.
123 | * sources.select('cssClass')
124 | *
125 | */
126 | selectClass: (className: string) => recycle.Listeners;
127 |
128 | /**
129 | * This method selects a element by id and returns a recycle.Listeners
130 | *
131 | * @param id
132 | * @returns {recycle.Listeners} Returns { addListener: (event: DomEvent) => Observable }
133 | * @example
134 | *
135 | * PS: Assuming i have a as a child element.
136 | * sources.select('elementId')
137 | *
138 | */
139 | selectId: (id: string) => recycle.Listeners
140 |
141 | /**
142 | * If you are using Redux (component is inside Provider) this will return a stream of your redux state
143 | *
144 | * @template R is a interface representing your Redux state
145 | * @returns {Observable} Returns a Observable with your latest Redux state
146 | * @example
147 | *
148 | * PS: Assuming R is { count: number }
149 | * sources.store.map((state: { count: number }) => state.count)
150 | *
151 | */
152 | store?: Observable
153 |
154 | /**
155 | * Returns a stream of your local component state
156 | *
157 | * @template S is a interface representing your Component state
158 | * @returns {Observable} Returns a Observable with your latest component state
159 | * @example
160 | *
161 | * sources.select('input')
162 | * .addListener('onKeyPress')
163 | * .filter(e => e.key === 'Enter')
164 | * .withLatestFrom(sources.state)
165 | * .map(([e, state]) => state.someStateValue)
166 | *
167 | */
168 | state: Observable
169 |
170 | /**
171 | * Returns a stream of component lifecycle events
172 | *
173 | * @returns {Observable}
174 | * @example
175 | *
176 | * sources.lifecycle
177 | * .filter(e => e === 'componentDidMount')
178 | * .do(something)
179 | *
180 | */
181 | lifecycle: Observable
182 | }
183 |
184 | interface Params {
185 | /**
186 | * React props passed by JSX
187 | */
188 | propTypes?: PropTypes.ValidationMap
189 |
190 | /**
191 | * Determines the html tag name
192 | */
193 | displayName?: string
194 |
195 | /**
196 | * Component's local initial state
197 | */
198 | initialState?: S
199 |
200 | /**
201 | *
202 | *
203 | * @param sources
204 | * @returns {Observable[]} Array of Redux action streams
205 | */
206 | dispatch?: (sources: recycle.Sources) => Observable[]
207 |
208 | /**
209 | * Acts like a Redux reducer for the component local state
210 | *
211 | * @param sources
212 | * @template S Interface representing the component local state
213 | * @template R Interface representing the Redux state (If using Redux)
214 | * @returns {Observable>[]}
215 | * @example
216 | *
217 | * update: (sources) => {
218 | * return [
219 | * sources.store
220 | * .reducer(function (state, store) {
221 | * return state
222 | * })
223 | * ]
224 | * },
225 | *
226 | */
227 | update?: (sources: recycle.Sources) => ReducerObservableFn[]
228 |
229 | /**
230 | * If you don't need to update a component local state or dispatch Redux action, but you still need to react
231 | * to some kind of async operation, you can use effects.
232 | *
233 | * @param sources
234 | * @returns Observable[]
235 | * @example
236 | *
237 | * effects: (sources) => {
238 | * return [
239 | * sources.select('input')
240 | * .addListener('onKeyPress')
241 | * .withLatestFrom(sources.props)
242 | * .map(([e, props]) => {
243 | * props.callParentFunction(e.target.value)
244 | * })
245 | * ]
246 | * }
247 | *
248 | */
249 | effects?: (sources: recycle.Sources) => Observable[]
250 |
251 | /**
252 | * Returns the JSX to be rendered for the component
253 | *
254 | * @param props
255 | * @param state
256 | * @returns {JSX.Element}
257 | * @example
258 | *
259 | * view: (props, state) =>
260 | *