Improve some confusing parts of the API.

[jamestalmage]

Goals

Improve some confusing naming / behavior in the API.

Background

As a new user of the library, doing an incremental rollout, I had the following experience:

1. Started with no database adapter, got role-based example working using the profile method on Github and Google providers to determine roll, and copying the roll to the token from user...
2. Added a database, it broke things, because now token was gone. Had to rework my callbacks.
3. Tried to implement a split configuration for edge compatibility, and to reduce all the database calls I was seeing. Callbacks needed to be reverted to jwt strategies, and I was surprised to find that ALL database activity ceased.

Having spent some time digging in to the code and documentation, I'm beginning to have a better understanding of what's going on, but I still need to double-check the purpose of each callback.

Proposal

I think there is room for improvement in API and/or documentation.

• If the output of the profile callback is going to be passed to the jwt and/or session callback, the property should be called profile. Similarly, if the session callback is going to receive the output of the jwt callback, it should be called jwt instead of token... (Basically, have the name of the property be a strong hint as to which callback produced said property).

• I think there should be a place in the documentation with a flow chart of exactly how a call progresses through each possible callback (not just the flow chart of oauth flow, but how / when each callback is called). If it exists, I somehow missed it.

• If the purpose of the session callback is to filter which data should be exposed to the client, it should be renamed in a way that reflects that. (i.e. buildClientExposedSession)

• It seems that in many of the callbacks a "default" value is built, and users are meant to augment it... If that's the case, I propose there be two available callbacks, implementers can choose to override either:

  • buildXXX (i.e. buildSession, buildToken....) In which the user is expected to build the entire return value from the inputs.
    *.enhanceXXX (i.e. extendSession, extendToken) In which the user is expected to enhance the default value with extra properties.

• Where the strategy used will determine the shape of parameters, I think one of the properties should be sessionStrategy, and a discriminated union, based on that property, should be used to enhance type safety.