- commit
- edfc02d
- parent
- 5730a71
- author
- Eric Bower
- date
- 2024-06-21 18:15:45 +0000 UTC
docs: copy
8 files changed,
+42,
-32
+3,
-1
1@@ -2,7 +2,9 @@ module github.com/neurosnap/starfx/docs
2
3 go 1.22
4
5-require github.com/picosh/pdocs v0.0.0-20240621040056-5cbf57557db3
6+// replace github.com/picosh/pdocs => /home/erock/dev/pico/pdocs
7+
8+require github.com/picosh/pdocs v0.0.0-20240621181009-3827cd3af2d3
9
10 require (
11 github.com/alecthomas/chroma v0.10.0 // indirect
+2,
-2
1@@ -6,8 +6,8 @@ github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
2 github.com/dlclark/regexp2 v1.4.0/go.mod h1:2pZnwuY/m+8K6iRw6wQdMtk+rH5tNGR1i55kozfMjCc=
3 github.com/dlclark/regexp2 v1.10.0 h1:+/GIL799phkJqYW+3YbOd8LCcbHzT0Pbo8zl70MHsq0=
4 github.com/dlclark/regexp2 v1.10.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
5-github.com/picosh/pdocs v0.0.0-20240621040056-5cbf57557db3 h1:VuX6UzKt5bNir3itrMBiROmzZp8PEZJkbD7muwz5x2s=
6-github.com/picosh/pdocs v0.0.0-20240621040056-5cbf57557db3/go.mod h1:KXO3Z0EVdA811AX6mlK4lwFDT+KgmegRVrEmZU5uLXU=
7+github.com/picosh/pdocs v0.0.0-20240621181009-3827cd3af2d3 h1:+/rt+j32CsEh49LAMKnX4GTVaIVlOLAcDX6SsYWKt+4=
8+github.com/picosh/pdocs v0.0.0-20240621181009-3827cd3af2d3/go.mod h1:KXO3Z0EVdA811AX6mlK4lwFDT+KgmegRVrEmZU5uLXU=
9 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
10 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
11 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+3,
-0
1@@ -10,3 +10,6 @@ Controllers do not relate to pages, they most often relate to centralized pieces
2 of business logic. This could be as simple as making a single API endpoint and
3 caching the results or as complex as making multiple dependent API calls and
4 combinatory logic.
5+
6+In the following sections we will discuss how to create controllers and the
7+different use cases for them inside `starfx`.
+4,
-4
1@@ -4,7 +4,7 @@ description: Use starfx with deno, node, or the browser
2 toc: 1
3 ---
4
5-# motivation
6+# Motivation
7
8 We think we need a react framework and server-side rendering (SSR) because
9 that's where money is being made. If we are building a highly dynamic and
10@@ -55,7 +55,7 @@ The benefits of using this library:
11 - Has a robust side-effect management system using structured concurrency
12 - Has data synchronization and caching separated from react
13
14-# when to use this library?
15+# When to use this library?
16
17 The primary target for this library are SPAs. This is for an app that might be
18 hosted inside an object store (like s3) or with a simple web server (like nginx)
19@@ -71,7 +71,7 @@ feel a little overwhelming. Just know if you use this library, your code will be
20 easier to read, easier to write, all while handling a massive amount of business
21 complexity.
22
23-# code
24+# Code
25
26 Here we demonstrate a complete example so you can glimpse at how `starfx` works.
27 In this example, we will fetch a github repo from an API endpoint, cache the
28@@ -128,7 +128,7 @@ function Example() {
29 }
30 ```
31
32-# install
33+# Install
34
35 ```bash
36 npm install starfx
+2,
-0
1@@ -6,3 +6,5 @@ description: State management in starfx
2 Since data normalization is a first-class citizen inside `starfx` we custom
3 built a react database for your front-end web apps. Our store is most similar to
4 `redux` but with a couple of important differences.
5+
6+Creating a front-end database starts first with creating a schema.
+6,
-1
1@@ -1,6 +1,7 @@
2 ---
3 title: React
4 description: How to integrate with React
5+toc: 2
6 ---
7
8 Even though we are **not** using `redux`, if you are familiar with
9@@ -38,14 +39,18 @@ function App() {
10 }
11 ```
12
13-# hooks
14+# Hooks
15
16 ## `useSelector`
17
18+Query your store with this hook.
19+
20 [See `react-redux` docs](https://react-redux.js.org/api/hooks#useselector)
21
22 ## `useDispatch`
23
24+Call thunks and endpoints with this hook.
25+
26 [See `react-redux` docs](https://react-redux.js.org/api/hooks#usedispatch)
27
28 ## `useLoader`
+9,
-5
1@@ -3,25 +3,29 @@ title: Resources
2 description: Some useful links to learn more
3 ---
4
5-# quick links
6+# Quick links
7
8 - [blog posts about starfx](https://bower.sh/?tag=starfx)
9 - [examples repo](https://github.com/neurosnap/starfx-examples)
10 - [production example repo](https://github.com/aptible/app-ui)
11
12-# talk
13+# Talks
14
15 I recently gave a talk about delimited continuations where I also discuss this
16 library:
17
18-[](https://youtu.be/uRbqLGj_6mI?si=Mok0J8Wp0Z-ahFrN)
19+- [Delimited continuations are all you need](https://youtu.be/uRbqLGj_6mI?si=Mok0J8Wp0Z-ahFrN)
20
21 Here is another talk I helped facilitate about `effection` with the library
22 creator:
23
24-[](https://youtu.be/lJDgpxRw5WA?si=cCHZiKqNO7vIUhPc)
25+- [effection with Charles Lowell](https://youtu.be/lJDgpxRw5WA?si=cCHZiKqNO7vIUhPc)
26
27-# other notable libraries
28+Here is a deep-dive on how we are using `starfx` in a production App at Aptible:
29+
30+- [app-ui deep dive](https://youtu.be/3M5VJuIi5fk)
31+
32+# Other notable libraries
33
34 This library is not possible without these foundational libraries:
35
+13,
-19
1@@ -1,6 +1,7 @@
2 ---
3 title: Schema
4 description: Learn more about schamas and slices
5+toc: 2
6 ---
7
8 A schema has two primary features:
9@@ -16,18 +17,6 @@ functions to:
10 - Update the value
11 - Query for data within the value
12
13-# Built-in slices
14-
15-As a result, the following slices should cover the most common data types and
16-associated logic:
17-
18-- [any](#any)
19-- [num](#num)
20-- [str](#str)
21-- [obj](#obj)
22-- [loaders](#loaders)
23-- [table](#table)
24-
25 # Schema assumptions
26
27 `createSchema` requires two slices by default in order for it and everything
28@@ -37,7 +26,12 @@ Why do we require those slices? Because if we can assume those exist, we can
29 build a lot of useful middleware and supervisors on top of that assumption. It's
30 a place for `starfx` and third-party functionality to hold their state.
31
32-# `slice.any`
33+# Built-in slices
34+
35+As a result, the following slices should cover the most common data types and
36+associated logic.
37+
38+## `slice.any`
39
40 This is essentially a basic getter and setter slice. You can provide the type it
41 ought to be and it has a couple functions to manage and query the value stored
42@@ -55,7 +49,7 @@ function*() {
43 }
44 ```
45
46-# `num`
47+## `num`
48
49 This slice has some custom actions to manage a number value.
50
51@@ -73,7 +67,7 @@ function*() {
52 }
53 ```
54
55-# `str`
56+## `str`
57
58 This slice is probably not super useful since it is essentially the same as
59 `slice.any<string>` but we could add more actions to it in the future.
60@@ -90,7 +84,7 @@ function*() {
61 }
62 ```
63
64-# `obj`
65+## `obj`
66
67 This is a specialized slice with some custom actions to deal with javascript
68 objects.
69@@ -114,7 +108,7 @@ function*() {
70 }
71 ```
72
73-# `table`
74+## `table`
75
76 This is the more powerful and specialized slice we created. It attempts to
77 mimick a database table where it holds an object:
78@@ -158,7 +152,7 @@ function*() {
79 }
80 ```
81
82-## empty
83+### empty
84
85 When `empty` is provided to `slice.table` and we use a selector like
86 `selectById` to find an entity that does **not** exist, we will return the
87@@ -183,7 +177,7 @@ in your system.
88
89 [Read more about entity factories.](https://bower.sh/entity-factories)
90
91-# `loaders`
92+## `loaders`
93
94 This is a specialized database table specific to managing loaders in `starfx`.
95 [Read more about loaders here](/loader).