@gmod/bam 7.1.19 → 7.1.21

package/src/record.ts

@@ -17,6 +17,8 @@ const ASCII_CIGAR_CODES = [
   77, 73, 68, 78, 83, 72, 80, 61, 88, 63, 63, 63, 63, 63, 63, 63,
 ]
 
+const textDecoder = new TextDecoder()
+
 // Bitmask for ops that consume ref: M=0, D=2, N=3, P=6, ==7, X=8
 // Binary: 0b111001101 = 0x1CD
 const CIGAR_CONSUMES_REF_MASK = 0x1cd
@@ -27,55 +29,42 @@ export interface Bytes {
   byteArray: Uint8Array
 }
 
-interface CIGAR_AND_LENGTH {
-  length_on_ref: number
-  NUMERIC_CIGAR: Uint32Array | number[]
-}
-
 export default class BamRecord {
   public fileOffset: number
-  private bytes: Bytes
+  private _byteArray: Uint8Array
+  private _start: number
+  private _end: number
   private _dataView: DataView
 
-  private _cachedFlags?: number
-  private _cachedRefId?: number
-  private _cachedStart?: number
   private _cachedEnd?: number
   private _cachedTags?: Record<string, unknown>
-  private _cachedCigarAndLength?: CIGAR_AND_LENGTH
+  private _cachedLengthOnRef?: number
+  private _cachedNumericCigar?: Uint32Array | number[]
   private _cachedNUMERIC_MD?: Uint8Array | null
   private _cachedTagsStart?: number
 
-  constructor(args: { bytes: Bytes; fileOffset: number }) {
-    this.bytes = args.bytes
+  constructor(args: { bytes: Bytes; fileOffset: number; dataView: DataView }) {
+    this._byteArray = args.bytes.byteArray
+    this._start = args.bytes.start
+    this._end = args.bytes.end
     this.fileOffset = args.fileOffset
-    this._dataView = new DataView(this.bytes.byteArray.buffer)
+    this._dataView = args.dataView
   }
 
   get byteArray() {
-    return this.bytes.byteArray
+    return this._byteArray
   }
 
   get flags() {
-    if (this._cachedFlags === undefined) {
-      this._cachedFlags =
-        (this._dataView.getInt32(this.bytes.start + 16, true) & 0xffff0000) >>
-        16
-    }
-    return this._cachedFlags
+    return (this._dataView.getInt32(this._start + 16, true) & 0xffff0000) >> 16
   }
+
   get ref_id() {
-    if (this._cachedRefId === undefined) {
-      this._cachedRefId = this._dataView.getInt32(this.bytes.start + 4, true)
-    }
-    return this._cachedRefId
+    return this._dataView.getInt32(this._start + 4, true)
   }
 
   get start() {
-    if (this._cachedStart === undefined) {
-      this._cachedStart = this._dataView.getInt32(this.bytes.start + 8, true)
-    }
-    return this._cachedStart
+    return this._dataView.getInt32(this._start + 8, true)
   }
 
   get end() {
@@ -98,12 +87,13 @@ export default class BamRecord {
     if (this.isSegmentUnmapped()) {
       return null
     } else {
+      const seqLen = this.seq_length
       const p =
         this.b0 +
         this.read_name_length +
         this.num_cigar_bytes +
-        this.num_seq_bytes
-      return this.byteArray.subarray(p, p + this.seq_length)
+        ((seqLen + 1) >> 1)
+      return this._byteArray.subarray(p, p + seqLen)
     }
   }
 
@@ -112,25 +102,27 @@ export default class BamRecord {
   }
 
   get b0() {
-    return this.bytes.start + 36
+    return this._start + 36
   }
 
   get tagsStart() {
     if (this._cachedTagsStart === undefined) {
+      const seqLen = this.seq_length
       this._cachedTagsStart =
         this.b0 +
         this.read_name_length +
         this.num_cigar_bytes +
-        this.num_seq_bytes +
-        this.seq_length
+        ((seqLen + 1) >> 1) +
+        seqLen
     }
     return this._cachedTagsStart
   }
+
   // batch fromCharCode: fastest for typical name lengths (see benchmarks/string-building.bench.ts)
   get name() {
     const len = this.read_name_length - 1
     const start = this.b0
-    const ba = this.byteArray
+    const ba = this._byteArray
     const codes = new Array(len)
     for (let i = 0; i < len; i++) {
       codes[i] = ba[start + i]!
@@ -170,12 +162,12 @@ export default class BamRecord {
 
     let p = this.tagsStart
 
-    const blockEnd = this.bytes.end
-    const ba = this.byteArray
+    const blockEnd = this._end
+    const ba = this._byteArray
     while (p < blockEnd) {
-      const currentTag1 = ba[p]!
-      const currentTag2 = ba[p + 1]!
-      const type = ba[p + 2]!
+      const currentTag1 = ba[p]
+      const currentTag2 = ba[p + 1]
+      const type = ba[p + 2]
       p += 3
 
       const isMatch = currentTag1 === tag1 && currentTag2 === tag2
@@ -232,26 +224,21 @@ export default class BamRecord {
         case 0x5a: // 'Z'
         case 0x48: {
           // 'H'
+          const start = p
+          while (p < blockEnd && ba[p] !== 0) {
+            p++
+          }
           if (isMatch) {
-            const start = p
-            while (p < blockEnd && ba[p] !== 0) {
-              p++
-            }
-            if (raw) {
-              return ba.subarray(start, p)
-            }
-            const value = []
-            for (let i = start; i < p; i++) {
-              value.push(String.fromCharCode(ba[i]!))
-            }
-            return value.join('')
+            return raw
+              ? ba.subarray(start, p)
+              : textDecoder.decode(ba.subarray(start, p))
           }
-          while (p <= blockEnd && ba[p++] !== 0) {}
+          p++ // advance past null terminator
           break
         }
         case 0x42: {
           // 'B'
-          const Btype = ba[p++]!
+          const Btype = ba[p++]
           const limit = this._dataView.getInt32(p, true)
           p += 4
           const absOffset = ba.byteOffset + p
@@ -331,9 +318,9 @@ export default class BamRecord {
   private _computeTags() {
     let p = this.tagsStart
 
-    const blockEnd = this.bytes.end
-    const ba = this.byteArray
-    const tags = {} as Record<string, unknown>
+    const blockEnd = this._end
+    const ba = this._byteArray
+    const tags: Record<string, unknown> = {}
     while (p < blockEnd) {
       const tag = String.fromCharCode(ba[p]!, ba[p + 1]!)
       const type = ba[p + 2]!
@@ -375,21 +362,17 @@ export default class BamRecord {
         case 0x5a: // 'Z'
         case 0x48: {
           // 'H'
-          const value = []
-          while (p <= blockEnd) {
-            const cc = ba[p++]!
-            if (cc !== 0) {
-              value.push(String.fromCharCode(cc))
-            } else {
-              break
-            }
+          const start = p
+          while (p < blockEnd && ba[p] !== 0) {
+            p++
           }
-          tags[tag] = value.join('')
+          tags[tag] = textDecoder.decode(ba.subarray(start, p))
+          p++ // advance past null terminator
           break
         }
         case 0x42: {
           // 'B'
-          const Btype = ba[p++]!
+          const Btype = ba[p++]
           const limit = this._dataView.getInt32(p, true)
           p += 4
           const absOffset = ba.byteOffset + p
@@ -520,13 +503,6 @@ export default class BamRecord {
     return !!(this.flags & Constants.BAM_FSUPPLEMENTARY)
   }
 
-  get cigarAndLength() {
-    if (this._cachedCigarAndLength === undefined) {
-      this._cachedCigarAndLength = this._computeCigarAndLength()
-    }
-    return this._cachedCigarAndLength
-  }
-
   // Benchmark results for CIGAR parsing strategies (see benchmarks/cigar-lifecycle.bench.ts):
   //
   // Aligned data:
@@ -545,78 +521,94 @@ export default class BamRecord {
   //
   // Strategy: use plain array with |0 for small aligned (≤50 ops) and all unaligned,
   // Uint32Array view only for large aligned CIGARs.
-  private _computeCigarAndLength() {
-    if (this.isSegmentUnmapped()) {
-      return {
-        length_on_ref: 0,
-        NUMERIC_CIGAR: new Uint32Array(0),
-      }
+
+  // CG tag pattern: first op is soft-clip consuming entire sequence, second op is N encoding length-on-ref
+  private _isCGTagPattern(p: number) {
+    const cigop = this._dataView.getInt32(p, true)
+    return (cigop & 0xf) === CIGAR_SOFT_CLIP && cigop >> 4 === this.seq_length
+  }
+
+  private _computeLengthOnRef(): number {
+    const flag_nc = this._dataView.getInt32(this._start + 16, true)
+    if (flag_nc & (Constants.BAM_FUNMAP << 16)) {
+      return 0
     }
 
-    const numCigarOps = this.num_cigar_ops
-    let p = this.b0 + this.read_name_length
+    const numCigarOps = flag_nc & 0xffff
+    const p = this.b0 + this.read_name_length
 
-    // check for CG tag by inspecting whether the CIGAR field contains a clip
-    // that consumes entire seqLen
-    const cigop = this._dataView.getInt32(p, true)
-    const lop = cigop >> 4
-    const op = cigop & 0xf
-    if (op === CIGAR_SOFT_CLIP && lop === this.seq_length) {
-      // if there is a CG the second CIGAR field will be a N tag the represents
-      // the length on ref
-      p += 4
-      const cigop = this._dataView.getInt32(p, true)
-      const lop = cigop >> 4
-      const op = cigop & 0xf
-      if (op !== CIGAR_REF_SKIP) {
+    if (this._isCGTagPattern(p)) {
+      const cigop2 = this._dataView.getInt32(p + 4, true)
+      if ((cigop2 & 0xf) !== CIGAR_REF_SKIP) {
         console.warn('CG tag with no N tag')
       }
-      const cgArray = this.tags.CG as Uint32Array
-      return {
-        NUMERIC_CIGAR: cgArray,
-        length_on_ref: lop,
-      }
+      return cigop2 >> 4
     }
 
-    const absOffset = this.byteArray.byteOffset + p
-    const isAligned = absOffset % 4 === 0
-
-    if (isAligned && numCigarOps > 50) {
+    const absOffset = this._byteArray.byteOffset + p
+    if (absOffset % 4 === 0 && numCigarOps > 50) {
       const cigarView = new Uint32Array(
-        this.byteArray.buffer,
+        this._byteArray.buffer,
         absOffset,
         numCigarOps,
       )
+      this._cachedNumericCigar = cigarView
       let lref = 0
       for (let c = 0; c < numCigarOps; ++c) {
-        const cigop = cigarView[c]!
-        lref += (cigop >> 4) * ((CIGAR_CONSUMES_REF_MASK >> (cigop & 0xf)) & 1)
-      }
-      return {
-        NUMERIC_CIGAR: cigarView,
-        length_on_ref: lref,
+        const co = cigarView[c]!
+        lref += (co >> 4) * ((CIGAR_CONSUMES_REF_MASK >> (co & 0xf)) & 1)
       }
+      return lref
     }
 
-    const cigarArray: number[] = new Array(numCigarOps)
     let lref = 0
     for (let c = 0; c < numCigarOps; ++c) {
-      const cigop = this._dataView.getInt32(p + c * 4, true) | 0
-      cigarArray[c] = cigop
-      lref += (cigop >> 4) * ((CIGAR_CONSUMES_REF_MASK >> (cigop & 0xf)) & 1)
+      const co = this._dataView.getInt32(p + c * 4, true)
+      lref += (co >> 4) * ((CIGAR_CONSUMES_REF_MASK >> (co & 0xf)) & 1)
     }
-    return {
-      NUMERIC_CIGAR: cigarArray,
-      length_on_ref: lref,
+    return lref
+  }
+
+  private _computeNumericCigar(): Uint32Array | number[] {
+    const flag_nc = this._dataView.getInt32(this._start + 16, true)
+    if (flag_nc & (Constants.BAM_FUNMAP << 16)) {
+      return new Uint32Array(0)
     }
+
+    const numCigarOps = flag_nc & 0xffff
+    const p = this.b0 + this.read_name_length
+
+    if (this._isCGTagPattern(p)) {
+      return (
+        (this.tags.CG as Uint32Array | number[] | undefined) ??
+        new Uint32Array(0)
+      )
+    }
+
+    const absOffset = this._byteArray.byteOffset + p
+    if (absOffset % 4 === 0 && numCigarOps > 50) {
+      return new Uint32Array(this._byteArray.buffer, absOffset, numCigarOps)
+    }
+
+    const cigarArray: number[] = new Array(numCigarOps)
+    for (let c = 0; c < numCigarOps; ++c) {
+      cigarArray[c] = this._dataView.getInt32(p + c * 4, true) | 0
+    }
+    return cigarArray
   }
 
   get length_on_ref() {
-    return this.cigarAndLength.length_on_ref
+    if (this._cachedLengthOnRef === undefined) {
+      this._cachedLengthOnRef = this._computeLengthOnRef()
+    }
+    return this._cachedLengthOnRef
   }
 
   get NUMERIC_CIGAR() {
-    return this.cigarAndLength.NUMERIC_CIGAR
+    if (this._cachedNumericCigar === undefined) {
+      this._cachedNumericCigar = this._computeNumericCigar()
+    }
+    return this._cachedNumericCigar
   }
 
   get CIGAR() {
@@ -649,35 +641,40 @@ export default class BamRecord {
 
   get NUMERIC_SEQ() {
     const p = this.b0 + this.read_name_length + this.num_cigar_bytes
-    return this.byteArray.subarray(p, p + this.num_seq_bytes)
+    return this._byteArray.subarray(p, p + this.num_seq_bytes)
   }
 
   get seq() {
-    const numeric = this.NUMERIC_SEQ
     const len = this.seq_length
+    const seqStart = this.b0 + this.read_name_length + this.num_cigar_bytes
+    const numeric = this._byteArray
     const buf = new Array(len)
     let i = 0
     const fullBytes = len >> 1
 
     for (let j = 0; j < fullBytes; ++j) {
-      const sb = numeric[j]!
-      buf[i++] = SEQRET_DECODER[(sb & 0xf0) >> 4]
-      buf[i++] = SEQRET_DECODER[sb & 0x0f]
+      const sb = numeric[seqStart + j]!
+      buf[i++] = SEQRET_DECODER[(sb & 0xf0) >> 4]!
+      buf[i++] = SEQRET_DECODER[sb & 0x0f]!
     }
 
     if (i < len) {
-      const sb = numeric[fullBytes]!
-      buf[i] = SEQRET_DECODER[(sb & 0xf0) >> 4]
+      const sb = numeric[seqStart + fullBytes]!
+      buf[i] = SEQRET_DECODER[(sb & 0xf0) >> 4]!
     }
 
     return buf.join('')
   }
 
   // adapted from igv.js
-  // uses precomputed lookup table indexed by flag bits + isize sign
+  // uses precomputed lookup table indexed by flag bits + isize sign.
+  // the BAM spec defines tlen as positive for the leftmost segment and
+  // negative for the rightmost, so tlen > 0 reliably indicates which
+  // read comes first without needing position-based correction
+  // (see also: gmod/cram-js src/cramFile/record.ts getPairOrientation)
   get pair_orientation() {
     const f = this.flags
-    // combined check: unmapped (0x4) clear, mate unmapped (0x8) clear
+    // unmapped (0x4) or mate unmapped (0x8) -> undefined
     if (f & 0xc || this.ref_id !== this.next_refid) {
       return undefined
     }
@@ -687,52 +684,52 @@ export default class BamRecord {
   }
 
   get bin_mq_nl() {
-    return this._dataView.getInt32(this.bytes.start + 12, true)
+    return this._dataView.getInt32(this._start + 12, true)
   }
 
   get flag_nc() {
-    return this._dataView.getInt32(this.bytes.start + 16, true)
+    return this._dataView.getInt32(this._start + 16, true)
   }
 
   get seq_length() {
-    return this._dataView.getInt32(this.bytes.start + 20, true)
+    return this._dataView.getInt32(this._start + 20, true)
   }
 
   get next_refid() {
-    return this._dataView.getInt32(this.bytes.start + 24, true)
+    return this._dataView.getInt32(this._start + 24, true)
   }
 
   get next_pos() {
-    return this._dataView.getInt32(this.bytes.start + 28, true)
+    return this._dataView.getInt32(this._start + 28, true)
   }
 
   get template_length() {
-    return this._dataView.getInt32(this.bytes.start + 32, true)
+    return this._dataView.getInt32(this._start + 32, true)
   }
 
   seqAt(idx: number): string | undefined {
     if (idx < this.seq_length) {
       const byteIndex = idx >> 1
       const sb =
-        this.byteArray[
+        this._byteArray[
           this.b0 + this.read_name_length + this.num_cigar_bytes + byteIndex
         ]!
 
       return idx % 2 === 0
-        ? SEQRET_DECODER[(sb & 0xf0) >> 4]
-        : SEQRET_DECODER[sb & 0x0f]
+        ? SEQRET_DECODER[(sb & 0xf0) >> 4]!
+        : SEQRET_DECODER[sb & 0x0f]!
     } else {
       return undefined
     }
   }
 
   toJSON() {
-    const data: Record<string, any> = {}
+    const data: Record<string, unknown> = {}
     for (const k of Object.keys(this)) {
-      if (k.startsWith('_') || k === 'bytes') {
+      if (k.startsWith('_')) {
         continue
       }
-      // @ts-ignore
+      // @ts-expect-error
       data[k] = this[k]
     }
 

package/src/util.ts

@@ -1,6 +1,7 @@
-import Chunk from './chunk.ts'
 import { longFromBytesToUnsigned } from './long.ts'
-import { Offset, VirtualOffset } from './virtualOffset.ts'
+
+import type Chunk from './chunk.ts'
+import type { Offset, VirtualOffset } from './virtualOffset.ts'
 
 export function canMergeBlocks(chunk1: Chunk, chunk2: Chunk) {
   return (
@@ -33,7 +34,7 @@ export interface BaseOpts {
 }
 
 export function makeOpts(obj: AbortSignal | BaseOpts = {}): BaseOpts {
-  return 'aborted' in obj ? ({ signal: obj } as BaseOpts) : obj
+  return 'aborted' in obj ? { signal: obj } : obj
 }
 
 export function optimizeChunks(chunks: Chunk[], lowest?: Offset) {
@@ -126,23 +127,22 @@ export function parseNameBytes(
   namesBytes: Uint8Array,
   renameRefSeq: (arg: string) => string = s => s,
 ) {
+  const decoder = new TextDecoder()
   let currRefId = 0
   let currNameStart = 0
-  const refIdToName = []
+  const refIdToName: string[] = []
   const refNameToId: Record<string, number> = {}
-  for (let i = 0; i < namesBytes.length; i += 1) {
+  for (let i = 0; i < namesBytes.length; i++) {
     if (!namesBytes[i]) {
       if (currNameStart < i) {
-        let refName = ''
-        for (let j = currNameStart; j < i; j++) {
-          refName += String.fromCharCode(namesBytes[j]!)
-        }
-        refName = renameRefSeq(refName)
+        const refName = renameRefSeq(
+          decoder.decode(namesBytes.subarray(currNameStart, i)),
+        )
         refIdToName[currRefId] = refName
         refNameToId[refName] = currRefId
       }
       currNameStart = i + 1
-      currRefId += 1
+      currRefId++
     }
   }
   return { refNameToId, refIdToName }