tylur.dev
prototypey.org - atproto lexicon typescript toolkit - mirror https://github.com/tylersayshi/prototypey
update description and include readme
+153
-154
+1
-144
README.md
+1
-144
README.md
···
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({
26
-
displayName: lx.string({ maxLength: 64, maxGraphemes: 64 }),
27
-
description: lx.string({ maxLength: 256, maxGraphemes: 256 }),
28
-
}),
29
-
}),
30
-
});
31
-
```
32
-
33
-
**generates to:**
34
-
35
-
```json
36
-
{
37
-
"lexicon": 1,
38
-
"id": "app.bsky.actor.profile",
39
-
"defs": {
40
-
"main": {
41
-
"type": "record",
42
-
"key": "self",
43
-
"record": {
44
-
"type": "object",
45
-
"properties": {
46
-
"displayName": {
47
-
"type": "string",
48
-
"maxLength": 64,
49
-
"maxGraphemes": 64
50
-
},
51
-
"description": {
52
-
"type": "string",
53
-
"maxLength": 256,
54
-
"maxGraphemes": 256
55
-
}
56
-
}
57
-
}
58
-
}
59
-
}
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
-
---
141
-
142
-
> 💝 This package was templated with
143
-
> [`create-typescript-app`](https://github.com/JoshuaKGoldberg/create-typescript-app)
144
-
> using the [Bingo framework](https://create.bingo).
1
+
./packages/prototypey/README.md
+1
-1
package.json
+1
-1
package.json
···
2
2
"name": "prototypey-monorepo",
3
3
"version": "0.0.0",
4
4
"private": true,
5
-
"description": "Type-safe lexicon inference for ATProto schemas",
5
+
"description": "atproto lexicon typescript toolkit",
6
6
"repository": {
7
7
"type": "git",
8
8
"url": "git+https://github.com/tylersayshi/prototypey.git"
+1
-1
packages/cli/README.md
+1
-1
packages/cli/README.md
···
42
42
- Reads ATProto lexicon JSON schemas
43
43
- Generates TypeScript types that match the schema structure
44
44
- Organizes output files by namespace (e.g., `app.bsky.feed.post` → `app/bsky/feed/post.ts`)
45
-
- Provides type-safe interfaces for working with lexicon data
45
+
- Provides typescript definitions of the lexicons for inference and later: validation
46
46
47
47
### `gen-emit`
48
48
+1
-3
packages/cli/src/index.ts
+1
-3
packages/cli/src/index.ts
···
9
9
10
10
const prog = sade("prototypey");
11
11
12
-
prog
13
-
.version(pkg.version)
14
-
.describe("Type-safe lexicon inference and code generation");
12
+
prog.version(pkg.version).describe("atproto lexicon typescript toolkit");
15
13
16
14
prog
17
15
.command("gen-inferred <outdir> <schemas...>")
+144
packages/prototypey/README.md
+144
packages/prototypey/README.md
···
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
+
**what you'll write:**
18
+
19
+
```ts
20
+
const lex = lx.lexicon("app.bsky.actor.profile", {
21
+
main: lx.record({
22
+
key: "self",
23
+
record: lx.object({
24
+
displayName: lx.string({ maxLength: 64, maxGraphemes: 64 }),
25
+
description: lx.string({ maxLength: 256, maxGraphemes: 256 }),
26
+
}),
27
+
}),
28
+
});
29
+
```
30
+
31
+
**generates to:**
32
+
33
+
```json
34
+
{
35
+
"lexicon": 1,
36
+
"id": "app.bsky.actor.profile",
37
+
"defs": {
38
+
"main": {
39
+
"type": "record",
40
+
"key": "self",
41
+
"record": {
42
+
"type": "object",
43
+
"properties": {
44
+
"displayName": {
45
+
"type": "string",
46
+
"maxLength": 64,
47
+
"maxGraphemes": 64
48
+
},
49
+
"description": {
50
+
"type": "string",
51
+
"maxLength": 256,
52
+
"maxGraphemes": 256
53
+
}
54
+
}
55
+
}
56
+
}
57
+
}
58
+
}
59
+
```
60
+
61
+
you could also access the json definition with `lex.json()`.
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
+
---
141
+
142
+
> 💝 This package was templated with
143
+
> [`create-typescript-app`](https://github.com/JoshuaKGoldberg/create-typescript-app)
144
+
> using the [Bingo framework](https://create.bingo).
+2
-2
packages/prototypey/package.json
+2
-2
packages/prototypey/package.json
···
1
1
{
2
2
"name": "prototypey",
3
-
"version": "0.1.0",
4
-
"description": "Type-safe lexicon inference for ATProto schemas",
3
+
"version": "0.1.1",
4
+
"description": "atproto lexicon typescript toolkit",
5
5
"repository": {
6
6
"type": "git",
7
7
"url": "git+https://github.com/tylersayshi/prototypey.git",
+1
-1
packages/site/index.html
+1
-1
packages/site/index.html
+1
-1
packages/site/src/components/Header.tsx
+1
-1
packages/site/src/components/Header.tsx
+1
-1
packages/site/tests/components/Header.test.tsx
+1
-1
packages/site/tests/components/Header.test.tsx