@gmod/cram 8.0.2 → 8.0.4

package/src/cramFile/codecs/_base.ts

@@ -42,4 +42,12 @@ export default abstract class CramCodec<
     blocksByContentId: Record<number, CramFileBlock>,
     cursors: Cursors,
   ): DataTypeMapping[TResult] | undefined
+
+  getBytesSubarray(
+    _blocksByContentId: Record<number, CramFileBlock>,
+    _cursors: Cursors,
+    _length: number,
+  ): Uint8Array | undefined {
+    return undefined
+  }
 }

package/src/cramFile/codecs/byteArrayLength.ts

@@ -35,18 +35,31 @@ export default class ByteArrayStopCodec extends CramCodec<
     const arrayLength =
       lengthCodec.decode(slice, coreDataBlock, blocksByContentId, cursors) || 0
 
-    const data = new Uint8Array(arrayLength)
     if (arrayLength > 0) {
       const dataCodec = this._getDataCodec()
-      // Call decode directly on codec to avoid repeated lookups
-      for (let i = 0; i < arrayLength; i += 1) {
-        data[i] =
-          dataCodec.decode(slice, coreDataBlock, blocksByContentId, cursors) ||
-          0
+      const subarray = dataCodec.getBytesSubarray(
+        blocksByContentId,
+        cursors,
+        arrayLength,
+      )
+      if (subarray) {
+        return subarray
+      } else {
+        const data = new Uint8Array(arrayLength)
+        for (let i = 0; i < arrayLength; i += 1) {
+          data[i] =
+            dataCodec.decode(
+              slice,
+              coreDataBlock,
+              blocksByContentId,
+              cursors,
+            ) || 0
+        }
+        return data
       }
+    } else {
+      return new Uint8Array(0)
     }
-
-    return data
   }
 
   // memoize

package/src/cramFile/codecs/external.ts

@@ -1,10 +1,47 @@
 import CramCodec, { Cursors } from './_base.ts'
 import { CramUnimplementedError } from '../../errors.ts'
+import { ExternalCramEncoding } from '../encoding.ts'
 import { CramFileBlock } from '../file.ts'
-import CramSlice from '../slice/index.ts'
-import { parseItf8 } from '../util.ts'
 import { CramBufferOverrunError } from './getBits.ts'
-import { ExternalCramEncoding } from '../encoding.ts'
+import CramSlice from '../slice/index.ts'
+
+function parseItf8Inline(buffer: Uint8Array, cursor: { bytePosition: number }) {
+  const offset = cursor.bytePosition
+  const countFlags = buffer[offset]!
+  if (countFlags < 0x80) {
+    cursor.bytePosition = offset + 1
+    return countFlags
+  }
+  if (countFlags < 0xc0) {
+    cursor.bytePosition = offset + 2
+    return ((countFlags & 0x3f) << 8) | buffer[offset + 1]!
+  }
+  if (countFlags < 0xe0) {
+    cursor.bytePosition = offset + 3
+    return (
+      ((countFlags & 0x1f) << 16) |
+      (buffer[offset + 1]! << 8) |
+      buffer[offset + 2]!
+    )
+  }
+  if (countFlags < 0xf0) {
+    cursor.bytePosition = offset + 4
+    return (
+      ((countFlags & 0x0f) << 24) |
+      (buffer[offset + 1]! << 16) |
+      (buffer[offset + 2]! << 8) |
+      buffer[offset + 3]!
+    )
+  }
+  cursor.bytePosition = offset + 5
+  return (
+    ((countFlags & 0x0f) << 28) |
+    (buffer[offset + 1]! << 20) |
+    (buffer[offset + 2]! << 12) |
+    (buffer[offset + 3]! << 4) |
+    (buffer[offset + 4]! & 0x0f)
+  )
+}
 
 export default class ExternalCodec extends CramCodec<
   'int' | 'byte',
@@ -37,12 +74,7 @@ export default class ExternalCodec extends CramCodec<
     const cursor = cursors.externalBlocks.getCursor(blockContentId)
 
     if (this.dataType === 'int') {
-      const [result, bytesRead] = parseItf8(
-        contentBlock.content,
-        cursor.bytePosition,
-      )
-      cursor.bytePosition += bytesRead
-      return result
+      return parseItf8Inline(contentBlock.content, cursor)
     } else {
       if (cursor.bytePosition >= contentBlock.content.length) {
         throw new CramBufferOverrunError(

package/src/cramFile/codecs/getBits.ts

@@ -1,4 +1,6 @@
-export class CramBufferOverrunError extends Error {}
+export class CramBufferOverrunError extends Error {
+  readonly code = 'CRAM_BUFFER_OVERRUN' as const
+}
 
 export function getBits(
   data: Uint8Array,

package/src/cramFile/record.ts

@@ -1,23 +1,53 @@
 import Constants from './constants.ts'
 import CramContainerCompressionScheme from './container/compressionScheme.ts'
+import { readNullTerminatedStringFromBuffer } from './util.ts'
 
 import type decodeRecord from './slice/decodeRecord.ts'
 
+// precomputed pair orientation strings indexed by ((flags >> 4) & 0xF) | (isize > 0 ? 16 : 0)
+// bits 0-3 encode flag bits 0x10(reverse),0x20(mate reverse),0x40(read1),0x80(read2)
+// bit 4 encodes whether isize > 0
+// prettier-ignore
+const PAIR_ORIENTATION_TABLE = [
+  'F F ','F R ','R F ','R R ','F2F1','F2R1','R2F1','R2R1',
+  'F1F2','F1R2','R1F2','R1R2','F2F1','F2R1','R2F1','R2R1',
+  'F F ','R F ','F R ','R R ','F1F2','R1F2','F1R2','R1R2',
+  'F2F1','R2F1','F2R1','R2R1','F1F2','R1F2','F1R2','R1R2',
+]
+
 export interface RefRegion {
   start: number
   end: number
   seq: string
 }
 
-export interface ReadFeature {
-  code: string
+interface ReadFeatureBase {
   pos: number
   refPos: number
-  data: any
-  ref?: string
-  sub?: string
 }
 
+/**
+ * Read features describe differences between a read and the reference sequence.
+ * Each feature has a code indicating the type of difference, a position in the
+ * read (pos), and a position on the reference (refPos).
+ */
+export type ReadFeature =
+  /** I=insertion, S=soft clip, b=bases, i=single-base insertion — all carry a sequence string */
+  | (ReadFeatureBase & { code: 'I' | 'S' | 'b' | 'i'; data: string })
+  /** B=base and quality pair — [substituted base, quality score] */
+  | (ReadFeatureBase & { code: 'B'; data: [string, number] })
+  /** X=base substitution — data is the substitution matrix index, ref/sub filled in by addReferenceSequence */
+  | (ReadFeatureBase & {
+      code: 'X'
+      data: number
+      ref?: string
+      sub?: string
+    })
+  /** D=deletion, N=reference skip, H=hard clip, P=padding, Q=single quality score */
+  | (ReadFeatureBase & { code: 'D' | 'N' | 'H' | 'P' | 'Q'; data: number })
+  /** q=quality scores for a stretch of bases */
+  | (ReadFeatureBase & { code: 'q'; data: number[] })
+
 export interface DecodeOptions {
   /** Whether to parse tags. If false, raw tag data is stored for lazy parsing. Default true. */
   decodeTags?: boolean
@@ -59,40 +89,30 @@ function decodeReadSequence(cramRecord: CramRecord, refRegion: RefRegion) {
         currentReadFeature += 1
 
         if (feature.code === 'b') {
-          // specify a base pair for some reason
           const added = feature.data
           bases += added
           regionPos += added.length
         } else if (feature.code === 'B') {
-          // base pair and associated quality
-          // TODO: do we need to set the quality in the qual scores?
           bases += feature.data[0]
           regionPos += 1
         } else if (feature.code === 'X') {
-          // base substitution
           bases += feature.sub
           regionPos += 1
         } else if (feature.code === 'I') {
-          // insertion
           bases += feature.data
         } else if (feature.code === 'D') {
-          // deletion
           regionPos += feature.data
         } else if (feature.code === 'i') {
-          // insert single base
           bases += feature.data
         } else if (feature.code === 'N') {
-          // reference skip. delete some bases
-          // do nothing
-          // seqBases.splice(feature.pos - 1, feature.data)
           regionPos += feature.data
         } else if (feature.code === 'S') {
-          // soft clipped bases that should be present in the read seq
-          // seqBases.splice(feature.pos - 1, 0, ...feature.data.split(''))
           bases += feature.data
         } else if (feature.code === 'P') {
           // padding, do nothing
-        } else if (feature.code === 'H') {
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        else if (feature.code === 'H') {
           // hard clip, do nothing
         }
       } else if (currentReadFeature < cramRecord.readFeatures.length) {
@@ -118,7 +138,7 @@ function decodeReadSequence(cramRecord: CramRecord, refRegion: RefRegion) {
   return bases.toUpperCase()
 }
 
-const baseNumbers = {
+const baseNumbers: Record<string, number | undefined> = {
   a: 0,
   A: 0,
   c: 1,
@@ -135,7 +155,12 @@ function decodeBaseSubstitution(
   cramRecord: CramRecord,
   refRegion: RefRegion,
   compressionScheme: CramContainerCompressionScheme,
-  readFeature: ReadFeature,
+  readFeature: ReadFeatureBase & {
+    code: 'X'
+    data: number
+    ref?: string
+    sub?: string
+  },
 ) {
   // decode base substitution code using the substitution matrix
   const refCoord = readFeature.refPos - refRegion.start
@@ -143,7 +168,7 @@ function decodeBaseSubstitution(
   if (refBase) {
     readFeature.ref = refBase
   }
-  let baseNumber = (baseNumbers as any)[refBase]
+  let baseNumber = baseNumbers[refBase]
   if (baseNumber === undefined) {
     baseNumber = 4
   }
@@ -229,7 +254,7 @@ export const MateFlagsDecoder = makeFlagsHelper(MateFlags)
  * Class of each CRAM record returned by this API.
  */
 export default class CramRecord {
-  public tags: Record<string, string>
+  public tags: Record<string, string | number | number[] | undefined>
   public flags: number
   public cramFlags: number
   public readBases?: string | null
@@ -238,9 +263,13 @@ export default class CramRecord {
   public alignmentStart: number
   public lengthOnRef: number | undefined
   public readLength: number
+  // templateLength is computed post-hoc for intra-slice mate pairs,
+  // templateSize is the raw CRAM-encoded TS data series value
   public templateLength?: number
   public templateSize?: number
-  public readName?: string
+  private _readName?: string
+  private _readNameRaw?: Uint8Array
+  public _syntheticReadName?: string
   public mateRecordNumber?: number
   public mate?: MateRecord
   public uniqueId: number
@@ -249,6 +278,18 @@ export default class CramRecord {
   public mappingQuality: number | undefined
   public qualityScores: Uint8Array | null | undefined
 
+  get readName() {
+    if (this._readName === undefined) {
+      if (this._readNameRaw) {
+        this._readName = readNullTerminatedStringFromBuffer(this._readNameRaw)
+        this._readNameRaw = undefined
+      } else {
+        return this._syntheticReadName
+      }
+    }
+    return this._readName
+  }
+
   constructor({
     flags,
     cramFlags,
@@ -261,32 +302,31 @@ export default class CramRecord {
     readFeatures,
     mateToUse,
     readGroupId,
-    readName,
+    readNameRaw,
     sequenceId,
     uniqueId,
     templateSize,
     alignmentStart,
     tags,
-  }: ReturnType<typeof decodeRecord> & { uniqueId: number }) {
+  }: ReturnType<typeof decodeRecord>) {
     this.flags = flags
     this.cramFlags = cramFlags
     this.readLength = readLength
     this.mappingQuality = mappingQuality
     this.lengthOnRef = lengthOnRef
     this.qualityScores = qualityScores
-    if (readBases) {
-      this.readBases = readBases
-    }
-
     this.readGroupId = readGroupId
-    this.readName = readName
     this.sequenceId = sequenceId!
     this.uniqueId = uniqueId
-    this.templateSize = templateSize
     this.alignmentStart = alignmentStart
     this.tags = tags
-
-    // backwards compatibility
+    if (readNameRaw) {
+      this._readNameRaw = readNameRaw
+    }
+    if (readBases) {
+      this.readBases = readBases
+    }
+    this.templateSize = templateSize
     if (readFeatures) {
       this.readFeatures = readFeatures
     }
@@ -411,29 +451,15 @@ export default class CramRecord {
   }
 
   // adapted from igv.js
-  // inlines flag checks and uses template literal instead of array+join
+  // uses precomputed lookup table indexed by flag bits + isize sign
   getPairOrientation() {
     const f = this.flags
     // combined check: paired (0x1) set, unmapped (0x4) clear, mate unmapped (0x8) clear
     if ((f & 0xd) !== 0x1 || this.sequenceId !== this.mate?.sequenceId) {
       return undefined
     }
-    const s1 = f & 0x10 ? 'R' : 'F'
-    const s2 = f & 0x20 ? 'R' : 'F'
-    let o1 = ' '
-    let o2 = ' '
-    if (f & 0x40) {
-      o1 = '1'
-      o2 = '2'
-    } else if (f & 0x80) {
-      o1 = '2'
-      o2 = '1'
-    }
-
     const isize = this.templateLength || this.templateSize || 0
-    return isize > 0
-      ? `${s1}${o1}${s2}${o2}`
-      : `${s2}${o2}${s1}${o1}`
+    return PAIR_ORIENTATION_TABLE[((f >> 4) & 0xf) | (isize > 0 ? 16 : 0)]
   }
 
   /**
@@ -489,6 +515,7 @@ export default class CramRecord {
       data[k] = (this as any)[k]
     })
 
+    data.readName = this.readName
     data.readBases = this.getReadBases()
     data.qualityScores = this.qualityScores
       ? Array.from(this.qualityScores)