Skip to content

Commit

Permalink
docs: more readme improvements
Browse files Browse the repository at this point in the history
  • Loading branch information
krulod committed May 21, 2024
1 parent a1698c2 commit f8dd169
Showing 1 changed file with 18 additions and 17 deletions.
35 changes: 18 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
# Reatom

The ultimate state manager for any kinds of applications.

## Key features
Expand All @@ -12,13 +10,14 @@ The ultimate state manager for any kinds of applications.
- the whole ecosystem weighs ~15KB
- rich official ecosystem with lots of high-quality helpers and integrations
- advanced primitives to abstract away the complexity of asynchronous interactions
- has integrations with [React](https://www.reatom.dev/package/npm-react/), [Svelte](https://www.reatom.dev/package/npm-svelte/), [SolidJS](https://www.reatom.dev/package/npm-solid-js/)
- has adapters for [React](https://www.reatom.dev/package/npm-react/), [Vue](https://www.reatom.dev/package/npm-vue/), [Angular](https://reatom.dev/package/npm-angular), [SolidJS](https://www.reatom.dev/package/npm-solid-js/) and [Svelte](https://www.reatom.dev/package/npm-svelte/)
- full TypeScript support
- APIs are designed to fully enable type inference
- all APIs are designed to fully enable type inference
- efficient at any scale
- decomposition made easy with factories
- lifecycle hooks for describing focused and self-sufficient models
- [includes tools to simplify debugging](https://reatom.dev/package/logger)
- builtin DI for straightforward testing and SSR
- lifecycle hooks for describing focused and self-sufficient models

## Getting started

Expand All @@ -32,45 +31,47 @@ The ultimate state manager for any kinds of applications.

**MobX**: MobX bundle size is too huge to use it in small embedded widgets, it uses getters/Proxies for change detections and has mutable nature, which eventually leads to confusing debugging sessions. [It has no atomicity as well](https://github.com/artalar/state-management-specification/blob/master/src/index.test.js#L60).

**Effector:** Effector encourages the description of sequential procedures through custom operators like `sample`, making the code really confusing. It also lacks the laziness of reactive computations, automatic dependency tracking, and is less performant compared to Reatom.
**Effector:** Effector encourages the description of processes through custom operators like `sample`, making the code really confusing and unaccessible for those unfamiliar with the "DSL". It also lacks the laziness of reactive computations, automatic dependency tracking, and is less performant compared to Reatom.

Solutions like **zustand**, **jotai**, **nanostores**, **xstate**, [and many others](https://gist.github.com/artalar/e5e8a7274dfdfbe9d36c9e5ec22fc650), are either less efficient than Reatom, or are not that feature-rich.
In the modern front-end tooling landscape, there are lots of other solutions including **zustand**, **jotai**, **nanostores**, **xstate** [and many others](https://gist.github.com/artalar/e5e8a7274dfdfbe9d36c9e5ec22fc650), but we find them either less efficient than Reatom, or lacking in features.

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

Reatom is always developed for continous usage. LTS versions are released once a year since [December 2019](https://github.com/artalar/reatom/releases/tag/v1.0) and have [compatibility layers](https://www.reatom.dev/compat/core-v1) with the most recent version of the core package. We hope it proves our approach to maintainance to be responsible.
Reatom has always been developed for continous usage. LTS versions are released once a year since [December 2019](https://github.com/artalar/reatom/releases/tag/v1.0) and have [compatibility layers](https://www.reatom.dev/compat/core-v1) with the most recent version of the core package. We hope it proves our approach to maintainance to be responsible.

Our team currently consists of 4 people: [@artalar](https://github.com/artalar) and [@krulod](https://github.com/krulod) develop and maintain the core features, while [@BANOnotIT](https://github.com/BANOnotIT) and [@Akiyamka](https://github.com/Akiyamka) help with documentation and issue management. [Many other people also took part in the development of the library](https://github.com/artalar/reatom/graphs/contributors).

### What about build targets and browser support?

All packages are configured based on [Browserslist's "last 1 year" query](https://browsersl.ist/#q=last+1+year). If you need to support older environments, you should handle transpilation by yourself.
All packages are shipped transpiled [Browserslist's "last 1 year" query](https://browsersl.ist/#q=last+1+year). If you need to support older environments, you should handle transpilation by yourself.

Packages include CommonJS and ESM entrypoints. See `package.json` files for more details.

### How performant Reatom is?

[Here is the benchmark](https://github.com/artalar/reactive-computed-bench) of complex computations for different state managers. Although Reatom features introduce more overhead, it appears to be more performant than MobX, which is pretty impressive.
Performance at design time is one of the main principles behind all Reatom code. Packages are written to be as small and efficient as possble, and all critical code is constantly being optimized pedantically.

As a proof, [here is a benchmark](https://github.com/artalar/reactive-computed-bench) testing efficiency and memory consumption of various reactive programming libraries. Although the immutable nature of Reatom that makes its features possible does introduce more overhead, it appears to be more performant than MobX, which we believe is a quite decent result.

### Limitations?

No software is free from limitations, and Reatom is no exception.

- Immutable data introduces some overhead and encourages you to optimize your data structures.
- Lazy nature of Reatom may be unobvious and cause some problems like missing updates, but we find it much easier to bear with than the flaws of hot observables.
- Currently, there is no way to subscribe to errors of reactive computations, but we are working on it.
- Currently, there is no asynchronous transactions support, but we are working on it.
- We already have lots of utils and the ecosystem is growing all the time, but at the moment we don't have a strict architectural framework like `mobx-state-tree` that makes the development exceptionally straightforward.
- Immutable data introduces some overhead and encourages you to optimize your data structures, but these trade-offs are insignificant compared to pros
- Lazy nature of Reatom may feel unobvious and cause some problems like missing updates, but they are much easier to bear with than the flaws of hot observables
- Currently, there is no way to subscribe to errors of reactive computations, but we are working on it
- Currently, there is no asynchronous transactions support, but we are working on it
- Ecosystem is growing all the time and is already pretty decent, but at the moment we don't have a strict architectural framework like `mobx-state-tree` that makes the development exceptionally straightforward

## Zen

- Good primitive is better than framework
- A good primitive is better than a framework
- Composition beats configuration
- JavaScript features should be reused, not reinvented

## Media

- [X (EN)](https://twitter.com/ReatomJS)
- [X (EN)](https://x.com/ReatomJS)
- [Telegram (RU)](https://t.me/reatom_ru)
- [YouTube (RU)](https://www.youtube.com/playlist?list=PLXObawgXpIfxERCN8Lqd89wdsXeUHm9XU)

Expand Down

0 comments on commit f8dd169

Please sign in to comment.