RFC: Angular Composition API

[antischematic]

RFC: Angular Composition API

This topic is an open discussion for the current and future development of Angular Composition API. If you have an issue please open a separate thread.

Why Angular needs a composition API

State

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.

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:

1. We can observe changes to the value of count, even it's an input or not.

2. We can extract the logic and side effect into another function, which is not possible 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:

1. Declaritive

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.

2. 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:

1. Subscriptions are deferred until the view has mounted, after all inputs and queries have been populated.

2. Change detection runs automatically whenever a value is emitted, after calling the observer. State changes are batched to prevent uneccessary re-renders.

3. Subscriptions are automatically cleaned up when the view is destroyed.

4. 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 the Context scheduler.

Fig 7. Before/After DOM update hooks

function setup(context: Context) {
   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

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".

How composition works

TBD

Execution context

TBD

Reactive blocks

TBD

Functional groups

TBD

Change detection

TBD

Angular Composition API

This RFC includes a reference implementation. Install it with one of the commands below.

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.

Prior Arts

React Hooks

Vue Composition API

Angular Effects

[DmitryEfimenko]

Let me start off by saying that I have much respect for the effort being put in here.

However, after working with React hooks for quite a some time, I came to really dislike the whole "useWhatever" hooks approach for state management.
I feel that using straight up RxJS gives much more flexibility. The subscribe method that I see in the proposed solution looks like just a glorified combineLatest. Maybe I don't understand something, but it looks like this leaves out the flexibility for data flow control of other operators available from RxJS.

Perhaps this is not the most objective feedback, but rather my initial feelings.

[antischematic]

@DmitryEfimenko Thank you for your feedback. To clarify, the proposed API is designed to work in tandem with RxJS specifically.

On the surface you can consider the following two snippets to be conceptually equivalent.

Plain RxJS

const value = new BehaviorSubject(0)
value.subscribe((current) => {
  console.log(current)
})

Composition API

const value = use(0) // uses BehaviorSubject under the hood, returns an interop observable. Interchangeable.
subscribe(value, (current) => {
  console.log(current)
})

The problems that subscribe attempts to solve are:

• Early subscribers
  Top level subscriptions are deferred until initial props and queries have been populated. We don't need to worry about subscribing too early.
• Change detection
  Imperative subscriptions have to manually manage change detection when in OnPush mode. Similar to the async pipe, subscribe will automatically schedule change detection while batching state changes.
• Automatic unsubscribe
  When the context is destroyed subscriptions are automatically cleaned up
• Error handling
  Make RxJS more approachable by simplifying error handling. Instead of retrying errors, subscribe will accept a materialized stream and map these notifications to the appropriate next, error or complete observer. Additionally, uncaught errors are piped to the ErrorHandler service, which is crucial for the implementation of Error Boundaries.
• Abort signals
  Fine grain control of subscription lifecycles without the drawbacks of takeUntil.
• Composable subscriptions
  Make RxJS more approachable by simplifying higher order streams. A subscription nested in another subscription will automatically unsubscribe when the parent subscription emits (similar to switchMap), or when the context is destroyed, or when an abort signal is received if configured.
• Teardown logic in observers
  Observers passed to subscribe can return TeardownLogic, which will be triggered the next time the observer is called, or when the context is destroyed, or when an abort signal is received if configured.
• Reactive observers
  A concept where reading a reactive value inside an observer will mark that value as a dependency. A reactive observer will be called each time one of its dependencies emits a new value. Basically a more ergonomic version of combineLatest.

There are some use cases where it might not be appropriate to use the subscribe API. You can still have full control by using plain RxJS.

const value = new BehaviourSubject(0)
const sink = subscribe()

sink.add(value.subscribe((current) => {
  console.log(current)
}))

To your last point about data flow control, subscribe makes no assumptions about the type of observable it is given. You can use pipeable operators however you like to achieve the desired result.

[chaosmonster]

I agree with @DmitryEfimenko

If I jump into the role of a PO my biggest question is what do you gain from this? The proposed code is just equivalent to Vue 3's composition API which doesn't provide any benefit for me as a developer in Angular or at least you didn't sell it to me? Is it more performant? Is it reducing the bundle size? Does it make testing simpler? Does it reduce complexity?

To extend on that vue 3 introduced the composition API to manage code reuse patterns, typescript support and readability or large components.

TypeScript is not an issue in Angular as it is a first class citizen.
Reuse Patterns exist in Angular with DI and the service concept. Next to that you can always use mixins (see Angular material).
Lastly if you follow the patterns suggested by Angular your readability is (subjectively) just fine as it is. Also keep in mind that Angular as it is class based and uses decorator does not have the limitation vue 2 had in regards to code organization within the class. We don't have to differentiate between data, methods and so on. One could change the linter rules and combine the properties and methods as they like (though at least in my opinion I wouldn't like to read that)

Lastly:

I really like to look beyond the tellerand and see what other libraries and frameworks do. But not everything needs to be copied, as it is often a result of a problem that occured. And one should always as themself do we have that problem or do we have a different approach to solve that problem already in place?

[antischematic]

@chaosmonster Good questions, I will try to answer briefly.

• What do you gain from this?
  Observable inputs, observable queries, automatic change detection with OnPush performance, simpler lifecycle model, composable subscriptions, automatic teardown, function composition, value providers, view scheduler, error handling, reactive observers and synchronous component templates.

• Is it more performant?
  The reference implementation detaches ChangeDetectorRef from the change-detection tree, so it should be more performant in theory. It also works without Zone.js, which aligns with future Zone.js opt-out on the Angular roadmap.

• Is it reducing the bundle size
  As a standalone library it will currently add 3kb (min, gzipped) to your bundle size. This is 9kb net gain if zone.js is removed.

• Does it make testing simpler?
  The proposal shouldn't have any impact on current Angular testing methodology.

• Does it reduce complexity?
  This proposal aims to reduce the conceptual complexity of lifecycles, providers, reactive state, change detection and async template bindings.

[antischematic]

I've added a Sierpinski triangle bench demo. Refer to this issue for perf comparisons.

View demo here
https://mmuscat.github.io/striangle-demo/

[antischematic]

Added a listen feature to the core library that lets you compose callbacks, host listeners and event listeners. Documentation here

import { Component } from "@angular/core"
import { listen, ViewDef } from "@mmuscat/angular-composition-api"

function setup() {
   listen<MouseEvent>("click", (event) => {
      console.log("clicked!", event)
   })

   listen("window:scroll", () => {
      console.log("scrolling!")
   })

   return {}
}

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

[antischematic]

I've added a composition equivalent to the @Attribute decorator, with optional type cast. This uses Renderer2 and ElementRef to read static attributes.

function setup() {
  const enabled = attribute("enabled", Boolean)
  const results = use()
  const loadApi = inject(API)
  
  subscribe(loadApi().pipe(
    filter(enabled)
  ), { next: results })
  
  return {
    results
  }
}

@Component({
  selector: "my-component"
})
export class MyComponent extends ViewDef(setup) {}

<my-component enabled></my-component>

[antischematic]

Adding a combine utility method that flattens Value objects into a single Value. Setting the value of a combined Value will update and trigger upstream Value objects, and vice-versa.

const count = use(0)
const disabled = use(false)

const state = combine({
  disabled,
  nested: {
    count
  },
  name: "Plain Jane"
})

state() // { disabled: true, nested: { count: 0 }, name: "Plain Jane" }
state({
  disabled: true,
  nested: {
    count: 10
  },
  name: "Still Plain Jane"
})

count() // 10
disabled() // true

count(20) // updates `state`
state().count // 20

[antischematic]

Two more convenience methods for working with Value objects.

get will return the flattened state of the requested object by calling the getter method, which will trigger reactive observers.

const count = use(0)
const disabled = use(false)

subscribe(() => {
  const state = get({ count, disabled }) // reactive
})

access returns flattened state through the value accessor, which doesn't trigger reactive observers.

const count = use(0)
const disabled = use(false)

subscribe(() => {
  const state = access({ count, disabled }) // not reactive
})

[lennerd]

I think the new additions are great. I can see how they make this composition API even more powerfull than similar APIs from other frameworks due to their ability to also reactively fetch information from the DOM.

One comment though to the naming of Values. The very generic name fits because they are the basic building blocks in our setup functions. At the same time I‘m afraid they are harder to grasp for newcomers and harder to talk about when creating and talking about code in teams.

What do you think about the nameReactive Value?

[antischematic]

Regarding naming convention, I went with Value because it aligns with existing Angular terminology (eg. useValue, ValueProvider).

I try to pick names that can be naturally composed in a sentence.

You can provide a Value using a ValueToken.

There's also many derivatives of Value, such as DeferredValue, AccessorValue, ComputedValue. I'm not sure adding Reactive into the mix helps much.

All Value objects are interop observables and implement NextObserver, so for those not partial to the vue-like reactivity API (reactive observers), they can ignore it.

Earlier versions used rxjs naming conventions (eg. ValueSubject) but I decided to drop the suffix. At some point in the future Angular might make rxjs an optional dependency, so I want to align with whatever comes out of this initiative.

[lennerd]

I can see your point, though I still believe the name does not carry the meaning of values insight the Composition API.

Regarding naming convention, I went with Value because it aligns with existing Angular terminology (eg. useValue, ValueProvider).

For me this is just one more reason to give it a more distinct name. The value you are referring to has a completely different meaning to me. A value insight Angulars DI system. No reactivity or other useful "magic" involved. Just a pointer to some value I want to use later. I have the feeling we can find a lot more values in the programming world because it is such a generic name. 😅

There's also many derivatives of Value, such as DeferredValue, AccessorValue, ComputedValue. I'm not sure adding Reactive into the mix helps much.

I don't think we need to carry the word reactive into other derivatives. But thats just my feeling. For me reactivity underlines the true property of a value object. A wrapper which makes the primitive value reactive. Same for deferred, accessor and computed. True, they are also reactive, but their main property is not reactivity anymore.

Earlier versions used rxjs naming conventions (eg. ValueSubject) but I decided to drop the suffix. At some point in the future Angular might make rxjs an optional dependency, so I want to align with whatever comes out of this initiative.

I'm amazed by your insights into the discussions held by the Angular community.

[lennerd]

@mmuscat btw. As we discussed in issue #22 ValueProvider are meant to carry any value, not just reactive ones.

So I’m still voting for ReactiveValue.

[lennerd]

Should pipe be a helper function insight the compositon API? Or am I missing your point?

If not, this sounds like overkill and maybe also a little like loosing the focus on the core API to me.

[antischematic]

@lennerd I agree, this went off the rails. I have a better proposal, going to hide this one.

[antischematic]

Adding a pipe utility that is just a bit of sugar on top of rxjs pipe. The idea is to express values as a series of transformations on a source observable without an intermediate subscribe.

The basic signature is:

declare function pipe<T, A>(observableInput: Observable<T>, op1: OperatorFunction<T, A>): Value<A | undefined>

function setup() {
   const userId = use(EMPTY)
   const loadTodos = inject(LoadTodos)
   const todos = pipe(userId, exhaustMap(loadTodos))

   // can set
   todos([])
   todos.next([])
   // can read
   todos()
   todos.value

   // can subscribe
   subscribe(todos, {
      next() {},
      error() {},
   })

   return {
      userId,
      todos,  // unwrapped in view
   }
}

The pipe expression

const todos = pipe(userId, exhaustMap(loadTodos))

Is equivalent to

const todos = use(userId.pipe(exhaustMap(loadTodos)))

Extraction

function loadTodos(userId) {
   return pipe(userId, exhaustMap(inject(LoadTodos)))
}

function setup() {
   const userId = use(EMPTY)
   const todos = loadTodos(userId)

   return {
      userId,
      todos,
   }
}

Overloads

// if first argument is not an observable input, behave like rxjs pipe
declare function pipe<T, A>(op1: OperatorFunction<T, A>): OperatorFunction<T, A>

declare function pipe<T, A, B, C, D, E, F, G, H, I>(observableInput: Observable<T>, op1: OperatorFunction<T, A>, op2...op8, op9: OperatorFunction<H, I>): DeferredValue<I>

declare function pipe<T, A, B, C, D, E, F, G, H, I>(op1: OperatorFunction<T, A>, op2...op8, op9: OperatorFunction<H, I>): OperatorFunction<I>

[lennerd]

Reactive Pipes … 😬

[antischematic]

I want to improve the composition API error handling story. It's never been easy to handle errors with rxjs in a way that lets you:

1. Prevent the stream from collapsing
2. Notify the user of an error
3. Conditionally retry the stream

Attempting to do this with operators is messy and tightly couples error handling and retry logic with observables that are primarily concerned with transforming data.

Proposal: Add error hooks to Value objects and introduce onError to manipulate the error stream.

function loadTodos(userId) {
   return pipe(userId, exhaustMap(inject(LoadTodos)))
}

function setup() {
   const userId = use(EMPTY)
   const todos = loadTodos(userId)
   const reload = use(Function)
   const error = onError(todos, (error) => {
      console.error(error)
      return reload
   })

   return {
      userId,
      error,
      todos,
      reload
   }
}

@Component({
   selector: "todos",
   template: `
      <div *ngIf="error else showTodos">
        Something went wrong.
        <button (click)="reload()">Reload</button>
      </div>
      <ng-template #showTodos>
         <spinner *ngIf="!todos"></spinner>
         <div *ngFor="let todo of todos">
            <todo [value]="todo"></todo>
         </div>
      </ng-template>
   `
})
export class Todos extends ViewDef(setup) { }

The onError hook intercepts the todos error observer and redirects it to a callback function. This callback function receives an ErrorState object with information about the error. The return value of onError is Value<ErrorState | undefined> and can be used to display error messages in the view.

interface ErrorState {
   retries: number // number of times this value has been retried
   message?: string // error message if provided
   error: unknown // original error object
}

By intercepting errors with onError, todos no longer emits error notifications. The value can be retried by returning a notifier from the onError callback. When this notifier emits, todos re-subscribes to the stream and starts producing values to again to new and existing observers. This also clears the error state.

onError can also be called with a single callback argument that listens to all errors caught on the component. When used this way there is no retry mechanism. The return value is ignored.

function setup() {
  const anyError = onError((error) => {
    // listen to any error
    if (error instanceof HttpError) {
      console.error(error)
    }
    // rethrow to dispatch to ErrorHandler service
    throw error
  })

  return {
    anyError
  }
}

---

Other considerations:

• Intercepting values with onError will prevent errors from triggering an error boundary.
• If there are multiple listeners, they are executed in series until the error is handled (by not rethrowing). onError will remove a listener when its context is destroyed.
• If the final listener rethrows, this is piped back to the Value error observer, producing an error notification.
• Remove the dematerialize behavior of subscribe

[antischematic]

Docs added for 0.1304.1 release
https://mmuscat.github.io/angular-composition-api/docs/utils
https://mmuscat.github.io/angular-composition-api/docs/errors

[antischematic]

Exploring composition of dynamic components with automatic handling of input and output bindings. Probably not going to add this to the core lib.

@Component()
class Widget {
  @Input() count
  @Output() countChange
}

function setup() {
  const count = use()
  const countChange = use(Function)
  const component = use(Widget)
  const widget = render(component, {
    count,
    countChange
  })
  return {
    widget
  }
}

@Component({
  template: `
    <ng-container *ngRender="widget"></ng-container>
  `
})
export class MyComponent extends ViewDef(setup) {}

ngRender is a hypothetical directive that accepts a ComponentRef because ngComponentOutlet currently doesn't. The host view is then attached to the DOM. When a new component is received the old one is detached. Cleanup is handled inside the render function, which returns a ReadonlyValue<ComponentRef>. It's also possible to bind to any public property on the component class, not just inputs (eg. for populating ViewChild and ViewChildren queries).

[antischematic]

Generalising the dynamic component example above, a JSX syntax using subjects could be possible. Note this is purely syntactic sugar, there is no VDOM or any react nonsense here. This doesn't allow for directives either.

function setup() {
  const count = use()
  const countChange = use(Function)

  const widget = <ParentComponent
    count={count}
    countChange={countChange}
  >
     <ChildComponent count={count}>
        <div>hello {count}</div>
     </ChildComponent>
  </ParentComponent>

  return {
    widget,
    count,
    countChange
  }
}

Would be equivalent to

function setup() {
  const count = use()
  const countChange = use(Function)

  const widget = [ParentComponent, {
     count,
     countChange
   }, [
     [ChildComponent, {
       count
     }, [
       ["div", null, [`hello ${count}`]],
     ]]
   ]]

  return {
    widget,
    count,
    countChange
  }
}

Then fed into ngRender which would do all the work in the template. Or used in imperative view composition (angular/angular#43120) depending on how that goes.

[lennerd]

„there is no VDOM or any react nonsense here“ 😂

Anyway. Do not see the advantage here. Why should I use this?

In generel I get the impression you aim to replace every possible code from a component. IMHO this library should focus on reusing UI logic not actual render logic.

[antischematic]

Just exploring possibilities. This won't be added to core and I have no plans of working on it. Core lib won't export anything that manipulates DOM structure..

[lennerd]

This RFC looks great. And the utilities you presented look promising as well.

How can we create some more traction? Any plans on gathering more feedback? Maybe we can post this discussion in the Angular issue board? Or some other platform where we can reach more community members?

[antischematic]

Let's not jump the gun, first impressions are everything and I don't want people jumping in who aren't going to add to the discussion. I think the best way forward is to lead by example, that means having real projects and examples to point to that people can examine, and solid documentation including a REPL and maybe video.

I occasionally post updates to the Angular discord channel, that's about the extent I'm willing to go as I don't use social media.

[antischematic]

Reworking store API, will expand later: https://github.com/mmuscat/angular-composition-api/tree/master/packages/store

[antischematic]

Adding an onChanges lifecycle hook that allows you to tap into the change detection cycle of a Value. This allows you to detect when a change originated from outside the component:

• When an @Input() changes
• When assigning to a variable in a template
• When assigning to a ComponentRef instance and calling detectChanges().

Example

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

  const changes = onChanges(count, (change) => {
    console.log(change.first) // false
    console.log(change.current)
    console.log(change.previous)
  })

  console.log(changes.first) // true
  console.log(change.current) // 0
  console.log(change.previous) // undefined

  countChange(10) // does NOT trigger `onChanges`

  return {
    count,
    countChange
  }
}

@Component({
  template: `
    <!-- Template assignment triggers `onChanges` -->
    <counter [value]="count" (valueChange)="count = $event"></counter>
  `,
  // inputs trigger `onChanges`
  inputs: ["count"]
})
export class MyComponent extends ViewDef(setup) {}

onChanges will emit Change notifications containing the current and previous value emitted.

[antischematic]

0.1306.0 released, some minor interface changes and first release of Phalanx state store.