@rx-signals/store

@rx-signals/store

Reactive state and effects management

:warning: This documentation is work in progress for the upcoming 3.0.0 version. There is however no good reason to use 2.x over 3.0.0-rc22, so please start with the rc-version (3.0.0 will be the first version I'm going to advertise publicly, so it's more like a 1.0 in reality.).

3.0.0-rc22 is better than 2.x in any aspect and the code is production-ready. It's mainly documentation that needs improvement for a final realease (though 2.x had no documentation at all, apart from doc-strings). It is however possible that I will introduce minor breaking changes until 3.0.0 is finally released.

Installation

npm install --save @rx-signals/store@3.0.0-rc22

Dependencies

RxJs is the one and only peer dependency. You need a version >6.4.0 (so 7.x is also perfectly fine) in your project.

License

MIT

What is it?

rx-signals is a library for the MVU (Model-View-Update) pattern.

It is however not limited to MVU, but can be used in all architectures that would benefit from its features:

• State Management
  • Global and/or local
• Reactive Programming
  • High-level abstractions over RxJs (you can still go as low as you want)
• Effects Management
  • Clean side-effect isolation
  • Mock-less testing of your application logic
• An alternative to Redux, NgRx or other MVU-libs
  • Less boilerplate / More DRY
  • More abstractions / Better reusability

Though it heavily relies on RxJs, this lib is not Angular-specific. You can (and should) also use it in any other context where you have RxJs at your disposal!

(Use it in the backend or with any presentation-framework you like. Decoupling application-logic from presentation-logic is a strength of this library.)

rx-signals itself is implemented with TypeScript and therefore naturally comes with first-class type-safety.

High-level overview

This lib comes with a

• Store for
  • State-management based on the RP (reactive programming) concepts of events and behaviors (generalized as signals)
  • Reactive dependency injection
• Signals- and SignalsBuilder Types as
  • Encapsulation/Abstraction-layer over low-level signal-composition
• SignalsFactory as
  • Abstraction-layer over the SignalsBuilder-type for high-level composition and reusability (enabling DRY architecture)
• EffectSignalsFactory as
  • SignalsFactory that covers side-effect-scenarios generically, encapsulating and abstracting away all the pitfalls and possibilities to shoot yourself in the foot.

See rx-signals design goals for more.

Getting started

Terminology

What does rx-signals mean anyway? Well the rx stands for reactive extensions, so it's the same rx as in RxJs. The term signals is lent from the world of functional reactive programming (FRP), that knows two types of signals. The first type are Events being a signal of values occurring at discrete points of time. The second type of signals are Behaviors that represent values that vary over time in response to Events.

In RP (Reactive Programming), we can defined Events and Behaviors as follows:

• Event-streams:
  • Value-streams that have no current value
  • Publish values (events) to subscribers at discrete points of time
  • Can depend on other event-streams and/or behaviors
• Behaviors:
  • Value-Streams that always have a current value (though possibly lazy)
  • Current value can change at discrete points in time (published to subscribers)
  • Can depend on other behaviors and/or event-streams

So an RxJs example for behaviors would be a BehaviorSubject, while an example for event-streams would be a Subject. Thus, in RxJs-world you can translate signal as observable.

Directions

You should start with my introduction to MVU, State Management, Reactive Programming and Effects Management, if

• you don't know what any of these terms mean
• you like to understand the basis for the rx-signals architecture
• you think State Management is only about having a global state and how to modify it
• you think you're doing RP, just because you're using something like RxJs
• you think Effects Management is only about managing async processes (like http calls)
• you don't know that all these things are tied together

Otherwise, you may start with Using rx-signals. Where necessary, it will still link to the corresponding passages of the formerly mentioned introduction.

The full API-documentation (as generated from the doc strings) can be found here

If you want to use this library in an Angular project, I suggest using the @rx-signals/angular-provider in addition.

An introduction for people with NgRx background can be found here