gff-nostream 3.0.11 → 5.0.0

package/src/util.ts

@@ -1,10 +1,6 @@
-// Fast, low-level functions for parsing and formatting GFF3.
+// Fast, low-level functions for parsing GFF3.
 // JavaScript port of Robert Buels's Bio::GFF3::LowLevel Perl module.
 
-const directiveRegex = /^\s*##\s*(\S+)\s*(.*)/
-const whitespaceRegex = /\s+/
-const nonDigitRegex = /\D/g
-
 const HEX_LOOKUP: Record<string, string | undefined> = {}
 for (let i = 0; i < 256; i++) {
   const hex = i.toString(16).toUpperCase().padStart(2, '0')
@@ -18,7 +14,6 @@ for (let i = 0; i < 256; i++) {
  * @param stringVal - Escaped GFF3 string value
  * @returns An unescaped string value
  */
-
 export function unescape(stringVal: string) {
   const idx = stringVal.indexOf('%')
   if (idx === -1) {
@@ -30,18 +25,17 @@ export function unescape(stringVal: string) {
   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)
-      }
+    const char =
+      stringVal[i] === '%' && i + 2 < stringVal.length
+        ? HEX_LOOKUP[stringVal.slice(i + 1, i + 3)]
+        : undefined
+    if (char !== undefined) {
+      result += stringVal.slice(lastIdx, i) + char
       i += 3
       lastIdx = i
     } else {
+      // Not a valid escape: advance one char so a '%' that begins a real
+      // escape immediately after isn't swallowed (e.g. the %20 in "a%b%20c").
       i++
     }
   }
@@ -49,79 +43,6 @@ export function unescape(stringVal: string) {
   return result + stringVal.slice(lastIdx)
 }
 
-function parseAttributesImpl(
-  attrString: string,
-  shouldUnescape: boolean,
-): 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
-        }
-
-        let valStart = eqIdx + 1
-        while (valStart < semiIdx) {
-          let commaIdx = attrString.indexOf(',', valStart)
-          if (commaIdx === -1 || commaIdx > semiIdx) {
-            commaIdx = semiIdx
-          }
-          if (commaIdx > valStart) {
-            const val = attrString.slice(valStart, commaIdx)
-            arec.push(shouldUnescape ? unescape(val) : val)
-          }
-          valStart = commaIdx + 1
-        }
-      }
-    }
-    start = semiIdx + 1
-  }
-  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.
- *
- * @param attrString - String of GFF3 9th column
- * @returns Parsed attributes
- */
-export function parseAttributesNoUnescape(attrString: string): GFF3Attributes {
-  return parseAttributesImpl(attrString, false)
-}
-
 function isEmpty(s: string) {
   return s.length === 0 || s === '.'
 }
@@ -134,189 +55,6 @@ function strField<E extends null | ''>(
   return isEmpty(s) ? empty : shouldUnescape ? unescape(s) : s
 }
 
-function numField(s: string) {
-  return isEmpty(s) ? null : +s
-}
-
-function parseFeatureImpl(
-  line: string,
-  shouldUnescape: boolean,
-): GFF3FeatureLine {
-  const f = line.split('\t')
-  const attrString = f[8]!
-  return {
-    seq_id: strField(f[0]!, shouldUnescape, null),
-    source: strField(f[1]!, shouldUnescape, null),
-    type: strField(f[2]!, shouldUnescape, null),
-    start: numField(f[3]!),
-    end: numField(f[4]!),
-    score: numField(f[5]!),
-    strand: strField(f[6]!, false, null),
-    phase: strField(f[7]!, false, null),
-    attributes: isEmpty(attrString)
-      ? null
-      : parseAttributesImpl(attrString, shouldUnescape),
-  }
-}
-
-/**
- * Parse a GFF3 feature line
- *
- * @param line - GFF3 feature line
- * @returns The parsed feature
- */
-export function parseFeature(line: string): GFF3FeatureLine {
-  return parseFeatureImpl(line, true)
-}
-
-/**
- * Parse a GFF3 feature line without unescaping.
- * Fast path for data known to contain no escaped characters.
- *
- * @param line - GFF3 feature line
- * @returns The parsed feature
- */
-export function parseFeatureNoUnescape(line: string): GFF3FeatureLine {
-  return parseFeatureImpl(line, false)
-}
-
-/**
- * Parse a GFF3 directive line.
- *
- * @param line - GFF3 directive line
- * @returns The parsed directive
- */
-export function parseDirective(
-  line: string,
-):
-  | GFF3Directive
-  | GFF3SequenceRegionDirective
-  | GFF3GenomeBuildDirective
-  | null {
-  const match = directiveRegex.exec(line)
-  if (!match) {
-    return null
-  }
-
-  const name = match[1]!
-  const contents = match[2]!
-
-  const parsed: GFF3Directive = { directive: name }
-  if (contents.length) {
-    parsed.value = contents.trimEnd()
-  }
-
-  if (name === 'sequence-region') {
-    const c = contents.split(whitespaceRegex, 3)
-    return {
-      ...parsed,
-      seq_id: c[0]!,
-      start: c[1]!.replaceAll(nonDigitRegex, ''),
-      end: c[2]!.replaceAll(nonDigitRegex, ''),
-    }
-  } else if (name === 'genome-build') {
-    const [source, buildName] = contents.split(whitespaceRegex, 2)
-    return {
-      ...parsed,
-      source: source!,
-      buildName: buildName!,
-    }
-  }
-
-  return parsed
-}
-
-/** A record of GFF3 attribute identifiers and the values of those identifiers */
-export type GFF3Attributes = Record<string, string[] | undefined>
-
-/** A representation of a single line of a GFF3 file */
-export interface GFF3FeatureLine {
-  /** The ID of the landmark used to establish the coordinate system for the current feature */
-  seq_id: string | null
-  /** A free text qualifier intended to describe the algorithm or operating procedure that generated this feature */
-  source: string | null
-  /** The type of the feature */
-  type: string | null
-  /** The start coordinates of the feature */
-  start: number | null
-  /** The end coordinates of the feature */
-  end: number | null
-  /** The score of the feature */
-  score: number | null
-  /** The strand of the feature */
-  strand: string | null
-  /** For features of type "CDS", the phase indicates where the next codon begins relative to the 5' end of the current CDS feature */
-  phase: string | null
-  /** Feature attributes */
-  attributes: GFF3Attributes | null
-}
-
-/**
- * A GFF3 Feature line that includes references to other features defined in
- * their "Parent" or "Derives_from" attributes
- */
-export interface GFF3FeatureLineWithRefs extends GFF3FeatureLine {
-  /** An array of child features */
-  child_features: GFF3Feature[]
-  /** An array of features derived from this feature */
-  derived_features: GFF3Feature[]
-}
-
-/**
- * A GFF3 feature, which may include multiple individual feature lines
- */
-export type GFF3Feature = GFF3FeatureLineWithRefs[]
-
-/** A GFF3 directive */
-export interface GFF3Directive {
-  /** The name of the directive */
-  directive: string
-  /** The string value of the directive */
-  value?: string
-}
-
-/** A GFF3 sequence-region directive */
-export interface GFF3SequenceRegionDirective extends GFF3Directive {
-  /** The string value of the directive */
-  value: string
-  /** The sequence ID parsed from the directive */
-  seq_id: string
-  /** The sequence start parsed from the directive */
-  start: string
-  /** The sequence end parsed from the directive */
-  end: string
-}
-
-/** A GFF3 genome-build directive */
-export interface GFF3GenomeBuildDirective extends GFF3Directive {
-  /** The string value of the directive */
-  value: string
-  /** The genome build source parsed from the directive */
-  source: string
-  /** The genome build name parsed from the directive */
-  buildName: string
-}
-
-/** A GFF3 comment */
-export interface GFF3Comment {
-  /** The text of the comment */
-  comment: string
-}
-
-/** A GFF3 FASTA single sequence */
-export interface GFF3Sequence {
-  /** The ID of the sequence */
-  id: string
-  /** The description of the sequence */
-  description?: string
-  /** The sequence */
-  sequence: string
-}
-
-export type GFF3Item = GFF3Feature | GFF3Directive | GFF3Comment | GFF3Sequence
-
-// JBrowse format types and parsing functions
-
 const JBROWSE_DEFAULT_FIELDS = new Set([
   'start',
   'end',
@@ -352,7 +90,18 @@ const COMMON_ATTRS: Record<string, string | undefined> = {
   gap: 'gap',
 }
 
-export interface JBrowseFeature {
+const STRAND_MAP: Record<string, number | undefined> = {
+  '+': 1,
+  '-': -1,
+  '.': 0,
+}
+
+/**
+ * A parsed GFF3 feature: a flat object with 0-based half-open coordinates,
+ * numeric strand (`1`/`-1`/`0`), attributes spread as lowercase top-level keys,
+ * and child features nested under `subfeatures`.
+ */
+export interface GffFeature {
   start: number
   end: number
   strand?: number
@@ -361,11 +110,16 @@ export interface JBrowseFeature {
   refName: string
   phase?: number
   score?: number
-  subfeatures: JBrowseFeature[]
+  subfeatures: GffFeature[]
   [key: string]: unknown
 }
 
-function parseAttributesJBrowseImpl(
+/**
+ * Parse the 9th column (attributes) of a GFF3 feature line into `result`,
+ * lowercasing keys and suffixing any that collide with a default field name.
+ * Pass shouldUnescape=false as a fast path for data with no escaped characters.
+ */
+export function parseAttributes(
   attrString: string,
   result: Record<string, unknown>,
   shouldUnescape: boolean,
@@ -420,38 +174,23 @@ function parseAttributesJBrowseImpl(
   }
 }
 
-export function parseAttributesJBrowse(
-  attrString: string,
-  result: Record<string, unknown>,
-) {
-  parseAttributesJBrowseImpl(attrString, result, true)
-}
-
-export function parseAttributesJBrowseNoUnescape(
-  attrString: string,
-  result: Record<string, unknown>,
-) {
-  parseAttributesJBrowseImpl(attrString, result, false)
-}
-
-const STRAND_MAP: Record<string, number | undefined> = {
-  '+': 1,
-  '-': -1,
-  '.': 0,
-}
-
-function parseFeatureJBrowseImpl(
-  line: string,
-  shouldUnescape: boolean,
-): JBrowseFeature {
+/**
+ * Parse a GFF3 feature line. Unescaping is skipped entirely for lines with no
+ * '%' character, which is the common case.
+ *
+ * @param line - GFF3 feature line
+ * @returns The parsed feature
+ */
+export function parseFeature(line: string): GffFeature {
   const f = line.split('\t')
+  const shouldUnescape = line.includes('%')
   const startStr = f[3]!
   const endStr = f[4]!
   const scoreStr = f[5]!
   const phase = f[7]!
   const attrString = f[8]!
 
-  const result: JBrowseFeature = {
+  const result: GffFeature = {
     refName: strField(f[0]!, shouldUnescape, ''),
     source: strField(f[1]!, shouldUnescape, null),
     type: strField(f[2]!, shouldUnescape, null),
@@ -463,14 +202,6 @@ function parseFeatureJBrowseImpl(
     subfeatures: [],
   }
 
-  parseAttributesJBrowseImpl(attrString, result, shouldUnescape)
+  parseAttributes(attrString, result, shouldUnescape)
   return result
 }
-
-export function parseFeatureJBrowse(line: string): JBrowseFeature {
-  return parseFeatureJBrowseImpl(line, true)
-}
-
-export function parseFeatureJBrowseNoUnescape(line: string): JBrowseFeature {
-  return parseFeatureJBrowseImpl(line, false)
-}