@atproto/lex-builder 0.1.4 → 0.1.5

package/src/lex-def-builder.ts

@@ -1,1035 +0,0 @@
-import {
-  JSDocStructure,
-  OptionalKind,
-  SourceFile,
-  VariableDeclarationKind,
-} from 'ts-morph'
-import {
-  LexiconArray,
-  LexiconArrayItems,
-  LexiconBlob,
-  LexiconBoolean,
-  LexiconBytes,
-  LexiconCid,
-  LexiconDocument,
-  LexiconError,
-  LexiconIndexer,
-  LexiconInteger,
-  LexiconMessage,
-  LexiconObject,
-  LexiconParameters,
-  LexiconPayload,
-  LexiconPermissionSet,
-  LexiconProcedure,
-  LexiconQuery,
-  LexiconRecord,
-  LexiconRef,
-  LexiconRefUnion,
-  LexiconString,
-  LexiconSubscription,
-  LexiconToken,
-  LexiconUnknown,
-} from '@atproto/lex-document'
-import { l } from '@atproto/lex-schema'
-import {
-  RefResolver,
-  RefResolverOptions,
-  ResolvedRef,
-  getPublicIdentifiers,
-} from './ref-resolver.js'
-import { asNamespaceExport } from './ts-lang.js'
-
-/**
- * Configuration options for the {@link LexDefBuilder} class.
- *
- * @see {@link RefResolverOptions} for reference resolution options
- */
-export type LexDefBuilderOptions = RefResolverOptions & {
-  /**
-   * The module specifier to use for importing the lexicon schema library.
-   *
-   * @default '@atproto/lex-schema'
-   */
-  lib?: string
-}
-
-/**
- * Builds TypeScript type definitions and runtime schemas from a single
- * Lexicon document.
- *
- * This class is responsible for generating the `.defs.ts` files that contain:
- * - Type aliases for each lexicon definition
- * - Runtime schema validators using `@atproto/lex-schema`
- * - Utility functions for type checking and validation
- * - Proper import statements for cross-references
- *
- * Each lexicon definition type (record, object, query, procedure, etc.)
- * is handled with specialized code generation logic.
- */
-export class LexDefBuilder {
-  private readonly refResolver: RefResolver
-
-  constructor(
-    private readonly options: LexDefBuilderOptions,
-    private readonly file: SourceFile,
-    private readonly doc: LexiconDocument,
-    indexer: LexiconIndexer,
-  ) {
-    this.refResolver = new RefResolver(doc, file, indexer, options)
-  }
-
-  async build() {
-    this.file.addVariableStatement({
-      declarationKind: VariableDeclarationKind.Const,
-      declarations: [
-        { name: '$nsid', initializer: JSON.stringify(this.doc.id) },
-      ],
-    })
-
-    this.file.addExportDeclaration({
-      namedExports: [{ name: '$nsid' }],
-    })
-
-    const defs = Object.keys(this.doc.defs)
-    if (defs.length) {
-      const moduleSpecifier = this.options?.lib ?? '@atproto/lex-schema'
-      this.file
-        .addImportDeclaration({ moduleSpecifier })
-        .addNamedImports([{ name: 'l' }])
-
-      for (const hash of defs) {
-        await this.addDef(hash)
-      }
-    }
-  }
-
-  private addUtils(definitions: Record<string, undefined | string>) {
-    for (const [name, initializer] of Object.entries(definitions)) {
-      if (initializer == null) continue
-
-      this.file.addVariableStatement({
-        isExported: true,
-        declarationKind: VariableDeclarationKind.Const,
-        declarations: [{ name, initializer }],
-      })
-    }
-  }
-
-  private async addDef(hash: string) {
-    const def = Object.hasOwn(this.doc.defs, hash) ? this.doc.defs[hash] : null
-    if (def == null) return
-
-    switch (def.type) {
-      case 'permission-set':
-        return this.addPermissionSet(hash, def)
-      case 'procedure':
-        return this.addProcedure(hash, def)
-      case 'query':
-        return this.addQuery(hash, def)
-      case 'subscription':
-        return this.addSubscription(hash, def)
-      case 'record':
-        return this.addRecord(hash, def)
-      case 'token':
-        return this.addToken(hash, def)
-      case 'object':
-        return this.addObject(hash, def)
-      case 'array':
-        return this.addArray(hash, def)
-      default:
-        await this.addSchema(hash, def, {
-          type: await this.compileContainedType(def),
-          schema: await this.compileContainedSchema(def),
-          validationUtils: true,
-        })
-    }
-  }
-
-  private async addPermissionSet(hash: string, def: LexiconPermissionSet) {
-    const permission = def.permissions.map((def) => {
-      const options = stringifyOptions(def, undefined, ['resource', 'type'])
-      return markPure(
-        `l.permission(${JSON.stringify(def.resource)}, ${options})`,
-      )
-    })
-
-    const options = stringifyOptions(def, [
-      'title',
-      'title:lang',
-      'detail',
-      'detail:lang',
-    ] satisfies (keyof l.PermissionSetOptions)[])
-
-    await this.addSchema(hash, def, {
-      schema: markPure(
-        `l.permissionSet($nsid, [${permission.join(',')}], ${options})`,
-      ),
-    })
-  }
-
-  private async addParameters(parameters?: LexiconParameters): Promise<string> {
-    const varName = '$params'
-
-    this.addUtils({
-      [varName]: await this.compileParamsSchema(parameters),
-    })
-
-    // @TODO Build the types instead of using an inferred type.
-    this.file.addTypeAlias({
-      isExported: true,
-      name: '$Params',
-      type: `l.InferOutput<typeof ${varName}>`,
-      docs: compileDocs(parameters?.description),
-    })
-
-    return varName
-  }
-
-  private async addInput(input?: LexiconPayload): Promise<string> {
-    const varName = '$input'
-
-    this.addUtils({
-      [varName]: await this.compilePayload(input),
-    })
-
-    // @TODO Build the types instead of using an inferred type.
-    this.file.addTypeAlias({
-      isExported: true,
-      name: '$Input<B = l.BinaryData>',
-      type: `l.InferPayload<typeof ${varName}, B>`,
-      docs: compileDocs(input?.description),
-    })
-
-    this.file.addTypeAlias({
-      isExported: true,
-      name: '$InputBody<B = l.BinaryData>',
-      type: `l.InferPayloadBody<typeof ${varName}, B>`,
-      docs: compileDocs(input?.description),
-    })
-
-    return varName
-  }
-
-  private async addOutput(output?: LexiconPayload): Promise<string> {
-    const varName = '$output'
-
-    this.addUtils({
-      [varName]: await this.compilePayload(output),
-    })
-
-    // @TODO Build the types instead of using an inferred type.
-    this.file.addTypeAlias({
-      isExported: true,
-      name: '$Output<B = l.BinaryData>',
-      type: `l.InferPayload<typeof ${varName}, B>`,
-      docs: compileDocs(output?.description),
-    })
-
-    this.file.addTypeAlias({
-      isExported: true,
-      name: '$OutputBody<B = l.BinaryData>',
-      type: `l.InferPayloadBody<typeof ${varName}, B>`,
-      docs: compileDocs(output?.description),
-    })
-
-    return varName
-  }
-
-  private async addMessage(message?: LexiconMessage) {
-    const varName = '$message'
-
-    this.addUtils({
-      [varName]: await this.compileBodySchema(message?.schema),
-    })
-
-    // @TODO Build the types instead of using an inferred type.
-    this.file.addTypeAlias({
-      isExported: true,
-      name: '$Message',
-      type: `l.InferOutput<typeof ${varName}>`,
-      docs: compileDocs(message?.description),
-    })
-
-    return varName
-  }
-
-  private async addProcedure(hash: string, def: LexiconProcedure) {
-    if (hash !== 'main') {
-      throw new Error(`Definition ${hash} cannot be of type ${def.type}`)
-    }
-
-    // Declare each piece of the method as its own top-level exported const
-    // *before* `main`. This allows to export those pieces individually instead
-    // of "extracting" them from the "main" definition as below, which is bad
-    // for tree-shaking.
-    //
-    // export const $params = main.params`
-
-    const paramsVar = await this.addParameters(def.parameters)
-    const inputVar = await this.addInput(def.input)
-    const outputVar = await this.addOutput(def.output)
-
-    await this.addSchema(hash, def, {
-      schema: markPure(
-        `l.procedure($nsid, ${paramsVar}, ${inputVar}, ${outputVar}${formatErrorsArg(await this.compileErrors(def.errors))})`,
-      ),
-    })
-
-    this.addUtils({
-      $lxm: '$nsid',
-    })
-  }
-
-  private async addQuery(hash: string, def: LexiconQuery) {
-    if (hash !== 'main') {
-      throw new Error(`Definition ${hash} cannot be of type ${def.type}`)
-    }
-
-    // Declare each piece of the method as its own top-level exported const
-    // *before* `main`. This allows to export those pieces individually instead
-    // of "extracting" them from the "main" definition as below, which is bad
-    // for tree-shaking:
-    //
-    // export const $params = main.params
-
-    const paramsVar = await this.addParameters(def.parameters)
-    const outputVar = await this.addOutput(def.output)
-
-    await this.addSchema(hash, def, {
-      schema: markPure(
-        `l.query($nsid, ${paramsVar}, ${outputVar}${formatErrorsArg(await this.compileErrors(def.errors))})`,
-      ),
-    })
-
-    this.addUtils({
-      $lxm: '$nsid',
-    })
-  }
-
-  private async addSubscription(hash: string, def: LexiconSubscription) {
-    if (hash !== 'main') {
-      throw new Error(`Definition ${hash} cannot be of type ${def.type}`)
-    }
-
-    // Declare each piece of the method as its own top-level exported const
-    // *before* `main`. This allows to export those pieces individually instead
-    // of "extracting" them from the "main" definition as below, which is bad
-    // for tree-shaking.
-    //
-    // export const $params = main.params`
-
-    const paramsVar = await this.addParameters(def.parameters)
-    const messageVar = await this.addMessage(def.message)
-
-    await this.addSchema(hash, def, {
-      schema: markPure(
-        `l.subscription($nsid, ${paramsVar}, ${messageVar}${formatErrorsArg(await this.compileErrors(def.errors))})`,
-      ),
-    })
-
-    this.addUtils({
-      $lxm: '$nsid',
-    })
-  }
-
-  private async addRecord(hash: string, def: LexiconRecord) {
-    if (hash !== 'main') {
-      throw new Error(`Definition ${hash} cannot be of type ${def.type}`)
-    }
-
-    const key = JSON.stringify(def.key ?? 'any')
-    const objectSchema = await this.compileObjectSchema(def.record)
-
-    const properties = await this.compilePropertiesTypes(def.record)
-    properties.unshift(`$type: ${JSON.stringify(l.$type(this.doc.id, hash))}`)
-
-    await this.addSchema(hash, def, {
-      type: `{ ${properties.join(';')} }`,
-      schema: (ref) =>
-        markPure(
-          `l.record<${key}, ${ref.typeName}>(${key}, $nsid, ${objectSchema})`,
-        ),
-      objectUtils: true,
-      validationUtils: true,
-    })
-  }
-
-  private async addObject(hash: string, def: LexiconObject) {
-    const objectSchema = await this.compileObjectSchema(def)
-
-    const properties = await this.compilePropertiesTypes(def)
-    properties.unshift(`$type?: ${JSON.stringify(l.$type(this.doc.id, hash))}`)
-
-    await this.addSchema(hash, def, {
-      type: `{ ${properties.join(';')} }`,
-      schema: (ref) =>
-        markPure(
-          `l.typedObject<${ref.typeName}>($nsid, ${JSON.stringify(hash)}, ${objectSchema})`,
-        ),
-      objectUtils: true,
-      validationUtils: true,
-    })
-  }
-
-  private async addToken(hash: string, def: LexiconToken) {
-    await this.addSchema(hash, def, {
-      schema: markPure(`l.token($nsid, ${JSON.stringify(hash)})`),
-      type: JSON.stringify(l.$type(this.doc.id, hash)),
-      validationUtils: true,
-    })
-  }
-
-  private async addArray(hash: string, def: LexiconArray) {
-    // @TODO It could be nice to expose the array item type as a separate type.
-    // This was not done (yet) as there is no easy way to name it to avoid
-    // collisions.
-
-    const itemSchema = await this.compileContainedSchema(def.items)
-    const options = stringifyOptions(def, [
-      'minLength',
-      'maxLength',
-    ] satisfies (keyof l.ArraySchemaOptions)[])
-
-    await this.addSchema(hash, def, {
-      type: `(${await this.compileContainedType(def.items)})[]`,
-      // @NOTE Not using compileArraySchema to allow specifying the generic
-      // parameter to l.array<>.
-      schema: (ref) =>
-        markPure(`l.array<${ref.typeName}[number]>(${itemSchema}, ${options})`),
-      validationUtils: true,
-    })
-  }
-
-  private async addSchema(
-    hash: string,
-    def: { description?: string },
-    {
-      type,
-      schema,
-      objectUtils,
-      validationUtils,
-    }: {
-      type?: string | ((ref: ResolvedRef) => string)
-      schema?: string | ((ref: ResolvedRef) => string)
-      objectUtils?: boolean
-      validationUtils?: boolean
-    },
-  ): Promise<ResolvedRef> {
-    const ref = await this.refResolver.resolveLocal(hash)
-    const pub = getPublicIdentifiers(hash)
-
-    if (type) {
-      this.file.addTypeAlias({
-        name: ref.typeName,
-        type: typeof type === 'function' ? type(ref) : type,
-        docs: compileDocs(def.description),
-      })
-
-      this.file.addExportDeclaration({
-        isTypeOnly: true,
-        namedExports: [
-          {
-            name: ref.typeName,
-            alias:
-              ref.typeName === pub.typeName
-                ? undefined
-                : asNamespaceExport(pub.typeName),
-          },
-        ],
-      })
-    }
-
-    if (schema) {
-      this.file.addVariableStatement({
-        declarationKind: VariableDeclarationKind.Const,
-        declarations: [
-          {
-            name: ref.varName,
-            initializer: typeof schema === 'function' ? schema(ref) : schema,
-          },
-        ],
-        docs: compileDocs(def.description),
-      })
-
-      this.file.addExportDeclaration({
-        namedExports: [
-          {
-            name: ref.varName,
-            alias:
-              ref.varName === pub.varName
-                ? undefined
-                : asNamespaceExport(pub.varName),
-          },
-        ],
-      })
-    }
-
-    if (hash === 'main' && objectUtils) {
-      this.addUtils({
-        $type: `$nsid`,
-        $isTypeOf: markPure(`${ref.varName}.isTypeOf.bind(${ref.varName})`),
-        $build: markPure(`${ref.varName}.build.bind(${ref.varName})`),
-      })
-    }
-
-    if (hash === 'main' && validationUtils) {
-      this.addUtils({
-        $assert: markPure(`${ref.varName}.assert.bind(${ref.varName})`),
-        $check: markPure(`${ref.varName}.check.bind(${ref.varName})`),
-        $cast: markPure(`${ref.varName}.cast.bind(${ref.varName})`),
-        $ifMatches: markPure(`${ref.varName}.ifMatches.bind(${ref.varName})`),
-        $matches: markPure(`${ref.varName}.matches.bind(${ref.varName})`),
-        $parse: markPure(`${ref.varName}.parse.bind(${ref.varName})`),
-        $safeParse: markPure(`${ref.varName}.safeParse.bind(${ref.varName})`),
-        $validate: markPure(`${ref.varName}.validate.bind(${ref.varName})`),
-        $safeValidate: markPure(
-          `${ref.varName}.safeValidate.bind(${ref.varName})`,
-        ),
-      })
-    }
-
-    return ref
-  }
-
-  private async compilePayload(def: LexiconPayload | undefined) {
-    if (!def) return markPure(`l.payload()`)
-
-    // Special case for JSON object payloads
-    if (def.encoding === 'application/json' && def.schema?.type === 'object') {
-      const properties = await this.compilePropertiesSchemas(def.schema)
-      return markPure(`l.jsonPayload({${properties.join(',')}})`)
-    }
-
-    const encodedEncoding = JSON.stringify(def.encoding)
-    if (def.schema) {
-      const bodySchema = await this.compileBodySchema(def.schema)
-      return markPure(`l.payload(${encodedEncoding}, ${bodySchema})`)
-    } else {
-      return markPure(`l.payload(${encodedEncoding})`)
-    }
-  }
-
-  private async compileBodySchema(
-    def?: LexiconRef | LexiconRefUnion | LexiconObject,
-  ): Promise<string> {
-    if (!def) return 'undefined'
-    if (def.type === 'object') return this.compileObjectSchema(def)
-    return this.compileContainedSchema(def)
-  }
-
-  private async compileParamsSchema(def: undefined | LexiconParameters) {
-    if (!def) return markPure(`l.params()`)
-
-    const properties = await this.compilePropertiesSchemas(def)
-    return markPure(
-      properties.length === 0
-        ? `l.params()`
-        : `l.params({${properties.join(',')}})`,
-    )
-  }
-
-  private async compileErrors(defs?: readonly LexiconError[]) {
-    if (!defs?.length) return ''
-    return JSON.stringify(defs.map((d) => d.name))
-  }
-
-  private async compileObjectSchema(def: LexiconObject): Promise<string> {
-    const properties = await this.compilePropertiesSchemas(def)
-    return markPure(`l.object({${properties.join(',')}})`)
-  }
-
-  private async compilePropertiesSchemas(options: {
-    properties: Record<string, LexiconArray | LexiconArrayItems>
-    required?: readonly string[]
-    nullable?: readonly string[]
-  }): Promise<string[]> {
-    for (const opt of ['required', 'nullable'] as const) {
-      if (options[opt]) {
-        for (const prop of options[opt]) {
-          if (!Object.hasOwn(options.properties, prop)) {
-            throw new Error(`No schema found for ${opt} property "${prop}"`)
-          }
-        }
-      }
-    }
-
-    return Promise.all(
-      Object.entries(options.properties).map((entry) => {
-        return this.compilePropertyEntrySchema(entry, options)
-      }),
-    )
-  }
-
-  private async compilePropertiesTypes(options: {
-    properties: Record<string, LexiconArray | LexiconArrayItems>
-    required?: readonly string[]
-    nullable?: readonly string[]
-  }) {
-    return Promise.all(
-      Object.entries(options.properties).map((entry) => {
-        return this.compilePropertyEntryType(entry, options)
-      }),
-    )
-  }
-
-  private async compilePropertyEntrySchema(
-    [key, def]: [string, LexiconArray | LexiconArrayItems],
-    options: {
-      required?: readonly string[]
-      nullable?: readonly string[]
-    },
-  ) {
-    const isNullable = options.nullable?.includes(key)
-    const isRequired = options.required?.includes(key)
-
-    let schema = await this.compileContainedSchema(def)
-
-    if (isNullable) {
-      schema = markPure(`l.nullable(${schema})`)
-    }
-
-    if (!isRequired) {
-      schema = markPure(`l.optional(${schema})`)
-    }
-
-    return `${JSON.stringify(key)}:${schema}`
-  }
-
-  private async compilePropertyEntryType(
-    [key, def]: [string, LexiconArray | LexiconArrayItems],
-    options: {
-      required?: readonly string[]
-      nullable?: readonly string[]
-    },
-  ) {
-    const isNullable = options.nullable?.includes(key)
-    const isRequired = options.required?.includes(key)
-
-    const optional = isRequired ? '' : '?'
-    const append = isNullable ? ' | null' : ''
-
-    const jsDoc = compileLeadingTrivia(def.description) || ''
-    const name = JSON.stringify(key)
-    const type = await this.compileContainedType(def)
-
-    return `${jsDoc}${name}${optional}:${type}${append}`
-  }
-
-  private async compileContainedSchema(
-    def: LexiconArray | LexiconArrayItems,
-  ): Promise<string> {
-    switch (def.type) {
-      case 'unknown':
-        return this.compileUnknownSchema(def)
-      case 'boolean':
-        return this.compileBooleanSchema(def)
-      case 'integer':
-        return this.compileIntegerSchema(def)
-      case 'string':
-        return this.compileStringSchema(def)
-      case 'bytes':
-        return this.compileBytesSchema(def)
-      case 'blob':
-        return this.compileBlobSchema(def)
-      case 'cid-link':
-        return this.compileCidLinkSchema(def)
-      case 'ref':
-        return this.compileRefSchema(def)
-      case 'union':
-        return this.compileRefUnionSchema(def)
-      case 'array':
-        return this.compileArraySchema(def)
-      default:
-        // @ts-expect-error
-        throw new Error(`Unsupported def type: ${def.type}`)
-    }
-  }
-
-  private async compileContainedType(
-    def: LexiconArray | LexiconArrayItems,
-  ): Promise<string> {
-    switch (def.type) {
-      case 'unknown':
-        return this.compileUnknownType(def)
-      case 'boolean':
-        return this.compileBooleanType(def)
-      case 'integer':
-        return this.compileIntegerType(def)
-      case 'string':
-        return this.compileStringType(def)
-      case 'bytes':
-        return this.compileBytesType(def)
-      case 'blob':
-        return this.compileBlobType(def)
-      case 'cid-link':
-        return this.compileCidLinkType(def)
-      case 'ref':
-        return this.compileRefType(def)
-      case 'union':
-        return this.compileRefUnionType(def)
-      case 'array':
-        return this.compileArrayType(def)
-      default:
-        // @ts-expect-error
-        throw new Error(`Unsupported def type: ${def.type}`)
-    }
-  }
-
-  private async compileArraySchema(def: LexiconArray): Promise<string> {
-    const itemSchema = await this.compileContainedSchema(def.items)
-    const options = stringifyOptions(def, [
-      'minLength',
-      'maxLength',
-    ] satisfies (keyof l.ArraySchemaOptions)[])
-    return markPure(`l.array(${itemSchema}, ${options})`)
-  }
-
-  private async compileArrayType(def: LexiconArray): Promise<string> {
-    return `(${await this.compileContainedType(def.items)})[]`
-  }
-
-  private async compileUnknownSchema(_def: LexiconUnknown): Promise<string> {
-    return markPure(`l.lexMap()`)
-  }
-
-  private async compileUnknownType(_def: LexiconUnknown): Promise<string> {
-    return `l.LexMap`
-  }
-
-  private withDefault(schema: string, defaultValue: unknown) {
-    if (defaultValue === undefined) return schema
-
-    return markPure(`l.withDefault(${schema}, ${JSON.stringify(defaultValue)})`)
-  }
-
-  private async compileBooleanSchema(def: LexiconBoolean): Promise<string> {
-    const schema = l.boolean()
-
-    if (def.default !== undefined) {
-      schema.check(def.default)
-    }
-
-    if (hasConst(def)) return this.compileConstSchema(def)
-
-    return this.withDefault(markPure(`l.boolean()`), def.default)
-  }
-
-  private async compileBooleanType(def: LexiconBoolean): Promise<string> {
-    if (hasConst(def)) return this.compileConstType(def)
-    return 'boolean'
-  }
-
-  private async compileIntegerSchema(def: LexiconInteger): Promise<string> {
-    const schema = l.integer(def)
-
-    if (hasConst(def)) {
-      schema.check(def.const)
-    }
-
-    if (hasEnum(def)) {
-      for (const val of def.enum) schema.check(val)
-    }
-
-    if (def.default !== undefined) {
-      schema.check(def.default)
-    }
-
-    if (hasConst(def)) return this.compileConstSchema(def)
-    if (hasEnum(def)) return this.compileEnumSchema(def)
-
-    const options = stringifyOptions(def, [
-      'maximum',
-      'minimum',
-    ] satisfies (keyof l.IntegerSchemaOptions)[])
-
-    return this.withDefault(markPure(`l.integer(${options})`), def.default)
-  }
-
-  private async compileIntegerType(def: LexiconInteger): Promise<string> {
-    if (hasConst(def)) return this.compileConstType(def)
-    if (hasEnum(def)) return this.compileEnumType(def)
-
-    return 'number'
-  }
-
-  private async compileStringSchema(def: LexiconString): Promise<string> {
-    const schema = l.string(def)
-
-    if (hasConst(def)) {
-      schema.check(def.const)
-    }
-
-    if (hasEnum(def)) {
-      for (const val of def.enum) schema.check(val)
-    }
-
-    if (def.default !== undefined) {
-      schema.check(def.default)
-    }
-
-    if (hasConst(def)) return this.compileConstSchema(def)
-    if (hasEnum(def)) return this.compileEnumSchema(def)
-
-    const runtimeOptions = [
-      'format',
-      'maxGraphemes',
-      'minGraphemes',
-      'maxLength',
-      'minLength',
-      // We don't want to include knownValues in the schema options **at
-      // runtime** as it has no effect and only causes bloat:
-      // "knownValues",
-    ] as const satisfies (keyof l.StringSchemaOptions)[]
-
-    const options = stringifyOptions(def, runtimeOptions)
-
-    // We *do* however need knownValues for the inferred type, so we include it
-    // as the generic parameter. We only do this if the def has knownValues,
-    // otherwise we let TypeScript infer the options generic by not defining it.
-    const generic = def.knownValues
-      ? stringifyOptions(def, [
-          ...runtimeOptions,
-          'knownValues',
-        ] satisfies (keyof l.StringSchemaOptions)[])
-      : undefined
-
-    return this.withDefault(
-      markPure(`l.string${generic ? `<${generic}>` : ''}(${options})`),
-      def.default,
-    )
-  }
-
-  private async compileStringType(def: LexiconString): Promise<string> {
-    if (hasConst(def)) return this.compileConstType(def)
-    if (hasEnum(def)) return this.compileEnumType(def)
-
-    switch (def.format) {
-      case undefined:
-        break
-      case 'datetime':
-        return 'l.DatetimeString'
-      case 'uri':
-        return 'l.UriString'
-      case 'at-uri':
-        return 'l.AtUriString'
-      case 'did':
-        return 'l.DidString'
-      case 'handle':
-        return 'l.HandleString'
-      case 'at-identifier':
-        return 'l.AtIdentifierString'
-      case 'nsid':
-        return 'l.NsidString'
-      case 'tid':
-        return 'l.TidString'
-      case 'cid':
-        return 'l.CidString'
-      case 'language':
-        return 'l.LanguageString'
-      case 'record-key':
-        return 'l.RecordKeyString'
-      default:
-        throw new Error(`Unknown string format: ${def.format}`)
-    }
-
-    if (def.knownValues?.length) {
-      return (
-        def.knownValues.map((v) => JSON.stringify(v)).join(' | ') +
-        ' | l.UnknownString'
-      )
-    }
-
-    return 'string'
-  }
-
-  private async compileBytesSchema(def: LexiconBytes): Promise<string> {
-    const options = stringifyOptions(def, [
-      'minLength',
-      'maxLength',
-    ] satisfies (keyof l.BytesSchemaOptions)[])
-    return markPure(`l.bytes(${options})`)
-  }
-
-  private async compileBytesType(_def: LexiconBytes): Promise<string> {
-    return 'Uint8Array'
-  }
-
-  private async compileBlobSchema(def: LexiconBlob): Promise<string> {
-    const options = stringifyOptions(def, [
-      'maxSize',
-      'accept',
-    ] satisfies (keyof l.BlobSchemaOptions)[])
-    return markPure(`l.blob(${options})`)
-  }
-
-  private async compileBlobType(_def: LexiconBlob): Promise<string> {
-    return 'l.BlobRef'
-  }
-
-  private async compileCidLinkSchema(_def: LexiconCid): Promise<string> {
-    return markPure(`l.cid()`)
-  }
-
-  private async compileCidLinkType(_def: LexiconCid): Promise<string> {
-    return 'l.Cid'
-  }
-
-  private async compileRefSchema(def: LexiconRef): Promise<string> {
-    const { varName, typeName } = await this.refResolver.resolve(def.ref)
-    // @NOTE "as any" is needed in schemas with circular refs as TypeScript
-    // cannot infer the type of a value that depends on its initializer type
-    return markPure(`l.ref<${typeName}>((() => ${varName}) as any)`)
-  }
-
-  private async compileRefType(def: LexiconRef): Promise<string> {
-    const ref = await this.refResolver.resolve(def.ref)
-    return ref.typeName
-  }
-
-  private async compileRefUnionSchema(def: LexiconRefUnion): Promise<string> {
-    if (def.refs.length === 0 && def.closed) {
-      return markPure(`l.never()`)
-    }
-
-    const refs = await Promise.all(
-      def.refs.map(async (ref: string) => {
-        const { varName, typeName } = await this.refResolver.resolve(ref)
-        // @NOTE "as any" is needed in schemas with circular refs as TypeScript
-        // cannot infer the type of a value that depends on its initializer type
-        return markPure(`l.typedRef<${typeName}>((() => ${varName}) as any)`)
-      }),
-    )
-
-    return markPure(`l.typedUnion([${refs.join(',')}], ${def.closed ?? false})`)
-  }
-
-  private async compileRefUnionType(def: LexiconRefUnion): Promise<string> {
-    const types = await Promise.all(
-      def.refs.map(async (ref) => {
-        const { typeName } = await this.refResolver.resolve(ref)
-        return `l.$Typed<${typeName}>`
-      }),
-    )
-    if (!def.closed) types.push('l.Unknown$TypedObject')
-    return types.join(' | ') || 'never'
-  }
-
-  private async compileConstSchema<
-    T extends null | number | string | boolean,
-  >(def: { const: T; enum?: readonly T[]; default?: T }): Promise<string> {
-    if (hasEnum(def) && !def.enum.includes(def.const)) {
-      return markPure(`l.never()`)
-    }
-
-    const result = markPure(`l.literal(${JSON.stringify(def.const)})`)
-
-    return this.withDefault(result, def.default)
-  }
-
-  private async compileConstType<
-    T extends null | number | string | boolean,
-  >(def: { const: T; enum?: readonly T[] }): Promise<string> {
-    if (hasEnum(def) && !def.enum.includes(def.const)) {
-      return 'never'
-    }
-    return JSON.stringify(def.const)
-  }
-
-  private async compileEnumSchema<T extends null | number | string>(def: {
-    enum: readonly T[]
-    default?: T
-  }): Promise<string> {
-    if (def.enum.length === 0) {
-      return markPure(`l.never()`)
-    }
-
-    const result =
-      def.enum.length === 1
-        ? markPure(`l.literal(${JSON.stringify(def.enum[0])})`)
-        : markPure(`l.enum(${JSON.stringify(def.enum)})`)
-
-    return this.withDefault(result, def.default)
-  }
-
-  private async compileEnumType<T extends null | number | string>(def: {
-    enum: readonly T[]
-  }): Promise<string> {
-    return def.enum.map((v) => JSON.stringify(v)).join(' | ') || 'never'
-  }
-}
-
-type ParsedDescription = OptionalKind<JSDocStructure> & {
-  description?: string
-  tags?: { tagName: string; text?: string }[]
-}
-
-function parseDescription(description: string): ParsedDescription {
-  if (/deprecated/i.test(description)) {
-    const deprecationMatch = description.match(
-      /(\s*deprecated\s*(?:--?|:)?\s*([^-]*)(?:-+)?)/i,
-    )
-    if (deprecationMatch) {
-      const { 1: match, 2: deprecationNotice } = deprecationMatch
-      return {
-        description: description.replace(match, '').trim() || undefined,
-        tags: [{ tagName: 'deprecated', text: deprecationNotice?.trim() }],
-      }
-    } else {
-      return {
-        description: description.trim() || undefined,
-        tags: [{ tagName: 'deprecated' }],
-      }
-    }
-  }
-
-  return {
-    description: description.trim() || undefined,
-  }
-}
-
-function compileLeadingTrivia(description?: string) {
-  if (!description) return undefined
-  const parsed = parseDescription(description)
-  if (!parsed.description && !parsed.tags?.length) return undefined
-  const tags = parsed.tags
-    ?.map(({ tagName, text }) => (text ? `@${tagName} ${text}` : `@${tagName}`))
-    ?.join('\n')
-  const text = `\n${[parsed.description, tags].filter(Boolean).join('\n\n')}`
-  return `\n\n/**${text.replaceAll('\n', '\n * ')}\n */\n`
-}
-
-function compileDocs(description?: string) {
-  if (!description) return undefined
-  return [parseDescription(description)]
-}
-
-function stringifyOptions<O extends Record<string, unknown>>(
-  obj: O,
-  include?: (keyof O)[],
-  exclude?: (keyof O)[],
-) {
-  const filtered = Object.entries(obj).filter(
-    ([k]) => (!include || include.includes(k)) && !exclude?.includes(k),
-  )
-  return filtered.length ? JSON.stringify(Object.fromEntries(filtered)) : ''
-}
-
-function hasConst<T extends { const?: unknown }>(
-  def: T,
-): def is T & { const: NonNullable<T['const']> } {
-  return def.const != null
-}
-
-function hasEnum<T extends { enum?: readonly unknown[] }>(
-  def: T,
-): def is T & { enum: unknown[] } {
-  return def.enum != null
-}
-
-function markPure<T extends string>(v: T): `/*#__PURE__*/ ${T}` {
-  return `/*#__PURE__*/ ${v}`
-}
-
-function formatErrorsArg(errors: string) {
-  return errors ? `, ${errors}` : ''
-}