diff --git a/docs/go.mod b/docs/go.mod index 1406e8f..34ad2bb 100644 --- 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 index 9eafe34..0ae9a92 100644 --- 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 index 0396f8e..ae5cbc2 100644 --- 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 index e8e3f19..820b09d 100644 --- 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 index 71a67d4..0aca7f4 100644 --- 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 index dd2ba8e..8df9635 100644 --- 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 index 7c1ad6e..623a86d 100644 --- 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 index 8a908a2..16923a8 100644 --- 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` 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).