Declaration Merging over scopes in the documentation

[RafaelGSS]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

In the documentation, we have some sections approaching the declaration merging, however, looks reasonable to add a declaration merging over scopes as well.

For instance, you have scope X and scope Y:

function scopeX(fastify, opts, done) {
  fastify.register(require('fastify-jwt'), { ...jwtOptions })
  done()
}

function scopeY(fastify, opts, done) {
  // fastify.jwt is undefined, but it shows as a property in the intelisense because of declaration merging
  fastify.jwt
}

fastify.register(scopeX)
fastify.register(scopeY)

Motivation

Fastify was designed to work gracefully with encapsulation, and it should be replicated by their types.

[RafaelGSS]

@fastify/typescript do you know if it's possible to use declaration-merging over scopes by just a configuration in the tsconfig? Looks like a barrier.

[simoneb]

It would be interesting to understand how declaration merging actually works here.

Please correct me if I'm wrong but I believe that the fastify.jwt decorator is shown in autocompletion because it's exported by the fastify-jwt package, meaning that as soon as you require that package in your code typescript will assume that any occurrence of FastifyInstance in your code will have that decorator.

If that is true, then the problem becomes: how do we restrict declaration merging in a way that it only applies to certain parts of the codebase? It sounds like a tricky problem to solve!

[jsumners]

If anyone tackles this before #3474 is merged, please branch from it and target that branch in the PR.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[RafaelGSS]

I gave it a shot 5 months ago, however, I haven't found a good way to do that. @fastify/typescript @sinclairzx81 do you have any thoughts on that? Otherwise, I'll close it.

[sinclairzx81]

@RafaelGSS Hi

Unfortunately, I don't see a easy way to enable this without changing the signature of register() and forcing either method chaining (as below to allow the context to propagate) or providing generic hints on the scopeX(..) and scopeY(..) functions (as per reference example for this issue). Something like the following.

// remap to Fastify<DefaaultFastifyContext & { jwt: {...} }>
fastify.register((fastify, opts) => { return { jwt: require('fastify-jwt') } })
       .register(async (fastify, opts) => { console.log(fastify.jwt); return {} }) 

One thought might be to drop the done() function in favor of returning a PartialContext | Promise<PartialContext> only where the PartialContext can be Object.assign(fastify, partialContext)'ed and be type remapped to Fastify & PartialContext.

In terms of the scopeX() and scopeY() generic hints, there might be something that can be done with Instantiation expressions (available in TS 4.7) to allow the return type of scopeX() to be inferred as a generic hint on scopeY(), but the provision for this to work would be that the signature for register() is updated accordingly to return an inferable PartialContext

It might be best to defer this for a later time (I think there could be a larger discussion to be had around aligning some of the JS logic to be a bit more conducive towards TS inference) and narrowing some of the ways users can interact with Fastify, this with some notes to other issues I've seen such as #3810 (comment).

Hope that helps!

[RafaelGSS]

Thank you!