@gmod/gff-nostream

中文文档
5.6.6发布于 2026/11/16MITTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 1.3万

utilities to read GFF3 data

原始使用文档
文档目录12 节
  1. Install
  2. Usage
  3. Object format
  4. Parsing behavior
  5. Multi-location features
  6. Lazy parsing
  7. API
  8. Parsing
  9. Attributes
  10. Other
  11. Types
  12. Contributing

@gmod/gff-nostream

NPM version Build Status

Parses GFF3 data, as a simplified version of @gmod/gff with no Node.js stream dependency.

Install

pnpm add @gmod/gff-nostream

Usage

import { readFileSync } from 'node:fs'
import { parseStringSync } from '@gmod/gff-nostream'

const features = parseStringSync(readFileSync('my_annotations.gff3', 'utf8'))

In the browser, pass any GFF3 string, such as one from fetch(…).then(r => r.text()). For a remote .gff3.gz, query it with @gmod/tabix and pass the returned lines to parseLines.

Object format

  • Coordinates are 0-based half-open.
  • strand is a number (1/-1/0).
  • Attributes become lowercase top-level keys, unwrapped from their array when single-valued.
  • Child features nest under subfeatures.
{
  "refName": "ctg123",
  "source": null,
  "type": "gene",
  "start": 999,
  "end": 9000,
  "strand": 1,
  "subfeatures": [
    {
      "refName": "ctg123",
      "source": null,
      "type": "mRNA",
      "start": 1049,
      "end": 9000,
      "strand": 1,
      "subfeatures": [],
      "id": "mRNA00001",
      "parent": "gene00001",
      "name": "EDEN.1"
    }
  ],
  "id": "gene00001",
  "name": "EDEN"
}

The parser appends 2 to an attribute whose lowercased name matches a fixed field (refName, source, type, start, end, score, strand, phase, subfeatures, seq_id, refname), so Start= becomes start2.

Parsing behavior

  • The parser ignores comments, directives, and ##FASTA sections.
  • The parser trims spaces around attribute tags, so Name=A; ID=x has an ID.
  • A feature whose Parent is missing from the input, as when a tabix query cuts off the parent line, comes back as a top-level feature.

Multi-location features

A multi-location feature has the same ID on several lines, such as a CDS spanning several segments.

  • With no parent, the first line becomes one feature spanning every segment, with each segment as a subfeature of the same type. An NCBI cDNA_match comes back this way.
  • With a parent, each line stays a separate feature under it, as for a multi-exon CDS. The parser still merges an ID that another line names as its parent, such as an NCBI frameshift CDS (SARS-CoV-2 ORF1ab) with mature peptides under it.
  • Lines that differ in type, or whose first line already has children, stay separate duplicates.

Lazy parsing

Every parse function has a …Lazy counterpart that leaves column 9 as raw text on feature.attributeString instead of spreading it into keys. It reads only ID and Parent, since it cannot build the tree without them.

import { getAttribute, parseLinesLazy } from '@gmod/gff-nostream'

const features = parseLinesLazy(lines)
const names = features.map(f => getAttribute(f, 'name'))

Lazy parsing pays off only when most attributes go unread, since each getAttribute rescans the string. See docs/lazy-parsing.md.

API

Parsing

parseStringSync(str: string): GffFeature[]

Parse a GFF3 string.

parseLines(lines: readonly string[]): GffFeature[]

Parse GFF3 feature lines, such as a tabix query returns. The lines must contain no blanks, comments, or ##FASTA section.

parseRecords<R extends LineRecord>(records: readonly R[]): ParsedRecord<R>[]

Parse an array of records wrapping raw GFF3 lines.

The parser pairs each top-level feature with its source record, extra fields included, so a caller can attach its own stable id.

const records = lines.map((line, i) => ({ line, offset: offsets[i] }))
const features = parseRecords(records).map(({ feature, record }) => ({
  ...feature,
  id: record.offset,
}))

parseLinesLazy / parseRecordsLazy

Like parseLines and parseRecords, returning LazyGffFeatures. See Lazy parsing.

parseFeatureLazy(line: string): LazyGffFeature

Parse a single line, with no tree building.

Attributes

getAttribute(feature: LazyGffFeature, key: string): unknown

One attribute by its parsed key (lowercased, 2-suffixed if reserved), in the shape the eager parser produces.

getAttributes(feature: LazyGffFeature): Record<string, unknown>

Every attribute, as the eager parser would spread them.

getLinkAttributes(feature: LazyGffFeature): { id: unknown; parent: unknown }

ID and Parent in one pass, for callers doing their own linking.

Other

extractType(line: string): string

The feature type (column 3) of a raw line, or '' for a line with fewer than two tabs.

hasIdAttribute(line: string): boolean

Whether a raw line has an ID the parser would link children to, by the parser's own tag scan.

Types

interface LineRecord {
  line: string
}

interface ParsedRecord<R extends LineRecord = LineRecord> {
  feature: GffFeature
  record: R
}

ParsedLazyRecord is ParsedRecord with a LazyGffFeature.

Contributing

See CONTRIBUTING.md for development and release steps.

版本与发布记录

@gmod/gff-nostream 共发布 8 个版本,首次发布于 2026/10/08;过去 12 个月发布了 8 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.6.6latest2026/11/16今天
5.6.52026/11/161 天前
5.6.42026/10/3017 天前
5.6.32026/10/3017 天前
5.6.22026/10/151 个月前
5.6.12026/10/081 个月前

关于 @gmod/gff-nostream 的常见问题

@gmod/gff-nostream 是什么?

utilities to read GFF3 data

如何安装 @gmod/gff-nostream?

在项目目录运行 npm install @gmod/gff-nostream,或使用 pnpm add / yarn add / bun add。

@gmod/gff-nostream 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gmod/gff-nostream 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gmod/gff-nostream 可以商用吗?

@gmod/gff-nostream 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gmod/gff-nostream 的下载量有多少?

根据 npm 官方下载统计,@gmod/gff-nostream 在 2026/10/17 – 2026/11/15 这 30 天内被下载 12,571 次,日均约 419 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gmod/gff-nostream 还在维护吗?

最新版本 5.6.6 发布于 2026/11/16(今天);至今共发布 8 个版本,其中过去 12 个月发布了 8 个;首次发布于 2026/10/08。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。