WHEREAS, AT Protocol code generation is very important to the ecosystem.

  • Every record in every repository is defined by a lexicon.

  • Interacting with those lexicons requires types and code snippets, ideally through some kind of code generation.

  • Every minute spent by a developer trying to make codegen tools work is a minute they’re not working on their application.

  • Worse yet, they might write all of their types manually.

WHEREAS, the state of AT Protocol code generation is in absolute shambles. 

  • The first-party Bluesky Go and TypeScript type generation tools work well within their respective repositories. Using them outside the atproto and indigo repositories involves horrible, horrible hacks.

  • Hey, remember that there’s a lexicon resolution spec that can be used to canonically resolve NSIDs into their records with DNS? No? Yeah, neither do the authors of existing lexicon generation tools; to my knowledge they all take JSON files as input.

  • All existing codegen tools exist in isolation. If a developer is working with, say, a Go backend and a TypeScript frontend, they must install two tools, learn two sets of command line flags, and set up two processes in their Makefile. This wastes time and gets developers caught up in minutiae.

  • All existing codegen tools exist exclusively on the command-line. There exists no online playground where developers can preview code generation in a variety of languages.

AND THEREFORE, the following shall be created:

  • A unified code generation tool, with an initial target of type generation in TypeScript, Go, and Rust.

  • The initial target can be feature parity with existing codegen tools (often by borrowing code from them) before continuing to evolve and blowing them out of the water.

  • The tool should make use of protocol-compliant lexicon resolution.

  • The tool should also be capable of generating documentation in a variety of formats (HTML, Markdown).

  • The tool should be accessible both through the command line and through an online sandbox.

Where Streamplace comes in

Streamplace needs high-quality code generation for Go, TypeScript, and Rust as much as the rest of the ecosystem does. But also, while I think Streamplace is an important project, I’m sad that we haven’t contributed many tools or libraries back to the community. We’re one of a precious few funded entities in the ATProto; but our community tooling contributions are basically just OATProxy. (Graze is blowing us out of the water!)

So, we’ve contracted @juli.ee, the creator of the best, most widely-used atproto developer tool, to lead the project and create the initial version.

Where you come in

  • If you’re a grant-writing entity, please support the project! I posit this is in the top-five most needed things in the ecosystem.

  • If you’re a developer, especially a developer in one of the languages we haven’t listed yet, please get in touch! Over the long term, a properly-maintained tool would probably have a maintainer for each language to, at minimum, keep the generated code up-to-date with latest advancements in each language and SDK.

  • We don't have a name for the thing yet! The floor is official open for suggestions. Hop in the Streamplace Discord to help out!

Unanswered Questions

  • Should this tool generate types locally for every single type you want to use in your project? Or should it pull down other included projects as libraries? Should this behavior be configurable as a command-line option?

  • Go devs prefer to write their codegen in Go, Rust in Rust, TypeScript in TypeScript. I’d like for there to be one tool that generates them all. This doesn’t preclude using a variety of languages when appropriate: this isn’t Streamplace, it doesn’t need to be a single binary.

    • Potentially, a Docker image containing all the relevant language runtimes could be shipped.

    • Or language-specific code generation routines could be compiled to WASM and deployed online that way.

  • What's it called???