@atproto/lex-schema 0.0.14 → 0.0.16

package/src/core/validation-issue.ts

@@ -1,5 +1,4 @@
 import { ifCid, isLegacyBlobRef, isPlainObject } from '@atproto/lex-data'
-import { PropertyKey } from './property-key.js'
 
 /**
  * Abstract base class for all validation issues.
@@ -9,10 +8,13 @@ import { PropertyKey } from './property-key.js'
  * - The path to the invalid value in the data structure
  * - The actual input value that failed validation
  *
- * Subclasses add specific properties relevant to each issue type and
- * implement the {@link toString} method for human-readable error messages.
+ * Subclasses add specific properties relevant to each issue type and implement
+ * the {@link message} property for human-readable error messages (that don't
+ * contain the error path)
  */
 export abstract class Issue {
+  abstract readonly message: string
+
   constructor(
     readonly code: string,
     readonly path: readonly PropertyKey[],
@@ -22,7 +24,9 @@ export abstract class Issue {
   /**
    * Returns a human-readable description of the validation issue.
    */
-  abstract toString(): string
+  toString() {
+    return `${this.message}${stringifyPath(this.path)}`
+  }
 
   /**
    * Converts the issue to a JSON-serializable object.
@@ -33,7 +37,7 @@ export abstract class Issue {
     return {
       code: this.code,
       path: this.path,
-      message: this.toString(),
+      message: this.message,
     }
   }
 }
@@ -51,10 +55,6 @@ export class IssueCustom extends Issue {
   ) {
     super('custom', path, input)
   }
-
-  toString() {
-    return `${this.message}${stringifyPath(this.path)}`
-  }
 }
 
 /**
@@ -67,20 +67,13 @@ export class IssueInvalidFormat extends Issue {
     path: readonly PropertyKey[],
     input: unknown,
     readonly format: string,
-    readonly message?: string,
+    readonly detail?: string,
   ) {
     super('invalid_format', path, input)
   }
 
-  toString() {
-    return `Invalid ${this.formatDescription}${this.message ? ` (${this.message})` : ''}${stringifyPath(this.path)} (got ${stringifyValue(this.input)})`
-  }
-
-  toJSON() {
-    return {
-      ...super.toJSON(),
-      format: this.format,
-    }
+  override get message(): string {
+    return `Invalid ${this.formatDescription}${this.detail ? ` (${this.detail}, ` : ' ('}got ${stringifyValue(this.input)})`
   }
 
   /** Returns a human-readable description of the expected format. */
@@ -102,6 +95,13 @@ export class IssueInvalidFormat extends Issue {
         return this.format
     }
   }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      format: this.format,
+    }
+  }
 }
 
 /**
@@ -119,8 +119,8 @@ export class IssueInvalidType extends Issue {
     super('invalid_type', path, input)
   }
 
-  toString() {
-    return `Expected ${oneOf(this.expected.map(stringifyExpectedType))} value type${stringifyPath(this.path)} (got ${stringifyType(this.input)})`
+  override get message(): string {
+    return `Expected ${oneOf(this.expected.map(stringifyExpectedType))} value type (got ${stringifyType(this.input)})`
   }
 
   toJSON() {
@@ -146,8 +146,8 @@ export class IssueInvalidValue extends Issue {
     super('invalid_value', path, input)
   }
 
-  toString() {
-    return `Expected ${oneOf(this.values.map(stringifyValue))}${stringifyPath(this.path)} (got ${stringifyValue(this.input)})`
+  override get message(): string {
+    return `Expected ${oneOf(this.values.map(stringifyValue))} (got ${stringifyValue(this.input)})`
   }
 
   toJSON() {
@@ -170,8 +170,8 @@ export class IssueRequiredKey extends Issue {
     super('required_key', path, input)
   }
 
-  toString() {
-    return `Missing required key "${String(this.key)}"${stringifyPath(this.path)}`
+  override get message(): string {
+    return `Missing required key "${String(this.key)}"`
   }
 
   toJSON() {
@@ -214,8 +214,8 @@ export class IssueTooBig extends Issue {
     super('too_big', path, input)
   }
 
-  toString() {
-    return `${this.type} too big (maximum ${this.maximum})${stringifyPath(this.path)} (got ${this.actual})`
+  override get message(): string {
+    return `${this.type} too big (maximum ${this.maximum}, got ${this.actual})`
   }
 
   toJSON() {
@@ -241,8 +241,8 @@ export class IssueTooSmall extends Issue {
     super('too_small', path, input)
   }
 
-  toString() {
-    return `${this.type} too small (minimum ${this.minimum})${stringifyPath(this.path)} (got ${this.actual})`
+  override get message(): string {
+    return `${this.type} too small (minimum ${this.minimum}, got ${this.actual})`
   }
 
   toJSON() {
@@ -274,9 +274,9 @@ function buildJsonPath(path: readonly PropertyKey[]): string {
 }
 
 function toJsonPathSegment(segment: PropertyKey): string {
-  if (typeof segment === 'number') {
-    return `[${segment}]`
-  } else if (/^[a-zA-Z_$][a-zA-Z0-9_]*$/.test(segment as string)) {
+  if (typeof segment === 'number' || typeof segment === 'symbol') {
+    return `[${String(segment)}]`
+  } else if (/^[a-zA-Z_$][a-zA-Z0-9_]*$/.test(segment)) {
     return `.${segment}`
   } else {
     return `[${JSON.stringify(segment)}]`

package/src/core/validator.ts

@@ -1,5 +1,5 @@
-import { PropertyKey } from './property-key.js'
-import { ResultFailure, ResultSuccess, failure, success } from './result.js'
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { ResultFailure, ResultSuccess, success } from './result.js'
 import { LexValidationError } from './validation-error.js'
 import {
   Issue,
@@ -21,8 +21,12 @@ export type ValidationSuccess<Value = unknown> = ResultSuccess<Value>
 
 /**
  * Represents a failed validation result containing a {@link LexValidationError}.
+ *
+ * @extends ResultFailure<LexValidationError>
+ * @see {@link ResultFailure}
+ * @see {@link LexValidationError}
  */
-export type ValidationFailure = ResultFailure<LexValidationError>
+export type ValidationFailure = LexValidationError
 
 /**
  * Discriminated union representing the outcome of a validation operation.
@@ -148,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'
 
@@ -169,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
 }
 
 /**
@@ -217,6 +234,7 @@ export class ValidationContext {
       mode: 'parse'
     },
   ): ValidationResult<InferOutput<V>>
+
   /**
    * Validates input against a validator in validate mode (default).
    *
@@ -237,6 +255,7 @@ export class ValidationContext {
       mode?: 'validate'
     },
   ): ValidationResult<I & InferInput<V>>
+
   /**
    * Validates input against a validator with configurable options.
    *
@@ -258,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)
   }
@@ -326,7 +346,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 LexValidationError(Array.from(this.issues)))
+        return new LexValidationError(Array.from(this.issues))
       }
 
       if (this.options.mode !== 'parse' && !Object.is(result.value, input)) {
@@ -426,7 +446,7 @@ export class ValidationContext {
    * @returns A failed validation result
    */
   failure(reason: LexValidationError): ValidationFailure {
-    return failure(reason)
+    return reason
   }
 
   /**

package/src/core.ts

@@ -1,5 +1,4 @@
 export * from './core/$type.js'
-export * from './core/property-key.js'
 export * from './core/record-key.js'
 export * from './core/result.js'
 export * from './core/schema.js'

package/src/schema/array.test.ts

@@ -77,11 +77,11 @@ describe('ArraySchema', () => {
     it('rejects single values', () => {
       const schema = array(string())
       const result = schema.safeValidate(3)
-      expect(result).toEqual({
+      expect(result).toMatchObject({
         success: false,
         reason: expect.objectContaining({
           message: expect.stringContaining(
-            'Expected array value type at $ (got integer)',
+            'Expected array value type (got integer) at $',
           ),
         }),
       })

package/src/schema/blob.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { assert, describe, expect, it } from 'vitest'
 import { parseCid } from '@atproto/lex-data'
 import { blob } from './blob.js'
 
@@ -214,37 +214,62 @@ describe('BlobSchema', () => {
   })
 
   describe('strict validation', () => {
-    const strictSchema = blob({ strict: true })
+    const schema = blob()
 
     it('accepts valid raw CID in strict mode', () => {
-      const result = strictSchema.safeParse({
-        $type: 'blob',
-        ref: blobCid,
-        mimeType: 'image/jpeg',
-        size: 10000,
-      })
+      const result = schema.safeParse(
+        {
+          $type: 'blob',
+          ref: blobCid,
+          mimeType: 'image/jpeg',
+          size: 10000,
+        },
+        { strict: true },
+      )
       expect(result.success).toBe(true)
     })
 
     it('rejects non-raw CID in strict mode', () => {
-      const result = strictSchema.safeParse({
-        $type: 'blob',
-        ref: lexCid,
-        mimeType: 'image/jpeg',
-        size: 10000,
-      })
+      const result = schema.safeParse(
+        {
+          $type: 'blob',
+          ref: lexCid,
+          mimeType: 'image/jpeg',
+          size: 10000,
+        },
+        { strict: true },
+      )
       expect(result.success).toBe(false)
     })
 
     it('accepts non-raw CID in non-strict mode', () => {
-      const nonStrictSchema = blob({ strict: false })
-      const result = nonStrictSchema.safeParse({
+      const result = schema.safeParse(
+        {
+          $type: 'blob',
+          ref: lexCid,
+          mimeType: 'image/jpeg',
+          size: 10000,
+        },
+        { strict: false },
+      )
+      expect(result.success).toBe(true)
+    })
+
+    it('coerces legacy blob format in non-strict parse mode', () => {
+      const result = schema.safeParse(
+        {
+          cid: lexCid.toString(),
+          mimeType: 'image/jpeg',
+        },
+        { strict: false },
+      )
+      assert(result.success)
+      expect(result.value).toEqual({
         $type: 'blob',
         ref: lexCid,
         mimeType: 'image/jpeg',
-        size: 10000,
+        size: -1,
       })
-      expect(result.success).toBe(true)
     })
   })
 
@@ -455,51 +480,294 @@ describe('BlobSchema', () => {
     })
   })
 
-  describe('combined options', () => {
-    it('validates with strict and allowLegacy both true', () => {
-      const schema = blob({ strict: true, allowLegacy: true })
+  describe('legacy blob format with strict mode combinations', () => {
+    describe('allowLegacy: false (default)', () => {
+      const schema = blob()
+
+      describe('strict: true (default)', () => {
+        it('rejects legacy blob format', () => {
+          const result = schema.safeParse({
+            cid: blobCid.toString(),
+            mimeType: 'image/jpeg',
+          })
+          expect(result.success).toBe(false)
+        })
+
+        it('accepts standard BlobRef', () => {
+          const result = schema.safeParse({
+            $type: 'blob',
+            ref: blobCid,
+            mimeType: 'image/jpeg',
+            size: 10000,
+          })
+          expect(result.success).toBe(true)
+        })
+      })
+
+      describe('strict: false', () => {
+        it('coerces legacy blob format into BlobRef', () => {
+          const result = schema.safeParse(
+            {
+              cid: blobCid.toString(),
+              mimeType: 'image/jpeg',
+            },
+            { strict: false },
+          )
+          assert(result.success)
+          expect(result.value).toEqual({
+            $type: 'blob',
+            ref: blobCid,
+            mimeType: 'image/jpeg',
+            size: -1,
+          })
+        })
+
+        it('coerces legacy blob format with lexCid', () => {
+          const result = schema.safeParse(
+            {
+              cid: lexCid.toString(),
+              mimeType: 'image/png',
+            },
+            { strict: false },
+          )
+          assert(result.success)
+          expect(result.value).toEqual({
+            $type: 'blob',
+            ref: lexCid,
+            mimeType: 'image/png',
+            size: -1,
+          })
+        })
+
+        it('rejects legacy blob format with invalid cid', () => {
+          const result = schema.safeParse(
+            {
+              cid: 'invalid-cid',
+              mimeType: 'image/jpeg',
+            },
+            { strict: false },
+          )
+          expect(result.success).toBe(false)
+        })
+
+        it('accepts standard BlobRef with non-raw CID', () => {
+          const result = schema.safeParse(
+            {
+              $type: 'blob',
+              ref: lexCid,
+              mimeType: 'image/jpeg',
+              size: 10000,
+            },
+            { strict: false },
+          )
+          expect(result.success).toBe(true)
+        })
+      })
+    })
+
+    describe('allowLegacy: true', () => {
+      const schema = blob({ allowLegacy: true })
 
-      // Should accept strict BlobRef
-      const blobRefResult = schema.safeParse({
-        $type: 'blob',
-        ref: blobCid,
-        mimeType: 'image/jpeg',
-        size: 10000,
+      describe('strict: true (default)', () => {
+        it('accepts legacy blob format as LegacyBlobRef', () => {
+          const result = schema.safeParse({
+            cid: blobCid.toString(),
+            mimeType: 'image/jpeg',
+          })
+          assert(result.success)
+          expect('cid' in result.value && result.value.cid).toBe(
+            blobCid.toString(),
+          )
+        })
+
+        it('accepts standard BlobRef', () => {
+          const result = schema.safeParse({
+            $type: 'blob',
+            ref: blobCid,
+            mimeType: 'image/jpeg',
+            size: 10000,
+          })
+          expect(result.success).toBe(true)
+        })
+
+        it('rejects non-raw CID in BlobRef format (strict)', () => {
+          const result = schema.safeParse({
+            $type: 'blob',
+            ref: lexCid,
+            mimeType: 'image/jpeg',
+            size: 10000,
+          })
+          expect(result.success).toBe(false)
+        })
+      })
+
+      describe('strict: false', () => {
+        it('accepts legacy blob format as LegacyBlobRef', () => {
+          const result = schema.safeParse(
+            {
+              cid: blobCid.toString(),
+              mimeType: 'image/jpeg',
+            },
+            { strict: false },
+          )
+          assert(result.success)
+          expect('cid' in result.value && result.value.cid).toBe(
+            blobCid.toString(),
+          )
+        })
+
+        it('accepts standard BlobRef with non-raw CID (non-strict)', () => {
+          const result = schema.safeParse(
+            {
+              $type: 'blob',
+              ref: lexCid,
+              mimeType: 'image/jpeg',
+              size: 10000,
+            },
+            { strict: false },
+          )
+          expect(result.success).toBe(true)
+        })
+
+        it('accepts standard BlobRef with raw CID', () => {
+          const result = schema.safeParse(
+            {
+              $type: 'blob',
+              ref: blobCid,
+              mimeType: 'image/jpeg',
+              size: 10000,
+            },
+            { strict: false },
+          )
+          expect(result.success).toBe(true)
+        })
       })
-      expect(blobRefResult.success).toBe(true)
+    })
+  })
 
-      // Should accept LegacyBlobRef
-      const legacyResult = schema.safeParse({
-        cid: blobCid.toString(),
-        mimeType: 'image/jpeg',
+  describe('mime and size checks depend on strict mode', () => {
+    describe('accept constraint', () => {
+      const schema = blob({ accept: ['image/jpeg', 'image/png'] })
+
+      it('rejects non-matching mime type in strict mode (default)', () => {
+        const result = schema.safeParse({
+          $type: 'blob',
+          ref: blobCid,
+          mimeType: 'image/gif',
+          size: 10000,
+        })
+        expect(result.success).toBe(false)
+      })
+
+      it('accepts non-matching mime type in non-strict mode', () => {
+        const result = schema.safeParse(
+          {
+            $type: 'blob',
+            ref: blobCid,
+            mimeType: 'image/gif',
+            size: 10000,
+          },
+          { strict: false },
+        )
+        expect(result.success).toBe(true)
       })
-      expect(legacyResult.success).toBe(true)
 
-      // Should reject non-raw CID in BlobRef format
-      const nonRawResult = schema.safeParse({
-        $type: 'blob',
-        ref: lexCid,
-        mimeType: 'image/jpeg',
-        size: 10000,
+      it('accepts matching mime type in strict mode', () => {
+        const result = schema.safeParse({
+          $type: 'blob',
+          ref: blobCid,
+          mimeType: 'image/jpeg',
+          size: 10000,
+        })
+        expect(result.success).toBe(true)
       })
-      expect(nonRawResult.success).toBe(false)
     })
 
-    it('validates with all options combined', () => {
+    describe('maxSize constraint', () => {
+      const schema = blob({ maxSize: 1000 })
+
+      it('rejects oversized blob in strict mode (default)', () => {
+        const result = schema.safeParse({
+          $type: 'blob',
+          ref: blobCid,
+          mimeType: 'image/jpeg',
+          size: 5000,
+        })
+        expect(result.success).toBe(false)
+      })
+
+      it('accepts oversized blob in non-strict mode', () => {
+        const result = schema.safeParse(
+          {
+            $type: 'blob',
+            ref: blobCid,
+            mimeType: 'image/jpeg',
+            size: 5000,
+          },
+          { strict: false },
+        )
+        expect(result.success).toBe(true)
+      })
+
+      it('accepts correctly sized blob in strict mode', () => {
+        const result = schema.safeParse({
+          $type: 'blob',
+          ref: blobCid,
+          mimeType: 'image/jpeg',
+          size: 500,
+        })
+        expect(result.success).toBe(true)
+      })
+    })
+
+    describe('combined accept and maxSize constraints', () => {
       const schema = blob({
-        strict: true,
-        allowLegacy: true,
         accept: ['image/jpeg'],
         maxSize: 20000,
       })
 
-      const result = schema.safeParse({
-        $type: 'blob',
-        ref: blobCid,
-        mimeType: 'image/jpeg',
-        size: 10000,
+      it('accepts valid blob in strict mode', () => {
+        const result = schema.safeParse({
+          $type: 'blob',
+          ref: blobCid,
+          mimeType: 'image/jpeg',
+          size: 10000,
+        })
+        expect(result.success).toBe(true)
+      })
+
+      it('rejects wrong mime in strict mode', () => {
+        const result = schema.safeParse({
+          $type: 'blob',
+          ref: blobCid,
+          mimeType: 'image/png',
+          size: 10000,
+        })
+        expect(result.success).toBe(false)
+      })
+
+      it('rejects oversized in strict mode', () => {
+        const result = schema.safeParse({
+          $type: 'blob',
+          ref: blobCid,
+          mimeType: 'image/jpeg',
+          size: 30000,
+        })
+        expect(result.success).toBe(false)
+      })
+
+      it('accepts wrong mime and oversized in non-strict mode', () => {
+        const result = schema.safeParse(
+          {
+            $type: 'blob',
+            ref: blobCid,
+            mimeType: 'video/mp4',
+            size: 99999,
+          },
+          { strict: false },
+        )
+        expect(result.success).toBe(true)
       })
-      expect(result.success).toBe(true)
     })
   })
 })