RFC: $transition$ injectable promise

[christopherthielen]

I've been working on the "transition service" idea that's been tossed around here. See this commit in ui-router-extras: christopherthielen/ui-router-extras@92c4f81

So far, I have implemented and tested

• $transition$: an injectable object which contains:
  • the to state/params
  • the from state/params
  • a promise which wraps the $state.transitionTo() promise
• $transitionStart: a new event, fired in response to $stateChangeStart which exposes the $transition$ object/promise
• $transitionSuccess and $transitionError Mirrors $stateChangeSuccess/Error, but are broadcasted based on the promise. I'm not sold on these, they seem perhaps unnecessary, but I put them in because it was ridiculously easy to do so.

---

$transition$

The $transition$ object contains the details of the current transition, to: { state: toState, params: toParams} and from: { state: fromState, params: fromParams } }. It also has promise which is resolved when the promise returned by $state.transitionTo() is resolved.

$transition is injectable as long as the transition is currently in process. This means it can be injected into onEnter/onExit/controller functions.

$transitionStart

The $transitionStart event fires in response to $stateChangeStart. This event exposes $transition to interested parties. Since $transitionStart exposes $transition$, it allows interested parties to listen for transitions, then process them using promises, which was impossible using $stateChangeStart.

benefits

• Listen for state changes, respond using promises. When listening for $stateChangeStart/Success/Error, there is a separation between the starting event and the terminating event. One also has to listen for both Success and Error events to connect the dots.
• Inject current transition into code invoked while the transition is pending. Currently, onEnter/Exit/controller don't know why they are being invoked. For example, the onEnter doesn't know if the destination state is that specific state, or some substate.
• ??? other things?
• Profit!!!

closes

I believe this change would address the following:

#1169
#1182
#1153
#1151
#1112
#1100
#1085
#1016
#575
#238
#23

[christopherthielen]

Also #1259

[christopherthielen]

As of version 0.0.10, UI-Router Extras now has the $transition$ api, as an incubator/early-access to what we're working towards in UI-Router.

See this plunkr: http://embed.plnkr.co/0jbkBmAJUoMDYpt8FXao/preview for a demo.

This demonstrates:

• Listening for $transitionStart event
  • .then(success, error) on the $transition$.promise passed into the $transitionStart listener
  • .finally() on $transition$.promise passed into the $transitionStart listener
• Injection of the currently active $transition$ into onEnter/onExit blocks of states
• Injection of the currently active $transition$ into a controller.

[timkindberg]

This is really awesome Chris! So would we have both $stateChangeStart and $transitionStart? I think we may just want one or the other. Are they different really?

[christopherthielen]

The problem I ran into is that $stateChangeStart event has 5 parameters already, so to avoid a breaking change, I either had to introduce another event with just the event and a single transition param, or add transition as the sixth parameter. I figured $transitionStart would win in the long run, so opted for the first option since people would probably ignore the first 5 parameters if we chose the latter option.

[bvaughn]

A key difference @timkindberg, at least in how it relates to the comment I left on 238, is the to state. The $stateChangeStart event doesn't specify a valid to-state and you end up having to manually track it.

[timkindberg]

@christopherthielen I wouldn't be too worried about breaking changes if we are ultimately doing more good than harm. I'd rather keep the API simple and have breaking changes. Anyway, if you haven't noticed I'm not around too much anymore, but still loving what you guys are doing... so what I'm saying is its up to you!