gff-nostream 3.0.1 → 3.0.4

package/src/api.ts

@@ -43,15 +43,14 @@ export function parseStringSyncJBrowse(str: string): JBrowseFeature[] {
 function stringToRecords(str: string) {
   const lines = str.split(/\r?\n/)
   const records: LineRecord[] = []
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]!
-    if (line.length === 0 || line[0] === '#') {
+  for (const line of lines) {
+    if (line.length === 0 || line.startsWith('#')) {
       if (line.startsWith('##FASTA')) {
         break
       }
       continue
     }
-    if (line[0] === '>') {
+    if (line.startsWith('>')) {
       break
     }
     records.push({
@@ -76,8 +75,7 @@ export function parseRecords(records: LineRecord[]): GFF3Feature[] {
   const byId = new Map<string, GFF3Feature>()
   const orphans = new Map<string, GFF3Feature[]>()
 
-  for (let i = 0; i < records.length; i++) {
-    const record = records[i]!
+  for (const record of records) {
     const featureLine = (
       record.hasEscapes
         ? parseFeature(record.line)
@@ -87,9 +85,7 @@ export function parseRecords(records: LineRecord[]): GFF3Feature[] {
     featureLine.derived_features = []
 
     if (record.lineHash !== undefined) {
-      if (!featureLine.attributes) {
-        featureLine.attributes = {}
-      }
+      featureLine.attributes ??= {}
       featureLine.attributes._lineHash = [String(record.lineHash)]
     }
 
@@ -104,7 +100,7 @@ export function parseRecords(records: LineRecord[]): GFF3Feature[] {
 
     let feature: GFF3Feature
     if (ids) {
-      const id = ids[0]!
+      const id = ids[0]
       const existing = byId.get(id)
       if (existing) {
         existing.push(featureLine)
@@ -117,8 +113,8 @@ export function parseRecords(records: LineRecord[]): GFF3Feature[] {
         byId.set(id, feature)
         const waiting = orphans.get(id)
         if (waiting) {
-          for (let j = 0; j < waiting.length; j++) {
-            featureLine.child_features.push(waiting[j]!)
+          for (const w of waiting) {
+            featureLine.child_features.push(w)
           }
           orphans.delete(id)
         }
@@ -128,12 +124,11 @@ export function parseRecords(records: LineRecord[]): GFF3Feature[] {
     }
 
     if (parents) {
-      for (let j = 0; j < parents.length; j++) {
-        const parentId = parents[j]!
+      for (const parentId of parents) {
         const parent = byId.get(parentId)
         if (parent) {
-          for (let k = 0; k < parent.length; k++) {
-            parent[k]!.child_features.push(feature)
+          for (const p of parent) {
+            p.child_features.push(feature)
           }
         } else {
           let arr = orphans.get(parentId)
@@ -162,8 +157,7 @@ export function parseRecordsJBrowse(records: LineRecord[]): JBrowseFeature[] {
   const byId = new Map<string, JBrowseFeature>()
   const orphans = new Map<string, JBrowseFeature[]>()
 
-  for (let i = 0; i < records.length; i++) {
-    const record = records[i]!
+  for (const record of records) {
     const feature = record.hasEscapes
       ? parseFeatureJBrowse(record.line)
       : parseFeatureJBrowseNoUnescape(record.line)
@@ -189,8 +183,8 @@ export function parseRecordsJBrowse(records: LineRecord[]): JBrowseFeature[] {
         byId.set(id, feature)
         const waiting = orphans.get(id)
         if (waiting) {
-          for (let j = 0; j < waiting.length; j++) {
-            feature.subfeatures.push(waiting[j]!)
+          for (const w of waiting) {
+            feature.subfeatures.push(w)
           }
           orphans.delete(id)
         }
@@ -199,8 +193,7 @@ export function parseRecordsJBrowse(records: LineRecord[]): JBrowseFeature[] {
 
     if (parent) {
       const parents = Array.isArray(parent) ? parent : [parent]
-      for (let j = 0; j < parents.length; j++) {
-        const parentId = parents[j]!
+      for (const parentId of parents) {
         const parentFeature = byId.get(parentId)
         if (parentFeature) {
           parentFeature.subfeatures.push(feature)

package/src/util.ts

@@ -1,17 +1,12 @@
 // Fast, low-level functions for parsing and formatting GFF3.
 // JavaScript port of Robert Buels's Bio::GFF3::LowLevel Perl module.
 
-const escapeRegex = /%([0-9A-Fa-f]{2})/g
 const directiveRegex = /^\s*##\s*(\S+)\s*(.*)/
 const lineEndRegex = /\r?\n$/
 const whitespaceRegex = /\s+/
 const nonDigitRegex = /\D/g
-// eslint-disable-next-line no-control-regex
-const attrEscapeRegex = /[\n;\r\t=%&,\u0000-\u001f\u007f-\u00ff]/g
-// eslint-disable-next-line no-control-regex
-const columnEscapeRegex = /[\n\r\t%\u0000-\u001f\u007f-\u00ff]/g
 
-const HEX_LOOKUP: Record<string, string> = {}
+const HEX_LOOKUP: Record<string, string | undefined> = {}
 for (let i = 0; i < 256; i++) {
   const hex = i.toString(16).toUpperCase().padStart(2, '0')
   HEX_LOOKUP[hex] = String.fromCharCode(i)
@@ -25,17 +20,40 @@ for (let i = 0; i < 256; i++) {
  * @returns An unescaped string value
  */
 
-export function unescape(s: string): string {
-  return s.indexOf('%') === -1 ? s : decodeURIComponent(s)
+export function unescape(stringVal: string) {
+  const idx = stringVal.indexOf('%')
+  if (idx === -1) {
+    return stringVal
+  }
+
+  let result = ''
+  let lastIdx = 0
+  let i = idx
+
+  while (i < stringVal.length) {
+    if (stringVal[i] === '%' && i + 2 < stringVal.length) {
+      result += stringVal.slice(lastIdx, i)
+      const hex = stringVal.slice(i + 1, i + 3)
+      const char = HEX_LOOKUP[hex]
+      if (char !== undefined) {
+        result += char
+      } else {
+        result += stringVal.slice(i, i + 3)
+      }
+      i += 3
+      lastIdx = i
+    } else {
+      i++
+    }
+  }
+
+  return result + stringVal.slice(lastIdx)
 }
 
-/**
- * Parse the 9th column (attributes) of a GFF3 feature line.
- *
- * @param attrString - String of GFF3 9th column
- * @returns Parsed attributes
- */
-export function parseAttributes(attrString: string): GFF3Attributes {
+function parseAttributesImpl(
+  attrString: string,
+  shouldUnescape: boolean,
+): GFF3Attributes {
   if (attrString.length === 0 || attrString === '.') {
     return {}
   }
@@ -73,7 +91,7 @@ export function parseAttributes(attrString: string): GFF3Attributes {
           }
           if (commaIdx > valStart) {
             const val = attrString.slice(valStart, commaIdx)
-            arec.push(unescape(val))
+            arec.push(shouldUnescape ? unescape(val) : val)
           }
           valStart = commaIdx + 1
         }
@@ -84,6 +102,16 @@ export function parseAttributes(attrString: string): GFF3Attributes {
   return attrs
 }
 
+/**
+ * Parse the 9th column (attributes) of a GFF3 feature line.
+ *
+ * @param attrString - String of GFF3 9th column
+ * @returns Parsed attributes
+ */
+export function parseAttributes(attrString: string): GFF3Attributes {
+  return parseAttributesImpl(attrString, true)
+}
+
 /**
  * Parse the 9th column (attributes) of a GFF3 feature line without unescaping.
  * Fast path for data known to contain no escaped characters.
@@ -92,59 +120,42 @@ export function parseAttributes(attrString: string): GFF3Attributes {
  * @returns Parsed attributes
  */
 export function parseAttributesNoUnescape(attrString: string): GFF3Attributes {
-  if (attrString.length === 0 || attrString === '.') {
-    return {}
-  }
-
-  const attrs: GFF3Attributes = {}
-  let len = attrString.length
-
-  if (attrString[len - 1] === '\n') {
-    len = attrString[len - 2] === '\r' ? len - 2 : len - 1
-    attrString = attrString.slice(0, len)
-  }
-
-  let start = 0
-  while (start < len) {
-    let semiIdx = attrString.indexOf(';', start)
-    if (semiIdx === -1) {
-      semiIdx = len
-    }
-
-    if (semiIdx > start) {
-      const eqIdx = attrString.indexOf('=', start)
-      if (eqIdx !== -1 && eqIdx < semiIdx && eqIdx + 1 < semiIdx) {
-        const tag = attrString.slice(start, eqIdx)
-        let arec = attrs[tag]
-        if (!arec) {
-          arec = []
-          attrs[tag] = arec
-        }
+  return parseAttributesImpl(attrString, false)
+}
 
-        let valStart = eqIdx + 1
-        while (valStart < semiIdx) {
-          let commaIdx = attrString.indexOf(',', valStart)
-          if (commaIdx === -1 || commaIdx > semiIdx) {
-            commaIdx = semiIdx
-          }
-          if (commaIdx > valStart) {
-            arec.push(attrString.slice(valStart, commaIdx))
-          }
-          valStart = commaIdx + 1
-        }
-      }
-    }
-    start = semiIdx + 1
+function normImpl(s: string, shouldUnescape: boolean) {
+  if (s.length === 0 || s === '.') {
+    return null
   }
-  return attrs
+  return shouldUnescape ? unescape(s) : s
 }
 
-function normUnescape(s: string) {
-  return s.length === 0 || s === '.' ? null : unescape(s)
-}
+function parseFeatureImpl(
+  line: string,
+  shouldUnescape: boolean,
+): GFF3FeatureLine {
+  const f = line.split('\t')
+  const startStr = f[3]
+  const endStr = f[4]
+  const scoreStr = f[5]
+  const strand = f[6]
+  const phase = f[7]
+  const attrString = f[8]
 
-function norm(s: string) {
-  return s.length === 0 || s === '.' ? null : s
+  return {
+    seq_id: normImpl(f[0], shouldUnescape),
+    source: normImpl(f[1], shouldUnescape),
+    type: normImpl(f[2], shouldUnescape),
+    start: startStr.length === 0 || startStr === '.' ? null : +startStr,
+    end: endStr.length === 0 || endStr === '.' ? null : +endStr,
+    score: scoreStr.length === 0 || scoreStr === '.' ? null : +scoreStr,
+    strand: normImpl(strand, false),
+    phase: normImpl(phase, false),
+    attributes:
+      attrString.length === 0 || attrString === '.'
+        ? null
+        : parseAttributesImpl(attrString, shouldUnescape),
+  }
 }
 
 /**
@@ -154,28 +165,7 @@ function norm(s: string) {
  * @returns The parsed feature
  */
 export function parseFeature(line: string): GFF3FeatureLine {
-  const f = line.split('\t')
-  const seq_id = f[0]!
-  const source = f[1]!
-  const type = f[2]!
-  const startStr = f[3]!
-  const endStr = f[4]!
-  const scoreStr = f[5]!
-  const strand = f[6]!
-  const phase = f[7]!
-  const attrString = f[8]!
-
-  return {
-    seq_id: normUnescape(seq_id),
-    source: normUnescape(source),
-    type: normUnescape(type),
-    start: startStr.length === 0 || startStr === '.' ? null : +startStr,
-    end: endStr.length === 0 || endStr === '.' ? null : +endStr,
-    score: scoreStr.length === 0 || scoreStr === '.' ? null : +scoreStr,
-    strand: norm(strand),
-    phase: norm(phase),
-    attributes: attrString.length === 0 || attrString === '.' ? null : parseAttributes(attrString),
-  }
+  return parseFeatureImpl(line, true)
 }
 
 /**
@@ -186,38 +176,12 @@ export function parseFeature(line: string): GFF3FeatureLine {
  * @returns The parsed feature
  */
 export function parseFeatureNoUnescape(line: string): GFF3FeatureLine {
-  const f = line.split('\t')
-  const seq_id = f[0]!
-  const source = f[1]!
-  const type = f[2]!
-  const startStr = f[3]!
-  const endStr = f[4]!
-  const scoreStr = f[5]!
-  const strand = f[6]!
-  const phase = f[7]!
-  const attrString = f[8]!
-
-  return {
-    seq_id: norm(seq_id),
-    source: norm(source),
-    type: norm(type),
-    start: startStr.length === 0 || startStr === '.' ? null : +startStr,
-    end: endStr.length === 0 || endStr === '.' ? null : +endStr,
-    score: scoreStr.length === 0 || scoreStr === '.' ? null : +scoreStr,
-    strand: norm(strand),
-    phase: norm(phase),
-    attributes: attrString.length === 0 || attrString === '.' ? null : parseAttributesNoUnescape(attrString),
-  }
+  return parseFeatureImpl(line, false)
 }
 
-/**
- * Parse a GFF3 feature from a pre-split fields array
- *
- * @param f - Array of 9 GFF3 column values (use null or '.' for empty values)
- * @returns The parsed feature
- */
-export function parseFieldsArray(
+function parseFieldsArrayImpl(
   f: (string | null | undefined)[],
+  shouldUnescape: boolean,
 ): GFF3FeatureLine {
   const seq_id = f[0]
   const source = f[1]
@@ -230,18 +194,33 @@ export function parseFieldsArray(
   const attrString = f[8]
 
   return {
-    seq_id: seq_id ? normUnescape(seq_id) : null,
-    source: source ? normUnescape(source) : null,
-    type: type ? normUnescape(type) : null,
+    seq_id: seq_id ? normImpl(seq_id, shouldUnescape) : null,
+    source: source ? normImpl(source, shouldUnescape) : null,
+    type: type ? normImpl(type, shouldUnescape) : null,
     start: !startStr || startStr === '.' ? null : +startStr,
     end: !endStr || endStr === '.' ? null : +endStr,
     score: !scoreStr || scoreStr === '.' ? null : +scoreStr,
     strand: strand && strand !== '.' ? strand : null,
     phase: phase && phase !== '.' ? phase : null,
-    attributes: !attrString || attrString === '.' ? null : parseAttributes(attrString),
+    attributes:
+      !attrString || attrString === '.'
+        ? null
+        : parseAttributesImpl(attrString, shouldUnescape),
   }
 }
 
+/**
+ * Parse a GFF3 feature from a pre-split fields array
+ *
+ * @param f - Array of 9 GFF3 column values (use null or '.' for empty values)
+ * @returns The parsed feature
+ */
+export function parseFieldsArray(
+  f: (string | null | undefined)[],
+): GFF3FeatureLine {
+  return parseFieldsArrayImpl(f, true)
+}
+
 /**
  * Parse a GFF3 feature from a pre-split fields array without unescaping.
  * Fast path for data known to contain no escaped characters.
@@ -252,27 +231,7 @@ export function parseFieldsArray(
 export function parseFieldsArrayNoUnescape(
   f: (string | null | undefined)[],
 ): GFF3FeatureLine {
-  const seq_id = f[0]
-  const source = f[1]
-  const type = f[2]
-  const startStr = f[3]
-  const endStr = f[4]
-  const scoreStr = f[5]
-  const strand = f[6]
-  const phase = f[7]
-  const attrString = f[8]
-
-  return {
-    seq_id: seq_id && seq_id !== '.' ? seq_id : null,
-    source: source && source !== '.' ? source : null,
-    type: type && type !== '.' ? type : null,
-    start: !startStr || startStr === '.' ? null : +startStr,
-    end: !endStr || endStr === '.' ? null : +endStr,
-    score: !scoreStr || scoreStr === '.' ? null : +scoreStr,
-    strand: strand && strand !== '.' ? strand : null,
-    phase: phase && phase !== '.' ? phase : null,
-    attributes: !attrString || attrString === '.' ? null : parseAttributesNoUnescape(attrString),
-  }
+  return parseFieldsArrayImpl(f, false)
 }
 
 /**
@@ -297,27 +256,26 @@ export function parseDirective(
   let [, , contents] = match
 
   const parsed: GFF3Directive = { directive: name }
-  if (contents!.length) {
-    contents = contents!.replace(lineEndRegex, '')
+  if (contents.length) {
+    contents = contents.replace(lineEndRegex, '')
     parsed.value = contents
   }
 
-  // do a little additional parsing for sequence-region and genome-build directives
   if (name === 'sequence-region') {
-    const c = contents!.split(whitespaceRegex, 3)
+    const c = contents.split(whitespaceRegex, 3)
     return {
       ...parsed,
       seq_id: c[0],
       start: c[1]?.replaceAll(nonDigitRegex, ''),
       end: c[2]?.replaceAll(nonDigitRegex, ''),
-    } as GFF3SequenceRegionDirective
+    }
   } else if (name === 'genome-build') {
-    const [source, buildName] = contents!.split(whitespaceRegex, 2)
+    const [source, buildName] = contents.split(whitespaceRegex, 2)
     return {
       ...parsed,
       source,
       buildName,
-    } as GFF3GenomeBuildDirective
+    }
   }
 
   return parsed
@@ -425,6 +383,30 @@ const JBROWSE_DEFAULT_FIELDS = new Set([
   'strand',
 ])
 
+// Pre-computed lowercase for common GFF3 spec attribute names to avoid
+// toLowerCase() calls in the hot path
+const COMMON_ATTRS: Record<string, string | undefined> = {
+  ID: 'id',
+  Name: 'name',
+  Parent: 'parent',
+  Note: 'note',
+  Dbxref: 'dbxref',
+  Ontology_term: 'ontology_term',
+  Is_circular: 'is_circular',
+  Alias: 'alias',
+  Target: 'target',
+  Gap: 'gap',
+  Derives_from: 'derives_from',
+  id: 'id',
+  name: 'name',
+  parent: 'parent',
+  note: 'note',
+  dbxref: 'dbxref',
+  alias: 'alias',
+  target: 'target',
+  gap: 'gap',
+}
+
 export interface JBrowseFeature {
   start: number
   end: number
@@ -438,22 +420,10 @@ export interface JBrowseFeature {
   [key: string]: unknown
 }
 
-function parseStrand(s: string) {
-  if (s === '+') {
-    return 1
-  }
-  if (s === '-') {
-    return -1
-  }
-  if (s === '.') {
-    return 0
-  }
-  return undefined
-}
-
-export function parseAttributesJBrowse(
+function parseAttributesJBrowseImpl(
   attrString: string,
   result: Record<string, unknown>,
+  shouldUnescape: boolean,
 ) {
   if (attrString.length === 0 || attrString === '.') {
     return
@@ -481,9 +451,12 @@ export function parseAttributesJBrowse(
           continue
         }
 
-        let key = tag.toLowerCase()
-        if (JBROWSE_DEFAULT_FIELDS.has(key)) {
-          key += '2'
+        let key = COMMON_ATTRS[tag]
+        if (key === undefined) {
+          key = tag.toLowerCase()
+          if (JBROWSE_DEFAULT_FIELDS.has(key)) {
+            key += '2'
+          }
         }
 
         const values: string[] = []
@@ -495,7 +468,7 @@ export function parseAttributesJBrowse(
           }
           if (commaIdx > valStart) {
             const val = attrString.slice(valStart, commaIdx)
-            values.push(unescape(val))
+            values.push(shouldUnescape ? unescape(val) : val)
           }
           valStart = commaIdx + 1
         }
@@ -507,113 +480,71 @@ export function parseAttributesJBrowse(
   }
 }
 
-export function parseAttributesJBrowseNoUnescape(
+export function parseAttributesJBrowse(
   attrString: string,
   result: Record<string, unknown>,
 ) {
-  if (attrString.length === 0 || attrString === '.') {
-    return
-  }
-
-  let len = attrString.length
-  if (attrString[len - 1] === '\n') {
-    len = attrString[len - 2] === '\r' ? len - 2 : len - 1
-    attrString = attrString.slice(0, len)
-  }
-
-  let start = 0
-  while (start < len) {
-    let semiIdx = attrString.indexOf(';', start)
-    if (semiIdx === -1) {
-      semiIdx = len
-    }
-
-    if (semiIdx > start) {
-      const eqIdx = attrString.indexOf('=', start)
-      if (eqIdx !== -1 && eqIdx < semiIdx && eqIdx + 1 < semiIdx) {
-        const tag = attrString.slice(start, eqIdx)
-        if (tag === '_lineHash') {
-          start = semiIdx + 1
-          continue
-        }
-
-        let key = tag.toLowerCase()
-        if (JBROWSE_DEFAULT_FIELDS.has(key)) {
-          key += '2'
-        }
-
-        const values: string[] = []
-        let valStart = eqIdx + 1
-        while (valStart < semiIdx) {
-          let commaIdx = attrString.indexOf(',', valStart)
-          if (commaIdx === -1 || commaIdx > semiIdx) {
-            commaIdx = semiIdx
-          }
-          if (commaIdx > valStart) {
-            values.push(attrString.slice(valStart, commaIdx))
-          }
-          valStart = commaIdx + 1
-        }
+  parseAttributesJBrowseImpl(attrString, result, true)
+}
 
-        result[key] = values.length === 1 ? values[0] : values
-      }
-    }
-    start = semiIdx + 1
-  }
+export function parseAttributesJBrowseNoUnescape(
+  attrString: string,
+  result: Record<string, unknown>,
+) {
+  parseAttributesJBrowseImpl(attrString, result, false)
 }
 
-export function parseFeatureJBrowse(line: string): JBrowseFeature {
+function parseFeatureJBrowseImpl(
+  line: string,
+  shouldUnescape: boolean,
+): JBrowseFeature {
   const f = line.split('\t')
-  const seq_id = f[0]!
-  const source = f[1]!
-  const type = f[2]!
-  const startStr = f[3]!
-  const endStr = f[4]!
-  const scoreStr = f[5]!
-  const strand = f[6]!
-  const phase = f[7]!
-  const attrString = f[8]!
+  const seq_id = f[0]
+  const source = f[1]
+  const type = f[2]
+  const startStr = f[3]
+  const endStr = f[4]
+  const scoreStr = f[5]
+  const strand = f[6]
+  const phase = f[7]
+  const attrString = f[8]
 
   const result: JBrowseFeature = {
-    refName: seq_id.length === 0 || seq_id === '.' ? '' : unescape(seq_id),
-    source: source.length === 0 || source === '.' ? null : unescape(source),
-    type: type.length === 0 || type === '.' ? null : unescape(type),
+    refName:
+      seq_id.length === 0 || seq_id === '.'
+        ? ''
+        : shouldUnescape
+          ? unescape(seq_id)
+          : seq_id,
+    source:
+      source.length === 0 || source === '.'
+        ? null
+        : shouldUnescape
+          ? unescape(source)
+          : source,
+    type:
+      type.length === 0 || type === '.'
+        ? null
+        : shouldUnescape
+          ? unescape(type)
+          : type,
     start: startStr.length === 0 || startStr === '.' ? 0 : +startStr - 1,
     end: endStr.length === 0 || endStr === '.' ? 0 : +endStr,
     score: scoreStr.length === 0 || scoreStr === '.' ? undefined : +scoreStr,
-    strand: parseStrand(strand),
+    strand:
+      strand === '+' ? 1 : strand === '-' ? -1 : strand === '.' ? 0 : undefined,
     phase: phase.length === 0 || phase === '.' ? undefined : +phase,
     subfeatures: [],
   }
 
-  parseAttributesJBrowse(attrString, result)
+  parseAttributesJBrowseImpl(attrString, result, shouldUnescape)
   return result
 }
 
-export function parseFeatureJBrowseNoUnescape(line: string): JBrowseFeature {
-  const f = line.split('\t')
-  const seq_id = f[0]!
-  const source = f[1]!
-  const type = f[2]!
-  const startStr = f[3]!
-  const endStr = f[4]!
-  const scoreStr = f[5]!
-  const strand = f[6]!
-  const phase = f[7]!
-  const attrString = f[8]!
-
-  const result: JBrowseFeature = {
-    refName: seq_id.length === 0 || seq_id === '.' ? '' : seq_id,
-    source: source.length === 0 || source === '.' ? null : source,
-    type: type.length === 0 || type === '.' ? null : type,
-    start: startStr.length === 0 || startStr === '.' ? 0 : +startStr - 1,
-    end: endStr.length === 0 || endStr === '.' ? 0 : +endStr,
-    score: scoreStr.length === 0 || scoreStr === '.' ? undefined : +scoreStr,
-    strand: parseStrand(strand),
-    phase: phase.length === 0 || phase === '.' ? undefined : +phase,
-    subfeatures: [],
-  }
+export function parseFeatureJBrowse(line: string): JBrowseFeature {
+  return parseFeatureJBrowseImpl(line, true)
+}
 
-  parseAttributesJBrowseNoUnescape(attrString, result)
-  return result
+export function parseFeatureJBrowseNoUnescape(line: string): JBrowseFeature {
+  return parseFeatureJBrowseImpl(line, false)
 }