@atproto/lex-schema 0.0.16 → 0.0.17

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/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 $',
           ),
         }),
       })

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)
 }