26 |
27 |
28 | ## Submitting Bugs
29 |
30 | If you encounter an issue with freactal, please [look to see](https://github.com/FormidableLabs/freactal/issues) if the issue has already been reported. If it has not, please [open a new issue](https://github.com/FormidableLabs/freactal/issues/new).
31 |
32 | When submitting a bug report, make sure to include a repro. The best way to do this, is to fork the [freactal-sketch sandbox](https://codesandbox.io/s/github/divmain/freactal-sketch/tree/master/), modify it so that the bug is observable, and include a link in your bug report.
33 |
34 |
35 |
72 |
73 |
74 | ## Guide
75 |
76 | This guide is intended to get you familiar with the `freactal` way of doing things. If you're looking for something specific, take a look at the [API Documentation](#api-documentation). If you're just starting out with `freactal`, read on!
77 |
78 |
79 | ### Containing state
80 |
81 | Most state management solutions for React put all state in one place. `freactal` doesn't suffer from that constraint, but it is a good place to start. So let's see what that might look like.
82 |
83 | ```javascript
84 | import { provideState } from "freactal";
85 |
86 | const wrapComponentWithState = provideState({
87 | initialState: () => ({ counter: 0 })
88 | });
89 | ```
90 |
91 | In the above example, we define a new state container type using `provideState`, and provide it an argument. You can think about the arguments passed to `provideState` as the schema for your state container; we'll get more familiar with the other possible arguments later in the guide.
92 |
93 | The `initialState` function is invoked whenever the component that it is wrapping is instantiated. But so far, our state container is not wrapping anything, so let's expand our example a bit.
94 |
95 | ```javascript
96 | import React, { Component } from "react";
97 | import { render } from "react-dom";
98 |
99 | const Parent = ({ state }) => (
100 |
123 | ));
124 |
125 | render(, document.getElementById("root"));
126 | ```
127 |
128 | Alright, we're getting close. But we're missing one important piece: `injectState`.
129 |
130 | Like `provideState`, `injectState` is a component wrapper. It links your application component with the state that it has access to.
131 |
132 | It may not be readily apparent to you why `injectState` is necessary, so let's make it clear what each `freactal` function is doing. With `provideState`, you define a state template that can then be applied to any component. Once applied, that component will act as a "headquarters" for a piece of state and the effects that transform it (more on that later). If you had a reason, the same template could be applied to multiple components, and they'd each have their own state based on the template you defined.
133 |
134 | But that only _tracks_ state. It doesn't make that state accessible to the developer. That's what `injectState` is for.
135 |
136 | In early versions of `freactal`, the state was directly accessible to the component that `provideState` wrapped. However, that meant that whenever a state change occurred, the entire tree would need to re-render. `injectState` intelligently tracks the pieces of state that you actually access, and a re-render only occurs when _those_ pieces of state undergo a change.
137 |
138 | Alright, so let's finalize our example with all the pieces in play.
139 |
140 | ```javascript
141 | import React, { Component } from "react";
142 | import { render } from "react-dom";
143 | import { provideState, injectState } from "freactal";
144 |
145 | const wrapComponentWithState = provideState({
146 | initialState: () => ({ counter: 0 })
147 | });
148 |
149 | const Parent = wrapComponentWithState(injectState(({ state }) => (
150 |
162 |
163 |
164 | ### Accessing state from a child component
165 |
166 | As was mentioned above, the `provideState`-wrapped component isn't really the one that provides access to state. That's `injectState`'s job. So what would stop you from injecting state into a child component that isn't containing state itself? The answer is nothing!
167 |
168 | Let's modify the example so that we're injecting state into a child component.
169 |
170 | ```javascript
171 | import React, { Component } from "react";
172 | import { render } from "react-dom";
173 | import { provideState, injectState } from "freactal";
174 |
175 |
176 | const Child = injectState(({ state }) => (
177 |
180 | ));
181 |
182 | const wrapComponentWithState = provideState({
183 | initialState: () => ({ counter: 0 })
184 | });
185 |
186 | const Parent = wrapComponentWithState(({ state }) => (
187 |
188 | ));
189 |
190 |
191 | render(, document.getElementById("root"));
192 | ```
193 |
194 | Let's review what's going on here.
195 |
196 | 1. Using `provideState`, we define a state-container template intended to store a single piece of state: the `counter`.
197 | 2. That template is applied to the `Parent` component.
198 | 3. When the `Parent` is rendered, we see that it references a `Child` component.
199 | 4. That `Child` component is wrapped with `injectState`.
200 | 5. Because `Child` is contained within the subtree where `Parent` is the root node, it has access to the `Parent` component's state.
201 |
202 | We could insert another component at the end, and `injectState` into the `GrandChild` component, and it would work the same.
203 |
204 |
205 |
206 |
207 |
208 | ### Transforming state
209 |
210 | Alright, so we know how to setup state containers, give them an initial state, and consume that state from child components. But all of this is not very useful if state is never updated. That's where effects come in.
211 |
212 | Effects are the one and only way to change `freactal` state in your application. These effects are defined as part of your state container template when calling `provideState`, and they can be invoked from anywhere that state has been injected (with `injectState`).
213 |
214 | Let's take a look at that first part.
215 |
216 | ```javascript
217 | const wrapComponentWithState = provideState({
218 | initialState: () => ({ counter: 0 }),
219 | effects: {
220 | addOne: () => state => Object.assign({}, state, { counter: state.counter + 1 })
221 | }
222 | });
223 | ```
224 |
225 | You might be wondering why we have that extra `() =>` right before `state =>` in the `addOne` definition. That'll be explained in the next section - for now, let's look at all the other pieces.
226 |
227 | In the above example, we've defined an effect that, when invoked, will update the `counter` in our state container by adding `1`.
228 |
229 | Since updating an element of state based on previous state (and potentially new information) is something you'll be doing often, `freactal` [provides a shorthand](#update) to make this a bit more readable:
230 |
231 | ```javascript
232 | const wrapComponentWithState = provideState({
233 | initialState: () => ({ counter: 0 }),
234 | effects: {
235 | addOne: update(state => ({ counter: state.counter + 1 }))
236 | }
237 | });
238 | ```
239 |
240 | Now let's look at how you might trigger this effect:
241 |
242 | ```javascript
243 | const Child = injectState(({ state, effects }) => (
244 |
248 | ));
249 | ```
250 |
251 | Wherever your `` is in your application, the state and effects it references will be accessible, so long as the state container is somewhere further up in the tree.
252 |
253 |
254 |
255 |
256 | ### Transforming state (cont.)
257 |
258 | If you've used Redux, effects are roughly comparable to an action-reducer pair, with a couple of important differences.
259 |
260 | The first of those differences relates to asychronicity. Under the hood, `freactal` relies heavily on `Promise`s to schedule state updates. In fact, the following effects are all functionally equivalent:
261 |
262 | ```javascript
263 | addOne: () => state => Object.assign({}, state, { counter: state.counter + 1 })
264 | /* vs */
265 | addOne: () => Promise.resolve(state => Object.assign({}, state, { counter: state.counter + 1 }))
266 | /* vs */
267 | addOne: () => new Promise(resolve => resolve(state => Object.assign({}, state, { counter: state.counter + 1 })))
268 | ```
269 |
270 | To put it explicitly, the value you provide for each key in your `effects` object is:
271 |
272 | 1. A function that takes in some arguments (we'll cover those shortly) and returns...
273 | 2. A promise that resolves to...
274 | 3. A function that takes in state and returns...
275 | 4. The updated state.
276 |
277 | Step 2 can optionally be omitted, since `freactal` wraps these values in `Promise.resolve`.
278 |
279 | For most developers, this pattern is probably the least familiar of those that `freactal` relies upon. But it allows for some powerful and expressive state transitions with basically no boilerplate.
280 |
281 | For example, any number of things can occur between the time that an effect is invoked and the time that the state is updated. These "things" might include doing calculations, or talking to an API, or integrating with some other JS library.
282 |
283 | So, you might define the following effect:
284 |
285 | ```javascript
286 | updatePosts: () => fetch("/api/posts")
287 | .then(result => result.json())
288 | .then(({ posts }) => state => Object.assign({}, state, { posts }))
289 | ```
290 |
291 | In other words, any action that your application might take, that ultimately _could_ result in a state change can be simply expressed as an effect. Not only that, but this pattern also allows for effects and UI components to be tested with clean separation.
292 |
293 | And, perhaps most importantly, this pattern allows for intermediate state.
294 |
295 |
296 |
297 |
298 |
299 | ### Intermediate state
300 |
301 | So far, we haven't see any arguments to the first, outer-most function in our effect definitions. In simple scenarios, this outer-function may seem unnecessary, as in the illustration above.
302 |
303 | But what about cases where you want state to be updated part-way through an operation? You _could_ put all this logic in your UI code, and invoke effects from there multiple times. But that's not ideal for a number of reasons:
304 |
305 | 1. A single effect might be invoked from multiple places in your application.
306 | 2. The code that influences how state might be transformed is now living in multiple places.
307 | 3. It is much harder to test.
308 |
309 | Fundamentally, the problem is that this pattern violates the principle of separation of concerns.
310 |
311 | So, what's the alternative?
312 |
313 | Well, we've already defined an effect as a function that, when invoked, will resolve to another function that transforms state. Why couldn't we re-use this pattern to represent this "part-way" (or intermediate) state? The answer is: nothing is stopping us!
314 |
315 | The first argument passed to an effect in the outer function is the same `effects` object that is exposed to components where state has been injected. And these effects can be invoked in the same way. Even more importantly, because effects always resolve to a `Promise`, we can wait for an intermediate state transition to complete before continuing with our original state transition.
316 |
317 | That might be a lot to take in, so let's look at an example:
318 |
319 | ```javascript
320 | const wrapComponentWithState = provideState({
321 | initialState: () => ({
322 | posts: null,
323 | postsPending: false
324 | }),
325 | effects: {
326 | setPostsPending: update((state, postsPending) => ({ postsPending })),
327 | getPosts: effects => effects.setPostsPending(true)
328 | .then(() => fetch("/api/posts"))
329 | .then(result => result.json())
330 | .then(({ posts }) => effects.setPostsPending(false).then(() => posts))
331 | .then(posts => state => Object.assign({}, state, { posts }))
332 | }
333 | });
334 | ```
335 |
336 | There's a lot going on there, so let's go through it piece by piece.
337 |
338 | - The initial state is set with two keys, `posts` and `postsPending`.
339 | + `posts` will eventually contain an array of blog posts or something like that.
340 | + `postsPending` is a flag that, when `true`, indicates that we are currently fetching the `posts`.
341 | - Two `effects` are defined.
342 | + `setPostsPending` sets the `postsPending` flag to either `true` or `false`.
343 | + `getPosts` does a number of things:
344 | * It invokes `setPostsPending`, setting the pending flag to `true`.
345 | * It waits for the `setPostsPending` effect to complete before continuing.
346 | * It fetches some data from an API.
347 | * It parses that data into JSON.
348 | * It invokes `setPostsPending` with a value of `false`, and waits for it to complete.
349 | * It resolves to a function that updates the `posts` state value.
350 |
351 | In the above example, `setPostsPending` has a synchronous-like behavior - it immediately resolves to a state update function. But it could just as easily do something asynchronous, like make an AJAX call or interact with the IndexedDB API.
352 |
353 | And because all of this is just `Promise` composition, you can put together helper functions that give consistency to intermediate state updates. Here's an example:
354 |
355 | ```javascript
356 | const wrapWithPending = (pendingKey, cb) => effects =>
357 | effects.setFlag(pendingKey, true)
358 | .then(cb)
359 | .then(value => effects.setFlag(pendingKey, false).then(() => value));
360 | ```
361 |
362 | Which could be consumed like so:
363 |
364 | ```javascript
365 | const wrapComponentWithState = provideState({
366 | initialState: () => ({
367 | posts: null,
368 | postsPending: false
369 | }),
370 | effects: {
371 | setFlag: update((state, key, value) => ({ [key]: value })),
372 | getPosts: wrapWithPending("postsPending", () => fetch("/api/posts")
373 | .then(result => result.json())
374 | .then(({ posts }) => state => Object.assign({}, state, { posts }))
375 | )
376 | }
377 | });
378 | ```
379 |
380 |
381 |
382 |
383 |
384 | ### Effect arguments
385 |
386 | But what if you want to update state with some value that you captured from the user? In Redux parlance: what about action payloads?
387 |
388 | If you were looking closely, you may have noticed we already did something like that when we invoked `setPostsPending`.
389 |
390 | Whether you are invoking an effect from your UI code or from another effect, you can pass arguments directly with the invocation. Those arguments will show up after the `effects` argument in your effect definition.
391 |
392 | Here's an example:
393 |
394 | ```javascript
395 | const wrapComponentWithState = provideState({
396 | initialState: () => ({ thing: "val" }),
397 | effects: {
398 | setThing: (effects, newVal) => state => Object.assign({}, state, { thing: newVal })
399 | }
400 | });
401 | ```
402 |
403 | And it could invoked from your component like so:
404 |
405 | ```javascript
406 | const Child = injectState(({ state, effects }) => {
407 | const onClick = () => effects.setThing("new val");
408 | return (
409 |
410 | { `Our "thing" value is: ${state.thing}` }
411 |
412 |
413 | );
414 | });
415 | ```
416 |
417 |
418 |
419 |
420 |
421 | ### Computed state values
422 |
423 | As an application grows, it becomes increasingly important to have effective organizational tools. This is especially true for how you store and transform data.
424 |
425 | Consider the following state container:
426 |
427 | ```javascript
428 | const wrapComponentWithState = provideState({
429 | initialState: () => ({
430 | givenName: "Walter",
431 | familyName: "Harriman"
432 | }),
433 | effects: {
434 | setGivenName: update((state, val) => ({ givenName: val })),
435 | setFamilyName: update((state, val) => ({ familyName: val }))
436 | }
437 | });
438 | ```
439 |
440 | Let's say that we're implementing a component and we want to display the user's full name. We might write that component like this:
441 |
442 | ```javascript
443 | const WelcomeMessage = injectState(({ state }) => {
444 | const fullName = `${state.givenName} ${state.familyName}`;
445 | return (
446 |
447 | {`Hi, ${fullName}, and welcome!`}
448 |
449 | );
450 | });
451 | ```
452 |
453 | That seems like a pretty reasonable piece of code. But, even for a small piece of data like a full name, things can get more complex as the application grows.
454 |
455 | What if we're displaying that full name in multiple components? Should we compute it in all those places, or maybe inject state further up the tree and pass it down as a prop? That can get messy to the point where you're passing down dozens of props.
456 |
457 | What if the user is in a non-English locale, where they may not place given names before family names? We would have to remember to do that everywhere.
458 |
459 | And what if we want to derive another value off of the generated `fullName` value? What about multiple derived values, derived from other derived values? What if we're not dealing with names, but more complex data structures instead?
460 |
461 | `freactal`'s answer to this is computed values.
462 |
463 | You've probably run into something like this before. Vue.js has computed properties. MobX has computed values. Redux outsources this concern to libraries like `reselect`. Ultimately, they all serve the same function: exposing compound values to the UI based on simple state values.
464 |
465 | Here's how you define computed values in `freactal`, throwing in some of the added complexities we mentioned:
466 |
467 | ```javascript
468 | const wrapComponentWithState = provideState({
469 | initialState: () => ({
470 | givenName: "Walter",
471 | familyName: "Harriman",
472 | locale: "en-us"
473 | }),
474 | effects: {
475 | setGivenName: update((state, val) => ({ givenName: val })),
476 | setFamilyName: update((state, val) => ({ familyName: val }))
477 | },
478 | computed: {
479 | fullName: ({ givenName, familyName, locale }) => startsWith(locale, "en") ?
480 | `${givenName} ${familyName}` :
481 | `${familyName} ${givenName}`,
482 | greeting: ({ fullName, locale }) => startsWith(locale, "en") ?
483 | `Hi, ${fullName}, and welcome!` :
484 | `Helló ${fullName}, és szívesen!`
485 | }
486 | });
487 | ```
488 |
489 | _**Note:** This is not a replacement for a proper internationalization solution like `react-intl`, and is for illustration purposes only._
490 |
491 | Here we see two computed values, `fullName` and `greeting`. They both rely on the `locale` state value, and `greeting` actually relies upon `fullName`, whereas `fullName` relies on the given and family names.
492 |
493 | How might that be consumed?
494 |
495 | ```javascript
496 | const WelcomeMessage = injectState(({ state }) => (
497 |
498 | {state.greeting}
499 |
500 | ));
501 | ```
502 |
503 | In another component, we might want to just use the `fullName` value:
504 |
505 | ```javascript
506 | const Elsewhere = injectState(({ state }) => (
507 |
508 | {`Are you sure you want to do that, ${state.fullName}?`}
509 |
510 | ));
511 | ```
512 |
513 | Hopefully you can see that this can be a powerful tool to help you keep your code organized and readable.
514 |
515 | Here are a handful of other things that will be nice for you to know.
516 |
517 | - Computed values are generated _lazily_. This means that if the `greeting` value above is never accessed, it will never be computed.
518 | - Computed values are _cached_. Once a computed value is calculated once, a second state retrieval will return the cached value.
519 | - Cached values are _invalidated_ when dependencies change. If you were to trigger the `setGivenName` effect with a new name, the `fullName` and `greeting` values would be recomputed as soon as React re-rendered the UI.
520 |
521 | That's all you need to know to use computed values effectively!
522 |
523 |
524 |
525 |
526 |
527 | ### Composing multiple state containers
528 |
529 | We started this guide by noting that, while most React state libraries contain state in a single place, `freactal` approaches things differently.
530 |
531 | Before we dive into how that works, let's briefly consider some of the issues that arise with the centralized approach to state management:
532 |
533 | - Oftentimes, it is hard to know how to organize state-related code. Definitions for events or actions live separately from the UI that triggers them, which lives separately from functions that reduce those events into state, which also live separately from code that transforms state into more complex values.
534 | - While React components are re-usable ([see](http://www.material-ui.com/) [component](http://elemental-ui.com/) [libraries](https://github.com/brillout/awesome-react-components)), complex stateful components are a hard nut to crack. There's this fuzzy line when addressing complexity in your own code that, when crossed, means you should be using a state library vs React's own `setState`. But how do you make that work DRY across applications and team boundaries?
535 | - Sometimes you might want to compose full SPAs together in various ways, but if they need to interact on the page or share state in some way, how do you go about accomplishing this? The results here are almost universally ad-hoc.
536 | - It is an often arduous process when it comes time to refactor your application and move state-dependant components into different parts of your application. Wiring everything up can be tedious as hell.
537 |
538 | These are constraints that `freactal` aims to address. Let's take a look at a minimal example:
539 |
540 | ```javascript
541 | const Child = injectState(({ state }) => (
542 |
543 | This is the Child.
544 | {state.fromParent}
545 | {state.fromGrandParent}
546 |
565 | ));
566 | ```
567 |
568 | Its important to notice here that `Child` was able to access state values from both its `Parent` and its `GrandParent`. All state keys will be accessible from the `Child`, unless there is a key conflict between `Parent` and `GrandParent` (in which case `Parent` "wins").
569 |
570 | This pattern allows you to co-locate your code by feature, rather than by function. In other words, if you're rolling out a new feature for your application, all of that new code - UI, state, effects, etc - can go in one place, rather than scattered across your code-base.
571 |
572 | Because of this, refactoring becomes easier. Want to move a component to a different part of your application? Just move the directory and update the import from the parents. What if this component accesses parent state? If that parent is still an anscestor, you don't have to change a thing. If it's not, moving that state to a more appropriate place should be part of the refactor anyway.
573 |
574 | But one word of warning: accessing parent state can be powerful, and very useful, but it also necessarily couples the child state to the parent state. While the coupling is a "loose" coupling, it still may introduce complexity that should be carefully thought-out.
575 |
576 | One more thing.
577 |
578 | Child effects can also trigger parent effects. Let's say your UX team has indicated that, whenever an API call is in flight, a global spinner should be shown. But maybe the data is only needed in certain parts of the application. In this scenario, you could define `beginApiCall` and `completeApiCall` effects that track how many API calls are active. If above `0`, you show a spinner. These effects can be accessed by call-specific effects further down in the state hierarchy, like so:
579 |
580 | ```javascript
581 | const Child = injectState(({ state, effects }) => (
582 |
583 | This is the Child.
584 | {state.fromParent}
585 | {state.fromGrandParent}
586 |
591 |
622 | ));
623 | ```
624 |
625 |
626 | ## Testing
627 |
628 | Before wrapping up, let's take a look at one additional benefit that `freactal` brings to the table: the ease of test-writing.
629 |
630 | If you hadn't noticed already, all of the examples we've looked at in this guide have relied upon [stateless functional components](https://hackernoon.com/react-stateless-functional-components-nine-wins-you-might-have-overlooked-997b0d933dbc). This is no coincidence - from the beginning, a primary goal of `freactal` was to encapsulate _all_ state in `freactal` state containers. That means you shouldn't need to use React's `setState` at all.
631 |
632 | **Here's the bottom line:** because _all_ state can be contained within `freactal` state containers, the rest of your application components can be ["dumb components"](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0).
633 |
634 | This approach allows you to test your state and your components completely independent from one another.
635 |
636 | Let's take a look at a simplified example from above, and then dive into how you might test this application. For the purposes of this example, I assume you're using Mocha, Chai, Sinon, sinon-chai, and Enzyme.
637 |
638 | First, our application code:
639 |
640 | ```javascript
641 | /*** app.js ***/
642 |
643 | import { wrapComponentWithState } from "./state";
644 |
645 |
646 | export const App = ({ state, effects }) => {
647 | const { givenName, familyName, fullName, greeting } = state;
648 | const { setGivenName, setFamilyName } = effects;
649 |
650 | const onChangeGiven = ev => setGivenName(ev.target.value);
651 | const onChangeFamily = ev => setFamilyName(ev.target.value);
652 |
653 | return (
654 |
655 |
656 | { greeting }
657 |
658 |
659 |
660 |
661 |
662 |
663 |
664 |
665 | );
666 | };
667 |
668 | /* Notice that we're exporting both the unwrapped and the state-wrapped component... */
669 | export default wrapComponentWithState(App);
670 | ```
671 |
672 | And then our state template:
673 |
674 | ```javascript
675 | /*** state.js ***/
676 |
677 | import { provideState, update } from "freactal";
678 |
679 | export const wrapComponentWithState = provideState({
680 | initialState: () => ({
681 | givenName: "Walter",
682 | familyName: "Harriman"
683 | }),
684 | effects: {
685 | setGivenName: update((state, val) => ({ givenName: val })),
686 | setFamilyName: update((state, val) => ({ familyName: val }))
687 | },
688 | computed: {
689 | fullName: ({ givenName, familyName }) => `${givenName} ${familyName}`,
690 | greeting: ({ fullName }) => `Hi, ${fullName}, and welcome!`
691 | }
692 | });
693 | ```
694 |
695 | Next, let's add a few tests!
696 |
697 |
698 | ### Stateless functional components
699 |
700 | Remember, our goal here is to test state and UI in isolation. Read through the following example to see how you might make assertions about 1) data-driven UI content, and 2) the ways in which your UI might trigger an effect.
701 |
702 | ```javascript
703 | /*** app.spec.js ***/
704 |
705 | import { mount } from "enzyme";
706 | // Make sure to import the _unwrapped_ component here!
707 | import { App } from "./app";
708 |
709 |
710 | // We'll be re-using these values, so let's put it here for convenience.
711 | const state = {
712 | givenName: "Charlie",
713 | familyName: "In-the-box",
714 | fullName: "Charlie In-the-box",
715 | greeting: "Howdy there, kid!"
716 | };
717 |
718 | describe("my app", () => {
719 | it("displays a greeting to the user", () => {
720 | // This test should be easy - all we have to do is ensure that
721 | // the string that is passed in is displayed correctly!
722 |
723 | // We're not doing anything with effects here, so let's not bother
724 | // setting them for now...
725 | const effects = {};
726 |
727 | // First, we mount the component, providing the expected state and effects.
728 | const el = mount();
729 |
730 | // And then we can make assertions on the output.
731 | expect(el.find("#greeting").text()).to.equal("Howdy there, kid!");
732 | });
733 |
734 | it("accepts changes to the given name", () => {
735 | // Next we're testing the conditions under which our component might
736 | // interact with the provided effects.
737 | const effects = {
738 | setGivenName: sinon.spy(),
739 | setFamilyName: sinon.spy()
740 | };
741 |
742 | const el = mount();
743 |
744 | // Using `sinon-chai`, we can make readable assertions about whether
745 | // a spy function has been called. We don't expect our effect to
746 | // be invoked when the component mounts, so let's make that assertion
747 | // here.
748 | expect(effects.setGivenName).not.to.have.been.called;
749 | // Next, we can simulate a input-box value change.
750 | el.find("input.given").simulate("change", {
751 | target: { value: "Eric" }
752 | });
753 | // And finally, we can assert that the effect - or, rather, the Sinon
754 | // spy that is standing in for the effect - was invoked with the expected
755 | // value.
756 | expect(effects.setGivenName).to.have.been.calledWith("Eric");
757 | });
758 | });
759 | ```
760 |
761 | That takes care of your SFCs. This should really be no different than how you might have been testing your presentational components in the past, except that with `freactal`, this is the _only_ sort of testing you need to do for your React components.
762 |
763 |
764 | ### State and effects
765 |
766 | Next up is state. As you read through the example below, take note that we can make assertions about the initial state and any expected transformations to that state without involving a React component or rendering to the DOM.
767 |
768 | ```javascript
769 | /*** state.spec.js ***/
770 |
771 | import { wrapComponentWithState } from "./state";
772 |
773 | describe("state container", () => {
774 | it("supports fullName", () => {
775 | // Normally, you'd pass a component as the first argument to your
776 | // state template. However, if you pass no argument to the state
777 | // template, you'll get back a test instance that you can extract
778 | // `state` and `effects` from. Just don't try to render the thing!
779 | const { effects, getState } = wrapComponentWithState();
780 |
781 | expect(getState().fullName).to.equal("Walter Harriman");
782 |
783 | // Since effects return a Promise, we're going to make it easy
784 | // on ourselves and wrap all of our assertions from this point on
785 | // inside a Promise.
786 | return Promise.resolve()
787 | // When a Promise is provided as the return value to a Promise's
788 | // `.then` callback, the outer Promise awaits the inner before
789 | // any subsequent callbacks are fired.
790 | .then(() => effects.setGivenName("Alfred"))
791 | // Now that `givenName` has been set to "Alfred", we can make an
792 | // assertion...
793 | .then(() => expect(getState().fullName).to.equal("Alfred Harriman"))
794 | // Then we can do the same for the family name...
795 | .then(() => effects.setFamilyName("Hitchcock"))
796 | // And make one final assertion.
797 | .then(() => expect(getState().fullName).to.equal("Alfred Hitchcock"));
798 | });
799 |
800 | // You could write similar assertions here
801 | it("supports a greeting");
802 | });
803 | ```
804 |
805 | That's it for testing!
806 |
807 |
808 |
809 |
810 |
811 | ### Conclusion
812 |
813 | We hope that you found this guide to be helpful!
814 |
815 | If you find that a piece is missing that would've helped you understand `freactal`, please feel free to [open an issue](https://github.com/FormidableLabs/freactal/issues/new). For help working through a problem, [reach out on Twitter](http://twitter.com/divmain), open an issue, or ping us on [Gitter](https://gitter.im/FormidableLabs/freactal).
816 |
817 | You can also read through the API docs below!
818 |
819 |
820 |
821 |
822 |
823 | ## API Documentation
824 |
825 | ### `provideState`
826 |
827 | This is used to define a state container, which in turn can wrap one of your application components.
828 |
829 | ```javascript
830 | const StatefulComponent = provideState({/* options */})(StatelessComponent);
831 | ```
832 |
833 | The `options` argument is an object with one or more of the following keys: `initialState`, `effects`, `initialize`, and `computed`.
834 |
835 |
836 | #### `initialState`
837 |
838 | A function defining the state of your state container when it is first initialized.
839 |
840 | This function is invoked both on the server during a server-side render and on the client. However, you might employ environment detection in order to yield divergent results.
841 |
842 | ```javascript
843 | provideState({
844 | initialState: () => ({
845 | a: "value will",
846 | b: "set here"
847 | })
848 | })
849 | ```
850 | Component props can be passed to `initialState` like so :
851 |
852 | ```javascript
853 | provideState({
854 | initialState: ({ value }) => ({
855 | a: value,
856 | b: "set here"
857 | })
858 | })
859 | ```
860 |
861 |
862 | #### `effects`
863 |
864 | Effects are the mechanism by which state is updated.
865 |
866 | The `effects` value should be an object, where the keys are function names (that you will later) and the values are functions.
867 |
868 | Each effect will be provided one or more arguments: an `effects` reference (see note below), and any arguments that are passed to the function when they're invoked in application code.
869 |
870 | The return value is either 1) a function that takes in old state and returns new state or, 2) a Promise that resolves to #1.
871 |
872 | This may seem opaque, so please refer to the [guide](#effect-arguments) for information on how to use them effectively.
873 |
874 | ```javascript
875 | provideState({
876 | effects: {
877 | doThing: (effects, argA) =>
878 | Promise.resolve(state => Object.assign({}, state, { val: argA }))
879 | }
880 | });
881 | ```
882 |
883 | **NOTE 1:** The effects are called synchronously so you that you can use directly any passed events:
884 |
885 | ```javascript
886 | provideState({
887 | effects: {
888 | onInputChange: (effects, event) => {
889 | const { value } = event.target
890 | return state =>
891 | Object.assign({}, state, { inputValue: value })
892 | }
893 | }
894 | });
895 |
896 | const MyComponent = injectState(({ effects, state }) => (
897 |
898 | ))
899 | ```
900 |
901 | **NOTE 2:** The `effects` object that is passed to each effect is _not_ the same as the outer effects object that you define here. Instead, that object is a composition of the hierarchy of stateful effects.
902 |
903 | ##### `initialize`
904 |
905 | Each state container can define a special effect called `initialize`. This effect has props passed in as a second argument and will be implicitly invoked in two circumstances:
906 |
907 | 1. During SSR, each state container with an `initialize` effect will invoke it, and the rendering process will await the resolution of that effect before continuing with rendering.
908 | 2. When running in the browser, each state container with an `initialize` effect will invoke it when the container is mounted into the DOM.
909 |
910 | Note: this effect will NOT be passed down to a component's children.
911 |
912 |
913 | #### `computed`
914 |
915 | The `computed` object allows you to define compound state values that depend on basic state values or other computed values.
916 |
917 | The value provided as the `computed` option should be an object where each key is the name by which the computed value will be referenced, and each value is a function taking in state and returning a computed value.
918 |
919 | ```javascript
920 | provideState({
921 | initialState: () => ({
922 | a: "value will",
923 | b: "set here"
924 | }),
925 | computed: {
926 | aPlusB: ({ a, b }) => `${a} + ${b}`, // "value will + set here"
927 | typeOfAPlusB: ({ aPlusB }) => typeof aPlusB // "string"
928 | }
929 | })
930 | ```
931 |
932 | Props can't be passed to `computed`
933 |
934 | #### `middleware`
935 |
936 | Middleware is defined per state container, not globally. Each middleware function will be invoked in the order provided whenever a state change has occurred.
937 |
938 | With middleware, you should be able to inject new state values, intercept effects before they begin, track when effects complete, and modify the way in which sub-components interact and respond to state containers further up the tree.
939 |
940 | To write middleware effectively, you'll probably want to take a look at the Freactal's internal `buildContext` method. Fortunately it is pretty straightforward.
941 |
942 | The following is an example that will log out whenever an effect is invoked, the arguments it was provided, and when the effect completed:
943 |
944 | ```javascript
945 | provideState({
946 | middleware: [
947 | freactalCxt => Object.assign({}, freactalCxt, {
948 | effects: Object.keys(freactalCxt.effects).reduce((memo, key) => {
949 | memo[key] = (...args) => {
950 | console.log("Effect started", key, args);
951 | return freactalCxt.effects[key](...args).then(result => {
952 | console.log("Effect completed", key);
953 | return result;
954 | })
955 | };
956 | return memo;
957 | }, {})
958 | })
959 | ]
960 | })
961 | ```
962 |
963 |
964 | ### `injectState`
965 |
966 | While `provideState` supplies the means by which you declare your state and its possible transitions, `injectState` is the means by which you access `state` and `effects` from your UI code.
967 |
968 | By default, `injectState` will detect the keys that you access in your component, and will only force a re-render if those keys change in the upstream state container.
969 |
970 | ```javascript
971 | const StatelessComponent = ({ state: { myValue } }) =>
972 |
{ myValue }
973 | const WithState = injectState(StatelessComponent);
974 | ```
975 |
976 | In the above example, `StatelessComponent` would only be re-rendered a second time if `myValue` changed in the upstream state container.
977 |
978 | However, it is possible to explicitly define which keys you want to "listen" to. When using this form, the keys that you specify are injected into the wrapped component as props.
979 |
980 | ```javascript
981 | const StatelessComponent = ({ myValue }) =>
982 |
{ myValue }
983 | const StatefulComponent = injectState(StatelessComponent, ["myValue", "otherValueToo"]);
984 | ```
985 |
986 | In this example, `StatelessComponent` would re-render when `myValue` changed, but it would also re-render when `otherValueToo` changed, even though that value is not used in the component.
987 |
988 |
989 | ### `hydrate` and `initialize`
990 |
991 | These functions are used to deeply initialize state in the SSR context and then re-hydrate that state on the client. For more information about how to use these functions, see the below documentation on [Server-side Rendering](#server-side-rendering).
992 |
993 |
994 |
995 |
996 |
997 | ## Helper functions
998 |
999 | You may find the following functions handy, as a shorthand for common tasks.
1000 |
1001 |
1002 | ### `update`
1003 |
1004 | This handy helper provides better ergonomics when defining an effect that updates state.
1005 |
1006 | It can be consumed like so:
1007 |
1008 | ```javascript
1009 | import { provideState, update } from "freactal";
1010 | const wrapComponentWithState = provideState({
1011 | // ...
1012 | effects: {
1013 | myEffect: update({ setThisKey: "to this value..." })
1014 | }
1015 | });
1016 | ```
1017 |
1018 | Which is equivalent to the following:
1019 |
1020 | ```javascript
1021 | import { provideState } from "freactal";
1022 | const wrapComponentWithState = provideState({
1023 | // ...
1024 | effects: {
1025 | myEffect: () => state => Object.assign({}, state, { setThisKey: "to this value..." })
1026 | }
1027 | });
1028 | ```
1029 |
1030 | When your update _is_ dependant on the previous state you can pass a function, like so:
1031 |
1032 | ```javascript
1033 | import { provideState, update } from "freactal";
1034 | const wrapComponentWithState = provideState({
1035 | // ...
1036 | effects: {
1037 | myEffect: update(state => ({ counter: state.counter + 1 }))
1038 | }
1039 | });
1040 | ```
1041 |
1042 | Which is equivalent to the following:
1043 |
1044 | ```javascript
1045 | import { provideState } from "freactal";
1046 | const wrapComponentWithState = provideState({
1047 | // ...
1048 | effects: {
1049 | myEffect: () => state => Object.assign({}, state, { counter: state.counter + 1 })
1050 | }
1051 | });
1052 | ```
1053 |
1054 | Any arguments that are passed to the invocation of your effect will also be passed to the function you provide to `update`.
1055 |
1056 | I.e.
1057 |
1058 | ```javascript
1059 | effects: {
1060 | updateCounterBy: (effects, addVal) => state => Object.assign({}, state, { counter: state.counter + addVal })
1061 | }
1062 | ```
1063 |
1064 | is equivalent to:
1065 |
1066 | ```javascript
1067 | effects: {
1068 | myEffect: update((state, addVal) => ({ counter: state.counter + addVal }))
1069 | }
1070 | ```
1071 |
1072 |
1073 | ### `mergeIntoState`
1074 |
1075 | `update` is intended for synchronous updates only. But writing out a state-update function for asynchronous effects can get tedious. That's where `mergeIntoState` comes in.
1076 |
1077 | ```javascript
1078 | mergeIntoState(newData)
1079 | ```
1080 |
1081 | ... is exactly equivalent to...
1082 |
1083 | ```javascript
1084 | state => Object.assign({}, state, newData)
1085 | ```
1086 |
1087 | Here's what it might look like in practice:
1088 |
1089 | ```javascript
1090 | export const getData = (effects, dataId) => fetch(`http://some.url/${dataId}`)
1091 | .then(response => response.json())
1092 | .then(body => mergeIntoState({ data: body.data }));
1093 | ```
1094 |
1095 |
1096 |
1097 |
1098 |
1099 | ## Server-side Rendering
1100 |
1101 | Historically, server-side rendering of stateful React applications has involved many moving pieces. `freactal` aims to simplify this area without sacrificing the power of its fractal architecture.
1102 |
1103 | There are two parts to achieving SSR with `freactal`: state initialization on the server, and state hydration on the client.
1104 |
1105 | Keep in mind that, if you have a state container whose state needs to be initialized in a particular way, you should take a look at the [`initialize`](#initialize) effect.
1106 |
1107 | `freactal` supports both React's built-in `renderToString` method, as well as the newer [Rapscallion](https://github.com/FormidableLabs/rapscallion).
1108 |
1109 | ### with `React#renderToString`
1110 |
1111 | On the server, you'll need to recursively initialize your state tree. This is accomplished with the `initialize` function, provided by `freactal/server`.
1112 |
1113 | ```javascript
1114 | /* First, import renderToString and the initialize function. */
1115 | import { renderToString } from "react-dom/server";
1116 | import { initialize } from "freactal/server";
1117 |
1118 | /*
1119 | Within the context of your Node.js server route, pass the root component to
1120 | the initialize function.
1121 | */
1122 | initialize()
1123 | /* This invocation will return a Promise that resolves to VDOM and state */
1124 | .then(({ vdom, state }) => {
1125 | /* Pass the VDOM to renderToString to get HTML out. */
1126 | const appHTML = renderToString(vdom);
1127 | /*
1128 | Pass your application HTML and the application state (an object) to a
1129 | function that inserts application HTML into and tags,
1130 | serializes state, and inserts that state into an accessible part of
1131 | the DOM.
1132 | */
1133 | const html = boilerplate(appHTML, state);
1134 | /* Finally, send the full-page HTML to the client */
1135 | return res.send(html).end();
1136 | })
1137 | ```
1138 |
1139 | You can find a full `freactal` example, including a server and SSR [here](https://github.com/FormidableLabs/freactal/tree/master/example).
1140 |
1141 |
1142 | ### with Rapscallion
1143 |
1144 | The above method involves a partial render of your application (`initialize`), ultimately relying upon `React.renderToString` to transform the VDOM into an HTML string. This is because `renderToString` is synchronous, and `freactal` is asynchronous by design.
1145 |
1146 | Because Rapscallion is also asynchronous by design, there is even less ceremony involved.
1147 |
1148 | ```javascript
1149 | /* First, import Rapscallion's render and the captureState function. */
1150 | import { render } from "rapscallion";
1151 | import { captureState } from "freactal/server";
1152 |
1153 | /*
1154 | Within the context of your Node.js server route, invoke `captureState` with your root component.
1155 | */
1156 | const { Captured, state } = captureState();
1157 |
1158 | /* Pass the component to Rapscallion's renderer */
1159 | render()
1160 | .toPromise()
1161 | .then(appHTML => {
1162 | /*
1163 | At this point, the `state` object will be fully populated with your
1164 | state tree's data.
1165 |
1166 | Pass your application HTML and state to a function that inserts
1167 | application HTML into and tags, serializes state, and
1168 | inserts that state into an accessible part of the DOM.
1169 | */
1170 | const html = boilerplate(appHTML, state);
1171 | /* Finally, send the full-page HTML to the client */
1172 | return res.send(html).end();
1173 | });
1174 | ```
1175 |
1176 |
1177 | ### Hydrate state on the client
1178 |
1179 | Using one of the above methods, you can capture your application state while server-side rendering and insert it into the resulting HTML. The final piece of the SSR puzzle is re-hydrating your state containers inside the browser.
1180 |
1181 | This is accomplished with `hydrate` in the context of your `initialState` function.
1182 |
1183 | Assuming you've serialized the SSR state and exposed it as `window.__state__`, your root state container should look something like this:
1184 |
1185 | ```javascript
1186 | import { provideState, hydrate } from "freactal";
1187 |
1188 | const IS_BROWSER = typeof window === "object";
1189 | const stateTemplate = provideState({
1190 | initialState: IS_BROWSER ?
1191 | hydrate(window.__state__) :
1192 | () => { /* your typical state values */ },
1193 | effects: { /* ... */ },
1194 | computed: { /* ... */ }
1195 | });
1196 | ```
1197 |
1198 | In SSR, your `typical state values` will be provided as your initial state. In the browser, the initial state will be read from `window.__state__`.
1199 |
1200 | Assuming you've done this with your root state container, you can similarly re-hydrate nested state containers like so:
1201 |
1202 | ```javascript
1203 | import { provideState, hydrate } from "freactal";
1204 |
1205 | const IS_BROWSER = typeof window === "object";
1206 | const stateTemplate = provideState({
1207 | initialState: IS_BROWSER ?
1208 | hydrate() :
1209 | () => { /* your typical state values */ },
1210 | effects: { /* ... */ },
1211 | computed: { /* ... */ }
1212 | });
1213 | ```
1214 |
1215 | Note that there is no need to pass `window.__state__` to the `hydrate` function for nested state containers.
1216 |
1217 |
1218 |
1219 |
1220 |
1221 | ## Maintenance Status
1222 |
1223 | **Archived:** This project is no longer maintained by Formidable. We are no longer responding to issues or pull requests unless they relate to security concerns. We encourage interested developers to fork this project and make it their own!
1224 |
--------------------------------------------------------------------------------
