feat(server): add a subscriptions server

[jasonkuhrt]

closes #897

TODO

• docs
  • jsdoc
  • website api
  • website guides
  • website tutorial
• tests

[jasonkuhrt]

The following comment is really reflection on the Setset library.

It would be great if Setset could have initializers that depend upon external data.

This would require initializers to not run at construction time but at "assembly" time. External data would be passed at this time. And initializers would then run.

This would mean it would not be possible for users to access settings data and metadata before assembly. At least those that depend on assembly.

We could call these settings "assembled settings".

Maybe assembled settings would have a special initialized state before assembly. Like a constant "__PENDING_ASSEMBLY__". That could work from a runtime point of view.

What about from a static point of view? Firstly, like Setset.Leaf we would need a new type Setset.Assembled.

Then we would need the new .assemble method to return a statically transformed version of the settings wherein "__PENDING_ASSEMBLY__" would be stripped as a type.

Example:

// foo is an assembled setting

settings.data.foo // number | "__PENDING_ASSEMBLY__"
settings = settings.assemble()
settings.data.foo // number

This static behaviour looks NTH at best for Nexus b/c end users wouldn't be seeing this static transformation b/c it happens internally within Nexus.

What would be user facing though is this case:

settings.data.foo // number | "__PENDING_ASSEMBLY__"
settings.change({ foo: 1 })
settings.data.foo // should be: number
                  // actual:    number | "__PENDING_ASSEMBLY__"

Assembled initializers don't matter once the user has explicitly set the setting.

Like before we could capture the transformation in the return value of .change() (maybe...) however the mutative quality of Setset is currently an important DX aspect of it so it can be used as an e.g. singleton. ... This looks like an impossible problem to solve not withstanding new features from TS itself.

Typegen doesn't help because the effect lives between LOC.

One solution could be a utility to strip the pending assembly type:

settings.data.foo // number | "__PENDING_ASSEMBLY__"
settings.change({ foo: 1 })
Setset.notPendingAssembly(settings.data.foo) // number

Statically this would strip the "__PENDING_ASSEMBLY__" type. Dynamically it would check that the value isn't "__PENDING_ASSEMBLY__". Those dynamic checks could be disabled in production.

If most settings were assembled and the user often accessed those settings having to wield this utility function often could get very annoying.

But frankly it is totally unclear if that is the case. For example in Nexus the number of users that are going to be checking the settings.data.server.subscriptions.enabled option seems to be near zero.

So overall my conclusion is:

• introducing the concept of assembly removes buggy code from the system
  • internally more related logic gets to be colocated
  • extenerally users won't see the simply wrong settings.data.server.subscriptions.enabled // false when its actually true because they defined subscription type in this schema
• the static type of pending assembly allows for the effect of assembly to be tracked for users
• it is not possible to track .change effects mutatively so the utility function notPendingAssembly can come to the rescue in rare (?) occasions when user needs to deal with the assembled setting explicitly

[jasonkuhrt]

See large design comment about Setset

[giautm]

@jasonkuhrt hey, there is has some typo

[giautm]

PR here: https://github.com/graphql-nexus/nexus/pull/1407