@atproto/lex-schema 0.1.5 → 0.1.6

package/src/schema/record.ts

@@ -1,217 +0,0 @@
-import { LexMap } from '@atproto/lex-data'
-import {
-  $Typed,
-  $typed,
-  InferInput,
-  InferOutput,
-  LexiconRecordKey,
-  NsidString,
-  RecordKeyValue,
-  Schema,
-  Unknown$TypedObject,
-  ValidationContext,
-  Validator,
-} from '../core.js'
-import { lazyProperty } from '../util/lazy-property.js'
-import { literal } from './literal.js'
-import { string } from './string.js'
-import { withDefault } from './with-default.js'
-
-/**
- * Infers the record key type from a RecordSchema.
- *
- * @template R - The RecordSchema type
- */
-export type InferRecordKey<R extends RecordSchema> =
-  R extends RecordSchema<infer TKey> ? RecordKeyValue<TKey> : never
-
-export type TypedRecord<
-  TType extends NsidString,
-  TValue extends { $type?: unknown } = { $type?: unknown },
-> = TValue extends { $type: TType }
-  ? TValue
-  : $Typed<Exclude<TValue, Unknown$TypedObject>, TType>
-
-/**
- * Schema for AT Protocol records with a type identifier and key constraints.
- *
- * Records are the primary data unit in AT Protocol. Each record has a `$type`
- * field identifying its Lexicon schema, and is stored at a specific key
- * (TID, NSID, or other format) in a repository.
- *
- * @template TKey - The record key type ('tid', 'nsid', 'any', or 'literal:...')
- * @template TType - The NSID string identifying this record type
- * @template TShape - The validator type for the record's data shape
- *
- * @example
- * ```ts
- * const postSchema = new RecordSchema(
- *   'tid',
- *   'app.bsky.feed.post',
- *   l.object({ text: l.string(), createdAt: l.string() })
- * )
- * ```
- */
-export class RecordSchema<
-  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>
-> {
-  readonly type = 'record' as const
-
-  keySchema: RecordKeySchema<TKey>
-
-  constructor(
-    readonly key: TKey,
-    readonly $type: TType,
-    readonly schema: TShape,
-  ) {
-    super()
-    this.keySchema = recordKey(key)
-  }
-
-  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(
-    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 }>(
-    value: TValue,
-  ): value is TypedRecord<TType, TValue> {
-    return value.$type === this.$type
-  }
-
-  /**
-   * 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))
-  }
-
-  /**
-   * 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))
-  }
-}
-
-export type RecordKeySchemaOutput<Key extends LexiconRecordKey> =
-  RecordKeyValue<Key>
-
-export type RecordKeySchema<Key extends LexiconRecordKey> = Schema<
-  RecordKeyValue<Key>
->
-
-const keySchema = string({ format: 'record-key' })
-const tidSchema = string({ format: 'tid' })
-const nsidSchema = string({ format: 'nsid' })
-const selfLiteralSchema = withDefault(literal('self'), 'self')
-
-function recordKey<Key extends LexiconRecordKey>(
-  key: Key,
-): RecordKeySchema<Key> {
-  // @NOTE Use cached instances for common schemas
-  if (key === 'any') return keySchema as any
-  if (key === 'tid') return tidSchema as any
-  if (key === 'nsid') return nsidSchema as any
-  if (key.startsWith('literal:')) {
-    const value = key.slice(8) as RecordKeyValue<Key>
-    if (value === 'self') return selfLiteralSchema as any
-    return withDefault(literal(value), value)
-  }
-
-  throw new Error(`Unsupported record key type: ${key}`)
-}
-
-/**
- * Ensures that a `$type` used in a record is a valid NSID (i.e. no fragment).
- */
-type AsNsid<T> = T extends `${string}#${string}` ? never : T
-
-/**
- * Creates a record schema for AT Protocol records.
- *
- * Records are the primary data unit in AT Protocol repositories. They have
- * a `$type` field identifying their Lexicon schema, and are stored at keys
- * following a specific format (TID, NSID, etc.).
- *
- * This function offers two overloads:
- * - One that infers the output type from the provided arguments (does not
- *   support circular references)
- * - One with an explicitly defined interface for use with codegen and
- *   circular references
- *
- * @param key - The record key type: 'tid', 'nsid', 'any', or 'literal:value'
- * @param type - The NSID identifying this record type (e.g., 'app.bsky.feed.post')
- * @param validator - Schema validator for the record's properties
- * @returns A new {@link RecordSchema} instance
- *
- * @example
- * ```ts
- * // Post record with TID key
- * const postSchema = l.record('tid', 'app.bsky.feed.post', l.object({
- *   text: l.string({ maxGraphemes: 300 }),
- *   createdAt: l.string({ format: 'datetime' }),
- *   reply: l.optional(l.object({
- *     root: l.ref(() => strongRefSchema),
- *     parent: l.ref(() => strongRefSchema),
- *   })),
- * }))
- *
- * // Profile record with literal 'self' key
- * const profileSchema = l.record('literal:self', 'app.bsky.actor.profile', l.object({
- *   displayName: l.optional(l.string({ maxGraphemes: 64 })),
- *   description: l.optional(l.string({ maxGraphemes: 256 })),
- *   avatar: l.optional(l.blob({ accept: ['image/*'] })),
- * }))
- *
- * // Build a record with automatic $type injection
- * const post = postSchema.build({ text: 'Hello!', createdAt: new Date().toISOString() })
- * ```
- */
-export function record<
-  const K extends LexiconRecordKey,
-  const T extends NsidString,
-  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 LexMap & { $type: NsidString },
->(
-  key: K,
-  type: AsNsid<V['$type']>,
-  validator: Validator<Omit<V, '$type'>>,
-): RecordSchema<K, V['$type'], Validator<Omit<V, '$type'>>>
-/*@__NO_SIDE_EFFECTS__*/
-export function record<
-  const K extends LexiconRecordKey,
-  const T extends NsidString,
-  const S extends Validator<LexMap>,
->(key: K, type: T, validator: S) {
-  return new RecordSchema<K, T, S>(key, type, validator)
-}

package/src/schema/ref.test.ts

@@ -1,349 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { Schema, Validator } from '../core.js'
-import { integer } from './integer.js'
-import { object } from './object.js'
-import { optional } from './optional.js'
-import { ref } from './ref.js'
-import { string } from './string.js'
-
-describe('RefSchema', () => {
-  describe('basic validation', () => {
-    it('validates through a simple string reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = string()
-      const result = schema.safeParse('hello')
-      expect(result.success).toBe(true)
-    })
-
-    it('validates through an integer reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = integer()
-      const result = schema.safeParse(42)
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects invalid input through reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = string()
-      const result = schema.safeParse(123)
-      expect(result.success).toBe(false)
-    })
-
-    it('validates null rejection through reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = string()
-      const result = schema.safeParse(null)
-      expect(result.success).toBe(false)
-    })
-
-    it('validates undefined rejection through reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = integer()
-      const result = schema.safeParse(undefined)
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('lazy schema resolution', () => {
-    it('does not call getter until first validation', () => {
-      let getterCalled = false
-      const schema = ref(() => {
-        getterCalled = true
-        return string()
-      })
-      expect(getterCalled).toBe(false)
-
-      schema.safeParse('test')
-      expect(getterCalled).toBe(true)
-    })
-
-    it('throws error if getter is called multiple times', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = string()
-
-      // Access schema property to resolve it
-      void schema.validator
-
-      // Try to access the original getter again (which should throw)
-      // This is internal behavior, but we're testing the protection mechanism
-      expect(() => {
-        // Force access to the cached schema property
-        const schemaValue = schema.validator
-        // This should work fine as it's now cached
-        expect(schemaValue).toBeDefined()
-      }).not.toThrow()
-    })
-  })
-
-  describe('with object schemas', () => {
-    it('validates objects through reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = object({
-        name: string(),
-        age: integer(),
-      })
-
-      expect(
-        schema.safeValidate({
-          name: 'Alice',
-          age: 30,
-        }),
-      ).toMatchObject({
-        success: true,
-      })
-    })
-
-    it('rejects invalid objects through reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = object({
-        name: string(),
-        age: integer(),
-      })
-      const result = schema.safeParse({
-        name: 'Alice',
-        age: 'thirty',
-      })
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects objects with missing properties through reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = object({
-        name: string(),
-        age: integer(),
-      })
-      const result = schema.safeParse({
-        name: 'Alice',
-      })
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('with constrained schemas', () => {
-    it('validates string with minLength constraint through reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = string({ minLength: 5 })
-      const result = schema.safeParse('hello')
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects string violating minLength through reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = string({ minLength: 5 })
-      const result = schema.safeParse('hi')
-      expect(result.success).toBe(false)
-    })
-
-    it('validates integer with range constraints through reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = integer({ minimum: 0, maximum: 100 })
-      const result = schema.safeParse(50)
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects integer violating constraints through reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = integer({ minimum: 0, maximum: 100 })
-      const result = schema.safeParse(150)
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('circular references', () => {
-    it('supports indirect circular references', () => {
-      // Create two schemas that reference each other
-      // This demonstrates forward references are possible
-
-      type A = { value: string; ref?: B }
-      type B = { value: number; ref?: A }
-
-      const schemaA: Schema<A> = object({
-        value: string(),
-        ref: optional(ref<Validator<B>>((() => schemaB) as any)),
-      })
-
-      const schemaB: Schema<B> = object({
-        value: integer(),
-        ref: optional(ref<Validator<A>>((() => schemaA) as any)),
-      })
-
-      expect(
-        schemaB.matches({
-          value: 42,
-          ref: {
-            value: 'hello',
-            ref: {
-              value: 3,
-            },
-          },
-        }),
-      ).toBe(true)
-
-      expect(
-        schemaA.matches({
-          value: 'hello',
-          ref: {
-            value: 3,
-            ref: {
-              value: 'world',
-            },
-          },
-        }),
-      ).toBe(true)
-    })
-  })
-
-  describe('multiple validations', () => {
-    it('validates multiple inputs correctly', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = string({ minLength: 3 })
-
-      const result1 = schema.safeParse('hello')
-      expect(result1.success).toBe(true)
-
-      const result2 = schema.safeParse('hi')
-      expect(result2.success).toBe(false)
-
-      const result3 = schema.safeParse('world')
-      expect(result3.success).toBe(true)
-
-      const result4 = schema.safeParse('no')
-      expect(result4.success).toBe(false)
-    })
-
-    it('handles different types of validation failures', () => {
-      const schema = ref(() =>
-        object({
-          name: string({ minLength: 2 }),
-          age: integer({ minimum: 0 }),
-        }),
-      )
-
-      const result1 = schema.safeParse({ name: 'A', age: 25 })
-      expect(result1.success).toBe(false)
-
-      const result2 = schema.safeParse({ name: 'Alice', age: -5 })
-      expect(result2.success).toBe(false)
-
-      const result3 = schema.safeParse({ name: 'Alice', age: 25 })
-      expect(result3.success).toBe(true)
-    })
-  })
-
-  describe('edge cases', () => {
-    it('handles empty string validation', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = string()
-      const result = schema.safeParse('')
-      expect(result.success).toBe(true)
-    })
-
-    it('handles zero validation', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = integer()
-      const result = schema.safeParse(0)
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects NaN through integer reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = integer()
-      const result = schema.safeParse(NaN)
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects Infinity through integer reference', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = integer()
-      const result = schema.safeParse(Infinity)
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects arrays when expecting string', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = string()
-      const result = schema.safeParse(['array'])
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects objects when expecting string', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = string()
-      const result = schema.safeParse({ key: 'value' })
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects booleans when expecting string', () => {
-      const schema = ref(() => innerSchema)
-      const innerSchema = string()
-      const result = schema.safeParse(true)
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('nested references', () => {
-    it('validates through nested RefSchema', () => {
-      const innerRef = ref(() => innerSchema)
-      const innerSchema = string({ minLength: 3 })
-      const outerRef = ref(() => innerRef)
-
-      const result = outerRef.safeParse('hello')
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects invalid input through nested RefSchema', () => {
-      const innerRef = ref(() => innerSchema)
-      const innerSchema = string({ minLength: 3 })
-      const outerRef = ref(() => innerRef)
-
-      const result = outerRef.safeParse('hi')
-      expect(result.success).toBe(false)
-    })
-
-    it('validates with deeply nested references', () => {
-      const level3 = ref(() => innerSchema)
-      const innerSchema = integer({ minimum: 0 })
-      const level2 = ref(() => level3)
-      const level1 = ref(() => level2)
-
-      const result = level1.safeParse(42)
-      expect(result.success).toBe(true)
-    })
-  })
-
-  describe('schema property access', () => {
-    it('allows direct access to resolved schema', () => {
-      const innerSchema = string({ minLength: 5 })
-      const refSchema = ref(() => innerSchema)
-
-      const resolved = refSchema.validator
-      expect(resolved).toBe(innerSchema)
-    })
-
-    it('returns same instance on multiple schema property accesses', () => {
-      const innerSchema = string()
-      const refSchema = ref(() => innerSchema)
-
-      const first = refSchema.validator
-      const second = refSchema.validator
-      const third = refSchema.validator
-
-      expect(first).toBe(second)
-      expect(second).toBe(third)
-    })
-
-    it('resolves schema before validation', () => {
-      let resolved = false
-      const refSchema = ref(() => {
-        resolved = true
-        return string()
-      })
-
-      expect(resolved).toBe(false)
-
-      const schemaValue = refSchema.validator
-      expect(resolved).toBe(true)
-      expect(schemaValue).toBeDefined()
-    })
-  })
-})

package/src/schema/ref.ts

@@ -1,103 +0,0 @@
-import {
-  InferInput,
-  InferOutput,
-  Schema,
-  ValidationContext,
-  Validator,
-  WrappedValidator,
-} from '../core.js'
-
-/**
- * Function type that returns a validator, used for lazy schema resolution.
- *
- * @template TValidator - The validator type that will be returned
- */
-export type RefSchemaGetter<out TValidator extends Validator> = () => TValidator
-
-/**
- * Schema for creating references to other schemas with lazy resolution.
- *
- * Useful for handling circular references or breaking module dependency cycles.
- * The referenced schema is resolved lazily when first needed for validation.
- *
- * @template TValidator - The referenced validator type
- *
- * @example
- * ```ts
- * // Self-referential schema for tree structure
- * const nodeSchema = l.object({
- *   value: l.string(),
- *   children: l.array(l.ref(() => nodeSchema)),
- * })
- * ```
- */
-export class RefSchema<const TValidator extends Validator>
-  extends Schema<InferInput<TValidator>, InferOutput<TValidator>>
-  implements WrappedValidator<TValidator>
-{
-  readonly type = 'ref' as const
-
-  #getter: RefSchemaGetter<TValidator>
-
-  constructor(getter: RefSchemaGetter<TValidator>) {
-    // @NOTE In order to avoid circular dependency issues, we don't resolve
-    // the schema here. Instead, we resolve it lazily when first accessed.
-
-    super()
-
-    this.#getter = getter
-  }
-
-  get validator(): TValidator {
-    return this.#getter.call(null)
-  }
-
-  unwrap(): TValidator {
-    return this.validator
-  }
-
-  validateInContext(input: unknown, ctx: ValidationContext) {
-    return ctx.validate(input, this.validator)
-  }
-}
-
-/**
- * Creates a reference schema with lazy resolution.
- *
- * Allows referencing schemas that may not be defined yet, enabling
- * circular references and breaking dependency cycles. The getter function
- * is called lazily when validation is first performed.
- *
- * @param get - Function that returns the referenced validator
- * @returns A new {@link RefSchema} instance
- *
- * @example
- * ```ts
- * // Circular reference - tree node that contains children of the same type
- * const treeNodeSchema = l.object({
- *   name: l.string(),
- *   children: l.optional(l.array(l.ref(() => treeNodeSchema))),
- * })
- *
- * // Cross-module reference
- * const commentSchema = l.object({
- *   text: l.string(),
- *   author: l.ref(() => userSchema), // userSchema defined elsewhere
- * })
- *
- * // Explicitly typed reference
- * const itemSchema = l.ref<Item>(() => complexItemSchema)
- * ```
- */
-/*@__NO_SIDE_EFFECTS__*/
-export function ref<const TValidator extends Validator>(
-  get: RefSchemaGetter<TValidator>,
-): RefSchema<TValidator>
-export function ref<TInput, TOutput extends TInput = TInput>(
-  get: RefSchemaGetter<Validator<TInput, TOutput>>,
-): RefSchema<Validator<TInput, TOutput>>
-export function ref<const TValidator extends Validator>(
-  get: RefSchemaGetter<TValidator>,
-) {
-  return new RefSchema<TValidator>(get)
-}