And no — type safety is applied at the HTTP interface. API consumers need no special library to get all the benefits.
So it's basically validation middleware. The HTTP protocol does not define any such thing.
There are various tools for it already, but the JS ecosystem has always been up for yet another framework.
I use a JsonObject to do type narrowing and generate appropriate error messages when I receive invalid data over the wire: https://www.npmjs.com/package/@retrohacker/json-types
In every codebase I’ve added this to, I’ve found invalid parsing logic.
I feel like this type, or something similar, should be bundled in the official TypeScript project. That untested data comes out as “any” is not a good developer experience in my opinion.
And “unknown” is basically broken for type narrowing.
How? Typescript 4.9 improved it for type narrowing significantly. https://devblogs.microsoft.com/typescript/announcing-typescr...
Last weekend I actually hacked an an experiment to codegen narrowing unknown to a specific type and it works pretty well https://github.com/joshhunt/codegen-json-validator-experimen...
https://github.com/microsoft/TypeScript/issues/25720
Working with untrusted types in a GraphQL project lead me to creating that JsonObject module.
I wrote up what I was thinking at the time here: http://www.blankenship.io/essays/2022-12-01/
Maybe this has improved.
You mean you could use a library that helps you with checking the shapes?
Using the json-types module above, you assign your incoming json object to the JsonObject type. Then you type narrow by validating the payload contains the properties you are using.
So you can:
const user = (await body.json()) as JsonObject;
// This is properly type narrowed and will work
if (typeof user.emailAddress === "string") {
// do something with user.emailAddress
}
// The compiler will let you know you can't trust
// user.name to be a string at this point. This
// would have generated an exception at runtime
// for a malformed payload if the compiler didn't
// catch it.
user.username.split(" ")
// You can also do type narrowing with early returns
if(typeof user.age !== number) {
return new Error("user.age is expected to be a number");
}
// You can now use user.age with type safety
```Not sure what particular use case you have in mind but which language has built-in functionality to validate chunks of bytes without some kind of type definition? To me this is an orthogonal problem to language design. Every web framework has to serialize and deserialize data.
What I was getting at is that TypeScript is perfectly suited to define type safe data structures wihtout reinventing the wheel. If you're going to parse type definitions for your validation middleware you might as well use something that can also applied to your business logic.
It converts Zod types to OpenAPI specification.
Json schema is more universal, and it can be used in .NET, Java, etc.
I want to write definitions in the "first party syntax" - which both JSDoc and Typescript types are - and have everything else generated out from that.
Typescript's types simply aren't able to provide input validation, both because they don't exist at runtime and for lack of power ("number must be 0..10").
At least with Zod, you also get Typescript types, from the same schema.
I don't want to declare my schema with zod's DSL. I'll either use an openapi spec from elsewhere and generate artefacts from that, or declare them with Typescript and... generate validation from them.
To use Typescript or not doesnt matter, it is about runtime validation. The one like the native JS way with JSDoc, the other likes Typescript and doesnt matter the build step for the API.
Personally I’m a fan of ts-rest: https://ts-rest.com/
Write a specification of your endpoints in TypeScript, and from that one spec you get:
- Server side validation of requests/responses
- A TypeScript API client
- Specialized clients, if you like, for example a react-query client if you like using react-query
- Auto-generated docs (OAS)
- TypeScript types for requests and responses to use in your code
IMO a lot more maintainable than a jsdoc based approach. For example, you can define a type for a Person, and then re-use that type in the responses of all Person-related endpoints, and even in POST/PUT/PATCH bodies (saying things like “the POST body is a person Person, but omit the id field”). With jsdoc you’re repeating that definition a tonne, AND you’re lacking compile time type safety.
It is absolutely possible to question the necessity of a or motivation behind a project, without attacking someone. It's not that OP did ruin a million dollar project. I find your comment quite harsh. Prefacing it with the very first sentence shows that you were quite aware of that. Not a good style, in my opinion.
Yes, it's verbose, but its advantages over Typescript is that it work without any compilation step, while being standard enough to give helpful type-hint on any good enough IDE.
Of course, if your project uses Typescript already, you should use Typescript instead, but if you just want to do a simple web page without any compilation step/package.json shenanigan, it's sometime nice to reach for JSDoc.
EDIT: to answer your question, in JSDoc you can typedef your own custom objects[0], so you thankfully don't have to repeat your types everywhere.
Also do I understand it correctly that you need to use Instant API everywhere in order to get this "type safety" and as such any consumer implementation would be basically limited to JavaScript?