prototypey.org - atproto lexicon typescript toolkit - mirror https://github.com/tylersayshi/prototypey
tylur.dev
new readme
+86
-36
README.md
+86
-36
README.md
···
1
-
# typed-lexicon
2
3
-
> [!WARNING]
4
-
> this project is in the middle of active initial development and not ready for
5
-
> use. there will be updates posted [here](https://bsky.app/profile/tylur.dev)
6
-
> if you'd like to follow along!
7
8
-
9
10
-
this will be a toolkit for writing lexicon json schema's in typescript and
11
-
providing types for lexicon data shape. it will:
12
13
-
- remove boilerplate and improve ergonomics
14
-
- type hint for
15
-
[atproto type parameters](https://atproto.com/specs/lexicon#overview-of-types)
16
-
- infer the typescript type definitions for the data shape to avoid duplication
17
-
and skew
18
-
- methods and a cli for generating json
19
20
-
With each of the above finished, i'll plan to write a `validate` method that
21
-
will be published alongside this that takes any lexicon json definition and
22
-
validates payloads off that.
23
24
-
My working hypothesis: it will be easier to write lexicons in typescript with a
25
-
single api, then validate based off the json definition, than it would be to
26
-
start with validation library types (standard-schema style) and attempt to use
27
-
those as the authoring and validation tools.
28
29
-
**what you'd write:**
30
31
-
```typescript
32
-
const profileNamespace = lx.lexicon("app.bsky.actor.profile", {
33
main: lx.record({
34
key: "self",
35
record: lx.object({
···
70
}
71
```
72
73
-
---
74
75
-
<p align="center">
76
-
<a href="https://github.com/tylersayshi/prototypey/blob/main/.github/CODE_OF_CONDUCT.md" target="_blank"><img alt="🤝 Code of Conduct: Kept" src="https://img.shields.io/badge/%F0%9F%A4%9D_code_of_conduct-kept-21bb42" /></a>
77
-
<a href="https://github.com/tylersayshi/prototypey/blob/main/LICENSE.md" target="_blank"><img alt="📝 License: MIT" src="https://img.shields.io/badge/%F0%9F%93%9D_license-MIT-21bb42.svg" /></a>
78
-
<img alt="💪 TypeScript: Strict" src="https://img.shields.io/badge/%F0%9F%92%AA_typescript-strict-21bb42.svg" />
79
-
</p>
80
81
-
## Usage
82
83
-
tbd
84
85
-
## Development
86
87
-
See [`.github/CONTRIBUTING.md`](./.github/CONTRIBUTING.md), then
88
-
[`.github/DEVELOPMENT.md`](./.github/DEVELOPMENT.md). Thanks! 💖
89
90
-
<!-- You can remove this notice if you don't want it 🙂 no worries! -->
91
92
> 💝 This package was templated with
93
> [`create-typescript-app`](https://github.com/JoshuaKGoldberg/create-typescript-app)
94
> using the [Bingo framework](https://create.bingo).
···
1
+
# prototypey
2
3
+
A (soon-to-be) fully-featured sdk for developing lexicons with typescript.
4
5
+
## Installation
6
7
+
```bash
8
+
npm install prototypey
9
+
```
10
+
11
+
## Usage
12
13
+
Prototypey provides both a TypeScript library for authoring lexicons and a CLI for code generation.
14
15
+
### Authoring Lexicons
16
17
+
Use the library to author type-safe lexicon schemas in TypeScript:
18
19
+
**what you'll write:**
20
21
+
```ts
22
+
const lex = lx.lexicon("app.bsky.actor.profile", {
23
main: lx.record({
24
key: "self",
25
record: lx.object({
···
60
}
61
```
62
63
+
### CLI Commands
64
65
+
The `prototypey` package includes a CLI with two main commands:
66
67
+
#### `gen-inferred` - Generate TypeScript from JSON schemas
68
69
+
```bash
70
+
prototypey gen-inferred <outdir> <schemas...>
71
+
```
72
73
+
Reads ATProto lexicon JSON schemas and generates TypeScript types.
74
75
+
**Example:**
76
77
+
```bash
78
+
prototypey gen-inferred ./generated/inferred ./lexicons/**/*.json
79
+
```
80
81
+
#### `gen-emit` - Emit JSON schemas from TypeScript
82
+
83
+
```bash
84
+
prototypey gen-emit <outdir> <sources...>
85
+
```
86
+
87
+
Extracts JSON schemas from TypeScript lexicon definitions.
88
+
89
+
**Example:**
90
+
91
+
```bash
92
+
prototypey gen-emit ./lexicons ./src/lexicons/**/*.ts
93
+
```
94
+
95
+
### Typical Workflow
96
+
97
+
1. Author lexicons in TypeScript using the library
98
+
2. Emit JSON schemas with `gen-emit` for runtime validation
99
+
100
+
**Recommended:** Add as a script to your `package.json`:
101
+
102
+
```json
103
+
{
104
+
"scripts": {
105
+
"lexicon:emit": "prototypey gen-emit ./schemas ./src/lexicons/**/*.ts"
106
+
}
107
+
}
108
+
```
109
+
110
+
Then run:
111
+
112
+
```bash
113
+
npm run lexicon:emit
114
+
```
115
+
116
+
## State of the Project
117
+
118
+
**Done:**
119
+
120
+
- Full atproto spec lexicon authoring with in IDE docs & hints for each attribute (ts => json)
121
+
- CLI generates json from ts definitions
122
+
- CLI generates ts from json definitions
123
+
- Inferrance of valid type from full lexicon definition
124
+
- the really cool part of this is that it fills in the refs from the defs all at the type level
125
+
126
+
**TODO/In Progress:**
127
+
128
+
- Library art! Please reach out if you'd be willing to contribute some drawings or anything!
129
+
- Runtime validation using [@atproto/lexicon](https://www.npmjs.com/package/@atproto/lexicon)
130
+
- this will be hard to get correct, I'm weary of loading all of the json in a project's lexicons into js memory and would like to run benchmarks and find the best way to get this right.
131
+
- The CLI needs more real world use and mileage. I expect bugs and weird behavior in this initial release (sorry).
132
+
133
+
## Disclaimer:
134
+
135
+
I'm considering how to use the json for validation (there will likely be some lazy-loading). For the cli,
136
+
files may need to adopt a convention so it's easy to determine what is an `lx.lexicon` and then generate out it's json and export it as a validator that lazy loads json to validate. (these are just ideas right now, but I want to share where we are now :)
137
+
138
+
Please give any and all feedback. I've not really written many lexicons much myself yet, so this project is at a point of "well I think this makes sense" 😂. Both the [issues page](https://github.com/tylersayshi/prototypey/issues) and [discussions](https://github.com/tylersayshi/prototypey/discussions) are open and ready for y'all 🙂.
139
+
140
+
<small>
141
> 💝 This package was templated with
142
> [`create-typescript-app`](https://github.com/JoshuaKGoldberg/create-typescript-app)
143
> using the [Bingo framework](https://create.bingo).
144
+
</small>