6 ms·

Seems like you put a lot of work into this and as such I'm hesitant to criticize. But what in the world made you think this is superior to using an actual type-

Seems like you put a lot of work into this and as such I'm hesitant to criticize. But what in the world made you think this is superior to using an actual type-safe language like TypeScript? /** * Streams results for our lovable assistant * @param {string} query The question for our assistant * @stream {object} chunk * @stream {string} chunk.id * @stream {string} chunk.object * @stream {integer} chunk.created * @stream {string} chunk.model * @stream {object[]} chunk.choices * @stream {integer} chunk.choices[].index * @stream {object} chunk.choices[].delta * @stream {?string} chunk.choices[].delta.role * @stream {?string} chunk.choices[].delta.content * @returns {object} message * @returns {string} message.content */ Is a developer supposed to type that out for every single endpoint that uses the chunk type? 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?

keithwhor 3y ago
No not necessarily! I just haven’t written type import support yet; though you’re welcome to help. And no — type safety is applied at the HTTP interface. API consumers need no special library to get all the benefits.
- codemusings 3y ago
  > And no — type safety is applied at the HTTP interface. So it's basically validation middleware. The HTTP protocol does not define any such thing.
  - jfengel 3y ago
    No, and neither does Typescript. One of the biggest weaknesses in Typescript is that it can't validate data across the wire. Which is a major use case for the language. There are various tools for it already, but the JS ecosystem has always been up for yet another framework.
    - r3trohack3r 3y ago
      I hear you, but I don’t think this is necessarily true. It does leave type checking to your parsing logic, but the compiler can give you strong guarantees that you’re being defensive about untrusted structured data. 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 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.
      - madeofpalk 3y ago
        > And “unknown” is basically broken for type narrowing. How? Typescript 4.9 improved it for type narrowing significantly. https://devblogs.microsoft.com/typescript/announcing-typescript-4-9/#in-narrowing 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-experiment/blob/main/output.ts https://github.com/joshhunt/codegen-json-validator-experimen...
        r3trohack3r 3y ago
        I haven't worked much in typescript over the last 10 months, but last time I tried type narrowing on untrusted data typecast to unknown I ran into a handful of problems documented here: https://github.com/microsoft/TypeScript/issues/25720 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/ http://www.blankenship.io/essays/2022-12-01/ Maybe this has improved.
        madeofpalk 3y ago
        Yes. The main one is `foo in obj` now correctly narrows to `unknown & { foo: unknown }`. This allows you to correctly narrow an unknown to a fully typed object, as my code sample shows :)
9dev 3y ago
Yes, I was wondering about that too. If you put in the effort to parse the docblock into runtime validation, why not pick up the existing utilities to convert TypeScript types into runtime code during the build? That would be much more powerful, with the added benefit of having type safety for all other code, and a familiar syntax for developers.
- ushakov 3y ago
  …or just use Zod?
  - Ciantic 3y ago
    And if you like Zod, you might as well use this: https://github.com/asteasolutions/zod-to-openapi https://github.com/asteasolutions/zod-to-openapi It converts Zod types to OpenAPI specification.
    - vmfunction 3y ago
      Or json schema, this https://www.npmjs.com/package/zod-to-json-schema https://www.npmjs.com/package/zod-to-json-schema Json schema is more universal, and it can be used in .NET, Java, etc.
  - 9dev 3y ago
    Yeah, that’s what I was thinking of. There are a few alternatives though, so I referred to existing tooling in general.
  - madeofpalk 3y ago
    I don't like writing type definitions with zod's DSL. 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.
    - purplerabbit 3y ago
      I like the sentiment, but you’ve gotta admit that being able to skip the “generation” step has its benefits
ushakov 3y ago
You should check out tsoa, ts-rest, zodios and feTS
w3news 3y ago
It is type safety at runtime. Typescript gives you some type safety at develop time (like jsdoc also can do) But if I read it right, this helps you to generate OpenAPI spec to validate the api endpoints, to get easy type safety at runtime. See also e.g. https://openapistack.co/docs/openapi-backend/intro/ https://openapistack.co/docs/openapi-backend/intro/ that is also helping to be type safe at runtime. Or Nest can also generate OpenAPI als validation based on it. Only difference is that OpenAPI stack is design first, and Instant is code first. And Nest use decorators and Instant JSDoc. It is more like https://www.npmjs.com/package/swagger-jsdoc https://www.npmjs.com/package/swagger-jsdoc that generate the OpenAPI from JSDoc. 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.
- yashap 3y ago
  It is worth noting there are good options out there to get both compile time type safety and runtime validation using TypeScript. Personally I’m a fan of ts-rest: https://ts-rest.com/ 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.
MrGilbert 3y ago
Side note: "Seems like you put a lot of work into this and as such I'm hesitant to criticize. But what in the world made you think [...]" 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. //Despite the downvotes, I still stand by my opinion. I don't get them, but that's fine.
- codemusings 3y ago
  You're not wrong and I tried to mellow my initial reaction when commenting. I don't feel like I attacked OP though. Getting some outside perspective is important.
mablopoule 3y ago
I don't have an opinion about this particular project, but this just JSDoc, as mentioned in the readme: "Simply write a JSDoc-compliant comment block for a function that represents your API endpoint". 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. [0] https://devhints.io/jsdoc https://devhints.io/jsdoc
deleted 3y ago
[deleted]

keithwhor 3y ago

No not necessarily! I just haven’t written type import support yet; though you’re welcome to help. And no — type safety is applied at the HTTP interface. API consumers need no special library to get all the benefits.

codemusings 3y ago
> And no — type safety is applied at the HTTP interface. So it's basically validation middleware. The HTTP protocol does not define any such thing.
- jfengel 3y ago
  No, and neither does Typescript. One of the biggest weaknesses in Typescript is that it can't validate data across the wire. Which is a major use case for the language. There are various tools for it already, but the JS ecosystem has always been up for yet another framework.
  - r3trohack3r 3y ago
    I hear you, but I don’t think this is necessarily true. It does leave type checking to your parsing logic, but the compiler can give you strong guarantees that you’re being defensive about untrusted structured data. 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 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.
    - madeofpalk 3y ago
      > And “unknown” is basically broken for type narrowing. How? Typescript 4.9 improved it for type narrowing significantly. https://devblogs.microsoft.com/typescript/announcing-typescript-4-9/#in-narrowing 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-experiment/blob/main/output.ts https://github.com/joshhunt/codegen-json-validator-experimen...
      - r3trohack3r 3y ago
        I haven't worked much in typescript over the last 10 months, but last time I tried type narrowing on untrusted data typecast to unknown I ran into a handful of problems documented here: https://github.com/microsoft/TypeScript/issues/25720 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/ http://www.blankenship.io/essays/2022-12-01/ Maybe this has improved.
        madeofpalk 3y ago
        Yes. The main one is `foo in obj` now correctly narrows to `unknown & { foo: unknown }`. This allows you to correctly narrow an unknown to a fully typed object, as my code sample shows :)

9dev 3y ago

Yes, I was wondering about that too. If you put in the effort to parse the docblock into runtime validation, why not pick up the existing utilities to convert TypeScript types into runtime code during the build? That would be much more powerful, with the added benefit of having type safety for all other code, and a familiar syntax for developers.

ushakov 3y ago
…or just use Zod?
- Ciantic 3y ago
  And if you like Zod, you might as well use this: https://github.com/asteasolutions/zod-to-openapi https://github.com/asteasolutions/zod-to-openapi It converts Zod types to OpenAPI specification.
  - vmfunction 3y ago
    Or json schema, this https://www.npmjs.com/package/zod-to-json-schema https://www.npmjs.com/package/zod-to-json-schema Json schema is more universal, and it can be used in .NET, Java, etc.
- 9dev 3y ago
  Yeah, that’s what I was thinking of. There are a few alternatives though, so I referred to existing tooling in general.
- madeofpalk 3y ago
  I don't like writing type definitions with zod's DSL. 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.
  - purplerabbit 3y ago
    I like the sentiment, but you’ve gotta admit that being able to skip the “generation” step has its benefits

ushakov 3y ago

You should check out tsoa, ts-rest, zodios and feTS

w3news 3y ago

It is type safety at runtime. Typescript gives you some type safety at develop time (like jsdoc also can do) But if I read it right, this helps you to generate OpenAPI spec to validate the api endpoints, to get easy type safety at runtime. See also e.g. https://openapistack.co/docs/openapi-backend/intro/ https://openapistack.co/docs/openapi-backend/intro/ that is also helping to be type safe at runtime. Or Nest can also generate OpenAPI als validation based on it. Only difference is that OpenAPI stack is design first, and Instant is code first. And Nest use decorators and Instant JSDoc. It is more like https://www.npmjs.com/package/swagger-jsdoc https://www.npmjs.com/package/swagger-jsdoc that generate the OpenAPI from JSDoc. 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.

yashap 3y ago
It is worth noting there are good options out there to get both compile time type safety and runtime validation using TypeScript. Personally I’m a fan of ts-rest: https://ts-rest.com/ 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.

MrGilbert 3y ago

Side note: "Seems like you put a lot of work into this and as such I'm hesitant to criticize. But what in the world made you think [...]" 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. //Despite the downvotes, I still stand by my opinion. I don't get them, but that's fine.

codemusings 3y ago
You're not wrong and I tried to mellow my initial reaction when commenting. I don't feel like I attacked OP though. Getting some outside perspective is important.

mablopoule 3y ago

I don't have an opinion about this particular project, but this just JSDoc, as mentioned in the readme: "Simply write a JSDoc-compliant comment block for a function that represents your API endpoint". 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. [0] https://devhints.io/jsdoc https://devhints.io/jsdoc

deleted 3y ago

[deleted]