jsdoc

src/index.ts

···
+/**
+ * plcbundle - Zero-dependency library for working with PLC bundle archives
+ * 
+ * This module provides a Bun-native implementation for reading, processing,
+ * and cloning PLC (Placeholder DID) bundle archives. It leverages Bun's native
+ * features for optimal performance.
+ * 
+ * @example
+ * ```ts
+ * import { PLCBundle } from "@yourscope/plcbundle-bun";
+ * 
+ * // Create bundle instance
+ * const bundle = new PLCBundle("./bundles");
+ * 
+ * // Clone from remote
+ * await bundle.clone("https://plcbundle.atscan.net", {
+ *   bundles: "1-100",
+ *   threads: 8
+ * });
+ * 
+ * // Process operations
+ * await bundle.processBundles(1, 10, (op, pos, num) => {
+ *   console.log(op.did);
+ * });
+ * ```
+ * 
+ * @module
+ */
+
 export { PLCBundle } from './plcbundle';
 export type { 
   BundleIndex, 
   BundleMetadata, 
   Operation,
-  ProcessCallback 
+  ProcessCallback,
+  ProcessStats,
+  ProcessOptions,
+  CloneOptions,
+  CloneStats,
 } from './types';

src/plcbundle.ts

···
 }
 
 /**
- * Bundle reader and processor for plcbundle format
+ * Main class for reading and processing PLC bundle archives.
+ * 
+ * This class provides methods for:
+ * - Cloning bundles from remote repositories
+ * - Reading and verifying local bundles
+ * - Streaming operations from bundles
+ * - Processing bundles with custom callbacks
+ * 
+ * All operations use Bun's native features for optimal performance.
+ * 
+ * @example Basic usage
+ * ```ts
+ * const bundle = new PLCBundle('./my-bundles');
+ * 
+ * // Get repository information
+ * const stats = await bundle.getStats();
+ * console.log(`Repository has ${stats.lastBundle} bundles`);
+ * 
+ * // Stream operations from a bundle
+ * for await (const op of bundle.streamOperations(1)) {
+ *   console.log(op.did);
+ * }
+ * ```
+ * 
+ * @example Clone from remote
+ * ```ts
+ * const bundle = new PLCBundle('./bundles');
+ * 
+ * await bundle.clone('https://plcbundle.atscan.net', {
+ *   bundles: '1-100',
+ *   threads: 8,
+ *   verify: true,
+ *   onProgress: (stats) => {
+ *     console.log(`${stats.downloadedBundles}/${stats.totalBundles}`);
+ *   }
+ * });
+ * ```
+ * 
+ * @example Process with callback
+ * ```ts
+ * await bundle.processBundles(1, 10, (op, pos, num) => {
+ *   if (op.did.startsWith('did:plc:')) {
+ *     console.log(`Found DID: ${op.did}`);
+ *   }
+ * }, {
+ *   threads: 4,
+ *   onProgress: (stats) => console.log(`${stats.totalOps} ops`)
+ * });
+ * ```
  */
 export class PLCBundle {
   private dir: string;
   private indexPath: string;
   private cachedIndex?: BundleIndex;
 
+    /**
+   * Create a new PLCBundle instance.
+   * 
+   * @param dir - Directory containing bundle files (default: './')
+   * @param indexPath - Path to the index file (default: `${dir}/plc_bundles.json`)
+   * 
+   * @example
+   * ```ts
+   * // Use default directory
+   * const bundle1 = new PLCBundle();
+   * 
+   * // Specify custom directory
+   * const bundle2 = new PLCBundle('./my-bundles');
+   * 
+   * // Custom directory and index path
+   * const bundle3 = new PLCBundle('./bundles', './custom-index.json');
+   * ```
+   */
   constructor(dir: string = './', indexPath?: string) {
     this.dir = dir.endsWith('/') ? dir : `${dir}/`;
     this.indexPath = indexPath || `${this.dir}plc_bundles.json`;
   }
 
   /**
-   * Load and cache the bundle index
+   * Load the bundle index from disk.
+   * 
+   * The index is cached in memory after first load. Use `refresh` parameter
+   * to force reloading from disk.
+   * 
+   * @param refresh - If true, reload from disk even if cached (default: false)
+   * @returns Promise resolving to the bundle index
+   * @throws Error if index file cannot be read or parsed
+   * 
+   * @example
+   * ```ts
+   * // Load index (uses cache if available)
+   * const index = await bundle.loadIndex();
+   * 
+   * // Force reload from disk
+   * const freshIndex = await bundle.loadIndex(true);
+   * ```
    */
   async loadIndex(refresh = false): Promise<BundleIndex> {
     if (!refresh && this.cachedIndex) {
···
   }
 
   /**
-   * Save the bundle index
+   * Save a bundle index to disk.
+   * 
+   * Writes the index as formatted JSON and updates the in-memory cache.
+   * The index is written atomically using Bun's file API.
+   * 
+   * @param index - The bundle index to save
+   * @returns Promise that resolves when save is complete
+   * 
+   * @example
+   * ```ts
+   * const index = await bundle.loadIndex();
+   * index.last_bundle = 150;
+   * await bundle.saveIndex(index);
+   * ```
    */
   async saveIndex(index: BundleIndex): Promise<void> {
     await Bun.write(this.indexPath, JSON.stringify(index, null, 2));
···
   }
 
   /**
-   * Get metadata for a specific bundle
+   * Get metadata for a specific bundle.
+   * 
+   * @param bundleNum - The bundle number to retrieve metadata for
+   * @returns Promise resolving to bundle metadata, or undefined if not found
+   * 
+   * @example
+   * ```ts
+   * const metadata = await bundle.getMetadata(42);
+   * if (metadata) {
+   *   console.log(`Bundle ${metadata.bundle_number} has ${metadata.operation_count} operations`);
+   * }
+   * ```
    */
   async getMetadata(bundleNum: number): Promise<BundleMetadata | undefined> {
     const index = await this.loadIndex();
···
   }
 
   /**
-   * Get bundle file path
+   * Get the file path for a specific bundle.
+   * 
+   * Bundles are named with zero-padded 6-digit numbers (e.g., `000042.jsonl.zst`).
+   * 
+   * @param bundleNum - The bundle number
+   * @returns Full path to the bundle file
+   * 
+   * @example
+   * ```ts
+   * const path = bundle.getBundlePath(42);
+   * // Returns: "./bundles/000042.jsonl.zst"
+   * ```
    */
   getBundlePath(bundleNum: number): string {
     return `${this.dir}${bundleNum.toString().padStart(6, '0')}.jsonl.zst`;
   }
 
   /**
-   * Read and decompress a bundle
+   * Read and decompress a bundle file.
+   * 
+   * Uses Bun's native zstd decompression for optimal performance.
+   * 
+   * @param bundleNum - The bundle number to read
+   * @returns Promise resolving to the decompressed JSONL content as a string
+   * @throws Error if bundle file cannot be read or decompressed
+   * 
+   * @example
+   * ```ts
+   * const jsonl = await bundle.readBundle(1);
+   * console.log(`Bundle size: ${jsonl.length} bytes`);
+   * ```
    */
   async readBundle(bundleNum: number): Promise<string> {
     const path = this.getBundlePath(bundleNum);
···
   }
 
   /**
-   * Parse operations from bundle content
+   * Parse operations from JSONL content.
+   * 
+   * @param content - JSONL string with one operation per line
+   * @returns Array of parsed operations
+   * 
+   * @example
+   * ```ts
+   * const jsonl = await bundle.readBundle(1);
+   * const operations = bundle.parseOperations(jsonl);
+   * console.log(`Parsed ${operations.length} operations`);
+   * ```
    */
   parseOperations(content: string): Operation[] {
     return content
···
   }
 
   /**
-   * Stream operations from a bundle (memory efficient)
+   * Stream operations from a bundle (memory efficient).
+   * 
+   * This async generator yields operations one at a time, which is more
+   * memory efficient than loading all operations at once.
+   * 
+   * @param bundleNum - The bundle number to stream from
+   * @yields Operations from the bundle
+   * 
+   * @example
+   * ```ts
+   * for await (const op of bundle.streamOperations(1)) {
+   *   console.log(op.did);
+   *   if (someCondition) break; // Can stop early
+   * }
+   * ```
    */
   async *streamOperations(bundleNum: number): AsyncGenerator<Operation> {
     const content = await this.readBundle(bundleNum);
···
   }
 
   /**
-   * Process multiple bundles with a callback (supports multi-threading)
+   * Process multiple bundles with a callback function.
+   * 
+   * Supports both single-threaded and multi-threaded processing via {@link ProcessOptions}.
+   * Operations are processed in chronological order.
+   * 
+   * @param start - First bundle number to process (inclusive)
+   * @param end - Last bundle number to process (inclusive)
+   * @param callback - Function called for each operation
+   * @param options - Processing options (threads, progress callback)
+   * @returns Promise resolving to processing statistics
+   * 
+   * @example Single-threaded
+   * ```ts
+   * await bundle.processBundles(1, 10, (op, pos, num) => {
+   *   console.log(`Bundle ${num}, pos ${pos}: ${op.did}`);
+   * });
+   * ```
+   * 
+   * @example Multi-threaded with progress
+   * ```ts
+   * await bundle.processBundles(1, 100, (op) => {
+   *   // Process operation
+   * }, {
+   *   threads: 4,
+   *   onProgress: (stats) => {
+   *     console.log(`Processed ${stats.totalOps} operations`);
+   *   }
+   * });
+   * ```
    */
   async processBundles(
     start: number,
···
   }
 
   /**
-   * Clone bundles from a remote repository
+   * Clone bundles from a remote repository.
+   * 
+   * Downloads bundles via HTTP, verifies hashes, and saves progress periodically.
+   * Supports resuming interrupted downloads - bundles that already exist and
+   * pass verification will be skipped.
+   * 
+   * Progress is automatically saved every 5 seconds and on completion.
+   * 
+   * @param remoteUrl - Base URL of the remote bundle repository
+   * @param options - Clone options (bundles, threads, verification, callbacks)
+   * @returns Promise resolving to clone statistics
+   * @throws Error if remote is unreachable or bundle range is invalid
+   * 
+   * @example Clone all bundles
+   * ```ts
+   * await bundle.clone('https://plcbundle.atscan.net', {
+   *   threads: 8,
+   *   verify: true
+   * });
+   * ```
+   * 
+   * @example Clone specific range with progress
+   * ```ts
+   * await bundle.clone('https://plcbundle.atscan.net', {
+   *   bundles: '1-100',
+   *   threads: 4,
+   *   onProgress: (stats) => {
+   *     const pct = (stats.downloadedBytes / stats.totalBytes * 100).toFixed(1);
+   *     console.log(`${pct}% complete`);
+   *   }
+   * });
+   * ```
+   * 
+   * @example Resume interrupted download
+   * ```ts
+   * // First run - interrupted
+   * await bundle.clone('https://plcbundle.atscan.net', { bundles: '1-1000' });
+   * 
+   * // Second run - automatically resumes
+   * await bundle.clone('https://plcbundle.atscan.net', { bundles: '1-1000' });
+   * ```
    */
   async clone(
     remoteUrl: string,
···
   }
 
   /**
-   * Verify bundle integrity
+   * Verify the integrity of a bundle.
+   * 
+   * Checks both the compressed file hash and the content hash against
+   * the values stored in the bundle index.
+   * 
+   * Uses Bun's native SHA-256 hasher for optimal performance.
+   * 
+   * @param bundleNum - The bundle number to verify
+   * @returns Promise resolving to verification result
+   * 
+   * @example
+   * ```ts
+   * const result = await bundle.verifyBundle(42);
+   * if (result.valid) {
+   *   console.log('Bundle is valid');
+   * } else {
+   *   console.error('Verification failed:');
+   *   result.errors.forEach(err => console.error(`  - ${err}`));
+   * }
+   * ```
    */
   async verifyBundle(bundleNum: number): Promise<{ valid: boolean; errors: string[] }> {
     const metadata = await this.getMetadata(bundleNum);
···
   }
 
   /**
-   * Calculate chain hash
+   * Calculate a chain hash linking bundles together.
+   * 
+   * The chain hash ensures bundles form an unbroken chain and haven't
+   * been tampered with. Genesis bundles use a special hash format.
+   * 
+   * @param parentHash - Hash of the parent bundle (empty for genesis)
+   * @param contentHash - Hash of this bundle's content
+   * @param isGenesis - Whether this is the first bundle in the chain
+   * @returns The calculated chain hash as a hex string
+   * 
+   * @example
+   * ```ts
+   * // Genesis bundle
+   * const genesisHash = bundle.calculateChainHash('', contentHash, true);
+   * 
+   * // Subsequent bundle
+   * const chainHash = bundle.calculateChainHash(parentHash, contentHash, false);
+   * ```
    */
   calculateChainHash(parentHash: string, contentHash: string, isGenesis: boolean): string {
     const input = isGenesis 
···
   }
 
   /**
-   * Get bundle statistics
+   * Get repository statistics.
+   * 
+   * Provides a quick overview of the bundle repository without loading
+   * all bundle metadata.
+   * 
+   * @returns Promise resolving to repository statistics
+   * 
+   * @example
+   * ```ts
+   * const stats = await bundle.getStats();
+   * console.log(`Version: ${stats.version}`);
+   * console.log(`Bundles: ${stats.totalBundles}`);
+   * console.log(`Size: ${(stats.totalSize / 1e9).toFixed(2)} GB`);
+   * console.log(`Updated: ${stats.updatedAt}`);
+   * ```
    */
   async getStats(): Promise<{
     version: string;

src/types.ts

···
+/**
+ * Type definitions for plcbundle library
+ * 
+ * This module contains all TypeScript type definitions used throughout
+ * the plcbundle library.
+ * 
+ * @module
+ */
+
+/**
+ * Metadata for a single bundle in the repository.
+ * 
+ * Contains information about the bundle's contents, hashes for verification,
+ * and temporal boundaries.
+ */
 export interface BundleMetadata {
+  /** Sequential number identifying this bundle (e.g., 1, 2, 3...) */
   bundle_number: number;
+  
+  /** ISO 8601 timestamp of the first operation in this bundle */
   start_time: string;
+  
+  /** ISO 8601 timestamp of the last operation in this bundle */
   end_time: string;
+  
+  /** Total number of PLC operations contained in this bundle */
   operation_count: number;
+  
+  /** Number of unique DIDs referenced in this bundle */
   did_count: number;
+  
+  /** Chain hash linking this bundle to its predecessor */
   hash: string;
+  
+  /** SHA-256 hash of the uncompressed JSONL content */
   content_hash: string;
+  
+  /** Chain hash of the previous bundle (empty string for genesis bundle) */
   parent: string;
+  
+  /** SHA-256 hash of the compressed .jsonl.zst file */
   compressed_hash: string;
+  
+  /** Size of the compressed bundle file in bytes */
   compressed_size: number;
+  
+  /** Size of the uncompressed JSONL content in bytes */
   uncompressed_size: number;
+  
+  /** Cursor for fetching subsequent operations (end_time of previous bundle) */
   cursor: string;
+  
+  /** ISO 8601 timestamp when this bundle was created */
   created_at: string;
 }
 
+/**
+ * Index file containing metadata for all bundles in a repository.
+ * 
+ * This is the main entry point for discovering available bundles.
+ * Located at `plc_bundles.json` in the repository root.
+ */
 export interface BundleIndex {
+  /** Version of the index format (currently "1.0") */
   version: string;
+  
+  /** Bundle number of the most recent bundle */
   last_bundle: number;
+  
+  /** ISO 8601 timestamp when the index was last updated */
   updated_at: string;
+  
+  /** Total size of all compressed bundles in bytes */
   total_size_bytes: number;
+  
+  /** Array of metadata for each bundle, sorted by bundle_number */
   bundles: BundleMetadata[];
 }
 
+/**
+ * A single PLC operation as stored in bundles.
+ * 
+ * Operations represent changes to DID documents in the PLC directory.
+ */
 export interface Operation {
+  /** Decentralized Identifier (DID) this operation applies to */
   did: string;
+  
+  /** Content Identifier (CID) of this operation */
   cid: string;
+  
+  /** The actual operation data containing DID document changes */
   operation: any;
+  
+  /** ISO 8601 timestamp when this operation was created */
   createdAt: string;
+  
+  /** Additional fields that may be present in operations */
   [key: string]: any;
 }
 
+/**
+ * Callback function called for each operation during processing.
+ * 
+ * @param op - The operation being processed
+ * @param position - Zero-based position of the operation within its bundle
+ * @param bundleNum - The bundle number being processed
+ * 
+ * @example
+ * ```ts
+ * const callback: ProcessCallback = (op, position, bundleNum) => {
+ *   if (op.did.startsWith('did:plc:test')) {
+ *     console.log(`Found test DID at bundle ${bundleNum}, position ${position}`);
+ *   }
+ * };
+ * ```
+ */
 export type ProcessCallback = (
   op: Operation,
   position: number,
   bundleNum: number
 ) => void | Promise<void>;
 
+/**
+ * Statistics collected during bundle processing.
+ * 
+ * Tracks the number of operations and bytes processed.
+ */
 export interface ProcessStats {
+  /** Total number of operations processed */
   totalOps: number;
+  
+  /** Number of operations that matched criteria (if applicable) */
   matchCount: number;
+  
+  /** Total bytes of operation data processed */
   totalBytes: number;
+  
+  /** Bytes of data for matched operations (if applicable) */
   matchedBytes: number;
 }
 
+/**
+ * Options for processing bundles.
+ * 
+ * Allows customization of parallel processing and progress reporting.
+ */
 export interface ProcessOptions {
+  /** Number of worker threads to use for parallel processing (default: 1) */
   threads?: number;
+  
+  /**
+   * Callback invoked periodically to report processing progress.
+   * Called approximately every 10,000 operations.
+   * 
+   * @param stats - Current processing statistics
+   */
   onProgress?: (stats: ProcessStats) => void;
 }
 
+/**
+ * Options for cloning bundles from a remote repository.
+ * 
+ * Controls download behavior, verification, and progress reporting.
+ */
 export interface CloneOptions {
+  /** Number of parallel download threads (default: 4) */
   threads?: number;
+  
+  /**
+   * Bundle selection specification.
+   * 
+   * Can be:
+   * - A single bundle number: `"42"`
+   * - A range: `"1-100"`
+   * - Undefined to clone all available bundles
+   */
   bundles?: string;
+  
+  /** Whether to verify SHA-256 hashes of downloaded bundles (default: true) */
   verify?: boolean;
+  
+  /**
+   * Function to check if cloning should stop (for graceful shutdown).
+   * 
+   * @returns `true` if cloning should stop, `false` to continue
+   */
   shouldStop?: () => boolean;
+  
+  /**
+   * Callback invoked to report download progress.
+   * 
+   * @param stats - Current download statistics
+   */
   onProgress?: (stats: CloneStats) => void;
 }
 
+/**
+ * Statistics collected during bundle cloning.
+ * 
+ * Tracks download progress, including successes, skips, and failures.
+ */
 export interface CloneStats {
+  /** Total number of bundles to download */
   totalBundles: number;
+  
+  /** Number of bundles successfully downloaded in this session */
   downloadedBundles: number;
+  
+  /** Number of bundles skipped (already existed and verified) */
   skippedBundles: number;
+  
+  /** Number of bundles that failed to download */
   failedBundles: number;
+  
+  /** Total bytes to download across all bundles */
   totalBytes: number;
+  
+  /** Bytes downloaded so far (including skipped bundles) */
   downloadedBytes: number;
 }