Prefabricated facades in NgRx Auto-Entity expose all the necessary properties and methods to allow you to fully leverage all of the state, actions and selectors Auto-Entity manages. Once you have extended a class from the base facade class, you may leverage all of this functionality without any additional effort.

Selections (Observable Data Properties)

Each entity facade exposes a number of properties that wrap NgRx state selections, exposing the streaming data within. Each of these properties returns and Observable of the appropriate type based on the state Auto-Entity tracks. We call these selections. The available properties on every entity facade include the following:

Familiar Functionality

All of these properties are encapsulating functionality you may already be familiar with. In the past with plain old NgRx, you might have done something like the following:

This is in fact what all of the entity facade properties are doing for you. We simplify the above repetitive procedure so you may simply access a property rather than have to bring in the store, pipe and select yourself:

Still Observable

Since all of our entity facade properties are observables, you are still free to use .pipe() on them as necessary, and leverage the full power of RxJs and reactive programming.

Prefabricated facades are one of NgRx Auto-Entities most powerful offerings. Not only can they greatly simplify your code, facades offer a way of organizing and encapsulating core business logic. You can pull a lot of behavior out of your components and move it into your facades. This simplifies your components, and can potentially improve code reuse.

Generated for You

When preparing your state with a call to the buildState function, Auto-Entity will generate an entity facade class for you. These classes are best considered to be base classes, from which you should extend another class. See the instructions on how in the next section.

Rich Prefabricated Functionality

Prefabricated facades come complete with a core set of properties and methods that may be used "out of the box" without any additional work on your part beyond extending the base facade class. There is no explicit need to wrap every property or method provided by a facade base class in your own class in order to use it. You may, and are encouraged to, add your own custom properties and methods to encapsulate higher level behavior, though!

To use one of these properties in your component, simply inject your facade classes:

export class CustomersComponent implements OnInit {
    customers$: Observable<Customer[]>;
    currentCustomer$: Observable<Customer>;
    isLoading$: Observable<boolean>;
    
    constructor(private customers: CustomerFacade) {
    }
    
    ngOnInit(): void {
        this.customers$ = this.customers.all$;
        this.customer$ = this.customers.current$;
        this.isLoading$ = this.customers.isLoading$;
        
        this.customers.loadAll();
    }
    
    select(customer: Customer): void {
        this.customers.select(customer);
    }
}

The classic use case is to expose observables on your component to represent the various streams you will use in your template. With NgRx Auto-Entity, this becomes a rather trivial exercise, as there is no real work that must be done in the component. (Continue to the next section to learn how to improve upon the classic approach when using facades.)

Use the Async Pipe

We highly recommend following NgRx best practices here to avoid subscribing directly to any observable on an entity facade. Instead, use the async pipe from Angular in your templates, and follow container/presenter model for your component architecture:

<div class="customers" *ngIf="isLoading$ | async; else #loading">
    <app-customer-list 
        [customers]="customers$ | async" 
        (selected)="select($event)">
    </app-customer-list>
    <app-customer-detail 
        *ngIf="(customer$ | async) as customer"
        [customer]="customer">
    </app-customer-detail>
</div>
<ng-template #loading>
Loading customers...
</ng-template>

NgRx Auto-Entity will generate a new facade class for you dynamically whenever you call buildState. You may optionally destructure this facade class from the response, along with destructuring other core aspects of your new state:

export const { initialState, facade: CustomerFacadeBase } = buildState(Customer);
export function customerReducer(state = initialState): IEntityState<Customer> {
    return state;
}

The above is the recommended and most minimal use case for the building states with Auto-Entity. For most use cases, nothing beyond the initialState and facade class should be required.

We also recommend renaming for export the name facade into a more appropriate, unique name for a base facade class for your entity. In the example here, we have renamed the facade to CustomerFacadeBase.

Extending a Concrete Facade

Once you have your base facade class, you will need to extend the proper facade class from it. Extension is required in order to provide the facade base class with the necessary services. Since our facades are dynamically generated classes created by a simple function, we are unable to leverage the Angular Injector directly.

export class CustomerFacade extends CustomerFacadeBase {
    constructor(private store: Store<AppState>) {
        super(Customer, store);
    }
}

The above is the most minimal use case for a facade. The only requirement is to call super() from within your constructor, and pass in the entity model type as well as the store. From here, you may start using all of the ready-made functionality the base facade offers, without any additional work.

Prefabricated facades in NgRx Auto-Entity expose all the necessary properties and methods to allow you to fully leverage all of the state, actions and selectors Auto-Entity manages. Once you have extended a class from the base facade class, you may leverage all of this functionality without any additional effort.

Activities (Action Dispatching Methods)

In addition to properties for each selection, entity facades also expose a number of methods that wrap NgRx action dispatch calls. Each of these methods handles creation and subsequent dispatch of the appropriate generic action, including handling all the type information. We call these activities. The available methods on every facade include:

Familiar Functionality

All of these methods, as with the properties, are encapsulating functionality you may already be familiar with. In the past with plain old NgRx, you might have done something like the following:

this.store.dispatch(new LoadAll(Customer, { organizationId: orgId }));

This is in fact what all of the entity facade methods are doing for you. We simplify the above repetitive procedure so you may simply call a method with just the bare bones required arguments, rather than have to bring in the store, dispatch and construct new actions yourself:

loadAll(criteria?: any): void {
  this.store.dispatch(new LoadAll(this.modelType, criteria));
}

The model type is tracked when you extend the facade base class with your own concrete implementation:

export class CustomerFacade extends CustomerFacadeBase {
    constructor(private store: Store<AppState>) {
        super(Customer, store); // Passing Customer here sets this.modelType
    }
}

In some cases, assigning facade properties to other properties on your component classes may itself be somewhat overly complex. There is not necessarily an explicit need to have observable properties on the component itself.

Light Weight Containers

For container components such as the above Customers component, there is nothing of particular note in the component itself that isn't simply replicating functionality we already have in the facade. We could simply expose the facade to the template by making it public in the constructor:

export class CustomersComponent {    
    constructor(public customers: CustomerFacade) {
        customers.loadAll();
    }
}

Facade in the Template

Then simply use the facade within the template, as it already provides all of the same exact functionality:

<div class="customers" *ngIf="customers.isLoading$ | async; else #loading">
    <app-customer-list 
        [customers]="customers.all$ | async" 
        (selected)="customers.select($event)">
    </app-customer-list>
    <app-customer-detail 
        *ngIf="(customers.current$ | async) as customer"
        [customer]="customer">
    </app-customer-detail>
</div>
<ng-template #loading>
    Loading customers...
</ng-template>

Note just how simple this container component is now that we have leveraged the full capabilities of a generated auto-entity facade! And note just how little code you really had to write.

To use one of these activities in your component, simply inject your facade class and call the method in the constructor, an ngOnInit or similar handler, or a custom handler:

export class CustomersComponent implements OnInit {    
    constructor(
        public customers: CustomerFacade, 
        public router: Router,
        public route: ActivatedRoute
    ) {
        this.customers.loadAll();
    }
    
    ngOnInit(): void {
        this.route.paramMap.pipe(
            filter(params => params.has('id')),
            map(params => params.get('id'))
        ).subscribe(id => this.customers.selectByKey(id));
    }
    
    select(customer: Customer): void {
        this.router.navigate(['./', customer.id]);
    }
}

Use the Async Pipe!

We highly recommend following NgRx best practices here to avoid subscribing directly to any observable on an entity facade. Instead, use the async pipe from Angular in your templates, and follow container/presenter model for your component architecture:

<div class="customers" *ngIf="customers.isLoading$ | async; else #loading">
    <app-customer-list 
        [customers]="customers.all$ | async" 
        (selected)="select($event)">
    </app-customer-list>
    <app-customer-detail 
        *ngIf="(customers.current$ | async) as customer"
        [customer]="customer">
    </app-customer-detail>
</div>
<ng-template #loading>
    Loading customers...
</ng-template>

Here is the full excerpt of code that you had to write to implement our customers container component from the facade examples. We are assuming code module imports are handled by the IDE and are not something you would necessarily "write" yourself. Standard Angular decorator content excluded as it is usually generated for you.