@gmod/range-cache-filehandle

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

A filehandle that caches byte ranges in chunks and coalesces adjacent reads into one request

原始使用文档
文档目录9 节
  1. Usage
  2. Behavior
  3. Tuning
  4. Upgrading from 1.x
  5. Docs
  6. References
  7. The layer above
  8. Provenance
  9. License

@gmod/range-cache-filehandle

NPM version Build Status

A GenericFilehandle that caches the byte ranges it fetched and coalesces nearby reads into one request.

An indexed genomics parser makes many small, adjacent, semi-random reads, most near ones it just made. This layer sits under the parser, turns those reads into a few large requests, and serves the next query's overlapping reads from memory.

npm install @gmod/range-cache-filehandle

Usage

Drop-in for RemoteFile from generic-filehandle2:

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

const cram = new CramFile({
  filehandle: new RemoteFileWithRangeCache('https://example.com/file.cram'),
})

CachedFilehandle wraps a local file or Blob instead. Its second argument keys this file's bytes in the shared cache, so it must identify the underlying bytes:

import { CachedFilehandle } from '@gmod/range-cache-filehandle'
import { LocalFile } from 'generic-filehandle2'

const file = new CachedFilehandle(new LocalFile(path), `file://${path}`)

Behavior

Two reads issued in one turn: one is partly cached and partly in flight, and their four gaps become three range requests
  • Stores exactly the byte extents it fetched, per file, and fetches only the gaps a read leaves.
  • Plans every read issued in the same microtask turn together. A gap under 64 KiB grows to 64 KiB, and gaps within 64 KiB of each other share a request.
  • Joins a request another read has in flight rather than asking again.
  • Reference-counts each request's readers, so a shared request is cancelled only once all of them abort. A reader passing no signal pins it for everyone.
  • Holds 256 MiB per worker, evicting the least recently used 1 MiB piece, and sweeps bytes idle for 15 minutes. clearCache() drops everything, clearCacheFor(key) drops one file, sweepIdleCache() reclaims early, setCacheLimit(bytes) changes the cap and cachedBytes() reports what the cache holds.
  • Runs 20 requests at a time per origin.
  • Learns a file's size from Content-Range, a 416, a body shorter than its request, or stat(), and clamps reads past it.
  • Needs a server that supports range requests. A 200 to a range request is an error, and a 206 whose Content-Range is not the range asked for throws instead of being cached.
  • Names a cause on failure: CORS, mixed content, a server ignoring the Range header, a connection that goes 30s without answering.

The cache never retries a request and sets no time limit on a transfer, only on the wait for a response to begin. To stop a read, abort the AbortSignal you passed it; the cache passes the signal through to the socket.

docs/dataflow.md walks one read through all of it.

Tuning

MIN_REQUEST, PIECE_SIZE, CACHE_LIMIT, CACHE_IDLE_TIMEOUT_MS, MAX_CONCURRENT and RESPONSE_TIMEOUT_MS are exported for reading, not setting, because the cache is module-global. docs/tuning.md gives the measurements behind each.

Upgrading from 1.x

  • setChunkCacheLimit(bytes) is setCacheLimit(bytes), and the limit is exact bytes rather than whole 256 KiB chunks.
  • CHUNK_SIZE and MAX_CACHE_ENTRIES are gone; MIN_REQUEST, PIECE_SIZE and CACHE_LIMIT replace them.
  • A 200 to a range request is an error even when the request started at byte 0, and a 416 with no readable length bounds the file at the start of its range. Both assume a server that supports ranges.
  • CachedFilehandle refuses an inner handle that caches under the same key.
  • A request goes out one microtask after the read that needs it.

Docs

References

The layer above

range-cache-filehandle caches bytes. Each parser that reads through it also caches what it parsed, with a separate budget and idle timeout, and a hit in that cache means the read never reaches this layer:

Provenance

  • Extracted from JBrowse 2, where it was @jbrowse/core/util/io/RemoteFileWithRangeCache, so parsers can use it without depending on @jbrowse/core.
  • Replaces http-range-fetcher, which merges the requests made in the last 100 ms. This package merges the gaps of reads issued in one microtask turn, so it waits out no timer, and it passes an AbortSignal through to the socket.

License

MIT

版本与发布记录

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

版本发布日期距今
2.0.0latest2026/10/1829 天前
1.6.02026/10/1730 天前
1.5.22026/10/151 个月前
1.5.12026/10/121 个月前
1.5.02026/10/011 个月前
1.4.02026/08/242 个月前

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

@gmod/range-cache-filehandle 是什么?

A filehandle that caches byte ranges in chunks and coalesces adjacent reads into one request

如何安装 @gmod/range-cache-filehandle?

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

@gmod/range-cache-filehandle 支持 TypeScript 吗?

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

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

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

@gmod/range-cache-filehandle 可以商用吗?

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

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

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

@gmod/range-cache-filehandle 还在维护吗?

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