@atproto/lex-schema 0.0.12 → 0.0.14

package/src/core/schema.ts

@@ -1,3 +1,4 @@
+import { lazyProperty } from '../util/lazy-property.js'
 import {
   InferInput,
   InferOutput,
@@ -11,13 +12,13 @@ import {
  * Options for parsing operations.
  * Excludes the `mode` option as it is implicitly set to `"parse"`.
  */
-type ParseOptions = Omit<ValidationOptions, 'mode'>
+export type ParseOptions = Omit<ValidationOptions, 'mode'>
 
 /**
  * Options for validation operations.
  * Excludes the `mode` option as it is implicitly set to `"validate"`.
  */
-type ValidateOptions = Omit<ValidationOptions, 'mode'>
+export type ValidateOptions = Omit<ValidationOptions, 'mode'>
 
 /**
  * Internal type structure for schema type inference.
@@ -58,7 +59,7 @@ export interface SchemaInternals<out TInput = unknown, out TOutput = TInput> {
  * class MySchema extends Schema<string> {
  *   validateInContext(input: unknown, ctx: ValidationContext): ValidationResult {
  *     if (typeof input !== 'string') {
- *       return ctx.issueInvalidType(input, 'string')
+ *       return ctx.issueUnexpectedType(input, 'string')
  *     }
  *     return ctx.success(input)
  *   }
@@ -66,7 +67,7 @@ export interface SchemaInternals<out TInput = unknown, out TOutput = TInput> {
  *
  * const schema = new MySchema()
  * schema.assert('hello')     // OK
- * schema.assert(123)         // Throws ValidationError
+ * schema.assert(123)         // Throws LexValidationError
  * schema.matches('hello')    // true
  * schema.matches(123)        // false
  * ```
@@ -88,6 +89,12 @@ export abstract class Schema<
    */
   declare readonly ['__lex']: TInternals
 
+  // Needed to discriminate multiple schema types when used in unions. Without
+  // this, Typescript could allow an EnumSchema<"foo" | "bar"> to be used where
+  // a StringSchema is expected, since they would both be structurally
+  // compatible.
+  abstract readonly type: string
+
   /**
    * Performs validation of the input value within a validation context.
    *
@@ -184,12 +191,12 @@ export abstract class Schema<
    *
    * Unlike {@link validate}, this method allows the schema to transform
    * the input value (e.g., applying default values, type coercion).
-   * Throws a {@link ValidationError} if the input is invalid.
+   * Throws a {@link LexValidationError} if the input is invalid.
    *
    * @param input - The value to parse
    * @param options - Optional parsing configuration
    * @returns The parsed and potentially transformed value
-   * @throws {ValidationError} If the input fails validation
+   * @throws {LexValidationError} If the input fails validation
    *
    * @example
    * ```typescript
@@ -238,13 +245,13 @@ export abstract class Schema<
    *
    * Unlike {@link parse}, this method requires the input to exactly match
    * the schema without any transformations (no defaults applied, no coercion).
-   * Throws a {@link ValidationError} if the input is invalid or would require transformation.
+   * Throws a {@link LexValidationError} if the input is invalid or would require transformation.
    *
    * @typeParam I - The input type (preserved in the return type)
    * @param input - The value to validate
    * @param options - Optional validation configuration
    * @returns The validated input with narrowed type
-   * @throws {ValidationError} If the input fails validation or requires transformation
+   * @throws {LexValidationError} If the input fails validation or requires transformation
    *
    * @example
    * ```typescript
@@ -291,104 +298,111 @@ export abstract class Schema<
 
   // @NOTE Dollar-prefixed aliases
   //
-  // The built lexicons namespaces export utility functions that allow accessing
-  // the schema's methods without the need to specify ".main." as part of the
-  // namespace. This way, a utility for a particular record type can be called
-  // like "app.bsky.feed.post.<utility>()" instead of
-  // "app.bsky.feed.post.main.<utility>()". Because those utilities could
-  // conflict with other schemas (e.g. if there is a lexicon definition at
-  // "#<utility>"), those exported utilities will be prefixed with "$". In order
-  // to be able to consistently call the utilities, when using the "main" and
-  // non "main" definitions, we also expose the same methods with a "$" prefix.
-  // Thanks to this, both of the following call will be possible:
+  // The `lex-builder` lib generates namespaced utility functions that allow
+  // accessing the schema's methods without the need to specify the ".main."
+  // part of the namespace. This allows utilities for a particular record type
+  // to be called like "app.bsky.feed.post.<utility>()" instead of
+  // "app.bsky.feed.post.main.<utility>()".
+  //
+  // Because those utilities could conflict with other schemas (e.g. if there is
+  // a lexicon definition with the same name as the "<utility>"), those exported
+  // utilities will be prefixed with "$".
+  //
+  // Similarly, since those utilities are defined as simple "const", they are
+  // also bound (using JS's .bind) to the schema instance, so that they can be
+  // used without worrying about the context (e.g. "app.bsky.feed.post.$parse()"
+  // will work regardless of how it is imported or called).
+  //
+  // In order to provide the same functionalities for non-main definitions, we
+  // also define those aliases directly on the schema instance, so that they can
+  // be used in the same way as the utilities generated by "lex-builder". For
+  // example, if there is a non-main definition "app.bsky.feed.defs.postView",
+  // it will also be possible to call "app.bsky.feed.defs.postView.$parse()".
+  //
+  // These methods are also "bound" to the instance so that they can be used
+  // exactly like the utilities generated by "lex-builder", without worrying
+  // about the context.
+  //
+  // There are two ways we could "bind" those methods to the instance:
+  // 1. Define them as getters that return the bound method (e.g. get $parse() {
+  //    return this.parse.bind(this) })
+  // 2. Define them as properties that are initialized in the constructor (e.g.
+  //    this.$parse = this.parse.bind(this))
   //
-  // - "app.bsky.feed.post.$parse(...)" // calls a utility function created by "lex build"
-  // - "app.bsky.feed.defs.postView.$parse(...)" // uses the alias defined below on the schema instance
+  // Since a **lot** of those methods would end-up being created in systems that
+  // contains many schemas (e.g. the appview), we choose the first approach
+  // (getters) in order to avoid the overhead of creating all those bound
+  // functions upfront when instantiating the schemas.
 
   /**
-   * Alias for {@link assert} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link assert} for compatibility with generated utilities.
    * @see {@link assert}
    */
-  $assert(input: unknown): asserts input is InferInput<this> {
-    return this.assert(input)
+  get $assert(): typeof this.assert {
+    return lazyProperty(this, '$assert', this.assert.bind(this))
   }
 
   /**
-   * Alias for {@link check} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link check} for compatibility with generated utilities.
    * @see {@link check}
    */
-  $check(input: unknown): void {
-    return this.check(input)
+  get $check(): typeof this.check {
+    return lazyProperty(this, '$check', this.check.bind(this))
   }
 
   /**
-   * Alias for {@link cast} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link cast} for compatibility with generated utilities.
    * @see {@link cast}
    */
-  $cast<I>(input: I): I & InferInput<this> {
-    return this.cast(input)
+  get $cast(): typeof this.cast {
+    return lazyProperty(this, '$cast', this.cast.bind(this))
   }
 
   /**
-   * Alias for {@link matches} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link matches} for compatibility with generated utilities.
    * @see {@link matches}
    */
-  $matches(input: unknown): input is InferInput<this> {
-    return this.matches(input)
+  get $matches(): typeof this.matches {
+    return lazyProperty(this, '$matches', this.matches.bind(this))
   }
 
   /**
-   * Alias for {@link ifMatches} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link ifMatches} for compatibility with generated utilities.
    * @see {@link ifMatches}
    */
-  $ifMatches<I>(input: I): (I & InferInput<this>) | undefined {
-    return this.ifMatches(input)
+  get $ifMatches(): typeof this.ifMatches {
+    return lazyProperty(this, '$ifMatches', this.ifMatches.bind(this))
   }
 
   /**
-   * Alias for {@link parse} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link parse} for compatibility with generated utilities.
    * @see {@link parse}
    */
-  $parse(input: unknown, options?: ValidateOptions): InferOutput<this> {
-    return this.parse(input, options)
+  get $parse(): typeof this.parse {
+    return lazyProperty(this, '$parse', this.parse.bind(this))
   }
 
   /**
-   * Alias for {@link safeParse} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link safeParse} for compatibility with generated utilities.
    * @see {@link safeParse}
    */
-  $safeParse(
-    input: unknown,
-    options?: ValidateOptions,
-  ): ValidationResult<InferOutput<this>> {
-    return this.safeParse(input, options)
+  get $safeParse(): typeof this.safeParse {
+    return lazyProperty(this, '$safeParse', this.safeParse.bind(this))
   }
 
   /**
-   * Alias for {@link validate} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link validate} for compatibility with generated utilities.
    * @see {@link validate}
    */
-  $validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {
-    return this.validate(input, options)
+  get $validate(): typeof this.validate {
+    return lazyProperty(this, '$validate', this.validate.bind(this))
   }
 
   /**
-   * Alias for {@link safeValidate} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link safeValidate} for compatibility with generated utilities.
    * @see {@link safeValidate}
    */
-  $safeValidate<I>(
-    input: I,
-    options?: ValidateOptions,
-  ): ValidationResult<I & InferInput<this>> {
-    return this.safeValidate(input, options)
+  get $safeValidate(): typeof this.safeValidate {
+    return lazyProperty(this, '$safeValidate', this.safeValidate.bind(this))
   }
 }

package/src/core/string-format.ts

@@ -9,9 +9,9 @@ import {
   RecordKeyString,
   TidString,
   UriString,
+  isDatetimeString,
   isValidAtIdentifier as isValidAtId,
   isValidAtUri,
-  isValidDatetime,
   isValidDid,
   isValidHandle,
   isValidLanguage,
@@ -26,6 +26,19 @@ import { CheckFn } from '../util/assertion-util.js'
 // Individual string format types and type guards
 // -----------------------------------------------------------------------------
 
+// Re-exporting from @atproto/syntax without modification to preserve types and
+// documentation for types and utilities that are already well-defined there.
+// @TODO rework other string formats in @atproto/syntax to follow this pattern
+// and re-export here, e.g. language tags, NSIDs, record keys, etc.
+export {
+  type DatetimeString,
+  asDatetimeString,
+  currentDatetimeString,
+  ifDatetimeString,
+  isDatetimeString,
+  toDatetimeString,
+} from '@atproto/syntax'
+
 /**
  * Type guard that checks if a value is a valid AT identifier (DID or handle).
  *
@@ -74,22 +87,6 @@ export const isCidString = ((v) => validateCidString(v)) as CheckFn<CidString>
  */
 export type CidString = string
 
-/**
- * Type guard that checks if a value is a valid datetime string.
- *
- * @param value - The value to check
- * @returns `true` if the value is a valid datetime string
- */
-export const isDatetimeString: CheckFn<DatetimeString> = isValidDatetime
-export type {
-  /**
-   * An ISO 8601 datetime string.
-   *
-   * @example `"2024-01-15T12:30:00.000Z"`
-   */
-  DatetimeString,
-}
-
 /**
  * Type guard that checks if a value is a valid DID string.
  *

package/src/core/validation-error.ts

@@ -19,7 +19,7 @@ import {
  *
  * @example
  * ```typescript
- * const error = new ValidationError([
+ * const error = new LexValidationError([
  *   new IssueInvalidType(['user', 'age'], 'hello', ['number'])
  * ])
  * console.log(error.message)
@@ -30,8 +30,8 @@ import {
  * // { error: 'InvalidRequest', message: '...', issues: [...] }
  * ```
  */
-export class ValidationError extends LexError {
-  name = 'ValidationError'
+export class LexValidationError extends LexError<'InvalidRequest'> {
+  name = 'LexValidationError'
 
   /**
    * The list of validation issues that caused this error.
@@ -59,9 +59,9 @@ export class ValidationError extends LexError {
   /**
    * Converts the error to a JSON-serializable object.
    *
-   * @returns An object containing the error details and all issues in JSON format
+   * @returns An object containing the error details and issues details
    */
-  toJSON() {
+  override toJSON() {
     return {
       ...super.toJSON(),
       issues: this.issues.map((issue) => issue.toJSON()),
@@ -81,23 +81,23 @@ export class ValidationError extends LexError {
    * ```typescript
    * const failures = schemas.map(s => s.safeValidate(data)).filter(r => !r.success)
    * if (failures.length === schemas.length) {
-   *   throw ValidationError.fromFailures(failures)
+   *   throw LexValidationError.fromFailures(failures)
    * }
    * ```
    */
   static fromFailures(
-    failures: ResultFailure<ValidationError>[],
-  ): ValidationError {
+    failures: readonly ResultFailure<LexValidationError>[],
+  ): LexValidationError {
     if (failures.length === 1) return failureReason(failures[0])
     const issues = failures.flatMap(extractFailureIssues)
-    return new ValidationError(issues, {
+    return new LexValidationError(issues, {
       // Keep the original errors as the cause chain
       cause: failures.map(failureReason),
     })
   }
 }
 
-function extractFailureIssues(result: ResultFailure<ValidationError>) {
+function extractFailureIssues(result: ResultFailure<LexValidationError>) {
   return result.reason.issues
 }
 

package/src/core/validation-issue.ts

@@ -1,4 +1,4 @@
-import { ifCid, isPlainObject } from '@atproto/lex-data'
+import { ifCid, isLegacyBlobRef, isPlainObject } from '@atproto/lex-data'
 import { PropertyKey } from './property-key.js'
 
 /**
@@ -260,7 +260,7 @@ export class IssueTooSmall extends Issue {
 
 function stringifyExpectedType(expected: string): string {
   if (expected === '$typed') {
-    return 'an object or record which includes a "$type" property'
+    return 'an object which includes the "$type" property'
   }
   return expected
 }
@@ -295,6 +295,7 @@ function stringifyType(value: unknown): string {
       if (value === null) return 'null'
       if (Array.isArray(value)) return 'array'
       if (ifCid(value)) return 'cid'
+      if (isLegacyBlobRef(value)) return 'legacy-blob'
       if (value instanceof Date) return 'date'
       if (value instanceof RegExp) return 'regexp'
       if (value instanceof Map) return 'map'

package/src/core/validator.ts

@@ -1,6 +1,6 @@
 import { PropertyKey } from './property-key.js'
 import { ResultFailure, ResultSuccess, failure, success } from './result.js'
-import { ValidationError } from './validation-error.js'
+import { LexValidationError } from './validation-error.js'
 import {
   Issue,
   IssueInvalidFormat,
@@ -20,16 +20,16 @@ import {
 export type ValidationSuccess<Value = unknown> = ResultSuccess<Value>
 
 /**
- * Represents a failed validation result containing a {@link ValidationError}.
+ * Represents a failed validation result containing a {@link LexValidationError}.
  */
-export type ValidationFailure = ResultFailure<ValidationError>
+export type ValidationFailure = ResultFailure<LexValidationError>
 
 /**
  * Discriminated union representing the outcome of a validation operation.
  *
  * Check the `success` property to determine if validation passed or failed:
  * - If `success` is `true`, the `value` property contains the validated data
- * - If `success` is `false`, the `reason` property contains the {@link ValidationError}
+ * - If `success` is `false`, the `reason` property contains the {@link LexValidationError}
  *
  * @typeParam Value - The type of the validated value on success
  *
@@ -39,7 +39,7 @@ export type ValidationFailure = ResultFailure<ValidationError>
  * if (result.success) {
  *   // result.value is string
  * } else {
- *   // result.reason is ValidationError
+ *   // result.reason is LexValidationError
  * }
  * ```
  */
@@ -192,7 +192,7 @@ export type ValidationOptions = {
  * class MyValidator implements Validator {
  *   validateInContext(input: unknown, ctx: ValidationContext): ValidationResult {
  *     if (typeof input !== 'string') {
- *       return ctx.issueInvalidType(input, 'string')
+ *       return ctx.issueUnexpectedType(input, 'string')
  *     }
  *     return ctx.success(input)
  *   }
@@ -326,7 +326,7 @@ export class ValidationContext {
       if (this.issues.length > 0) {
         // Validator returned a success but issues were added via the context.
         // This means the overall validation failed.
-        return failure(new ValidationError(Array.from(this.issues)))
+        return failure(new LexValidationError(Array.from(this.issues)))
       }
 
       if (this.options.mode !== 'parse' && !Object.is(result.value, input)) {
@@ -341,7 +341,7 @@ export class ValidationContext {
         // another.
 
         // This if block comes before the next one because 'this.issues' will
-        // end-up being appended to the returned ValidationError (see the
+        // end-up being appended to the returned LexValidationError (see the
         // "failure" method below), resulting in a more complete error report.
         return this.issueInvalidValue(input, [result.value])
       }
@@ -377,6 +377,15 @@ export class ValidationContext {
     K extends PropertyKey & keyof I,
     V extends Validator,
   >(input: I, key: K, validator: V): ValidationResult<InferInput<V>> {
+    // @NOTE we could add support for recursive schemas by keeping track of
+    // "parent" objects in the context and checking for circular references
+    // here. This would allow us to validate recursive structures without
+    // hitting maximum call stack errors, and would also allow us to provide
+    // better error messages for circular reference issues. However, this is not
+    // a priority at the moment as recursive structures are not supported in
+    // the context of AT Protocol lexicons, and we can always add this in the
+    // future if needed.
+
     // Instead of creating a new context, we just push/pop the path segment.
     this.currentPath.push(key)
     try {
@@ -416,7 +425,7 @@ export class ValidationContext {
    * @param reason - The validation error
    * @returns A failed validation result
    */
-  failure(reason: ValidationError): ValidationFailure {
+  failure(reason: LexValidationError): ValidationFailure {
     return failure(reason)
   }
 
@@ -429,7 +438,7 @@ export class ValidationContext {
    * @returns A failed validation result
    */
   issue(issue: Issue) {
-    return this.failure(new ValidationError([...this.issues, issue]))
+    return this.failure(new LexValidationError([...this.issues, issue]))
   }
 
   /**
@@ -443,6 +452,17 @@ export class ValidationContext {
     return this.issue(new IssueInvalidValue(this.path, input, values))
   }
 
+  /**
+   * Creates a failure for an invalid type.
+   *
+   * @param input - The actual value that was received
+   * @param expected - An array of expected type names
+   * @returns A failed validation result with an invalid type issue
+   */
+  issueInvalidType(input: unknown, expected: readonly string[]) {
+    return this.issue(new IssueInvalidType(this.path, input, expected))
+  }
+
   /**
    * Creates a failure for an invalid type.
    *
@@ -450,8 +470,8 @@ export class ValidationContext {
    * @param expected - The expected type name
    * @returns A failed validation result with an invalid type issue
    */
-  issueInvalidType(input: unknown, expected: string) {
-    return this.issue(new IssueInvalidType(this.path, input, [expected]))
+  issueUnexpectedType(input: unknown, expected: string) {
+    return this.issueInvalidType(input, [expected])
   }
 
   /**

package/src/helpers.test.ts

@@ -61,7 +61,7 @@ describe('InferMethodParams', () => {
         l.params({
           cursor: l.optional(l.integer()),
         }),
-        l.unknownObject(),
+        l.lexMap(),
       )
 
       type Params = l.InferMethodParams<typeof subscription>

package/src/helpers.ts

@@ -26,47 +26,81 @@ export function getMain<T extends object>(ns: Main<T>): T {
  * `ReadableStream`, etc.). This type is a placeholder to represent binary data
  * when not explicitly provided.
  */
-type BinaryData = Restricted<'Binary data'>
+export type BinaryData = Restricted<'Binary data'>
 
-export type InferMethodParams<M extends Procedure | Query | Subscription> =
-  InferOutput<M['parameters']>
+export type InferMethodParams<
+  M extends Procedure | Query | Subscription = Procedure | Query | Subscription,
+> =
+  M extends Procedure<any, infer TParams, any, any, any>
+    ? InferOutput<TParams>
+    : M extends Query<any, infer TParams, any, any>
+      ? InferOutput<TParams>
+      : M extends Subscription<any, infer TParams, any, any>
+        ? InferOutput<TParams>
+        : never
 
 export type InferMethodInput<
-  M extends Procedure | Query | Subscription,
+  M extends Procedure | Query | Subscription = Procedure | Query | Subscription,
   B = BinaryData,
-> = M extends Procedure ? InferPayload<M['input'], B> : undefined
+> =
+  M extends Procedure<any, any, infer TInput, any, any>
+    ? InferPayload<TInput, B>
+    : undefined
 
 export type InferMethodInputBody<
-  M extends Procedure | Query | Subscription,
+  M extends Procedure | Query | Subscription = Procedure | Query | Subscription,
   B = BinaryData,
-> = M extends Procedure ? InferPayloadBody<M['input'], B> : undefined
+> =
+  M extends Procedure<any, any, infer TInput, any, any>
+    ? InferPayloadBody<TInput, B>
+    : undefined
 
 export type InferMethodInputEncoding<
-  M extends Procedure | Query | Subscription,
-> = M extends Procedure ? InferPayloadEncoding<M['input']> : undefined
+  M extends Procedure | Query | Subscription = Procedure | Query | Subscription,
+> =
+  M extends Procedure<any, any, infer TInput, any, any>
+    ? InferPayloadEncoding<TInput>
+    : undefined
 
 export type InferMethodOutput<
-  M extends Procedure | Query | Subscription,
+  M extends Procedure | Query | Subscription = Procedure | Query | Subscription,
   B = BinaryData,
-> = M extends Procedure | Query ? InferPayload<M['output'], B> : undefined
+> =
+  M extends Procedure<any, any, any, infer TOutput, any>
+    ? InferPayload<TOutput, B>
+    : M extends Query<any, any, infer TOutput, any>
+      ? InferPayload<TOutput, B>
+      : undefined
 
 export type InferMethodOutputBody<
-  M extends Procedure | Query | Subscription,
+  M extends Procedure | Query | Subscription = Procedure | Query | Subscription,
   B = BinaryData,
-> = M extends Procedure | Query ? InferPayloadBody<M['output'], B> : undefined
+> =
+  M extends Procedure<any, any, any, infer TOutput, any>
+    ? InferPayloadBody<TOutput, B>
+    : M extends Query<any, any, infer TOutput, any>
+      ? InferPayloadBody<TOutput, B>
+      : undefined
 
 export type InferMethodOutputEncoding<
-  M extends Procedure | Query | Subscription,
-> = M extends Procedure | Query ? InferPayloadEncoding<M['output']> : undefined
+  M extends Procedure | Query | Subscription = Procedure | Query | Subscription,
+> =
+  M extends Procedure<any, any, any, infer TOutput, any>
+    ? InferPayloadEncoding<TOutput>
+    : M extends Query<any, any, infer TOutput, any>
+      ? InferPayloadEncoding<TOutput>
+      : undefined
 
 export type InferMethodMessage<
-  //
-  M extends Subscription,
-> = M extends Subscription ? InferOutput<M['message']> : undefined
+  M extends Procedure | Query | Subscription = Procedure | Query | Subscription,
+> =
+  M extends Subscription<any, any, infer TMessage, any>
+    ? InferOutput<TMessage>
+    : undefined
 
 export type InferMethodError<
   //
-  M extends Procedure | Query | Subscription,
+  M extends Procedure | Query | Subscription = Procedure | Query | Subscription,
 > = M extends { errors: readonly (infer E extends string)[] } ? E : never
 
 export const lexErrorDataSchema = object({

package/src/schema/array.ts

@@ -36,6 +36,8 @@ export class ArraySchema<const TItem extends Validator> extends Schema<
   Array<InferInput<TItem>>,
   Array<InferOutput<TItem>>
 > {
+  readonly type = 'array' as const
+
   constructor(
     readonly validator: TItem,
     readonly options: ArraySchemaOptions = {},
@@ -45,7 +47,7 @@ export class ArraySchema<const TItem extends Validator> extends Schema<
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (!Array.isArray(input)) {
-      return ctx.issueInvalidType(input, 'array')
+      return ctx.issueUnexpectedType(input, 'array')
     }
 
     const { minLength, maxLength } = this.options

package/src/schema/blob.ts

@@ -32,6 +32,7 @@ export type BlobSchemaOptions = BlobRefCheckOptions & {
 }
 
 export type { BlobRef, LegacyBlobRef }
+export { isBlobRef, isLegacyBlobRef }
 
 /**
  * Schema for validating blob references in AT Protocol.
@@ -53,6 +54,8 @@ export class BlobSchema<
 > extends Schema<
   TOptions extends { allowLegacy: true } ? BlobRef | LegacyBlobRef : BlobRef
 > {
+  readonly type = 'blob' as const
+
   constructor(readonly options?: TOptions) {
     super()
   }
@@ -68,7 +71,7 @@ export class BlobSchema<
           : null
 
     if (!blob) {
-      return ctx.issueInvalidType(input, 'blob')
+      return ctx.issueUnexpectedType(input, 'blob')
     }
 
     const accept = this.options?.accept