prototypey.org - atproto lexicon typescript toolkit - mirror https://github.com/tylersayshi/prototypey
jsdoc generate everything from https://atproto.com/specs/lexicon
+235
-12
+235
-12
src/lib.ts
+235
-12
src/lib.ts
···
24
24
| "procedure"
25
25
| "subscription";
26
26
27
+
/**
28
+
* Common options available for lexicon items.
29
+
* @see https://atproto.com/specs/lexicon#string-formats
30
+
*/
27
31
interface LexiconItemCommonOptions {
32
+
/** Indicates this field must be provided */
28
33
required?: boolean;
34
+
/** Indicates this field can be explicitly set to null */
29
35
nullable?: boolean;
30
36
}
31
37
38
+
/**
39
+
* Base interface for all lexicon items.
40
+
* @see https://atproto.com/specs/lexicon#overview-of-types
41
+
*/
32
42
interface LexiconItem extends LexiconItemCommonOptions {
33
43
type: LexiconType;
34
44
}
35
45
46
+
/**
47
+
* Definition in a lexicon namespace.
48
+
* @see https://atproto.com/specs/lexicon#lexicon-document
49
+
*/
36
50
type Def = {
37
51
type: LexiconType;
38
52
};
39
53
54
+
/**
55
+
* Lexicon namespace document structure.
56
+
* @see https://atproto.com/specs/lexicon#lexicon-document
57
+
*/
40
58
interface LexiconNamespace {
59
+
/** Namespaced identifier (NSID) for this lexicon */
41
60
id: string;
61
+
/** Named definitions within this namespace */
42
62
defs: {
43
63
[name: string]: Def;
44
64
};
45
65
}
46
66
67
+
/**
68
+
* String type options.
69
+
* @see https://atproto.com/specs/lexicon#string
70
+
*/
47
71
interface StringOptions extends LexiconItemCommonOptions {
72
+
/**
73
+
* Semantic string format constraint.
74
+
* @see https://atproto.com/specs/lexicon#string-formats
75
+
*/
48
76
format?:
49
-
| "at-identifier"
50
-
| "at-uri"
51
-
| "cid"
52
-
| "datetime"
53
-
| "did"
54
-
| "handle"
55
-
| "nsid"
56
-
| "tid"
57
-
| "record-key"
58
-
| "uri"
59
-
| "language";
77
+
| "at-identifier" // Handle or DID
78
+
| "at-uri" // AT Protocol URI
79
+
| "cid" // Content Identifier
80
+
| "datetime" // Timestamp (UTC, ISO 8601)
81
+
| "did" // Decentralized Identifier
82
+
| "handle" // User handle identifier
83
+
| "nsid" // Namespaced Identifier
84
+
| "tid" // Timestamp Identifier
85
+
| "record-key" // Repository record key
86
+
| "uri" // Generic URI
87
+
| "language"; // IETF BCP 47 language tag
88
+
/** Maximum string length in bytes */
60
89
maxLength?: number;
90
+
/** Minimum string length in bytes */
61
91
minLength?: number;
92
+
/** Maximum string length in Unicode graphemes */
62
93
maxGraphemes?: number;
94
+
/** Minimum string length in Unicode graphemes */
63
95
minGraphemes?: number;
96
+
/** Hints at expected values, not enforced */
64
97
knownValues?: string[];
98
+
/** Restricts to an exact set of string values */
65
99
enum?: string[];
100
+
/** Default value if not provided */
66
101
default?: string;
102
+
/** Fixed, unchangeable value */
67
103
const?: string;
68
104
}
69
105
106
+
/**
107
+
* Boolean type options.
108
+
* @see https://atproto.com/specs/lexicon#boolean
109
+
*/
70
110
interface BooleanOptions extends LexiconItemCommonOptions {
111
+
/** Default value if not provided */
71
112
default?: boolean;
113
+
/** Fixed, unchangeable value */
72
114
const?: boolean;
73
115
}
74
116
117
+
/**
118
+
* Integer type options.
119
+
* @see https://atproto.com/specs/lexicon#integer
120
+
*/
75
121
interface IntegerOptions extends LexiconItemCommonOptions {
122
+
/** Minimum allowed value (inclusive) */
76
123
minimum?: number;
124
+
/** Maximum allowed value (inclusive) */
77
125
maximum?: number;
126
+
/** Restricts to an exact set of integer values */
78
127
enum?: number[];
128
+
/** Default value if not provided */
79
129
default?: number;
130
+
/** Fixed, unchangeable value */
80
131
const?: number;
81
132
}
82
133
134
+
/**
135
+
* Bytes type options for arbitrary byte arrays.
136
+
* @see https://atproto.com/specs/lexicon#bytes
137
+
*/
83
138
interface BytesOptions extends LexiconItemCommonOptions {
139
+
/** Minimum byte array length */
84
140
minLength?: number;
141
+
/** Maximum byte array length */
85
142
maxLength?: number;
86
143
}
87
144
145
+
/**
146
+
* Blob type options for binary data with MIME types.
147
+
* @see https://atproto.com/specs/lexicon#blob
148
+
*/
88
149
interface BlobOptions extends LexiconItemCommonOptions {
150
+
/** Allowed MIME types (e.g., ["image/png", "image/jpeg"]) */
89
151
accept?: string[];
152
+
/** Maximum blob size in bytes */
90
153
maxSize?: number;
91
154
}
92
155
156
+
/**
157
+
* Array type options.
158
+
* @see https://atproto.com/specs/lexicon#array
159
+
*/
93
160
interface ArrayOptions extends LexiconItemCommonOptions {
161
+
/** Minimum array length */
94
162
minLength?: number;
163
+
/** Maximum array length */
95
164
maxLength?: number;
96
165
}
97
166
167
+
/**
168
+
* Record type options for repository records.
169
+
* @see https://atproto.com/specs/lexicon#record
170
+
*/
98
171
interface RecordOptions {
172
+
/** Record key strategy: "self" for self-describing or "tid" for timestamp IDs */
99
173
key: "self" | "tid";
174
+
/** Object schema defining the record structure */
100
175
record: { type: "object" };
176
+
/** Human-readable description */
101
177
description?: string;
102
178
}
103
179
180
+
/**
181
+
* Union type options for multiple possible types.
182
+
* @see https://atproto.com/specs/lexicon#union
183
+
*/
104
184
interface UnionOptions extends LexiconItemCommonOptions {
185
+
/** If true, only listed refs are allowed; if false, additional types may be added */
105
186
closed?: boolean;
106
187
}
107
188
189
+
/**
190
+
* Map of property names to their lexicon item definitions.
191
+
* @see https://atproto.com/specs/lexicon#object
192
+
*/
108
193
interface ObjectProperties {
109
194
[key: string]: LexiconItem;
110
195
}
111
196
197
+
/**
198
+
* Resulting object schema with required and nullable fields extracted.
199
+
* @see https://atproto.com/specs/lexicon#object
200
+
*/
112
201
interface ObjectResult<T extends ObjectProperties> {
113
202
type: "object";
203
+
/** Property definitions */
114
204
properties: T;
205
+
/** List of required property names */
115
206
required?: string[];
207
+
/** List of nullable property names */
116
208
nullable?: string[];
117
209
}
118
210
211
+
/**
212
+
* Map of parameter names to their lexicon item definitions.
213
+
* @see https://atproto.com/specs/lexicon#params
214
+
*/
119
215
interface ParamsProperties {
120
216
[key: string]: LexiconItem;
121
217
}
122
218
219
+
/**
220
+
* Resulting params schema with required fields extracted.
221
+
* @see https://atproto.com/specs/lexicon#params
222
+
*/
123
223
interface ParamsResult<T extends ParamsProperties> {
124
224
type: "params";
225
+
/** Parameter definitions */
125
226
properties: T;
227
+
/** List of required parameter names */
126
228
required?: string[];
127
229
}
128
230
231
+
/**
232
+
* HTTP request or response body schema.
233
+
* @see https://atproto.com/specs/lexicon#http-endpoints
234
+
*/
129
235
interface BodySchema {
236
+
/** MIME type encoding (typically "application/json") */
130
237
encoding: "application/json" | (string & {});
238
+
/** Human-readable description */
131
239
description?: string;
240
+
/** Object schema defining the body structure */
132
241
schema?: ObjectResult<ObjectProperties>;
133
242
}
134
243
244
+
/**
245
+
* Error definition for HTTP endpoints.
246
+
* @see https://atproto.com/specs/lexicon#http-endpoints
247
+
*/
135
248
interface ErrorDef {
249
+
/** Error name/code */
136
250
name: string;
251
+
/** Human-readable error description */
137
252
description?: string;
138
253
}
139
254
255
+
/**
256
+
* Query endpoint options (HTTP GET).
257
+
* @see https://atproto.com/specs/lexicon#query
258
+
*/
140
259
interface QueryOptions {
260
+
/** Human-readable description */
141
261
description?: string;
262
+
/** Query string parameters */
142
263
parameters?: ParamsResult<ParamsProperties>;
264
+
/** Response body schema */
143
265
output?: BodySchema;
266
+
/** Possible error responses */
144
267
errors?: ErrorDef[];
145
268
}
146
269
270
+
/**
271
+
* Procedure endpoint options (HTTP POST).
272
+
* @see https://atproto.com/specs/lexicon#procedure
273
+
*/
147
274
interface ProcedureOptions {
275
+
/** Human-readable description */
148
276
description?: string;
277
+
/** Query string parameters */
149
278
parameters?: ParamsResult<ParamsProperties>;
279
+
/** Request body schema */
150
280
input?: BodySchema;
281
+
/** Response body schema */
151
282
output?: BodySchema;
283
+
/** Possible error responses */
152
284
errors?: ErrorDef[];
153
285
}
154
286
287
+
/**
288
+
* WebSocket message schema for subscriptions.
289
+
* @see https://atproto.com/specs/lexicon#subscription
290
+
*/
155
291
interface MessageSchema {
292
+
/** Human-readable description */
156
293
description?: string;
294
+
/** Union of possible message types */
157
295
schema: { type: "union"; refs: readonly string[] };
158
296
}
159
297
298
+
/**
299
+
* Subscription endpoint options (WebSocket).
300
+
* @see https://atproto.com/specs/lexicon#subscription
301
+
*/
160
302
interface SubscriptionOptions {
303
+
/** Human-readable description */
161
304
description?: string;
305
+
/** Query string parameters */
162
306
parameters?: ParamsResult<ParamsProperties>;
307
+
/** Message schema for events */
163
308
message?: MessageSchema;
309
+
/** Possible error responses */
164
310
errors?: ErrorDef[];
165
311
}
166
312
167
313
/**
168
-
* Main API: Create a namespace (lexicon document)
314
+
* Main API for creating lexicon schemas.
315
+
* @see https://atproto.com/specs/lexicon
169
316
*/
170
317
export const lx = {
318
+
/**
319
+
* Creates a null type.
320
+
* @see https://atproto.com/specs/lexicon#null
321
+
*/
171
322
null(
172
323
options?: LexiconItemCommonOptions,
173
324
): { type: "null" } & LexiconItemCommonOptions {
···
176
327
...options,
177
328
};
178
329
},
330
+
/**
331
+
* Creates a boolean type with optional constraints.
332
+
* @see https://atproto.com/specs/lexicon#boolean
333
+
*/
179
334
boolean<T extends BooleanOptions>(options?: T): T & { type: "boolean" } {
180
335
return {
181
336
type: "boolean",
182
337
...options,
183
338
} as T & { type: "boolean" };
184
339
},
340
+
/**
341
+
* Creates an integer type with optional min/max and enum constraints.
342
+
* @see https://atproto.com/specs/lexicon#integer
343
+
*/
185
344
integer<T extends IntegerOptions>(options?: T): T & { type: "integer" } {
186
345
return {
187
346
type: "integer",
188
347
...options,
189
348
} as T & { type: "integer" };
190
349
},
350
+
/**
351
+
* Creates a string type with optional format, length, and value constraints.
352
+
* @see https://atproto.com/specs/lexicon#string
353
+
*/
191
354
string<T extends StringOptions>(options?: T): T & { type: "string" } {
192
355
return {
193
356
type: "string",
194
357
...options,
195
358
} as T & { type: "string" };
196
359
},
360
+
/**
361
+
* Creates an unknown type for flexible, unvalidated objects.
362
+
* @see https://atproto.com/specs/lexicon#unknown
363
+
*/
197
364
unknown(
198
365
options?: LexiconItemCommonOptions,
199
366
): { type: "unknown" } & LexiconItemCommonOptions {
···
202
369
...options,
203
370
};
204
371
},
372
+
/**
373
+
* Creates a bytes type for arbitrary byte arrays.
374
+
* @see https://atproto.com/specs/lexicon#bytes
375
+
*/
205
376
bytes<T extends BytesOptions>(options?: T): T & { type: "bytes" } {
206
377
return {
207
378
type: "bytes",
208
379
...options,
209
380
} as T & { type: "bytes" };
210
381
},
382
+
/**
383
+
* Creates a CID link reference to content-addressed data.
384
+
* @see https://atproto.com/specs/lexicon#cid-link
385
+
*/
211
386
cidLink<Link extends string>(link: Link): { type: "cid-link"; $link: Link } {
212
387
return {
213
388
type: "cid-link",
214
389
$link: link,
215
390
};
216
391
},
392
+
/**
393
+
* Creates a blob type for binary data with MIME type constraints.
394
+
* @see https://atproto.com/specs/lexicon#blob
395
+
*/
217
396
blob<T extends BlobOptions>(options?: T): T & { type: "blob" } {
218
397
return {
219
398
type: "blob",
220
399
...options,
221
400
} as T & { type: "blob" };
222
401
},
402
+
/**
403
+
* Creates an array type with item schema and length constraints.
404
+
* @see https://atproto.com/specs/lexicon#array
405
+
*/
223
406
array<Items extends LexiconItem, Options extends ArrayOptions>(
224
407
items: Items,
225
408
options?: Options,
···
230
413
...options,
231
414
} as Options & { type: "array"; items: Items };
232
415
},
416
+
/**
417
+
* Creates a token type for symbolic values in unions.
418
+
* @see https://atproto.com/specs/lexicon#token
419
+
*/
233
420
token<Description extends string>(
234
421
description: Description,
235
422
): { type: "token"; description: Description } {
236
423
return { type: "token", description };
237
424
},
425
+
/**
426
+
* Creates a reference to another schema definition.
427
+
* @see https://atproto.com/specs/lexicon#ref
428
+
*/
238
429
ref<Ref extends string>(
239
430
ref: Ref,
240
431
options?: LexiconItemCommonOptions,
···
245
436
...options,
246
437
} as LexiconItemCommonOptions & { type: "ref"; ref: Ref };
247
438
},
439
+
/**
440
+
* Creates a union type for multiple possible type variants.
441
+
* @see https://atproto.com/specs/lexicon#union
442
+
*/
248
443
union<const Refs extends readonly string[], Options extends UnionOptions>(
249
444
refs: Refs,
250
445
options?: Options,
···
255
450
...options,
256
451
} as Options & { type: "union"; refs: Refs };
257
452
},
453
+
/**
454
+
* Creates a record type for repository records.
455
+
* @see https://atproto.com/specs/lexicon#record
456
+
*/
258
457
record<T extends RecordOptions>(options: T): T & { type: "record" } {
259
458
return {
260
459
type: "record",
261
460
...options,
262
461
};
263
462
},
463
+
/**
464
+
* Creates an object type with defined properties.
465
+
* @see https://atproto.com/specs/lexicon#object
466
+
*/
264
467
object<T extends ObjectProperties>(options: T): ObjectResult<T> {
265
468
const required = Object.keys(options).filter(
266
469
(key) => options[key].required,
···
280
483
}
281
484
return result;
282
485
},
486
+
/**
487
+
* Creates a params type for query string parameters.
488
+
* @see https://atproto.com/specs/lexicon#params
489
+
*/
283
490
params<Properties extends ParamsProperties>(
284
491
properties: Properties,
285
492
): ParamsResult<Properties> {
···
299
506
}
300
507
return result;
301
508
},
509
+
/**
510
+
* Creates a query endpoint definition (HTTP GET).
511
+
* @see https://atproto.com/specs/lexicon#query
512
+
*/
302
513
query<T extends QueryOptions>(options?: T): T & { type: "query" } {
303
514
return {
304
515
type: "query",
305
516
...options,
306
517
} as T & { type: "query" };
307
518
},
519
+
/**
520
+
* Creates a procedure endpoint definition (HTTP POST).
521
+
* @see https://atproto.com/specs/lexicon#procedure
522
+
*/
308
523
procedure<T extends ProcedureOptions>(
309
524
options?: T,
310
525
): T & { type: "procedure" } {
···
313
528
...options,
314
529
} as T & { type: "procedure" };
315
530
},
531
+
/**
532
+
* Creates a subscription endpoint definition (WebSocket).
533
+
* @see https://atproto.com/specs/lexicon#subscription
534
+
*/
316
535
subscription<T extends SubscriptionOptions>(
317
536
options?: T,
318
537
): T & { type: "subscription" } {
···
321
540
...options,
322
541
} as T & { type: "subscription" };
323
542
},
543
+
/**
544
+
* Creates a lexicon namespace document.
545
+
* @see https://atproto.com/specs/lexicon#lexicon-document
546
+
*/
324
547
namespace<ID extends string, D extends LexiconNamespace["defs"]>(
325
548
id: ID,
326
549
defs: D,