@atproto/lex-schema 0.0.15 → 0.0.17

package/src/core/schema.ts

@@ -47,7 +47,7 @@ export interface SchemaInternals<out TInput = unknown, out TOutput = TInput> {
  * - **Assertion methods**: `assert()`, `check()` - throw on invalid input
  * - **Type guard methods**: `matches()`, `ifMatches()` - return boolean or optional value
  * - **Parse methods**: `parse()`, `safeParse()` - allow value transformation/coercion
- * - **Validate methods**: `validate()`, `safeValidate()` - strict validation without coercion
+ * - **Validate methods**: `validate()`, `safeValidate()` - validation without coercion
  *
  * All methods are also available with a `$` prefix (e.g., `$parse()`, `$validate()`)
  * for consistent access in generated lexicon namespaces.
@@ -120,8 +120,11 @@ export abstract class Schema<out TInput = unknown, out TOutput = TInput>
    * will typically arise in generic contexts, where the narrowed type is not
    * needed.
    */
-  assert(input: unknown): asserts input is InferInput<this> {
-    const result = ValidationContext.validate(input, this)
+  assert(
+    input: unknown,
+    options?: ValidateOptions,
+  ): asserts input is InferInput<this> {
+    const result = this.safeValidate(input, options)
     if (!result.success) throw result.reason
   }
 
@@ -131,8 +134,8 @@ export abstract class Schema<out TInput = unknown, out TOutput = TInput>
    * every name in the call target to be declared with an explicit type
    * annotation. ts(2775)_" errors.
    */
-  check(input: unknown): void {
-    this.assert(input)
+  check(input: unknown, options?: ValidateOptions): void {
+    this.assert(input, options)
   }
 
   /**
@@ -140,8 +143,8 @@ export abstract class Schema<out TInput = unknown, out TOutput = TInput>
    * schema, otherwise throws. This is the same as calling {@link parse}() with
    * `mode: "validate"`.
    */
-  cast<I>(input: I): I & InferInput<this> {
-    const result = ValidationContext.validate(input, this)
+  cast<I>(input: I, options?: ValidateOptions): I & InferInput<this> {
+    const result = this.safeValidate(input, options)
     if (result.success) return result.value
     throw result.reason
   }
@@ -149,9 +152,6 @@ export abstract class Schema<out TInput = unknown, out TOutput = TInput>
   /**
    * Type guard that checks if the input matches this schema.
    *
-   * @param input - The value to check
-   * @returns `true` if the input is valid according to this schema
-   *
    * @example
    * ```typescript
    * if (schema.matches(data)) {
@@ -160,8 +160,11 @@ export abstract class Schema<out TInput = unknown, out TOutput = TInput>
    * }
    * ```
    */
-  matches<I>(input: I): input is I & InferInput<this> {
-    const result = ValidationContext.validate(input, this)
+  matches<I>(
+    input: I,
+    options?: ValidateOptions,
+  ): input is I & InferInput<this> {
+    const result = this.safeValidate(input, options)
     return result.success
   }
 
@@ -171,9 +174,6 @@ export abstract class Schema<out TInput = unknown, out TOutput = TInput>
    * This is useful for optional filtering operations where you want to
    * conditionally extract values that match a schema.
    *
-   * @param input - The value to check
-   * @returns The input value with narrowed type if valid, otherwise `undefined`
-   *
    * @example
    * ```typescript
    * const validData = schema.ifMatches(data)
@@ -183,8 +183,11 @@ export abstract class Schema<out TInput = unknown, out TOutput = TInput>
    * }
    * ```
    */
-  ifMatches<I>(input: I): (I & InferInput<this>) | undefined {
-    return this.matches(input) ? input : undefined
+  ifMatches<I>(
+    input: I,
+    options?: ValidateOptions,
+  ): (I & InferInput<this>) | undefined {
+    return this.matches(input, options) ? input : undefined
   }
 
   /**

package/src/core/string-format.ts

@@ -1,3 +1,4 @@
+import { isValidISODateString } from 'iso-datestring-validator'
 import { validateCidString } from '@atproto/lex-data'
 import {
   AtIdentifierString,
@@ -48,6 +49,26 @@ export {
   isDatetimeString,
 } from '@atproto/syntax'
 
+/**
+ * Matches any ISO-ish datetime string. This is a more lenient check than
+ * the strict {@link isDatetimeString} guard, which only allows datetimes that
+ * fully conform to the AT Protocol specification (e.g. must include timezone).
+ */
+export function isDatetimeStringLoose<I>(
+  input: I,
+): input is I & DatetimeString {
+  // @NOTE the returned type assertion is inaccurate wrt. the DatetimeString
+  // type definition. A more accurate solution would be to use a branded type
+  // instead of a template literal for the "datetime" format
+  if (typeof input !== 'string') return false
+  try {
+    return isValidISODateString(input)
+  } catch {
+    // @NOTE isValidISODateString throws on some inputs
+    return false
+  }
+}
+
 // DatetimeString utilities
 export { currentDatetimeString, toDatetimeString } from '@atproto/syntax'
 
@@ -223,23 +244,39 @@ type StringFormats = {
 export type StringFormat = Extract<keyof StringFormats, string>
 
 const stringFormatVerifiers: {
-  readonly [K in StringFormat]: CheckFn<StringFormats[K]>
+  readonly [K in StringFormat]: readonly [
+    strict: CheckFn<StringFormats[K]>,
+    loose?: CheckFn<StringFormats[K]>,
+  ]
 } = /*#__PURE__*/ Object.freeze({
   __proto__: null,
 
-  'at-identifier': isAtIdentifierString,
-  'at-uri': isAtUriString,
-  cid: isCidString,
-  datetime: isDatetimeString,
-  did: isDidString,
-  handle: isHandleString,
-  language: isLanguageString,
-  nsid: isNsidString,
-  'record-key': isRecordKeyString,
-  tid: isTidString,
-  uri: isUriString,
+  'at-identifier': [isAtIdentifierString],
+  'at-uri': [isAtUriString],
+  cid: [isCidString],
+  datetime: [isDatetimeString, isDatetimeStringLoose],
+  did: [isDidString],
+  handle: [isHandleString],
+  language: [isLanguageString],
+  nsid: [isNsidString],
+  'record-key': [isRecordKeyString],
+  tid: [isTidString],
+  uri: [isUriString],
 })
 
+export type StringFormatValidationOptions = {
+  /**
+   * Allows to be more lenient in validation by using a "loose" verification
+   * function, if available. The behavior of the loose verifier depends on the
+   * specific format, but generally it may allow for a wider range of valid
+   * inputs, including values that are not compliant with the AT Protocol
+   * specification.
+   *
+   * @default true
+   */
+  strict?: boolean
+}
+
 /**
  * Infers the string type for a given format name.
  *
@@ -277,12 +314,18 @@ export type InferStringFormat<F extends StringFormat> = F extends StringFormat
 export function isStringFormat<I extends string, F extends StringFormat>(
   input: I,
   format: F,
+  options?: StringFormatValidationOptions,
 ): input is I & StringFormats[F] {
   const formatVerifier = stringFormatVerifiers[format]
   // Fool-proof
   if (!formatVerifier) throw new TypeError(`Unknown string format: ${format}`)
 
-  return formatVerifier(input)
+  const check: CheckFn<StringFormats[F]> =
+    options?.strict === false
+      ? formatVerifier[1] ?? formatVerifier[0]
+      : formatVerifier[0]
+
+  return check(input)
 }
 
 /**
@@ -304,8 +347,9 @@ export function isStringFormat<I extends string, F extends StringFormat>(
 export function assertStringFormat<I extends string, F extends StringFormat>(
   input: I,
   format: F,
+  options?: StringFormatValidationOptions,
 ): asserts input is I & StringFormats[F] {
-  if (!isStringFormat(input, format)) {
+  if (!isStringFormat(input, format, options)) {
     throw new TypeError(`Invalid string format (${format}): ${input}`)
   }
 }
@@ -332,8 +376,9 @@ export function assertStringFormat<I extends string, F extends StringFormat>(
 export function asStringFormat<I extends string, F extends StringFormat>(
   input: I,
   format: F,
+  options?: StringFormatValidationOptions,
 ): I & StringFormats[F] {
-  assertStringFormat(input, format)
+  assertStringFormat(input, format, options)
   return input
 }
 
@@ -361,8 +406,9 @@ export function asStringFormat<I extends string, F extends StringFormat>(
 export function ifStringFormat<I extends string, F extends StringFormat>(
   input: I,
   format: F,
+  options?: StringFormatValidationOptions,
 ): undefined | (I & StringFormats[F]) {
-  return isStringFormat(input, format) ? input : undefined
+  return isStringFormat(input, format, options) ? input : undefined
 }
 
 /**

package/src/core/validation-error.ts

@@ -23,7 +23,7 @@ import {
  *   new IssueInvalidType(['user', 'age'], 'hello', ['number'])
  * ])
  * console.log(error.message)
- * // "Expected number value type at $.user.age (got string)"
+ * // "Expected integer value type (got "some-string") at $.user.age"
  *
  * console.log(error.issues.length) // 1
  * console.log(error.toJSON())
@@ -46,7 +46,7 @@ export class LexValidationError
    * Issues are aggregated when possible (e.g., multiple invalid type issues
    * at the same path are combined into a single issue listing all expected types).
    */
-  readonly issues: Issue[]
+  readonly issues: readonly Issue[]
 
   /**
    * Creates a new validation error from a list of issues.

package/src/core/validation-issue.ts

@@ -1,5 +1,8 @@
 import { ifCid, isLegacyBlobRef, isPlainObject } from '@atproto/lex-data'
 
+const STRING_PREVIEW_MAX_LENGTH = 48
+const STRING_PREVIEW_TRUNCATED_SUFFIX = '…'
+
 /**
  * Abstract base class for all validation issues.
  *
@@ -120,7 +123,7 @@ export class IssueInvalidType extends Issue {
   }
 
   override get message(): string {
-    return `Expected ${oneOf(this.expected.map(stringifyExpectedType))} value type (got ${stringifyType(this.input)})`
+    return `Expected ${oneOf(this.expected.map(stringifyExpectedType))} value type (got ${stringifyValue(this.input)})`
   }
 
   toJSON() {
@@ -289,55 +292,36 @@ function oneOf(arr: readonly string[]): string {
   return `one of ${arr.slice(0, -1).join(', ')} or ${arr.at(-1)}`
 }
 
-function stringifyType(value: unknown): string {
-  switch (typeof value) {
-    case 'object':
-      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'
-      if (value instanceof Set) return 'set'
-      return 'object'
-    case 'number':
-      if (Number.isInteger(value) && Number.isSafeInteger(value)) {
-        return 'integer'
-      }
-      if (Number.isNaN(value)) {
-        return 'NaN'
-      }
-      if (value === Infinity) {
-        return 'Infinity'
-      }
-      if (value === -Infinity) {
-        return '-Infinity'
-      }
-      return 'float'
-    default:
-      return typeof value
-  }
-}
-
 function stringifyValue(value: unknown): string {
   switch (typeof value) {
     case 'bigint':
       return `${value}n`
     case 'number':
-    case 'string':
     case 'boolean':
-      return JSON.stringify(value)
+      return String(value)
+    case 'string':
+      return JSON.stringify(
+        value.length < STRING_PREVIEW_MAX_LENGTH
+          ? value
+          : `${value.slice(0, STRING_PREVIEW_MAX_LENGTH - STRING_PREVIEW_TRUNCATED_SUFFIX.length)}${STRING_PREVIEW_TRUNCATED_SUFFIX}`,
+      )
     case 'object':
+      if (value === null) return 'null'
       if (Array.isArray(value)) {
         return `[${stringifyArray(value, stringifyValue)}]`
       }
       if (isPlainObject(value)) {
         return `{${stringifyArray(Object.entries(value), stringifyObjectEntry)}}`
       }
-    // fallthrough
+      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'
+      if (value instanceof Set) return 'set'
+      return 'object'
     default:
-      return stringifyType(value)
+      return typeof value
   }
 }
 

package/src/core/validator.ts

@@ -152,11 +152,13 @@ export type ValidationOptions = {
   /**
    * The validation mode determining how transformations are handled.
    *
-   * - `"validate"` (default): Strict validation where the result must be
+   * - `"validate"`: Strict validation where the result must be
    *   strictly equal to the input value. No transformations such as applying
    *   default values are allowed.
    * - `"parse"`: Allows the schema to transform the input value, such as
    *   applying default values or performing type coercion.
+   *
+   * @default "validate"
    */
   mode?: 'validate' | 'parse'
 
@@ -173,6 +175,17 @@ export type ValidationOptions = {
    * ```
    */
   path?: readonly PropertyKey[]
+
+  /**
+   * Whether to enforce strict validation rules (e.g., MIME type matching, size
+   * limits, datetime format).
+   *
+   * This is typically useful to allow more lax validation when parsing server
+   * responses, while enforcing strict validation for user input.
+   *
+   * @default true
+   */
+  strict?: boolean
 }
 
 /**
@@ -221,6 +234,7 @@ export class ValidationContext {
       mode: 'parse'
     },
   ): ValidationResult<InferOutput<V>>
+
   /**
    * Validates input against a validator in validate mode (default).
    *
@@ -241,6 +255,7 @@ export class ValidationContext {
       mode?: 'validate'
     },
   ): ValidationResult<I & InferInput<V>>
+
   /**
    * Validates input against a validator with configurable options.
    *
@@ -262,6 +277,7 @@ export class ValidationContext {
     const context = new ValidationContext({
       path: options?.path ?? [],
       mode: options?.mode ?? 'validate',
+      strict: options?.strict ?? true,
     })
     return context.validate(input, validator)
   }

package/src/helpers.ts

@@ -9,6 +9,7 @@ import {
   Subscription,
   object,
   optional,
+  regexp,
   string,
 } from './schema.js'
 
@@ -103,7 +104,12 @@ export type InferMethodError<
   M extends Procedure | Query | Subscription = Procedure | Query | Subscription,
 > = M extends { errors: readonly (infer E extends string)[] } ? E : never
 
+/**
+ * @see {@link https://atproto.com/specs/xrpc#error-responses}
+ */
 export const lexErrorDataSchema = object({
-  error: string({ minLength: 1 }),
+  // type name of the error (generic ASCII constant, no whitespace)
+  error: regexp(/^[\w_-]+$/, 'Expected ASCII constant with no whitespace'),
+  // description of the error, appropriate for display to humans
   message: optional(string()),
 }) satisfies Schema<LexErrorData>

package/src/schema/array.test.ts

@@ -81,7 +81,7 @@ describe('ArraySchema', () => {
         success: false,
         reason: expect.objectContaining({
           message: expect.stringContaining(
-            'Expected array value type (got integer) at $',
+            'Expected array value type (got 3) at $',
           ),
         }),
       })