@atproto/lex-schema 0.0.16 → 0.0.18

package/src/schema/blob.ts

@@ -1,9 +1,11 @@
 import {
   BlobRef,
   LegacyBlobRef,
+  TypedBlobRef,
+  getBlobSize,
   isBlobRef,
   isLegacyBlobRef,
-  parseCidSafe,
+  isTypedBlobRef,
 } from '@atproto/lex-data'
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
@@ -12,14 +14,6 @@ import { memoizedOptions } from '../util/memoize.js'
  * Configuration options for blob schema validation.
  */
 export type BlobSchemaOptions = {
-  /**
-   * Whether to allow legacy blob references format
-   *
-   * @default false
-   * @see {@link LegacyBlobRef}
-   */
-  allowLegacy?: boolean
-
   /**
    * List of accepted MIME types (supports wildcards like 'image/*' or '*\/*')
    *
@@ -35,8 +29,8 @@ export type BlobSchemaOptions = {
   maxSize?: number
 }
 
-export type { BlobRef, LegacyBlobRef }
-export { isBlobRef, isLegacyBlobRef }
+export type { BlobRef, LegacyBlobRef, TypedBlobRef }
+export { isBlobRef, isLegacyBlobRef, isTypedBlobRef }
 
 /**
  * Schema for validating blob references in AT Protocol.
@@ -55,9 +49,7 @@ export { isBlobRef, isLegacyBlobRef }
  */
 export class BlobSchema<
   const TOptions extends BlobSchemaOptions = NonNullable<unknown>,
-> extends Schema<
-  TOptions extends { allowLegacy: true } ? BlobRef | LegacyBlobRef : BlobRef
-> {
+> extends Schema<BlobRef> {
   readonly type = 'blob' as const
 
   constructor(readonly options?: TOptions) {
@@ -65,23 +57,29 @@ export class BlobSchema<
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
-    const blob = parseValue.call(ctx, input, this.options)
-
+    const blob = parseValue.call(ctx, input)
     if (!blob) {
       return ctx.issueUnexpectedType(input, 'blob')
     }
 
     // In non-strict mode, we allow blob refs to pass through without MIME
     // type or size checks.
-    if (ctx.options.strict) {
-      const accept = this.options?.accept
+    if (ctx.options.strict && this.options != null) {
+      const { accept } = this.options
       if (accept && !matchesMime(blob.mimeType, accept)) {
         return ctx.issueInvalidPropertyValue(blob, 'mimeType', accept)
       }
 
-      const maxSize = this.options?.maxSize
-      if (maxSize != null && 'size' in blob && blob.size > maxSize) {
-        return ctx.issueTooBig(blob, 'blob', maxSize, blob.size)
+      const { maxSize } = this.options
+      if (maxSize != null) {
+        const size = getBlobSize(blob)
+        if (size === undefined) {
+          // Unable to enforce size constraint if size is not available (legacy
+          // blob ref), so we treat it as a validation failure in strict mode.
+          return ctx.issueInvalidPropertyType(blob, 'size' as any, 'integer')
+        } else if (size > maxSize) {
+          return ctx.issueTooBig(blob, 'blob', maxSize, size)
+        }
       }
     }
 
@@ -95,33 +93,19 @@ export class BlobSchema<
   }
 }
 
-function parseValue(
-  this: ValidationContext,
-  input: unknown,
-  options?: BlobSchemaOptions,
-): BlobRef | LegacyBlobRef | null {
-  // If there is a $type property, we treat if as a potential BlobRef and
+function parseValue(this: ValidationContext, input: unknown): BlobRef | null {
+  // If there is a $type property, we treat if as a potential TypedBlobRef and
   // validate accordingly.
   if ((input as any)?.$type !== undefined) {
     // Use the context's option for the "strict" check
-    return isBlobRef(input, this.options) ? input : null
+    return isTypedBlobRef(input, this.options) ? input : null
   }
 
   // If there is no $type property, we may be dealing with a legacy blob ref. If
-  // legacy refs are allowed, validate against the legacy format. If not
-  // allowed, but we are in non-strict "parse" mode, coerce legacy refs into
-  // standard BlobRef format for backward compatibility. Otherwise, reject the
-  // value.
-  if (options?.allowLegacy) {
-    if (isLegacyBlobRef(input)) {
-      return input
-    }
-  } else if (!this.options.strict && this.options.mode === 'parse') {
-    if (isLegacyBlobRef(input)) {
-      const { cid, mimeType } = input
-      const ref = parseCidSafe(cid)
-      if (ref) return { $type: 'blob', ref, mimeType, size: -1 }
-    }
+  // legacy refs are allowed (non-strict mode), we check if the input matches
+  // the legacy format.
+  if (!this.options.strict) {
+    if (isLegacyBlobRef(input, this.options)) return input
   }
 
   return null
@@ -157,13 +141,10 @@ function matchesMime(mime: string, accepted: string[]): boolean {
  *
  * // Any image type with size limit
  * const avatarSchema = l.blob({ accept: ['image/*'], maxSize: 1000000 })
- *
- * // Allow legacy format
- * const legacySchema = l.blob({ allowLegacy: true })
  * ```
  */
 export const blob = /*#__PURE__*/ memoizedOptions(function <
-  O extends BlobSchemaOptions = { allowLegacy?: false },
+  O extends BlobSchemaOptions = NonNullable<unknown>,
 >(options?: O) {
   return new BlobSchema(options)
 })

package/src/schema/params.test.ts

@@ -419,7 +419,7 @@ describe('ParamsSchema', () => {
           ['name', 'Alice'],
           ['bools', 'notabool'],
         ]),
-      ).toThrow('Expected boolean value type (got string) at $.bools')
+      ).toThrow('Expected boolean value type (got "notabool") at $.bools')
 
       expect(() =>
         schema.fromURLSearchParams(
@@ -431,7 +431,7 @@ describe('ParamsSchema', () => {
             path: ['foo', 'bar'],
           },
         ),
-      ).toThrow('Expected boolean value type (got string) at $.foo.bar.bools')
+      ).toThrow('Expected boolean value type (got "2") at $.foo.bar.bools')
     })
 
     it('ignores empty string values', () => {

package/src/schema/payload.ts

@@ -109,10 +109,9 @@ export class Payload<
   matchesEncoding(contentType: string | undefined): boolean {
     const { encoding } = this
 
-    // Handle undefined cases
     if (encoding === undefined) {
-      // Expecting no body
-      return contentType == null
+      // When the output is not defined, we don't enforce any rule on the payload.
+      return true
     } else if (contentType == null) {
       // Expecting a body, but got no content-type
       return false

package/src/schema/record.test.ts

@@ -1,6 +1,8 @@
-import { describe, expect, it } from 'vitest'
-import { Infer, Unknown$Type, Unknown$TypedObject } from '../core.js'
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { DidString, Infer, Unknown$Type, Unknown$TypedObject } from '../core.js'
+import { integer } from './integer.js'
 import { object } from './object.js'
+import { optional } from './optional.js'
 import { record } from './record.js'
 import { string } from './string.js'
 
@@ -123,41 +125,157 @@ describe('RecordSchema', () => {
     })
   })
 
-  describe('build method', () => {
+  describe('build() method', () => {
     const schema = record(
       'any',
-      'app.bsky.feed.post',
+      'io.example.record',
       object({
-        $type: string(),
-        text: string(),
+        actor: string({ format: 'did' }),
+        text: optional(string()),
       }),
     )
 
-    it('adds correct $type to input', () => {
-      const result = schema.build({ text: 'Hello world' })
-      expect(result.$type).toBe('app.bsky.feed.post')
-      expect(result.text).toBe('Hello world')
+    it('adds $type to input', () => {
+      const result = schema.build({
+        actor: 'did:foo:bar',
+        text: 'Hello',
+      })
+      expect(result).toStrictEqual({
+        $type: 'io.example.record',
+        actor: 'did:foo:bar',
+        text: 'Hello',
+      })
+      expectTypeOf(result).toEqualTypeOf<{
+        $type: 'io.example.record'
+        actor: DidString
+        text?: string
+      }>()
+    })
+
+    it('causes a type error for invalid values', () => {
+      const result = schema.build({
+        // @ts-expect-error
+        actor: 3,
+        text: 'Hello',
+      })
+      expectTypeOf(result).toEqualTypeOf<{
+        $type: 'io.example.record'
+        actor: DidString
+        text?: string
+      }>()
     })
 
     it('preserves existing properties', () => {
       const result = schema.build({
-        text: 'Hello world',
+        actor: 'did:foo:bar',
         // @ts-expect-error
         extra: 'value',
       })
-      expect(result.$type).toBe('app.bsky.feed.post')
-      expect(result.text).toBe('Hello world')
-      // @ts-expect-error
-      expect(result.extra).toBe('value')
+      expect(result).toStrictEqual({
+        $type: 'io.example.record',
+        actor: 'did:foo:bar',
+        extra: 'value',
+      })
+      expectTypeOf(result).toEqualTypeOf<{
+        actor: `did:${string}:${string}`
+        text?: string | undefined
+        $type: 'io.example.record'
+      }>()
     })
 
     it('overwrites existing $type', () => {
       const result = schema.build({
         // @ts-expect-error
         $type: 'wrong.type',
-        text: 'Hello world',
+        actor: 'did:foo:bar',
+      })
+      expect(result).toStrictEqual({
+        $type: 'io.example.record',
+        actor: 'did:foo:bar',
+      })
+      expectTypeOf(result).toEqualTypeOf<{
+        $type: 'io.example.record'
+        actor: DidString
+        text?: string
+      }>()
+    })
+
+    describe('build() does not validate', () => {
+      const schema = record(
+        'any',
+        'io.example.record',
+        object({
+          actor: string({ format: 'did' }),
+          count: integer(),
+        }),
+      )
+
+      it('does not throw for invalid data', () => {
+        const result = schema.build({
+          // @ts-expect-error
+          actor: 'not-a-did',
+          count: 123,
+        })
+
+        expect(result.$type).toBe('io.example.record')
+        expect(result.actor).toBe('not-a-did')
+        expect(result.count).toBe(123)
+      })
+
+      it('does not throw for invalid types', () => {
+        const result = schema.build({
+          actor: 'did:plc:abc123',
+          // @ts-expect-error
+          count: 'not-a-number',
+        })
+
+        expect(result.$type).toBe('io.example.record')
+        expect(result.count).toBe('not-a-number')
+      })
+
+      it('does not throw for missing required fields', () => {
+        // @ts-expect-error
+        const result = schema.build({})
+
+        expect(result.$type).toBe('io.example.record')
+        expect(result.actor).toBeUndefined()
+        expect(result.count).toBeUndefined()
+      })
+
+      it('does not throw for extra fields', () => {
+        const result = schema.build({
+          actor: 'did:plc:abc123',
+          count: 42,
+          // @ts-expect-error
+          extra: 'unexpected',
+        })
+
+        expect(result.$type).toBe('io.example.record')
+
+        // @ts-expect-error
+        expect(result.extra).toBe('unexpected')
+      })
+
+      it('parse() still validates after build()', () => {
+        const built = schema.build({
+          // @ts-expect-error
+          actor: 'not-a-did',
+          count: 123,
+        })
+
+        expect(() => schema.parse(built)).toThrow('Invalid DID')
+      })
+
+      it('safeParse() can detect validation errors after build()', () => {
+        const built = schema.build({
+          // @ts-expect-error
+          actor: 'not-a-did',
+          count: 123,
+        })
+
+        const result = schema.safeParse(built)
+        expect(result.success).toBe(false)
       })
-      expect(result.$type).toBe('app.bsky.feed.post')
     })
   })
 

package/src/schema/record.ts

@@ -1,3 +1,4 @@
+import { LexMap } from '@atproto/lex-data'
 import {
   $Typed,
   $typed,
@@ -51,9 +52,9 @@ export type TypedRecord<
  * ```
  */
 export class RecordSchema<
-  const TKey extends LexiconRecordKey = any,
-  const TType extends NsidString = any,
-  const TShape extends Validator<{ [k: string]: unknown }> = any,
+  const TKey extends LexiconRecordKey = LexiconRecordKey,
+  const TType extends NsidString = NsidString,
+  const TShape extends Validator<LexMap> = Validator<LexMap>,
 > extends Schema<
   $Typed<InferInput<TShape>, TType>,
   $Typed<InferOutput<TShape>, TType>
@@ -86,9 +87,13 @@ export class RecordSchema<
   }
 
   build(
-    input: Omit<InferInput<this>, '$type'>,
-  ): $Typed<InferOutput<this>, TType> {
-    return this.parse($typed(input, this.$type))
+    input: Omit<InferOutput<TShape>, '$type'>,
+  ): $Typed<InferOutput<TShape>, TType>
+  build(
+    input: Omit<InferInput<TShape>, '$type'>,
+  ): $Typed<InferInput<TShape>, TType>
+  build(input: Record<string, unknown>) {
+    return $typed(input, this.$type)
   }
 
   isTypeOf<TValue extends { $type?: unknown }>(
@@ -199,11 +204,11 @@ type AsNsid<T> = T extends `${string}#${string}` ? never : T
 export function record<
   const K extends LexiconRecordKey,
   const T extends NsidString,
-  const S extends Validator<{ [k: string]: unknown }>,
+  const S extends Validator<LexMap>,
 >(key: K, type: AsNsid<T>, validator: S): RecordSchema<K, T, S>
 export function record<
   const K extends LexiconRecordKey,
-  const V extends { $type: NsidString },
+  const V extends LexMap & { $type: NsidString },
 >(
   key: K,
   type: AsNsid<V['$type']>,
@@ -213,7 +218,7 @@ export function record<
 export function record<
   const K extends LexiconRecordKey,
   const T extends NsidString,
-  const S extends Validator<{ [k: string]: unknown }>,
+  const S extends Validator<LexMap>,
 >(key: K, type: T, validator: S) {
   return new RecordSchema<K, T, S>(key, type, validator)
 }

package/src/schema/regexp.ts

@@ -20,7 +20,10 @@ export class RegexpSchema<
 > extends Schema<TValue> {
   readonly type = 'regexp' as const
 
-  constructor(public readonly pattern: RegExp) {
+  constructor(
+    public readonly pattern: RegExp,
+    public readonly message?: string,
+  ) {
     super()
   }
 
@@ -30,7 +33,11 @@ export class RegexpSchema<
     }
 
     if (!this.pattern.test(input)) {
-      return ctx.issueInvalidFormat(input, this.pattern.toString())
+      return ctx.issueInvalidFormat(
+        input,
+        this.pattern.toString(),
+        this.message,
+      )
     }
 
     return ctx.success(input as TValue)
@@ -67,6 +74,9 @@ export class RegexpSchema<
  * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
-export function regexp<TInput extends string = string>(pattern: RegExp) {
-  return new RegexpSchema<TInput>(pattern)
+export function regexp<TInput extends string = string>(
+  pattern: RegExp,
+  message?: string,
+): RegexpSchema<TInput> {
+  return new RegexpSchema<TInput>(pattern, message)
 }

package/src/schema/string.ts

@@ -99,12 +99,15 @@ export class StringSchema<
       }
     }
 
+    // Optimization: count graphemes once
     let lazyGraphLen: number
 
     const minGraphemes = this.options.minGraphemes
     if (minGraphemes != null) {
-      // Optimization: avoid counting graphemes if the length check already fails
       if (str.length < minGraphemes) {
+        // If the JavaScript string length (UTF-16) is below the minimal limit,
+        // its grapheme length (which <= .length) will also be below.
+        // Fail early.
         return ctx.issueTooSmall(str, 'grapheme', minGraphemes, str.length)
       } else if ((lazyGraphLen ??= graphemeLen(str)) < minGraphemes) {
         return ctx.issueTooSmall(str, 'grapheme', minGraphemes, lazyGraphLen)
@@ -113,7 +116,10 @@ export class StringSchema<
 
     const maxGraphemes = this.options.maxGraphemes
     if (maxGraphemes != null) {
-      if ((lazyGraphLen ??= graphemeLen(str)) > maxGraphemes) {
+      if (str.length <= maxGraphemes) {
+        // If the JavaScript string length (UTF-16) is within the maximum limit,
+        // its grapheme length (which <= .length) will also be within.
+      } else if ((lazyGraphLen ??= graphemeLen(str)) > maxGraphemes) {
         return ctx.issueTooBig(str, 'grapheme', maxGraphemes, lazyGraphLen)
       }
     }

package/src/schema/typed-object.test.ts

@@ -303,6 +303,83 @@ describe('TypedObjectSchema', () => {
       const result = emptySchema.build(input)
       expect(result).toEqual({ $type: 'app.bsky.test' })
     })
+
+    describe('build() does not validate', () => {
+      const validationSchema = typedObject(
+        'app.bsky.test',
+        'validation',
+        object({
+          actor: string({ format: 'did' }),
+          count: integer(),
+        }),
+      )
+
+      it('does not throw for invalid data', () => {
+        const result = validationSchema.build({
+          // @ts-expect-error
+          actor: 'not-a-did',
+          count: 123,
+        })
+
+        expect(result.$type).toBe('app.bsky.test#validation')
+        expect(result.actor).toBe('not-a-did')
+        expect(result.count).toBe(123)
+      })
+
+      it('does not throw for invalid types', () => {
+        const result = validationSchema.build({
+          actor: 'did:plc:abc123',
+          // @ts-expect-error
+          count: 'not-a-number',
+        })
+
+        expect(result.$type).toBe('app.bsky.test#validation')
+        expect(result.count).toBe('not-a-number')
+      })
+
+      it('does not throw for missing required fields', () => {
+        // @ts-expect-error
+        const result = validationSchema.build({})
+
+        expect(result.$type).toBe('app.bsky.test#validation')
+        expect(result.actor).toBeUndefined()
+        expect(result.count).toBeUndefined()
+      })
+
+      it('does not throw for extra fields', () => {
+        const result = validationSchema.build({
+          actor: 'did:plc:abc123',
+          count: 42,
+          // @ts-expect-error
+          extra: 'unexpected',
+        })
+
+        expect(result.$type).toBe('app.bsky.test#validation')
+        // @ts-expect-error
+        expect(result.extra).toBe('unexpected')
+      })
+
+      it('parse() still validates after build()', () => {
+        const built = validationSchema.build({
+          // @ts-expect-error
+          actor: 'not-a-did',
+          count: 123,
+        })
+
+        expect(() => validationSchema.parse(built)).toThrow('Invalid DID')
+      })
+
+      it('safeParse() can detect validation errors after build()', () => {
+        const built = validationSchema.build({
+          // @ts-expect-error
+          actor: 'not-a-did',
+          count: 123,
+        })
+
+        const result = validationSchema.safeParse(built)
+        expect(result.success).toBe(false)
+      })
+    })
   })
 
   describe('$build method', () => {

package/src/schema/typed-object.ts

@@ -1,4 +1,4 @@
-import { isPlainObject } from '@atproto/lex-data'
+import { LexMap, isPlainObject } from '@atproto/lex-data'
 import {
   $Type,
   $TypeOf,
@@ -43,7 +43,7 @@ export type MaybeTypedObject<
  */
 export class TypedObjectSchema<
   const TType extends $Type = $Type,
-  const TShape extends Validator<{ [k: string]: unknown }> = any,
+  const TShape extends Validator<LexMap> = Validator<LexMap>,
 > extends Schema<
   $TypedMaybe<InferInput<TShape>, TType>,
   $TypedMaybe<InferOutput<TShape>, TType>
@@ -74,12 +74,13 @@ export class TypedObjectSchema<
   }
 
   build(
-    input: Omit<InferInput<this>, '$type'>,
-  ): $Typed<InferOutput<this>, TType> {
-    return this.parse($typed(input, this.$type)) as $Typed<
-      InferOutput<this>,
-      TType
-    >
+    input: Omit<InferOutput<TShape>, '$type'>,
+  ): $Typed<InferOutput<TShape>, TType>
+  build(
+    input: Omit<InferInput<TShape>, '$type'>,
+  ): $Typed<InferInput<TShape>, TType>
+  build(input: Record<string, unknown>) {
+    return $typed(input, this.$type)
   }
 
   isTypeOf<TValue extends Record<string, unknown>>(
@@ -155,7 +156,7 @@ export class TypedObjectSchema<
 export function typedObject<
   const N extends NsidString,
   const H extends string,
-  const S extends Validator<{ [k: string]: unknown }>,
+  const S extends Validator<LexMap>,
 >(nsid: N, hash: H, validator: S): TypedObjectSchema<$Type<N, H>, S>
 export function typedObject<V extends { $type?: $Type }>(
   nsid: V extends { $type?: infer T extends string }
@@ -174,7 +175,7 @@ export function typedObject<V extends { $type?: $Type }>(
 export function typedObject<
   const N extends NsidString,
   const H extends string,
-  const S extends Validator<{ [k: string]: unknown }>,
+  const S extends Validator<LexMap>,
 >(nsid: N, hash: H, validator: S) {
   return new TypedObjectSchema<$Type<N, H>, S>($type(nsid, hash), validator)
 }