@atproto/lex-schema 0.0.11 → 0.0.13

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>,
@@ -17,6 +39,8 @@ export class RefSchema<const TValidator extends Validator>
   >
   implements WrappedValidator<TValidator>
 {
+  readonly type = 'ref' as const
+
   #getter: RefSchemaGetter<TValidator>
 
   constructor(getter: RefSchemaGetter<TValidator>) {
@@ -41,6 +65,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,15 +1,32 @@
 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> {
+  readonly type = 'regexp' as const
+
   constructor(public readonly pattern: RegExp) {
     super()
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (typeof input !== 'string') {
-      return ctx.issueInvalidType(input, 'string')
+      return ctx.issueUnexpectedType(input, 'string')
     }
 
     if (!this.pattern.test(input)) {
@@ -20,6 +37,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.test.ts

@@ -1,5 +1,6 @@
-import { describe, expect, it } from 'vitest'
-import { string } from './string.js'
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { Infer, UnknownString } from '../core.js'
+import { StringSchemaOptions, string } from './string.js'
 import { token } from './token.js'
 import { withDefault } from './with-default.js'
 
@@ -610,4 +611,100 @@ describe('StringSchema', () => {
       expect(result.success).toBe(true)
     })
   })
+
+  describe('knownValues option', () => {
+    it('allows omitting knownValues at runtime', () => {
+      string<{ knownValues: ['active', 'inactive'] }>()
+
+      // @ts-expect-error format requires options to be set
+      string<{ knownValues: ['active', 'inactive']; format: 'did' }>()
+
+      // @ts-expect-error any options, besides knownValues, must be provided
+      string<{ knownValues: ['active', 'inactive']; minLength: 5 }>()
+
+      string<{
+        knownValues: ['john.doe', 'someone.else']
+        format: 'handle'
+      }>({
+        format: 'handle',
+      })
+
+      string<{
+        knownValues: ['john.doe', 'someone.else']
+      }>({
+        // Being *more* precise than the generic if fine
+        format: 'handle',
+      })
+
+      string<{
+        knownValues: ['did', 'inactive']
+        format: 'did'
+      }>({
+        // @ts-expect-error does not match format form generic constraint
+        format: 'handle',
+      })
+
+      string<{
+        knownValues: ['active', 'inactive']
+        minLength: 10
+      }>({
+        minLength: 10,
+      })
+
+      string<{
+        knownValues: ['active', 'inactive']
+        minLength: 5
+      }>({
+        // @ts-expect-error mismatch
+        minLength: 10,
+      })
+    })
+  })
+
+  it('properly types knownValues in parameters', () => {
+    const schema = string({
+      knownValues: ['active', 'inactive'],
+    })
+    type SchemaType = Infer<typeof schema>
+    expectTypeOf<{
+      foo: SchemaType
+    }>().toMatchObjectType<{
+      foo: 'active' | 'inactive' | UnknownString
+    }>()
+    expectTypeOf<{
+      foo: SchemaType
+    }>().not.toMatchObjectType<{
+      foo: string
+    }>()
+    expectTypeOf<{
+      foo: SchemaType
+    }>().not.toMatchObjectType<{
+      foo: 'active' | 'inactive'
+    }>()
+    expectTypeOf<{
+      foo: SchemaType
+    }>().not.toMatchObjectType<{
+      foo: UnknownString
+    }>()
+  })
+
+  it('type string<any>() as string', () => {
+    const schema = string<any>()
+    type SchemaType = Infer<typeof schema>
+    expectTypeOf<{
+      foo: SchemaType
+    }>().toMatchObjectType<{
+      foo: string
+    }>()
+  })
+
+  it('type string<StringSchemaOptions>({}) as string', () => {
+    const schema = string<StringSchemaOptions>({})
+    type SchemaType = Infer<typeof schema>
+    expectTypeOf<{
+      foo: SchemaType
+    }>().toMatchObjectType<{
+      foo: string
+    }>()
+  })
 })

package/src/schema/string.ts

@@ -1,49 +1,93 @@
 import { graphemeLen, ifCid, utf8Len } from '@atproto/lex-data'
 import {
   InferStringFormat,
+  Restricted,
   Schema,
   StringFormat,
+  UnknownString,
   ValidationContext,
   isStringFormat,
 } from '../core.js'
+import { IfAny } from '../util/if-any.js'
 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 knownValues - Known string literal values for type narrowing
+ * @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
+  knownValues?: readonly string[]
   minLength?: number
   maxLength?: number
   minGraphemes?: number
   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<
-  TOptions extends { format: infer F extends StringFormat }
-    ? InferStringFormat<F>
-    : string
+  IfAny<
+    TOptions,
+    string,
+    TOptions extends { format: infer F extends StringFormat }
+      ? InferStringFormat<F>
+      : TOptions extends { knownValues: readonly (infer V extends string)[] }
+        ? V | UnknownString
+        : string
+  >
 > {
-  constructor(readonly options?: TOptions) {
+  readonly type = 'string' as const
+
+  // @NOTE since the _string utility allows omitting knownValues when TOptions
+  // *does* include it (since it's only used for typing), we cannot type options
+  // as TOptions directly since it may not actually include knownValues at
+  // runtime, making schema.options.knownValues potentially undefined even when
+  // TOptions includes it.
+  readonly options: StringSchemaOptions
+
+  constructor(options: TOptions) {
     super()
+    this.options = options
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     const str = coerceToString(input)
     if (str == null) {
-      return ctx.issueInvalidType(input, 'string')
+      return ctx.issueUnexpectedType(input, 'string')
     }
 
     let lazyUtf8Len: number
 
-    const minLength = this.options?.minLength
+    const minLength = this.options.minLength
     if (minLength != null) {
       if ((lazyUtf8Len ??= utf8Len(str)) < minLength) {
         return ctx.issueTooSmall(str, 'string', minLength, lazyUtf8Len)
       }
     }
 
-    const maxLength = this.options?.maxLength
+    const maxLength = this.options.maxLength
     if (maxLength != null) {
       // Optimization: we can avoid computing the UTF-8 length if the maximum
       // possible length, in bytes, of the input JS string is smaller than the
@@ -57,7 +101,7 @@ export class StringSchema<
 
     let lazyGraphLen: number
 
-    const minGraphemes = this.options?.minGraphemes
+    const minGraphemes = this.options.minGraphemes
     if (minGraphemes != null) {
       // Optimization: avoid counting graphemes if the length check already fails
       if (str.length < minGraphemes) {
@@ -67,14 +111,14 @@ export class StringSchema<
       }
     }
 
-    const maxGraphemes = this.options?.maxGraphemes
+    const maxGraphemes = this.options.maxGraphemes
     if (maxGraphemes != null) {
       if ((lazyGraphLen ??= graphemeLen(str)) > maxGraphemes) {
         return ctx.issueTooBig(str, 'grapheme', maxGraphemes, lazyGraphLen)
       }
     }
 
-    const format = this.options?.format
+    const format = this.options.format
     if (format != null && !isStringFormat(str, format)) {
       return ctx.issueInvalidFormat(str, format)
     }
@@ -123,8 +167,57 @@ export function coerceToString(input: unknown): string | null {
   }
 }
 
-export const string = /*#__PURE__*/ memoizedOptions(function <
-  const O extends StringSchemaOptions = NonNullable<unknown>,
->(options?: StringSchemaOptions & O) {
-  return new StringSchema<O>(options)
-})
+function _string(): StringSchema<NonNullable<unknown>>
+function _string<
+  // Allow calling `string<{ knownValues: [...] }>()` without passing an options
+  // object, since knownValues is only used for typing and has no runtime
+  // effect, so it can be safely omitted at runtime.
+  const TOptions extends {
+    knownValues: StringSchemaOptions['knownValues']
+  } & {
+    [K in Exclude<
+      keyof StringSchemaOptions,
+      'knownValues'
+    >]?: Restricted<`An options argument is required when using the "${K}" option`>
+  },
+>(): StringSchema<
+  IfAny<TOptions, any, { knownValues: TOptions['knownValues'] }>
+>
+function _string<const TOptions extends StringSchemaOptions>(
+  // If TOptions is explicitly provided (e.g. `string<{ ... }>({ ... })`), we
+  // allow the actual options argument to omit the "knownValues" property since
+  // it's only used for inferring the type and has no runtime effect.
+  options: TOptions | Omit<TOptions, 'knownValues'>,
+): StringSchema<TOptions>
+function _string(options: StringSchemaOptions = {}) {
+  return new StringSchema(options)
+}
+
+/**
+ * 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(_string)

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)