Type Definitions in architect/functions

[tbeseda]

I wanted to document a recent convo with Arc user @zachrip that mirrors discussions I've had with a few others. I think there's a lot of value in adding and owning types for the functions lib. What do others think?

Background

We've chatted about this before and given the research at the time and availability of a DefinitelyTyped package, we decided to let that library handle typings. However, it has fallen out of sync and is actually more work in a process outside our team's control. IMO there are simpler, new-ish approaches for providing types in the actual @architect/functions package that can work for us.

If we want, it can be a single .d.ts file (but a folder might be better for maintenance) and an update to the package.json file.
This is how I added types to arcdown. I also added a test for types with dtslint (tooling from MS) -- but this isn't totally necessary.

Goals

1. provide types for the @architect/functions user APIs (ie. arc.http|tables|events|etc)
2. internalize those types -- don't rely on @types/
3. don't modify any actual library code
4. no change to internal API JSDoc comments
5. optionally, test the definitions

Trade-offs

• changes to the userland API will require updates to the type definitions
• others?

[I left out any discussion about the benefits of typings for TS and JS users, because at this point it seems apparent, but I'm happy to demo the advantages for anyone unconvinced 😀]

[camjackson]

I think internalising the types is a great idea. As a developer it's always nice if I install a library and its types are ready to go, instead of having to install a separate library. There's some overhead in maintaining the types, but that overhead is only worsened when the types are in a completely separate package.

When I've done this in the past I've tended to just put the types directly in the source of my library, rather than use a .d.ts. But I can see that this arc/functions is written in JS, not TS, so I guess that's not an option here.

If you're open to PRs, I'd be happy to have a crack at this?