@gmod/cram 7.0.2 → 8.0.0

package/src/cramFile/slice/decodeRecord.ts

@@ -7,6 +7,7 @@ import CramContainerCompressionScheme, {
 import {
   BamFlagsDecoder,
   CramFlagsDecoder,
+  DecodeOptions,
   MateFlagsDecoder,
   ReadFeature,
 } from '../record.ts'
@@ -14,16 +15,21 @@ import CramSlice, { SliceHeader } from './index.ts'
 import { CramFileBlock } from '../file.ts'
 import { isMappedSliceHeader } from '../sectionParsers.ts'
 
+// Reusable TextDecoder instance for string decoding (ASCII/Latin1)
+const textDecoder = new TextDecoder('latin1')
+
 /**
  * given a Buffer, read a string up to the first null character
  * @private
  */
 function readNullTerminatedString(buffer: Uint8Array) {
-  let r = ''
-  for (let i = 0; i < buffer.length && buffer[i] !== 0; i++) {
-    r += String.fromCharCode(buffer[i]!)
+  // Find the null terminator
+  let end = 0
+  while (end < buffer.length && buffer[end] !== 0) {
+    end++
   }
-  return r
+  // Decode using TextDecoder (faster than char-by-char concatenation)
+  return textDecoder.decode(buffer.subarray(0, end))
 }
 
 /**
@@ -123,17 +129,50 @@ function parseTagData(tagType: string, buffer: Uint8Array) {
   throw new CramMalformedError(`Unrecognized tag type ${tagType}`)
 }
 
+// Pre-defined schema lookup tables (version-independent entries)
+const data1SchemaBase = {
+  B: ['character', 'BA'] as const,
+  X: ['number', 'BS'] as const,
+  D: ['number', 'DL'] as const,
+  I: ['string', 'IN'] as const,
+  i: ['character', 'BA'] as const,
+  b: ['string', 'BB'] as const,
+  q: ['numArray', 'QQ'] as const,
+  Q: ['number', 'QS'] as const,
+  H: ['number', 'HC'] as const,
+  P: ['number', 'PD'] as const,
+  N: ['number', 'RS'] as const,
+} as const
+
+// Version-specific S entry
+const data1SchemaV1: Record<string, readonly [string, string]> = {
+  ...data1SchemaBase,
+  S: ['string', 'IN'] as const,
+}
+const data1SchemaV2Plus: Record<string, readonly [string, string]> = {
+  ...data1SchemaBase,
+  S: ['string', 'SC'] as const,
+}
+
+// Second data item schema for read features that have two values
+const data2Schema: Record<string, readonly [string, string]> = {
+  B: ['number', 'QS'] as const,
+}
+
 function decodeReadFeatures(
   alignmentStart: number,
   readFeatureCount: number,
   decodeDataSeries: any,
-  compressionScheme: CramContainerCompressionScheme,
+  _compressionScheme: CramContainerCompressionScheme,
   majorVersion: number,
 ) {
   let currentReadPos = 0
   let currentRefPos = alignmentStart - 1
   const readFeatures: ReadFeature[] = new Array(readFeatureCount)
 
+  // Select the appropriate schema based on version (once per call, not per iteration)
+  const data1Schema = majorVersion > 1 ? data1SchemaV2Plus : data1SchemaV1
+
   function decodeRFData([type, dataSeriesName]: readonly [
     type: string,
     dataSeriesName: string,
@@ -142,17 +181,10 @@ function decodeReadFeatures(
     if (type === 'character') {
       return String.fromCharCode(data)
     } else if (type === 'string') {
-      let r = ''
-      for (let i = 0; i < data.byteLength; i++) {
-        r += String.fromCharCode(data[i])
-      }
-      return r
+      return textDecoder.decode(data)
     } else if (type === 'numArray') {
       return Array.from(data)
     }
-    // else if (type === 'number') {
-    //   return data[0]
-    // }
     return data
   }
 
@@ -161,32 +193,18 @@ function decodeReadFeatures(
 
     const readPosDelta = decodeDataSeries('FP')
 
-    // map of operator name -> data series name
-    const data1Schema = {
-      B: ['character', 'BA'] as const,
-      S: ['string', majorVersion > 1 ? 'SC' : 'IN'] as const, // IN if cram v1, SC otherwise
-      X: ['number', 'BS'] as const,
-      D: ['number', 'DL'] as const,
-      I: ['string', 'IN'] as const,
-      i: ['character', 'BA'] as const,
-      b: ['string', 'BB'] as const,
-      q: ['numArray', 'QQ'] as const,
-      Q: ['number', 'QS'] as const,
-      H: ['number', 'HC'] as const,
-      P: ['number', 'PD'] as const,
-      N: ['number', 'RS'] as const,
-    }[code]
-
-    if (!data1Schema) {
+    const schema = data1Schema[code]
+
+    if (!schema) {
       throw new CramMalformedError(`invalid read feature code "${code}"`)
     }
 
-    let data = decodeRFData(data1Schema)
+    let data: any = decodeRFData(schema)
 
-    // if this is a tag with two data items, make the data an array and add the second item
-    const data2Schema = { B: ['number', 'QS'] as const }[code]
-    if (data2Schema) {
-      data = [data, decodeRFData(data2Schema)]
+    // if this is a read feature with two data items, make the data an array
+    const schema2 = data2Schema[code]
+    if (schema2) {
+      data = [data, decodeRFData(schema2)]
     }
 
     currentReadPos += readPosDelta
@@ -213,6 +231,11 @@ export type DataSeriesDecoder = <T extends DataSeriesEncodingKey>(
   dataSeriesName: T,
 ) => DataTypeMapping[DataSeriesTypes[T]] | undefined
 
+export type BulkByteRawDecoder = (
+  dataSeriesName: 'QS' | 'BA',
+  length: number,
+) => Uint8Array | undefined
+
 export default function decodeRecord(
   slice: CramSlice,
   decodeDataSeries: DataSeriesDecoder,
@@ -223,6 +246,8 @@ export default function decodeRecord(
   cursors: Cursors,
   majorVersion: number,
   recordNumber: number,
+  decodeOptions?: Required<DecodeOptions>,
+  decodeBulkBytesRaw?: BulkByteRawDecoder,
 ) {
   let flags = decodeDataSeries('BF')!
 
@@ -312,26 +337,32 @@ export default function decodeRecord(
   // TN = tag names
   const TN = compressionScheme.getTagNames(TLindex)!
   const ntags = TN.length
+  const shouldDecodeTags = decodeOptions?.decodeTags !== false
   for (let i = 0; i < ntags; i++) {
     const tagId = TN[i]!
-    const tagName = tagId.slice(0, 2)
-    const tagType = tagId.slice(2, 3)
-
+    // Always decode to advance cursor position
     const tagData = compressionScheme
       .getCodecForTag(tagId)
       .decode(slice, coreDataBlock, blocksByContentId, cursors)
-    tags[tagName] =
-      tagData === undefined
-        ? undefined
-        : typeof tagData === 'number'
-          ? tagData
-          : parseTagData(tagType, tagData)
+
+    // Only parse tags if requested (default: true)
+    if (shouldDecodeTags) {
+      // Use direct character access instead of slice() to avoid string allocation
+      const tagName = tagId[0]! + tagId[1]!
+      const tagType = tagId[2]!
+      tags[tagName] =
+        tagData === undefined
+          ? undefined
+          : typeof tagData === 'number'
+            ? tagData
+            : parseTagData(tagType, tagData)
+    }
   }
 
   let readFeatures: ReadFeature[] | undefined
   let lengthOnRef: number | undefined
   let mappingQuality: number | undefined
-  let qualityScores: number[] | undefined | null
+  let qualityScores: Uint8Array | undefined | null
   let readBases = undefined
   if (!BamFlagsDecoder.isSegmentUnmapped(flags)) {
     // reading read features
@@ -373,25 +404,46 @@ export default function decodeRecord(
     mappingQuality = decodeDataSeries('MQ')!
 
     if (CramFlagsDecoder.isPreservingQualityScores(cramFlags)) {
-      qualityScores = new Array(readLength)
-      for (let i = 0; i < qualityScores.length; i++) {
-        qualityScores[i] = decodeDataSeries('QS')!
+      // Try raw bytes first (most efficient - just a subarray view)
+      const rawQS = decodeBulkBytesRaw?.('QS', readLength)
+      if (rawQS) {
+        qualityScores = rawQS
+      } else {
+        // Fallback to single-byte decoding into new Uint8Array
+        qualityScores = new Uint8Array(readLength)
+        for (let i = 0; i < readLength; i++) {
+          qualityScores[i] = decodeDataSeries('QS')!
+        }
       }
     }
   } else if (CramFlagsDecoder.isDecodeSequenceAsStar(cramFlags)) {
     readBases = null
     qualityScores = null
   } else {
-    const bases = new Array(readLength) as number[]
-    for (let i = 0; i < bases.length; i++) {
-      bases[i] = decodeDataSeries('BA')!
+    // Try raw bytes first for TextDecoder (most efficient)
+    const rawBA = decodeBulkBytesRaw?.('BA', readLength)
+    if (rawBA) {
+      readBases = textDecoder.decode(rawBA)
+    } else {
+      // Fallback to single-byte decoding
+      let s = ''
+      for (let i = 0; i < readLength; i++) {
+        s += String.fromCharCode(decodeDataSeries('BA')!)
+      }
+      readBases = s
     }
-    readBases = String.fromCharCode(...bases)
 
     if (CramFlagsDecoder.isPreservingQualityScores(cramFlags)) {
-      qualityScores = new Array(readLength)
-      for (let i = 0; i < bases.length; i++) {
-        qualityScores[i] = decodeDataSeries('QS')!
+      // Try raw bytes first (most efficient - just a subarray view)
+      const rawQS = decodeBulkBytesRaw?.('QS', readLength)
+      if (rawQS) {
+        qualityScores = rawQS
+      } else {
+        // Fallback to single-byte decoding into new Uint8Array
+        qualityScores = new Uint8Array(readLength)
+        for (let i = 0; i < readLength; i++) {
+          qualityScores[i] = decodeDataSeries('QS')!
+        }
       }
     }
   }

package/src/cramFile/slice/index.ts

@@ -1,13 +1,17 @@
 import { CramArgumentError, CramMalformedError } from '../../errors.ts'
 import { Cursors, DataTypeMapping } from '../codecs/_base.ts'
+import { DataSeriesEncodingKey } from '../codecs/dataSeriesTypes.ts'
 import { CramBufferOverrunError } from '../codecs/getBits.ts'
 import Constants from '../constants.ts'
-import decodeRecord, { DataSeriesDecoder } from './decodeRecord.ts'
-import { DataSeriesEncodingKey } from '../codecs/dataSeriesTypes.ts'
+import decodeRecord, {
+  BulkByteRawDecoder,
+  DataSeriesDecoder,
+} from './decodeRecord.ts'
+import ExternalCodec from '../codecs/external.ts'
 import { DataSeriesTypes } from '../container/compressionScheme.ts'
 import CramContainer from '../container/index.ts'
 import CramFile, { CramFileBlock } from '../file.ts'
-import CramRecord from '../record.ts'
+import CramRecord, { DecodeOptions, defaultDecodeOptions } from '../record.ts'
 import {
   MappedSliceHeader,
   UnmappedSliceHeader,
@@ -335,7 +339,7 @@ export default class CramSlice {
     return this.getRecords(() => true)
   }
 
-  async _fetchRecords() {
+  async _fetchRecords(decodeOptions: Required<DecodeOptions>) {
     const { majorVersion } = await this.file.getDefinition()
 
     const compressionScheme = await this.container.getCompressionScheme()
@@ -412,6 +416,34 @@ export default class CramSlice {
       }
       return codec.decode(this, coreDataBlock, blocksByContentId, cursors)
     }
+
+    // Create bulk byte decoder for QS and BA data series if they use External codec
+    const qsCodec = compressionScheme.getCodecForDataSeries('QS')
+    const baCodec = compressionScheme.getCodecForDataSeries('BA')
+    const qsIsExternal = qsCodec instanceof ExternalCodec
+    const baIsExternal = baCodec instanceof ExternalCodec
+    // Create raw byte decoder for QS/BA decoding
+    const decodeBulkBytesRaw: BulkByteRawDecoder | undefined =
+      qsIsExternal || baIsExternal
+        ? (dataSeriesName, length) => {
+            if (dataSeriesName === 'QS' && qsIsExternal) {
+              return qsCodec.getBytesSubarray(
+                blocksByContentId,
+                cursors,
+                length,
+              )
+            }
+            if (dataSeriesName === 'BA' && baIsExternal) {
+              return baCodec.getBytesSubarray(
+                blocksByContentId,
+                cursors,
+                length,
+              )
+            }
+            return undefined
+          }
+        : undefined
+
     const records: CramRecord[] = new Array(
       sliceHeader.parsedContent.numRecords,
     )
@@ -427,6 +459,8 @@ export default class CramSlice {
           cursors,
           majorVersion,
           i,
+          decodeOptions,
+          decodeBulkBytesRaw,
         )
         records[i] = new CramRecord({
           ...init,
@@ -474,13 +508,21 @@ export default class CramSlice {
     return records
   }
 
-  async getRecords(filterFunction: (r: CramRecord) => boolean) {
+  async getRecords(
+    filterFunction: (r: CramRecord) => boolean,
+    decodeOptions?: DecodeOptions,
+  ) {
+    // Merge with defaults
+    const opts = { ...defaultDecodeOptions, ...decodeOptions }
+
     // fetch the features if necessary, using the file-level feature cache
-    const cacheKey = this.container.filePosition + this.containerPosition
-    let recordsPromise = this.file.featureCache.get(cacheKey.toString())
+    // Include decode options in cache key so different decode configs are cached separately
+    const optionsKey = `${opts.decodeTags ? 1 : 0}`
+    const cacheKey = `${this.container.filePosition}:${this.containerPosition}:${optionsKey}`
+    let recordsPromise = this.file.featureCache.get(cacheKey)
     if (!recordsPromise) {
-      recordsPromise = this._fetchRecords()
-      this.file.featureCache.set(cacheKey.toString(), recordsPromise)
+      recordsPromise = this._fetchRecords(opts)
+      this.file.featureCache.set(cacheKey, recordsPromise)
     }
 
     const unfiltered = await recordsPromise

package/src/indexedCramFile.ts

@@ -1,7 +1,7 @@
 import { Slice } from './craiIndex.ts'
 import { SeqFetch } from './cramFile/file.ts'
 import CramFile from './cramFile/index.ts'
-import CramRecord from './cramFile/record.ts'
+import CramRecord, { DecodeOptions } from './cramFile/record.ts'
 import { CramUnimplementedError } from './errors.ts'
 
 import type { GenericFilehandle } from 'generic-filehandle2'
@@ -86,11 +86,14 @@ export default class IndexedCramFile {
       viewAsPairs?: boolean
       pairAcrossChr?: boolean
       maxInsertSize?: number
-    } = {},
+    } & DecodeOptions = {},
   ) {
-    opts.viewAsPairs = opts.viewAsPairs || false
-    opts.pairAcrossChr = opts.pairAcrossChr || false
-    opts.maxInsertSize = opts.maxInsertSize || 200000
+    const viewAsPairs = opts.viewAsPairs || false
+    const pairAcrossChr = opts.pairAcrossChr || false
+    const maxInsertSize = opts.maxInsertSize || 200000
+    const decodeOptions: DecodeOptions = {
+      decodeTags: opts.decodeTags,
+    }
 
     if (typeof seq === 'string') {
       // TODO: support string reference sequence names somehow
@@ -104,32 +107,36 @@ export default class IndexedCramFile {
     // fetch all the slices and parse the feature data
     const sliceResults = await Promise.all(
       slices.map(slice =>
-        this.getRecordsInSlice(slice, feature => {
-          // Check if feature belongs to this sequence
-          if (feature.sequenceId !== seq) {
-            return false
-          }
+        this.getRecordsInSlice(
+          slice,
+          feature => {
+            // Check if feature belongs to this sequence
+            if (feature.sequenceId !== seq) {
+              return false
+            }
+
+            // For unmapped reads (lengthOnRef is undefined), they are placed at their
+            // mate's position. Include them if that position is within the range.
+            if (feature.lengthOnRef === undefined) {
+              return (
+                feature.alignmentStart >= start && feature.alignmentStart <= end
+              )
+            }
 
-          // For unmapped reads (lengthOnRef is undefined), they are placed at their
-          // mate's position. Include them if that position is within the range.
-          if (feature.lengthOnRef === undefined) {
+            // For mapped reads, check if they overlap the requested range
+            // Use > instead of >= for start boundary to match samtools behavior
             return (
-              feature.alignmentStart >= start && feature.alignmentStart <= end
+              feature.alignmentStart <= end &&
+              feature.alignmentStart + feature.lengthOnRef - 1 > start
             )
-          }
-
-          // For mapped reads, check if they overlap the requested range
-          // Use > instead of >= for start boundary to match samtools behavior
-          return (
-            feature.alignmentStart <= end &&
-            feature.alignmentStart + feature.lengthOnRef - 1 > start
-          )
-        }),
+          },
+          decodeOptions,
+        ),
       ),
     )
 
     let ret: CramRecord[] = Array.prototype.concat(...sliceResults)
-    if (opts.viewAsPairs) {
+    if (viewAsPairs) {
       const readNames: Record<string, number> = {}
       const readIds: Record<string, number> = {}
       for (const read of ret) {
@@ -159,9 +166,9 @@ export default class IndexedCramFile {
         if (
           unmatedPairs[name] &&
           cramRecord.mate &&
-          (cramRecord.mate.sequenceId === seqId || opts.pairAcrossChr) &&
+          (cramRecord.mate.sequenceId === seqId || pairAcrossChr) &&
           Math.abs(cramRecord.alignmentStart - cramRecord.mate.alignmentStart) <
-            opts.maxInsertSize
+            maxInsertSize
         ) {
           const mateSlices = this.index.getEntriesForRange(
             cramRecord.mate.sequenceId,
@@ -225,10 +232,11 @@ export default class IndexedCramFile {
       sliceBytes,
     }: { containerStart: number; sliceStart: number; sliceBytes: number },
     filterFunction: (r: CramRecord) => boolean,
+    decodeOptions?: DecodeOptions,
   ) {
     const container = this.cram.getContainerAtPosition(containerStart)
     const slice = container.getSlice(sliceStart, sliceBytes)
-    return slice.getRecords(filterFunction)
+    return slice.getRecords(filterFunction, decodeOptions)
   }
 
   /**

package/src/wasm/noodles-cram/.gitignore

@@ -0,0 +1 @@
+*

package/src/wasm/noodles-cram/noodles_cram_wasm.d.ts

@@ -0,0 +1,42 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Get the byte position where the header ends (first data container starts)
+ *
+ * # Arguments
+ * * `data` - The CRAM file data (only needs first ~64KB typically)
+ */
+export function get_header_length(data: Uint8Array): bigint;
+
+export function init_panic_hook(): void;
+
+export function parse_crai_index(data: Uint8Array): any;
+
+export function parse_cram_file(data: Uint8Array): any;
+
+/**
+ * Parse a CRAM file with reference sequences provided
+ *
+ * # Arguments
+ * * `data` - The CRAM file data as bytes
+ * * `references` - Array of {name: string, sequence: string} objects
+ */
+export function parse_cram_file_with_references(data: Uint8Array, references: any): any;
+
+/**
+ * Parse records from a specific region of a CRAM file
+ *
+ * This function is designed for indexed access. It takes:
+ * - header_data: The CRAM file from start up to the first data container
+ * - container_data: The bytes of the container(s) to parse
+ * - references: Reference sequences needed for decoding
+ *
+ * # Arguments
+ * * `header_data` - Bytes from file start through header container
+ * * `container_data` - Bytes of the data container(s) to parse
+ * * `references` - Array of {name: string, sequence: string} objects
+ */
+export function parse_cram_records_from_container(header_data: Uint8Array, container_data: Uint8Array, references: any): any;
+
+export function parse_header(data: Uint8Array): any;

package/src/wasm/noodles-cram/noodles_cram_wasm.js

@@ -0,0 +1,5 @@
+import * as wasm from "./noodles_cram_wasm_bg.wasm";
+export * from "./noodles_cram_wasm_bg.js";
+import { __wbg_set_wasm } from "./noodles_cram_wasm_bg.js";
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();