This comes up so often, and every time I wonder how much the people who want it have a shared understanding of what it is they want. I realize this is reiterating a point that TS team members have already made, but I’m coming from a different perspective: actually having built higher level tooling on top of one of the solutions mentioned in the post, and having built a fairly mature prototype of another solution from the ground up to address problems none of the existing offerings solve.
My use case isn’t particularly outlandish, I can even imagine it being non-niche if I ever get around to publishing it. But it’s also pretty far afield from any of the existing solutions: platform-agnostic documentation as a core/foundational principle.
My original work implemented JSON Schema documentation on top of io-ts, and added some runtime and type level functionality to support that. But my vision for a hypothetical successor is that
- the documentation standard itself (whether JSON Schema, OpenAPI, or any other underlying format) should be the underlying primitive
- the underlying format should be composable to produce APIs which are just as user friendly (ie users shouldn’t have to muck around with the doc format unless they have a really specific use case, and even then they should still be able to compose the parts they’re not concerned with)
- no additional build time codegen tooling: define a schema once, its type is inferrable from the definition without a compiler extension or IDE config, its documentation is a plain function call executable in any standard runtime to resolve what’s composed
This is all very achievable in TypeScript as-is. But it’s way out of scope from what I imagine any first class thing would or should be. And sure, if such first class thing existed, that wouldn’t make my thing any less achievable. But here’s what I think it would do:
1. Disincentivize usage by users who prefer the first class thing with type syntax as the primary authoring mechanism.
2. Incentivize me to cave on tooling to accommodate that.
3. Piss people off because “we wanted less tooling not more”.
4. Recurse into this same debate.
I’d personally prefer the status quo. Even if that means rehashing the same debate every few months, at least it’s at a recursion depth that’s manageable and doesn’t have countless other sets of unintended consequences.
My use case isn’t particularly outlandish, I can even imagine it being non-niche if I ever get around to publishing it. But it’s also pretty far afield from any of the existing solutions: platform-agnostic documentation as a core/foundational principle.
My original work implemented JSON Schema documentation on top of io-ts, and added some runtime and type level functionality to support that. But my vision for a hypothetical successor is that
- the documentation standard itself (whether JSON Schema, OpenAPI, or any other underlying format) should be the underlying primitive
- the underlying format should be composable to produce APIs which are just as user friendly (ie users shouldn’t have to muck around with the doc format unless they have a really specific use case, and even then they should still be able to compose the parts they’re not concerned with)
- no additional build time codegen tooling: define a schema once, its type is inferrable from the definition without a compiler extension or IDE config, its documentation is a plain function call executable in any standard runtime to resolve what’s composed
This is all very achievable in TypeScript as-is. But it’s way out of scope from what I imagine any first class thing would or should be. And sure, if such first class thing existed, that wouldn’t make my thing any less achievable. But here’s what I think it would do:
1. Disincentivize usage by users who prefer the first class thing with type syntax as the primary authoring mechanism.
2. Incentivize me to cave on tooling to accommodate that.
3. Piss people off because “we wanted less tooling not more”.
4. Recurse into this same debate.
I’d personally prefer the status quo. Even if that means rehashing the same debate every few months, at least it’s at a recursion depth that’s manageable and doesn’t have countless other sets of unintended consequences.