Document context merging order for before hook ctx

[justinabrahms]

Fixes #124

[toddbaert]

I dont love that this is a bit redundant with 3.2.2, but that was true before this change and I'm not sure the best way to resolve it. I think this is an improvement.

[toddbaert]

I think this made perfect sense before provider hooks, but now with them in the mix, things get more complicated.

One of the primary use-cases of provider hooks is context transformation... if a provider hook does significant context transformation (say, into some vendor-specific object, or by serializing values in some required way) then it has to have the highest merge priority, right?

So do we do:

(top-most wins):

1. before hook
2. invocation
3. client
4. api

or

(top-most wins):

1. provider before hooks
2. invocation
3. before hook
4. client
5. api

[justinabrahms]

Huh. I don't like our options now. :-P

You're thinking that a context transformation use-case is going to set an additional property on the context that's specific for the provider?

How about this (top-most wins)?

1. provider before hooks
2. invocation hooks
3. invocation context
4. client before hook
5. client context
6. api before hook
7. api context

[toddbaert]

You're thinking that a context transformation use-case is going to set an additional property on the context that's specific for the provider?

Well yes, but to be honest, I was thinking something even more potentially problematic - our context transformer allowed the context object to be an entirely new object/instance - for example an LDUser. I'm not sure that was understood 😅 . As you can imagine merging after that transformation is completely impossible.

At the very least, I think provider hooks may transform the context in a way to maintain compatibility with their particular backend, so they need to "win".

[toddbaert]

Thinking about it more, considering implementation difficulty and cognitive burden on application-authors, I think I'm in favor of:

(top-most wins):

1. before hooks (all of them, including provider hooks)
2. invocation
3. client
4. api

So hooks will always win... I think this is OK and simple to understand. If the author REALLY wants to override something in their invocation, they can use an invocation before hook to do that, which will override everything except the provider hooks (which is ideal).

@justinabrahms @beeme1mr what do you guys think about that?

[justinabrahms]

I think I could be into that. So we're saying that:

• We don't really expect you to specify content in your invocation context that will collide w/ things the hooks provide.
• If you do have a conflict you want to exclude, we expect you to define an inline hook.
• You cannot override before hook values from a provider.

[toddbaert]

I think I could be into that. So we're saying that:

• We don't really expect you to specify content in your invocation context that will collide w/ things the hooks provide.
• If you do have a conflict you want to exclude, we expect you to define an inline hook.
• You cannot override before hook values from a provider.

Exactly.