types: make model types support sync AND async methods

[jankapunkt]

Summary

This is proof of concept for further discussion, related to #344
Please add your opinion and review.

Linked issue(s)

#344

Involved parts of the project

Types

Added tests?

OAuth2 standard

Reproduction

Custom IDE related

[z1haze]

Thanks for this

[Copilot]

Copilot wasn't able to review any files in this pull request.

[HappyZombies]

So I have an opinion here, this isn't really about runtime compatibility (which is fine), since the lib treats every model function as async, but about whether the type system should match what the documentation states.

I think really there are 2 possible solutions:

1. Update the types to string | Promise to match the doc's promise of sync-or-async. (Which is what this CR is doing).

2. Update the docs to clarify: “You can write synchronous logic, but model methods must return a Promise.”

To me option 2 seems cleaner — the current typings enforce consistent async shape and avoid noisy unions. Since async functions support returning sync values anyway, for example, just wrap it in async? That will always return a promise.

(async () => 'foo')(); // returns a resolved Promise

What do yall think?

[dhensby]

I agree with @HappyZombies - people can mark their function async and they are compatible with the typing system and the method is still technically sync (but I admit is returning a promise). Generally I'd prefer a narrower well defined interface in TS than one that covers all the technical possibilities of the implementation (a problem our types currently have with the bespoke Falsey type - something I've thought about trying to remove).

If the OP of the discussion doesn't like sticking to the type declaration, then use JS, if they want to use TS they they'll need to adhere to the typings because those are the intended (rather than possible) interfaces

[jankapunkt]

@HappyZombies @dhensby thank you for your input. Since I'm no TypeScript pro I can't really add valuable information. Feel free to close, if you think this is out of scope.