Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fix some broken links #736

Merged
merged 2 commits into from
Jan 6, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,21 @@
- **simple** and powerful abstractions.
<small>There are only three main primitives: `ctx`, `atom`, `action`, all other features and packages works on top of that.</small>
- **immutable** and reliable.
<small>All pure computations processed with [atomicity](https://www.reatom.dev/general/what-is-state-manager#state) guaranties.</small>
<small>All pure computations processed with atomicity guaranties.</small>
- **explicit reactivity** without proxies.
<small>To archive [maximum](#how-performant-reatom-is) performance we have [atomization](https://www.reatom.dev/guides/atomization) pattern.</small>
<small>To archive [maximum](#how-performant-reatom-is) performance we have [atomization](https://www.reatom.dev/recipes/atomization) pattern.</small>
- perfect **effects management**.
<small>Advanced [async package](https://www.reatom.dev/package/async) allows you to describe complex async flows with caching, retrying and automatic cancellation with native `await` and `AbortController`.</small>
- nice **debugging** experience.
<small>Each atom and action update stores [immutable cause (call) stack](https://www.reatom.dev/guides/debug) which is super helpful for debugging complex async flows. To simplify this we have [logger package](https://www.reatom.dev/package/logger).</small>
<small>Each atom and action update stores [immutable cause (call) stack](https://www.reatom.dev/getting-started/debugging/) which is super helpful for debugging complex async flows. To simplify this we have [logger package](https://www.reatom.dev/package/logger).</small>
- implicit **DI**.
<small>To run tests and SSR <strong>100% safety</strong> you need an isolation layer, which `ctx` is! We have the extra [testing package](https://www.reatom.dev/package/testing) with pack of helpers for a mocking.</small>
- actor-like **lifecycle hooks**
<small> To archive a trhtully modularity you have ability to describe [self-sufficient models](https://www.reatom.dev/guides/lifecycle)</small>
<small> To archive a trhtully modularity you have ability to describe [self-sufficient models](https://www.reatom.dev/handbook#lifecycle)</small>
- **smallest bundle** size: [2 KB](https://bundlejs.com/?q=%40reatom%2Fcore) gzipped
<small>Because of the power of the base primitives all ecosystem with A LOT of enterprize-grade helpers took only [~15KB](https://bundlejs.com/?q=%40reatom%2Fframework%2C%40reatom%2Fnpm-react%2C%40reatom%2Fpersist-web-storage%2C%40reatom%2Fundo%2C%40reatom%2Fform-web&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%2C%22use-sync-external-store%22%5D%7D%7D) - insane!</small>
- **best TypeScript** experience
<small>[Automatic type inference](https://www.reatom.dev/guides/typescript) is one of the main priority of Reatom developement.</small>
<small>[Automatic type inference](https://www.reatom.dev/recipes/typescript/) is one of the main priority of Reatom developement.</small>

[The core package](https://www.reatom.dev/core) includes most these features and you may use it anywhere, from huge apps to even small libs, as the overhead is tiny. Also, you could reuse our carefully written [helper tools](https://www.reatom.dev/package/framework) to solve complex tasks in a couple lines of code. We are trying to build a stable and balanced ecosystem for perfect DX and predictable maintains even for years ahead.

Expand Down Expand Up @@ -96,7 +96,7 @@ document.getElementById('save').addEventListener('click', () => {

Check out [@reatom/core docs](https://www.reatom.dev/core) for detailed explanation of key principles and features.

Do you use React.js? Check out [npm-react](https://www.reatom.dev/adapter/npm-react) package!
Do you use React.js? Check out [npm-react](https://www.reatom.dev/package/npm-react) package!

## Advanced example

Expand Down Expand Up @@ -190,32 +190,32 @@ export const Search = () => {

The whole logic definition is only about 15 LoC and it is not coupled to React and could be tested easily. What would the lines count be in a different library? The most impressive thing is that the overhead is [less than 4KB (gzip)](https://bundlejs.com/?q=%28import%29%40reatom%2Fframework%2C%28import%29%40reatom%2Fnpm-react&treeshake=%5B%7B%0A++atom%2CcreateCtx%2ConUpdate%2CreatomAsync%2Csleep%2CwithAbort%2CwithDataAtom%2CwithRetry%2C%7D%5D%2C%5B%7B+useAtom+%7D%5D&share=MYewdgzgLgBBCmBDATsAFgQSiAtjAvDItjgBQBE5ANDOQiulruQJQDcAUKJLAGbxR0ASQgQArvAgEYyJCQwQAnmGClESlTFLAoADxoBHCckUAuOFGQBLMAHMWBAHwwA3hxhEA7oiuwIAG3h4AAdSACYAVgAGdhgAejiYABN4ACMQMRV4dxhuaFcYX3gcKQBfaURvXyJgqwA6fkE0EXFJUiN4ExodXTruSxB-QOR2HNkoMWQwQqhiiE5SmnJG4VEJCFY62uD4UhzPXzQAEWJEJjIAbQBdFip9w4x05ChSFwtkYnhbM1p-dSgALQ2AEHMDkGClW73KBoABKAhMrxyHnA8IAVvAdNo9DROsgQMhzIgwIoaONrJIHG4PDT4olxpNpik-opCtMSjACTAAQBGGDYGDBWQAN3gYFg5KskmRNIZUxgeIJAH46jhJBBELZ4HUbMB-GIUhAKB9ZjB-FYcL5WDLaUqYDyolEYAAqGAAWWIaFVNlI0SiZIRUqkztdYRYNpp5l5nFpixykLuowSMkyMBWzTWkk503gopMcCQqEwJBgYmCSU%2BHHAAFVy59SPQi%2BcaOmWutRlxZJ8AMJ6UijMQIc6kVuZiB1CtQM4kFhAA&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%2C%22use-sync-external-store%22%5D%7D%7D) could you imagine?! And you are not limited to network cache, Reatom is powerful and expressive enough for describing any kind of state.

To get maximum of Reatom and the ecosystem just go to [tutorial](https://www.reatom.dev/tutorial). If you need something tiny - check out [the core package docs](https://www.reatom.dev/core). Also, we have a [package for testing](https://www.reatom.dev/package/testing)!
To get maximum of Reatom and the ecosystem just go to [tutorial](https://www.reatom.dev/getting-started/setup/). If you need something tiny - check out [the core package docs](https://www.reatom.dev/core). Also, we have a [package for testing](https://www.reatom.dev/package/testing)!

## Roadmap

- Finish [forms package](https://www.reatom.dev/package/form)
- Finish ~~[persist](https://www.reatom.dev/package/persist)~~ and [navigation](https://github.com/artalar/reatom/tree/v3/packages/navigation)~~ (improve [url](https://www.reatom.dev/package/url/)) packages
- Add adapters for most popular ui frameworks: ~~[react](https://www.reatom.dev/adapter/npm-react)~~, angular, vue, ~~[svelte](https://www.reatom.dev/adapter/npm-svelte)~~, ~~[solid](https://www.reatom.dev/adapter/npm-solid-js/)~~.
- Finish ~~[persist](https://www.reatom.dev/package/persist)~~, improve [url](https://www.reatom.dev/package/url/) packages
- Add adapters for most popular ui frameworks: ~~[react](https://www.reatom.dev/package/npm-react)~~, angular, vue, ~~[svelte](https://www.reatom.dev/package/npm-svelte)~~, ~~[solid](https://www.reatom.dev/package/npm-solid-js/)~~.
- Port some components logic from reakit.io, to made it fast, light and portable.
- Add ability to made async transaction and elaborate optimistic-ui patterns and helpers / package.

## FAQ

### Why not X?

**Redux** is awesome and Reatom is heavy inspired by it. Immutability, separation of computations and effects are good architecture designs principles. But there are a lot of missing features, when you trying to build something huge, or want to describe something small. Some of them is just impossible to fix, like [batching](https://www.reatom.dev/core#ctxget-batch-api), [O(n) complexity](https://www.reatom.dev/guides/atomization#reducing-computational-complexity) or that selectors is not inspectable and breaks [the atomicy](https://www.reatom.dev/general/what-is-state-manager#state). Others is really [hard to improve](https://github.com/reduxjs/reselect/discussions/491). And boilerplate, yeah, [the difference is a huge](https://github.com/artalar/RTK-entities-basic-example/pull/1/files#diff-43162f68100a9b5eb2e58684c7b9a5dc7b004ba28fd8a4eb6461402ec3a3a6c6).
**Redux** is awesome and Reatom is heavy inspired by it. Immutability, separation of computations and effects are good architecture designs principles. But there are a lot of missing features, when you trying to build something huge, or want to describe something small. Some of them is just impossible to fix, like [batching](https://www.reatom.dev/core#ctxget-batch-api), [O(n) complexity](https://www.reatom.dev/recipes/atomization/#reducing-computational-complexity) or that selectors is not inspectable and breaks [the atomicy](https://www.reatom.dev/general/what-is-state-manager#state). Others is really [hard to improve](https://github.com/reduxjs/reselect/discussions/491). And boilerplate, yeah, [the difference is a huge](https://github.com/artalar/RTK-entities-basic-example/pull/1/files#diff-43162f68100a9b5eb2e58684c7b9a5dc7b004ba28fd8a4eb6461402ec3a3a6c6).
Reatom solves all this problems and bring much more features by the almost same size.

**MobX** brings too big bundle to use it in a small widgets, Reatom is more universal in this case. Also, MobX has mutability and implicit reactivity, which is usefull for simple cases, but could be not obvious and hard to debug in complex cases. There is no separate thing like action / event / effect to describe some dependent effects sequences (FRP-way). [There is not atomicy too](https://github.com/artalar/state-management-specification/blob/master/src/index.test.js#L60).

**Effector** is too opinionated. There is **no** first-class support for **lazy** reactive computations and all connections are [hot](https://luukgruijs.medium.com/understanding-hot-vs-cold-observables-62d04cf92e03) everytime, which is could be more predictable, but defenetly is not optimal. Effector is not friendly for fabric creation (because of it hotness), which disallow us to use [atomization](https://www.reatom.dev/guides/atomization#ref-pattern) patterns, needed to handle immutability efficient. [The bundle size is 2-3 times larger](https://bundlejs.com/?q=effector&treeshake=%5B%7BcraeteStore%2CcreateEvent%2Ccombine%7D%5D) and [performance is lower](https://github.com/artalar/reactive-computed-bench).
**Effector** is too opinionated. There is **no** first-class support for **lazy** reactive computations and all connections are [hot](https://luukgruijs.medium.com/understanding-hot-vs-cold-observables-62d04cf92e03) everytime, which is could be more predictable, but defenetly is not optimal. Effector is not friendly for fabric creation (because of it hotness), which disallow us to use [atomization](https://www.reatom.dev/recipes/atomization/) patterns, needed to handle immutability efficient. [The bundle size is 2-3 times larger](https://bundlejs.com/?q=effector&treeshake=%5B%7BcraeteStore%2CcreateEvent%2Ccombine%7D%5D) and [performance is lower](https://github.com/artalar/reactive-computed-bench).

[Zustand](https://github.com/pmndrs/zustand), [nanostores](https://github.com/nanostores/nanostores), [xstate](https://xstate.js.org) and [many other](https://gist.github.com/artalar/e5e8a7274dfdfbe9d36c9e5ec22fc650) state managers have no so great combination of type inference, features, bundle size and performance, as Reatom have.

### Why immutability?

Immutable data is much predictable and better for debug, than mutable states and wrapers around that. Reatom specialy designed with focus on [simple debug of async chains](https://www.reatom.dev/guides/debug) and [have a patterns](https://www.reatom.dev/guides/atomization) to handle [greate performance](#how-performant-reatom-is).
Immutable data is much predictable and better for debug, than mutable states and wrapers around that. Reatom specialy designed with focus on [simple debug of async chains](https://www.reatom.dev/getting-started/debugging/) and [have a patterns](https://www.reatom.dev/recipes/atomization/) to handle [greate performance](#how-performant-reatom-is).

### What LTS policy is used and what about bus factor?

Expand All @@ -233,13 +233,13 @@ All builds have two types of output formats: CJS (`exports.require`, `main`) and

[Here is the benchmark](https://github.com/artalar/reactive-computed-bench) of complex computations for different state managers. Note that Reatom by default uses immutable data structures, works in a separate context (DI-like) and keeps [atomicity](https://www.reatom.dev/general/what-is-state-manager#state), which means the Reatom test checks more features, than other state manager tests. Anyway, for the middle numbers Reatom faster than MobX which is pretty impressive.

Also, check out [atomization guide](https://www.reatom.dev/guides/atomization).
Also, check out [atomization guide](https://www.reatom.dev/recipes/atomization).

### Limitations

Of course there are no software without limitations. Reatom is trying to be a silver bullet but we still have some cases which you should know about.

- Immutable data always have an additional performance impact and in critical cases you should think well about your structures and how you could handle it better. The good news is that you [don't have to use normalization](https://www.reatom.dev/guides/atomization).
- Immutable data always have an additional performance impact and in critical cases you should think well about your structures and how you could handle it better. The good news is that you [don't have to use normalization](https://www.reatom.dev/recipes/atomization).
- Laziness could be not obvious in some cases and will cause some updates missing. But it easy to debug a missing update, which is more explicit, than memory leaks and performance issues of hot observables. Anyway, we have [hooks](https://www.reatom.dev/package/hooks) for hot linking.
- Currently, there is no way to subscribe on error of any dependency, but we are working on it. In [reatomAsync](https://www.reatom.dev/package/async) passed effects wraps to an error handler and allow you to handle errors, but again - you should wrap it explicit.
- Currently, there is no asynchronous transactions support, but we are working on it. It is important feature for simplify building of optimistic UI and we really think it will improve UX a lot.
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/compat/react-v1.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ description: Reatom for react-v1



This is compatible package which allow you to use `@reatom/core-v1` with react. All docs is [here](/adapter/npm-react/).
This is compatible package which allow you to use `@reatom/core-v1` with react. All docs is [here](/package/npm-react/).

## Setup batching for old React

Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/getting-started/debugging.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ const ctx = createCtx()
connectLogger(ctx)
```

More settings you can found in [@reatom/logger](@reatom/logger) documentation
More settings you can found in [@reatom/logger](https://www.reatom.dev/package/logger) documentation

## Usage

Expand Down
Loading
Loading