@atproto/lex-document 0.1.1 → 0.1.3

package/src/lexicon-indexer.ts

@@ -1,60 +0,0 @@
-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

@@ -1,132 +0,0 @@
-import { LexiconDocument } from './lexicon-document.js'
-import { LexiconIndexer } from './lexicon-indexer.js'
-
-/**
- * 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()
-  readonly #iterator:
-    | 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>,
-  ) {
-    this.#iterator =
-      Symbol.asyncIterator in source
-        ? source[Symbol.asyncIterator]()
-        : 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
-
-    for await (const doc of this) {
-      if (doc.id === id) return doc
-    }
-
-    throw Object.assign(new Error(`Lexicon ${id} not found`), {
-      code: 'ENOENT',
-    })
-  }
-
-  async *[Symbol.asyncIterator](): AsyncIterator<
-    LexiconDocument,
-    void,
-    undefined
-  > {
-    const returned = new Set<string>()
-
-    for (const doc of this.#lexicons.values()) {
-      returned.add(doc.id)
-      yield doc
-    }
-
-    do {
-      const { value, done } = await this.#iterator.next()
-
-      if (done) break
-
-      if (returned.has(value.id)) {
-        const err = new Error(`Duplicate lexicon document id: ${value.id}`)
-        await this.#iterator.throw?.(err)
-        throw err // In case iterator.throw does not exist or does not throw
-      }
-
-      this.#lexicons.set(value.id, value)
-      returned.add(value.id)
-      yield value
-    } while (true)
-
-    // At this point, the underlying iterator is done. However, there may have
-    // been requests (.get()) for documents that caused the iterator to yield
-    // those documents during concurrent execution of this loop. If that was the
-    // case, new documents may have been added to `#lexicons` that have not yet
-    // been yielded. We need to yield those as well. Since we yield control back
-    // to the caller, we need to repeat this process until no new documents
-    // appear sunce we don't know what happens.
-
-    for (const doc of this.#lexicons.values()) {
-      if (!returned.has(doc.id)) {
-        returned.add(doc.id)
-        yield doc
-      }
-    }
-  }
-
-  async [Symbol.asyncDispose](): Promise<void> {
-    await this.#iterator.return?.()
-  }
-}

package/src/lexicon-schema-builder.test.ts

@@ -1,297 +0,0 @@
-import { beforeAll, describe, expect, it } from 'vitest'
-import { parseCid } from '@atproto/lex-data'
-import { l } from '@atproto/lex-schema'
-import { LexiconDocument, lexiconDocumentSchema } from './lexicon-document.js'
-import { LexiconIterableIndexer } from './lexicon-iterable-indexer.js'
-import { LexiconSchemaBuilder } from './lexicon-schema-builder.js'
-
-describe('LexiconSchemaBuilder', () => {
-  let schemas: Map<
-    string,
-    | l.Validator<unknown>
-    | l.Query
-    | l.Subscription
-    | l.Procedure
-    | l.PermissionSet
-  >
-
-  const getSchema = <T extends abstract new (...args: any) => any>(
-    ref: string,
-    type: T,
-  ) => {
-    const schema = schemas.get(ref)
-    expect(schema).toBeDefined()
-    expect(schema).toBeInstanceOf(type)
-    return schema as InstanceType<T>
-  }
-
-  beforeAll(async () => {
-    const indexer = new LexiconIterableIndexer([
-      lexiconDocumentSchema.parse({
-        lexicon: 1,
-        id: 'com.example.kitchenSink',
-        defs: {
-          main: {
-            type: 'record',
-            description: 'A record',
-            key: 'tid',
-            record: {
-              type: 'object',
-              required: [
-                'object',
-                'array',
-                'boolean',
-                'integer',
-                'string',
-                'bytes',
-                'cidLink',
-              ],
-              properties: {
-                object: { type: 'ref', ref: '#object' },
-                array: { type: 'array', items: { type: 'string' } },
-                boolean: { type: 'boolean' },
-                integer: { type: 'integer' },
-                string: { type: 'string' },
-                bytes: { type: 'bytes' },
-                cidLink: { type: 'cid-link' },
-              },
-            },
-          },
-          object: {
-            type: 'object',
-            required: ['object', 'array', 'boolean', 'integer', 'string'],
-            properties: {
-              object: { type: 'ref', ref: '#subObject' },
-              array: { type: 'array', items: { type: 'string' } },
-              boolean: { type: 'boolean' },
-              integer: { type: 'integer' },
-              string: { type: 'string' },
-              refToEnumWithDefault: { type: 'ref', ref: '#enumWithDefault' },
-            },
-          },
-          subObject: {
-            type: 'object',
-            required: ['boolean'],
-            properties: {
-              boolean: { type: 'boolean' },
-            },
-          },
-          enumWithDefault: {
-            type: 'string',
-            default: 'option3',
-            enum: ['option1', 'option2', 'option3'],
-          },
-        },
-      }),
-    ])
-    schemas = await LexiconSchemaBuilder.buildAll(indexer)
-  })
-
-  it('Validates records correctly', () => {
-    const schema = getSchema('com.example.kitchenSink#main', l.RecordSchema)
-
-    const value = {
-      $type: 'com.example.kitchenSink',
-      object: {
-        object: { boolean: true },
-        array: ['one', 'two'],
-        boolean: true,
-        integer: 123,
-        string: 'string',
-        refToEnumWithDefault: 'option3',
-      },
-      array: ['one', 'two'],
-      boolean: true,
-      integer: 123,
-      string: 'string',
-      datetime: new Date().toISOString(),
-      atUri: 'at://did:web:example.com/com.example.test/self',
-      did: 'did:web:example.com',
-      cid: 'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
-      bytes: new Uint8Array([0, 1, 2, 3]),
-      cidLink: parseCid(
-        'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
-      ),
-    }
-
-    expect(schema.safeParse(value)).toStrictEqual({ success: true, value })
-  })
-
-  it('Validates objects correctly', () => {
-    const schema = getSchema(
-      'com.example.kitchenSink#object',
-      l.TypedObjectSchema,
-    )
-
-    const value = {
-      object: { boolean: true },
-      array: ['one', 'two'],
-      boolean: true,
-      integer: 123,
-      string: 'string',
-    }
-
-    expect(schema.safeParse(value)).toStrictEqual({
-      success: true,
-      value: {
-        object: { boolean: true },
-        array: ['one', 'two'],
-        boolean: true,
-        integer: 123,
-        string: 'string',
-        refToEnumWithDefault: 'option3',
-      },
-    })
-  })
-
-  it('rejects invalid enum values', () => {
-    const schema = getSchema(
-      'com.example.kitchenSink#object',
-      l.TypedObjectSchema,
-    )
-
-    const value = {
-      object: { boolean: true },
-      array: ['one', 'two'],
-      boolean: true,
-      integer: 123,
-      string: 'string',
-      refToEnumWithDefault: 'invalidOption',
-    }
-
-    expect(schema.safeParse(value)).toMatchObject({
-      success: false,
-      reason: {
-        issues: [
-          {
-            code: 'invalid_value',
-            input: 'invalidOption',
-            values: ['option1', 'option2', 'option3'],
-          },
-        ],
-      },
-    })
-  })
-
-  it('does not apply defaults when validating', () => {
-    const schema = getSchema(
-      'com.example.kitchenSink#object',
-      l.TypedObjectSchema,
-    )
-
-    const value = {
-      object: { boolean: true },
-      array: ['one', 'two'],
-      boolean: true,
-      integer: 123,
-      string: 'string',
-    }
-
-    expect(schema.safeValidate(value)).toStrictEqual({
-      success: true,
-      value: {
-        object: { boolean: true },
-        array: ['one', 'two'],
-        boolean: true,
-        integer: 123,
-        string: 'string',
-      },
-    })
-  })
-
-  it('allows missing optional record fields', () => {
-    const schema = getSchema(
-      'com.example.kitchenSink#object',
-      l.TypedObjectSchema,
-    )
-
-    expect(
-      schema.matches({
-        object: { boolean: true },
-        array: ['one', 'two'],
-        boolean: true,
-        integer: 123,
-        string: 'string',
-      }),
-    ).toBe(true)
-  })
-
-  it('Rejects missing required record fields', () => {
-    const schema = getSchema(
-      'com.example.kitchenSink#object',
-      l.TypedObjectSchema,
-    )
-
-    const value = {
-      object: { boolean: true },
-      // array: ['one', 'two'],
-      boolean: true,
-      integer: 123,
-      string: 'string',
-    }
-
-    expect(schema.safeParse(value)).toMatchObject({
-      success: false,
-      reason: { issues: [{ code: 'required_key', key: 'array' }] },
-    })
-  })
-
-  it('fails validation when ref uri has multiple hash segments', async () => {
-    const schema: LexiconDocument = {
-      lexicon: 1,
-      id: 'com.example.invalid',
-      defs: {
-        main: {
-          type: 'object',
-          properties: {
-            test: { type: 'ref', ref: 'com.example.invalid#test#test' },
-          },
-        },
-      },
-    }
-
-    await expect(async () => {
-      await LexiconSchemaBuilder.buildAll(new LexiconIterableIndexer([schema]))
-    }).rejects.toThrow('Uri can only have one hash segment')
-  })
-
-  it('fails lexicon parsing when uri is invalid', async () => {
-    const schema: LexiconDocument = {
-      lexicon: 1,
-      id: 'com.example.invalid',
-      defs: {
-        main: {
-          type: 'object',
-          properties: {
-            test: { type: 'ref', ref: 'com.example.missing#main' },
-          },
-        },
-      },
-    }
-
-    await expect(async () => {
-      await LexiconSchemaBuilder.buildAll(new LexiconIterableIndexer([schema]))
-    }).rejects.toThrow('Lexicon com.example.missing not found')
-  })
-
-  it('fails lexicon parsing when uri is invalid', async () => {
-    const schema: LexiconDocument = {
-      lexicon: 1,
-      id: 'com.example.invalid',
-      defs: {
-        main: {
-          type: 'object',
-          properties: {
-            test: { type: 'ref', ref: 'com.example.invalid#nonexistent' },
-          },
-        },
-      },
-    }
-
-    await expect(async () => {
-      await LexiconSchemaBuilder.buildAll(new LexiconIterableIndexer([schema]))
-    }).rejects.toThrow(
-      'No definition found for hash ""nonexistent"" in com.example.invalid',
-    )
-  })
-})