Improve type definitions to allow strict type-checking of ctx.call, actions definitions and events

[Telokis]

📝 Description

The current type definitions do not provide any type-safety regarding ctx.call, ctx.emit, actions definitions in services and events handlers in services.
This merge requests updates the type definitions with type-safety mecanisms for both actions and events.
A detailed explanation can be found in #822 where the implementation was explained as it was developed.

The changes are made with 100% retro-compatibility in mind. If no mapping is provided, the behavior is the current, forgiving one.

Impacts of the type definitions changes:

• Action handlers must return the proper value if ActionsMapping and ActionsEntry are specified.
• Field actions of service schema recognizes specific keys based on ActionsMapping and ActionsEntry.
• Field events of service schema recognizes specific keys based on EventsMapping.
• never can be used as first generic argument for Service. (Fallbacks to the default value)
• Context.params is strictly-typed within an action handler if ActionsMapping is provided.
• Context.params is strictly-typed within an event handler if EventsMapping is provided.
• Context.eventName is strictly-typed if EventsMapping is provided.
• Context.call is strictly-typed if ActionsMapping is provided.
• Context.emit is strictly-typed if EventsMapping is provided.
• Context.broadcast is strictly-typed if EventsMapping is provided.
• ServiceBroker.call is strictly-typed if ActionsMapping is provided.
• ServiceBroker.emit is strictly-typed if EventsMapping is provided.
• ServiceBroker.broadcast is strictly-typed if EventsMapping is provided.
• ServiceBroker.broadcastLocal is strictly-typed if EventsMapping is provided.
• The index signature of ActionSchema has been narrowed down a bit. See this comment and the section Caveats at the bottom of this description.

🎯 Relevant issues

Closes #822

💎 Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

📜 Example code

Complete example in TypeSript playground

🚦 How Has This Been Tested?

This is currently being used in the project I made the changes for.
The playground link provided above also contains a quite exhaustive example of the new type-safety.

🏁 Checklist:

• My code follows the style guidelines of this project
  --> I reverted everything my eslint/prettier changed.
• I have performed a self-review of my own code
• I have added tests that prove my fix is effective or that my feature works
  --> The tsd dependency doesn't support TypeScript 4.1.0 yet. Tests are broken until then.
• New and existing unit tests pass locally with my changes
  --> Same reason as above.
• I have commented my code, particularly in hard-to-understand areas
  --> I did my best to make sure every trick is properly commented and explained

⚠️ Caveats:

• The code requires TypeScript 4.1.0 (Heavily relies on this feature) and can't be merged until it is officially released.
• The too permissive type mentionned in this comment
• The ServiceEventLegacyHandler/ServiceEventHandler ambiguity mentioned in this comment below ServiceEvent function deduction issue.
• People might rely on the syntax using *s for event handling. Those aren't recognized as special cases and must be @ts-ignored or specified in the EventsMapping. (The latter is recommended)

[Wallacy]

FWIW, TypeScript 4.1 is out: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html

[Telokis]

@Wallacy Hi! Yes, I noticed the release, thanks for telling me.
For now, I'm a bit burned out, I don't know when I'll be able to take the time and finish this properly.

[marbemac]

@icebob we ended up forking off of this and improving a few more typing related things - it has been immensely helpful, thank you @Telokis! Would have to double check but I don't think there are any breaking changes - if that's the case is this sort of typing change something you would consider accepting? If so we'll put it on our list to open up a PR.

[icebob]

@marbemac if it contains big changes which can cause problems for developers who are using the current typescript definitions, that I will be able to accept the PR in the next 0.15 version.

[edurdias]

@icebob, Do we have a timeline in place for the 0.15? What are your thoughts?

…

On Mon, Oct 11, 2021 at 9:42 AM Icebob ***@***.***> wrote: @marbemac <https://github.com/marbemac> if it contains big changes which can cause problems for developers who are using the current typescript definitions, that I will be able to accept the PR in the next 0.15 version. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#829 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAOF6HM3OTZRAP5JLC2NSEDUGLZVBANCNFSM4SUP56UA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[icebob]

@edurdias not yet. I'm collecting the major features/changes what will be implemented in 0.15. I think it can be released only in 22H1.

[Laurin-W]

Are there any updates on this? Would be super helpful.. :)