@atproto/lex-builder 0.0.13 → 0.0.15

package/src/ref-resolver.test.ts

@@ -0,0 +1,75 @@
+import { Project } from 'ts-morph'
+import { describe, expect, it } from 'vitest'
+import { LexiconDocument, LexiconIndexer } from '@atproto/lex-document'
+import { RefResolver } from './ref-resolver.js'
+
+class DummyIndexer implements LexiconIndexer, AsyncIterable<LexiconDocument> {
+  readonly docs: Map<string, LexiconDocument>
+
+  constructor(docs: LexiconDocument[]) {
+    this.docs = new Map(docs.map((doc) => [doc.id, doc]))
+  }
+
+  async get(id: string): Promise<LexiconDocument> {
+    const doc = this.docs.get(id)
+    if (!doc) {
+      throw new Error(`Document not found: ${id}`)
+    }
+    return doc
+  }
+
+  async *[Symbol.asyncIterator]() {
+    for (const doc of this.docs.values()) {
+      yield doc
+    }
+  }
+}
+
+describe('RefResolver', () => {
+  const docs: LexiconDocument[] = [
+    {
+      lexicon: 1,
+      id: 'com.example.foo',
+      defs: {
+        main: { type: 'token' },
+      },
+    },
+    {
+      lexicon: 1,
+      id: 'com.example.bar',
+      defs: {
+        main: { type: 'token' },
+      },
+    },
+  ]
+
+  it('uses default relative path for external refs', async () => {
+    const project = new Project({ useInMemoryFileSystem: true })
+    const file = project.createSourceFile('/com/example/foo.defs.ts')
+    const indexer = new DummyIndexer(docs)
+    const resolver = new RefResolver(docs[0], file, indexer, {})
+
+    await resolver.resolve('com.example.bar#main')
+
+    const imports = file.getImportDeclarations()
+    expect(imports).toHaveLength(1)
+    expect(imports[0].getModuleSpecifierValue()).toBe('./bar.defs.js')
+  })
+
+  it('uses custom moduleSpecifier when provided', async () => {
+    const project = new Project({ useInMemoryFileSystem: true })
+    const file = project.createSourceFile('/com/example/foo.defs.ts')
+    const indexer = new DummyIndexer(docs)
+    const resolver = new RefResolver(docs[0], file, indexer, {
+      moduleSpecifier: (nsid) => `https://lex.example.com/${nsid}.ts`,
+    })
+
+    await resolver.resolve('com.example.bar#main')
+
+    const imports = file.getImportDeclarations()
+    expect(imports).toHaveLength(1)
+    expect(imports[0].getModuleSpecifierValue()).toBe(
+      'https://lex.example.com/com.example.bar.ts',
+    )
+  })
+})

package/src/ref-resolver.ts

@@ -17,18 +17,68 @@ import {
   ucFirst,
 } from './util.js'
 
+/**
+ * Configuration options for the {@link RefResolver} class.
+ */
 export type RefResolverOptions = {
+  /**
+   * The file extension to use for import specifiers when resolving
+   * external references.
+   *
+   * @default '.js'
+   */
   importExt?: string
+  moduleSpecifier?: (nsid: string) => string
 }
 
+/**
+ * Represents a resolved lexicon reference as TypeScript identifiers.
+ *
+ * Contains the variable name (for runtime schema) and type name (for
+ * TypeScript type) that can be used to reference a lexicon definition.
+ */
 export type ResolvedRef = {
+  /**
+   * The variable name for the runtime schema.
+   *
+   * For local definitions, this is a simple identifier.
+   * For external definitions, this may be a qualified name like `ns.varName`
+   * or bracket notation like `ns["varName"]` for unsafe identifiers.
+   */
   varName: string
+  /**
+   * The type name for the TypeScript type alias.
+   *
+   * Always a valid TypeScript identifier, either simple or qualified.
+   */
   typeName: string
 }
 
 /**
- * Utility class to resolve lexicon references to TypeScript identifiers,
- * generating "import" statements as needed.
+ * Resolves lexicon references to TypeScript identifiers.
+ *
+ * This class handles the resolution of `ref` types in lexicon documents,
+ * converting lexicon reference strings (like `com.example.foo#bar`) into
+ * valid TypeScript identifiers. It automatically manages:
+ *
+ * - Local references within the same document
+ * - External references to other lexicon documents
+ * - Import statement generation for external references
+ * - Conflict avoidance with keywords, globals, and existing declarations
+ *
+ * Results are memoized to ensure consistent identifiers for the same
+ * reference throughout a file.
+ *
+ * @example
+ * ```ts
+ * const resolver = new RefResolver(doc, sourceFile, indexer, options)
+ *
+ * // Resolve a local reference
+ * const local = await resolver.resolve('#myDef')
+ *
+ * // Resolve an external reference
+ * const external = await resolver.resolve('com.example.other#def')
+ * ```
  */
 export class RefResolver {
   constructor(
@@ -79,6 +129,19 @@ export class RefResolver {
   }
 
   /**
+   * Resolves a local definition hash to TypeScript identifiers.
+   *
+   * This method generates safe, non-conflicting identifiers for definitions
+   * within the current document. It handles edge cases like:
+   * - Hash names that are JavaScript keywords
+   * - Hash names that conflict with global identifiers
+   * - Multiple hashes that would produce the same identifier
+   *
+   * @param hash - The definition hash (e.g., 'main', 'record', 'myType')
+   * @returns A promise resolving to the TypeScript identifiers
+   * @throws Error if the hash does not exist in the document
+   * @throws Error if conflicting type names are detected
+   *
    * @note The returned `typeName` and `varName` are *both* guaranteed to be
    * valid TypeScript identifiers.
    */
@@ -149,10 +212,12 @@ export class RefResolver {
   private readonly resolveExternal = memoize(
     async (fullRef: string): Promise<ResolvedRef> => {
       const [nsid, hash] = fullRef.split('#')
-      const moduleSpecifier = `${asRelativePath(
-        this.file.getDirectoryPath(),
-        join('/', ...nsid.split('.')),
-      )}.defs${this.options.importExt ?? '.js'}`
+      const moduleSpecifier = this.options.moduleSpecifier
+        ? this.options.moduleSpecifier(nsid)
+        : `${asRelativePath(
+            this.file.getDirectoryPath(),
+            join('/', ...nsid.split('.')),
+          )}.defs${this.options.importExt ?? '.js'}`
 
       // Lets first make sure the referenced lexicon exists
       const srcDoc = await this.indexer.get(nsid)
@@ -325,6 +390,13 @@ function nsidToIdentifier(nsid: string) {
 /**
  * Generates predictable public identifiers for a given definition hash.
  *
+ * This function creates the "public" names that will be exported from
+ * generated files. The variable name uses the original hash, while the
+ * type name is converted to PascalCase.
+ *
+ * @param hash - The definition hash (e.g., 'main', 'myType')
+ * @returns The public identifiers for the definition
+ *
  * @note The returned `typeName` is guaranteed to be a valid TypeScript
  * identifier. `varName` may not be a valid identifier (eg. if the hash contains
  * unsafe characters), and may need to be accessed using string indexing.

package/src/ts-lang.ts

@@ -1,5 +1,8 @@
 /**
- * JavaScript keywords
+ * Set of JavaScript reserved keywords and future reserved words.
+ *
+ * These identifiers cannot be used as variable or type names in generated code.
+ *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar}
  */
 const JS_KEYWORDS = new Set([
@@ -77,6 +80,12 @@ const JS_KEYWORDS = new Set([
   'yield',
 ])
 
+/**
+ * Checks if a word is a JavaScript reserved keyword.
+ *
+ * @param word - The identifier to check
+ * @returns `true` if the word is a reserved keyword
+ */
 export function isJsKeyword(word: string) {
   return JS_KEYWORDS.has(word)
 }
@@ -129,14 +138,42 @@ const GLOBAL_IDENTIFIERS = new Set([
   'Uncapitalize',
 ])
 
+/**
+ * Checks if a word is a global identifier that should be avoided.
+ *
+ * This includes JavaScript globals, TypeScript built-in types, and
+ * identifiers commonly used in the generated code.
+ *
+ * @param word - The identifier to check
+ * @returns `true` if the word is a global identifier
+ */
 export function isGlobalIdentifier(word: string) {
   return GLOBAL_IDENTIFIERS.has(word)
 }
 
+/**
+ * Checks if a name is safe to use as a local identifier.
+ *
+ * A safe local identifier is a valid JavaScript identifier that does not
+ * conflict with global identifiers.
+ *
+ * @param name - The identifier to check
+ * @returns `true` if the name is safe to use locally
+ */
 export function isSafeLocalIdentifier(name: string) {
   return !isGlobalIdentifier(name) && isValidJsIdentifier(name)
 }
 
+/**
+ * Checks if a name is a valid JavaScript identifier.
+ *
+ * Valid identifiers start with a letter, underscore, or dollar sign,
+ * followed by any combination of letters, digits, underscores, or dollar
+ * signs. Reserved keywords are not valid identifiers.
+ *
+ * @param name - The string to check
+ * @returns `true` if the name is a valid identifier
+ */
 export function isValidJsIdentifier(name: string) {
   return (
     name.length > 0 &&
@@ -145,6 +182,16 @@ export function isValidJsIdentifier(name: string) {
   )
 }
 
+/**
+ * Converts a name to a valid namespace export identifier.
+ *
+ * If the name is a valid JavaScript identifier, it is returned as-is.
+ * Otherwise, it is returned as a quoted string for use in export statements
+ * like `export { foo as "unsafe-name" }`.
+ *
+ * @param name - The export name
+ * @returns The name as a valid export identifier
+ */
 export function asNamespaceExport(name: string) {
   return isValidJsIdentifier(name) ? name : JSON.stringify(name)
 }