JSDoc typing example: FunctionScript

[keithwhor]

Hey all, I’m the founder of Autocode — https://autocode.com — and we’ve built our own type safety layer that applies to the HTTP interface (for FaaS architecture) with modified JSDoc syntax. To my knowledge, our implementation is one of the earliest — if not the earliest — examples of such, published in April 2017. We now have tens of thousands of developers running active apps with this syntax. Might be good to include it in the prior art aspect of the README. We’d love to contribute to conversations in the future as well.

https://github.com/acode/FunctionScript

Type safety is extremely useful for API specifications / the FaaS model.

Two things to note about developers leveraging our model: (1) our users are primarily first-time developers and (2) the majority are under 25 years old.

[benjamingr]

I'm... not sure how using JSDoc syntax for HTTP interfaces is prior art for adding type syntax to the language? Like, I don't think it actually is prior art rather it uses other prior art (JSDoc) to type something else (not JavaScript functions but HTTP interfaces).

I'm all for your enthusiasm for your business though :D always nice to see a founder excited about their company/product.

[benjamingr]

I think feedback would be useful regardless of prior art - if there is anything you missed in JSDoc or TypeScript or any footguns for example.

[keithwhor]

Like, I don't think it actually is prior art rather it uses other prior art (JSDoc) to type something else (not JavaScript functions but HTTP interfaces)

What is technical art if not combining existing technologies or applying a piece of technology across domains. :)

Re: feedback. Biggest piece is that adding typing to JavaScript gives the language a clean bridge into treating web APIs as first-class citizens of the development environment. It does so by enabling functions to be exportable directly to a web interface in a safe manner; the FaaS model of software development is only likely to get more popular with time. As developer products like ours reach more and more users, this functionality will become increasingly important. People want to build for the web. Typed function signatures provide a way to do so sanely and easily. So +1 for whole proposal.

Other points we've found, though more related to HTTP interfaces and less to the language itself:

• nullability is important for optional parameters -- as in defaults to null as opposed to undefined. undefined is rarely useful when you have a type signature and HTTP interfaces are impermeable to undefined values since the value doesn't exist in JSON.
• I know enums are omitted here, but they are important; mapping readable string constants to values helps build easier-to-digest APIs
• ranges are incredibly useful for number values
• though functionally non-existent outside of Typed Arrays, integer is an important type, especially when crossing the HTTP boundary

[orta]

I think an exercise which might be useful for this proposal is to think what it would look what the optimal syntax would be for your FunctionScript if being runtime compatible with JS wasn't a problem. The same types of constraints would apply to other serverless-y environments ( e.g. Lambda, Azure, Vercel etc )I'd imagine too

[matthew-dean]

Hmm the JSDoc extensions for FunctionScript are kind of clunky and ultimately, violate the JSDoc spec, do they not?