NgxSherlock is a set of Angular bindings for the Sherlock reactive state management library.
Install NgxSherlock by running:
$ npm install @politie/ngx-sherlockAdd the NgxSherlockModule to your AppModule:
import { NgModule } from '@angular/core';
import { NgxSherlockModule } from '@politie/ngx-sherlock';
@NgModule({
imports: [NgxSherlockModule],
...
})
export class AppModule { }Signature:
class AutoChangeDetectorService {
init(): Promise<void>;
}The AutoChangeDetectorService enables automatic change detection when using Sherlock Derivables, even when using the OnPush change-detection-strategy. The alternative is to use the value-pipe which is explained below. When using the AutoChangeDetectorService it is no longer needed to use the pipe.
The service needs to be instantiated once for each component. This is accomplished by mentioning it in the providers section of the Component metadata. It will detach the default ChangeDetector and re-enables change detection once #init() is called. This will ensure that change detection is wrapped with Sherlock magic.
The AutoChangeDetectorService service guarantees model and view fidelity, meaning one can easily use Angular's forms and template functionality.
trusty-sidekick.component.ts:
import { Component, ChangeDetectionStrategy, ChangeDetectorRef, Input } from '@angular/core';
import { AutoChangeDetectorService } from '@politie/ngx-sherlock';
import { atom, Derivable } from '@politie/sherlock';
@Component({
selector: 'trusty-sidekick',
template: `
<input type="text" [(ngModel)]="firstname$.value" placeholder="First name">
<input type="text" [(ngModel)]="surname$.value" placeholder="Surname">
<sidekick-greeter [name]="sidekick$"></sidekick-greeter>
`,
providers: [AutoChangeDetectorService],
})
export class TrustySidekickComponent {
readonly sidekick$ = atom({ firstname: 'John', surname: 'Watson' });
readonly firstname$ = this.sidekick$.pluck('firstname');
readonly surname$ = this.sidekick$.pluck('surname');
// Here we call AutoChangeDetectorService#init which will automatically react on changes in the state of
// any used derivable.
constructor(autoCD: AutoChangeDetectorService) { autoCD.init(); }
}
@Component({
selector: 'sidekick-greeter',
template: `
<h2 *ngIf="!beObnoxious">Well hello there, {{ name.value.firstname }} {{ name.value.surname }}!</h2>
<h2 *ngIf="beObnoxious">So good of you to finally join us, {{ name.value.surname }}...</h2>
<button (click)="toggle()">Change mood</button>
`,
changeDetection: ChangeDetectionStrategy.OnPush,
providers: [AutoChangeDetectorService],
})
export class SidekickGreeterComponent implements OnInit {
@Input() name: Derivable<{ firstname: string, surname: string }>;
obnoxious$ = atom(false);
get beObnoxious() {
return this.obnoxious$.get();
}
constructor(autoCD: AutoChangeDetectorService) { autoCD.init(); }
toggle() {
this.obnoxious$.swap(mood => !mood);
}
}The ValuePipe unwraps a Derivable or DerivableProxy value and triggers the ChangeDetectorRef whenever an internal value changes
and a change detection cycle is needed. This allows a component to have an OnPush ChangeDetectionStrategy, greatly increasing
performance.
my.component.html:
<h1>My awesome counter</h1>
<p>We're already at: <strong>{{ counter$ | value }}</strong></p>my.component.ts:
import { Component, OnInit, ChangeDetectionStrategy } from '@angular/core';
import { atom } from '@politie/sherlock';
@Component({
selector: 'my-component';
templateUrl: 'my.component.html',
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class MyComponent implements OnInit {
readonly counter$ = atom(0);
ngOnInit() {
setInterval(() => this.counter$.swap(i => i++), 1000);
}
}