The current state of externals is documented here:
https://tangled.org/@danabra.mov/typelex/blob/main/DOCS.md#external-stubs
Currently, if you want to refer to a Lexicon (which isn't written in Typelex), you can stub it out like
// Empty stub (like .d.ts in TypeScript)
namespace com.atproto.label.defs {
model SelfLabels { }
}
It's enough to have the namespaces and the model names. (And maybe @token decorators for tokens?) You don't need to fill in the entire thing.
Still, these stubs are tedious to create by hand. Something feels off about the workflow. You also don't actually want them to appear as the output JSON. Instead, you want the original Lexicon JSON for them in your lexicons/ folder.
This is very similar to the concept of "externals" in JavaScript bundlers.
I think an ideal workflow might look closer to this:
- You check in some external lexicons into
lexicons/manually. Maybe you even use some tool that does it by nsid via Lexicon resolution. For example, https://jsr.io/@lpm/cli does this vialexicons.json. - Typelex automatically generates a file with
.tspstubs for those Lexicons from JSON. Maybe this file is gitignore'd. It doesn't need to actually translate them because simply declaring eachnamespaceper JSON file and amodelper each of itsdefsshould be sufficient. This makes them appear in IntelliSense, etc. - Typelex also knows to not include those external Lexicons into the output. I.e. it shouldn't write them to
lexicons/since they are external.
Key questions:
- This requires Typelex itself to have this logic somewhere. So it's maybe no longer just an emitter but a higher-level tool. A CLI (https://tangled.org/@danabra.mov/typelex/issues/4) seems like an obvious place to do that.
- Whether externals are configured or inferred. How do you know something is an external?
- If it's explicit, where is it configured? Is this Typelex configuration or something more general? Should Typelex adopt
lexicons.jsonfrom https://jsr.io/@lpm/cli? - If it's inferred, what would it be inferred based on? We probably shouldn't infer it based on which namespaces are "missing" since those could just be typos. It's also not necessarily the case that you only work in one primary namespace. I think inferring might just be too confusing.
- If
.tspexterns get generated, how do they become available to the compiler? Is the generated file somewhere in your repo? Where do we put it? Is it continuously updated or is there a command to do that? It can't just be done at compilation because you also want the LSP to be aware of external lexicons. Maybe it's a command to the CLI.
- If it's explicit, where is it configured? Is this Typelex configuration or something more general? Should Typelex adopt
This should be easy if the emitter knows they are externals. Then it can know just not to emit them. Maybe there could be an
@externaldecorator to mark them. Then the stubs generated by the CLI could have that decorator.