3 ms·

I wonder why this isn't written in Typescript directly so as to handle documentation, validation and type definitions in one go. Especially if you want to reus

I wonder why this isn't written in Typescript directly so as to handle documentation, validation and type definitions in one go. Especially if you want to reuse type definitions of objects elsewhere in your code. An API request or response usually do not contain the exact model attributes. Only the public facing ones which are then often filtered down some more, depending on the user making the request (and their roles, groups, permissions).

eyelidlessness 3y ago
> I wonder why this isn't written in Typescript directly so as to handle documentation, validation and type definitions in one go. I suspect they want TypeSpec to be more runtime agnostic (as also tends to be the preference with TypeScript). Specifically to support arbitrary validation/serde. Having written a fully integrated generalized solution (runtime-defined schema -> parser, types, documentation, serializer), by far my biggest regret the first time around is coupling it so closely to a particular schema runtime. Partly this is because I have bigger dreams for designing a schema system purpose built for the task (I had previously piggybacked on io-ts, which worked but it took considerable non-essential effort and complexity); partly it’s because there can be significant tradeoffs between different runtime solutions in terms of performance and ergonomics.
bterlson 3y ago
Our first attempt at a TypeSpec-like thing was in fact a TypeScript dialect! It works great for simple cases, but at the limit it falls over for a number of reasons. HTTP needs a lot of metadata that isn't found in TypeScript, things like HTTP verbs, query/path params, headers, routes, etc. API patterns also need their own metadata, like for pagination you need to know various bits of metadata that describe how to paginate an endpoint. Also many things in the TypeScript type system and stdlib don't apply in the context of API descriptions, so we needed a subset. So after going down this road for a while, we found we were in a place where the syntax was actually very complex, with metadata spread between deeply nested generic type instantiations and JSDoc comments, and didn't feel at all like TypeScript. This didn't align with our goals of having something simple and easy to learn for all devs. So I wrote the first implementation of a custom language in a day and folks really liked the direction. 4 years later, here we are!

eyelidlessness 3y ago

> I wonder why this isn't written in Typescript directly so as to handle documentation, validation and type definitions in one go. I suspect they want TypeSpec to be more runtime agnostic (as also tends to be the preference with TypeScript). Specifically to support arbitrary validation/serde. Having written a fully integrated generalized solution (runtime-defined schema -> parser, types, documentation, serializer), by far my biggest regret the first time around is coupling it so closely to a particular schema runtime. Partly this is because I have bigger dreams for designing a schema system purpose built for the task (I had previously piggybacked on io-ts, which worked but it took considerable non-essential effort and complexity); partly it’s because there can be significant tradeoffs between different runtime solutions in terms of performance and ergonomics.

bterlson 3y ago

Our first attempt at a TypeSpec-like thing was in fact a TypeScript dialect! It works great for simple cases, but at the limit it falls over for a number of reasons. HTTP needs a lot of metadata that isn't found in TypeScript, things like HTTP verbs, query/path params, headers, routes, etc. API patterns also need their own metadata, like for pagination you need to know various bits of metadata that describe how to paginate an endpoint. Also many things in the TypeScript type system and stdlib don't apply in the context of API descriptions, so we needed a subset. So after going down this road for a while, we found we were in a place where the syntax was actually very complex, with metadata spread between deeply nested generic type instantiations and JSDoc comments, and didn't feel at all like TypeScript. This didn't align with our goals of having something simple and easy to learn for all devs. So I wrote the first implementation of a custom language in a day and folks really liked the direction. 4 years later, here we are!