package
Reusable binary delta-update engine: apply TRDIFF10/bsdiff+zstd patch chains to a binary and discover chains from a pluggable source (OCI/GHCR or GitHub Releases). Pure Node, zero product coupling.
npm install binpatchGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 1 packages.
201.7 kB
Includes dependencies.
Reusable binary delta-update engine. Apply a TRDIFF10 / bsdiff+zstd patch chain to a binary, discover chains from a pluggable source (OCI/GHCR tags or GitHub Release assets), and generate + publish patches via a composite GitHub Action. Pure Node, zero product coupling — works for Electron apps, CLIs, agents, and any single-file binary artifact.
npm install binpatchDocs: https://binpatch.p.byk.im/ · Source: https://github.com/BYK/binpatch
Every time your binary updates itself, your users pull the entire file
again — even when the new release changed a few hundred kilobytes of a
100 MB Electron app, a 50 MB CLI, or a 200 MB game updater.
That's bandwidth and patience burned on bytes that didn't move. A binary
delta (bsdiff) between consecutive builds is typically a few percent of
the full size — see the home page graph
for real measurements on getsentry/cli.
The hard part isn't making the patch — it's the two halves that most projects hand-roll separately (and get wrong):
binpatch gives you both as one MIT-licensed TypeScript library plus a
drop-in GitHub Action. Powers self-updates in production for shipped
binaries you may already be using (including getsentry/cli).
Battle-tested reliability — minus the years of accumulated fixes you'd
otherwise have to write yourself.
Two halves, one wire contract:
node:* builtins only), zero product coupling.action/.This package covers the apply core (TRDIFF10 patch parsing, chain
application, an offline cache) and chain discovery — a pluggable
SourceStrategy over OCI/GHCR patch-manifest tags and GitHub Release assets,
plus a cache-first resolveAndApply orchestrator. The CI-side generation half
ships in the same repo as a composite GitHub Action.
import {
applyPatchChainInMemory,
parsePatchHeader,
makeCache,
} from "binpatch";
// Apply an ordered chain of patches to an old binary, writing the final
// output to disk. Intermediate hops stay in memory; only the final hop is
// written and hashed. Returns the SHA-256 of the produced binary.
const sha256 = await applyPatchChainInMemory(oldPath, patches, destPath, {
onBytes: (n) => { /* progress: n output bytes produced this chunk */ },
});
// Offline cache — the consumer decides where it lives (no config lookup here).
const cache = makeCache("/path/to/cache-dir");
await cache.save(chain, steps);
const cached = await cache.load(currentVersion, targetVersion);
Higher level: hand resolveAndApply a SourceStrategy and it does cache-first
resolution, apply, SHA verification, and progress events. All product specifics
are injected — the library has no GitHub/registry/version knowledge baked in.
import {
resolveAndApply,
ghcrSource,
githubReleaseSource,
} from "binpatch";
// Nightly channel — OCI patch-manifest tags on a registry (e.g. GHCR).
const nightly = ghcrSource({
registry: "https://ghcr.io",
repo: "owner/project",
userAgent: "my-cli/1.2.3",
binaryName: "my-cli-linux-x64",
targetTag: (v) => `nightly-${v}`, // where the target image manifest lives
compareVersions, // your semver comparator (-1|0|1)
});
// Stable channel — GitHub Release assets.
const stable = githubReleaseSource({
releasesUrl: "https://api.github.com/repos/owner/project/releases"
Implement your own SourceStrategy for any other layout — the contract is a
single method:
resolveChain(current, target, signal?, report?) => PatchChain | null. Call the
optional report(reason) to classify a null result for telemetry (it never
changes control flow).
The library never draws progress. resolveAndApply emits
{ type: "phase" | "bytes" | "done"; phase; ... } events via onProgress; a
missing handler is silent, and a throwing handler can never abort the operation
(safeProgress). Each consumer renders however it likes — a stderr bar, a
spinner message, or a log line — using the byte counts in the bytes events.
parsePatchHeader, offtin, PatchHeader, MAX_OUTPUT_SIZE, addDiffChunk
— TRDIFF10 header parsing + the vectorized diff-add primitive.applyPatch, applyPatchToMemory, applyPatchChainInMemory — patch apply.resolveAndApply, SourceStrategy, ghcrSource, githubReleaseSource,
OciClient — chain discovery + orchestration.ProgressEvent, ProgressHandler, safeProgress — progress events.PatchChain, PatchLink, ChainStep, DeltaResult, BinpatchError,
and the contract constants (MAX_STABLE_CHAIN_DEPTH,
MAX_NIGHTLY_CHAIN_DEPTH, SIZE_THRESHOLD_RATIO, PATCH_TAG_PREFIX).makeCache, PatchCache, patchFileName, chainFileName, ChainMeta,
PatchStepMeta — the offline patch cache."TRDIFF10" magic + offtin sign-magnitude i64
controlLen / diffLen / newSize, followed by zstd(control) | zstd(diff) | zstd(extra). newSize is bounded by MAX_OUTPUT_SIZE (2 GiB) on parse.The generator (the GitHub Action, later) produces this layout; this package consumes it. Either half is usable on its own as long as both honor the contract.
MIT. The apply algorithm derives from Colin Percival's bsdiff (BSD) via the TRDIFF10 (zstd) variant produced by zig-bsdiff.