Rename blocking and defer to something easier to understand

[dlmr]

I suggest we change some of the terminology used in the API to something easier to understand and reason about.

Old	New
blocking	beforeTransition
defer	afterTransition
parallel	runAfterTransitionImmediately

Thoughts about this change?

[PAkerstrand]

I ❤️ the before-/afterTransition names. Not too fond of parallel-rename though. In my mind it can be confused with the route transition not being blocked after all. What about runTransitionHooksInParallel? Also, I'd like to enforce that:

1. onError is at most invoked once per route transition.
2. afterTransition will only resolve if beforeTransition succeeds, else it will also reject.

Thoughts?

[dlmr]

In my mind it can be confused with the route transition not being blocked after all.

The route transition will still be blocked, it's just that we will not wait util all the beforeTransition hooks have been completed before firing of the hooks for afterTransition. So the actual effect that happens when settings parallel to true is that we start the afterTransition hooks together with beforeTransition.

1. onError is at most invoked once per route transition.

The problem with this is that if we are in parallel mode and a afterTransition hook fails, should we just handle that as a general error? The idea with having onError called twice is that we might want to handle an error from a beforeTransition hook in another way than an error for afterTransition since we might still want to make our transition.

1. afterTransition will only resolve if beforeTransition succeeds, else it will also reject.

Do you mean that we should always wait with firing any events util after beforeTransition is completed, even if afterTransition fails/completes before beforeTransition when in parallel mode?

[PAkerstrand]

In my mind it can be confused with the route transition not being blocked after all.

The route transition will still be blocked, it's just that we will not wait util all the beforeTransition hooks have been completed before firing of the hooks for afterTransition. So the actual effect that happens when settings parallel to true is that we start the afterTransition hooks together with beforeTransition.

I understand this, but I think the suggested rename makes this distinction less clear. If we runAfterTransitionImmediately "would that mean that no blocking takes place"?

1. onError is at most invoked once per route transition.

The problem with this is that if we are in parallel mode and a afterTransition hook fails, should we just handle that as a general error? The idea with having onError called twice is that we might want to handle an error from a beforeTransition hook in another way than an error for afterTransition since we might still want to make our transition.

My idea is that if/when onError is resolved, the parameter passed to onError contains all info necessary to find which hooks failed, whether the transition took place etc. Something along the lines of:

onError({
  runTransitionHooksInParallel: true,
  beforeTransitionSuccess: true,
  afterTransitionSuccess: false,
  failures: [{
    component: function Dashboard() {},
    beforeTransition: [],
    afterTransition: ['trackStatistics', 'afterTransitionCompleted'],
  }],
  router,
  location,
  ...
});

1. afterTransition will only resolve if beforeTransition succeeds, else it will also reject.

Do you mean that we should always wait with firing any events util after beforeTransition is completed, even if afterTransition fails/completes before beforeTransition when in parallel mode?

Yes, I'd like to, in some way, orchestrate the error notification in order to gather as much data as possible about the errors. And I don't think it's unreasonable to assume that in order for afterTransition to succeed, beforeTransition has to succeed before. This does not imply that we can't invoke the hooks in parallel, but rather that afterTransition has a dependency on the success of beforeTransition in order to make sense.

[dlmr]

@PAkerstrand This makes sense, will do the needed adjustments for this in #7