@atproto/lex-schema 0.0.10 → 0.0.12

package/src/schema/payload.test.ts

@@ -3,7 +3,7 @@ import { integer } from './integer.js'
 import { object } from './object.js'
 import { payload } from './payload.js'
 import { string } from './string.js'
-import { unknown } from './unknown.js'
+import { unknownObject } from './unknown-object.js'
 
 describe('Payload', () => {
   describe('basic construction', () => {
@@ -113,7 +113,7 @@ describe('Payload', () => {
     })
 
     it('creates payload with unknown schema', () => {
-      const schema = unknown()
+      const schema = object({})
       const def = payload('application/json', schema)
       expect(def.encoding).toBe('application/json')
       expect(def.schema).toBe(schema)
@@ -224,7 +224,7 @@ describe('Payload', () => {
         'application/json',
         object({
           success: string(),
-          data: unknown(),
+          data: unknownObject(),
         }),
       )
       expect(def.encoding).toBe('application/json')

package/src/schema/payload.ts

@@ -1,50 +1,101 @@
 import { LexValue } from '@atproto/lex-data'
-import { Infer, Schema } from '../core.js'
-import { ObjectSchema, ObjectSchemaShape, object } from './object.js'
-
-export type InferPayload<
-  TPayload extends Payload,
-  TBody,
-> = TPayload['encoding'] extends infer E extends string
-  ? {
-      encoding: SchemaEncodingToDataEncoding<E>
-      body: InferPayloadBody<TPayload, TBody>
-    }
-  : void | undefined
+import { Infer, Schema, Validator } from '../core.js'
+import { ObjectSchema, object } from './object.js'
+
+export type { LexValue }
 
-export type SchemaEncodingToDataEncoding<E extends string> = E extends '*/*'
+type ToBodyMime<TEncoding extends string> = TEncoding extends '*/*'
   ? `${string}/${string}`
-  : E extends `${infer T extends string}/*`
+  : TEncoding extends `${infer T extends string}/*`
     ? `${T}/${string}`
-    : E
+    : TEncoding
+
+type ToBodyType<
+  TEncoding extends string,
+  TSchema,
+  TBinary,
+> = TSchema extends Schema
+  ? Infer<TSchema>
+  : TEncoding extends `application/json`
+    ? LexValue
+    : TBinary
 
+/**
+ * Infers the type of a Payload's encoding and body.
+ *
+ * @template TPayload - The Payload type
+ * @template TBody - Fallback body type for non-JSON encodings
+ */
+export type InferPayload<TPayload extends Payload, TBinary> =
+  TPayload extends Payload<infer TEncoding, infer TSchema>
+    ? TEncoding extends string
+      ? {
+          encoding: ToBodyMime<TEncoding>
+          body: ToBodyType<TEncoding, TSchema, TBinary>
+        }
+      : undefined
+    : never
+
+/**
+ * Converts schema encoding patterns to data encoding types.
+ *
+ * Handles wildcards like '*\/*' and 'image/*' in MIME types.
+ *
+ * @template TPayload - The Payload type
+ */
 export type InferPayloadEncoding<TPayload extends Payload> =
-  TPayload['encoding'] extends string
-    ? SchemaEncodingToDataEncoding<TPayload['encoding']>
-    : undefined
-
-export type InferPayloadBody<
-  TPayload extends Payload,
-  TBody,
-> = TPayload['encoding'] extends undefined
-  ? undefined // No encoding, no payload
-  : TPayload['schema'] extends Schema
-    ? Infer<TPayload['schema']>
-    : TPayload['encoding'] extends `application/json`
-      ? LexValue
-      : TBody
-
-export type PayloadShape<E extends string | undefined> = E extends undefined
+  TPayload extends Payload<infer TEncoding, any>
+    ? TEncoding extends string
+      ? ToBodyMime<TEncoding>
+      : undefined
+    : never
+
+/**
+ * Infers the body type from a Payload and fallback type.
+ *
+ * @template TPayload - The Payload type
+ * @template TBody - Fallback body type for non-JSON encodings without schema
+ */
+export type InferPayloadBody<TPayload extends Payload, TBinary> =
+  TPayload extends Payload<infer TEncoding, infer TSchema>
+    ? TEncoding extends string
+      ? ToBodyType<TEncoding, TSchema, TBinary>
+      : undefined
+    : never
+
+/**
+ * Determines valid schema type based on encoding presence.
+ *
+ * @template E - The encoding string type, or undefined
+ */
+export type PayloadSchema<E extends string | undefined> = E extends undefined
   ? undefined
-  : Schema | undefined
+  : Schema<LexValue> | undefined
 
+/**
+ * Represents a payload definition for Lexicon endpoints.
+ *
+ * Payloads define the body format for HTTP requests and responses.
+ * They consist of an encoding (MIME type) and an optional schema
+ * for validating the body content.
+ *
+ * @template TEncoding - The MIME type string, or undefined for no body
+ * @template TPayload - The schema type for body validation
+ *
+ * @example
+ * ```ts
+ * const jsonPayload = new Payload('application/json', l.object({ data: l.string() }))
+ * const binaryPayload = new Payload('image/*', undefined)
+ * const noPayload = new Payload(undefined, undefined)
+ * ```
+ */
 export class Payload<
   const TEncoding extends string | undefined = string | undefined,
-  const TPayload extends PayloadShape<TEncoding> = PayloadShape<TEncoding>,
+  const TSchema extends PayloadSchema<TEncoding> = PayloadSchema<TEncoding>,
 > {
   constructor(
     readonly encoding: TEncoding,
-    readonly schema: TPayload,
+    readonly schema: TSchema,
   ) {
     if (encoding === undefined && schema !== undefined) {
       throw new TypeError('schema cannot be defined when encoding is undefined')
@@ -86,17 +137,70 @@ export class Payload<
   }
 }
 
+/**
+ * Creates a payload definition for Lexicon endpoint bodies.
+ *
+ * Defines the expected MIME type and optional validation schema for
+ * request or response bodies.
+ *
+ * @param encoding - MIME type string (e.g., 'application/json', 'image/*'), or undefined for no body
+ * @param validator - Optional schema for validating the body content. Must be undefined if encoding is undefined.
+ * @returns A new {@link Payload} instance
+ *
+ * @example
+ * ```ts
+ * // JSON payload with schema
+ * const output = l.payload('application/json', l.object({
+ *   posts: l.array(postSchema),
+ *   cursor: l.optional(l.string()),
+ * }))
+ *
+ * // Binary payload (no schema validation)
+ * const blobInput = l.payload('*\/*', undefined)
+ *
+ * // Image payload with wildcard
+ * const imageInput = l.payload('image/*', undefined)
+ *
+ * // No payload (for endpoints without body)
+ * const noBody = l.payload()
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function payload<
   const E extends string | undefined = undefined,
-  const S extends PayloadShape<E> = undefined,
+  const S extends PayloadSchema<E> = undefined,
 >(encoding: E = undefined as E, validator: S = undefined as S) {
   return new Payload<E, S>(encoding, validator)
 }
 
+/**
+ * Creates a JSON payload with an object schema.
+ *
+ * Convenience function for the common case of JSON request/response bodies.
+ * Equivalent to `l.payload('application/json', l.object(properties))`.
+ *
+ * @param properties - Object mapping property names to validators
+ * @returns A new {@link Payload} instance with 'application/json' encoding
+ *
+ * @example
+ * ```ts
+ * // Query output
+ * const profileOutput = l.jsonPayload({
+ *   did: l.string({ format: 'did' }),
+ *   handle: l.string({ format: 'handle' }),
+ *   displayName: l.optional(l.string()),
+ * })
+ *
+ * // Procedure input
+ * const createPostInput = l.jsonPayload({
+ *   text: l.string({ maxGraphemes: 300 }),
+ *   createdAt: l.string({ format: 'datetime' }),
+ * })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
-export function jsonPayload<const P extends ObjectSchemaShape>(
-  properties: P,
-): Payload<'application/json', ObjectSchema<P>> {
+export function jsonPayload<
+  P extends Record<string, Validator<undefined | LexValue>>,
+>(properties: P): Payload<'application/json', ObjectSchema<P>> {
   return payload('application/json', object(properties))
 }

package/src/schema/permission-set.ts

@@ -1,6 +1,14 @@
 import { NsidString } from '../core.js'
 import { Permission } from './permission.js'
 
+/**
+ * Configuration options for a permission set.
+ *
+ * @property title - Human-readable title for the permission set
+ * @property title:lang - Localized titles by language code
+ * @property detail - Detailed description of the permission set
+ * @property detail:lang - Localized descriptions by language code
+ */
 export type PermissionSetOptions = {
   title?: string
   'title:lang'?: Record<string, undefined | string>
@@ -8,6 +16,24 @@ export type PermissionSetOptions = {
   'detail:lang'?: Record<string, undefined | string>
 }
 
+/**
+ * Represents a collection of related permissions in AT Protocol.
+ *
+ * Permission sets group permissions together with metadata for OAuth
+ * authorization flows. They are identified by an NSID.
+ *
+ * @template TNsid - The NSID identifying this permission set
+ * @template TPermissions - Tuple type of the included permissions
+ *
+ * @example
+ * ```ts
+ * const feedAccess = new PermissionSet(
+ *   'app.bsky.feed.access',
+ *   [readPermission, writePermission],
+ *   { title: 'Feed Access', detail: 'Read and write to your feed' }
+ * )
+ * ```
+ */
 export class PermissionSet<
   const TNsid extends NsidString = any,
   const TPermissions extends readonly Permission[] = any,
@@ -19,6 +45,38 @@ export class PermissionSet<
   ) {}
 }
 
+/**
+ * Creates a permission set grouping related permissions.
+ *
+ * Permission sets define OAuth scopes that applications can request.
+ * They include human-readable metadata for authorization UIs.
+ *
+ * @param nsid - The NSID identifying this permission set
+ * @param permissions - Array of permissions included in this set
+ * @param options - Optional metadata (title, detail, localization)
+ * @returns A new {@link PermissionSet} instance
+ *
+ * @example
+ * ```ts
+ * // Define individual permissions
+ * const readPosts = l.permission('read', { collection: 'app.bsky.feed.post' })
+ * const writePosts = l.permission('write', { collection: 'app.bsky.feed.post' })
+ *
+ * // Group into a permission set
+ * const postManagement = l.permissionSet(
+ *   'app.bsky.feed.postManagement',
+ *   [readPosts, writePosts],
+ *   {
+ *     title: 'Post Management',
+ *     detail: 'View and create posts on your behalf',
+ *     'title:lang': {
+ *       'es': 'Gestion de publicaciones',
+ *       'fr': 'Gestion des publications',
+ *     },
+ *   }
+ * )
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function permissionSet<
   const N extends NsidString,

package/src/schema/permission.ts

@@ -1,7 +1,24 @@
 import { Params } from './params.js'
 
+/**
+ * Type alias for permission options (same as Params).
+ */
 export type PermissionOptions = Params
 
+/**
+ * Represents a single permission in an AT Protocol permission set.
+ *
+ * Permissions define access rights to specific resources with optional
+ * parameters for fine-grained control.
+ *
+ * @template TResource - The resource identifier string type
+ * @template TOptions - The options type (must be valid Params)
+ *
+ * @example
+ * ```ts
+ * const readPermission = new Permission('read', { collection: 'app.bsky.feed.post' })
+ * ```
+ */
 export class Permission<
   const TResource extends string = any,
   const TOptions extends PermissionOptions = any,
@@ -12,6 +29,31 @@ export class Permission<
   ) {}
 }
 
+/**
+ * Creates a permission definition for AT Protocol authorization.
+ *
+ * Permissions specify what resources an application can access.
+ * Used in permission sets to define OAuth scopes.
+ *
+ * @param resource - The resource identifier (e.g., 'read', 'write', 'admin')
+ * @param options - Optional parameters for the permission
+ * @returns A new {@link Permission} instance
+ *
+ * @example
+ * ```ts
+ * // Simple permission
+ * const readPermission = l.permission('read')
+ *
+ * // Permission with options
+ * const writePostsPermission = l.permission('write', {
+ *   collection: 'app.bsky.feed.post',
+ * })
+ *
+ * // Multiple permissions with different scopes
+ * const readProfile = l.permission('read', { collection: 'app.bsky.actor.profile' })
+ * const readFeed = l.permission('read', { collection: 'app.bsky.feed.*' })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function permission<
   const R extends string,

package/src/schema/procedure.ts

@@ -2,6 +2,30 @@ import { NsidString } from '../core.js'
 import { ParamsSchema } from './params.js'
 import { Payload } from './payload.js'
 
+/**
+ * Represents a Lexicon procedure (HTTP POST) endpoint definition.
+ *
+ * Procedures are operations that may modify state on the server.
+ * They have parameters, an input payload (request body), an output
+ * payload (response body), and optional error types.
+ *
+ * @template TNsid - The NSID identifying this procedure
+ * @template TParameters - The parameters schema type
+ * @template TInputPayload - The request body payload type
+ * @template TOutputPayload - The response body payload type
+ * @template TErrors - Array of error type strings, or undefined
+ *
+ * @example
+ * ```ts
+ * const createPost = new Procedure(
+ *   'app.bsky.feed.post',
+ *   l.params({}),
+ *   l.jsonPayload({ text: l.string() }),
+ *   l.jsonPayload({ uri: l.string(), cid: l.string() }),
+ *   ['InvalidRecord']
+ * )
+ * ```
+ */
 export class Procedure<
   const TNsid extends NsidString = NsidString,
   const TParameters extends ParamsSchema = ParamsSchema,
@@ -22,6 +46,46 @@ export class Procedure<
   ) {}
 }
 
+/**
+ * Creates a procedure definition for a Lexicon POST endpoint.
+ *
+ * Procedures can modify server state. They accept both URL parameters
+ * and a request body (input payload).
+ *
+ * @param nsid - The NSID identifying this procedure endpoint
+ * @param parameters - Schema for URL query parameters
+ * @param input - Schema for request body payload
+ * @param output - Schema for response body payload
+ * @param errors - Optional array of error type strings
+ * @returns A new {@link Procedure} instance
+ *
+ * @example
+ * ```ts
+ * // Create record procedure
+ * const createRecord = l.procedure(
+ *   'com.atproto.repo.createRecord',
+ *   l.params({}),
+ *   l.jsonPayload({
+ *     repo: l.string({ format: 'at-identifier' }),
+ *     collection: l.string({ format: 'nsid' }),
+ *     record: l.unknown(),
+ *   }),
+ *   l.jsonPayload({
+ *     uri: l.string({ format: 'at-uri' }),
+ *     cid: l.string({ format: 'cid' }),
+ *   }),
+ *   ['InvalidRecord', 'RepoNotFound'],
+ * )
+ *
+ * // Procedure with binary input
+ * const uploadBlob = l.procedure(
+ *   'com.atproto.repo.uploadBlob',
+ *   l.params({}),
+ *   l.payload('*\/*', undefined), // Accept any content type
+ *   l.jsonPayload({ blob: l.blob() }),
+ * )
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function procedure<
   const N extends NsidString,

package/src/schema/query.ts

@@ -2,6 +2,28 @@ import { NsidString } from '../core.js'
 import { ParamsSchema } from './params.js'
 import { Payload } from './payload.js'
 
+/**
+ * Represents a Lexicon query (HTTP GET) endpoint definition.
+ *
+ * Queries are read-only operations that retrieve data from a server.
+ * They have parameters (passed as URL query parameters), an output
+ * payload, and optional error types.
+ *
+ * @template TNsid - The NSID identifying this query
+ * @template TParameters - The parameters schema type
+ * @template TOutputPayload - The output payload type
+ * @template TErrors - Array of error type strings, or undefined
+ *
+ * @example
+ * ```ts
+ * const getPostQuery = new Query(
+ *   'app.bsky.feed.getPost',
+ *   l.params({ uri: l.string({ format: 'at-uri' }) }),
+ *   l.payload('application/json', postSchema),
+ *   ['NotFound']
+ * )
+ * ```
+ */
 export class Query<
   const TNsid extends NsidString = NsidString,
   const TParameters extends ParamsSchema = ParamsSchema,
@@ -20,6 +42,39 @@ export class Query<
   ) {}
 }
 
+/**
+ * Creates a query definition for a Lexicon GET endpoint.
+ *
+ * Queries retrieve data without side effects. Parameters are sent as
+ * URL query string parameters.
+ *
+ * @param nsid - The NSID identifying this query endpoint
+ * @param parameters - Schema for URL query parameters
+ * @param output - Expected response payload schema
+ * @param errors - Optional array of error type strings
+ * @returns A new {@link Query} instance
+ *
+ * @example
+ * ```ts
+ * // Simple query with JSON output
+ * const getProfile = l.query(
+ *   'app.bsky.actor.getProfile',
+ *   l.params({ actor: l.string({ format: 'at-identifier' }) }),
+ *   l.jsonPayload({ displayName: l.string(), handle: l.string() }),
+ * )
+ *
+ * // Query with pagination and errors
+ * const getTimeline = l.query(
+ *   'app.bsky.feed.getTimeline',
+ *   l.params({
+ *     limit: l.optional(l.integer({ minimum: 1, maximum: 100 })),
+ *     cursor: l.optional(l.string()),
+ *   }),
+ *   l.jsonPayload({ feed: l.array(feedItemSchema), cursor: l.optional(l.string()) }),
+ *   ['BlockedActor', 'BlockedByActor'],
+ * )
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function query<
   const N extends NsidString,

package/src/schema/record.ts

@@ -14,9 +14,34 @@ import {
 import { literal } from './literal.js'
 import { string } from './string.js'
 
+/**
+ * Infers the record key type from a RecordSchema.
+ *
+ * @template R - The RecordSchema type
+ */
 export type InferRecordKey<R extends RecordSchema> =
   R extends RecordSchema<infer TKey> ? RecordKeySchemaOutput<TKey> : never
 
+/**
+ * Schema for AT Protocol records with a type identifier and key constraints.
+ *
+ * Records are the primary data unit in AT Protocol. Each record has a `$type`
+ * field identifying its Lexicon schema, and is stored at a specific key
+ * (TID, NSID, or other format) in a repository.
+ *
+ * @template TKey - The record key type ('tid', 'nsid', 'any', or 'literal:...')
+ * @template TType - The NSID string identifying this record type
+ * @template TShape - The validator type for the record's data shape
+ *
+ * @example
+ * ```ts
+ * const postSchema = new RecordSchema(
+ *   'tid',
+ *   'app.bsky.feed.post',
+ *   l.object({ text: l.string(), createdAt: l.string() })
+ * )
+ * ```
+ */
 export class RecordSchema<
   const TKey extends LexiconRecordKey = any,
   const TType extends NsidString = any,
@@ -115,15 +140,45 @@ function recordKey<Key extends LexiconRecordKey>(
 type AsNsid<T> = T extends `${string}#${string}` ? never : T
 
 /**
+ * Creates a record schema for AT Protocol records.
+ *
+ * Records are the primary data unit in AT Protocol repositories. They have
+ * a `$type` field identifying their Lexicon schema, and are stored at keys
+ * following a specific format (TID, NSID, etc.).
+ *
  * This function offers two overloads:
- * - One that allows creating a {@link RecordSchema}, and infer the output type
- *   from the provided arguments, without requiring to specify any of the
- *   generics. This is useful when you want to define a record without
- *   explicitly defining its interface. This version does not support circular
- *   references, as TypeScript cannot infer types in such cases.
- * - One allows creating a {@link RecordSchema} with an explicitly defined
- *   interface. This will typically be used by codegen (`lex build`) to generate
- *   schemas that work even if they contain circular references.
+ * - One that infers the output type from the provided arguments (does not
+ *   support circular references)
+ * - One with an explicitly defined interface for use with codegen and
+ *   circular references
+ *
+ * @param key - The record key type: 'tid', 'nsid', 'any', or 'literal:value'
+ * @param type - The NSID identifying this record type (e.g., 'app.bsky.feed.post')
+ * @param validator - Schema validator for the record's properties
+ * @returns A new {@link RecordSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Post record with TID key
+ * const postSchema = l.record('tid', 'app.bsky.feed.post', l.object({
+ *   text: l.string({ maxGraphemes: 300 }),
+ *   createdAt: l.string({ format: 'datetime' }),
+ *   reply: l.optional(l.object({
+ *     root: l.ref(() => strongRefSchema),
+ *     parent: l.ref(() => strongRefSchema),
+ *   })),
+ * }))
+ *
+ * // Profile record with literal 'self' key
+ * const profileSchema = l.record('literal:self', 'app.bsky.actor.profile', l.object({
+ *   displayName: l.optional(l.string({ maxGraphemes: 64 })),
+ *   description: l.optional(l.string({ maxGraphemes: 256 })),
+ *   avatar: l.optional(l.blob({ accept: ['image/*'] })),
+ * }))
+ *
+ * // Build a record with automatic $type injection
+ * const post = postSchema.build({ text: 'Hello!', createdAt: new Date().toISOString() })
+ * ```
  */
 export function record<
   const K extends LexiconRecordKey,

package/src/schema/ref.ts

@@ -7,8 +7,30 @@ import {
   WrappedValidator,
 } from '../core.js'
 
+/**
+ * Function type that returns a validator, used for lazy schema resolution.
+ *
+ * @template TValidator - The validator type that will be returned
+ */
 export type RefSchemaGetter<out TValidator extends Validator> = () => TValidator
 
+/**
+ * Schema for creating references to other schemas with lazy resolution.
+ *
+ * Useful for handling circular references or breaking module dependency cycles.
+ * The referenced schema is resolved lazily when first needed for validation.
+ *
+ * @template TValidator - The referenced validator type
+ *
+ * @example
+ * ```ts
+ * // Self-referential schema for tree structure
+ * const nodeSchema = l.object({
+ *   value: l.string(),
+ *   children: l.array(l.ref(() => nodeSchema)),
+ * })
+ * ```
+ */
 export class RefSchema<const TValidator extends Validator>
   extends Schema<
     InferInput<TValidator>,
@@ -41,6 +63,34 @@ export class RefSchema<const TValidator extends Validator>
   }
 }
 
+/**
+ * Creates a reference schema with lazy resolution.
+ *
+ * Allows referencing schemas that may not be defined yet, enabling
+ * circular references and breaking dependency cycles. The getter function
+ * is called lazily when validation is first performed.
+ *
+ * @param get - Function that returns the referenced validator
+ * @returns A new {@link RefSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Circular reference - tree node that contains children of the same type
+ * const treeNodeSchema = l.object({
+ *   name: l.string(),
+ *   children: l.optional(l.array(l.ref(() => treeNodeSchema))),
+ * })
+ *
+ * // Cross-module reference
+ * const commentSchema = l.object({
+ *   text: l.string(),
+ *   author: l.ref(() => userSchema), // userSchema defined elsewhere
+ * })
+ *
+ * // Explicitly typed reference
+ * const itemSchema = l.ref<Item>(() => complexItemSchema)
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function ref<const TValidator extends Validator>(
   get: RefSchemaGetter<TValidator>,