@atproto/lex-schema 0.0.11 → 0.0.12

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>,

package/src/schema/refine.ts

@@ -8,18 +8,40 @@ import {
 } from '../core.js'
 import { CustomAssertionContext } from './custom.js'
 
+/**
+ * Configuration for a refinement check that validates a condition.
+ *
+ * @template T - The type being validated
+ * @property check - Function that returns true if the value passes the check
+ * @property message - Error message when the check fails
+ * @property path - Optional path to associate with the error
+ */
 export type RefinementCheck<T> = {
   check: (value: T, ctx: CustomAssertionContext) => boolean
   message: string
   path?: PropertyKey | readonly PropertyKey[]
 }
 
+/**
+ * Configuration for a refinement assertion that narrows the type.
+ *
+ * @template T - The input type being validated
+ * @template Out - The narrowed output type
+ * @property check - Type guard function that narrows the type
+ * @property message - Error message when the assertion fails
+ * @property path - Optional path to associate with the error
+ */
 export type RefinementAssertion<T, Out extends T> = {
   check: (this: null, value: T, ctx: CustomAssertionContext) => value is Out
   message: string
   path?: PropertyKey | readonly PropertyKey[]
 }
 
+/**
+ * Infers the input type from a refinement configuration.
+ *
+ * @template R - The refinement type
+ */
 export type InferRefinement<R> =
   R extends RefinementCheck<infer T>
     ? T
@@ -27,25 +49,52 @@ export type InferRefinement<R> =
       ? T
       : never
 
+/**
+ * Union type of refinement check or assertion.
+ *
+ * @template T - The input type being validated
+ * @template Out - The output type (same as T for checks, narrowed for assertions)
+ */
 export type Refinement<T = any, Out extends T = T> =
   | RefinementCheck<T>
   | RefinementAssertion<T, Out>
 
 /**
- * Create a refined schema based on an existing schema and a refinement check.
+ * Creates a refined schema by adding additional validation constraints.
  *
- * @param schema - The base schema to refine.
- * @param refinement - The refinement check to apply.
- * @returns A new schema that includes the refinement.
- * @example
+ * Wraps an existing schema with an additional check function. The base schema
+ * is validated first, then the refinement check is applied to the result.
  *
+ * @param schema - The base schema to refine
+ * @param refinement - The refinement check or assertion to apply
+ * @returns A new schema that includes the refinement
+ *
+ * @example
  * ```ts
- * const PositiveInt = refine(l.integer(), {
+ * // Simple check refinement
+ * const positiveInt = l.refine(l.integer(), {
  *   check: (value) => value > 0,
- *   message: 'Value must be a positive integer',
+ *   message: 'Value must be positive',
  * })
- * const result = PositiveInt.validate(-5)
- * // result.success === false
+ *
+ * positiveInt.parse(5)  // 5
+ * positiveInt.parse(-1) // throws
+ *
+ * // Type-narrowing assertion
+ * const nonEmptyString = l.refine(l.string(), {
+ *   check: (value): value is string & { length: number } => value.length > 0,
+ *   message: 'String must not be empty',
+ * })
+ *
+ * // With custom path for nested errors
+ * const validDateRange = l.refine(
+ *   l.object({ start: l.string(), end: l.string() }),
+ *   {
+ *     check: (v) => new Date(v.start) < new Date(v.end),
+ *     message: 'Start date must be before end date',
+ *     path: ['end'],
+ *   }
+ * )
  * ```
  */
 export function refine<

package/src/schema/regexp.ts

@@ -1,5 +1,20 @@
 import { Schema, ValidationContext } from '../core.js'
 
+/**
+ * Schema for validating strings against a regular expression pattern.
+ *
+ * Validates that the input is a string and matches the provided pattern.
+ * The pattern is tested using RegExp.test().
+ *
+ * @template TValue - The string type (can be narrowed with branded types)
+ *
+ * @example
+ * ```ts
+ * const schema = new RegexpSchema(/^[a-z]+$/)
+ * schema.validate('hello') // success
+ * schema.validate('Hello') // fails - uppercase not allowed
+ * ```
+ */
 export class RegexpSchema<
   TValue extends string = string,
 > extends Schema<TValue> {
@@ -20,6 +35,35 @@ export class RegexpSchema<
   }
 }
 
+/**
+ * Creates a regexp schema that validates strings against a pattern.
+ *
+ * Useful for custom string formats not covered by the built-in format
+ * validators.
+ *
+ * @param pattern - Regular expression pattern to match against
+ * @returns A new {@link RegexpSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Simple pattern
+ * const slugSchema = l.regexp(/^[a-z0-9-]+$/)
+ *
+ * // With anchors for exact match
+ * const uuidSchema = l.regexp(
+ *   /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+ * )
+ *
+ * // Semantic versioning
+ * const semverSchema = l.regexp(/^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/)
+ *
+ * // Use in object
+ * const configSchema = l.object({
+ *   name: l.regexp(/^[a-z][a-z0-9-]*$/), // kebab-case identifier
+ *   version: semverSchema,
+ * })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function regexp<TInput extends string = string>(pattern: RegExp) {
   return new RegexpSchema<TInput>(pattern)

package/src/schema/string.ts

@@ -9,6 +9,15 @@ import {
 import { memoizedOptions } from '../util/memoize.js'
 import { TokenSchema } from './token.js'
 
+/**
+ * Configuration options for string schema validation.
+ *
+ * @property format - Expected string format (e.g., 'datetime', 'uri', 'at-uri', 'did', 'handle', 'nsid', 'cid', 'tid', 'record-key', 'at-identifier', 'language')
+ * @property minLength - Minimum length in UTF-8 bytes
+ * @property maxLength - Maximum length in UTF-8 bytes
+ * @property minGraphemes - Minimum number of grapheme clusters
+ * @property maxGraphemes - Maximum number of grapheme clusters
+ */
 export type StringSchemaOptions = {
   format?: StringFormat
   minLength?: number
@@ -17,6 +26,20 @@ export type StringSchemaOptions = {
   maxGraphemes?: number
 }
 
+/**
+ * Schema for validating string values with optional format and length constraints.
+ *
+ * Supports various string formats defined in the Lexicon specification, as well as
+ * length constraints measured in UTF-8 bytes or grapheme clusters.
+ *
+ * @template TOptions - The configuration options type
+ *
+ * @example
+ * ```ts
+ * const schema = new StringSchema({ format: 'datetime', maxLength: 64 })
+ * const result = schema.validate('2024-01-15T10:30:00Z')
+ * ```
+ */
 export class StringSchema<
   const TOptions extends StringSchemaOptions = StringSchemaOptions,
 > extends Schema<
@@ -123,6 +146,33 @@ export function coerceToString(input: unknown): string | null {
   }
 }
 
+/**
+ * Creates a string schema with optional format and length constraints.
+ *
+ * Strings can be validated against various formats (datetime, uri, did, handle, etc.)
+ * and constrained by length in UTF-8 bytes or grapheme clusters.
+ *
+ * @param options - Optional configuration for format and length constraints
+ * @returns A new {@link StringSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic string
+ * const nameSchema = l.string()
+ *
+ * // With format validation
+ * const dateSchema = l.string({ format: 'datetime' })
+ *
+ * // With length constraints (UTF-8 bytes)
+ * const bioSchema = l.string({ maxLength: 256 })
+ *
+ * // With grapheme constraints (user-perceived characters)
+ * const displayNameSchema = l.string({ maxGraphemes: 64 })
+ *
+ * // Combining constraints
+ * const handleSchema = l.string({ format: 'handle', minLength: 3, maxLength: 253 })
+ * ```
+ */
 export const string = /*#__PURE__*/ memoizedOptions(function <
   const O extends StringSchemaOptions = NonNullable<unknown>,
 >(options?: StringSchemaOptions & O) {

package/src/schema/subscription.ts

@@ -1,18 +1,51 @@
+import { LexValue } from '@atproto/lex-data'
 import { Infer, NsidString, Schema } from '../core.js'
 import { ParamsSchema } from './params.js'
 
+/**
+ * Infers the parameters type from a Subscription definition.
+ *
+ * @template S - The Subscription type
+ */
 export type InferSubscriptionParameters<S extends Subscription> = Infer<
   S['parameters']
 >
 
+/**
+ * Infers the message type from a Subscription definition.
+ *
+ * @template S - The Subscription type
+ */
 export type InferSubscriptionMessage<S extends Subscription> = Infer<
   S['message']
 >
 
+/**
+ * Represents a Lexicon subscription (WebSocket) endpoint definition.
+ *
+ * Subscriptions are real-time event streams delivered over WebSocket.
+ * They have parameters for initializing the connection and a message
+ * schema for validating incoming events.
+ *
+ * @template TNsid - The NSID identifying this subscription
+ * @template TParameters - The connection parameters schema type
+ * @template TMessage - The message schema type
+ * @template TErrors - Array of error type strings, or undefined
+ *
+ * @example
+ * ```ts
+ * const firehose = new Subscription(
+ *   'com.atproto.sync.subscribeRepos',
+ *   l.params({ cursor: l.optional(l.integer()) }),
+ *   repoEventSchema,
+ *   ['FutureCursor']
+ * )
+ * ```
+ */
 export class Subscription<
   const TNsid extends NsidString = NsidString,
   const TParameters extends ParamsSchema = ParamsSchema,
-  const TMessage extends Schema = Schema,
+  const TMessage extends Schema<LexValue> = Schema<LexValue>,
   const TErrors extends undefined | readonly string[] =
     | undefined
     | readonly string[],
@@ -27,11 +60,48 @@ export class Subscription<
   ) {}
 }
 
+/**
+ * Creates a subscription definition for a Lexicon WebSocket endpoint.
+ *
+ * Subscriptions enable real-time event streaming. The connection is
+ * initialized with parameters, and the server sends messages matching
+ * the message schema.
+ *
+ * @param nsid - The NSID identifying this subscription endpoint
+ * @param parameters - Schema for connection parameters
+ * @param message - Schema for validating incoming messages
+ * @param errors - Optional array of error type strings
+ * @returns A new {@link Subscription} instance
+ *
+ * @example
+ * ```ts
+ * // Repository event stream
+ * const subscribeRepos = l.subscription(
+ *   'com.atproto.sync.subscribeRepos',
+ *   l.params({
+ *     cursor: l.optional(l.integer()),
+ *   }),
+ *   l.typedUnion([
+ *     l.typedRef(() => commitEventSchema),
+ *     l.typedRef(() => handleEventSchema),
+ *     l.typedRef(() => identityEventSchema),
+ *   ], false),
+ *   ['FutureCursor', 'ConsumerTooSlow'],
+ * )
+ *
+ * // Label stream
+ * const subscribeLabels = l.subscription(
+ *   'com.atproto.label.subscribeLabels',
+ *   l.params({ cursor: l.optional(l.integer()) }),
+ *   labelEventSchema,
+ * )
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function subscription<
   const N extends NsidString,
   const P extends ParamsSchema,
-  const M extends Schema,
+  const M extends Schema<LexValue>,
   const E extends undefined | readonly string[] = undefined,
 >(nsid: N, parameters: P, message: M, errors: E = undefined as E) {
   return new Subscription<N, P, M, E>(nsid, parameters, message, errors)

package/src/schema/token.ts

@@ -1,5 +1,20 @@
 import { $type, NsidString, Schema, ValidationContext } from '../core.js'
 
+/**
+ * Schema for Lexicon token values.
+ *
+ * Tokens are named constants in Lexicon, identified by their NSID and hash.
+ * They validate to their string value (e.g., 'app.bsky.feed.defs#requestLess').
+ * TokenSchema instances can also be used as values themselves.
+ *
+ * @template TValue - The token string literal type
+ *
+ * @example
+ * ```ts
+ * const schema = new TokenSchema('app.bsky.feed.defs#requestLess')
+ * schema.validate('app.bsky.feed.defs#requestLess') // success
+ * ```
+ */
 export class TokenSchema<
   const TValue extends string = string,
 > extends Schema<TValue> {
@@ -37,6 +52,38 @@ export class TokenSchema<
   }
 }
 
+/**
+ * Creates a token schema for Lexicon named constants.
+ *
+ * Tokens are used in Lexicon as named constants or enum-like values.
+ * The token instance can be used both as a schema validator and as
+ * the token value itself (it serializes to its string value).
+ *
+ * @param nsid - The NSID part of the token
+ * @param hash - The hash part of the token (defaults to 'main')
+ * @returns A new {@link TokenSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Define tokens
+ * const requestLess = l.token('app.bsky.feed.defs', 'requestLess')
+ * const requestMore = l.token('app.bsky.feed.defs', 'requestMore')
+ *
+ * // Use as a value
+ * console.log(requestLess.toString()) // 'app.bsky.feed.defs#requestLess'
+ *
+ * // Use in union for validation
+ * const feedbackSchema = l.union([requestLess, requestMore])
+ *
+ * // Validate
+ * feedbackSchema.parse('app.bsky.feed.defs#requestLess') // success
+ *
+ * // Token instances can be used as values in other schemas
+ * const feedbackRequest = l.object({
+ *   feedback: requestLess, // Accepts the token value
+ * })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function token<
   const N extends NsidString,