@gmod/tabix 3.2.0 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmod/tabix",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "description": "Read Tabix-indexed files, supports both .tbi and .csi indexes",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -31,6 +31,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/tabixIndexedFile.ts --section TabixIndexedFile",
@@ -53,24 +55,24 @@
   ],
   "dependencies": {
     "@gmod/abortable-promise-cache": "^3.0.1",
-    "@gmod/bgzf-filehandle": "^6.0.3",
-    "generic-filehandle2": "^2.0.1",
-    "quick-lru": "^4.0.0"
+    "@gmod/bgzf-filehandle": "^6.0.9",
+    "@jbrowse/quick-lru": "^7.3.5",
+    "generic-filehandle2": "^2.0.16"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",
-    "@vitest/coverage-v8": "^4.0.6",
+    "@vitest/coverage-v8": "^4.0.16",
     "documentation": "^14.0.3",
-    "eslint": "^9.9.0",
+    "eslint": "^9.39.2",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-unicorn": "^62.0.0",
     "prettier": "^3.3.3",
     "rimraf": "^6.0.1",
     "standard-changelog": "^7.0.1",
     "typescript": "^5.7.0",
-    "typescript-eslint": "^8.0.1",
-    "vitest": "^4.0.6",
-    "webpack": "^5.93.0",
+    "typescript-eslint": "^8.50.1",
+    "vitest": "^4.0.16",
+    "webpack": "^5.104.1",
     "webpack-cli": "^6.0.1"
   },
   "publishConfig": {

package/src/tabixIndexedFile.ts

@@ -1,17 +1,21 @@
 import AbortablePromiseCache from '@gmod/abortable-promise-cache'
 import { unzip, unzipChunkSlice } from '@gmod/bgzf-filehandle'
+import LRU from '@jbrowse/quick-lru'
 import { LocalFile, RemoteFile } from 'generic-filehandle2'
-import LRU from 'quick-lru'
 
 import Chunk from './chunk.ts'
 import CSI from './csi.ts'
-import IndexFile, { IndexData, Options } from './indexFile.ts'
+import IndexFile, { Options } from './indexFile.ts'
 import TBI from './tbi.ts'
-import { checkAbortSignal } from './util.ts'
 
 import type { GenericFilehandle } from 'generic-filehandle2'
 
-type GetLinesCallback = (line: string, fileOffset: number) => void
+type GetLinesCallback = (
+  line: string,
+  fileOffset: number,
+  start: number,
+  end: number,
+) => void
 
 interface GetLinesOpts {
   [key: string]: unknown
@@ -29,6 +33,7 @@ export default class TabixIndexedFile {
   private filehandle: GenericFilehandle
   private index: IndexFile
   private renameRefSeq: (n: string) => string
+  private hasCustomRenameRefSeq: boolean
   private chunkCache: AbortablePromiseCache<Chunk, ReadChunk>
   public cache = new LRU<
     string,
@@ -73,7 +78,7 @@ export default class TabixIndexedFile {
     csiPath,
     csiUrl,
     csiFilehandle,
-    renameRefSeqs = n => n,
+    renameRefSeqs: renameRefSeqsPre,
     chunkCacheSize = 5 * 2 ** 20,
   }: {
     path?: string
@@ -88,6 +93,7 @@ export default class TabixIndexedFile {
     renameRefSeqs?: (n: string) => string
     chunkCacheSize?: number
   }) {
+    const renameRefSeqs = renameRefSeqsPre ?? (arg => arg)
     if (filehandle) {
       this.filehandle = filehandle
     } else if (path) {
@@ -142,6 +148,7 @@ export default class TabixIndexedFile {
     }
 
     this.renameRefSeq = renameRefSeqs
+    this.hasCustomRenameRefSeq = renameRefSeqsPre !== undefined
     this.chunkCache = new AbortablePromiseCache<Chunk, ReadChunk>({
       cache: new LRU({ maxSize: Math.floor(chunkCacheSize / (1 << 16)) }),
       fill: (args: Chunk, signal?: AbortSignal) =>
@@ -185,7 +192,7 @@ export default class TabixIndexedFile {
   ) {
     let signal: AbortSignal | undefined
     let options: Options = {}
-    let callback: (line: string, lineOffset: number) => void
+    let callback: GetLinesCallback
 
     if (typeof opts === 'function') {
       callback = opts
@@ -196,7 +203,6 @@ export default class TabixIndexedFile {
     }
 
     const metadata = await this.index.getMetadata(options)
-    checkAbortSignal(signal)
     const start = s ?? 0
     const end = e ?? metadata.maxRefLength
     if (!(start <= end)) {
@@ -209,9 +215,24 @@ export default class TabixIndexedFile {
     }
 
     const chunks = await this.index.blocksForRange(refName, start, end, options)
-    checkAbortSignal(signal)
     const decoder = new TextDecoder('utf8')
 
+    const isVCF = metadata.format === 'VCF'
+    const columnNumbersEffective = {
+      ref: metadata.columnNumbers.ref || 0,
+      start: metadata.columnNumbers.start || 0,
+      end: isVCF ? 8 : metadata.columnNumbers.end || 0,
+    }
+    const maxColumn = Math.max(
+      columnNumbersEffective.ref,
+      columnNumbersEffective.start,
+      columnNumbersEffective.end,
+    )
+    const metaCharCode = metadata.metaChar?.charCodeAt(0)
+    const coordinateOffset =
+      metadata.coordinateType === '1-based-closed' ? -1 : 0
+    const isIdentityRename = !this.hasCustomRenameRefSeq
+
     // now go through each chunk and parse and filter the lines out of it
     for (const c of chunks) {
       const { buffer, cpositions, dpositions } = await this.chunkCache.get(
@@ -220,7 +241,6 @@ export default class TabixIndexedFile {
         signal,
       )
 
-      checkAbortSignal(signal)
       let blockStart = 0
       let pos = 0
 
@@ -251,15 +271,24 @@ export default class TabixIndexedFile {
           }
 
           // filter the line for whether it is within the requested range
-          const { startCoordinate, overlaps } = this.checkLine(
-            metadata,
+          const result = this.checkLine(
             refName,
             start,
             end,
             line,
+            columnNumbersEffective.ref,
+            columnNumbersEffective.start,
+            columnNumbersEffective.end,
+            maxColumn,
+            metaCharCode,
+            coordinateOffset,
+            isVCF,
+            isIdentityRename,
           )
 
-          if (overlaps) {
+          if (result === null) {
+            return
+          } else if (result !== undefined) {
             callback(
               line,
               this.calculateFileOffset(
@@ -269,12 +298,9 @@ export default class TabixIndexedFile {
                 blockStart,
                 c.minv.dataPosition,
               ),
+              result.start,
+              result.end,
             )
-          } else if (startCoordinate !== undefined && startCoordinate >= end) {
-            // the lines were overlapping the region, but now have stopped, so we
-            // must be at the end of the relevant data and we can stop processing
-            // data now
-            return
           }
           blockStart = n + 1
         }
@@ -296,15 +322,24 @@ export default class TabixIndexedFile {
           }
 
           // filter the line for whether it is within the requested range
-          const { startCoordinate, overlaps } = this.checkLine(
-            metadata,
+          const result = this.checkLine(
             refName,
             start,
             end,
             line,
+            columnNumbersEffective.ref,
+            columnNumbersEffective.start,
+            columnNumbersEffective.end,
+            maxColumn,
+            metaCharCode,
+            coordinateOffset,
+            isVCF,
+            isIdentityRename,
           )
 
-          if (overlaps) {
+          if (result === null) {
+            return
+          } else if (result !== undefined) {
             callback(
               line,
               this.calculateFileOffset(
@@ -314,12 +349,9 @@ export default class TabixIndexedFile {
                 blockStart,
                 c.minv.dataPosition,
               ),
+              result.start,
+              result.end,
             )
-          } else if (startCoordinate !== undefined && startCoordinate >= end) {
-            // the lines were overlapping the region, but now have stopped, so we
-            // must be at the end of the relevant data and we can stop processing
-            // data now
-            return
           }
           blockStart = n + 1
         }
@@ -339,8 +371,6 @@ export default class TabixIndexedFile {
     const { firstDataLine, metaChar, maxBlockSize } =
       await this.getMetadata(opts)
 
-    checkAbortSignal(opts.signal)
-
     const maxFetch = (firstDataLine?.blockPosition || 0) + maxBlockSize
     // TODO: what if we don't have a firstDataLine, and the header actually
     // takes up more than one block? this case is not covered here
@@ -372,8 +402,6 @@ export default class TabixIndexedFile {
   /**
    * get a string containing the "header" region of the file, is the portion up
    * to the first non-meta line
-   *
-   * @returns {Promise} for a string
    */
   async getHeader(opts: Options = {}) {
     const decoder = new TextDecoder('utf8')
@@ -391,141 +419,152 @@ export default class TabixIndexedFile {
   }
 
   /**
-   * @param {object} metadata metadata object from the parsed index, containing
-   * columnNumbers, metaChar, and format
-   *
    * @param {string} regionRefName
    *
    * @param {number} regionStart region start coordinate (0-based-half-open)
    *
    * @param {number} regionEnd region end coordinate (0-based-half-open)
    *
-   * @param {array[string]} line
+   * @param {string} line
+   *
+   * @param {number} refColumn column number for ref
+   *
+   * @param {number} startColumn column number for start
+   *
+   * @param {number} endColumn column number for end
+   *
+   * @param {number} maxColumn pre-calculated max column
+   *
+   * @param {number} metaCharCode pre-calculated metaChar code
    *
-   * @returns {object} like `{startCoordinate, overlaps}`. overlaps is boolean,
-   * true if line is a data line that overlaps the given region
+   * @param {number} coordinateOffset 0 or -1 for coordinate adjustment
+   *
+   * @param {boolean} isVCF whether this is VCF format
+   *
+   * @param {boolean} isIdentityRename whether renameRefSeq is the identity function
+   *
+   * @returns {{ start: number, end: number } | null | undefined} coordinates if overlapping, null if should stop processing, undefined otherwise
    */
   checkLine(
-    metadata: IndexData,
     regionRefName: string,
     regionStart: number,
     regionEnd: number,
     line: string,
-  ) {
-    const { columnNumbers, metaChar, coordinateType, format } = metadata
-    // skip meta lines
-    if (metaChar && line.startsWith(metaChar)) {
-      return { overlaps: false }
+    refColumn: number,
+    startColumn: number,
+    endColumn: number,
+    maxColumn: number,
+    metaCharCode: number | undefined,
+    coordinateOffset: number,
+    isVCF: boolean,
+    isIdentityRename: boolean,
+  ): { start: number; end: number } | null | undefined {
+    if (metaCharCode !== undefined && line.charCodeAt(0) === metaCharCode) {
+      return
     }
 
-    // check ref/start/end using column metadata from index
-    let { ref, start, end } = columnNumbers
-    if (!ref) {
-      ref = 0
+    // Length-based fast path: split for short lines, indexOf for long lines
+    // Split is faster for short lines, but slow for long lines with big attribute columns
+    if (line.length < 500) {
+      const fields = line.split('\t')
+      const ref = fields[refColumn - 1]!
+      const refMatch = isIdentityRename
+        ? ref === regionRefName
+        : this.renameRefSeq(ref) === regionRefName
+      if (!refMatch) {
+        return
+      }
+
+      const startCoordinate = +fields[startColumn - 1]! + coordinateOffset
+      if (startCoordinate >= regionEnd) {
+        return null
+      }
+
+      let endCoordinate: number
+      if (endColumn === 0 || endColumn === startColumn) {
+        endCoordinate = startCoordinate + 1
+      } else if (isVCF) {
+        endCoordinate = this._getVcfEnd(
+          startCoordinate,
+          fields[3]!,
+          fields[endColumn - 1]!,
+        )
+      } else {
+        endCoordinate = +fields[endColumn - 1]!
+      }
+
+      if (endCoordinate <= regionStart) {
+        return
+      }
+      return { start: startCoordinate, end: endCoordinate }
     }
-    if (!start) {
-      start = 0
+
+    // Long lines - use indexOf chain (avoids parsing long attribute column)
+    let prev = -1
+    const tabs = [-1]
+    for (let i = 0; i < maxColumn; i++) {
+      const pos = line.indexOf('\t', prev + 1)
+      if (pos === -1) {
+        tabs.push(line.length)
+        break
+      }
+      tabs.push(pos)
+      prev = pos
     }
-    if (!end) {
-      end = 0
+
+    const ref = line.slice(tabs[refColumn - 1]! + 1, tabs[refColumn])
+    const refMatch = isIdentityRename
+      ? ref === regionRefName
+      : this.renameRefSeq(ref) === regionRefName
+    if (!refMatch) {
+      return
     }
-    if (format === 'VCF') {
-      end = 8
+
+    const startCoordinate =
+      +line.slice(tabs[startColumn - 1]! + 1, tabs[startColumn]) +
+      coordinateOffset
+    if (startCoordinate >= regionEnd) {
+      return null
     }
-    const maxColumn = Math.max(ref, start, end)
-
-    // this code is kind of complex, but it is fairly fast. basically, we want
-    // to avoid doing a split, because if the lines are really long that could
-    // lead to us allocating a bunch of extra memory, which is slow
-
-    let currentColumnNumber = 1 // cols are numbered starting at 1 in the index metadata
-    let currentColumnStart = 0
-    let refSeq = ''
-    let startCoordinate = -Infinity
-    const l = line.length
-    for (let i = 0; i < l + 1; i++) {
-      if (line[i] === '\t' || i === l) {
-        if (currentColumnNumber === ref) {
-          if (
-            this.renameRefSeq(line.slice(currentColumnStart, i)) !==
-            regionRefName
-          ) {
-            return {
-              overlaps: false,
-            }
-          }
-        } else if (currentColumnNumber === start) {
-          startCoordinate = Number.parseInt(
-            line.slice(currentColumnStart, i),
-            10,
-          )
-          // we convert to 0-based-half-open
-          if (coordinateType === '1-based-closed') {
-            startCoordinate -= 1
-          }
-          if (startCoordinate >= regionEnd) {
-            return {
-              startCoordinate,
-              overlaps: false,
-            }
-          }
-          if (
-            (end === 0 || end === start) && // if we have no end, we assume the feature is 1 bp long
-            startCoordinate + 1 <= regionStart
-          ) {
-            return {
-              startCoordinate,
-              overlaps: false,
-            }
-          }
-        } else if (format === 'VCF' && currentColumnNumber === 4) {
-          refSeq = line.slice(currentColumnStart, i)
-        } else if (currentColumnNumber === end) {
-          // this will never match if there is no end column
-          const endCoordinate =
-            format === 'VCF'
-              ? this._getVcfEnd(
-                  startCoordinate,
-                  refSeq,
-                  line.slice(currentColumnStart, i),
-                )
-              : Number.parseInt(line.slice(currentColumnStart, i), 10)
-          if (endCoordinate <= regionStart) {
-            return {
-              overlaps: false,
-            }
-          }
-        }
-        if (currentColumnNumber === maxColumn) {
-          break
-        }
-        currentColumnStart = i + 1
-        currentColumnNumber += 1
-      }
+
+    let endCoordinate: number
+    if (endColumn === 0 || endColumn === startColumn) {
+      endCoordinate = startCoordinate + 1
+    } else if (isVCF) {
+      endCoordinate = this._getVcfEnd(
+        startCoordinate,
+        line.slice(tabs[3]! + 1, tabs[4]),
+        line.slice(tabs[endColumn - 1]! + 1, tabs[endColumn]),
+      )
+    } else {
+      endCoordinate = +line.slice(tabs[endColumn - 1]! + 1, tabs[endColumn])
     }
-    return {
-      startCoordinate,
-      overlaps: true,
+
+    if (endCoordinate <= regionStart) {
+      return
     }
+
+    return { start: startCoordinate, end: endCoordinate }
   }
 
   _getVcfEnd(startCoordinate: number, refSeq: string, info: any) {
     let endCoordinate = startCoordinate + refSeq.length
-    // ignore TRA features as they specify CHR2 and END as being on a different
-    // chromosome
-    //
-    // if CHR2 is on the same chromosome, still ignore it because there should
-    // be another pairwise feature at the end of this one
     const isTRA = info.includes('SVTYPE=TRA')
-    if (info[0] !== '.' && !isTRA) {
-      const endRegex = /(?:^|;)END=([^;]+)/
-      const match = endRegex.exec(info)
-      if (match) {
-        endCoordinate = Number.parseInt(match[1]!, 10)
-      }
-    } else if (isTRA) {
+    if (isTRA) {
       return startCoordinate + 1
     }
+
+    if (info[0] !== '.') {
+      const endIdx = info.indexOf('END=')
+      if (endIdx !== -1 && (endIdx === 0 || info[endIdx - 1] === ';')) {
+        const start = endIdx + 4
+        let end = info.indexOf(';', start)
+        if (end === -1) {
+          end = info.length
+        }
+        endCoordinate = Number.parseInt(info.slice(start, end), 10)
+      }
+    }
     return endCoordinate
   }
 

package/src/tbi.ts

@@ -3,7 +3,7 @@ import { unzip } from '@gmod/bgzf-filehandle'
 import Chunk from './chunk.ts'
 import IndexFile, { Options } from './indexFile.ts'
 import { longFromBytesToUnsigned } from './long.ts'
-import { checkAbortSignal, optimizeChunks } from './util.ts'
+import { optimizeChunks } from './util.ts'
 import VirtualOffset, { fromBytes } from './virtualOffset.ts'
 
 const TBI_MAGIC = 21578324 // TBI\1
@@ -44,7 +44,6 @@ export default class TabixIndex extends IndexFile {
   async _parse(opts: Options = {}) {
     const buf = await this.filehandle.readFile(opts)
     const bytes = await unzip(buf)
-    checkAbortSignal(opts.signal)
     const dataView = new DataView(bytes.buffer)
 
     const magic = dataView.getUint32(0, true)

package/src/util.ts

@@ -1,48 +1,6 @@
 import Chunk from './chunk.ts'
 import VirtualOffset from './virtualOffset.ts'
 
-class AbortError extends Error {
-  public code: string | undefined
-}
-/**
- * Properly check if the given AbortSignal is aborted. Per the standard, if the
- * signal reads as aborted, this function throws either a DOMException
- * AbortError, or a regular error with a `code` attribute set to `ERR_ABORTED`.
- *
- * For convenience, passing `undefined` is a no-op
- *
- * @param {AbortSignal} [signal] an AbortSignal, or anything with an `aborted`
- * attribute
- *
- * @returns nothing
- */
-export function checkAbortSignal(signal?: AbortSignal) {
-  if (!signal) {
-    return
-  }
-
-  if (signal.aborted) {
-    if (typeof DOMException === 'undefined') {
-      const e = new AbortError('aborted')
-      e.code = 'ERR_ABORTED'
-      throw e
-    } else {
-      throw new DOMException('aborted', 'AbortError')
-    }
-  }
-}
-
-/**
- * Skips to the next tick, then runs `checkAbortSignal`.
- * Await this to inside an otherwise synchronous loop to
- * provide a place to break when an abort signal is received.
- * @param {AbortSignal} signal
- */
-export async function abortBreakPoint(signal?: AbortSignal) {
-  await Promise.resolve()
-  checkAbortSignal(signal)
-}
-
 export function canMergeBlocks(chunk1: Chunk, chunk2: Chunk) {
   return (
     chunk2.minv.blockPosition - chunk1.maxv.blockPosition < 65000 &&