@atproto/lex-installer 0.0.14 → 0.0.16

package/dist/nsid-set.js

@@ -3,17 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NsidSet = exports.MappedSet = void 0;
 const syntax_1 = require("@atproto/syntax");
 /**
- * A Set implementation that maps values of type K to an internal representation
- * I. Value identity is determined by the {@link Object.is} comparison of the
- * encoded values.
+ * A Set implementation that maps values of type K to an internal representation I.
  *
- * This is typically useful for values that can be serialized to a unique string
- * representation.
+ * Value identity is determined by the {@link Object.is} comparison of the
+ * encoded values. This is useful for complex types that can be serialized
+ * to a unique primitive representation (typically strings).
+ *
+ * @typeParam K - The external value type stored in the set
+ * @typeParam I - The internal encoded type used for identity comparison
  */
 class MappedSet {
     encodeValue;
     decodeValue;
     set = new Set();
+    /**
+     * Creates a new MappedSet with custom encoding/decoding functions.
+     *
+     * @param encodeValue - Function to convert external values to internal representation
+     * @param decodeValue - Function to convert internal representation back to external values
+     */
     constructor(encodeValue, decodeValue) {
         this.encodeValue = encodeValue;
         this.decodeValue = decodeValue;
@@ -57,7 +65,35 @@ class MappedSet {
     [Symbol.toStringTag] = 'MappedSet';
 }
 exports.MappedSet = MappedSet;
+/**
+ * A Set specialized for storing NSID (Namespaced Identifier) values.
+ *
+ * NSIDs are compared by their string representation, allowing different
+ * NSID object instances with the same value to be treated as equal.
+ *
+ * @example
+ * ```typescript
+ * import { NsidSet } from '@atproto/lex-installer'
+ * import { NSID } from '@atproto/syntax'
+ *
+ * const nsidSet = new NsidSet()
+ *
+ * nsidSet.add(NSID.from('app.bsky.feed.post'))
+ * nsidSet.add(NSID.from('app.bsky.actor.profile'))
+ *
+ * // Check membership
+ * nsidSet.has(NSID.from('app.bsky.feed.post')) // true
+ *
+ * // Iterate over NSIDs
+ * for (const nsid of nsidSet) {
+ *   console.log(nsid.toString())
+ * }
+ * ```
+ */
 class NsidSet extends MappedSet {
+    /**
+     * Creates a new empty NsidSet.
+     */
     constructor() {
         super((val) => val.toString(), (enc) => syntax_1.NSID.from(enc));
     }

package/dist/nsid-set.js.map

@@ -1 +1 @@
-{"version":3,"file":"nsid-set.js","sourceRoot":"","sources":["../src/nsid-set.ts"],"names":[],"mappings":";;;AAAA,4CAAsC;AAEtC;;;;;;;GAOG;AACH,MAAa,SAAS;IAID;IACA;IAJX,GAAG,GAAG,IAAI,GAAG,EAAK,CAAA;IAE1B,YACmB,WAA0B,EAC1B,WAA0B;QAD1B,gBAAW,GAAX,WAAW,CAAe;QAC1B,gBAAW,GAAX,WAAW,CAAe;IAC1C,CAAC;IAEJ,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAA;IACtB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;IAClB,CAAC;IAED,GAAG,CAAC,GAAM;QACR,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;QACnC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,GAAG,CAAC,GAAM;QACR,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;IAC5C,CAAC;IAED,MAAM,CAAC,GAAM;QACX,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;IAC/C,CAAC;IAED,CAAC,MAAM;QACL,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;YACpC,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;QAC7B,CAAC;IACH,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,MAAM,EAAE,CAAA;IACtB,CAAC;IAED,CAAC,OAAO;QACN,KAAK,MAAM,GAAG,IAAI,IAAI;YAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAC1C,CAAC;IAED,OAAO,CACL,UAAsD,EACtD,OAAa;QAEb,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;QAC1C,CAAC;IACH,CAAC;IAED,CAAC,MAAM,CAAC,QAAQ,CAAC;QACf,OAAO,IAAI,CAAC,MAAM,EAAE,CAAA;IACtB,CAAC;IAED,CAAC,MAAM,CAAC,WAAW,CAAC,GAAW,WAAW,CAAA;CAC3C;AAzDD,8BAyDC;AAED,MAAa,OAAQ,SAAQ,SAAuB;IAClD;QACE,KAAK,CACH,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,EACvB,CAAC,GAAG,EAAE,EAAE,CAAC,aAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CACxB,CAAA;IACH,CAAC;CACF;AAPD,0BAOC","sourcesContent":["import { NSID } from '@atproto/syntax'\n\n/**\n * A Set implementation that maps values of type K to an internal representation\n * I. Value identity is determined by the {@link Object.is} comparison of the\n * encoded values.\n *\n * This is typically useful for values that can be serialized to a unique string\n * representation.\n */\nexport class MappedSet<K, I = any> implements Set<K> {\n  private set = new Set<I>()\n\n  constructor(\n    private readonly encodeValue: (val: K) => I,\n    private readonly decodeValue: (enc: I) => K,\n  ) {}\n\n  get size(): number {\n    return this.set.size\n  }\n\n  clear(): void {\n    this.set.clear()\n  }\n\n  add(val: K): this {\n    this.set.add(this.encodeValue(val))\n    return this\n  }\n\n  has(val: K): boolean {\n    return this.set.has(this.encodeValue(val))\n  }\n\n  delete(val: K): boolean {\n    return this.set.delete(this.encodeValue(val))\n  }\n\n  *values(): IterableIterator<K> {\n    for (const val of this.set.values()) {\n      yield this.decodeValue(val)\n    }\n  }\n\n  keys(): SetIterator<K> {\n    return this.values()\n  }\n\n  *entries(): IterableIterator<[K, K]> {\n    for (const val of this) yield [val, val]\n  }\n\n  forEach(\n    callbackfn: (value: K, value2: K, set: Set<K>) => void,\n    thisArg?: any,\n  ): void {\n    for (const val of this) {\n      callbackfn.call(thisArg, val, val, this)\n    }\n  }\n\n  [Symbol.iterator](): IterableIterator<K> {\n    return this.values()\n  }\n\n  [Symbol.toStringTag]: string = 'MappedSet'\n}\n\nexport class NsidSet extends MappedSet<NSID, string> {\n  constructor() {\n    super(\n      (val) => val.toString(),\n      (enc) => NSID.from(enc),\n    )\n  }\n}\n"]}
+{"version":3,"file":"nsid-set.js","sourceRoot":"","sources":["../src/nsid-set.ts"],"names":[],"mappings":";;;AAAA,4CAAsC;AAEtC;;;;;;;;;GASG;AACH,MAAa,SAAS;IAUD;IACA;IAVX,GAAG,GAAG,IAAI,GAAG,EAAK,CAAA;IAE1B;;;;;OAKG;IACH,YACmB,WAA0B,EAC1B,WAA0B;QAD1B,gBAAW,GAAX,WAAW,CAAe;QAC1B,gBAAW,GAAX,WAAW,CAAe;IAC1C,CAAC;IAEJ,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAA;IACtB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;IAClB,CAAC;IAED,GAAG,CAAC,GAAM;QACR,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;QACnC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,GAAG,CAAC,GAAM;QACR,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;IAC5C,CAAC;IAED,MAAM,CAAC,GAAM;QACX,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAA;IAC/C,CAAC;IAED,CAAC,MAAM;QACL,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;YACpC,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;QAC7B,CAAC;IACH,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,MAAM,EAAE,CAAA;IACtB,CAAC;IAED,CAAC,OAAO;QACN,KAAK,MAAM,GAAG,IAAI,IAAI;YAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAC1C,CAAC;IAED,OAAO,CACL,UAAsD,EACtD,OAAa;QAEb,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAA;QAC1C,CAAC;IACH,CAAC;IAED,CAAC,MAAM,CAAC,QAAQ,CAAC;QACf,OAAO,IAAI,CAAC,MAAM,EAAE,CAAA;IACtB,CAAC;IAED,CAAC,MAAM,CAAC,WAAW,CAAC,GAAW,WAAW,CAAA;CAC3C;AA/DD,8BA+DC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAa,OAAQ,SAAQ,SAAuB;IAClD;;OAEG;IACH;QACE,KAAK,CACH,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,EACvB,CAAC,GAAG,EAAE,EAAE,CAAC,aAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CACxB,CAAA;IACH,CAAC;CACF;AAVD,0BAUC","sourcesContent":["import { NSID } from '@atproto/syntax'\n\n/**\n * A Set implementation that maps values of type K to an internal representation I.\n *\n * Value identity is determined by the {@link Object.is} comparison of the\n * encoded values. This is useful for complex types that can be serialized\n * to a unique primitive representation (typically strings).\n *\n * @typeParam K - The external value type stored in the set\n * @typeParam I - The internal encoded type used for identity comparison\n */\nexport class MappedSet<K, I = any> implements Set<K> {\n  private set = new Set<I>()\n\n  /**\n   * Creates a new MappedSet with custom encoding/decoding functions.\n   *\n   * @param encodeValue - Function to convert external values to internal representation\n   * @param decodeValue - Function to convert internal representation back to external values\n   */\n  constructor(\n    private readonly encodeValue: (val: K) => I,\n    private readonly decodeValue: (enc: I) => K,\n  ) {}\n\n  get size(): number {\n    return this.set.size\n  }\n\n  clear(): void {\n    this.set.clear()\n  }\n\n  add(val: K): this {\n    this.set.add(this.encodeValue(val))\n    return this\n  }\n\n  has(val: K): boolean {\n    return this.set.has(this.encodeValue(val))\n  }\n\n  delete(val: K): boolean {\n    return this.set.delete(this.encodeValue(val))\n  }\n\n  *values(): IterableIterator<K> {\n    for (const val of this.set.values()) {\n      yield this.decodeValue(val)\n    }\n  }\n\n  keys(): SetIterator<K> {\n    return this.values()\n  }\n\n  *entries(): IterableIterator<[K, K]> {\n    for (const val of this) yield [val, val]\n  }\n\n  forEach(\n    callbackfn: (value: K, value2: K, set: Set<K>) => void,\n    thisArg?: any,\n  ): void {\n    for (const val of this) {\n      callbackfn.call(thisArg, val, val, this)\n    }\n  }\n\n  [Symbol.iterator](): IterableIterator<K> {\n    return this.values()\n  }\n\n  [Symbol.toStringTag]: string = 'MappedSet'\n}\n\n/**\n * A Set specialized for storing NSID (Namespaced Identifier) values.\n *\n * NSIDs are compared by their string representation, allowing different\n * NSID object instances with the same value to be treated as equal.\n *\n * @example\n * ```typescript\n * import { NsidSet } from '@atproto/lex-installer'\n * import { NSID } from '@atproto/syntax'\n *\n * const nsidSet = new NsidSet()\n *\n * nsidSet.add(NSID.from('app.bsky.feed.post'))\n * nsidSet.add(NSID.from('app.bsky.actor.profile'))\n *\n * // Check membership\n * nsidSet.has(NSID.from('app.bsky.feed.post')) // true\n *\n * // Iterate over NSIDs\n * for (const nsid of nsidSet) {\n *   console.log(nsid.toString())\n * }\n * ```\n */\nexport class NsidSet extends MappedSet<NSID, string> {\n  /**\n   * Creates a new empty NsidSet.\n   */\n  constructor() {\n    super(\n      (val) => val.toString(),\n      (enc) => NSID.from(enc),\n    )\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-installer",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "license": "MIT",
   "description": "Lexicon document packet manager for AT Lexicons",
   "keywords": [
@@ -32,17 +32,17 @@
       "types": "./dist/index.d.ts",
       "browser": "./dist/index.js",
       "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@atproto/lex-builder": "^0.0.13",
-    "@atproto/lex-cbor": "^0.0.10",
-    "@atproto/lex-data": "^0.0.10",
-    "@atproto/lex-document": "^0.0.12",
-    "@atproto/lex-resolver": "^0.0.13",
-    "@atproto/lex-schema": "^0.0.11",
+    "@atproto/lex-builder": "^0.0.15",
+    "@atproto/lex-cbor": "^0.0.11",
+    "@atproto/lex-data": "^0.0.11",
+    "@atproto/lex-document": "^0.0.13",
+    "@atproto/lex-resolver": "^0.0.14",
+    "@atproto/lex-schema": "^0.0.12",
     "@atproto/syntax": "^0.4.3"
   },
   "devDependencies": {

package/src/fs.ts

@@ -1,11 +1,73 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
 
+/**
+ * Reads and parses a JSON file from the filesystem.
+ *
+ * @param path - Absolute or relative path to the JSON file
+ * @returns The parsed JSON content
+ * @throws {Error} When the file cannot be read (e.g., ENOENT, EACCES)
+ * @throws {SyntaxError} When the file contains invalid JSON
+ *
+ * @example
+ * ```typescript
+ * import { readJsonFile } from '@atproto/lex-installer'
+ *
+ * const manifest = await readJsonFile('./lexicons.manifest.json')
+ * ```
+ *
+ * @example
+ * Handle missing file:
+ * ```typescript
+ * import { readJsonFile, isEnoentError } from '@atproto/lex-installer'
+ *
+ * try {
+ *   const data = await readJsonFile('./config.json')
+ * } catch (err) {
+ *   if (isEnoentError(err)) {
+ *     console.log('File does not exist, using defaults')
+ *   } else {
+ *     throw err
+ *   }
+ * }
+ * ```
+ */
 export async function readJsonFile(path: string): Promise<unknown> {
   const contents = await readFile(path, 'utf8')
   return JSON.parse(contents)
 }
 
+/**
+ * Writes data as formatted JSON to a file.
+ *
+ * The function:
+ * - Creates parent directories if they don't exist
+ * - Formats JSON with 2-space indentation
+ * - Overwrites existing files
+ * - Sets file permissions to 0o644 (rw-r--r--)
+ *
+ * @param path - Absolute or relative path for the output file
+ * @param data - Data to serialize as JSON
+ * @throws {Error} When the file cannot be written
+ *
+ * @example
+ * ```typescript
+ * import { writeJsonFile } from '@atproto/lex-installer'
+ *
+ * await writeJsonFile('./output/data.json', {
+ *   name: 'example',
+ *   values: [1, 2, 3],
+ * })
+ * ```
+ *
+ * @example
+ * Write a lexicon document:
+ * ```typescript
+ * import { writeJsonFile } from '@atproto/lex-installer'
+ *
+ * await writeJsonFile('./lexicons/app/bsky/feed/post.json', lexiconDocument)
+ * ```
+ */
 export async function writeJsonFile(
   path: string,
   data: unknown,
@@ -19,6 +81,42 @@ export async function writeJsonFile(
   })
 }
 
+/**
+ * Checks if an error is an ENOENT (file not found) error.
+ *
+ * Useful for handling cases where a file may or may not exist,
+ * such as reading an optional configuration file.
+ *
+ * @param err - The error to check
+ * @returns `true` if the error is an ENOENT error, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { readFile } from 'node:fs/promises'
+ * import { isEnoentError } from '@atproto/lex-installer'
+ *
+ * const config = await readFile('./config.json').catch((err) => {
+ *   if (isEnoentError(err)) {
+ *     return { defaults: true }
+ *   }
+ *   throw err
+ * })
+ * ```
+ *
+ * @example
+ * In try/catch:
+ * ```typescript
+ * try {
+ *   const manifest = await readFile('./lexicons.manifest.json', 'utf8')
+ * } catch (err) {
+ *   if (isEnoentError(err)) {
+ *     // File doesn't exist, create a new manifest
+ *     return { version: 1, lexicons: [], resolutions: {} }
+ *   }
+ *   throw err
+ * }
+ * ```
+ */
 export function isEnoentError(err: unknown): boolean {
   return err instanceof Error && 'code' in err && err.code === 'ENOENT'
 }

package/src/index.ts

@@ -5,12 +5,97 @@ import {
   lexiconsManifestSchema,
 } from './lexicons-manifest.js'
 
+/**
+ * Options for the {@link install} function.
+ *
+ * Extends {@link LexInstallerOptions} with additional options for controlling
+ * the installation behavior.
+ *
+ * @example
+ * ```typescript
+ * const options: LexInstallOptions = {
+ *   lexicons: './lexicons',
+ *   manifest: './lexicons.manifest.json',
+ *   add: ['com.example.myLexicon', 'at://did:plc:xyz/com.example.otherLexicon'],
+ *   save: true,
+ *   ci: false,
+ * }
+ * ```
+ */
 export type LexInstallOptions = LexInstallerOptions & {
+  /**
+   * Array of lexicons to add to the installation. Can be NSID strings
+   * (e.g., 'com.example.myLexicon') or AT URIs
+   * (e.g., 'at://did:plc:xyz/com.example.myLexicon').
+   */
   add?: string[]
+
+  /**
+   * Whether to save the updated manifest after installation.
+   * When `true`, the manifest file will be written with any new lexicons.
+   * @default false
+   */
   save?: boolean
+
+  /**
+   * Enable CI mode for strict manifest verification.
+   * When `true`, throws an error if the manifest is out of date,
+   * useful for continuous integration pipelines.
+   * @default false
+   */
   ci?: boolean
 }
 
+/**
+ * Installs lexicons from the network based on the provided options.
+ *
+ * This is the main entry point for programmatic lexicon installation.
+ * It reads an existing manifest (if present), installs any new lexicons,
+ * and optionally saves the updated manifest.
+ *
+ * @param options - Configuration options for the installation
+ * @throws {Error} When the manifest file cannot be read (unless it doesn't exist)
+ * @throws {Error} When in CI mode and the manifest is out of date
+ *
+ * @example
+ * Install lexicons and save the manifest:
+ * ```typescript
+ * import { install } from '@atproto/lex-installer'
+ *
+ * await install({
+ *   lexicons: './lexicons',
+ *   manifest: './lexicons.manifest.json',
+ *   add: ['app.bsky.feed.post', 'app.bsky.actor.profile'],
+ *   save: true,
+ * })
+ * ```
+ *
+ * @example
+ * Verify manifest in CI pipeline:
+ * ```typescript
+ * import { install } from '@atproto/lex-installer'
+ *
+ * // Throws if manifest is out of date
+ * await install({
+ *   lexicons: './lexicons',
+ *   manifest: './lexicons.manifest.json',
+ *   ci: true,
+ * })
+ * ```
+ *
+ * @example
+ * Install from specific AT URIs:
+ * ```typescript
+ * import { install } from '@atproto/lex-installer'
+ *
+ * await install({
+ *   lexicons: './lexicons',
+ *   manifest: './lexicons.manifest.json',
+ *   add: ['at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post'],
+ *   save: true,
+ * })
+ * ```
+ */
 export async function install(options: LexInstallOptions) {
   const manifest: LexiconsManifest | undefined = await readJsonFile(
     options.manifest,

package/src/lex-installer.ts

@@ -23,12 +23,84 @@ import {
 import { NsidMap } from './nsid-map.js'
 import { NsidSet } from './nsid-set.js'
 
+/**
+ * Configuration options for the {@link LexInstaller} class.
+ *
+ * Extends {@link LexResolverOptions} with paths for lexicon storage
+ * and manifest management.
+ *
+ * @example
+ * ```typescript
+ * const options: LexInstallerOptions = {
+ *   lexicons: './lexicons',
+ *   manifest: './lexicons.manifest.json',
+ *   update: false,
+ * }
+ * ```
+ */
 export type LexInstallerOptions = LexResolverOptions & {
+  /**
+   * Path to the directory where lexicon JSON files will be stored.
+   * The directory structure mirrors the NSID hierarchy
+   * (e.g., 'app.bsky.feed.post' becomes 'app/bsky/feed/post.json').
+   */
   lexicons: string
+
+  /**
+   * Path to the manifest file that tracks installed lexicons and their resolutions.
+   */
   manifest: string
+
+  /**
+   * When `true`, forces re-fetching of lexicons from the network even if they
+   * already exist locally. Useful for updating to newer versions.
+   * @default false
+   */
   update?: boolean
 }
 
+/**
+ * Manages the installation of Lexicon schemas from the AT Protocol network.
+ *
+ * The `LexInstaller` class handles fetching, caching, and organizing lexicon
+ * documents. It tracks dependencies between lexicons and ensures all referenced
+ * schemas are installed. The class implements `AsyncDisposable` for proper
+ * resource cleanup.
+ *
+ * @example
+ * Basic usage with async disposal:
+ * ```typescript
+ * import { LexInstaller } from '@atproto/lex-installer'
+ *
+ * await using installer = new LexInstaller({
+ *   lexicons: './lexicons',
+ *   manifest: './lexicons.manifest.json',
+ * })
+ *
+ * await installer.install({
+ *   additions: ['app.bsky.feed.post'],
+ * })
+ *
+ * await installer.save()
+ * // Resources automatically cleaned up when block exits
+ * ```
+ *
+ * @example
+ * Manual disposal:
+ * ```typescript
+ * const installer = new LexInstaller({
+ *   lexicons: './lexicons',
+ *   manifest: './lexicons.manifest.json',
+ * })
+ *
+ * try {
+ *   await installer.install({ additions: ['app.bsky.actor.profile'] })
+ *   await installer.save()
+ * } finally {
+ *   await installer[Symbol.asyncDispose]()
+ * }
+ * ```
+ */
 export class LexInstaller implements AsyncDisposable {
   protected readonly lexiconResolver: LexResolver
   protected readonly indexer: LexiconDirectoryIndexer
@@ -50,6 +122,15 @@ export class LexInstaller implements AsyncDisposable {
     await this.indexer[Symbol.asyncDispose]()
   }
 
+  /**
+   * Compares the current manifest state with another manifest for equality.
+   *
+   * Both manifests are normalized before comparison to ensure consistent
+   * ordering of entries. Useful for detecting changes during CI verification.
+   *
+   * @param manifest - The manifest to compare against
+   * @returns `true` if the manifests are equivalent, `false` otherwise
+   */
   equals(manifest: LexiconsManifest): boolean {
     return lexEquals(
       normalizeLexiconsManifest(manifest),
@@ -57,6 +138,47 @@ export class LexInstaller implements AsyncDisposable {
     )
   }
 
+  /**
+   * Installs lexicons and their dependencies.
+   *
+   * This method processes explicit additions and restores entries from an
+   * existing manifest. It recursively resolves and installs all referenced
+   * lexicons to ensure complete dependency trees.
+   *
+   * @param options - Installation options
+   * @param options.additions - Iterable of lexicon identifiers to add.
+   *   Can be NSID strings or AT URIs.
+   * @param options.manifest - Existing manifest to use as a baseline.
+   *   Previously resolved URIs are preserved unless explicitly overridden.
+   *
+   * @example
+   * Install new lexicons:
+   * ```typescript
+   * await installer.install({
+   *   additions: ['app.bsky.feed.post', 'app.bsky.actor.profile'],
+   * })
+   * ```
+   *
+   * @example
+   * Install with existing manifest as hint:
+   * ```typescript
+   * const existingManifest = await readJsonFile('./lexicons.manifest.json')
+   * await installer.install({
+   *   additions: ['com.example.newLexicon'],
+   *   manifest: existingManifest,
+   * })
+   * ```
+   *
+   * @example
+   * Install from specific AT URIs:
+   * ```typescript
+   * await installer.install({
+   *   additions: [
+   *     'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post',
+   *   ],
+   * })
+   * ```
+   */
   async install({
     additions,
     manifest,
@@ -183,6 +305,15 @@ export class LexInstaller implements AsyncDisposable {
     return { lexicon, uri }
   }
 
+  /**
+   * Fetches a lexicon document from the network and saves it locally.
+   *
+   * The lexicon is retrieved from the specified AT URI, written to the
+   * local lexicons directory, and its metadata is recorded for the manifest.
+   *
+   * @param uri - The AT URI pointing to the lexicon document
+   * @returns An object containing the fetched lexicon document and its CID
+   */
   async fetch(uri: AtUri): Promise<{ lexicon: LexiconDocument; cid: Cid }> {
     console.debug(`Fetching lexicon from ${uri}...`)
 
@@ -196,6 +327,12 @@ export class LexInstaller implements AsyncDisposable {
     return { lexicon, cid }
   }
 
+  /**
+   * Saves the current manifest to disk.
+   *
+   * The manifest is normalized before saving to ensure consistent ordering
+   * of entries, making it suitable for version control.
+   */
   async save(): Promise<void> {
     await writeJsonFile(
       this.options.manifest,

package/src/lexicons-manifest.ts

@@ -1,19 +1,47 @@
 import { l } from '@atproto/lex-schema'
 
+/**
+ * Schema for validating and parsing lexicons manifest files.
+ *
+ * The manifest tracks which lexicons are installed and how they were resolved.
+ * This schema ensures the manifest file conforms to the expected structure.
+ */
 export const lexiconsManifestSchema = l.object({
+  /** Schema version, currently always 1 */
   version: l.literal(1),
+  /** Array of NSID strings for directly requested lexicons */
   lexicons: l.array(l.string({ format: 'nsid' })),
+  /** Map of NSID to resolution info (AT URI and CID) for all installed lexicons */
   resolutions: l.dict(
     l.string({ format: 'nsid' }),
     l.object({
+      /** AT URI where the lexicon was fetched from */
       uri: l.string({ format: 'at-uri' }),
+      /** Content identifier (CID) of the lexicon document */
       cid: l.string({ format: 'cid' }),
     }),
   ),
 })
 
+/**
+ * Type representing a parsed lexicons manifest.
+ */
 export type LexiconsManifest = l.Infer<typeof lexiconsManifestSchema>
 
+/**
+ * Normalizes a lexicons manifest for consistent storage and comparison.
+ *
+ * This function:
+ * - Sorts the `lexicons` array alphabetically
+ * - Sorts the `resolutions` object entries by key
+ * - Validates the result against the schema
+ *
+ * Normalization ensures that manifests with the same content produce identical
+ * JSON output, making them suitable for version control and comparison.
+ *
+ * @param manifest - The manifest to normalize
+ * @returns A new normalized manifest object
+ */
 export function normalizeLexiconsManifest(
   manifest: LexiconsManifest,
 ): LexiconsManifest {

package/src/nsid-map.ts

@@ -1,16 +1,25 @@
 import { NSID } from '@atproto/syntax'
 
 /**
- * A Map implementation that maps keys of type K to an internal representation
- * I. Key identity is determined by the {@link Object.is} comparison of the
- * encoded keys.
+ * A Map implementation that maps keys of type K to an internal representation I.
  *
- * This is typically useful for values that can be serialized to a unique string
- * representation.
+ * Key identity is determined by the {@link Object.is} comparison of the
+ * encoded keys. This is useful for complex key types that can be serialized
+ * to a unique primitive representation (typically strings).
+ *
+ * @typeParam K - The external key type
+ * @typeParam V - The value type stored in the map
+ * @typeParam I - The internal encoded key type used for identity comparison
  */
 class MappedMap<K, V, I = any> implements Map<K, V> {
   private map = new Map<I, V>()
 
+  /**
+   * Creates a new MappedMap with custom key encoding/decoding functions.
+   *
+   * @param encodeKey - Function to convert external keys to internal representation
+   * @param decodeKey - Function to convert internal representation back to external keys
+   */
   constructor(
     private readonly encodeKey: (key: K) => I,
     private readonly decodeKey: (enc: I) => K,
@@ -73,7 +82,39 @@ class MappedMap<K, V, I = any> implements Map<K, V> {
   [Symbol.toStringTag]: string = 'MappedMap'
 }
 
+/**
+ * A Map specialized for using NSID (Namespaced Identifier) values as keys.
+ *
+ * NSIDs are compared by their string representation, allowing different
+ * NSID object instances with the same value to be treated as the same key.
+ *
+ * @typeParam T - The value type stored in the map
+ *
+ * @example
+ * ```typescript
+ * import { NsidMap } from '@atproto/lex-installer'
+ * import { NSID } from '@atproto/syntax'
+ * import { LexiconDocument } from '@atproto/lex-document'
+ *
+ * const lexicons = new NsidMap<LexiconDocument>()
+ *
+ * // Store lexicon documents by NSID
+ * lexicons.set(NSID.from('app.bsky.feed.post'), postLexicon)
+ * lexicons.set(NSID.from('app.bsky.actor.profile'), profileLexicon)
+ *
+ * // Retrieve by NSID (different object instance works)
+ * const doc = lexicons.get(NSID.from('app.bsky.feed.post'))
+ *
+ * // Iterate over entries
+ * for (const [nsid, lexicon] of lexicons) {
+ *   console.log(`${nsid}: ${lexicon.description}`)
+ * }
+ * ```
+ */
 export class NsidMap<T> extends MappedMap<NSID, T, string> {
+  /**
+   * Creates a new empty NsidMap.
+   */
   constructor() {
     super(
       (key) => key.toString(),