@atproto/lex-schema 0.0.11 → 0.0.12

package/src/schema/params.ts

@@ -10,31 +10,84 @@ import {
 } from '../core.js'
 import { lazyProperty } from '../util/lazy-property.js'
 import { memoizedOptions } from '../util/memoize.js'
-import { array } from './array.js'
-import { boolean } from './boolean.js'
+import { ArraySchema, array } from './array.js'
+import { BooleanSchema, boolean } from './boolean.js'
 import { dict } from './dict.js'
-import { integer } from './integer.js'
-import { optional } from './optional.js'
+import { IntegerSchema, integer } from './integer.js'
+import { OptionalSchema, optional } from './optional.js'
 import { StringSchema, string } from './string.js'
 import { union } from './union.js'
+import { WithDefaultSchema } from './with-default.js'
 
+/**
+ * Scalar types allowed in URL parameters: boolean, integer, or string.
+ */
 export type ParamScalar = Infer<typeof paramScalarSchema>
 const paramScalarSchema = union([boolean(), integer(), string()])
 
+/**
+ * A single parameter value: scalar or array of scalars.
+ */
 export type Param = Infer<typeof paramSchema>
+
+/**
+ * Schema for validating individual parameter values.
+ */
 export const paramSchema = union([paramScalarSchema, array(paramScalarSchema)])
 
+/**
+ * Type for a params object with string keys and optional param values.
+ */
 export type Params = Infer<typeof paramsSchema>
+
+/**
+ * Schema for validating arbitrary params objects.
+ */
 export const paramsSchema = dict(string(), optional(paramSchema))
 
+// @NOTE In order to properly coerce URLSearchParams, we need to distinguish
+// between scalar and array validators, requiring to be able to detect which
+// schema types are being used, restricting the allowed param validators here.
+type ParamScalarValidator = StringSchema | BooleanSchema | IntegerSchema
+type ParamValueValidator =
+  | ParamScalarValidator
+  | ArraySchema<ParamScalarValidator>
+type ParamValidator =
+  | ParamValueValidator
+  | OptionalSchema<ParamValueValidator>
+  | OptionalSchema<WithDefaultSchema<ParamValueValidator>>
+  | WithDefaultSchema<ParamValueValidator>
+
+/**
+ * Type representing the shape of a params schema definition.
+ *
+ * Maps parameter names to their validators (must be Param or undefined).
+ */
 export type ParamsSchemaShape = {
-  [x: string]: Validator<Param | undefined>
+  [x: string]: ParamValidator
 }
 
+/**
+ * Schema for validating URL query parameters in Lexicon endpoints.
+ *
+ * Params are the query string parameters passed to queries, procedures,
+ * and subscriptions. Values must be scalars (boolean, integer, string)
+ * or arrays of scalars, as they need to be serializable to URL format.
+ *
+ * Provides methods for converting to/from URLSearchParams.
+ *
+ * @template TShape - The params shape type mapping names to validators
+ *
+ * @example
+ * ```ts
+ * const schema = new ParamsSchema({
+ *   limit: l.optional(l.integer({ minimum: 1, maximum: 100 })),
+ *   cursor: l.optional(l.string()),
+ * })
+ * ```
+ */
 export class ParamsSchema<
-  const TShape extends ParamsSchemaShape = {
-    [x: string]: Validator<Param | undefined>
-  },
+  const TShape extends ParamsSchemaShape = ParamsSchemaShape,
 > extends Schema<
   WithOptionalProperties<{
     [K in keyof TShape]: InferInput<TShape[K]>
@@ -47,14 +100,13 @@ export class ParamsSchema<
     super()
   }
 
-  get shapeValidators(): Map<string, Validator<Param | undefined>> {
+  get shapeValidators(): Map<string, ParamValidator> {
     const map = new Map(Object.entries(this.shape))
 
     return lazyProperty(this, 'shapeValidators', map)
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
-    // @TODO BETTER SUPPORT Input/Output
     if (!isPlainObject(input)) {
       return ctx.issueInvalidType(input, 'object')
     }
@@ -111,14 +163,22 @@ export class ParamsSchema<
     return ctx.success(copy ?? input)
   }
 
-  fromURLSearchParams(urlSearchParams: URLSearchParams): InferOutput<this> {
+  fromURLSearchParams(iterable: Iterable<[string, string]>): InferOutput<this> {
     const params: Record<string, Param> = {}
 
-    for (const [key, value] of urlSearchParams.entries()) {
-      const validator = this.shapeValidators.get(key)
+    // Compatibility with URLSearchParams not being iterable in some environments
+    const entries =
+      iterable instanceof URLSearchParams ? iterable.entries() : iterable
+
+    for (const [key, value] of entries) {
+      const validator = unwrapValidator(this.shapeValidators.get(key))
+      const expectsArray = validator instanceof ArraySchema
+      const scalarValidator = expectsArray
+        ? unwrapValidator(validator.validator)
+        : validator
 
       const coerced: ParamScalar =
-        validator instanceof StringSchema
+        scalarValidator instanceof StringSchema
           ? value
           : value === 'true'
             ? true
@@ -128,12 +188,13 @@ export class ParamsSchema<
                 ? Number(value)
                 : value
 
-      if (params[key] === undefined) {
-        params[key] = coerced
-      } else if (Array.isArray(params[key])) {
-        params[key].push(coerced)
+      const currentParam = params[key]
+      if (currentParam === undefined) {
+        params[key] = expectsArray ? [coerced] : coerced
+      } else if (Array.isArray(currentParam)) {
+        currentParam.push(coerced)
       } else {
-        params[key] = [params[key] as ParamScalar, coerced]
+        params[key] = [currentParam, coerced]
       }
     }
 
@@ -161,8 +222,53 @@ export class ParamsSchema<
   }
 }
 
+/**
+ * Creates a params schema for URL query parameters.
+ *
+ * Params schemas validate query string parameters for Lexicon endpoints.
+ * Values must be boolean, integer, string, or arrays of those types.
+ *
+ * @param properties - Object mapping parameter names to their validators
+ * @returns A new {@link ParamsSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Simple pagination params
+ * const paginationParams = l.params({
+ *   limit: l.optional(l.withDefault(l.integer({ minimum: 1, maximum: 100 }), 50)),
+ *   cursor: l.optional(l.string()),
+ * })
+ *
+ * // Required parameter
+ * const actorParams = l.params({
+ *   actor: l.string({ format: 'at-identifier' }),
+ * })
+ *
+ * // Array parameter (multiple values)
+ * const filterParams = l.params({
+ *   tags: l.optional(l.array(l.string())),
+ * })
+ *
+ * // Convert from URL
+ * const urlParams = new URLSearchParams('limit=25&cursor=abc')
+ * const validated = paginationParams.fromURLSearchParams(urlParams)
+ *
+ * // Convert to URL
+ * const searchParams = paginationParams.toURLSearchParams({ limit: 25 })
+ * ```
+ */
 export const params = /*#__PURE__*/ memoizedOptions(function params<
   const TShape extends ParamsSchemaShape = NonNullable<unknown>,
 >(properties: TShape = {} as TShape) {
   return new ParamsSchema<TShape>(properties)
 })
+
+function unwrapValidator(schema?: Validator): Validator | undefined {
+  while (
+    schema instanceof OptionalSchema ||
+    schema instanceof WithDefaultSchema
+  ) {
+    schema = schema.validator
+  }
+  return schema
+}

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,