docs: update actions doc #1561

danielglejzner · danielglejzner · commit eb3bad8dc500 · 2023-05-26T02:03:32.000+02:00
diff --git a/apps/docs/docs/state/actions/actions.mdx b/apps/docs/docs/state/actions/actions.mdx
@@ -38,51 +38,58 @@ A demo application is available on [GitHub](https://github.com/BioPhoton/rx-angu
 
 ## Motivation
 
-Signals, or a more commonly used name actions, are a common part of state management and reactive systems in general.
+Operations, or a more commonly used name actions, are a common part of state management and reactive systems in general.
 Even if `@rx-angular/state` provides `set` method, sometimes you need to add behavior to your user input or incoming events.
 
 Subjects are normally used to implement this feature. This leads, especially in bigger applications, to a messy code that is bloated with Subjects.
 
 Let's have a look at this piece of code:
 
 ```typescript
+import { Component } from '@angular/core';
+import { Subject } from 'rxjs';
+import { withLatestFrom, switchMap } from 'rxjs/operators';
+
 @Component({
+  selector: 'my-component',
   template: `
     <input (input)="searchInput($event?.target?.value)" /> Search for:
     {{ search$ | async }}<br />
     <button (click)="submitBtn()">
-      Submit<button>
-        <br />
-        <ul>
-          <li *ngFor="let item of list$ | async as list">{{ item }}</li>
-        </ul>
-      </button>
+      Submit
     </button>
+    <br />
+    <ul>
+      <li *ngFor="let item of list$ | async">{{ item }}</li>
+    </ul>
   `,
 })
-class Component {
+export class MyComponent {
   private _submitBtn = new Subject<void>();
   private _searchInput = new Subject<string>();
 
-  set submitBtn() {
-    _submitBtn.next();
+  submitBtn() {
+    this._submitBtn.next();
   }
+
   get submitBtn$() {
-    return _searchInput.asObservable();
+    return this._submitBtn.asObservable();
   }
-  set search(search: string) {
-    _searchInput.next(search);
+
+  searchInput(value: string) {
+    this._searchInput.next(value);
   }
+
   get search$() {
-    return _searchInput.asObservable();
+    return this._searchInput.asObservable();
   }
 
   list$ = this.submitBtn$.pipe(
     withLatestFrom(this.search$),
     switchMap(([_, searchString]) => this.api.query(searchString))
   );
 
-  constructor(api: API) {}
+  constructor(private api: API) {}
 }
 ```
 
@@ -110,26 +117,26 @@ interface UiActions {
     <input (input)="ui.searchInput($event)" /> Search for:
     {{ ui.search$ | async }}<br />
     <button (click)="ui.submitBtn()">
-      Submit<button>
-        <br />
-        <ul>
-          <li *ngFor="let item of list$ | async as list">{{ item }}</li>
-        </ul>
-      </button>
+      Submit
     </button>
+    <br />
+    <ul>
+      <li *ngFor="let item of list$ | async as list">{{ item }}</li>
+    </ul>
   `,
   providers: [RxActionFactory],
 })
-class Component {
-  ui = this.factory.create({ searchInput: (e) => e.target.value });
+export class Component {
+  ui = this.factory.create({ searchInput: (e) => e.target ? e.target.value : '' });
 
   list$ = this.ui.submitBtn$.pipe(
     withLatestFrom(this.ui.search$),
     switchMap(([_, searchString]) => this.api.query(searchString))
   );
 
-  constructor(api: API, private factory: RxActionFactory<UiActions>) {}
+  constructor(private api: API, private factory: RxActionFactory<UiActions>) {}
 }
+
 ```
 
 ## RxAngular Actions
@@ -155,7 +162,7 @@ yarn add @rx-angular/state
 By using RxAngular Actions we can reduce the boilerplate significantly, to do so we can start by thinking about the specific section their events and event payload types:
 
 ```typescript
-interface Commands {
+interface Actions {
   refreshUser: string | number;
   refreshList: string | number;
   refreshGenres: string | number;
@@ -165,40 +172,35 @@ interface Commands {
 Next we can use the typing to create the action object:
 
 ```typescript
-commands = getActions<Commands>();
-```
-
-The object can now be used to emit signals over setters:
-
-```typescript
-commands.refreshUser(value);
-commands.refreshList(value);
-commands.refreshGenres(value);
+const actionsFactory = new RxActionFactory<Actions>();
+const actions = actionsFactory.create();
 ```
 
-The emitted signals can be received over observable properties:
+The object can now be used to emit operations over setters:
 
 ```typescript
-refreshUser$ = commands.refreshUser$;
-refreshList$ = commands.refreshList$;
-refreshGenres$ = commands.refreshGenres$;
+actions.refreshUser(value);
+actions.refreshList(value);
+actions.refreshGenres(value);
 ```
 
-You can also emit multiple signals at once:
+The emitted operations can be received over observable properties:
 
 ```typescript
-commands({ refreshUser: true, refreshList: true });
+const refreshUser$ = actions.refreshUser$;
+const refreshList$ = actions.refreshList$;
+const refreshGenres$ = actions.refreshGenres$;
 ```
 
-If there is the need to make a combined signal you can also select multiple signals and get their emissions in one stream:
+If there is the need to make a combined operation you can also select multiple operations and get their emissions in one stream:
 
 ```typescript
-refreshUserOrList$ = commands.$(['refreshUser', 'refreshList']);
+const refreshUserOrList$ = concat(actions.refreshUser$, actions.refreshList$);
 ```
 
-### Signals in components
+### Operations in components
 
-In components/templates we can use signals to map user interaction as well as programmatic to effects or state changes.
+In components/templates we can use operations to map user interaction as well as programmatic to effects or state changes.
 This reduces the component class code as well as template.
 
 In addition, we can use it as a shorthand in the template and directly connect to action dispatching in the class.
@@ -211,8 +213,8 @@ interface UiActions {
 
 @Component({
   template: `
-    <input (input)="ui.searchInput($event)" /> Search for:
-    {{ ui.search$ | async }}<br />
+    <input (input)="ui.searchInput($event.target.value)" /> Search for:
+    {{ ui.searchInput$ | async }}<br />
     <button (click)="ui.submitBtn()">
       Submit<button>
         <br />
@@ -225,10 +227,10 @@ interface UiActions {
   providers: [RxState, RxActionFactory],
 })
 class Component {
-  ui = this.factory.create({ searchInput: (e) => e?.target?.value });
+  ui = this.factory.create<UiActions>({ searchInput: (e) => e });
   list$ = this.state.select('list');
   submittedSearchQuery$ = this.ui.submitBtn$.pipe(
-    withLatestFrom(this.ui.search$),
+    withLatestFrom(this.ui.searchInput$),
     map(([_, search]) => search),
     debounceTime(1500)
   );
@@ -238,14 +240,14 @@ class Component {
     private factory: RxActionFactory<UiActions>,
     globalState: StateService
   ) {
-    super();
     this.connect('list', this.globalState.refreshGenres$);
 
     this.state.hold(this.submittedSearchQuery$, this.globalState.refreshGenres);
     // Optional reactively:
     // this.globalState.connectRefreshGenres(this.submittedSearchQuery$);
   }
 }
+
 ```
 
 #### Using transforms
@@ -265,43 +267,46 @@ You can write you own transforms or use the predefined functions:
 - eventValue
 
 ```typescript
+import { Component } from '@angular/core';
+import { RxState, RxActionFactory } from '@rx-angular/state';
+import { StateService } from './state.service';
+import { withLatestFrom, map, debounceTime } from 'rxjs/operators';
+
 interface UiActions {
   submitBtn: void;
   searchInput: string;
 }
 
 @Component({
+  selector: 'my-component',
   template: `
     <input (input)="ui.searchInput($event)" /> Search for:
-    {{ ui.search$ | async }}<br />
+    {{ ui.searchInput$ | async }}<br />
     <button (click)="ui.submitBtn()">
-      Submit<button>
-        <br />
-        <ul>
-          <li *ngFor="let item of list$ | async as list">{{ item }}</li>
-        </ul>
-      </button>
+      Submit
     </button>
+    <br />
+    <ul>
+      <li *ngFor="let item of list$ | async">{{ item }}</li>
+    </ul>
   `,
   providers: [RxState, RxActionFactory],
 })
-class Component {
-  //                                (e) => e.target ? e.target.value : e
-  ui = this.factory.create({ searchInput: eventValue });
+export class MyComponent {
+  ui = this.factory.create<UiActions>({ searchInput: eventValue });
   list$ = this.state.select('list');
   submittedSearchQuery$ = this.ui.submitBtn$.pipe(
-    withLatestFrom(this.ui.search$),
+    withLatestFrom(this.ui.searchInput$),
     map(([_, search]) => search),
     debounceTime(1500)
   );
 
   constructor(
     private state: RxState<State>,
     private factory: RxActionFactory<UiActions>,
-    globalState: StateService
+    private globalState: StateService
   ) {
-    super();
-    this.connect('list', this.globalState.refreshGenres$);
+    this.state.connect('list', this.globalState.refreshGenres$);
 
     this.state.hold(this.submittedSearchQuery$, this.globalState.refreshGenres);
     // Optional reactively:
@@ -321,15 +326,15 @@ interface State {
   genres: MovieGenreModel[];
 }
 
-interface Commands {
+interface Actions {
   refreshGenres: string | number;
 }
 
 @Injectable({
   providedIn: 'root',
 })
 export class StateService extends RxState<State> {
-  private commands = new RxActionFactory<Commands>().create();
+  private actions = new RxActionFactory<Actions>().create();
 
   genres$ = this.select('genres');
 
@@ -338,20 +343,21 @@ export class StateService extends RxState<State> {
 
     this.connect(
       'genres',
-      this.commands.fetchGenres$.pipe(exhaustMap(this.tmdb2Service.getGenres))
+      this.actions.refreshGenres$.pipe(exhaustMap(this.tmdb2Service.getGenres))
     );
   }
 
-  refreshGenres(genre: string): void {
-    this.commands.fetchGenres(genre);
+  refreshGenres(genre: string | number): void {
+    this.actions.refreshGenres(genre);
   }
 
   // Optionally the reactive way
-  connectRefreshGenres(genre$: Observable<string>): void {
-    this.connect(
-      'genres',
-      this.commands.fetchGenres$.pipe(exhaustMap(this.tmdb2Service.getGenres))
+  connectRefreshGenres(genre$: Observable<string | number>): void {
+    this.hold(
+      genre$,
+      genre => this.actions.refreshGenres(genre)
     );
   }
 }
+
 ```
