After seeing Dan Abramov make typelex, I found myself wanting something analogous that was fully in typescript.
![import "@typlex/emitter";
namespace app.bsky.embed.external {
@doc("A representation of some externally linked content (eg, a URL and 'card'), embedded in a Bluesky record (eg, a post).")
model Main {
external: External;
}
model External {
@lexFormat("uri")
uri: string;
title: string;
description: string;
@blobAccept(#["image/*"])
@blobMaxSize(1000000)
thumb?: bytes;
}
model View {
external: ViewExternal;
}
model ViewExternal {
@lexFormat("uri")
uri: string;
title: string;
description: string;
@lexFormat("uri")
thumb?: string;
}
}](https://cdn.bsky.app/img/feed_fullsize/plain/did:plc:fpruhuo22xkm5o7ttr2ktxdo/bafkreihxwa4kky4xiwehkygl52yc7ffgpgfa45vwot5fohih3tufv3mk4i)
Atproto Lexicon definitions serve their purpose of flexibly defining schemas for an open social network. That said, they're not particularly optimized to be concise or very easily read by humans. Readability is subjective and personal, so my guess is that other atproto devs will prefer to read similarly to what works best for me.
I have a bit of a personal theory that typescript is the best language for anything resembling config or type authoring, especially when those can be re-used by other typescript code. Typescript has a whole host of developer tooling and in-editor support that can be easily built on top of for delightful developer experiences. From autocomplete, to jsdoc, versioning updates, and adding runtime code in place... it all just works so nicely together while feeling very familiar to app devs.
None of these are a given with any other DSL or json.
The Idea
reduce boilerplate
provide typehinting and in-editor documentation links
support runtime validation from schemaDefinition.validate(...) (where schemaDefinition is just the variable where your lexicon is defined)
infer the actual type of a lexicon instance from the initial definition (including intelligent replacement of #ref fields)
give a CLI that supports projects that use prototypey for authoring AND projects that author any other way that want prototypey's validation and type inference support. (e.g. you could use typelex.org for authoring and prototypey.org for validation and type inference)
How?
The implementation of the core library is quite light. The entire runtime implementation is in this single file, which is mostly just comments: https://github.com/tylersayshi/prototypey/blob/main/packages/prototypey/core/lib.ts
Reduce Boilerplate
This is also done well with mlf.lol and typelex.org and it's just super satisfying to see lines written cut in half.
Typehints and In-Editor Documentation
Bringing in-editor documentation to typescript developers is a big reason prototypey exists:
The atproto.com docs are quite good, but a dense read to attempt all at once. Linking out to the docs from each member (e.g. lx.record or lx.blob) is the most convenient way I can think to learn how to write lexicons, as you are writing them. Afterall, developers love learning by doing.
Runtime Validation
This is a problem well handled by @atproto/lexicon so all prototypey needs to do is pass the unwrapped json definition into @atproto/lexicon and call it a day 🙌.
Type Inference
This was a big personal reason I was attracted to building prototypey. I really like type level programming. It's a uniquely functional and quirky little language all on its own. And now, we get really nice inference of what lexicon types are actually supposed to be at runtime based off our much larger lexicon definition:
and then this get's really cool when we fill in local refs:
CLI
The convert the typescript definitions into json for finalizing we have a cli that supports emit like: prototypey gen-emit ./schemas ./src/lexicons/**/*.ts and it will turn json into typescript (for non-prototypey authored lexicons) with prototypey gen-from-json ./src/lexicons ./lexicons/**/*.json.
Try it out!
Hopefully prototypey can exist as a way to help atproto devs learn and maintain lexicon definitions. Even if your app isn't creating lexicons, maybe you could use the toolset for convenient validation and type inference!
docs: https://github.com/tylersayshi/prototypey
the playground: https://prototypey.org