Further simplifications and correctness fixes in decode hot path

- huffman: fix crash when inner loop reaches last code (bounds check was
  after array access); remove dead commented-out method; nest early-return
  in buildCaches into if block; use ?? -1 instead of ! for bitCodeToValue
  lookup; remove spurious inner braces in _decode
- decodeRecord: fold lengthOnRef computation into decodeReadFeatures return
  value, eliminating the second pass over read features; fix push(...spread)
  in getAllMatedRecords; hoist duplicate `content` variable in bind(); extract
  decodeQualityScores/decodeReadBases helpers; use Uint8Array+decodeLatin1
  in decodeReadBases fallback; remove dead RFFn alias; fix stale comment
- index.ts: inline ByteArrayStopCodec decode in bind() fast path; deduplicate
  tag decoder subarray body via readTagLen closure; fix indentation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: cmdcolin

src/cramFile/codecs/huffman.ts

@@ -152,14 +152,12 @@ export default class HuffmanIntCodec extends CramCodec<
     this.sortedValuesByBitCode = this.sortedCodes.map(c => c.value)
     this.sortedBitCodes = this.sortedCodes.map(c => c.bitCode)
     this.sortedBitLengthsByBitCode = this.sortedCodes.map(c => c.bitLength)
-    if (this.sortedBitCodes.length === 0) {
-      return
-    }
-    const maxBitCode = Math.max(...this.sortedBitCodes)
-
-    this.bitCodeToValue = new Array(maxBitCode + 1).fill(-1)
-    for (let i = 0; i < this.sortedBitCodes.length; i += 1) {
-      this.bitCodeToValue[this.sortedCodes[i]!.bitCode] = i
+    if (this.sortedBitCodes.length > 0) {
+      const maxBitCode = Math.max(...this.sortedBitCodes)
+      this.bitCodeToValue = new Array(maxBitCode + 1).fill(-1)
+      for (let i = 0; i < this.sortedBitCodes.length; i += 1) {
+        this.bitCodeToValue[this.sortedCodes[i]!.bitCode] = i
+      }
     }
   }
 
@@ -172,10 +170,6 @@ export default class HuffmanIntCodec extends CramCodec<
     return this._decode(slice, coreDataBlock, cursors.coreBlock)
   }
 
-  // _decodeNull() {
-  //   return -1
-  // }
-
   // the special case for zero-length codes
   _decodeZeroLengthCode() {
     return this.sortedCodes[0]!.value
@@ -194,20 +188,17 @@ export default class HuffmanIntCodec extends CramCodec<
         bits |= getBitsInline(input, coreCursor, bitsToRead)
       }
       prevLen = length
-      {
-        const index = this.bitCodeToValue[bits]!
-        if (index > -1 && this.sortedBitLengthsByBitCode[index] === length) {
-          return this.sortedValuesByBitCode[index]!
-        }
-
-        for (
-          let j = i;
-          this.sortedCodes[j + 1]!.bitLength! === length &&
-          j < this.sortedCodes.length;
-          j += 1
-        ) {
-          i += 1
-        }
+      const index = this.bitCodeToValue[bits] ?? -1
+      if (index > -1 && this.sortedBitLengthsByBitCode[index] === length) {
+        return this.sortedValuesByBitCode[index]!
+      }
+      for (
+        let j = i;
+        j + 1 < this.sortedCodes.length &&
+        this.sortedCodes[j + 1]!.bitLength === length;
+        j += 1
+      ) {
+        i += 1
       }
     }
     throw new CramMalformedError('Huffman symbol not found.')

src/cramFile/slice/decodeRecord.ts

@@ -52,16 +52,9 @@ export interface BoundDecoders {
   TN(): number | undefined
 }
 
-/**
- * parse a BAM tag's array value from a binary buffer
- * @private
- */
-// Uses DataView instead of typed arrays (e.g. new Int32Array(buffer.buffer))
-// because the buffer may be a subarray of a larger ArrayBuffer. Typed array
-// constructors like Int32Array interpret .buffer as the entire underlying
-// ArrayBuffer starting at byte 0, ignoring the subarray's byteOffset. This
-// caused silent data corruption when reading tag values. DataView with explicit
-// byteOffset reads from the correct position within the parent buffer.
+// Uses DataView rather than typed arrays because the buffer is a subarray of a
+// larger ArrayBuffer. Int32Array(buffer.buffer) would start at byte 0 of the
+// parent, ignoring buffer.byteOffset, causing silent data corruption.
 function parseTagValueArray(buffer: Uint8Array) {
   const arrayType = String.fromCharCode(buffer[0]!)
 
@@ -148,25 +141,21 @@ function parseTagData(tagType: string, buffer: Uint8Array) {
   throw new CramMalformedError(`Unrecognized tag type ${tagType}`)
 }
 
-// Read-feature schema: a charCode-indexed array of [letter, fn] tuples where
-// fn() decodes the feature's data, fully transformed
-// (character → fromCharCode, string → decodeLatin1, numArray → Array.from,
-// number → identity, B → [base, qualityScore]). Built once per slice; the
-// inner loop becomes a charCode lookup + monomorphic call.
+// Read-feature schema: a charCode-indexed array of [code, fn] tuples where
+// fn() decodes and transforms the feature's data (character → fromCharCode,
+// string → decodeLatin1, numArray → Array.from, number → identity,
+// B → [base, qualityScore]). Built once per slice; the inner loop becomes
+// a charCode lookup + monomorphic call with no per-feature allocation.
 type RFData = string | number | number[] | [string, number]
-type RFFn = () => RFData
-export type RFEntry = readonly [code: string, fn: RFFn]
+export type RFEntry = readonly [code: string, fn: () => RFData]
 
 export function buildRFSchema(
   bd: BoundDecoders,
   majorVersion: number,
 ): (RFEntry | undefined)[] {
   const SC = majorVersion > 1 ? bd.SC : bd.IN
   const arr: (RFEntry | undefined)[] = new Array(128)
-  arr['B'.charCodeAt(0)] = [
-    'B',
-    () => [String.fromCharCode(bd.BA()!), bd.QS()!],
-  ]
+  arr['B'.charCodeAt(0)] = ['B', () => [String.fromCharCode(bd.BA()!), bd.QS()!] as [string, number]]
   arr['X'.charCodeAt(0)] = ['X', () => bd.BS()!]
   arr['D'.charCodeAt(0)] = ['D', () => bd.DL()!]
   arr['I'.charCodeAt(0)] = ['I', () => decodeLatin1(bd.IN()!)]
@@ -186,12 +175,10 @@ function decodeReadFeatures(
   readFeatureCount: number,
   bd: BoundDecoders,
   schema: (RFEntry | undefined)[],
-) {
-  // Track the running offset between ref and read coordinates so that
-  // refPos = readPos + refOffset. Deletions advance ref past consumed
-  // ref bases (offset goes up); insertions advance read past consumed
-  // read bases (offset goes down). This mirrors CIGAR consume-ref vs
-  // consume-read semantics.
+): [ReadFeature[], number] {
+  // refOffset tracks the running base-pair gap between read and reference
+  // coordinates. Returns the net delta (refOffset - initial) so the caller
+  // can compute lengthOnRef = readLength + delta without a second pass.
   let readPos = 0
   let refOffset = alignmentStart - 1
   const readFeatures: ReadFeature[] = new Array(readFeatureCount)
@@ -227,7 +214,7 @@ function decodeReadFeatures(
       refOffset -= 1
     }
   }
-  return readFeatures
+  return [readFeatures, refOffset - (alignmentStart - 1)]
 }
 
 export type BulkByteRawDecoder = (
@@ -260,11 +247,11 @@ function decodeReadBases(
   if (raw) {
     return decodeLatin1(raw)
   }
-  let s = ''
+  const buf = new Uint8Array(readLength)
   for (let i = 0; i < readLength; i++) {
-    s += String.fromCharCode(decodeBA()!)
+    buf[i] = decodeBA()!
   }
-  return s
+  return decodeLatin1(buf)
 }
 
 export type BoundTagDecoders = Record<
@@ -304,7 +291,7 @@ export default function decodeRecord(
       : sliceHeader.parsedContent.refSeqId
 
   const readLength = bd.RL()!
-  // if APDelta, will calculate the true start in a second pass
+  // if APDelta, AP is a delta from the previous record's alignmentStart
   let alignmentStart = bd.AP()!
   if (compressionScheme.APdelta) {
     alignmentStart = alignmentStart + cursors.lastAlignmentStart
@@ -393,28 +380,16 @@ export default function decodeRecord(
   if (!BamFlagsDecoder.isSegmentUnmapped(flags)) {
     // reading read features
     const readFeatureCount = bd.FN()!
+    lengthOnRef = readLength
     if (readFeatureCount) {
-      readFeatures = decodeReadFeatures(
+      const [features, refDelta] = decodeReadFeatures(
         alignmentStart,
         readFeatureCount,
         bd,
         rfSchema,
       )
-    }
-
-    // compute the read's true span on the reference sequence, and the end
-    // coordinate of the alignment on the reference
-    lengthOnRef = readLength
-    if (readFeatures) {
-      for (const { code, data } of readFeatures) {
-        if (code === 'D' || code === 'N') {
-          lengthOnRef += data
-        } else if (code === 'I' || code === 'S') {
-          lengthOnRef = lengthOnRef - data.length
-        } else if (code === 'i') {
-          lengthOnRef = lengthOnRef - 1
-        }
-      }
+      readFeatures = features
+      lengthOnRef += refDelta
     }
     if (Number.isNaN(lengthOnRef)) {
       console.warn(

src/cramFile/slice/index.ts

@@ -70,7 +70,9 @@ function calculateMultiSegmentMatedTemplateLength(
           'intra-slice mate record not found, this file seems malformed',
         )
       }
-      records.push(...getAllMatedRecords(mateRecord))
+      for (const r of getAllMatedRecords(mateRecord)) {
+        records.push(r)
+      }
     }
     return records
   }
@@ -549,11 +551,10 @@ export default class CramSlice {
           return () => undefined
         }
         const cursor = cursors.externalBlocks.getCursor(bid)
+        const content = contentBlock.content
         if (codec.dataType === 'int') {
-          const content = contentBlock.content
           return () => parseItf8(content, cursor)
         }
-        const content = contentBlock.content
         return () => content[cursor.bytePosition++]
       }
       if (codec instanceof ByteArrayStopCodec) {
@@ -637,40 +638,25 @@ export default class CramSlice {
         const valContent = valContentBlock.content
         const valCursor = cursors.externalBlocks.getCursor(valBid)
         const lenPreDecoded = preDecodedIntBlocks.get(lenBid)
-        if (lenPreDecoded) {
-          boundTagDecoders[tagId] = () => {
-            const length = lenPreDecoded.values[lenPreDecoded.index++]!
-            if (length === 0) {
-              return EMPTY_BYTES
-            }
-            const start = valCursor.bytePosition
-            const end = start + length
-            if (end > valContent.length) {
-              throw new CramBufferOverrunError(
-                'attempted to read beyond end of block. this file seems truncated.',
-              )
-            }
-            valCursor.bytePosition = end
-            return valContent.subarray(start, end)
+        const lenContent = lenContentBlock.content
+        const lenCursor = cursors.externalBlocks.getCursor(lenBid)
+        const readTagLen = lenPreDecoded
+          ? () => lenPreDecoded.values[lenPreDecoded.index++]!
+          : () => parseItf8(lenContent, lenCursor)
+        boundTagDecoders[tagId] = () => {
+          const length = readTagLen()
+          if (length === 0) {
+            return EMPTY_BYTES
           }
-        } else {
-          const lenContent = lenContentBlock.content
-          const lenCursor = cursors.externalBlocks.getCursor(lenBid)
-          boundTagDecoders[tagId] = () => {
-            const length = parseItf8(lenContent, lenCursor)
-            if (length === 0) {
-              return EMPTY_BYTES
-            }
-            const start = valCursor.bytePosition
-            const end = start + length
-            if (end > valContent.length) {
-              throw new CramBufferOverrunError(
-                'attempted to read beyond end of block. this file seems truncated.',
-              )
-            }
-            valCursor.bytePosition = end
-            return valContent.subarray(start, end)
+          const start = valCursor.bytePosition
+          const end = start + length
+          if (end > valContent.length) {
+            throw new CramBufferOverrunError(
+              'attempted to read beyond end of block. this file seems truncated.',
+            )
           }
+          valCursor.bytePosition = end
+          return valContent.subarray(start, end)
         }
       } else {
         boundTagDecoders[tagId] = bindTagFallback(tagId)