Design Doc - @rx-angular/state

# Design Doc - @rx-angular/state author: Michael Hladky created: 2020-02-02 status: [**draft** | in review | approved | implemented | obsolete] doc url: Link to the document itself feedback url: Link to the related GitHub issue or similar design doc template version: 1.0.0 ## Objective  Angular is missing the glue to tie component/directive/pipe properties safely together in a reactive way. This code should solve the low level problems and leave enough space for custom wrappers. Also it can be used library independent. Furthermore it can be a starting point for a more specific state management e.g. something that couples with a specific global state lib. Fully tested, documented and usable version here: [@rx-angular/state](https://www.npmjs.com/package/@rx-angular/state) ### Approvals ### Expected User/Developer Experience  With this service the developer can creat fully reactive components without using the word subscribe. It takes care of handling reactive things like the router as well as imperative like Input Bindings. Under the hood it uses some logic to take care of the following problematic things: - **NO initial state needed, state is lazy. Especially important for `*ngrxLet` as it has a lazy view** - [The reentrance situation](https://stackblitz.com/edit/rxjs-notification-reentrance) - Subscribing independent fron the view - Unsubscribing from all stateful as well as side effect subscriptions when the component is destroyed - [Ensures composition is always hot, independent of subscribers](https://stackblitz.com/edit/ng-mat-rxjs-ex-hot-vs-cold) - No need to use `subscribe` anymore. As this class only tackles low level problems it could ised as core for other architectural patterns like Alex Okrushko's [Component Store Architecture](https://hackmd.io/zLKrFIadTMS2T6zCYGyHew?view) as well as for display only components that need to be reactive. --- **The naming and number of overloads of the API can still be decided on** Setup can be done in 2 ways: Inheritance: - `class MyComponent extends RxState<{key: number}>` Injection: - `constructor(state: RxState<{key: number}>)` Interaction with the state can be done over 4 methods split into 2 styles: Imperative: - **getState** - get state imperatively - **setState** - set state imperatively Ractive: - **$** - get state reactively with no optimisations - **select** - get state reactively - **connect** - set state reactively Side effects are subscribed and unsubscribed over 1 method: - **hold** - maintain subscription for side efects ### Motivational Problems The motivation here is to provide a slim API to the user and internally handle all low-level problems. Especially helpful is the `connect` and `hold` method as they enable fully reactive and subscriptionless coding. To elaborate I solve following problems: **Selection state:** ```typescript export class MyComponent { // Full object readonly state$ = this.state.select(); // state slice readonly firstName$ = this.state.select('firstName'); // nested state slice readonly firstName$ = this.state.select('user', 'firstname'); // transformation readonly firstName$ this.state.select(map(s => s.firstName)); // transformation, behaviour readonly firstName$ = this.state.select(map(s => s.firstName), debounceTime(1000)); constructor(private state: RxState<{title: string}>) { } } ``` **Connection single value input bindings to the state:** ```typescript export class MyComponent { readonly firstName$ = this.state.select(s => s.firstName); @Input() set user(user: {firstName: string, lastName: string}) { this.state.setState(user); // with previouse state this.state.setState(s => ({...user, firstName + s.otherSlice})); } constructor(private state: RxState<{title: string}>) { } } ``` **Connection in input bindings to the state:** ```typescript export class MyComponent { readonly messages$ = this.state.select(s => s.firstName); @Input() set messages(messages$) { // with single messages - Observable<string[]> this.state.connect('messages', message$); // with single messages - Observable<string> this.state.connect(messages$, => (s, m) => ({...s, messages: s.concat([m])})); } constructor(private state: RxState<{messages: string[]}>) { } } ``` **Connection Services to the state:** ```typescript export class MyComponent { readonly userRoles$ = this.state.select(s => s.userRoles); constructor(private GlobalState: Store<{userRoles: string[], ...}>, private state: RxState<{userRoles: string[]}>) { // the full global state this.state.connect(this.globalState); // The roles selection this.state.connect('userRoles', this.globalState.select(getUserRoles())); // The roles selection, with composition of the previous state this.state.connect('userRoles', this.globalState.select(getUserRoles()), (s, userRoles) => calculation(s, userRoles)); } } ``` **Managing side effects Services to the state:** ```typescript export class MyComponent { constructor(private router: Router, private state: RxState<{messages: string[]}>) { const paramChange$ = this.router.params; // Hold an already composed side effect this.state.hold(paramChange$.pipe(tap(params => this.runSideEffect(params)))); // Hold and compose side effect this.state.hold(paramChange$, (params) => this.runSideEffect(params)); } } ``` **Mantaining loading states:** ```typescript export class MyComponent { readonly users$ = this.$.select(s => s.users); readonly loading$ = this.$.select(s => s.loading); constructor(private router: Router, private userService: UserService, private $: RxState<{user: User, loading: boolean}>) { const fetchUserOnUrlChange$ = this.router.params.pipe( switchMap(p => this.userService.getUser(p.user).pipe( map(res => ({user: res.user})), startWith({loading: true}), endWith({loading: false}) )) ); this.$.connect(userFetch$); } } ``` I also did a low level research for all cornercases we need to consider: [💾 Reactive Ephemeral State](https://dev.to/rxjs/research-on-reactive-ephemeral-state-in-component-oriented-frameworks-38lk) ### Prior Art ## Prototype ### Detailed Design  ```typescript export class RxState<T extends object> implements Subscribable<any> { subscription = new Subscription(); effectSubject = new Subject<Observable<Partial<T>>>(); state stateObservables = new Subject<Observable<Partial<T>>>(); stateSlices = new Subject<Partial<T>>(); stateAccumulator: (st: T, sl: Partial<T>) => T = ( st: T, sl: Partial<T> ): T => { return { ...st, ...sl }; } $ = merge( this.stateObservables.pipe( this.distinctUntilChanged(), mergeAll(), observeOn(queueScheduler) ), this.stateSlices.pipe(observeOn(queueScheduler)) ).pipe( scan(this.stateAccumulator, {} as T), tap(newState => (this.state = newState)), publishReplay(1) ); constructor() {} getState(): T { return this.state; } setState<K extends keyof T>( projectState: ProjectStateFn<T> | K ): void { this.nextSlice( projectState(this.state) ); } connect<K extends keyof T>( slice$: Observable<any | Partial<T>>, projectFn: ProjectStateReducer<T, K> ): void { const project = projectOrSlices$; const slice$ = keyOrSlice$.pipe( filter(slice => slice !== undefined), map(v => project(this.getState(), v)) ); this.accumulationObservable.nextSliceObservable(slice$); } select<R>( ...opOrMapFn: OperatorFunction<T, R>[] | string[] ): Observable<T | R> { if (!opOrMapFn || opOrMapFn.length === 0) { return this.$.pipe(stateful()); } else if (isStringArrayGuard(opOrMapFn)) { return this.$.pipe(stateful(pluck(...opOrMapFn))); } else if (isOperateFnArrayGuard(opOrMapFn)) { return this.$.pipe(stateful(pipeFromArray(opOrMapFn))); } throw new WrongSelectParamsError(); } hold<S>( obsOrObsWithSideEffect: Observable<S>, sideEffectFn?: (arg: S) => void ): void { if (sideEffectFn) { this.effectSubject.next( obsOrObsWithSideEffect.pipe(tap(sideEffectFn)) ); return; } this.effectSubject.next(obsOrObsWithSideEffect); } subscribe(): Unsubscribable { const subscription = new Subscription(); subscription.add(this.$.subscribe()); subscription.add(this.effectSubject.subscribe()); return subscription; } } ``` **API usage:** - setState setState({key: value}); setState((state) => ({key: state.value + 1}) - getState getState().value; - connect connect(Observable<{key: value}>); connect(Observable<{key: value}>, (state, value) => ({key: state.value + value}) - select select(propertyKey) select((state) => state.value) - hold hold(Observable<any>) hold(Observable<someType>, (value: someType) => void) ### Caveats  **New wording introduced** **New concept introduced through the connect method** - Demands good documentation - Point out anti-patterns ### Performance Considerations  **distinctUntilChanged and shareReplay are placed automatically inside the select method** **Updates from retrieved denormalized state to normalized state cause a performance impact in the state selection** **Maintaining denormalized state** - Special select logic => knowledge ## Documentation Plan  Already existing docs are here as a starting point: https://github.com/BioPhoton/ngx-rx/tree/master/libs/ngx-rx-state ### Style Guide Impact  The needed documentation has no impact on the current way the documentation is maintained. ### Developer Experience Impact  This has no impact on a user's workflow but can increase performance and enables them to run zone-less. If the user decide to disable NgZone, they may need to get more familiar with RxJS operators. Other than this the user does not need to adopt or change anything. ### Breaking Changes The new pipe will not introduce any breaking changes. ## Alternatives considered  **Why is the base class not extending from the Subject class?** It's Bad practice. **Where is the reducer?** No need for a reducer as we have no actions. **Why no actions?** We are working in a local scope, there is no need to decouple from ourselves. **How to work with entities?** Predefined methods for arrays, objects, linked lists. **Why is the selection method also reactive and not using mapper functions, e.g. createSelector only?** Because create selector is not reactive. ## Work Breakdown  n/a ## Resources  - [💾 Reactive Ephemeral State](https://dev.to/rxjs/research-on-reactive-ephemeral-state-in-component-oriented-frameworks-38lk) In: Dev.to, Michael Hladky - [💾 NgRx Component Store](https://hackmd.io/zLKrFIadTMS2T6zCYGyHew?view) In: HackMD, Alex Okrushko - [💾 component-store-ngrx-demo](https://stackblitz.com/edit/component-store-ngrx-demo)In: StackBlitz, Alex Okrushko - [💾 NgRx Local Store](https://paper.dropbox.com/doc/NgRx-Local-Store-CskwmD7OBGca1YvMKVuPw) In: DropBox Paper, Mike Ryan

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.