Genotype API Documentation - v0.1.0
    Preparing search index...

    Class BAMParser

    Streaming BAM parser with BGZF decompression and binary decoding

    Designed for memory efficiency with large BAM files from modern sequencers. Handles real-world BAM complexity including:

    • Long reads from PacBio/Oxford Nanopore (>100kb sequences)
    • Large CIGAR strings with complex operations
    • Comprehensive optional tag support
    • BGZF block-level error recovery
    const parser = new BAMParser();
    for await (const record of parser.parseFile('alignments.bam')) {
      if (record.format === 'bam') {
        console.log(`${record.qname} -> ${record.rname}:${record.pos}`);
      }
    }

    const parser = new BAMParser({
      skipValidation: false,
      trackLineNumbers: true,
      onError: (error) => console.error(`BAM error: ${error}`)
    });

    Hierarchy

    Index

    Constructors

    constructor

    Methods

    parseFile parse parseString getParsingStats createOptimized loadIndex queryRegion setReferenceNames getIndexStatistics validateIndex closeIndex

    Constructors

    • Create a new BAM parser with specified options and interrupt support

      Parameters

      • options: BamParserOptions = {}

        BAM parser configuration options including AbortSignal

      Returns BAMParser

    Methods

    • Parse BAM records from a file using Bun's optimized file I/O

      Parameters

      • filePath: string

        Path to BAM file to parse

      • Optionaloptions: FileReaderOptions

        File reading options for performance tuning

      Returns AsyncIterable<SAMHeader | BAMAlignment>

      BAMAlignment or SAMHeader objects as they are parsed from the file

      When BAM format is invalid

      When BGZF decompression fails

      const parser = new BAMParser();
      for await (const record of parser.parseFile('/path/to/alignments.bam')) {
        if (record.format === 'bam') {
          console.log(`${record.qname} -> ${record.rname}:${record.pos}`);
        }
      }

    • Parse BAM records from a binary stream with optimized BGZF handling

      Parameters

      • stream: ReadableStream<Uint8Array<ArrayBufferLike>>

        ReadableStream of binary BAM data

      Returns AsyncIterable<SAMHeader | BAMAlignment>

      BAMAlignment or SAMHeader objects as they are parsed

      When BAM format is invalid

      When BGZF decompression fails

    • Parse BAM records from a binary string (base64 or hex encoded)

      Parameters

      • data: string

        String containing binary BAM data (base64 or hex encoded)

      Returns AsyncIterable<SAMHeader | BAMAlignment>

      BAMAlignment or SAMHeader objects as they are parsed

      When BAM format is invalid or string encoding is unsupported

      const parser = new BAMParser();
      // Base64 encoded BAM data
      const bamData = "QkFNAQAAAAA..."; // base64 encoded BAM
      for await (const record of parser.parseString(bamData)) {
        if (record.format === 'bam') {
          console.log(`${record.qname} -> ${record.rname}:${record.pos}`);
        }
      }

    • Get parsing statistics for performance monitoring

      Returns {
          runtime: "node" | "deno" | "bun" | "unknown";
          bunOptimized: boolean;
          memoryEfficient: boolean;
          recommendedBufferSize: number;
      }

      Statistics object with performance metrics

    • Create a performance-optimized BAM parser instance

      Parameters

      • Optionaloptions: { bufferSize?: number; skipValidation?: boolean; enableWarnings?: boolean }

        Performance tuning options

      Returns BAMParser

      Optimized parser instance

    • Load BAI index file for indexed access to BAM data

      Parameters

      • baiFilePath: string

        Path to BAI index file

      • Optionaloptions: BAIReaderOptions

        BAI reader options

      Returns Promise<void>

      Promise resolving when index is loaded

      If index file cannot be loaded

      const parser = new BAMParser();
      await parser.loadIndex('/path/to/file.bam.bai');

      // Now can perform indexed queries
      for await (const alignment of parser.queryRegion('chr1', 1000, 2000)) {
        console.log(`${alignment.qname} -> ${alignment.rname}:${alignment.pos}`);
      }

    • Query genomic region using loaded BAI index

      Parameters

      • referenceName: string

        Reference sequence name (e.g., 'chr1', '1')

      • start: number

        Start coordinate (1-based, inclusive)

      • end: number

        End coordinate (1-based, inclusive)

      Returns AsyncIterable<BAMAlignment>

      AsyncIterable of alignments in the specified region

      If index is not loaded or query fails

      const parser = new BAMParser();
      await parser.loadIndex('/path/to/file.bam.bai');

      for await (const alignment of parser.queryRegion('chr1', 1000, 2000)) {
        if (alignment.format === 'bam') {
          console.log(`Found alignment: ${alignment.qname} at ${alignment.pos}`);
        }
      }

    • Set reference sequence names for mapping reference IDs

      Parameters

      • names: string[]

        Array of reference sequence names in order

      Returns void

    • Validate loaded BAI index integrity

      Parameters

      • thorough: boolean = false

        Whether to perform thorough validation

      Returns Promise<{ isValid: boolean; warnings: string[]; errors: string[] }>

      Promise resolving to validation result

      If index is not loaded

    • Close BAI index and clean up resources

      Returns Promise<void>

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods