bterlson

Hey, nice work on openapi-code-generator, its output is very nice. I think you could probably package it up as a TypeSpec emitter without too much difficulty, by emitting OpenAPI and feeding it to your generator. I am doing a similar thing for a Kiota emitter I'm working on. We recently added an API to get the OpenAPI as a JS object which may be of help in this quest:

https://typespec.io/docs/libraries/openapi3/reference/js-api...

I answered in more detail in another comment, but we actually tried this first, and couldn't make it work for the kinds of complex APIs we deal with in Azure. But, it worked great for simple APIs, and I hope someone releases such a tool at some point.

It's LSP, and we also have a VS extension in the marketplace.

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!

Hey, author here. Right now we don't have any streaming or eventing support, but I am working on it as we speak. My first goal is to support describing SSE and JSONL HTTP streaming endpoints, but I want to work toward an AsyncAPI emitter as a peer for our OpenAPI emitter.

If you use the fetch API you can get a readable stream and party on without too much difficulty. You can also implement a transform stream in ~10SLOC that will make the reader vend parsed JSON objects and can be reused easily.

I agree, but SSE is a more complex protocol that requires additional handling on both client and server, with capabilities that may not be relevant for your use case (multiple event types, event id). For JS clients and JS servers it is not particularly onerous to implement, but for other ecosystems can require a fair bit of code. JSONL streaming is very easy to implement on both ends, so all else aside I think would be preferred if all you really want to do is stream JSON values.

Great comparison. Would love to see http response streaming added to the mix. I think a lot of use cases involving finite streams sent from server to client can be handled by the server streaming JSONL in the response. I tend to prefer this over SSE for finite data streams.

This is a great question. We think OpenAPI is great and TypeSpec is a great way to write OpenAPI, but OpenAPI has some challenges generating high quality, language ideomatic code for complex services. Generating code straight from TypeSpec can drive better codegen in some cases such as the one you mention, especially when combined with custom libraries and emitters. Incidentally, this is how we are creating many client libraries for Azure services.

That said, these are not opposing choices really, or a bridge to anything. OpenAPI works great for probably most http services, has a huge ecosystem, and enjoys wide support across the industry so I'd expect many folks to continue to leverage our OpenAPI emitter to take advantage of that.

In general we don't limit ourselves to things which can be trivially compiled to OpenAPI but try to be super general purpose. We support protobuf and intend to support more protocols going forward, and also have experimented with generating other things like JSON RPC, ORMs, db migrations, etc.

Thank you! We take most of our inspiration from TypeScript and sometimes C#, but I agree that gql demonstrates the value of terse, highly readable specs quite nicely.

Since there's a lot of show and tell going on, I'll jump in too I suppose.

I work on a tool in this space called TypeSpec (aka.ms/typespec) that aims to address some of the authoring concerns folks have with OpenAPI. We're a language that feels a lot like TypeScript, with support for high-level features you might be used to in a more typical PL, but compiles to high quality OpenAPI 3.0 you can feed into your existing code/docs generation pipeline. You can see this in action on our playground: https://cadlplayground.z22.web.core.windows.net. We also support protobuf and (once my PR gets merged) JSON Schema targets.

We're not yet to beta (obviously, no website even) but we're hoping to get there relatively soon. Happy to hear any thoughts, especially from folks using OpenAPI.

The current speed of iteration means you get updates in smaller batches rather than more throughput. Still important, but it's not like we're letting proposals bake less. Note how so far we've only gotten two big new features post-ES6 - async functions and async generators. Further, some features (e.g. decorators, bind operator) have had babel plugins for years and yet hasn't shipped in a spec.

Babel has a lot of plugins, and hopefully people don't have to learn all of them. How many people use stage-0 plugins for bind operator or do expressions?

You're right that Babel (and TypeScript!) implement features earlier than they land in the spec, but at least TS does so only when it's almost for sure going to make it in (around stage 3) and people probably shouldn't be using stage 0-2 plugins for anything but experiments, IMO.

I think it's good to note that this proposal is not far along the process. Pattern matching, if it clears TC39 (a tall order, to be honest), won't land in a spec for half a decade at least I would bet.

So, keep the feedback coming, and don't worry that you'll have to learn this syntax tomorrow. It's still very early, and I wouldn't be surprised if there are at least a couple major revisions before anything like this lands in ECMAScript.

Yes, this is by no means normative! Nothing will happen without a long discussion and consensus among dozens of people. TC39 has a meeting later this month where I imagine this will discussed in more detail.

Also, assuming we can't use flatten, I am sure we will land on a reasonable name that is not smoosh.

More strongly, the draft is incomplete by its very nature. If you care about having only complete and ratified standards, do not use the GitHub snapshot. Use the official versions hosted on ECMA's website (https://www.ecma-international.org/memento/TC39-M.htm).

If anyone has any data on this topic I would love to hear and understand it!

Official standards are moved to ECMA's website. E.g. ES2017 is here: https://www.ecma-international.org/publications/files/ECMA-S.... The GitHub site is mostly targeted toward implementers who are always working off the latest draft for new spec or implementation work.

I hear ya. Once the spec is finalized for the year I produce a change log. I have done so in between versions before but things tend to be menial and/or change a lot and it was a lot of work for not too much gain. Willing to go back on this. You can always watch the commits go in here though: https://github.com/tc39/ecma262/commits/master.

There are many proposals sitting at the cusp of the stage 3 to stage 4 transition. There will be a couple more meaty things to make it. I suspect we'll end up with more proposals ready than I have time to integrate into the main spec :)

Probably not ES2018, but 2019 is looking likelier now thanks in part to excellent work by Daniel Ehrenberg (@littledan).

I will be writing the ES2018 intro prose around when we send ES2018 draft to ECMA for ratification (few months away yet).

Wow, oddly relevant - I've been working on a RegExp implementation in JavaScript using similar techniques (minus vectorization of course, RIP SIMD.js). There is no efficient way in JavaScript to replace many patterns (e.g. a list of sentence fragments with optional whitespace, capitalization, pluralization, etc.) against a large document where the replacement requires metadata about the subpattern that was matched (e.g. to replace a term with a link to the term's definition).

I wonder if I should switch gears and try to write a native Node module for this instead. This looks really great.

I'm sorry I missed your comment earlier, but hopefully replying later is better than never :)

ChakraCore is cross-platform now so we no longer get the benefit of a single platform. However back when we were only Windows there were advantages, certainly, if only because all the work spent getting everything working on different OSes can instead be invested in improving performance.

Agreed, Octane was good as far as benchmarks go but you have to balance with a much larger set of benchmarks and always ground your work in real-world scenarios (something we focused heavily on from day one e.g. when we realized having an interpreter really helps startup on lots of real-world apps but doesn't do much for Octane score).

That said, FWIW I think Edge/Chakra gets the crown on Windows!

(I work on Chakra)

Thanks for your thoughts :) We've updated the roadmap[1] to call out that JIT and more platforms are coming in future iterations.

1: https://github.com/Microsoft/ChakraCore/wiki/Roadmap

The goal is for all of ChakraCore to be broadly cross-platform eventually, including the JIT, and including many more platforms than just Ubuntu x64. The roadmap reflects our next steps for the next 6 months but is not the entire journey.

Disclosure: I work on Chakra