💬 RFC

Summary

We have introduced a breaking change in the way propertyChanged callbacks behave, but we could easily revert that breaking change. Should we, though? We need opinions.

🔦 Context

v1

If your component has no bind method, the initialization logic will place that method on your component and it would invoke those callbacks. So:

• propertyChanged callbacks are invoked during the bind lifecycle by default.
• If you declare the bind method in your component, they are not invoked (because the method that invokes them is not placed on your component).

v2

We have the improved architecture and flexibility to do pretty much anything here, but we need to pick something as a default. In line with improving unobtrusiveness (e.g. not placing methods on your components), we temporarily decided on the following:

• propertyChanged callbacks are never invoked during the bind lifecycle
• Declaring the binding (v2’s equivalent of bind) method does not affect any behavior

This is based on some assumptions, which may or may not be correct:

• Often, you only need to do something when a value changes (as opposed to being set for the first time)
• If you need to do something specific during bind, the changed behavior of propertyChanged callbacks can catch you off-guard. It requires you to be aware of a framework internal that is not necessarily intuitive.
• If you need to do something during initial set of one or more properties, it’s typically irrespective of which specific property changed; rather it’s a component-wide initialization that may use several properties. It makes more sense to invoke this logic from binding hook than from a propertyChanged callback.

But it’s a breaking change

And that in itself might also catch people off-guard, so we need to find out if above assumptions are correct in the sense that:

• opt-in for propertyChanged callbacks during bind makes more sense than opt-out
• consistent propertyChanged callback behavior irrespective of the presence/absence of binding makes more sense than hook-dependent behavior

Again, we have the flexibility to do pretty much anything here, we don’t have some of the constraints we did in v1. We just need to make a choice for something which we then won’t be changing for the years to come.

💻 Examples

Assume a simple component with a single bindable property. We set its initial value to 42 from the app (not shown here), and after initialization we set it to 43, and observe the console log.

v1

without bind hook

export class Component {
  @bindable property;

  propertyChanged(newValue, oldValue) {
    console.log('propertyChanged', newValue, oldValue);
  }
}

startup log

enter component controller.bind
  'propertyChanged', 42, undefined
leave component controller.bind
'propertyChanged', 43, 42

with bind hook

export class Component {
  @bindable property;

  propertyChanged(newValue, oldValue) {
    console.log('propertyChanged', newValue, oldValue);
  }

  bind() {
    console.log('bind', this.property);
  }
}

startup log

enter component controller.bind
  'bind', 42
leave component controller.bind
'propertyChanged', 43, 42

v2 with opt-in (as it is now)

Note: flags is a numeric property represented by const enum LifecycleFlags. They’re shown as strings in the log to understand better how they could be utilized here. Also, flags which are irrelevant for the purpose of this examples (e.g. fromStartTask) are omitted for brevity.

without binding hook

export class Component {
  @bindable property;

  propertyChanged(newValue, oldValue, flags) {
    console.log('propertyChanged', newValue, oldValue, flags);
  }
}

startup log

enter component controller.bind
leave component controller.bind
'propertyChanged', 43, 42, 'updateTarget'

with binding hook

export class Component {
  @bindable property;

  propertyChanged(newValue, oldValue, flags) {
    console.log('propertyChanged', newValue, oldValue, flags);
  }

  binding() {
    console.log('bind', this.property);
  }
}

startup log

enter component controller.bind
  'binding', 42
leave component controller.bind
'propertyChanged', 43, 42, 'updateTarget'

v2 with opt-out

without binding hook

export class Component {
  @bindable property;

  propertyChanged(newValue, oldValue, flags) {
    console.log('propertyChanged', newValue, oldValue, flags);
  }
}

startup log

enter component controller.bind
  'propertyChanged', 42, undefined, 'updateTarget | fromBind'
leave component controller.bind
'propertyChanged', 43, 42, 'updateTarget'

with binding hook

export class Component {
  @bindable property;

  propertyChanged(newValue, oldValue, flags) {
    console.log('propertyChanged', newValue, oldValue, flags);
  }

  binding() {
    console.log('bind', this.property);
  }
}

startup log

enter component controller.bind
  'propertyChanged', 42, undefined, 'updateTarget | fromBind'
  'binding', 42
leave component controller.bind
'propertyChanged', 43, 42, 'updateTarget'

TL;DR

What makes the most sense to you, the user?

• Option 1: v1 behavior The presence/absence of bind() method determines whether propertyChanged is invoked during bind.

• Option 2: v2 behavior, opt-in propertyChanged is never invoked during bind. If you need them to be invoked, you must do so by manually invoking them from the binding() hook

• Option 2: v2 behavior, opt-out propertyChanged is always invoked during bind. If you need to ignore them during bind, you can use the flags (e.g. if (!LifecycleFlags.fromBind(flags) { /* ... */ }) to conditionally execute your logic.