- commit
- 351a8d3
- parent
- 23b3bf2
- author
- Eric Bower
- date
- 2024-08-16 20:29:58 +0000 UTC
docs: copy
5 files changed,
+42,
-32
+0,
-5
1@@ -110,11 +110,6 @@ func main() {
2 Href: "/design-philosophy",
3 Page: pager("design-philosophy.md"),
4 },
5- {
6- Text: "API",
7- Href: "/api",
8- Page: pager("api.md"),
9- },
10 {
11 Text: "Resources",
12 Href: "/resources",
+0,
-6
1@@ -1,6 +0,0 @@
2----
3-title: API
4-description: Our API for public consumption
5----
6-
7-WIP
+15,
-16
1@@ -9,9 +9,10 @@ toc: 1
2 We think we need a react framework and server-side rendering (SSR) because
3 that's where money is being made. If we are building a highly dynamic and
4 interactive web application then we probably don't need SSR. These frameworks
5-sell us that they are an easier way to build web apps, but that's not true. Just
6-think of it this way: if we can build a web app using only static assets, isn't
7-that simpler than having static assets **and** a react framework server?
8+sell us that they are an easier way to build web apps, but that's not strictly
9+true. Just think of it this way: if we can build a web app using **only** static
10+assets, isn't that simpler than having static assets **and** a react framework
11+server?
12
13 React hook-based fetching and caching libraries dramatically simplify data
14 synchronization but are so tightly coupled to a component's life cycle that it
15@@ -20,12 +21,12 @@ downside of not being able to normalize our cache which means we have to spend
16 time thinking about how and when to invalidate our cache.
17
18 Further, all of these data caching libraries don't handle data normalization. In
19-every library we are going to see a line like: "Data normalization is hard and
20-it isn't worth it." Their libraries are not built with data normalization in
21-mind so they claim it's an anti-feature. Why do we want to normalize data in the
22-backend but not the frontend? Data normalization is critically important because
23-it makes CRUD operations automatically update our web app without having to
24-invalidate our cache.
25+many similar libraries we are going to see a line like: "Data normalization is
26+hard and it isn't worth it." Their libraries are not built with data
27+normalization in mind so they claim it's an anti-feature. Why do we want to
28+normalize data in the backend but not the frontend? Data normalization is
29+critically important because it makes CRUD operations automatically update our
30+web app without having to invalidate our cache.
31
32 So what if we are building a highly interactive web app that doesn't need SEO
33 and we also need more control over data synchronization and caching?
34@@ -49,11 +50,11 @@ The benefits of using this library:
35 - The missing model and controller (MC) in react (V)
36 - Designed for single-page applications (SPAs)
37 - Makes data normalization easy and straightforward
38-- Has a powerful middleware system similar to express to handle requests and
39+- Has a powerful middleware system similar to `express` to handle requests and
40 responses
41 - Reduces state management boilerplate to its absolute essentials
42 - Has a robust side-effect management system using structured concurrency
43-- Has data synchronization and caching separated from react
44+- Has data synchronization and caching separated from `react`
45
46 # When to use this library?
47
48@@ -68,8 +69,8 @@ This library is **not** a great fit for ecommerce, tiny projects, or blogs. This
49 is for web apps that are generally behind a login screen that require a
50 desktop-class user experience. This library is designed to scale, so it might
51 feel a little overwhelming. Just know if you use this library, your code will be
52-easier to read, easier to write, all while handling a massive amount of business
53-complexity.
54+easier to read, easier to write, easier to refactor, all while handling a
55+massive amount of business complexity.
56
57 # Code
58
59@@ -112,9 +113,7 @@ function App() {
60
61 function Example() {
62 const { isInitialLoading, isError, message, data } = useCache(fetchRepo());
63-
64 if (isInitialLoading) return "Loading ...";
65-
66 if (isError) return `An error has occurred: ${message}`;
67
68 return (
69@@ -140,7 +139,7 @@ yarn add starfx
70 ```
71
72 ```ts
73-import * as starfx from "https://deno.land/x/starfx@0.7.0/mod.ts";
74+import * as starfx from "https://deno.land/x/starfx@0.13.2/mod.ts";
75 ```
76
77 # Effection
+3,
-3
1@@ -10,8 +10,8 @@ user events (e.g. clicks, form inputs, etc.), activate side-effects (e.g. fetch
2 api data, submit form data, update state), and then intelligently update the
3 view. If you are familiar with **MVC**:
4
5-- `react` is the **View**
6-- `starfx` is the **Model** and **Controller**
7+- `react` is the **View** layer
8+- `starfx` are the **Model** and **Controller** layers
9
10 The high-level picture of `starfx` is _essentially_ a glorified pubsub system:
11
12@@ -20,7 +20,7 @@ The high-level picture of `starfx` is _essentially_ a glorified pubsub system:
13 - When a user interacts with your web app, events gets dispatched
14 - `starfx` listens for events and triggers side-effects (e.g. fetches API data,
15 updates state, etc.)
16-- An entirely new version of the `starfx` state gets created
17+- An entirely new version of the state gets created
18 - `react` surgically updates the view based on changes to the `starfx` state
19 - Rinse and repeat
20
+24,
-2
1@@ -6,8 +6,7 @@ toc: 2
2
3 Even though we are **not** using `redux`, if you are familiar with
4 [react-redux](https://react-redux.js.org) then this will be an identical
5-experience because that's what we are using under-the-hood to integrate with
6-`react`.
7+experience because `starfx/react` has an identical API signature.
8
9 `useDispatch`, `useSelector`, and `createSelector` are the bread and butter of
10 `redux`'s integration with `react` all of which we use inside `starfx`.
11@@ -45,12 +44,35 @@ function App() {
12
13 Query your store with this hook.
14
15+```tsx
16+import { useSelector } from "starfx";
17+
18+function App() {
19+ const data = useSelector((state) => state.data);
20+ return <div>{data}</div>;
21+}
22+```
23+
24 [See `react-redux` docs](https://react-redux.js.org/api/hooks#useselector)
25
26 ## `useDispatch`
27
28 Call thunks and endpoints with this hook.
29
30+```tsx
31+import { useDispatch } from "starfx";
32+
33+function App() {
34+ const dispatch = useDispatch();
35+
36+ return (
37+ <button onClick={() => dipatch({ type: "action!" })}>
38+ Click me!
39+ </button>
40+ );
41+}
42+```
43+
44 [See `react-redux` docs](https://react-redux.js.org/api/hooks#usedispatch)
45
46 ## `useLoader`