@atproto/lex-document 0.0.12 → 0.0.13

package/src/lexicon-indexer.ts

@@ -1,8 +1,60 @@
 import { LexiconDocument } from './lexicon-document.js'
 
+/**
+ * Interface for indexing and retrieving Lexicon documents by their NSID.
+ *
+ * @example
+ * ```ts
+ * // Using a custom indexer implementation
+ * const networkIndexer: LexiconIndexer = {
+ *   async get(nsid: string) {
+ *     const doc = await resolveLexicon(nsid)
+ *     return doc
+ *   }
+ * }
+ *
+ * const validator = await LexiconSchemaBuilder.build(networkIndexer, 'com.example.post#main')
+ * ```
+ */
 export interface LexiconIndexer {
+  /**
+   * Retrieves a Lexicon document by its NSID.
+   *
+   * @param nsid - The Namespaced Identifier of the Lexicon document to retrieve
+   * @returns A promise that resolves to the Lexicon document
+   * @throws When the document with the given NSID cannot be found
+   *
+   * @example
+   * ```ts
+   * const doc = await indexer.get('com.atproto.repo.createRecord')
+   * console.log(doc.defs.main?.type) // 'procedure'
+   * ```
+   */
   get(nsid: string): Promise<LexiconDocument>
 
+  /**
+   * Optional async disposal method for cleanup.
+   *
+   * When implemented, allows the indexer to be used with `await using`
+   * syntax for automatic resource cleanup.
+   *
+   * @returns A promise that resolves when disposal is complete
+   */
   [Symbol.asyncDispose]?: () => Promise<void>
+
+  /**
+   * Optional async iterator for iterating over all available Lexicon documents.
+   *
+   * @returns An async iterator yielding Lexicon documents
+   *
+   * @example
+   * ```ts
+   * if (Symbol.asyncIterator in indexer) {
+   *   for await (const doc of indexer) {
+   *     console.log(doc.id)
+   *   }
+   * }
+   * ```
+   */
   [Symbol.asyncIterator]?: () => AsyncIterator<LexiconDocument, void, unknown>
 }

package/src/lexicon-iterable-indexer.ts

@@ -2,7 +2,34 @@ import { LexiconDocument } from './lexicon-document.js'
 import { LexiconIndexer } from './lexicon-indexer.js'
 
 /**
- * (Lazily) indexes lexicon documents from an iterable source.
+ * Lazily indexes Lexicon documents from an iterable source.
+ *
+ * This class implements `LexiconIndexer` by consuming documents from an
+ * iterable (sync or async) and caching them for efficient retrieval.
+ * Documents are indexed on-demand as they are requested or iterated over.
+ *
+ * @example
+ * ```ts
+ * // From an array of documents
+ * const docs = [lexiconDoc1, lexiconDoc2, lexiconDoc3]
+ * const indexer = new LexiconIterableIndexer(docs)
+ *
+ * // Documents are indexed lazily as requested
+ * const doc = await indexer.get('com.example.post')
+ * ```
+ *
+ * @example
+ * ```ts
+ * // From an async generator (e.g., reading from files)
+ * async function* loadLexicons() {
+ *   for (const file of lexiconFiles) {
+ *     yield JSON.parse(await fs.readFile(file, 'utf8'))
+ *   }
+ * }
+ *
+ * await using indexer = new LexiconIterableIndexer(loadLexicons())
+ * const schemas = await LexiconSchemaBuilder.buildAll(indexer)
+ * ```
  */
 export class LexiconIterableIndexer implements LexiconIndexer, AsyncDisposable {
   readonly #lexicons: Map<string, LexiconDocument> = new Map()
@@ -10,6 +37,21 @@ export class LexiconIterableIndexer implements LexiconIndexer, AsyncDisposable {
     | AsyncIterator<LexiconDocument, void, unknown>
     | Iterator<LexiconDocument, void, unknown>
 
+  /**
+   * Creates a new {@link LexiconIterableIndexer} from an iterable source.
+   *
+   * @param source - An iterable or async iterable of Lexicon documents.
+   *   The iterator is consumed lazily as documents are requested.
+   *
+   * @example
+   * ```ts
+   * // Sync iterable (array, Set, Map.values(), etc.)
+   * const indexer = new LexiconIterableIndexer(lexiconDocuments)
+   *
+   * // Async iterable (async generator, ReadableStream, etc.)
+   * const indexer = new LexiconIterableIndexer(asyncLexiconStream)
+   * ```
+   */
   constructor(
     readonly source: AsyncIterable<LexiconDocument> | Iterable<LexiconDocument>,
   ) {
@@ -19,6 +61,14 @@ export class LexiconIterableIndexer implements LexiconIndexer, AsyncDisposable {
         : source[Symbol.iterator]()
   }
 
+  /**
+   * Retrieves a Lexicon document by its NSID.
+   *
+   * If the document has already been indexed, it is returned from cache.
+   * Otherwise, the source iterator is consumed until the document is found.
+   *
+   * @see {@link LexiconIndexer.get}
+   */
   async get(id: string): Promise<LexiconDocument> {
     const cached = this.#lexicons.get(id)
     if (cached) return cached

package/src/lexicon-schema-builder.ts

@@ -1,4 +1,11 @@
-import { l } from '@atproto/lex-schema'
+import {
+  ArraySchema,
+  BooleanSchema,
+  IntegerSchema,
+  StringSchema,
+  l,
+} from '@atproto/lex-schema'
+import { LexValue } from '../../lex-data/dist/lex.js'
 import {
   LexiconArray,
   LexiconArrayItems,
@@ -13,23 +20,63 @@ import {
 import { LexiconIndexer } from './lexicon-indexer.js'
 
 /**
- * Builds a validator for a given lexicon "ref" from a lexicon indexer.
+ * Builds validators for Lexicon documents.
+ *
+ * This class converts Lexicon type definitions into runtime validators
+ * that can validate data against the schema. It handles reference resolution,
+ * supporting both local (`#defName`) and cross-document (`nsid#defName`) refs.
  *
  * @example
+ * ```ts
+ * import { LexiconSchemaBuilder, LexiconIterableIndexer } from '@atproto/lex-document'
+ *
+ * // Build a single validator
+ * const indexer = new LexiconIterableIndexer(lexiconDocs)
+ * const validator = await LexiconSchemaBuilder.build(indexer, 'com.example.post#main')
+ *
+ * // Validate data
+ * const result = validator.safeParse(myPostData)
+ * if (result.success) {
+ *   console.log('Valid:', result.value)
+ * } else {
+ *   console.log('Invalid:', result.error)
+ * }
+ * ```
  *
+ * @example
  * ```ts
- * import { LexiconSchemaBuilder } from '@atproto/lex/doc'
- * import { LexiconStreamIndexer } from '@atproto/lex/doc'
+ * // Build all validators from an iterable indexer
+ * const indexer = new LexiconIterableIndexer(lexiconDocs)
+ * const allSchemas = await LexiconSchemaBuilder.buildAll(indexer)
  *
- * const indexer = new LexiconStreamIndexer(lexiconDocs)
- * const validator = await LexiconSchemaBuilder.build(indexer, 'com.example.foo#bar')
+ * for (const [ref, schema] of allSchemas) {
+ *   console.log(`Built validator for ${ref}`)
+ * }
  * ```
  */
 export class LexiconSchemaBuilder {
+  /**
+   * Builds a validator for a single Lexicon definition reference.
+   *
+   * @param indexer - The Lexicon indexer to resolve documents from
+   * @param fullRef - The full reference to build, in format "nsid#defName"
+   * @returns A promise resolving to a validator for the referenced definition
+   * @throws Error if the reference does not point to a schema type
+   *
+   * @example
+   * ```ts
+   * const validator = await LexiconSchemaBuilder.build(
+   *   indexer,
+   *   'app.bsky.feed.post#main'
+   * )
+   *
+   * validator.parse(postRecord) // Throws if invalid
+   * ```
+   */
   static async build(
     indexer: LexiconIndexer,
     fullRef: string,
-  ): Promise<l.Validator<unknown>> {
+  ): Promise<l.Schema<LexValue>> {
     const ctx = new LexiconSchemaBuilder(indexer)
     try {
       const result = await ctx.buildFullRef(fullRef)
@@ -42,11 +89,36 @@ export class LexiconSchemaBuilder {
     }
   }
 
+  /**
+   * Builds validators for all definitions in all documents from an iterable indexer.
+   *
+   * This method iterates over all Lexicon documents available in the indexer
+   * and builds validators for every definition in each document.
+   *
+   * @param indexer - An iterable Lexicon indexer (must implement `Symbol.asyncIterator`)
+   * @returns A promise resolving to a Map of full references to their validators.
+   *   The map values can be validators, Query, Subscription, Procedure, or PermissionSet.
+   * @throws Error if the indexer does not support iteration
+   *
+   * @example
+   * ```ts
+   * const indexer = new LexiconIterableIndexer(allLexiconDocs)
+   * const schemas = await LexiconSchemaBuilder.buildAll(indexer)
+   *
+   * // Access a specific schema
+   * const postSchema = schemas.get('app.bsky.feed.post#main')
+   *
+   * // Iterate all schemas
+   * for (const [ref, schema] of schemas) {
+   *   console.log(ref, schema)
+   * }
+   * ```
+   */
   static async buildAll(indexer: LexiconIndexer) {
     const builder = new LexiconSchemaBuilder(indexer)
     const schemas = new Map<
       string,
-      | l.Validator<unknown>
+      | l.Schema<LexValue>
       | l.Query
       | l.Subscription
       | l.Procedure
@@ -71,12 +143,39 @@ export class LexiconSchemaBuilder {
 
   #asyncTasks = new AsyncTasks()
 
+  /**
+   * Creates a new LexiconSchemaBuilder instance.
+   *
+   * Note: For most use cases, prefer using the static `build()` or `buildAll()`
+   * methods instead of instantiating directly.
+   *
+   * @param indexer - The Lexicon indexer to resolve documents from
+   */
   constructor(protected indexer: LexiconIndexer) {}
 
+  /**
+   * Waits for all pending reference resolution tasks to complete.
+   *
+   * When building schemas with cross-references, the builder schedules
+   * async tasks to resolve those references. This method must be called
+   * to ensure all references are fully resolved before using the validators.
+   *
+   * @returns A promise that resolves when all pending tasks are complete
+   * @throws Rethrows any errors from failed reference resolution
+   */
   async done(): Promise<void> {
     await this.#asyncTasks.done()
   }
 
+  /**
+   * Builds a validator for a full reference (memoized).
+   *
+   * Results are cached, so calling with the same reference returns
+   * the same promise/result.
+   *
+   * @param fullRef - The full reference in format "nsid#defName"
+   * @returns A promise resolving to the built schema or method definition
+   */
   buildFullRef = memoize(async (fullRef: string) => {
     const { nsid, hash } = parseRef(fullRef)
 
@@ -85,20 +184,20 @@ export class LexiconSchemaBuilder {
     return this.compileDef(doc, hash)
   })
 
-  protected buildRefGetter(fullRef: string): () => l.Validator<unknown> {
-    let validator: l.Validator<unknown>
+  protected buildRefGetter(fullRef: string): () => l.Schema<LexValue> {
+    let schema: l.Schema<LexValue>
 
     this.#asyncTasks.add(
       this.buildFullRef(fullRef).then((v) => {
         if (!(v instanceof l.Schema)) {
           throw new Error(`Only refs to schema types are allowed`)
         }
-        validator = v
+        schema = v
       }),
     )
 
     return () => {
-      if (validator) return validator
+      if (schema) return schema
       throw new Error('Validator not yet built. Did you await done()?')
     }
   }
@@ -178,7 +277,7 @@ export class LexiconSchemaBuilder {
   protected compileLeaf(
     doc: LexiconDocument,
     def: LexiconArray | LexiconArrayItems,
-  ): l.Validator<unknown> {
+  ): l.Schema<LexValue> {
     if (
       'const' in def &&
       'enum' in def &&
@@ -232,7 +331,7 @@ export class LexiconSchemaBuilder {
       case 'bytes':
         return l.bytes(def)
       case 'unknown':
-        return l.unknown()
+        return l.unknownObject()
       case 'array':
         return l.array(this.compileLeaf(doc, def.items), def)
       default:
@@ -243,7 +342,7 @@ export class LexiconSchemaBuilder {
   protected compileRef(
     doc: LexiconDocument,
     def: LexiconRef | LexiconRefUnion,
-  ) {
+  ): l.Schema<LexValue> {
     switch (def.type) {
       case 'ref':
         return l.ref(this.buildRefGetter(buildFullRef(doc, def.ref)))
@@ -260,18 +359,18 @@ export class LexiconSchemaBuilder {
     }
   }
 
-  protected compileObject(
-    doc: LexiconDocument,
-    def: LexiconObject,
-  ): l.ObjectSchema {
-    const props: Record<string, l.Validator> = {}
+  protected compileObject(doc: LexiconDocument, def: LexiconObject) {
+    const props: Record<string, l.Schema<undefined | LexValue>> = {}
     for (const [key, propDef] of Object.entries(def.properties)) {
       if (propDef === undefined) continue
 
       const isNullable = def.nullable?.includes(key)
       const isRequired = def.required?.includes(key)
 
-      let schema = this.compileLeaf(doc, propDef)
+      let schema: l.Schema<undefined | LexValue> = this.compileLeaf(
+        doc,
+        propDef,
+      )
 
       if (isNullable) {
         schema = l.nullable(schema)
@@ -289,7 +388,7 @@ export class LexiconSchemaBuilder {
   protected compilePayload(
     doc: LexiconDocument,
     def: LexiconPayload | undefined,
-  ): l.Payload {
+  ) {
     return l.payload(
       def?.encoding,
       def?.schema ? this.compilePayloadSchema(doc, def.schema) : undefined,
@@ -306,7 +405,7 @@ export class LexiconSchemaBuilder {
   protected compilePayloadSchema(
     doc: LexiconDocument,
     def: LexiconObject | LexiconRef | LexiconRefUnion,
-  ) {
+  ): l.Schema<LexValue, LexValue> {
     switch (def.type) {
       case 'object':
         return this.compileObject(doc, def)
@@ -324,7 +423,11 @@ export class LexiconSchemaBuilder {
 
       const isRequired = def.required?.includes(paramName)
 
-      const propSchema = this.compileLeaf(doc, paramDef) as l.Validator<l.Param>
+      const propSchema = this.compileLeaf(doc, paramDef) as
+        | StringSchema
+        | BooleanSchema
+        | IntegerSchema
+        | ArraySchema<StringSchema | BooleanSchema | IntegerSchema>
 
       shape[paramName] = isRequired ? propSchema : l.optional(propSchema)
     }