docs: copy

neurosnap · Jun 21, 2024 · edfc02d · edfc02d
1 parent 5730a71
commit edfc02d
Showing 8 changed files with 42 additions and 32 deletions.
diff --git a/docs/go.mod b/docs/go.mod
@@ -2,7 +2,9 @@ module github.com/neurosnap/starfx/docs
 
 go 1.22
 
-require github.com/picosh/pdocs v0.0.0-20240621040056-5cbf57557db3
+// replace github.com/picosh/pdocs => /home/erock/dev/pico/pdocs
+
+require github.com/picosh/pdocs v0.0.0-20240621181009-3827cd3af2d3
 
 require (
 	github.com/alecthomas/chroma v0.10.0 // indirect

diff --git a/docs/go.sum b/docs/go.sum
@@ -6,8 +6,8 @@ github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/dlclark/regexp2 v1.4.0/go.mod h1:2pZnwuY/m+8K6iRw6wQdMtk+rH5tNGR1i55kozfMjCc=
 github.com/dlclark/regexp2 v1.10.0 h1:+/GIL799phkJqYW+3YbOd8LCcbHzT0Pbo8zl70MHsq0=
 github.com/dlclark/regexp2 v1.10.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
-github.com/picosh/pdocs v0.0.0-20240621040056-5cbf57557db3 h1:VuX6UzKt5bNir3itrMBiROmzZp8PEZJkbD7muwz5x2s=
-github.com/picosh/pdocs v0.0.0-20240621040056-5cbf57557db3/go.mod h1:KXO3Z0EVdA811AX6mlK4lwFDT+KgmegRVrEmZU5uLXU=
+github.com/picosh/pdocs v0.0.0-20240621181009-3827cd3af2d3 h1:+/rt+j32CsEh49LAMKnX4GTVaIVlOLAcDX6SsYWKt+4=
+github.com/picosh/pdocs v0.0.0-20240621181009-3827cd3af2d3/go.mod h1:KXO3Z0EVdA811AX6mlK4lwFDT+KgmegRVrEmZU5uLXU=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=

diff --git a/docs/posts/controllers.md b/docs/posts/controllers.md
@@ -10,3 +10,6 @@ Controllers do not relate to pages, they most often relate to centralized pieces
 of business logic. This could be as simple as making a single API endpoint and
 caching the results or as complex as making multiple dependent API calls and
 combinatory logic.
+
+In the following sections we will discuss how to create controllers and the
+different use cases for them inside `starfx`.
diff --git a/docs/posts/getting-started.md b/docs/posts/getting-started.md
@@ -4,7 +4,7 @@ description: Use starfx with deno, node, or the browser
 toc: 1
 ---
 
-# motivation
+# Motivation
 
 We think we need a react framework and server-side rendering (SSR) because
 that's where money is being made. If we are building a highly dynamic and
@@ -55,7 +55,7 @@ The benefits of using this library:
 - Has a robust side-effect management system using structured concurrency
 - Has data synchronization and caching separated from react
 
-# when to use this library?
+# When to use this library?
 
 The primary target for this library are SPAs. This is for an app that might be
 hosted inside an object store (like s3) or with a simple web server (like nginx)
@@ -71,7 +71,7 @@ feel a little overwhelming. Just know if you use this library, your code will be
 easier to read, easier to write, all while handling a massive amount of business
 complexity.
 
-# code
+# Code
 
 Here we demonstrate a complete example so you can glimpse at how `starfx` works.
 In this example, we will fetch a github repo from an API endpoint, cache the
@@ -128,7 +128,7 @@ function Example() {
 }
 ```
 
-# install
+# Install
 
 ```bash
 npm install starfx

diff --git a/docs/posts/models.md b/docs/posts/models.md
@@ -6,3 +6,5 @@ description: State management in starfx
 Since data normalization is a first-class citizen inside `starfx` we custom
 built a react database for your front-end web apps. Our store is most similar to
 `redux` but with a couple of important differences.
+
+Creating a front-end database starts first with creating a schema.
diff --git a/docs/posts/react.md b/docs/posts/react.md
@@ -1,6 +1,7 @@
 ---
 title: React
 description: How to integrate with React
+toc: 2
 ---
 
 Even though we are **not** using `redux`, if you are familiar with
@@ -38,14 +39,18 @@ function App() {
 }
 ```
 
-# hooks
+# Hooks
 
 ## `useSelector`
 
+Query your store with this hook.
+
 [See `react-redux` docs](https://react-redux.js.org/api/hooks#useselector)
 
 ## `useDispatch`
 
+Call thunks and endpoints with this hook.
+
 [See `react-redux` docs](https://react-redux.js.org/api/hooks#usedispatch)
 
 ## `useLoader`

diff --git a/docs/posts/resources.md b/docs/posts/resources.md
@@ -3,25 +3,29 @@ title: Resources
 description: Some useful links to learn more
 ---
 
-# quick links
+# Quick links
 
 - [blog posts about starfx](https://bower.sh/?tag=starfx)
 - [examples repo](https://github.com/neurosnap/starfx-examples)
 - [production example repo](https://github.com/aptible/app-ui)
 
-# talk
+# Talks
 
 I recently gave a talk about delimited continuations where I also discuss this
 library:
 
-[![Delimited continuations are all you need](http://img.youtube.com/vi/uRbqLGj_6mI/0.jpg)](https://youtu.be/uRbqLGj_6mI?si=Mok0J8Wp0Z-ahFrN)
+- [Delimited continuations are all you need](https://youtu.be/uRbqLGj_6mI?si=Mok0J8Wp0Z-ahFrN)
 
 Here is another talk I helped facilitate about `effection` with the library
 creator:
 
-[![effection with Charles Lowell](http://img.youtube.com/vi/lJDgpxRw5WA/0.jpg)](https://youtu.be/lJDgpxRw5WA?si=cCHZiKqNO7vIUhPc)
+- [effection with Charles Lowell](https://youtu.be/lJDgpxRw5WA?si=cCHZiKqNO7vIUhPc)
 
-# other notable libraries
+Here is a deep-dive on how we are using `starfx` in a production App at Aptible:
+
+- [app-ui deep dive](https://youtu.be/3M5VJuIi5fk)
+
+# Other notable libraries
 
 This library is not possible without these foundational libraries:
 

diff --git a/docs/posts/schema.md b/docs/posts/schema.md
@@ -1,6 +1,7 @@
 ---
 title: Schema
 description: Learn more about schamas and slices
+toc: 2
 ---
 
 A schema has two primary features:
@@ -16,18 +17,6 @@ functions to:
 - Update the value
 - Query for data within the value
 
-# Built-in slices
-
-As a result, the following slices should cover the most common data types and
-associated logic:
-
-- [any](#any)
-- [num](#num)
-- [str](#str)
-- [obj](#obj)
-- [loaders](#loaders)
-- [table](#table)
-
 # Schema assumptions
 
 `createSchema` requires two slices by default in order for it and everything
@@ -37,7 +26,12 @@ Why do we require those slices? Because if we can assume those exist, we can
 build a lot of useful middleware and supervisors on top of that assumption. It's
 a place for `starfx` and third-party functionality to hold their state.
 
-# `slice.any`
+# Built-in slices
+
+As a result, the following slices should cover the most common data types and
+associated logic.
+
+## `slice.any`
 
 This is essentially a basic getter and setter slice. You can provide the type it
 ought to be and it has a couple functions to manage and query the value stored
@@ -55,7 +49,7 @@ function*() {
 }
 ```
 
-# `num`
+## `num`
 
 This slice has some custom actions to manage a number value.
 
@@ -73,7 +67,7 @@ function*() {
 }
 ```
 
-# `str`
+## `str`
 
 This slice is probably not super useful since it is essentially the same as
 `slice.any<string>` but we could add more actions to it in the future.
@@ -90,7 +84,7 @@ function*() {
 }
 ```
 
-# `obj`
+## `obj`
 
 This is a specialized slice with some custom actions to deal with javascript
 objects.
@@ -114,7 +108,7 @@ function*() {
 }
 ```
 
-# `table`
+## `table`
 
 This is the more powerful and specialized slice we created. It attempts to
 mimick a database table where it holds an object:
@@ -158,7 +152,7 @@ function*() {
 }
 ```
 
-## empty
+### empty
 
 When `empty` is provided to `slice.table` and we use a selector like
 `selectById` to find an entity that does **not** exist, we will return the
@@ -183,7 +177,7 @@ in your system.
 
 [Read more about entity factories.](https://bower.sh/entity-factories)
 
-# `loaders`
+## `loaders`
 
 This is a specialized database table specific to managing loaders in `starfx`.
 [Read more about loaders here](/loader).