gff-nostream 3.0.10 → 4.0.0

package/src/api.ts

@@ -1,15 +1,6 @@
-import {
-  parseFeature,
-  parseFeatureJBrowse,
-  parseFeatureJBrowseNoUnescape,
-  parseFeatureNoUnescape,
-} from './util.ts'
-
-import type {
-  GFF3Feature,
-  GFF3FeatureLineWithRefs,
-  JBrowseFeature,
-} from './util.ts'
+import { parseFeature } from './util.ts'
+
+import type { GffFeature } from './util.ts'
 
 interface ParseInput {
   line: string
@@ -45,8 +36,8 @@ function appendOrphan<T>(orphans: Map<string, T[]>, key: string, value: T) {
 }
 
 /**
- * The JBrowse parser collapses single-element attribute arrays to scalars, so a
- * raw ID/Parent value can be a string, a string array, or absent. These coerce
+ * The parser collapses single-element attribute arrays to scalars, so a raw
+ * ID/Parent value can be a string, a string array, or absent. These coerce
  * those `unknown` values without typecasts.
  */
 function firstString(value: unknown): string | undefined {
@@ -63,25 +54,15 @@ function toStringArray(value: unknown): string[] {
 
 /**
  * Synchronously parse a string containing GFF3 and return an array of the
- * parsed items.
+ * parsed features. Comments, directives, and `##FASTA` sections are ignored.
  *
  * @param str - GFF3 string
  * @returns array of parsed features
  */
-export function parseStringSync(str: string): GFF3Feature[] {
+export function parseStringSync(str: string): GffFeature[] {
   return parseRecords(stringToRecords(str))
 }
 
-/**
- * Synchronously parse a string containing GFF3 directly into JBrowse format.
- *
- * @param str - GFF3 string
- * @returns array of JBrowse-format features
- */
-export function parseStringSyncJBrowse(str: string): JBrowseFeature[] {
-  return parseRecordsJBrowse(stringToRecords(str))
-}
-
 function stringToRecords(str: string) {
   const lines = str.split(/\r?\n/)
   const records: ParseInput[] = []
@@ -102,102 +83,18 @@ function stringToRecords(str: string) {
 
 /**
  * Parse an array of LineRecord objects containing raw GFF3 lines.
- * Supports parent/child relationships.
- *
- * @param records - Array of LineRecord objects with raw line and metadata
- * @returns array of parsed features
- */
-export function parseRecords(records: ParseInput[]): GFF3Feature[] {
-  const items: GFF3Feature[] = []
-  const byId = new Map<string, GFF3Feature>()
-  const orphans = new Map<string, GFF3Feature[]>()
-
-  for (const record of records) {
-    const parsed = record.hasEscapes
-      ? parseFeature(record.line)
-      : parseFeatureNoUnescape(record.line)
-    const featureLine: GFF3FeatureLineWithRefs = {
-      ...parsed,
-      child_features: [],
-      derived_features: [],
-    }
-
-    if (record.lineHash !== undefined) {
-      featureLine.attributes ??= {}
-      featureLine.attributes._lineHash = [String(record.lineHash)]
-    }
-
-    const attrs = featureLine.attributes
-    const ids = attrs?.ID
-    const parents = attrs?.Parent
-
-    if (!ids && !parents) {
-      items.push([featureLine])
-    } else {
-      let feature: GFF3Feature
-      if (ids) {
-        const id = ids[0]!
-        const existing = byId.get(id)
-        if (existing) {
-          // Multi-location continuation: share child_features/derived_features
-          // with the first line so children remain visible across all lines
-          // regardless of arrival order.
-          featureLine.child_features = existing[0]!.child_features
-          featureLine.derived_features = existing[0]!.derived_features
-          existing.push(featureLine)
-          feature = existing
-        } else {
-          feature = [featureLine]
-          if (!parents) {
-            items.push(feature)
-          }
-          byId.set(id, feature)
-          const waiting = orphans.get(id)
-          if (waiting) {
-            for (const w of waiting) {
-              featureLine.child_features.push(w)
-            }
-            orphans.delete(id)
-          }
-        }
-      } else {
-        feature = [featureLine]
-      }
-
-      if (parents) {
-        for (const parentId of parents) {
-          const parent = byId.get(parentId)
-          if (parent) {
-            // child_features is shared across all parent feature lines,
-            // so push once via the first line.
-            parent[0]!.child_features.push(feature)
-          } else {
-            appendOrphan(orphans, parentId, feature)
-          }
-        }
-      }
-    }
-  }
-
-  return items
-}
-
-/**
- * Parse an array of LineRecord objects directly into JBrowse feature format.
  * Supports parent/child relationships via subfeatures.
  *
  * @param records - Array of LineRecord objects with raw line and metadata
- * @returns array of JBrowse-format features
+ * @returns array of parsed features
  */
-export function parseRecordsJBrowse(records: ParseInput[]): JBrowseFeature[] {
-  const items: JBrowseFeature[] = []
-  const byId = new Map<string, JBrowseFeature>()
-  const orphans = new Map<string, JBrowseFeature[]>()
+export function parseRecords(records: ParseInput[]): GffFeature[] {
+  const items: GffFeature[] = []
+  const byId = new Map<string, GffFeature>()
+  const orphans = new Map<string, GffFeature[]>()
 
   for (const record of records) {
-    const feature = record.hasEscapes
-      ? parseFeatureJBrowse(record.line)
-      : parseFeatureJBrowseNoUnescape(record.line)
+    const feature = parseFeature(record.line, record.hasEscapes)
 
     if (record.lineHash !== undefined) {
       feature._lineHash = String(record.lineHash)
@@ -206,34 +103,35 @@ export function parseRecordsJBrowse(records: ParseInput[]): JBrowseFeature[] {
     const id = firstString(feature.id)
     const parents = toStringArray(feature.parent)
 
-    if (!id && parents.length === 0) {
+    // A parentless line is a top-level item. Every line of a top-level
+    // discontinuous feature (e.g. cDNA_match/EST_match spanning several
+    // segments under one shared ID, with no Parent) is its own top-level
+    // item, so push regardless of whether the id is already registered.
+    if (parents.length === 0) {
       items.push(feature)
-    } else {
-      // Register the id only the first time it is seen. Continuation lines
-      // (multi-location features such as a CDS spanning several segments share
-      // one ID across lines) skip registration but must still be attached to
-      // their parent below, so this is independent of the parent handling.
-      if (id && !byId.has(id)) {
-        if (parents.length === 0) {
-          items.push(feature)
-        }
-        byId.set(id, feature)
-        const waiting = orphans.get(id)
-        if (waiting) {
-          for (const w of waiting) {
-            feature.subfeatures.push(w)
-          }
-          orphans.delete(id)
+    }
+
+    // Register the id only the first time it is seen. Continuation lines
+    // (multi-location features such as a CDS spanning several segments share
+    // one ID across lines) skip registration but must still be attached to
+    // their parent below, so this is independent of the parent handling.
+    if (id && !byId.has(id)) {
+      byId.set(id, feature)
+      const waiting = orphans.get(id)
+      if (waiting) {
+        for (const w of waiting) {
+          feature.subfeatures.push(w)
         }
+        orphans.delete(id)
       }
+    }
 
-      for (const parentId of parents) {
-        const parentFeature = byId.get(parentId)
-        if (parentFeature) {
-          parentFeature.subfeatures.push(feature)
-        } else {
-          appendOrphan(orphans, parentId, feature)
-        }
+    for (const parentId of parents) {
+      const parentFeature = byId.get(parentId)
+      if (parentFeature) {
+        parentFeature.subfeatures.push(feature)
+      } else {
+        appendOrphan(orphans, parentId, feature)
       }
     }
   }
@@ -241,13 +139,4 @@ export function parseRecordsJBrowse(records: ParseInput[]): JBrowseFeature[] {
   return items
 }
 
-export type {
-  GFF3Comment,
-  GFF3Directive,
-  GFF3Feature,
-  GFF3FeatureLine,
-  GFF3FeatureLineWithRefs,
-  GFF3Item,
-  GFF3Sequence,
-  JBrowseFeature,
-} from './util.ts'
+export type { GffFeature } from './util.ts'

package/src/index.ts

@@ -1,19 +1,3 @@
-export {
-  extractType,
-  parseRecords,
-  parseRecordsJBrowse,
-  parseStringSync,
-  parseStringSyncJBrowse,
-} from './api.ts'
+export { extractType, parseRecords, parseStringSync } from './api.ts'
 
-export type {
-  GFF3Comment,
-  GFF3Directive,
-  GFF3Feature,
-  GFF3FeatureLine,
-  GFF3FeatureLineWithRefs,
-  GFF3Item,
-  GFF3Sequence,
-  JBrowseFeature,
-  LineRecord,
-} from './api.ts'
+export type { GffFeature, LineRecord } from './api.ts'

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,30 +174,15 @@ 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. Pass shouldUnescape=false as a fast path for data
+ * known to contain no escaped characters.
+ *
+ * @param line - GFF3 feature line
+ * @param shouldUnescape - whether to unescape percent-encoded values
+ * @returns The parsed feature
+ */
+export function parseFeature(line: string, shouldUnescape: boolean): GffFeature {
   const f = line.split('\t')
   const startStr = f[3]!
   const endStr = f[4]!
@@ -451,7 +190,7 @@ function parseFeatureJBrowseImpl(
   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)
-}