DEV Community: Michael Muscat

Rules for Decorators: Why meta-programming in Angular sucks, and what you can do about it

Michael Muscat — Fri, 23 Sep 2022 09:14:50 +0000

Back in 2016 Angular was the first major web framework to launch with TypeScript as the primary authoring language, using ES6 classes, observables and decorators as its core building blocks.

Angular was taking some very big risks here. RxJS 5 was still in beta. To this day there is still no officially accepted proposal for JavaScript observables or decorators. The first stable release of "Angular 2" (now just "Angular") was a bit of a disaster. It wasn't until Angular 4 launched with its new Ahead-of-Time (AOT) compiler that new-Angular really hit its stride.

@Component({
  template: `
    <div>Hello {{name}}!</div>
  `,
  styles: [`h1 { font-family: Lato; }`]
})
export class HelloComponent {
  @Input() name: string
}

Now when we write an Angular component the decorator is magicked away during the AoT compilation process, where it is transformed and in-lined into static properties of the component class.

export class HelloComponent {
  static ɵcmp = {
    declaredInputs: Object { name: "name" },
    inputs: Object { name: "name" },
    selectors: [["hello"]],
    styles: ["h1[_ngcontent-%COMP%] { font-family: Lato; }"],
    template: function HelloComponent_Template(rf, ctx) {
      if (rf & 1) {
        i0.ɵɵelementStart(0, "h1");
        i0.ɵɵtext(1);
        i0.ɵɵelementEnd();
      } if (rf & 2) {
        i0.ɵɵadvance(1);
        i0.ɵɵtextInterpolate1("Hello ", ctx.name, "!");
      }
    },
    ...etc
  }

  static ɵfac = function HelloComponent_Factory() {
    return new HelloComponent()
  }
}

If you serve an Angular application and look at the compiled output you will see code like the example above. The Angular decorators aren't anywhere to be seen. However, that is not always the case...

Ahead-of-Time vs Just-in-Time compilation

Angular has two compilers, Ahead-of-Time (AOT) and Just-in-Time (JIT). Most of the time you don't notice the difference until you do.

Ahead-of-Time

This is the default compiler when serving and building Angular apps. Angular decorators are compiled into static properties during the build process and don't exist at runtime.

Just-in-Time

This is the compiler used when AOT compilation is disabled or not available. Angular decorators are evaluated at runtime, just before the application runs. This requires the Angular compiler to be shipped to the browser.

Unit Tests

When we run unit tests, Angular uses a combination of AOT and JIT compilation modes. If the code is already AOT compiled (eg. a library), it will use the compiled code. If the code is not compiled yet (eg. a component under test), JIT compilation is used.

Can you guess when the compilation happens?

@Component({ template: "" })
class UITest {}

describe("UITest", () => {
  it("should compile", () => {
    TestBed.configureTestingModule({
      declarations: [UITest]
    })

    const fixture = TestBed.createComponent(UITest)

    expect(fixture.componentInstance).toBeInstanceOf(UITest)
  })
})

That's right, the compilation happens when we call createComponent. The first call to TestBed.createComponent or TestBed.inject bootstraps the test environment and triggers JIT compilation.

Why Meta-Programming In Angular Sucks

Now that we have the backstory, here are the reasons why meta-programming in Angular sucks.

No Officially Supported Meta-Programming API

Angular, which uses decorators, does not let us add our own custom decorators! We are forced to deal with the idiosyncrasies of AOT and JIT compilation. There is no official support from Angular.

For meta-programming in Angular to be useful, we need to be able to do three things:

Obtain a reference to a decorated component's instance and injector.
Run initialization logic.
Run logic during lifecycle hooks.

Object Identity

Let's say we want to write a decorator that extends an Angular component.

function Store() {
  return function (target) {
    return class WithStore extends target {
      constructor(...args) {
        super(...args)
        console.log("extended!", inject(INJECTOR))
      }
    }
  }
}

What happens when we try to inject the decorated class?

@Store()
@Component()
export class UICounter {
  constructor(injector: Injector) {
    setTimeout(() => {
      console.log(injector.get(UICounter))
    })
  }
}

If you run this code in a unit test, it logs the component instance. If you run this code in the actual app, it throws:

NG0201: No provider for WithStore found!

Wait, what? To understand this, remember that Store is returning a new class called WithStore, not UICounter. In AOT compilation, Angular statically constructs the dependency injection container. It doesn't "see" WithStore since it hasn't executed yet. So the container is created with reference to UICounter. When we try to inject WithStore, no provider is found.

Why does this work in the unit test? In JIT mode the dependency injection container isn't created until the component is compiled, which is after the Store decorator is evaluated.

Order of Execution

Which decorator executes first?

@Store()
@Component()
export class UICounter {}

TypeScript experimental decorators are always called from bottom-to-top, so Component is called before Store. If we run this in an application we see this is true.

What about now?

@Component()
@Store()
export class UICounter {}

Running this code inside a unit test shows that Store is called first as we expect. In the actual app however, Component is executed during the build process, before Store has a chance to execute. This is a problem if Store depends on metadata set by Component. To make this work in both JIT and AOT, Store should be deferred until we know Component is executed.

These surprising behaviours make meta-programming in Angular almost impossible, but if you are willing to risk it there is a way.

Rules for Decorators

Here are five simple rules to follow for writing good decorators.

1. Never extend the base class

Extending a component is the easiest way to add some logic when it is created. As of Angular 14 we can also use inject to save a reference to the injector. However, since decorators are not statically analysable we run into the Object Identity problem.

2. Never replace a decorated class property with an incompatible type signature

Class field, accessor and method decorators should only replace the decorated property with a value that satisfies the original type signature.

@Store()
class UITodos {
  http = inject(HttpClient)

  @Action() loadTodos(userId: string): Observable<Todo[]> {
    return this.http.get(endpoint, { params: { userId }})
  }
}

Here the Action decorator taps the returned observable, returning a new observable that mirrors the original return type. Since TypeScript can't detect decorator type incompatibilities it is up to the author to ensure runtime types are compatible.

@Store()
class UITodos {
  todos: Todo[] = []

  @Select() get remaining(): Todo[] {
    return this.todos.filter(todo => !todo.completed)
  }
}

Here's another example with an accessor field. The Select decorator memoizes the getter function without changing its semantics.

Don't turn class fields into class accessors. Even if the type signature looks the same, the runtime semantics are completely different.

3. Don't inherit decorators from base classes

It's not worth the trouble. Lets avoid using class inheritance entirely. If you do explore this area you might run into obscure problems with code instrumentation in unit tests.

4. Don't extend the public API of a class.

Similar to Rule 2, don't use field decorators to add new properties to a class. Field decorators should only record metadata for a class decorator to process.

@Store()
@Component()
export class UICounter {
  count = 0

  @Action() increment() {
    this.count++
  }
}

The Action decorator does nothing but record the field name as metadata. When Store executes it reads the metadata and wraps the increment method by mutating the class prototype. It also attaches Angular lifecycle hooks.

From the consumer's perspective the class API hasn't changed.

5. Don't use decorators for everything

Unless you have a really good reason to, writing your own decorators should be avoided altogether.

How to decorate an Angular component

Currently this is only possible by accessing private Angular APIs. Use at your own risk.

@Component()
export class UICounter {
  @Input() count = 0
}

Rule 1 says we cannot use decorators to extend a class. So how do we obtain the component instance and injector?

const injector = Symbol("injector")

function Store() {
  return function(target) {
    const factory = target["ɵfac"]
    Object.defineProperty(target, "ɵfac", {
      value: function (...args) {
        const cmp = factory(...args)
        Reflect.defineMetadata(injector, inject(INJECTOR), cmp) 
        return cmp
      }
    })
  }
}

Thankfully, Angular does not invoke component class constructors directly. Instead, the Angular compiler creates a factory function that instantiates the component for us. This factory is also responsible for dependency injection in the constructor. By wrapping this factory we can then intercept the constructor call, obtain the component instance, and save a reference to the injector for later use.

@Store()
@Component()
export class UICounter {
  @Input() count = 0

  @Action() increment() {
    this.count++
  }
}

So we managed to solve the Object Identity, but we still have a Order of Execution problem when we try to run this code in unit tests which use JIT instead of AOT compilation.

@Component()
@Store() // target["ɵfac"] is undefined
export class UICounter {}

The end user shouldn't have to worry about the order of execution. In AOT everything works as expected, so let's focus on making JIT work.

const injector = Symbol("injector")
const decorators = new Map()

function wrapFactory(target) {
  const factory = target["ɵfac"]
  Object.defineProperty(target, "ɵfac", {
    value: function (...args) {
      const cmp = factory(...args)
      Reflect.defineMetadata(injector, inject(INJECTOR), cmp) 
      return cmp
    }
  })
}

function Store() {
  return function(target) {
    const factory = target["ɵfac"]
    if (factory) {
      wrapFactory(target)
    } else {
      decorators.add(target, wrapFactory)
    }
  }
}

function processDecorators() {
  for (const [target, decorate] of decorators) {
    decorate(target)
  }
  decorators.clear()
}

If we detect that there's an existing factory, then we wrap the factory immediately. Otherwise we cache the operation until we call processDecorators to finish decorating the component. For unit tests all we need to do is call processDecorators when the test environment is created.

@NgModule()
export class InitStoreTestingModule {
  constructor() {
    processDecorators()
  }
}

function initStoreTestingEnvironment() {
  beforeEach(() => {
    TestBed.configureTestingModule({
      imports: [InitStoreTestingModule]
    })
  })
}

Then just call the function inside the main test setup file

// test.ts

getTestBed().initTestingModule()
initStoreTestingEnvironment() // call before any tests are loaded

Since modules are loaded eagerly, and we register it as the first module, it will run before any component is created, but after all decorators have been evaluated. The decorator now works in both JIT and AOT modes.

Working Example

Good decorators are difficult to write, but easy to use. To see this in action check out how Angular State Library uses decorators to eliminate the boilerplate of state management.

Thanks for reading!

Turn a Directive Into a Fragment

Michael Muscat — Tue, 13 Sep 2022 03:20:49 +0000

You probably shouldn't do this. It's a bad idea. So anyway here's the code.

@Directive()
export class Fragment {
  nativeElement;
  comment;
  childNodes

  constructor() {
    this.nativeElement = inject(ElementRef).nativeElement;
    this.comment = document.createComment(
      ` ${Object.getPrototypeOf(this).constructor.name} `
    );
  }

  ngAfterViewInit() {
    const { nativeElement, comment } = this;
    const parent = nativeElement.parentElement;
    this.childNodes = Array.from(nativeElement.childNodes)
    parent.insertBefore(comment, nativeElement);
    for (const node of this.childNodes) {
      parent.insertBefore(node, nativeElement);
    }
    nativeElement.remove();
  }

  ngOnDestroy() {
    this.comment.remove();
    for (const node of this.childNodes) {
      node.remove()
    }
  }
}

This will replace the host element of a directive with whatever is inside it. It even leaves a nice little comment behind.

To see how it's used let's create a provider that will pass through values from the template.

@Directive({
  selector: 'MyProvider',
})
export class MyProvider extends Fragment {
  @Input() value;
}

We're using TitleCase here to distinguish it from rendered DOM elements. Remember that Angular selectors are case sensitive.

Now we can import the directive and use it in a template.

<MyProvider [value]="name">
  <hello></hello>
</MyProvider>

The hello component can then inject the provider to read its value.

@Component({
  selector: 'hello',
  template: `<h1>Hello {{provider.value}}!</h1>`,
  styles: [`h1 { font-family: Lato; }`],
})
export class HelloComponent {
  provider = inject(MyProvider);
}

See it in action on StackBlitz

When we look at the DOM we can see that the host element is replaced with a HTML comment.

Is This a Good Idea?

Probably not. All it does is add some sugar to <ng-container> in a not-very efficient way. There are probably other side effects I'm not aware of.

Can you think of a use case?

Directives as a Service

Michael Muscat — Fri, 09 Sep 2022 08:03:01 +0000

One of the unique features of Angular State Library is that every store is a @Directive.

Disclaimer: This project is an experiment, it is not production ready.

Unlike services, directives have access to inputs, outputs, host bindings/listeners, lifecycle hooks, templates, and queries. Directives are also instantiated eagerly, while services remain dormant until something else injects it. Directives have full control over the DOM.

Using directives as a service isn't a new concept. It's common practice to inject directives and components from other components in the injector tree. But we don't always think of directives as services, or that we might want services to be like a directive.

@Store()
@Component()
export class UIButton {
  @Input() disabled = false

  @Action()
  @HostListener("click")
  animateClick() {
    const { nativeElement } = inject(ElementRef)
    if (!this.disabled) {
      return dispatch(animateRipple(nativeElement), {
        complete() {
          console.log("animation done")
        }
      })
    }
  }
}

function animateRipple(element) {
  // use your imagination
}

Can your redux store do this?

In Angular State Library, a @Store is both a directive and a service. By using directives we can eliminate most of the boilerplate that comes with state management.

Template Providers

Since directives have inputs, we can make stores configurable. The store can then be re-used in different ways without sub-classing. This can be used to create a context API similar to React.

@Directive({
  standalone: true,
  selector: "ui-theme",
})
export class UITheme extends TemplateProvider {
  color = "red"
}

The theme provider can then be configured from a parent component.

<ui-theme [value]="blueTheme">
  <ui-button>Blue button</ui-button>
</ui-theme>
<ui-theme [value]="greenTheme">
  <ui-button>Green button</ui-button>
</ui-theme>

@Component({
  standalone: true,
  imports: [UITheme],
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class UIApp {
  blueTheme = {
    color: "blue"
  }
  greenTheme = {
    color: "green"
  }
}

And consumed from a descendant component.

<div [style.color]="theme.color">
  <ng-content></ng-content>
</div>

@Component({
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class UIButton {
  theme = select(UITheme)
}

We now have a configurable and reactive store that can be composed anywhere in our application.

Host Directives

Host Directives are the perfect use case for directives as a service. In Angular 15 (pending) we will be able to add directives to a host component without adding them to the template. This means we can attach root stores directly to a root @Component or Angular Element, which currently isn't possible.

@Component({
  standalone: true,
  selector: "ui-root",
  hostDirectives: [
    AuthStore, 
    ProfileStore, 
    NotificationStore
  ]
})
export class UIRoot {}

We will have to wait and see what the final solution looks like once it's released, but for now we can work around this by attaching the host directives to the component template instead.

<ng-container authStore profileStore notificationStore>
  <router-outlet></router-outlet>
</ng-container>

Good enough for now

When to Use a Directive Instead of a Service

This is just an opinion, but you might want to use a directive as a service if:

The service is stateful

A directive has the advantage of lifecycle hooks to properly manage long-lived subscriptions, react to input changes, and run change detection. It's also much easier to compose in templates.

The service depends on DOM elements or DOM events

While services can access the host element if it is provided in a directive, a directive can also use @Content and @View queries. It also has access to @HostListener and @HostBinding to make things easier.

The service needs to be initialized before it is injected

Directives are like ENVIRONMENT_INITIALIZER, except it works at component scope instead of application scope. Directives are always eager.

Angular State Library is a yes on all fronts. You can also start using your own directives as a service today.

Help Wanted

This project is currently a proof of concept. It's no where near production ready. If you are interested in contributing or dogfooding feel free to open a line on Github discussions, or leave a comment with your thoughts below.

Thanks for reading!

Reactivity In Actions

Michael Muscat — Tue, 06 Sep 2022 14:29:00 +0000

In Angular State Library actions are everything. And everything is an action.

Disclaimer: This project is an experiment, it is not production ready.

@Store()
@Component({
  changeDetection: ChangeDetectionStrategy.OnPush,
  providers: [Counter.Provide(UICounter)],
  selector: 'ui-counter',
  template:
    <p>UICounter: {{ count }}</p>
    <dd>
      <ng-content></ng-content>
    </dd>
})
export class UICounter {
  @Input() count = 0;
  @Output() countChange = new EventEmitter<number>(true);

  @Invoke() autoIncrement() {
    this.count++;
    this.countChange.emit(this.count);

    return dispatch(timer(1000), {
      next: this.autoIncrement,
    });
  }
}

The secret to reactivity in Angular is knowing when to run change detection. By default, Angular runs change detection for us automatically every time we interact with the DOM or do some async work. This magical reactivity is what sets Angular apart from the crowd. But it comes at a cost. Performance.

Pushing Problems

As an Angular application grows in size and complexity, we start running into problems. The more components we render, the slower each render cycle gets. This is because Angular dirty checks every data binding in every component every time change detection runs. How often does change detection run? A lot.

The root cause of this slow down is Zone.js. On every user interaction, microtask (eg. promises) and macrotask (eg. timers), Zone.js lets Angular know that it should run change detection in case some data binding in the app has changed. We have a budget to keep of 16ms (60Hz) or 8ms (120Hz) so that the user experience remains fluid. Angular's change detection cycle can easily exceed this limit.

To manage this problem, Angular says we should configure components to use the OnPush change detection strategy.

The OnPush Problem

The OnPush strategy tells Angular that this component's change detection tree should only be checked:

When @Input bindings change.
When an (event) binding emits.
When change detection is run manually.

In the example above we can see that the components rendered inside the OnPush component do not update when the counter changes. Since there is no input binding and no template event, that leaves only one option.

Manual Change Detection

At some point we will need to call markForCheck. This marks the view dirty so that Angular will check the component and update its host bindings and template bindings if necessary. There are two common approaches:

Async Pipes

Most Angular apps use AsyncPipe, which calls markForCheck internally. This in my opinion creates more problems than it solves, due to the cognitive load of async behaviour in templates plus the non-intuitive nature of RxJS. If a developer isn't familiar with the differences between unicast/multicast, and hot/cold observables, they're going to have a bad time.

Manual Subscribe

Subscribing in components is often frowned-upon, but it's a lot easier than using AsyncPipe, especially for callbacks.

@Component({
  changeDetection: ChangeDetectionStrategy.OnPush,
  template:
    <div>{{ data | json }}</div>
    <button (click)="loadData()">
      Load Data
    </button>
})i
export class UIData {
  private http = inject(HttpClient)
  private changeDetector = inject(ChangeDetectorRef)

  data

  loadData() {
    this.http.get(endpoint).subscribe((data) => {
      this.data = data
      this.changeDetector.markForCheck()
    })
  }
}

What about subscription management?

Of course, we still need to know when and how to manage long-lived subscriptions to prevent memory leaks.

Square Peg, Round Hole

Both approaches to manual change detection are lacking. This is because RxJS and Angular are built on fundamentally different paradigms. RxJS is functional and composable, while Angular components are object-oriented and imperative.

Putting RxJS into Angular templates

There are many existing solutions to this problem, but all come at the cost of increased complexity. We can offload state to services, but now we need a way to connect the service to our component. We can offload state to redux, but now we have to manage several layers of indirection. Why can't state management be simpler?

`Observable` Core, `@Directive` Shell

Hat tip Destroy All Software

Angular State Library solves the OnPush problem, combining Vue-style reactivity, RxJS and Redux. It also solves the square peg/round hole problem by keeping state management imperative on Angular's side while extracting RxJS into functional-composable side effects. Effects are then mapped back onto the component's state using imperative callbacks (ie. action reducers).

Any directive can be converted into a redux store without added layers of indirection and boilerplate. The possibilities are endless.

Reactivity in Action

The secret to reactivity is observable events. All events generated by Angular State Library are dispatched to a global event stream. All events are generated by actions.

The event stream is populated by calls to @Action methods
@Input changes are also tracked as events via ngOnChanges.
The event stream captures the next, error and complete events from dispatched effects.
Components connect to a store by providing a StoreToken.
The StoreToken subscribes to the store's event stream and triggers markForCheck to update the view when an event is emitted.
The StoreToken returns the store's state as a reactive proxy object for tracking in other actions and selectors.

Now we can inject stores anywhere without worrying about OnPush or subscriptions. It just works.

Help Wanted

Thanks for Reading!

Angular State Library

Michael Muscat — Sat, 03 Sep 2022 15:32:44 +0000

Disclaimer: This project is an experiment, it is not production ready.

Introduction

Why: I love RxJS. The integration between Angular and RxJS leaves much to the imagination. Existing state libraries are complicated and verbose.

How: It uses TypeScript decorators to wrap class methods in an injection context. ES6 Proxies wrap this to capture reactive dependencies. Reactive dependencies are dirty-checked during change detection. Reactive functions are invoked when their dependencies have changed.

What: Angular State Library borrows from Vue's reactivity system, combining it with RxJS observables and Redux, without boilerplate.

Redux: The Good Parts

Redux is a simple idea. State plus action equals new state. Also known as a reducer. For some this is means pure functions. But libraries like Immer and redux-thunk allow us to describe state changes in other, more ergonomic ways.

@Component()
export class UICounter {
   count = 0

   increment() {
      this.count++
   }
}

Is this redux?

Another aspect of redux is observability. One part of the system can observe the outputs of another part of the system and perform more actions. Sometimes we call these sagas, or side effects. Action plus side effect equals more actions.

@Component()
export class UICounter {
   count = 0

   increment() {
      this.count++

      setTimeout(() => {
         this.count *= 2
      }, 2000)
   }
}

Is this redux?

There are other benefits to using redux, such as immutability and development tools. These are secondary concerns. What we have done is boil down redux to two simple principles.

State is mutated when an action occurs.
Side effects are triggered after an action occurs.

We can implement this however we want. For Angular, we can do a whole lot more.

Angular State Library

@Store()
@Component()
export class UICounter {
   count = 0

   @Action() increment() {
      this.count++

      return dispatch(timer(2000), () =>
         this.count *= 2
      })
   }
}

const dispatch = createDispatch(UICounter)

Angular State Library is Redux reimagined.

The goal of this project is to eliminate the complexity of state management in Angular. There are no action factories here. No modules, no facades, no adapters. Just a simple Angular directive. Add some decorators and we're good to go.

Declarative State

State changes can be expressed declaratively. Functions decorated by @Invoke() are called automatically during the first change detection run, and each time its dependencies change there after.

@Store()
@Component()
export class UICounter {
   @Input() count = 0

   increment() {
      this.count++
   }

   @Invoke() logCount() {
      console.log(this.count)
   }
}

See it in action on StackBlitz

Here we see logCount is a reactive function that logs the current value of count whenever it changes. If you're familiar with Vue's reactivity system it's kind of like watchEffect. But there are some big differences:

No compiler tricks
No new reactive primitives (like ref)
Shallow proxies by default

This works because we are able to replace this with an ES6 Proxy object that marks property access on this as a dependency. When Angular's change detection cycle runs it checks the dependencies and invokes the action each time they change. It doesn't work on arrow functions.

More importantly, Invoke is just an alias for Action. We can observe its calls through the event stream.

Selectors

Think computed properties. Angular State Library has two types of selectors:

Field selectors

@Store()
@Component()
export class UICounter {
   @Input() count = 0

   @Select() get double() {
      return this.count * 2
   }
}

Field selectors wrap the this object in a shallow proxy that tracks dependencies, and only recalculates the value when those dependencies change. It's also lazy; nothing happens until we read the value.

Parameterized selectors

@Store()
@Component()
export class UICounter {
   @Input() todos = []

   @Select() getTodosWith(text) {
      return this.todos.filter(todo => todo.title.match(text))
   }
}

Parameterized selectors are the same as field selectors except the function arguments are also memoized. By default all arguments are memoized without limit, and reset when the object dependencies change. For example, if I query getTodosWith with the values "Bob", "Jane" and "George", all three queries would be memoized until the todos array changes, which clears the cache.

Side Effects

In Angular State Library, side effects are just plain RxJS observables. Effects are dispatched by actions, and each action can dispatch just one effect.

@Store()
@Component()
export class UICounter {
   count = 0

   @Action() increment() {
      this.count++

      return dispatch(timer(2000), () =>
         this.count *= 2
      })
   }
}

`dispatch`

First let's look at dispatch. It is used to dispatch effects and can only be used inside an action stack frame (ie. a method decorated with Action or one of its derivatives).

The dispatcher accepts two arguments: an observable source and an (optional) observer that receives its events. The dispatcher returns an observable that mirrors the original observable for further chaining.

When an action returns an observable the subscription doesn't happen immediately. The store waits until all actions have executed before it subscribes to effects.

`useOperator`

By default, the previous effect is cancelled each time an action dispatches a new effect. This is consistent with other reactivity systems. But RxJS lets us do more.

useOperator is used to configure the switching behaviour of effects. For example, if we want to merge effects instead of switching them:

@Store()
@Component()
export class UICounter {
   count = 0

   @Action() increment() {
      this.count++

      useOperator(mergeAll())

      return dispatch(timer(2000), () => {
         this.count *= 2
      })
   }
}

See it in action on StackBlitz

Try clicking the button many times and watch what happens. Now swap mergeAll() with switchAll() and click a few more times. See the difference? RxJS gives us amazing temporal powers.

Note: The flattening operator passed to useOperator cannot be changed once it has been set. It is locked in the first time it is called.

useOperator can also be composed with effects.

function updateTodo(todo: Todo): Observable<Todo> {
   useOperator(mergeAll())
   return inject(HttpClient).put<Todo>(
      `https://jsonplaceholder.typicode.com/todos/${todo.id}`,
      todo
   );
}

function toggleAll(todos: Todo[]): Observable<Todo[]> {
   useOperator(exhaustAll())
   return forkJoin(
      todos.map(todo => updateTodo({ 
         ...todo, 
         completed: !todo.completed
      }))
   );
}

Sagas

For most cases the one-to-one relationship between actions and effects should suffice, especially for basic I/O operations like fetch. But when that's not enough, we can observe the full stream of events to create sagas.

@Store()
@Component()
export class UICounter {
   count = 0

   @Action() increment() {
      this.count++
   }

   @Action() double() {
      this.count *= 2
   }

   @Invoke() doubleAfterIncrement() {
      const effect = fromStore(UICounter).pipe(
         filter(event => event.name === "increment"),
         filter(event => event.type === "dispatch"),
         delay(2000)
      )

      return dispatch(effect, {
         next: this.double
      })
   }
}

The fromStore helper can be used to observe all events, including effects, with full type inference.

Putting it all Together

For a full example showcasing most of the features in Angular State Library (and some bonus features like lazy loading and transitions) view the example app on StackBlitz.

Help wanted

This project is just a proof of concept. It's no where near production ready. If you are interested in contributing or dogfooding feel free to open a line on Github discussions, or leave a comment with your thoughts below.

Thanks for reading!

Deleting Redux

Michael Muscat — Sat, 27 Aug 2022 11:44:27 +0000

A comedy of errors.
Redux is a state management pattern that dates back decades, well before it was popularised in the web era. Like all popular things it has many attractors and detractors. Almost every place I've worked at has used it on at least one project. Whether you like it or not redux is a mainstay of the web as we know it today. If you've used redux before, you'll know it comes with an ungodly amount of boilerplate, indirection, and confusion. Try not to peel your eyes away as you look at this *simple* example, something you might find in a tutorial. ```tsx const Increment = createAction("Increment", props<{ by: number }>()) const Double = createAction("Double") class UICounterEffects { double = createEffect((actions) => { return actions.pipe( ofType(Increment), map(action => new Double()), delay(2000), ) }) } function countReducer(state, action) { switch(action.type) { case Increment.type: { return state += action.by } case Double.type: { return state *= 2 } } } const countSelector = createSelector(state => state.count) const initialState = { count: 0 } const REDUCERS = { count: countReducer } const Store = createStore(REDUCERS, { initialState, effects: [UICounterEffects] }) @Component({ providers: [Store], template: {{ count | async }} Increment }) export class UICounter { private store = inject(Store) count = this.store.select(countSelector) increment(by) { this.store.dispatch(new Increment({ by })) } } ``` Holy over-engineering Batman! So much code for so little action. Let's see what it looks like *without* redux. ```tsx @Component({ template: {{ count }} Increment }) export class UICounter { // we initialize some state count = 0 // we dispatch an action increment(by) { // we update the state this.count += by // we run some effects setTimeout(() => { // we update the state again this.count *= 2 }, 2000) } } ``` The first example is **1136 bytes** of code across **56 lines**. The second example does exactly the same thing in only **301 bytes** across **18 lines**! It is also easier to read and understand by an order of magnitude. Clearly something is wrong with people who use redux.

What about the "Dev tools", "time travel" and "immutable state"? I say these are highly overrated and redundant. Do the next guy a favour, shift+delete redux from your application.

State should be sliced according to function (eg. authentication state, user state, form state). Components should not rely on contextual (read: global) state unless that state really needs to be shared across your application. In short, just use services.

Even if you can't delete redux from your application, that's fine. Just stop using it for everything.

@Component({
   template:
      <div>{{ count }}</div>
      <button (click)="increment(1)">
         Increment
      </button>
})
export class UICounter {
   // we initialize some state
   count = 0
   // we dispatch an action
   @Action() increment(by) {
      // we update the state
      this.count += by
      // we run some effects
      return dispatch(timer(2000), () => {
         // we update the state again
         this.count *= 2
      })
   }
}

An acceptable amount of boilerplate

HostListener + Output = 🤔

Michael Muscat — Wed, 27 Jul 2022 22:01:00 +0000

A HostListener lets us listen to events.

An Output emits observable events.

Can they be used together? Yes they can! (open in Stackblitz)



@Component({
   selector: "my-counter",
   template: `
      Counter: {{ count }}
   `,
   changeDetection: ChangeDetectionStrategy.OnPush,
})
export class Counter {
   @Input() count = 0

   @Output() 
   readonly increment = interval(1000)

   @HostListener("increment", ["$event"])
   handleIncrement(increment) {
      this.count += increment
  }
}

Intended behaviour? Perhaps not!

It was a little surprising to learn that Angular components and directives can listen to custom events published by the Output decorator. This gives us a convenient way to subscribe to an observable without cleaning up afterwards; the subscription is automatically disposed when the component is destroyed. We do however pollute the output namespace in the process 🙆‍♂️

No need for share either since outputs are automatically multicast to parent template subscribers. It even works with OnPush. What else can we do?

Example With HTTP Request

Let's fetch some todos.



const handleError = ctx => source => source.pipe(
   catchError((error, source) =>
      ctx.handleError(error) ? source : EMPTY
   )
)

@Component({
   template: `
      I have {{ todos.length }} todos left to do
   `
})
export class Counter {
   protected todos = []

   @Output() 
   readonly response = inject(HttpClient)
      .get("https://jsonplaceholder.typicode.com/todos")
      .pipe(handleError(this))

   @HostListener("response", ["$event"])
   handleResponse(todos) {
      this.todos = todos
   }

   handleError(error: unknown) {
      console.error(error)
      return true
   }
}

Since Angular outputs are readonly new values cannot be assigned like AsyncPipe. Instead we need to handle errors to prevent the subscription from collapsing.

Other Things You Can't Do

The listen event in Renderer2 sadly doesn't share this behaviour.
Subscribing to the same event twice with HostListener is not possible, only the last subscription will be used.
This won't work in AppComponent since there's no parent view for Output to subscribe to.

Summary

This is just a neat little trick saves you some subscription management without any third party libs. I hope you find it useful.

Happy coding!

Experimental class composition with Angular 14

Michael Muscat — Wed, 06 Jul 2022 12:24:47 +0000

Do you sometimes wish that Angular had functional composition like other frameworks?

Well too bad, Angular is wedded to classes. And despite many attempts to fit square peg functions into round hole classes it just doesn't work well in practice. Angular does what it does for a reason and we shouldn't try to make it something it's not.

But what if you want it anyway and stumble across a way to make it happen with just one line of code?

<p>Count: {{ counter.value }}</p>

@Auto()
@Component()
class MyComponent {
  // nothing unusual?
  counter = new Counter()

  ngOnInit() {
    console.log("so far so good")
  }
}

@Auto()
class Counter {
  value = 0
  interval

  increment(ctx) {
    ctx.value++
  }

  ngOnInit() {
    console.log("wait what?")
    this.interval = setInterval(this.increment, 1000, this)
  }

  ngOnDestroy() {
    console.log("this shouldn't be possible")
    clearInterval(this.interval)
  }
}

One of they key features of functional composition is the ability to extract and co-locate lifecycle hooks into a single unit of logic that can be reused across many components. In Angular this unit of logic is normally represented by services decorated with Injectable.

Services however, have some downsides compared to functional composition:

Inability to pass parameters to a service from a component when it is created
Leaky services. Some code further down the tree could inject and use it in unintended ways.
Extra ceremony of having to add to providers array.
Unless provided in a component, inability to update the view
Accidentally injecting a parent instance because it wasn't provided correctly, or omitting @Self.
No access to the lifecycle of a directive.

Angular only supports lifecycle hooks on decorated classes, but in the example above we have an arbitrary Counter object with lifecycle hooks. How does that work? Why now?

Angular 14

In my recent article Angular 14 dependency injection unlocked I explain how inject became a public API for all Angular decorated classes including components. This liberates us from constructors as the only means to instantiate our dependencies, making the following possible without any hacks at all:

@Component()
class MyComponent {
  resource = new Resource()
}

class Resource() {
  http = inject(HttpClient) // now works in Angular 14!
}

The ability to inject dependencies is another key piece of the composition puzzle. We just need some way to hook into the component lifecycle.

Automatic Composition

antischematic / angular-auto

Auto decorators for Angular

@Auto()
@Component({
   template: `{{ count }}`,
   changeDetection: ChangeDetectionStrategy.OnPush,
})
export class MyComponent {
   @Input()
   count = 0;

   object = new Resource()

   @Subscribe()
   autoIncrement = interval(1000).pipe(
      tap((value) => this.count = value + 1)
   );

   @Unsubscribe()
   subscription = new Subscription();

   ngOnInit() {
      console.log("I am called!")
   }
}

@Auto()
export class Resource {
   private http = inject(HttpClient)
   @Check()
   value

   ngOnInit() {
      console.log("I am also called!")
   }

   fetch(params) {
      this.http.get(endpoint, params)
         .subscribe(

…

View on GitHub

With one line of code, just add Auto to your component, directive, service, etc. and it instantly composes with other Auto decorated objects.

Behind the scenes this decorator will cascade lifecycle hooks to any Auto object created inside a class field initializer or constructor. These are guarded so that component life cycles don't leak to services and vice versa.

Try it out!

But There's a Catch

For now this is only possible by mutating some private Angular APIs. So it's definitely not something you should try in production 🙇

Angular Friendly?

If you flinch when seeing useXXX in other frameworks, rest assured that I am not advocating for this to become a thing in Angular.

In Angular we use new XXX.

Happy Coding!

Angular 14 dependency injection unlocked

Michael Muscat — Mon, 13 Jun 2022 09:21:45 +0000

Quietly released with Angular 14 is a fix for this handy little inject utility that allows us to create and retrieve dependencies from the injector tree without relying on parameterized class constructors (read docs)

A small change with big ramifications?

Until now it's only been possible to use it in places such as an InjectionToken or Injectable constructor context. Angular 14 now allows inject to be used in Directive and Component constructor contexts as well.

This makes it a little nicer when injecting non class-based tokens.

const API = new InjectionToken<Api>("API")

// Angular <=13
@Directive()
export class MyDirective {
  constructor(@Inject(API) private api: Api) {}
}

// Angular <=13
@Component()
export class MyDirective {
  constructor(@Inject(API) private api: Api) {}
}

// Angular 14+
@Directive()
export class MyDirective {
  private api = inject(API) // type inferred
}

// Angular 14+
@Component()
export class MyDirective {
  private api = inject(API) // type inferred
}

Higher Order Services

Another change in Angular 14 loosens the rules around abstract class constructors so we can safely use them without running afoul of the Angular compiler with strictInjectionParameters.

Thanks to this change it's now much easier to compose higher order services using mixins. For example, we can replace the ResourceManager in this example with service composition.

// generate higher order service, mixing plain value
// parameters with dependency injection
export function createResource<T extends Fetchable>(
  fetchable: Type<T>
): Type<Resource<T>> {
  @Injectable()
  class ResourceImpl extends Resource<T> {
    constructor() {
      super(inject(fetchable));
    }
  }
  return ResourceImpl;
}

@Injectable()
export abstract class Resource<T extends Fetchable> {
  // this value is injected
  private changeDetectorRef = inject(ChangeDetectorRef);
  private subscription = Subscription.EMPTY

  ...

  // Angular behaviors require the `Injectable` decorator
  ngOnDestroy() {
    this.subscription.unsubscribe()
  }

  // this value is passed in through `super()`
  constructor(private fetchable: Fetchable) {}
}

This example shows how we can now easily mix dependency injection with explicit parameter constructors while preserving Angular behaviors like ngOnDestroy.

Let's see it in action.

const endpoint = 'https://jsonplaceholder.typicode.com/todos'

@Injectable({ providedIn: 'root' })
export class FetchTodosByUserId implements Fetchable<Todo[]> {
  private http = inject(HttpClient);

  fetch(userId: string) {
    return this.http.get<Todo[]>(endpoint, {
      params: {
        userId,
      },
    });
  }
}

<!-- todos.component.html -->
<div *ngFor="let todo of todos.value">
  <div>id: {{ todo.id }}</div>
  <div>title: {{ todo.title }}</div>
  <input disabled type="checkbox" [checked]="todo.completed" />
</div>

const TodosByUserId = createResource(FetchTodosByUserId);

@Component({
  selector: 'app-todos',
  templateUrl: './todos.component.html',
  providers: [TodosByUserId],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class TodosComponent {
  protected todos = inject(TodosByUserId);

  @Input()
  userId: string;

  ngOnChanges() {
    this.todos.fetch(this.userId);
  }
}

A working example can be seen here 👉 view on Stackblitz

A small step forward

Angular 14 has many long needed and welcomed improvements to the core developer experience. Be sure to check the change log so you don't miss anything.

Happy Coding!

Angular Transition Zone

Michael Muscat — Wed, 04 May 2022 12:28:45 +0000

Have you heard of zone.js? It's the secret sauce behind Angular's change detection mechanism. Whenever something async happens, Angular knows because zone.js knows. You are probably already using fakeAsync in your unit tests to suspend async tasks entirely!

The power to intercept, manipulate and schedule tasks in the JavaScript VM. That's zone.js in a nutshell. But what does that have to do with transitions?

A Tricky Problem

Let's say I have a button and I want to do some work when it is clicked. I also want to show a spinner while the work is happening until it is done.

<!-- ./button.html -->
<ng-content></ng-content>
<spinner *ngIf="pending"></spinner>

@Component({
   selector: "button",
   templateUrl: "./button.html"
})
export class ButtonComponent {
   pending: boolean
}

<!-- usage -->
<button (click)="doAsync()">Click me!</button>

How do I know when to show and stop the spinner? Perhaps I could pass it in as an @Input().

<!-- just add an input? -->
<button (click)="doAsync()" [pending]="pending">
   Click me!
</button>

But now there's an extra piece of state to manage. What if the button click ends up triggering some REST APIs followed by some navigation event that loads a bunch of async resolvers? It would be too cumbersome to keep track of it all.

That's where zone.js comes in. Instead of manually tracking every bit of async activity, we'll let zone.js tell us when all of the work is done instead.

We'll call this process a transition.

Zone.js Primer

By default every Angular application runs in the Angular zone. This zone is responsible for triggering change detection which updates the view. Without this we would need to manually tell Angular when to run change detection after every async task.

Zone.js works by monky-patching JavaScript globals such as setTimeout, Promise and addEventListener. The following example was taken from Zone Primer on Google Docs

// How Zone.js Works

// Save the original reference to setTimeout
let originalSetTimeout = window.setTimeout;
// Overwrite the API with a function which wraps callback in zone.
window.setTimeout = function(callback, delay) {
   // Invoke the original API but wrap the callback in zone.
   return originalSetTimeout(
      // Wrap the callback method
      Zone.current.wrap(callback), 
      delay
   );
}

// Return a wrapped version of the callback which restores zone.
Zone.prototype.wrap = function(callback) {
   // Capture the current zone
   let capturedZone = this;
   // Return a closure which executes the original closure in zone.
   return function() {
      // Invoke the original callback in the captured zone.
      return capturedZone.runGuarded(callback, this, arguments);
   };
};

The nice thing about Zone.js is that it's very easy to create a new Zone by forking an existing one. We will implement transitions by forking the Angular zone.

Transition API

Before we look at the implementation, let's reconsider the button example. What should a transition look like?

<!-- ./button.html -->
<ng-content></ng-content>
<spinner *ngIf="pending"></spinner>

@Component({
   selector: "button",
   templateUrl: "./button.html"
})
export class ButtonComponent {
   get pending() {
      return isPending()
   }

   @HostListener("click")
   handleClick() {
      startTransition()
   }
}

<!-- usage -->
<button (click)="doAsync()">Click me!</button>

This pseudo-code serves to illustrate two important features of the transition we wish to implement:

We can trigger the start of a transition
We can observe the status of a transition

The spinner knows nothing about what work will be performed. Zone.js will tell us the work is done when isPending() returns false.

Let's refine this into something a little more concrete.

// transition interface

interface Transition {
   start(token: TransitionToken): void
   has(token: TransitionToken): boolean
   invoke(task: Function): any
}

interface TransitionToken {
   name: string
}

start is the signal to begin a new transition. If a transition is already running, the previous transition is discarded. We'll associate each transition with a TransitionToken. For the next tick, all work that runs in the transition zone will be associated with this token.

has checks if a transition associated with TransitionToken is currently active, returning true if it is.

invoke immediately runs the callback it receives inside the transition zone. That way we only capture work that should be considered part of the transition.

Let's look at the button example again.

<!-- ./button.html -->
<ng-content></ng-content>
<spinner *ngIf="pending"></spinner>

const Click = new TransitionToken("Click")

@Component({
   selector: "button",
   templateUrl: "./button.html",
   providers: [Transition]
})
export class ButtonComponent {
   get pending() {
      return this.transition.has(Click)
   }

   @HostListener("click")
   handleClick() {
      this.transition.start(Click)
   }

   constructor(private transition: Transition) {}
}

This time we have a concrete service to wire transitions to the component.

<!-- async.html -->
<button (click)="doAsync()">Click me!</button>

import { timer } from "rxjs"

@Component({
   templateUrl: "./async.html",
   providers: [Transition]
})
class AsyncComponent {
   doAsync() {
      this.transition.invoke(() => {
         // sleep for 2 seconds
         timer(2000).subscribe()
      })
   }

   constructor(private transition: Transition) {}
}

The actual async work will be simulated with a 2 second timer that runs in the transition zone. From this example we should expect the spinner to spin for exactly 2 seconds once the button is clicked.

Transition Zone Implementation

For the basic implementation refer to this gist.

To implement transitions we need to fork an existing zone.

Zone.current.fork(spec) // <-- creates a new child zone

To do this we write a ZoneSpec.

class TransitionZoneSpec implements ZoneSpec {
   properties = {
      count: 0
   }

   onScheduleTask(delegate: ZoneDelegate, current: Zone, target: Zone, task: Task): Task {
      this.properties.count++
      return delegate.scheduleTask(target, task)
   }

   onInvokeTask(delegate: ZoneDelegate, current: Zone, target: Zone, task: Task, applyThis: any, applyArgs: any[] | undefined) {
      this.properties.count--
      return delegate.invokeTask(target, task, applyThis, applyArgs)
   }

   onHasTask() {
      // no more macrotasks or microtasks left in the queue
      if (this.properties.count === 0) {
         done() 
      }
   }
}

This is where zone.js allows us to jump in and take control of the JavaScript VM. Not quite there will be dragons, but just enough for us to be dangerous.

onScheduleTask let's us intercept the beginning of some async work that has not yet been scheduled. When you call something like setTimeout, zone.js will intercept that call and let us choose whether to schedule (or discard) it. For transitions we are only interested in counting the number of tasks that are scheduled.

onInvokeTask let's us intercept when the callback of some async work is about to be called. For example, when setTimeout(fn, 1000) is scheduled, the call to fn is the task that is intercepted. Again we get to choose whether or not to invoke the task. For transitions we are only interested in counting the number of tasks that are invoked.

onHasTask let's us know when work has been scheduled or completed. We can use this to inspect the state of our transition zone. When the task count returns to zero, the transition is "done".

Testing

We can test that our transition is working by writing a simple test (see reference implementation). We also want to verify that transitions survive async boundaries. This test uses nested setTimeout calls to simulate sequential async calls, such as a template rendering after fetching some data.

it("should have transition while async tasks are pending", fakeAsync(() => {
      const token = new TransitionToken("Test")
      const transition = startTransition(token)
      const ngZone = TestBed.inject(NgZone)

      transition.invoke(() => {
         setTimeout(() => {
            ngZone.run(() => {
               transition.invoke(() => {
                  setTimeout(() => {
                     // nested
                  }, 500)
               })
            })
         }, 1000)
      })

      // 0ms
      expect(transition.has(token)).toBeTrue()

      tick(500)

      // 500ms
      expect(transition.has(token)).toBeTrue()

      tick(500)

      // 1000ms start nested timeout
      expect(transition.has(token)).toBeTrue()

      tick(250)

      // 1250ms
      expect(transition.has(token)).toBeTrue()

      tick(250)

      // 1500ms
      expect(transition.has(token)).toBeFalse()
   }))

Summary

This concept was inspired by concurrent mode in React 18. I really wanted to see if it was possible to do something similar with Angular. I'm pleased to report that it is definitely possible, and with a surprisingly small amount of code. If React concurrent mode works by forking JSX rendering, then the Angular equivalent is to fork zones. The main difference is that React transitions are hidden from the user by running in memory. For Angular this is not possible. But this is less of a problem if you render as you fetch.

There's more work to be done for sure. Perhaps a suspense-like API? ng-cloak anyone? 😉

Happy Coding!

Render as you fetch with Angular lifecycle hooks

Michael Muscat — Mon, 25 Apr 2022 10:59:17 +0000

What if you could load asynchronous data right inside your component without the need for async pipes, subscribe, or even RxJS? Let's jump right in.

Fetching Data

To start with, we need some data to display in our app. We'll define a service that fetches some todos for us via HTTP.

const endpoint = "https://jsonplaceholder.typicode.com/todos"

@Injectable({ providedIn: "root" })
class TodosResource implements Fetchable<Todo[]> {
   fetch(userId: number) {
      return this.http.get(endpoint, {
         params: { userId }
      })
   }

   constructor(private http: HttpClient) {}
}

The fetch function itself doesn't have to return an observable. It could just as easily return any observable input, such as a promise. We'll make all resources adhere to this Fetchable interface.

For now this is just a normal Angular service. We'll come back to it later.

The Resource Interface

At its core, a resource can do two things:

interface Resource<T extends Fetchable<any>> {
   fetch(...params: FetchParams<T>): any
   read(): FetchType<T> | undefined
}

fetch Tell the resource to fetch some data. This could come from a HTTP or GraphQL endpoint, a websocket or any another async source.

read Attempt to read the current value of the resource, which might be undefined because no value has arrived yet.

With this interface defined we can write a class that implements it.

Implementation

The example below is truncated for the sake of brevity. A more concrete example can be found here

import { EMPTY, from, Subscription } from "rxjs"

export class ResourceImpl<T extends Fetchable> 
   implements Resource<T> {

   value?: FetchType<T>
   params: any
   subscription: Subscription
   state: string

   next(value: FetchType<T>) {
      this.value = value
      this.state = "active"
      this.changeDetectorRef.markForCheck()
   }

   read(): FetchType<T> | undefined {
      if (this.state === "initial") {
         this.connect()
      }
      return this.value
   }

   fetch(...params: FetchParams<T>) {
      this.params = params
      if (this.state !== "initial") {
         this.connect()
      }
   }

   connect() {
      const source = this.fetchable.fetch(...this.params)
      this.state = "pending"
      this.unsubscribe()
      this.subscription = from(source).subscribe(this)
   }

   unsubscribe() {
      this.subscription.unsubscribe()
   }

   constructor(
      private fetchable: T,
      private changeDetectorRef: ChangeDetectorRef
   ) {
      this.source = EMPTY
      this.subscription = Subscription.EMPTY
      this.state = "initial"
   }
}

The resource delegates the actual data fetching logic to the fetchable object which is injected in the constructor. The resource will always return the latest value when it is read.

You'll also notice that we don't immediately fetch data if we are in an initial state. For the first fetch we wait until read is called. This is necessary to prevent unnecessary fetches when a component is first mounted.

Let's also write another service to help us manage our resources.

import { 
   Injectable, 
   InjectFlags, 
   Injector, 
   ChangeDetectorRef
} from "@angular/core"

@Injectable()
export class ResourceManager {
   private cache: Map<any, ResourceImpl<Fetchable>>

   get<T extends Fetchable>(token: Type<T>): Resource<T> {
      if (this.cache.has(token)) {
         return this.cache.get(token)!
      }
      const fetchable = this.injector.get(token)
      const changeDetectorRef = this.injector
         .get(ChangeDetectorRef, undefined, InjectFlags.Self)
      const resource = new ResourceImpl(
         fetchable, 
         changeDetectorRef
      )
      this.cache.set(token, resource)
      return resource
   }

   ngOnDestroy() {
      for (const resource of this.cache.values()) {
         resource.unsubscribe()
      }
   }

   constructor(private injector: Injector) {
      this.cache = new Map()
   }
}

Usage

Now that we have built our resource services, let's see it in action!

<!-- todos.component.html -->

<div *ngFor="let todo of todos">
  <input type="checkbox" [value]="todo.complete" readonly />
  <span>{{ todo.title }}</span>
</div>

<button (click)="loadNextUser()">
  Next user
</button>

import {
   Component,
   OnChanges,
   DoCheck,
   Input,
   ChangeDetectionStrategy
} from "@angular/core"

import { 
   Resource,
   ResourceManager
} from "./resource-manager.service"

import { Todos, TodosResource } from "./todos.resource"

@Component({
   selector: "todos",
   templateUrl: "./todos.component.html",
   providers: [ResourceManager],
   changeDetection: ChangeDetectionStrategy.OnPush
})
export class TodosComponent implements OnChanges, DoCheck {
   @Input()
   userId: number

   resource: Resource<TodosResource>

   todos?: Todos[]

   ngOnChanges() {
      this.loadNextUser(this.userId)
   }

   ngDoCheck() {
      this.todos = this.resource.read()
   }

   loadNextUser(userId = this.userId++) {
      this.resource.fetch(userId)
   }

   constructor(manager: ResourceManager) {
      this.userId = 1
      this.resource = manager.get(TodosResource)
      this.resource.fetch(this.userId)
   }
}

Finally, we can see that fetch is called twice; once in the constructor and again during the ngOnChanges lifecycle hook. That's why we need to wait for a read before subscribing to the data source for the first time.

All the magic happens in ngDoCheck. It's normally a bad idea to use this hook, but it's perfect for rendering as you fetch! The read function simply returns the current value of the resource and assigns it to todos. If the resource hasn't changed since the last read, it's a no-op.

If you're wondering why this works, scroll back to the next function in ResourceImpl.

next() {
   // ...
   this.changeDetectorRef.markForCheck()
}

This marks the view dirty every time the resource receives a new value, and eventually triggers ngDoCheck. If a resource happens to be producing synchronous values very quickly we also avoid additional change detection calls. Neat!

Summary

We can render as we fetch by taking advantage of Angular's change detection mechanism. This makes it easy to load multiple data streams in parallel without blocking the view, and with a little more effort we can also show a nice fallback to the user while the data is loading. The approach is data agnostic and should complement your existing code.

Happy coding!

RFC: Why Angular needs a composition API

Michael Muscat — Sun, 05 Sep 2021 14:06:32 +0000

Angular is an opinionated framework, but leaves open the question of how state should be managed in our application. Out of the box we are presented with a mix of imperative and reactive styles for state management, which is a barrier to entry for purely reactive state.

A composition API solves this by filling in the gaps in Angular's reactive model, providing a consistent pattern for reactive state management.

State

Fig 1a. Imperative style

@Component()
export class MyComponent {
   @Input() 
   count = 0

   handleCountChange() {
      // do something with count
   }

   ngOnChanges(changes) {
      if (changes.count) {
         this.handleCountChange()
      }
   }
}

Fig 1b. Reactive composition

function setup() {
   const count = use(0)

   subscribe(count, () => {
      // do something with count
   })

   return {
      count
   }
}

@Component({
   inputs: ["count"]
})
export class MyComponent extends ViewDef(setup)

These two examples might look similar, but the latter example has a few advantages already:

We can observe changes to the value of count, even it's an input or not.
We can extract the logic and side effect into another function, which is not straightforward with the first example.

Fig 1c. Extraction

function useCount(value) {
   const count = use(value)

   subscribe(count, () => {
      // do something with count
   })

   return count
}

function setup() {
   const count = useCount(0)
}

@Component({
   inputs: ["count"]
})
export class MyComponent extends ViewDef(setup)

Subscriptions

Subscriptions are another pain point that Angular leaves us to figure out for ourselves. Current approaches in the ecosystem include:

Declarative

Out of the box Angular gives us a pipe that automatically handles subscriptions to observable template bindings.

Fig 2. Async pipe binding

<div *ngIf="observable$ | async as value"></div>

The benefits of this approach is that we do not have to worry about the timing of the subscription, since it will always happen when the view is mounted, and the view will be updated automatically when values change.

However in real world applications it is easy to accidentally over-subscribe to a value because you forgot to share() it first. Templates with many temporal async bindings are much harder to reason about than static templates with synchronous state.

Imperative

Another popular approach is to subscribe to observables in our component class, using a sink to simplify subscription disposal.

Fig 3. Subscription sink with imperative subscribe

@Component()
export class MyComponent {
   count = 0
   sink = new Subscription

   ngOnDestroy() {
      this.sink.unsubscribe()
   }

   constructor(store: Store, changeDetectorRef: ChangeDetectorRef) {
      this.sink.add(
         store.subscribe(state => {
            this.count = state.count
            changeDetectorRef.detectChanges()
         })
      )
   }
}

Sinks are a good way to deal with imperative subscriptions, but results in more verbose code. Other approaches use takeUntil, but that has its own pitfalls. The only guaranteed way to dispose of a subscription is to call its unsubscribe method.

The downside to this approach is we have to manually handle change detection if using the OnPush change detection strategy. The timing of the subscription here also matters, causing more confusion.

Let's see how composition solves these problems.

Fig 4. Composable subscriptions with reactive state

function setup() {
   const store = inject(Store)
   const count = use(0)

   subscribe(store, (state) => count(state.count))

   return {
      count
   }
}

@Component()
export class MyComponent extends ViewDef(setup) {}

<div *ngIf="count > 0"></div>

The composition API runs in an Execution Context with the following behaviour:

Subscriptions are deferred until the view has mounted, after all inputs and queries have been populated.
Change detection runs automatically whenever a value is emitted, after calling the observer. State changes are batched to prevent unnecessary re-renders.
Subscriptions are automatically cleaned up when the view is destroyed.
Reactive values are unwrapped in the component template for easy, synchronous access.

Lifecycle

The imperative style of Angular's lifecycle hooks work against us when we want truly reactive, composable components.

Fig 5. A riddle, wrapped in a mystery, inside an enigma

@Component()
export class MyComponent {
   ngOnChanges() {}
   ngOnInit() {}
   ngDoCheck() {}
   ngAfterContentInit() {}
   ngAfterContentChecked() {}
   ngAfterViewInit() {}
   ngAfterViewChecked() {}
   ngOnDestroy() {}
}

The composition API provides a Layer of Abstraction so we don't have to think about it.

Fig 6. Composition API lifecycle

function setup() {
   const count = use(0) // checked on ngDoCheck
   const content = use(ContentChild) // checked on ngAfterContentChecked
   const view = use(ViewChild) // checked on ngAfterViewChecked

   subscribe(() => {
      // ngAfterViewInit
      return () => {
         // ngOnDestroy
      }
   })

   return {
      count,
      content,
      view
   }
}

@Component()
export class MyComponent extends ViewDef(setup) {}

Fine tune control is also possible using a custom scheduler.

Fig 7. Before/After DOM update hooks

function setup(context: SchedulerLike) {
   const count = use(0)
   const beforeUpdate = count.pipe(
      auditTime(0, context) // pass 1 for afterUpdate
   )
   subscribe(beforeUpdate, () => {
      // after count changes, before DOM updates.
   })
}

@Component()
export class MyComponent extends ViewDef(setup) {}

Change Detection

Angular's default change detection strategy is amazing for beginners in that it "just works", but not long after it becomes necessary to optimise performance by using the OnPush strategy. However in this change detection mode you must manually trigger change detection after an async operation by calling detectChanges somewhere in your code, or implicitly with the async pipe.

By comparison, the composition API schedules change detection automatically:

Whenever a reactive input changes
Whenever a reactive value returned from a ViewDef emits
Whenever a subscribed observable emits
With or without zone.js

Fig 8. Composition API change detection

function setup(context: Context) {
   const count = use(0)

   subscribe(interval(1000), () => {
      // reactive change detection
   })

   return {
      count // reactive change detection
   }
}

@Component({
   inputs: ["count"] // bound to reactive input
})
export class MyComponent extends ViewDef(setup) {}

Changes to reactive state are batched so that the view is only checked once when multiple values are updated in the same "tick".

Angular Composition API

This RFC includes a reference implementation. Install it with one of the commands below. Currently requires Angular 12.x with RxJS 6.x.

npm i @mmuscat/angular-composition-api

yarn add @mmuscat/angular-composition-api

Built for Ivy

Angular Composition API wouldn't be possible without the underlying changes brought by the Ivy rendering engine.

Built for RxJS

Other libraries achieve reactivity by introducing their own reactive primitives. Angular Composition API builds on top of the existing RxJS library. The result is a small api surface area and bundle size. You already know how to use it.

Built for the future

There is currently talk of adding a view composition API to a future version of Angular. It is hoped that this library can provide inspiration for that discussion and potentially integrate with any new features that might bring.

Request for Comment

If you are interested in improving this proposal, leave a comment in this Github issue. Alternatively, you can try out the reference implementation from the links below.

Angular Composition API on Stackblitz

Angular Composition API on Github

Angular Composition API on NPM

Prior Arts

React Hooks

Vue Composition API

Angular Effects

DEV Community: Michael Muscat

Rules for Decorators: Why meta-programming in Angular sucks, and what you can do about it

Ahead-of-Time vs Just-in-Time compilation

Ahead-of-Time

Just-in-Time

Unit Tests

Why Meta-Programming In Angular Sucks

No Officially Supported Meta-Programming API

Object Identity

Order of Execution

Rules for Decorators

1. Never extend the base class

2. Never replace a decorated class property with an incompatible type signature

3. Don't inherit decorators from base classes

4. Don't extend the public API of a class.

5. Don't use decorators for everything

How to decorate an Angular component

Working Example

Turn a Directive Into a Fragment

Is This a Good Idea?

Directives as a Service

Template Providers

Host Directives

When to Use a Directive Instead of a Service

Help Wanted

Reactivity In Actions

Pushing Problems

Manual Change Detection

Async Pipes

Manual Subscribe

Square Peg, Round Hole

Observable Core, @Directive Shell

Help Wanted

Angular State Library

Introduction

Redux: The Good Parts

Angular State Library

Declarative State

Selectors

Side Effects

dispatch

useOperator

Sagas

Putting it all Together

Help wanted

Deleting Redux

HostListener + Output = 🤔

Example With HTTP Request

Other Things You Can't Do

Summary

Experimental class composition with Angular 14

Angular 14

Automatic Composition

antischematic / angular-auto

Auto decorators for Angular

Auto decorators for Angular

Angular Friendly?

Angular 14 dependency injection unlocked

A small change with big ramifications?

Higher Order Services

A small step forward

Angular Transition Zone

A Tricky Problem

Zone.js Primer

Transition API

Transition Zone Implementation

Testing

Summary

Render as you fetch with Angular lifecycle hooks

Fetching Data

The Resource Interface

Implementation

Usage

Summary

RFC: Why Angular needs a composition API

State

Subscriptions

Lifecycle

Change Detection

Angular Composition API

`Observable` Core, `@Directive` Shell

`dispatch`

`useOperator`