@gmod/cram 7.0.3 → 8.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmod/cram",
-  "version": "7.0.3",
+  "version": "8.0.1",
   "description": "read CRAM files with pure Javascript",
   "license": "MIT",
   "repository": "GMOD/cram-js",
@@ -29,6 +29,8 @@
   ],
   "scripts": {
     "test": "vitest",
+    "benchonly": "vitest bench",
+    "bench": "./scripts/build-both-branches.sh \"$BRANCH1\" \"$BRANCH2\" && vitest bench",
     "lint": "eslint --report-unused-disable-directives --max-warnings 0",
     "format": "prettier --write .",
     "docs": "documentation readme --shallow src/indexedCramFile.ts --section=IndexedCramFile; documentation readme --shallow src/cramFile/file.ts --section=CramFile; documentation readme --shallow src/craiIndex.ts --section=CraiIndex;  documentation readme --shallow src/cramFile/file.ts --section=CramFile; documentation readme --shallow src/cramFile/record.ts --section=CramRecord",
@@ -56,20 +58,20 @@
     "md5": "^2.2.1"
   },
   "devDependencies": {
-    "@gmod/indexedfasta": "^5.0.0",
+    "@gmod/indexedfasta": "^5.0.2",
     "@types/md5": "^2.3.2",
-    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/coverage-v8": "^4.0.18",
     "buffer": "^6.0.3",
     "documentation": "^14.0.3",
     "eslint": "^9.29.0",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-unicorn": "^62.0.0",
     "mock-fs": "^5.2.0",
-    "prettier": "^3.7.4",
+    "prettier": "^3.8.1",
     "rimraf": "^6.0.1",
     "typescript": "^5.7.0",
-    "typescript-eslint": "^8.49.0",
-    "vitest": "^4.0.15",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.0.18",
     "webpack": "^5.99.9",
     "webpack-cli": "^6.0.1"
   },

package/src/cramFile/codecs/beta.ts

@@ -1,5 +1,4 @@
-import CramCodec, { Cursors } from './_base.ts'
-import { getBits } from './getBits.ts'
+import CramCodec, { Cursor, Cursors } from './_base.ts'
 import { CramUnimplementedError } from '../../errors.ts'
 import { BetaEncoding } from '../encoding.ts'
 import { CramFileBlock } from '../file.ts'
@@ -24,11 +23,46 @@ export default class BetaCodec extends CramCodec<
     _blocksByContentId: Record<number, CramFileBlock>,
     cursors: Cursors,
   ) {
-    const fromBits = getBits(
+    return decodeBetaInline(
       coreDataBlock.content,
       cursors.coreBlock,
       this.parameters.length,
+      this.parameters.offset,
     )
-    return fromBits - this.parameters.offset
   }
 }
+
+/**
+ * Optimized beta decoder with inlined bit reading.
+ */
+function decodeBetaInline(
+  data: Uint8Array,
+  cursor: Cursor,
+  numBits: number,
+  offset: number,
+): number {
+  let { bytePosition, bitPosition } = cursor
+
+  // Fast path: reading exactly 8 bits when byte-aligned
+  if (numBits === 8 && bitPosition === 7) {
+    const val = data[bytePosition]!
+    cursor.bytePosition = bytePosition + 1
+    return val - offset
+  }
+
+  // General case
+  let val = 0
+  for (let i = 0; i < numBits; i++) {
+    val <<= 1
+    val |= (data[bytePosition]! >> bitPosition) & 1
+    bitPosition -= 1
+    if (bitPosition < 0) {
+      bytePosition += 1
+      bitPosition = 7
+    }
+  }
+
+  cursor.bytePosition = bytePosition
+  cursor.bitPosition = bitPosition
+  return val - offset
+}

package/src/cramFile/codecs/external.ts

@@ -52,4 +52,29 @@ export default class ExternalCodec extends CramCodec<
       return contentBlock.content[cursor.bytePosition++]!
     }
   }
+
+  getBytesSubarray(
+    blocksByContentId: Record<number, CramFileBlock>,
+    cursors: Cursors,
+    length: number,
+  ): Uint8Array | undefined {
+    const { blockContentId } = this.parameters
+    const contentBlock = blocksByContentId[blockContentId]
+    if (!contentBlock) {
+      return undefined
+    }
+
+    const cursor = cursors.externalBlocks.getCursor(blockContentId)
+    const start = cursor.bytePosition
+    const end = start + length
+
+    if (end > contentBlock.content.length) {
+      throw new CramBufferOverrunError(
+        'attempted to read beyond end of block. this file seems truncated.',
+      )
+    }
+
+    cursor.bytePosition = end
+    return contentBlock.content.subarray(start, end)
+  }
 }

package/src/cramFile/codecs/gamma.ts

@@ -1,5 +1,4 @@
-import CramCodec, { Cursors } from './_base.ts'
-import { getBits } from './getBits.ts'
+import CramCodec, { Cursor, Cursors } from './_base.ts'
 import { CramUnimplementedError } from '../../errors.ts'
 import { GammaEncoding } from '../encoding.ts'
 import { CramFileBlock } from '../file.ts'
@@ -24,19 +23,62 @@ export default class GammaCodec extends CramCodec<
     _blocksByContentId: Record<number, CramFileBlock>,
     cursors: Cursors,
   ) {
-    let length = 1
-
-    while (getBits(coreDataBlock.content, cursors.coreBlock, 1) === 0) {
-      length = length + 1
-    }
-
-    const readBits = getBits(
+    return decodeGammaInline(
       coreDataBlock.content,
       cursors.coreBlock,
-      length - 1,
+      this.parameters.offset,
     )
+  }
+}
+
+/**
+ * Optimized gamma decoder with inlined bit reading.
+ * Avoids function call overhead by inlining the getBits logic.
+ */
+function decodeGammaInline(
+  data: Uint8Array,
+  cursor: Cursor,
+  offset: number,
+): number {
+  let { bytePosition, bitPosition } = cursor
+  let length = 1
 
-    const value = readBits | (1 << (length - 1))
-    return value - this.parameters.offset
+  // Count leading zeros (each 0 bit increases length)
+  // Inline single-bit reads for the while loop
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  while (true) {
+    const bit = (data[bytePosition]! >> bitPosition) & 1
+    bitPosition -= 1
+    if (bitPosition < 0) {
+      bytePosition += 1
+      bitPosition = 7
+    }
+    if (bit === 1) {
+      break
+    }
+    length += 1
+  }
+
+  // Now read (length - 1) more bits for the value
+  let readBits = 0
+  const bitsToRead = length - 1
+  if (bitsToRead > 0) {
+    // Optimized multi-bit read
+    for (let i = 0; i < bitsToRead; i++) {
+      readBits <<= 1
+      readBits |= (data[bytePosition]! >> bitPosition) & 1
+      bitPosition -= 1
+      if (bitPosition < 0) {
+        bytePosition += 1
+        bitPosition = 7
+      }
+    }
   }
+
+  // Update cursor
+  cursor.bytePosition = bytePosition
+  cursor.bitPosition = bitPosition as Cursor['bitPosition']
+
+  const value = readBits | (1 << (length - 1))
+  return value - offset
 }

package/src/cramFile/codecs/getBits.ts

@@ -5,7 +5,6 @@ export function getBits(
   cursor: { bytePosition: number; bitPosition: number },
   numBits: number,
 ) {
-  let val = 0
   if (
     cursor.bytePosition + (7 - cursor.bitPosition + numBits) / 8 >
     data.length
@@ -14,8 +13,28 @@ export function getBits(
       'read error during decoding. the file seems to be truncated.',
     )
   }
+
+  // Fast path: reading exactly 8 bits when byte-aligned
+  if (numBits === 8 && cursor.bitPosition === 7) {
+    const val = data[cursor.bytePosition]!
+    cursor.bytePosition += 1
+    return val
+  }
+
+  // Fast path: reading exactly 1 bit
+  if (numBits === 1) {
+    const val = (data[cursor.bytePosition]! >> cursor.bitPosition) & 1
+    cursor.bitPosition -= 1
+    if (cursor.bitPosition < 0) {
+      cursor.bytePosition += 1
+      cursor.bitPosition = 7
+    }
+    return val
+  }
+
+  // General case: bit-by-bit loop
+  let val = 0
   for (let dlen = numBits; dlen; dlen--) {
-    // get the next `dlen` bits in the input, put them in val
     val <<= 1
     val |= (data[cursor.bytePosition]! >> cursor.bitPosition) & 1
     cursor.bitPosition -= 1

package/src/cramFile/codecs/huffman.ts

@@ -1,10 +1,49 @@
 import CramCodec, { Cursor, Cursors } from './_base.ts'
-import { getBits } from './getBits.ts'
 import { CramMalformedError } from '../../errors.ts'
 import { HuffmanEncoding } from '../encoding.ts'
 import { CramFileBlock } from '../file.ts'
 import CramSlice from '../slice/index.ts'
 
+/**
+ * Inlined getBits for huffman decoding - avoids function call overhead
+ */
+function getBitsInline(
+  data: Uint8Array,
+  cursor: Cursor,
+  numBits: number,
+): number {
+  let { bytePosition, bitPosition } = cursor
+
+  // Fast path for single bit (common in huffman)
+  if (numBits === 1) {
+    const val = (data[bytePosition]! >> bitPosition) & 1
+    bitPosition -= 1
+    if (bitPosition < 0) {
+      bytePosition += 1
+      bitPosition = 7
+    }
+    cursor.bytePosition = bytePosition
+    cursor.bitPosition = bitPosition as Cursor['bitPosition']
+    return val
+  }
+
+  // General case
+  let val = 0
+  for (let i = 0; i < numBits; i++) {
+    val <<= 1
+    val |= (data[bytePosition]! >> bitPosition) & 1
+    bitPosition -= 1
+    if (bitPosition < 0) {
+      bytePosition += 1
+      bitPosition = 7
+    }
+  }
+
+  cursor.bytePosition = bytePosition
+  cursor.bitPosition = bitPosition
+  return val
+}
+
 function numberOfSetBits(ii: number) {
   let i = (ii - (ii >> 1)) & 0x55555555
   i = (i & 0x33333333) + ((i >> 2) & 0x33333333)
@@ -144,8 +183,11 @@ export default class HuffmanIntCodec extends CramCodec<
     let bits = 0
     for (let i = 0; i < this.sortedCodes.length; i += 1) {
       const length = this.sortedCodes[i]!.bitLength
-      bits <<= length - prevLen
-      bits |= getBits(input, coreCursor, length - prevLen)
+      const bitsToRead = length - prevLen
+      if (bitsToRead > 0) {
+        bits <<= bitsToRead
+        bits |= getBitsInline(input, coreCursor, bitsToRead)
+      }
       prevLen = length
       {
         const index = this.bitCodeToValue[bits]!

package/src/cramFile/codecs/subexp.ts

@@ -1,5 +1,4 @@
-import CramCodec, { Cursors } from './_base.ts'
-import { getBits } from './getBits.ts'
+import CramCodec, { Cursor, Cursors } from './_base.ts'
 import { CramUnimplementedError } from '../../errors.ts'
 import { SubexpEncoding } from '../encoding.ts'
 import { CramFileBlock } from '../file.ts'
@@ -24,22 +23,60 @@ export default class SubexpCodec extends CramCodec<
     _blocksByContentId: Record<number, CramFileBlock>,
     cursors: Cursors,
   ) {
-    let numLeadingOnes = 0
-    while (getBits(coreDataBlock.content, cursors.coreBlock, 1)) {
-      numLeadingOnes = numLeadingOnes + 1
-    }
+    return decodeSubexpInline(
+      coreDataBlock.content,
+      cursors.coreBlock,
+      this.parameters.K,
+      this.parameters.offset,
+    )
+  }
+}
 
-    let b: number
-    let n: number
-    if (numLeadingOnes === 0) {
-      b = this.parameters.K
-      n = getBits(coreDataBlock.content, cursors.coreBlock, b)
-    } else {
-      b = numLeadingOnes + this.parameters.K - 1
-      const bits = getBits(coreDataBlock.content, cursors.coreBlock, b)
-      n = (1 << b) | bits
+/**
+ * Optimized subexp decoder with inlined bit reading.
+ */
+function decodeSubexpInline(
+  data: Uint8Array,
+  cursor: Cursor,
+  K: number,
+  offset: number,
+): number {
+  let { bytePosition, bitPosition } = cursor
+
+  // Count leading ones (inline single-bit reads)
+  let numLeadingOnes = 0
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  while (true) {
+    const bit = (data[bytePosition]! >> bitPosition) & 1
+    bitPosition -= 1
+    if (bitPosition < 0) {
+      bytePosition += 1
+      bitPosition = 7
+    }
+    if (bit === 0) {
+      break
     }
+    numLeadingOnes += 1
+  }
+
+  // Determine how many bits to read for the value
+  const b = numLeadingOnes === 0 ? K : numLeadingOnes + K - 1
 
-    return n - this.parameters.offset
+  // Read b bits
+  let bits = 0
+  for (let i = 0; i < b; i++) {
+    bits <<= 1
+    bits |= (data[bytePosition]! >> bitPosition) & 1
+    bitPosition -= 1
+    if (bitPosition < 0) {
+      bytePosition += 1
+      bitPosition = 7
+    }
   }
+
+  cursor.bytePosition = bytePosition
+  cursor.bitPosition = bitPosition as Cursor['bitPosition']
+
+  const n = numLeadingOnes === 0 ? bits : (1 << b) | bits
+  return n - offset
 }

package/src/cramFile/file.ts

@@ -1,5 +1,5 @@
-import crc32 from 'crc/calculators/crc32'
 import QuickLRU from '@jbrowse/quick-lru'
+import crc32 from 'crc/calculators/crc32'
 
 import { CramMalformedError, CramUnimplementedError } from '../errors.ts'
 import * as htscodecs from '../htscodecs/index.ts'
@@ -380,6 +380,88 @@ export default class CramFile {
 
     return block
   }
+
+  async readBlockFromBuffer(
+    buffer: Uint8Array,
+    bufferOffset: number,
+    filePosition: number,
+  ) {
+    const { majorVersion } = await this.getDefinition()
+    if (!this._sectionParsers) {
+      this._sectionParsers = getSectionParsers(majorVersion)
+    }
+    const sectionParsers = this._sectionParsers
+    const { cramBlockHeader } = sectionParsers
+
+    const headerBytes = buffer.subarray(
+      bufferOffset,
+      bufferOffset + cramBlockHeader.maxLength,
+    )
+    const blockHeader = parseItem(
+      headerBytes,
+      cramBlockHeader.parser,
+      0,
+      filePosition,
+    )
+    const blockContentPosition = blockHeader._endPosition
+    const contentOffset = bufferOffset + blockHeader._size
+
+    const d = buffer.subarray(
+      contentOffset,
+      contentOffset + blockHeader.compressedSize,
+    )
+    const uncompressedData =
+      blockHeader.compressionMethod !== 'raw'
+        ? await this._uncompress(
+            blockHeader.compressionMethod,
+            d,
+            blockHeader.uncompressedSize,
+          )
+        : d
+
+    const block: CramFileBlock = {
+      ...blockHeader,
+      _endPosition: blockContentPosition,
+      contentPosition: blockContentPosition,
+      content: uncompressedData,
+    }
+    if (majorVersion >= 3) {
+      const crcOffset = contentOffset + blockHeader.compressedSize
+      const crcBytes = buffer.subarray(
+        crcOffset,
+        crcOffset + sectionParsers.cramBlockCrc32.maxLength,
+      )
+      const crc = parseItem(
+        crcBytes,
+        sectionParsers.cramBlockCrc32.parser,
+        0,
+        blockContentPosition + blockHeader.compressedSize,
+      )
+      block.crc32 = crc.crc32
+
+      if (this.validateChecksums) {
+        const blockData = buffer.subarray(
+          bufferOffset,
+          bufferOffset + blockHeader._size + blockHeader.compressedSize,
+        )
+        const calculatedCrc32 = crc32(blockData) >>> 0
+        if (calculatedCrc32 !== crc.crc32) {
+          throw new CramMalformedError(
+            `crc mismatch in block data: recorded CRC32 = ${crc.crc32}, but calculated CRC32 = ${calculatedCrc32}`,
+          )
+        }
+      }
+
+      block._endPosition = crc._endPosition
+      block._size =
+        block.compressedSize + sectionParsers.cramBlockCrc32.maxLength
+    } else {
+      block._endPosition = blockContentPosition + block.compressedSize
+      block._size = block.compressedSize
+    }
+
+    return block
+  }
 }
 
 'getDefinition getSectionParsers getSamHeader'.split(' ').forEach(method => {

package/src/cramFile/record.ts

@@ -18,6 +18,15 @@ export interface ReadFeature {
   sub?: string
 }
 
+export interface DecodeOptions {
+  /** Whether to parse tags. If false, raw tag data is stored for lazy parsing. Default true. */
+  decodeTags?: boolean
+}
+
+export const defaultDecodeOptions: Required<DecodeOptions> = {
+  decodeTags: true,
+}
+
 function decodeReadSequence(cramRecord: CramRecord, refRegion: RefRegion) {
   // if it has no length, it has no sequence
   if (!cramRecord.lengthOnRef && !cramRecord.readLength) {
@@ -238,7 +247,7 @@ export default class CramRecord {
   public sequenceId: number
   public readGroupId: number
   public mappingQuality: number | undefined
-  public qualityScores: number[] | null | undefined
+  public qualityScores: Uint8Array | null | undefined
 
   constructor({
     flags,
@@ -294,6 +303,15 @@ export default class CramRecord {
     }
   }
 
+  /**
+   * Get a single quality score at the given index.
+   * @param index 0-based index into the quality scores
+   * @returns the quality score at that index, or undefined if not available
+   */
+  qualityScoreAt(index: number): number | undefined {
+    return this.qualityScores?.[index]
+  }
+
   /**
    * @returns {boolean} true if the read is paired, regardless of whether both segments are mapped
    */
@@ -401,8 +419,7 @@ export default class CramRecord {
       !this.isSegmentUnmapped() &&
       this.isPaired() &&
       !this.isMateUnmapped() &&
-      this.mate &&
-      this.sequenceId === this.mate.sequenceId
+      this.sequenceId === this.mate?.sequenceId
     ) {
       const s1 = this.isReverseComplemented() ? 'R' : 'F'
       const s2 = this.isMateReverseComplemented() ? 'R' : 'F'
@@ -460,7 +477,7 @@ export default class CramRecord {
     if (this.readFeatures) {
       // use the reference bases to decode the bases substituted in each base
       // substitution
-      this.readFeatures.forEach(readFeature => {
+      for (const readFeature of this.readFeatures) {
         if (readFeature.code === 'X') {
           decodeBaseSubstitution(
             this,
@@ -469,7 +486,7 @@ export default class CramRecord {
             readFeature,
           )
         }
-      })
+      }
     }
 
     // if this region completely covers this read,
@@ -494,6 +511,9 @@ export default class CramRecord {
     })
 
     data.readBases = this.getReadBases()
+    data.qualityScores = this.qualityScores
+      ? Array.from(this.qualityScores)
+      : this.qualityScores
 
     return data
   }