@atproto/lex-schema 0.0.13 → 0.0.15

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,6 +1,6 @@
-import { PropertyKey } from './property-key.js'
-import { ResultFailure, ResultSuccess, failure, success } from './result.js'
-import { ValidationError } from './validation-error.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,
   IssueInvalidFormat,
@@ -20,16 +20,20 @@ import {
 export type ValidationSuccess<Value = unknown> = ResultSuccess<Value>
 
 /**
- * Represents a failed validation result containing a {@link ValidationError}.
+ * Represents a failed validation result containing a {@link LexValidationError}.
+ *
+ * @extends ResultFailure<LexValidationError>
+ * @see {@link ResultFailure}
+ * @see {@link LexValidationError}
  */
-export type ValidationFailure = ResultFailure<ValidationError>
+export type ValidationFailure = LexValidationError
 
 /**
  * Discriminated union representing the outcome of a validation operation.
  *
  * Check the `success` property to determine if validation passed or failed:
  * - If `success` is `true`, the `value` property contains the validated data
- * - If `success` is `false`, the `reason` property contains the {@link ValidationError}
+ * - If `success` is `false`, the `reason` property contains the {@link LexValidationError}
  *
  * @typeParam Value - The type of the validated value on success
  *
@@ -39,7 +43,7 @@ export type ValidationFailure = ResultFailure<ValidationError>
  * if (result.success) {
  *   // result.value is string
  * } else {
- *   // result.reason is ValidationError
+ *   // result.reason is LexValidationError
  * }
  * ```
  */
@@ -326,7 +330,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 ValidationError(Array.from(this.issues)))
+        return new LexValidationError(Array.from(this.issues))
       }
 
       if (this.options.mode !== 'parse' && !Object.is(result.value, input)) {
@@ -341,7 +345,7 @@ export class ValidationContext {
         // another.
 
         // This if block comes before the next one because 'this.issues' will
-        // end-up being appended to the returned ValidationError (see the
+        // end-up being appended to the returned LexValidationError (see the
         // "failure" method below), resulting in a more complete error report.
         return this.issueInvalidValue(input, [result.value])
       }
@@ -425,8 +429,8 @@ export class ValidationContext {
    * @param reason - The validation error
    * @returns A failed validation result
    */
-  failure(reason: ValidationError): ValidationFailure {
-    return failure(reason)
+  failure(reason: LexValidationError): ValidationFailure {
+    return reason
   }
 
   /**
@@ -438,7 +442,7 @@ export class ValidationContext {
    * @returns A failed validation result
    */
   issue(issue: Issue) {
-    return this.failure(new ValidationError([...this.issues, issue]))
+    return this.failure(new LexValidationError([...this.issues, issue]))
   }
 
   /**

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/custom.ts

@@ -1,10 +1,4 @@
-import {
-  Issue,
-  IssueCustom,
-  PropertyKey,
-  Schema,
-  ValidationContext,
-} from '../core.js'
+import { Issue, IssueCustom, Schema, ValidationContext } from '../core.js'
 
 /**
  * Context object provided to custom assertion functions.

package/src/schema/params.test.ts

@@ -419,7 +419,7 @@ describe('ParamsSchema', () => {
           ['name', 'Alice'],
           ['bools', 'notabool'],
         ]),
-      ).toThrow('Expected boolean value type at $.bools (got string)')
+      ).toThrow('Expected boolean value type (got string) at $.bools')
 
       expect(() =>
         schema.fromURLSearchParams(
@@ -431,7 +431,23 @@ describe('ParamsSchema', () => {
             path: ['foo', 'bar'],
           },
         ),
-      ).toThrow('Expected boolean value type at $.foo.bar.bools (got string)')
+      ).toThrow('Expected boolean value type (got string) at $.foo.bar.bools')
+    })
+
+    it('ignores empty string values', () => {
+      const result = schema.fromURLSearchParams([
+        ['name', 'Alice'],
+        ['extra', ''],
+      ])
+      expect(result).toEqual({ name: 'Alice' })
+    })
+
+    it('ignores empty string values for known parameters', () => {
+      const result = schema.fromURLSearchParams([
+        ['name', 'Alice'],
+        ['age', ''],
+      ])
+      expect(result).toEqual({ name: 'Alice' })
     })
   })
 

package/src/schema/params.ts

@@ -6,10 +6,10 @@ import {
   Issue,
   IssueInvalidType,
   IssueInvalidValue,
+  LexValidationError,
   ParseOptions,
   Schema,
   ValidationContext,
-  ValidationError,
   Validator,
   WithOptionalProperties,
 } from '../core.js'
@@ -209,6 +209,9 @@ export class ParamsSchema<
       iterable instanceof URLSearchParams ? iterable.entries() : iterable
 
     for (const [name, value] of entries) {
+      // Ignore empty strings
+      if (!value) continue
+
       const validator = this.shapeValidators.get(name)
       const innerValidator = validator ? unwrapSchema(validator) : undefined
       const expectsArray = innerValidator instanceof ArraySchema
@@ -302,7 +305,7 @@ function coerceParam(
   // the index of the param in case of array params (e.g. "tags[1]"), which
   // could be helpful for debugging. The cost overhead is not worth it though
   // (IMO).
-  throw new ValidationError([issue])
+  throw new LexValidationError([issue])
 }
 
 function paramPath(key: string, options?: ParseOptions) {

package/src/schema/record.ts

@@ -11,6 +11,7 @@ import {
   ValidationContext,
   Validator,
 } from '../core.js'
+import { lazyProperty } from '../util/lazy-property.js'
 import { literal } from './literal.js'
 import { string } from './string.js'
 
@@ -70,10 +71,18 @@ export class RecordSchema<
     this.keySchema = recordKey(key)
   }
 
-  isTypeOf<TValue extends { $type?: unknown }>(
-    value: TValue,
-  ): value is TypedRecord<TType, TValue> {
-    return value.$type === this.$type
+  validateInContext(input: unknown, ctx: ValidationContext) {
+    const result = ctx.validate(input, this.schema)
+
+    if (!result.success) {
+      return result
+    }
+
+    if (result.value.$type !== this.$type) {
+      return ctx.issueInvalidPropertyValue(result.value, '$type', [this.$type])
+    }
+
+    return result
   }
 
   build(
@@ -82,30 +91,26 @@ export class RecordSchema<
     return this.parse($typed(input, this.$type))
   }
 
-  $isTypeOf<TValue extends { $type?: unknown }>(
+  isTypeOf<TValue extends { $type?: unknown }>(
     value: TValue,
   ): value is TypedRecord<TType, TValue> {
-    return this.isTypeOf<TValue>(value)
+    return value.$type === this.$type
   }
 
-  $build(
-    input: Omit<InferInput<this>, '$type'>,
-  ): $Typed<InferOutput<this>, TType> {
-    return this.build(input)
+  /**
+   * Bound alias for {@link build} for compatibility with generated utilities.
+   * @see {@link build}
+   */
+  get $build(): typeof this.build {
+    return lazyProperty(this, '$build', this.build.bind(this))
   }
 
-  validateInContext(input: unknown, ctx: ValidationContext) {
-    const result = ctx.validate(input, this.schema)
-
-    if (!result.success) {
-      return result
-    }
-
-    if (result.value.$type !== this.$type) {
-      return ctx.issueInvalidPropertyValue(result.value, '$type', [this.$type])
-    }
-
-    return result
+  /**
+   * Bound alias for {@link isTypeOf} for compatibility with generated utilities.
+   * @see {@link isTypeOf}
+   */
+  get $isTypeOf(): typeof this.isTypeOf {
+    return lazyProperty(this, '$isTypeOf', this.isTypeOf.bind(this))
   }
 }
 

package/src/schema/ref.ts

@@ -32,11 +32,7 @@ export type RefSchemaGetter<out TValidator extends Validator> = () => TValidator
  * ```
  */
 export class RefSchema<const TValidator extends Validator>
-  extends Schema<
-    InferInput<TValidator>,
-    InferOutput<TValidator>,
-    TValidator['__lex']
-  >
+  extends Schema<InferInput<TValidator>, InferOutput<TValidator>>
   implements WrappedValidator<TValidator>
 {
   readonly type = 'ref' as const

package/src/schema/refine.ts

@@ -1,7 +1,6 @@
 import {
   InferInput,
   IssueCustom,
-  PropertyKey,
   ValidationContext,
   ValidationResult,
   Validator,

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

@@ -332,6 +332,44 @@ describe('TypedObjectSchema', () => {
     })
   })
 
+  describe('bound $ methods', () => {
+    it('$build can be used as a detached function', () => {
+      const { $build } = schema
+      const result = $build({ text: 'Hello' })
+      expect(result).toEqual({
+        text: 'Hello',
+        $type: 'app.bsky.feed.post',
+      })
+    })
+
+    it('$isTypeOf can be used as a detached function', () => {
+      const { $isTypeOf } = schema
+      expect($isTypeOf({ text: 'Hello' })).toBe(true)
+      expect($isTypeOf({ $type: 'app.bsky.feed.post', text: 'Hello' })).toBe(
+        true,
+      )
+      expect($isTypeOf({ $type: 'other.type', text: 'Hello' })).toBe(false)
+    })
+
+    it('$parse can be used as a detached function', () => {
+      const { $parse } = schema
+      const result = $parse({ text: 'Hello' })
+      expect(result).toEqual({ text: 'Hello' })
+    })
+
+    it('$matches can be used as a detached function', () => {
+      const { $matches } = schema
+      expect($matches({ text: 'Hello' })).toBe(true)
+      expect($matches(42)).toBe(false)
+    })
+
+    it('lazy property returns the same function on repeated access', () => {
+      const fn1 = schema.$build
+      const fn2 = schema.$build
+      expect(fn1).toBe(fn2)
+    })
+  })
+
   describe('with complex nested schemas', () => {
     const complexSchema = typedObject(
       'app.bsky.actor.profile',

package/src/schema/typed-object.ts

@@ -14,6 +14,7 @@ import {
   ValidationContext,
   Validator,
 } from '../core.js'
+import { lazyProperty } from '../util/lazy-property.js'
 
 export type MaybeTypedObject<
   TType extends $Type,
@@ -56,10 +57,20 @@ export class TypedObjectSchema<
     super()
   }
 
-  isTypeOf<TValue extends Record<string, unknown>>(
-    value: TValue,
-  ): value is MaybeTypedObject<TType, TValue> {
-    return value.$type === undefined || value.$type === this.$type
+  validateInContext(input: unknown, ctx: ValidationContext) {
+    if (!isPlainObject(input)) {
+      return ctx.issueUnexpectedType(input, 'object')
+    }
+
+    if (
+      '$type' in input &&
+      input.$type !== undefined &&
+      input.$type !== this.$type
+    ) {
+      return ctx.issueInvalidPropertyValue(input, '$type', [this.$type])
+    }
+
+    return ctx.validate(input, this.schema)
   }
 
   build(
@@ -71,32 +82,26 @@ export class TypedObjectSchema<
     >
   }
 
-  $isTypeOf<TValue extends Record<string, unknown>>(
+  isTypeOf<TValue extends Record<string, unknown>>(
     value: TValue,
   ): value is MaybeTypedObject<TType, TValue> {
-    return this.isTypeOf(value)
+    return value.$type === undefined || value.$type === this.$type
   }
 
-  $build(
-    input: Omit<InferInput<this>, '$type'>,
-  ): $Typed<InferOutput<this>, TType> {
-    return this.build(input)
+  /**
+   * Bound alias for {@link build} for compatibility with generated utilities.
+   * @see {@link build}
+   */
+  get $build(): typeof this.build {
+    return lazyProperty(this, '$build', this.build.bind(this))
   }
 
-  validateInContext(input: unknown, ctx: ValidationContext) {
-    if (!isPlainObject(input)) {
-      return ctx.issueUnexpectedType(input, 'object')
-    }
-
-    if (
-      '$type' in input &&
-      input.$type !== undefined &&
-      input.$type !== this.$type
-    ) {
-      return ctx.issueInvalidPropertyValue(input, '$type', [this.$type])
-    }
-
-    return ctx.validate(input, this.schema)
+  /**
+   * Bound alias for {@link isTypeOf} for compatibility with generated utilities.
+   * @see {@link isTypeOf}
+   */
+  get $isTypeOf(): typeof this.isTypeOf {
+    return lazyProperty(this, '$isTypeOf', this.isTypeOf.bind(this))
   }
 }
 

package/src/schema/union.ts

@@ -1,9 +1,9 @@
 import {
   InferInput,
   InferOutput,
+  LexValidationError,
   Schema,
   ValidationContext,
-  ValidationError,
   ValidationFailure,
   Validator,
 } from '../core.js'
@@ -53,7 +53,7 @@ export class UnionSchema<
       failures.push(result)
     }
 
-    return ctx.failure(ValidationError.fromFailures(failures))
+    return ctx.failure(LexValidationError.fromFailures(failures))
   }
 }
 

package/dist/core/property-key.d.ts

@@ -1,2 +0,0 @@
-export type PropertyKey = string | number;
-//# sourceMappingURL=property-key.d.ts.map

package/dist/core/property-key.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"property-key.d.ts","sourceRoot":"","sources":["../../src/core/property-key.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAA"}

package/dist/core/property-key.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=property-key.js.map

package/dist/core/property-key.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"property-key.js","sourceRoot":"","sources":["../../src/core/property-key.ts"],"names":[],"mappings":"","sourcesContent":["export type PropertyKey = string | number\n"]}

package/src/core/property-key.ts

@@ -1 +0,0 @@
-export type PropertyKey = string | number