repos / starfx

commit

4596afa

parent

1532286

author

Eric Bower

date

2024-07-30 19:03:09 +0000 UTC

docs: learn page

 1@@ -25,6 +25,11 @@ func main() {
 2 				Href: "/getting-started",
 3 				Page: pager("getting-started.md"),
 4 			},
 5+			{
 6+				Text: "Learn",
 7+				Href: "/learn",
 8+				Page: pager("learn.md"),
 9+			},
10 			{
11 				Text: "Controllers",
12 				Href: "/controllers",

 1@@ -0,0 +1,66 @@
 2+---
 3+title: Learn
 4+description: Fundamental concepts in starfx
 5+---
 6+
 7+# How does `starfx` work?
 8+
 9+`starfx` is a companion framework to `react` that understands how to listen to
10+user events (e.g. clicks, form inputs, etc.), activate side-effects (e.g. fetch
11+api data, submit form data, update state), and then intelligently update the
12+view. If you are familiar with **MVC**:
13+
14+- `react` is the **View**
15+- `starfx` is the **Model** and **Controller**
16+
17+The high-level picture of `starfx` is _essentially_ a glorified pubsub system:
18+
19+- The user goes to your app
20+- The view is generated with `react`
21+- When a user interacts with your web app, events gets dispatched
22+- `starfx` listens for events and triggers side-effects (e.g. fetches API data,
23+  updates state, etc.)
24+- An entirely new version of the `starfx` state gets created
25+- `react` surgically updates the view based on changes to the `starfx` state
26+- Rinse and repeat
27+
28+It all happens as a single unidirectional loop.
29+
30+## How is `starfx` different?
31+
32+`starfx` is different in a number of ways.
33+
34+First, we combine both state and side-effect management into a single cohesive
35+unit. This streamlines the implementation of your web app.
36+
37+Second, business logic does not live inside of `react`, rather, it lives inside
38+of the side-effect system. We are not shackled by `react` lifecycle hooks, in
39+fact, `starfx` has virtually no concept of `react` at all -- except for a couple
40+of hooks. Then entire system is designed, from the ground up, to not need
41+`react` at all in order to function. At the end of the day, `starfx` works by
42+subscribing to and publishing events. Those events could come from `react`, but
43+they could also come from anywhere.
44+
45+## Why does `starfx` use js generators?
46+
47+Generators give us -- the library authors -- more control over how side-effects
48+are handled within a javascript runtime environment. There are things that we
49+can do with generators that are just not possible using `async`/`await`. To
50+provide some specific examples, we need the ability to manage async operations
51+as a tree of tasks. We need the ability to have
52+[structured concurrency](https://en.wikipedia.org/wiki/Structured_concurrency)
53+in order to granularly manipulate, manage, spawn, and teardown tasks.
54+
55+Furthermore, `async`/`await` is implemented using generator functions. In
56+`starfx`, not everything we want to `await` is a `Promise`!
57+
58+There is so much more to why generators are awesome but at the end of the day,
59+to the end developer, it doesn't really matter that much.
60+
61+If you are struggling to understand or are getting confused using generator
62+functions, just use the
63+[effection async rosetta stone](https://frontside.com/effection/docs/async-rosetta-stone).
64+
65+We highly recommend reading the
66+[Thinking in Effection](https://frontside.com/effection/docs/thinking-in-effection)
67+page because it should help here.