@gmod/inflate

中文文档
1.0.0发布于 2026/08/17MITTypeScriptESM + CJS零依赖近 30 天下载 1.1万

Fast DEFLATE decompression via wasm libdeflate, inlined as a single bundle

原始使用文档
文档目录10 节
  1. Install
  2. Usage
  3. API
  4. inflateRaw(input, outputSize): Promise<Uint8Array>
  5. inflateRawUnknownSize(input): Promise<Uint8Array>
  6. inflateRawBatch(inputs, offsets, lengths, maxBlockSize): Pr…
  7. Integrity
  8. Why not DecompressionStream ?
  9. Building
  10. License

@gmod/inflate

NPM version Build Status

DEFLATE decompression through a wasm libdeflate build, shipped as one self-contained bundle with the wasm inlined as base64 — no separate .wasm fetch, no build tooling for consumers.

It exists for one shape in particular: a file holding hundreds of separately compressed blocks. inflateRawBatch inflates a whole run of them in a single JS↔wasm crossing, which is what the platform's DecompressionStream cannot do, and roughly 4x faster than pako on the block sizes genomics formats use.

Install

$ npm install @gmod/inflate

Usage

import { inflateRaw, inflateRawBatch } from '@gmod/inflate'

// One block, size known from an index
const plain = await inflateRaw(rawDeflateBytes, uncompressedSize)

// A run of blocks packed in one buffer — one crossing for all of them
const { data, offsets } = await inflateRawBatch(
  buffer, // concatenated compressed bytes
  new Uint32Array([0, 512, 1400]), // where each block starts
  new Uint32Array([512, 888, 640]), // how long each is
  65536, // the largest any one inflates to
)
for (let i = 0; i < offsets.length - 1; i++) {
  const block = data.subarray(offsets[i], offsets[i + 1])
}

The wasm module instantiates lazily on the first call and is shared from then on, so there is nothing to initialize and no teardown.

API

inflateRaw(input, outputSize): Promise<Uint8Array>

One raw deflate stream whose uncompressed size is already known. This is the path worth reaching for: libdeflate writes straight into an exactly-sized buffer with no growth loop and no streaming state. Formats that record the uncompressed size in their index — bigwig, .hic, bgzf — can always use it.

input must not include a zlib header. If your bytes start with one (0x78), pass input.subarray(2).

inflateRawUnknownSize(input): Promise<Uint8Array>

The same, when the size is not recorded. Doubles a guess until it fits, so it costs a re-inflate per doubling. Prefer inflateRaw where you can.

inflateRawBatch(inputs, offsets, lengths, maxBlockSize): Promise<BatchResult>

Many blocks, one call. inputs is the concatenated compressed bytes and offsets/lengths (both Uint32Array) locate each block within it. maxBlockSize is the largest size any single block inflates to.

Unlike inflateRaw, each block here is expected to carry its 2-byte zlib header; the wasm skips it internally.

Returns { data, offsets }, where data is every block's bytes concatenated and offsets has blocks + 1 marks, so block i is data.subarray(offsets[i], offsets[i + 1]).

Integrity

Raw deflate carries no checksum — zlib's adler32 lives in the 4-byte trailer these entry points skip past. A corruption that still forms a legal bit stream decodes to the wrong bytes without an error. Callers needing integrity should take it from their container: bgzf's per-block CRC, or a mismatch against the uncompressed size an index recorded.

Corrupt input that is not a legal stream rejects normally, and the wasm instance stays usable for later calls.

Why not DecompressionStream?

The platform has had one since 2023, and for a single large buffer it is a fine answer. For a file of many small blocks it is not: its cost is dominated by a fixed per-call overhead, and a caller must reach it once per block. Measured across three GMOD parsers, the container's shape decides the result:

containershapevs wasm
bigwighundreds of small blocks4-11x
.hicfewer, larger blocks~2-7x
bgzfconcatenated members, 1 call~2x

inflateRawBatch is the answer to that per-call cost: it pays the crossing once for the whole group.

It is also only baseline since May 2023 (Safari 16.4, Firefox 113), so a fallback ships regardless — which removes the one remaining argument for it, the bundle saving.

Building

The tracked src/wasm/inflate-wasm-inlined.js is generated, and rebuilding it needs a Rust toolchain plus wasm-bindgen-cli:

$ pnpm build:wasm

It must rebuild byte-for-byte — preversion runs pnpm build, so a non-reproducible bundle would mean npm version quietly committing an artifact nobody reviewed, part-way through a release. git status clean after pnpm build:wasm is the check.

License

MIT

版本与发布记录

@gmod/inflate 共发布 2 个版本,首次发布于 2026/08/17;过去 12 个月发布了 2 个版本。

版本发布日期距今
1.0.0latest2026/08/172 个月前
0.0.02026/08/172 个月前

关于 @gmod/inflate 的常见问题

@gmod/inflate 是什么?

Fast DEFLATE decompression via wasm libdeflate, inlined as a single bundle

如何安装 @gmod/inflate?

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

@gmod/inflate 支持 TypeScript 吗?

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

@gmod/inflate 支持 ESM 还是 CommonJS?

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

@gmod/inflate 可以商用吗?

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

@gmod/inflate 的下载量有多少?

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

@gmod/inflate 还在维护吗?

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