@gmod/bgzf-filehandle

中文文档
6.8.5发布于 2026/11/16MITTypeScriptESM + CJS构建来源已验证近 30 天下载 10万

read from a compressed bgzip file (with .gzi) as if it were uncompressed

原始使用文档
文档目录7 节
  1. Install
  2. BgzfFilehandle
  3. unzip
  4. unzipChunkSlice
  5. Docs
  6. Academic use
  7. License

@gmod/bgzf-filehandle

NPM version Build Status

Reads block-gzipped (BGZF) files using uncompressed coordinates. @gmod/bam, @gmod/tabix and @gmod/indexedfasta build on it.

  • In: a bgzip file and its .gzi index, or a chunk from a BAI/TBI index
  • Out: the decompressed bytes
  • Inflates with libdeflate compiled to WebAssembly and inlined as base64, so there is no .wasm file to serve. On this repo's fixtures it runs 2-3x faster than pako (benchmarks)

Install

npm install @gmod/bgzf-filehandle

BgzfFilehandle

import { BgzfFilehandle } from '@gmod/bgzf-filehandle'
import { LocalFile } from 'generic-filehandle2'

const f = new BgzfFilehandle({
  filehandle: new LocalFile('my_file.gz'),
  gziFilehandle: new LocalFile('my_file.gz.gzi'),
})

const data = await f.read(300, 0) // length, position

Create the index with bgzip -i my_file, or bgzip -r my_file.gz for an existing file. For a remote file, wrap it in @gmod/range-cache-filehandle.

unzip

Decompresses a BGZF or plain gzip buffer:

import { unzip } from '@gmod/bgzf-filehandle'

const decompressed = await unzip(compressedData)

unzipChunkSlice

Decompresses a chunk {minv, maxv} from a BAI or TBI index, where each end is a virtual offset {blockPosition, dataPosition}:

import { MAX_BGZF_BLOCK_SIZE, unzipChunkSlice } from '@gmod/bgzf-filehandle'

// read one max-size block past maxv, since nothing records that block's length
const compressedData = await filehandle.read(
  maxv.blockPosition + MAX_BGZF_BLOCK_SIZE - minv.blockPosition,
  minv.blockPosition,
)
const { buffer, cpositions, dpositions } = await unzipChunkSlice(
  compressedData,
  { minv, maxv },
)

cpositions and dpositions hold block boundaries, for building feature IDs that stay stable across chunks.

A third argument spreads the blocks across Web Workers, which makes a multi-megabyte chunk 1.1-2.0x faster (docs/worker-pool.md):

import { getSharedWorkerPool } from '@gmod/bgzf-filehandle'

const pool = await getSharedWorkerPool() // undefined without Worker support
const result = await unzipChunkSlice(compressedData, { minv, maxv }, pool)

unzipChunkSegments takes the same arguments and skips the final copy into one buffer, for readers that can parse across segment boundaries (docs/worker-pool.md).

Docs

Academic use

Written with NHGRI funding as part of JBrowse. If you use this in a publication, please cite the most recent JBrowse paper at jbrowse.org.

License

MIT © Robert Buels, Colin Diesh

版本与发布记录

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

版本发布日期距今
6.8.5latest2026/11/161 天前
6.8.42026/10/3117 天前
6.8.32026/10/3017 天前
6.8.22026/10/1730 天前
6.8.12026/10/1730 天前
6.8.02026/10/151 个月前

关于 @gmod/bgzf-filehandle 的常见问题

@gmod/bgzf-filehandle 是什么?

read from a compressed bgzip file (with .gzi) as if it were uncompressed

如何安装 @gmod/bgzf-filehandle?

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

@gmod/bgzf-filehandle 支持 TypeScript 吗?

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

@gmod/bgzf-filehandle 支持 ESM 还是 CommonJS?

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

@gmod/bgzf-filehandle 可以商用吗?

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

@gmod/bgzf-filehandle 的下载量有多少?

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

@gmod/bgzf-filehandle 还在维护吗?

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