@atproto/lex-schema 0.0.1 → 0.0.3

package/src/schema/params.ts

@@ -1,64 +1,47 @@
 import { isPlainObject } from '@atproto/lex-data'
-import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+import { WithOptionalProperties } from '../core.js'
+import { lazyProperty } from '../util/lazy-property.js'
+import {
+  Infer,
+  Schema,
+  ValidationResult,
+  Validator,
+  ValidatorContext,
+} from '../validation.js'
 import { Param, ParamScalar, paramSchema } from './_parameters.js'
-import { ObjectSchemaPropertiesOutput } from './object.js'
 import { StringSchema } from './string.js'
 
-export type ParamsSchemaProperties = {
-  [_ in string]: Validator<Param>
-}
-
-export type ParamsSchemaOptions = {
-  required?: readonly string[]
-}
+export type ParamsSchemaShape = Record<string, Validator<Param | undefined>>
 
-export type ParamsSchemaOutput<
-  P extends ParamsSchemaProperties,
-  O extends ParamsSchemaOptions,
-> = ObjectSchemaPropertiesOutput<P, O>
+export type ParamsSchemaOutput<Shape extends ParamsSchemaShape> =
+  WithOptionalProperties<{
+    [K in keyof Shape]: Infer<Shape[K]>
+  }>
 
 export type InferParamsSchema<T> =
-  T extends ParamsSchema<infer P, infer O>
-    ? NonNullable<unknown> extends ParamsSchemaOutput<P, O>
-      ? ParamsSchemaOutput<P, O> | undefined
-      : ParamsSchemaOutput<P, O>
+  T extends ParamsSchema<infer P>
+    ? NonNullable<unknown> extends ParamsSchemaOutput<P>
+      ? ParamsSchemaOutput<P> | undefined // Allow undefined if all params are optional
+      : ParamsSchemaOutput<P>
     : never
 
 export class ParamsSchema<
-  const Validators extends ParamsSchemaProperties = ParamsSchemaProperties,
-  const Options extends ParamsSchemaOptions = ParamsSchemaOptions,
-  Output extends ParamsSchemaOutput<Validators, Options> = ParamsSchemaOutput<
-    Validators,
-    Options
-  >,
-> extends Validator<Output> {
-  readonly lexiconType = 'params' as const
-
-  constructor(
-    readonly validators: Validators,
-    readonly options: Options,
-  ) {
+  const Shape extends ParamsSchemaShape = ParamsSchemaShape,
+> extends Schema<ParamsSchemaOutput<Shape>> {
+  constructor(readonly validators: Shape) {
     super()
   }
 
-  get validatorsMap(): Map<string, Validator<Param>> {
+  get validatorsMap(): Map<string, Validator<Param | undefined>> {
     const map = new Map(Object.entries(this.validators))
 
-    // Cache the map on the instance (to avoid re-creating it)
-    Object.defineProperty(this, 'validatorsMap', {
-      value: map,
-      writable: false,
-      enumerable: false,
-      configurable: true,
-    })
-
-    return map
+    return lazyProperty(this, 'validatorsMap', map)
   }
 
-  override validateInContext(
+  validateInContext(
     input: unknown = {},
     ctx: ValidatorContext,
-  ): ValidationResult<Output> {
+  ): ValidationResult<ParamsSchemaOutput<Shape>> {
     if (!isPlainObject(input)) {
       return ctx.issueInvalidType(input, 'object')
     }
@@ -82,22 +65,19 @@ export class ParamsSchema<
     for (const [key, propDef] of this.validatorsMap) {
       const result = ctx.validateChild(input, key, propDef)
       if (!result.success) {
-        // Because default values are provided by child validators, we need to
-        // run the validator to get the default value and, in case of failure,
-        // ignore validation error that were caused by missing keys.
         if (!(key in input)) {
-          if (!this.options.required?.includes(key)) {
-            // Ignore missing non-required key
-            continue
-          } else {
-            // Transform into "required key" issue
-            return ctx.issueRequiredKey(input, key)
-          }
+          // Transform into "required key" issue
+          return ctx.issueRequiredKey(input, key)
         }
 
         return result
       }
 
+      // Skip copying if key is not present in input (and value is undefined)
+      if (result.value === undefined && !(key in input)) {
+        continue
+      }
+
       if (result.value !== input[key]) {
         // Copy on write
         copy ??= { ...input }
@@ -105,10 +85,12 @@ export class ParamsSchema<
       }
     }
 
-    return ctx.success((copy ?? input) as Output)
+    return ctx.success((copy ?? input) as ParamsSchemaOutput<Shape>)
   }
 
-  fromURLSearchParams(urlSearchParams: URLSearchParams): Output {
+  fromURLSearchParams(
+    urlSearchParams: URLSearchParams,
+  ): ParamsSchemaOutput<Shape> {
     const params: Record<string, Param> = {}
 
     for (const [key, value] of urlSearchParams.entries()) {
@@ -137,7 +119,7 @@ export class ParamsSchema<
     return this.parse(params)
   }
 
-  toURLSearchParams(input: Output): URLSearchParams {
+  toURLSearchParams(input: ParamsSchemaOutput<Shape>): URLSearchParams {
     const urlSearchParams = new URLSearchParams()
 
     if (input !== undefined) {

package/src/schema/payload.test.ts

@@ -0,0 +1,345 @@
+import { IntegerSchema } from './integer.js'
+import { ObjectSchema } from './object.js'
+import { Payload } from './payload.js'
+import { StringSchema } from './string.js'
+import { UnknownSchema } from './unknown.js'
+
+describe('Payload', () => {
+  describe('basic construction', () => {
+    it('creates payload with encoding and no schema', () => {
+      const payload = new Payload('application/json', undefined)
+      expect(payload.encoding).toBe('application/json')
+      expect(payload.schema).toBeUndefined()
+    })
+
+    it('creates payload with encoding and schema', () => {
+      const schema = new ObjectSchema({
+        name: new StringSchema({}),
+      })
+      const payload = new Payload('application/json', schema)
+      expect(payload.encoding).toBe('application/json')
+      expect(payload.schema).toBe(schema)
+    })
+
+    it('creates payload with undefined encoding and undefined schema', () => {
+      const payload = new Payload(undefined, undefined)
+      expect(payload.encoding).toBeUndefined()
+      expect(payload.schema).toBeUndefined()
+    })
+
+    it('creates payload with text encoding', () => {
+      const payload = new Payload('text/plain', undefined)
+      expect(payload.encoding).toBe('text/plain')
+      expect(payload.schema).toBeUndefined()
+    })
+
+    it('creates payload with text/html encoding', () => {
+      const payload = new Payload('text/html', undefined)
+      expect(payload.encoding).toBe('text/html')
+      expect(payload.schema).toBeUndefined()
+    })
+
+    it('creates payload with application/octet-stream encoding', () => {
+      const payload = new Payload('application/octet-stream', undefined)
+      expect(payload.encoding).toBe('application/octet-stream')
+      expect(payload.schema).toBeUndefined()
+    })
+
+    it('creates payload with image encoding', () => {
+      const payload = new Payload('image/png', undefined)
+      expect(payload.encoding).toBe('image/png')
+      expect(payload.schema).toBeUndefined()
+    })
+  })
+
+  describe('encoding types', () => {
+    it('handles application/json encoding', () => {
+      const payload = new Payload('application/json', undefined)
+      expect(payload.encoding).toBe('application/json')
+    })
+
+    it('handles text/* encodings', () => {
+      const textPlain = new Payload('text/plain', undefined)
+      expect(textPlain.encoding).toBe('text/plain')
+
+      const textHtml = new Payload('text/html', undefined)
+      expect(textHtml.encoding).toBe('text/html')
+
+      const textCss = new Payload('text/css', undefined)
+      expect(textCss.encoding).toBe('text/css')
+    })
+
+    it('handles binary encodings', () => {
+      const octetStream = new Payload('application/octet-stream', undefined)
+      expect(octetStream.encoding).toBe('application/octet-stream')
+
+      const imagePng = new Payload('image/png', undefined)
+      expect(imagePng.encoding).toBe('image/png')
+
+      const imageJpeg = new Payload('image/jpeg', undefined)
+      expect(imageJpeg.encoding).toBe('image/jpeg')
+    })
+
+    it('handles custom mime types', () => {
+      const payload = new Payload('application/vnd.custom+json', undefined)
+      expect(payload.encoding).toBe('application/vnd.custom+json')
+    })
+  })
+
+  describe('with schemas', () => {
+    it('creates payload with object schema', () => {
+      const schema = new ObjectSchema({
+        id: new IntegerSchema({}),
+        name: new StringSchema({}),
+      })
+      const payload = new Payload('application/json', schema)
+      expect(payload.encoding).toBe('application/json')
+      expect(payload.schema).toBe(schema)
+    })
+
+    it('creates payload with string schema', () => {
+      const schema = new StringSchema({})
+      const payload = new Payload('application/json', schema)
+      expect(payload.encoding).toBe('application/json')
+      expect(payload.schema).toBe(schema)
+    })
+
+    it('creates payload with integer schema', () => {
+      const schema = new IntegerSchema({})
+      const payload = new Payload('application/json', schema)
+      expect(payload.encoding).toBe('application/json')
+      expect(payload.schema).toBe(schema)
+    })
+
+    it('creates payload with unknown schema', () => {
+      const schema = new UnknownSchema()
+      const payload = new Payload('application/json', schema)
+      expect(payload.encoding).toBe('application/json')
+      expect(payload.schema).toBe(schema)
+    })
+
+    it('creates payload with complex nested schema', () => {
+      const schema = new ObjectSchema({
+        user: new ObjectSchema({
+          id: new IntegerSchema({}),
+          name: new StringSchema({}),
+          email: new StringSchema({ format: 'uri' }),
+        }),
+        metadata: new ObjectSchema({
+          createdAt: new StringSchema({ format: 'datetime' }),
+          updatedAt: new StringSchema({ format: 'datetime' }),
+        }),
+      })
+      const payload = new Payload('application/json', schema)
+      expect(payload.encoding).toBe('application/json')
+      expect(payload.schema).toBe(schema)
+    })
+  })
+
+  describe('validation constraints', () => {
+    it('throws error when schema is defined but encoding is undefined', () => {
+      const schema = new StringSchema({})
+      expect(() => {
+        // @ts-expect-error
+        new Payload(undefined, schema)
+      }).toThrow(TypeError)
+      expect(() => {
+        // @ts-expect-error
+        new Payload(undefined, schema)
+      }).toThrow('schema cannot be defined when encoding is undefined')
+    })
+
+    it('throws error when object schema is defined but encoding is undefined', () => {
+      const schema = new ObjectSchema({
+        name: new StringSchema({}),
+      })
+      expect(() => {
+        // @ts-expect-error
+        new Payload(undefined, schema)
+      }).toThrow(TypeError)
+      expect(() => {
+        // @ts-expect-error
+        new Payload(undefined, schema)
+      }).toThrow('schema cannot be defined when encoding is undefined')
+    })
+
+    it('throws error when integer schema is defined but encoding is undefined', () => {
+      const schema = new IntegerSchema({})
+      expect(() => {
+        // @ts-expect-error
+        new Payload(undefined, schema)
+      }).toThrow(TypeError)
+    })
+
+    it('allows undefined encoding with undefined schema', () => {
+      expect(() => {
+        new Payload(undefined, undefined)
+      }).not.toThrow()
+    })
+
+    it('allows defined encoding with undefined schema', () => {
+      expect(() => {
+        new Payload('application/json', undefined)
+      }).not.toThrow()
+    })
+
+    it('allows defined encoding with defined schema', () => {
+      const schema = new StringSchema({})
+      expect(() => {
+        new Payload('application/json', schema)
+      }).not.toThrow()
+    })
+  })
+
+  describe('property access', () => {
+    it('has accessible encoding property', () => {
+      const payload = new Payload('application/json', undefined)
+      expect(payload.encoding).toBe('application/json')
+    })
+
+    it('has accessible schema property', () => {
+      const schema = new StringSchema({})
+      const payload = new Payload('application/json', schema)
+      expect(payload.schema).toBe(schema)
+    })
+
+    it('encoding property is immutable in TypeScript', () => {
+      const payload = new Payload('application/json', undefined)
+      // TypeScript enforces readonly at compile time
+      expect(payload.encoding).toBe('application/json')
+    })
+
+    it('schema property is immutable in TypeScript', () => {
+      const schema = new StringSchema({})
+      const payload = new Payload('application/json', schema)
+      // TypeScript enforces readonly at compile time
+      expect(payload.schema).toBe(schema)
+    })
+  })
+
+  describe('usage scenarios', () => {
+    it('creates payload for JSON API response', () => {
+      const payload = new Payload(
+        'application/json',
+        new ObjectSchema({
+          success: new StringSchema({}),
+          data: new UnknownSchema(),
+        }),
+      )
+      expect(payload.encoding).toBe('application/json')
+      expect(payload.schema).toBeDefined()
+    })
+
+    it('creates payload for plain text response', () => {
+      const payload = new Payload('text/plain', undefined)
+      expect(payload.encoding).toBe('text/plain')
+      expect(payload.schema).toBeUndefined()
+    })
+
+    it('creates payload for binary data', () => {
+      const payload = new Payload('application/octet-stream', undefined)
+      expect(payload.encoding).toBe('application/octet-stream')
+      expect(payload.schema).toBeUndefined()
+    })
+
+    it('creates payload for image upload', () => {
+      const payload = new Payload('image/jpeg', undefined)
+      expect(payload.encoding).toBe('image/jpeg')
+      expect(payload.schema).toBeUndefined()
+    })
+
+    it('creates payload for multipart form data', () => {
+      const payload = new Payload('multipart/form-data', undefined)
+      expect(payload.encoding).toBe('multipart/form-data')
+      expect(payload.schema).toBeUndefined()
+    })
+
+    it('creates payload for URL encoded form', () => {
+      const payload = new Payload(
+        'application/x-www-form-urlencoded',
+        undefined,
+      )
+      expect(payload.encoding).toBe('application/x-www-form-urlencoded')
+      expect(payload.schema).toBeUndefined()
+    })
+
+    it('creates empty payload (no encoding, no schema)', () => {
+      const payload = new Payload(undefined, undefined)
+      expect(payload.encoding).toBeUndefined()
+      expect(payload.schema).toBeUndefined()
+    })
+  })
+
+  describe('edge cases', () => {
+    it('handles encoding with charset parameter', () => {
+      const payload = new Payload('application/json; charset=utf-8', undefined)
+      expect(payload.encoding).toBe('application/json; charset=utf-8')
+    })
+
+    it('handles encoding with multiple parameters', () => {
+      const payload = new Payload(
+        'multipart/form-data; boundary=something',
+        undefined,
+      )
+      expect(payload.encoding).toBe('multipart/form-data; boundary=something')
+    })
+
+    it('handles empty string encoding', () => {
+      const payload = new Payload('', undefined)
+      expect(payload.encoding).toBe('')
+    })
+
+    it('creates multiple payloads with same schema reference', () => {
+      const sharedSchema = new ObjectSchema({
+        id: new IntegerSchema({}),
+      })
+      const payload1 = new Payload('application/json', sharedSchema)
+      const payload2 = new Payload('application/json', sharedSchema)
+
+      expect(payload1.schema).toBe(payload2.schema)
+      expect(payload1.schema).toBe(sharedSchema)
+    })
+
+    it('creates multiple payloads with different schemas', () => {
+      const schema1 = new StringSchema({})
+      const schema2 = new IntegerSchema({})
+      const payload1 = new Payload('application/json', schema1)
+      const payload2 = new Payload('application/json', schema2)
+
+      expect(payload1.schema).not.toBe(payload2.schema)
+      expect(payload1.schema).toBe(schema1)
+      expect(payload2.schema).toBe(schema2)
+    })
+  })
+
+  describe('type inference scenarios', () => {
+    it('works with application/json and object schema', () => {
+      const schema = new ObjectSchema({
+        message: new StringSchema({}),
+      })
+      const payload = new Payload('application/json', schema)
+      expect(payload.encoding).toBe('application/json')
+      expect(payload.schema).toBe(schema)
+    })
+
+    it('works with text/* encodings expecting string bodies', () => {
+      const payload1 = new Payload('text/plain', undefined)
+      const payload2 = new Payload('text/html', undefined)
+      const payload3 = new Payload('text/csv', undefined)
+
+      expect(payload1.encoding).toBe('text/plain')
+      expect(payload2.encoding).toBe('text/html')
+      expect(payload3.encoding).toBe('text/csv')
+    })
+
+    it('works with binary encodings expecting Uint8Array bodies', () => {
+      const payload1 = new Payload('image/png', undefined)
+      const payload2 = new Payload('application/octet-stream', undefined)
+      const payload3 = new Payload('video/mp4', undefined)
+
+      expect(payload1.encoding).toBe('image/png')
+      expect(payload2.encoding).toBe('application/octet-stream')
+      expect(payload3.encoding).toBe('video/mp4')
+    })
+  })
+})

package/src/schema/payload.ts

@@ -1,5 +1,5 @@
 import { LexValue } from '@atproto/lex-data'
-import { Validator } from '../validation.js'
+import { Infer, Validator } from '../validation.js'
 
 export type LexBody<E extends string = any> = E extends `text/${string}`
   ? string // Text encodings always yield string bodies
@@ -12,8 +12,8 @@ export type InferPayloadEncoding<P extends Payload> =
 
 export type InferPayloadBody<P extends Payload> =
   P extends Payload<any, infer S>
-    ? S extends Validator<infer V>
-      ? V
+    ? S extends Validator
+      ? Infer<S>
       : P extends Payload<infer E extends string>
         ? LexBody<E>
         : undefined
@@ -23,10 +23,10 @@ export type PayloadOutput<
   E extends string | undefined = any,
   S extends Validator | undefined = any,
 > = E extends string
-  ? S extends Validator<infer V>
+  ? S extends Validator
     ? {
         encoding: E
-        body: V
+        body: Infer<S>
       }
     : {
         encoding: E