danabra.mov
An experimental TypeSpec syntax for Lexicon
ok
+18
-180
-44
CLAUDE.md
-44
CLAUDE.md
···
1
-
you're working on a TypeSpec emitter for atproto lexicons. you have these commands: `pnpm run build` builds the example (you can inspect the generated lexicons in the `packages/example/lexicon`) and `pnpm test` runs tests (they are in `packages/emitter/test/`).
2
-
3
-
what i want you to do is to gradually keep adding features to typelex so that in the end it's possible to express all Lexicon code with that language. you have the following resources:
4
-
5
-
- read `SYNTAX.md`!!! it's the main guideline
6
-
7
-
- `../typespec/packages` has a bunch of other emitters (so you can check how they're implemented and common patterns)
8
-
9
-
- `../typespec/website/src/content` has typescpec docs (which you might find very useful)
10
-
11
-
- `../atproto-website/src/app/[locale]/specs/lexicon` contains lexicon spec (where we want to reach feature parity), and most importantly
12
-
13
-
- `test/scenarios/atproto/output` contains a TON of lexicon definitions which i want you to translate to typespec one by one. for each atproto lexicon you're porting, your job is to create the corresponding "`input`s" for them (and fix bugs or add missing features along the way).
14
-
15
-
the goal is to end up with a language that feels nice and concise, not some weird interop thing. so try to do things "typespec" way as you go through each lexicon. and try to respect atproto too. this should feel like a *language for atproto*. consider whether your design is elegant. and make sure to look at other typespec emitters for design ideas!
16
-
17
-
remember NOT to change the output to fit the input -- your job is to make the input MATCH the output. if some lexicon is too hard, you can give up on it and try another one. good luck!
18
-
19
-
the workflow is: pick some new lexicons, create the input files, figure out missing features / bugs, and try to get tests to pass. repeat. when you make nontrivial progress, you'll want to prepare a commit.
20
-
21
-
before you want to make a commit, make sure `pnpm test` and `pnpm run build` passes and, ideally, inspect the `example` app output (and maybe add the features you've just implemented there for parity). then stop and notify me.
22
-
23
-
ps. be mindful of the code style. we only put decorators on same line if it's `@required` alone; otherwise, put each on newline and add a newline after. see existing files for a hint.
24
-
25
-
good luck! i believe in you
26
-
27
-
28
-
---
29
-
30
-
whenever you get stuck (try `npm test`) because you don't have a convention for how to define some pattern yetm i want you to read these sources
31
-
32
-
- `../typespec/packages` has a bunch of other emitters (so you can check how they're implemented and common patterns)
33
-
34
-
- `../typespec/website/src/content` has typescpec docs (which you might find very useful)
35
-
36
-
- `../atproto-website/src/app/[locale]/specs/lexicon` contains lexicon spec
37
-
38
-
and ultrathink about what's the most appropriate way to define defs like you want would be in this typespec translation of atproto. you can research these sources for what feels most idiomatic to define that syntax, and how to make
39
-
the formatter understand that convention and emit the JSON we want.
40
-
41
-
also note that you can always look at generated atproto lexicons in ../atproto/lexicons -- use these!! look at the TS types there for corresponding
42
-
models to inspire how you represent things in tsp syntax.
43
-
44
-
- read `SYNTAX.md`!!! it's the main guideline
+8
-2
DOCS.md
+8
-2
DOCS.md
···
1
-
# TypeSpec to Lexicon Reference
1
+
# Typelex Docs
2
+
3
+
This guide maps atproto Lexicon JSON syntax to typelex (a [TypeSpec](https://typespec.io/) emitter). It assumes you're familiar with Lexicon and want to understand how to express it in TypeSpec. Consult [TypeSpec docs](https://typespec.io/) on details of TypeSpec syntax.
2
4
3
-
This guide maps atproto Lexicon JSON syntax to TypeSpec (typelex). It assumes you're familiar with Lexicon and want to understand how to express it in TypeSpec.
5
+
Btw, this page was mostly written by Claude. I hope it's mostly correct and comprehensible.
6
+
7
+
## Playground
8
+
9
+
Go to https://typelex-playground.pages.dev/ to play with a bunch of lexicons.
4
10
5
11
## Quick Start
6
12
LICENSE
LICENSE.md
LICENSE
LICENSE.md
+8
-132
README.md
+8
-132
README.md
···
1
1
# typelex
2
2
3
-
> TypeSpec-based IDL for ATProto Lexicons
4
-
5
-
typelex allows you to define [ATProto](https://atproto.com) lexicons using [TypeSpec](https://typespec.io), providing type safety, better tooling, and a more ergonomic syntax compared to writing raw JSON.
6
-
7
-
## Features
8
-
9
-
- 🔧 **Type-safe** - Leverage TypeSpec's type system to catch errors at compile time
10
-
- 📝 **Better DX** - Write lexicons with IDE support, auto-completion, and inline documentation
11
-
- 🎯 **ATProto-compliant** - Generates valid lexicon JSON that works with any ATProto implementation
12
-
- 🚀 **Simple** - No complex tooling or configuration required
13
-
14
-
## Quick Start
15
-
16
-
```bash
17
-
# Install TypeSpec compiler
18
-
npm install -g @typespec/compiler
19
-
20
-
# Install typelex emitter
21
-
npm install --save-dev @typelex/emitter
22
-
```
23
-
24
-
Create a `main.tsp` file:
25
-
26
-
```typescript
27
-
namespace app.bsky.feed;
28
-
29
-
@doc("A post in the feed")
30
-
model Post {
31
-
@doc("Post content")
32
-
text: string;
33
-
34
-
@doc("Creation timestamp")
35
-
createdAt: utcDateTime;
36
-
37
-
@doc("Languages the post is written in")
38
-
langs?: string[];
39
-
}
40
-
```
41
-
42
-
Add a `tspconfig.yaml`:
43
-
44
-
```yaml
45
-
emit:
46
-
- "@typelex/emitter"
47
-
options:
48
-
"@typelex/emitter":
49
-
output-dir: "./lexicons"
50
-
```
51
-
52
-
Compile to lexicon JSON:
53
-
54
-
```bash
55
-
tsp compile .
56
-
```
57
-
58
-
## Output
59
-
60
-
typelex generates standard ATProto lexicon files:
61
-
62
-
```json
63
-
{
64
-
"lexicon": 1,
65
-
"id": "app.bsky.feed.post",
66
-
"defs": {
67
-
"main": {
68
-
"type": "record",
69
-
"key": "tid",
70
-
"record": {
71
-
"type": "object",
72
-
"properties": {
73
-
"text": {
74
-
"type": "string",
75
-
"description": "Post content"
76
-
},
77
-
"createdAt": {
78
-
"type": "string",
79
-
"format": "datetime",
80
-
"description": "Creation timestamp"
81
-
},
82
-
"langs": {
83
-
"type": "array",
84
-
"items": {
85
-
"type": "string"
86
-
},
87
-
"description": "Languages the post is written in"
88
-
}
89
-
},
90
-
"required": ["text", "createdAt"]
91
-
}
92
-
}
93
-
}
94
-
}
95
-
```
96
-
97
-
## Examples
98
-
99
-
See the [`packages/example`](./packages/example) directory for a complete example project.
100
-
101
-
## Development
102
-
103
-
```bash
104
-
# Clone the repository
105
-
git clone https://github.com/yourusername/typelex.git
106
-
cd typelex
107
-
108
-
# Build the emitter
109
-
pnpm install
110
-
pnpm run build
3
+
An experimental TypeSpec emitter for Lexicon.
111
4
112
-
# Try the example
113
-
pnpm run example
114
-
```
5
+
See https://typelex.pages.dev/
115
6
116
-
## Current Status
7
+
## Playground
117
8
118
-
⚠️ **Early Development** - typelex currently supports basic record types. Support for queries, procedures, and subscriptions is coming soon.
9
+
See https://typelex-playground.pages.dev/
119
10
120
-
### Supported
11
+
## Reference
121
12
122
-
- ✅ Record types
123
-
- ✅ Basic types (string, boolean, integer, datetime)
124
-
- ✅ Arrays and objects
125
-
- ✅ Optional fields
126
-
- ✅ Documentation
13
+
See [DOCS.md](./DOCS.md)
127
14
128
-
### Coming Soon
15
+
## License
129
16
130
-
- 🚧 XRPC queries and procedures
131
-
- 🚧 Subscriptions
132
-
- 🚧 Union types
133
-
- 🚧 ATProto-specific validations (maxGraphemes, etc.)
134
-
- 🚧 Blob references
17
+
MIT
135
18
136
-
## Contributing
137
-
138
-
Contributions are welcome! Please feel free to submit a Pull Request.
139
-
140
-
## License
141
-
142
-
MIT