@gmod/cram

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

read CRAM files with pure Javascript

原始使用文档
文档目录9 节
  1. Quick start
  2. Mismatches
  3. Records
  4. Header, reference names and cancellation
  5. Performance
  6. Script tag
  7. Docs
  8. Academic use
  9. License

@gmod/cram

NPM version Build Status

Read CRAM files in node or the browser.

  • Handles CRAM 2.x and 3.x, .crai indexes, and every v3 and v3.1 codec, including fqzcomp and tok3.
  • The codecs are the htscodecs C library that samtools uses, compiled to WebAssembly and inlined in the bundle, so there is no .wasm file to serve.
  • Golomb and Golomb-Rice, which only v2 files use, are not implemented.
npm install @gmod/cram

Quick start

import { IndexedCramFile, CraiIndex } from '@gmod/cram'
import { IndexedFasta } from '@gmod/indexedfasta'
import { RemoteFile } from 'generic-filehandle2'

const fasta = new IndexedFasta({
  fasta: new RemoteFile('https://example.com/reference.fa'),
  fai: new RemoteFile('https://example.com/reference.fa.fai'),
})

const indexedFile = new IndexedCramFile({
  cramUrl: 'https://example.com/file.cram',
  index: new CraiIndex({ url: 'https://example.com/file.cram.crai' }),
  fetchReferenceSequence: (seqId, start, end, refName, opts) =>
    fasta.getSequence(refName, start, end, opts),
})

const records = await indexedFile.getRecordsForRange('chr1', 10000, 20000)

for (const record of records) {
  for (const { code, refPos, bases } of record.getMismatches()) {
    console.log(record.readName, String.fromCharCode(code), refPos, bases)
  }
}

For local files, pass cramPath, CraiIndex({ path }) and IndexedFasta({ path }).

  • Coordinates are 0-based half-open, as in @gmod/bam; add 1 for a 1-based format such as SAM's POS.
  • Query a reference by its name in the file's header, such as chr1, 1 or CHROMOSOME_I. A name the file lacks returns [].

Mismatches

record.getMismatches() lists substitutions, insertions, deletions, reference skips and clips, and forEachMismatch passes them to a callback instead. code is a CIGAR char code (88 for X).

import { RF_SUBST } from '@gmod/cram'

record.forEachMismatch(
  (code, refPos, length, bases, qual, refBaseCode, clipLength) => {
    if (code === RF_SUBST) {
      console.log(refPos, bases)
    }
  },
  { start: 10000, end: 20000 }, // optional window
)

Substitutions need the quick start's fetchReferenceSequence, and read N without it. See Mismatch for the fields and window, and Reference sequence for the callback.

Records

record.getReadBases() // 'ACGT…', the read sequence
record.getCigarString() // '50M2I48M'
record.getTag('NM') // one auxiliary tag
record.qualityScoreAt(0) // one base quality
record.isReverseComplemented() // the usual SAM flags

docs/api.md lists every property and method.

Header, reference names and cancellation

await indexedFile.cram.getReferenceInfo() // [{ name, length, md5 }, ...]
await indexedFile.cram.getSamHeader() // parsed SAM header
await indexedFile.hasDataForReferenceSequence('chrY') // false if the file has no chrY

const controller = new AbortController()
await indexedFile.getRecordsForRange('chr1', 0, 1_000_000, {
  signal: controller.signal,
})

Performance

@gmod/range-cache-filehandle merges the many small HTTP requests a query makes into fewer, and reuses bytes across queries:

import { RemoteFileWithRangeCache } from '@gmod/range-cache-filehandle'

const indexedFile = new IndexedCramFile({
  cramFilehandle: new RemoteFileWithRangeCache(url),
  index: new CraiIndex({
    filehandle: new RemoteFileWithRangeCache(`${url}.crai`),
  }),
})

In a browser, slices decode on a worker pool by default. Pass useSliceWorkerPool: false to turn it off, or numSliceWorkers to set its size (workers.md).

Script tag

A standalone browser build puts the same exports on window.gmodCRAM, loading its codec worker from the same directory and decoding in-process without it. The example directory has a working page.

<script src="https://unpkg.com/@gmod/cram/dist/cram-bundle.js"></script>

Docs

  • docs/api.md: every option, property and method, including walking a record's raw read features
  • MIGRATION.md: breaking changes, newest first
  • docs/dataflow.md: a query from index to records, with links to the design docs and ADRs

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

版本与发布记录

@gmod/cram 共发布 122 个版本,首次发布于 2018/07/14;过去 12 个月发布了 59 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
14.5.0latest2026/11/161 天前
14.4.02026/11/097 天前
14.3.22026/10/141 个月前
14.3.12026/10/121 个月前
14.3.02026/10/111 个月前
14.2.12026/10/091 个月前

关于 @gmod/cram 的常见问题

@gmod/cram 是什么?

read CRAM files with pure Javascript

如何安装 @gmod/cram?

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

@gmod/cram 支持 TypeScript 吗?

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

@gmod/cram 支持 ESM 还是 CommonJS?

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

@gmod/cram 可以商用吗?

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

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

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

@gmod/cram 还在维护吗?

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