bps

A library and CLI tool for creating and applying BPS patches. BPS is short for Binary Patching System. A BPS patch contains the difference between two binary files, the source and the target, and can be used to transform the source file into the target file. For more information, please read the BPS specification.

Usage

This module can be treated as an ES module:

import * as bps from 'bps';
// or
import { parse, apply, build, serialize, ActionType } from 'bps';

This module can also be treated as a CommonJS module:

const bps = require('bps');
// or
const { parse, apply, build, serialize, ActionType } = require('bps');

Parsing a BPS patch

You can parse a BPS binary patch into an instruction set:

const file = await fs.readFile('patch.bps', null);

try
{
  const {
    instructions,
    checksum
  } = bps.parse(file);
}
catch (error)
{
  // Throws an error when the patch is invalid, e.g. when
  // the patch doesn't have a valid BPS header.
}

Applying a BPS patch

You can apply an instruction set to a binary source:

const source = await fs.readFile('source.txt', null);

try
{
  const target = bps.apply(instructions, source);
}
catch (error)
{
  // Throws an error when the provided source does not
  // match the checksum stated in the patch instructions.
}

Building a BPS patch

You can build an instruction set from a source and a desired target:

const instructions = bps.build(
  await fs.readFile('source.txt', null),
  await fs.readFile('target.txt', null)
);

Serializing a BPS patch

You can serialize an instruction set into a binary BPS buffer:

const {
  buffer,
  checksum
} = bps.serialize(instructions);

await fs.writeFile('patch.bps', buffer, null);

Instruction sets

An instruction set will have the following fields:

An instruction set compromises of actions, an action results in bytes being appended to the target. Each action has the following properties:

• type\ A discriminator property stating what type of action it is.
• length\ The number of bytes that the action will write to the target.

The four action types are:

• ActionType.SourceRead\ Represents an action that copies a number of bytes from the source to the target.
• ActionType.TargetRead\ Represents an action that writes specified bytes to the target. These actions will have an additional property called bytes which will be an array of bytes to write to the target.
• ActionType.SourceCopy\ Represents an action that seeks to a location (a.k.a. relative offset) in the source and copies a number of bytes from that location to the target. These actions will have an additional property called offset which describes the amount to move the source relative offset by, this can be negative to move backwards.
• ActionType.TargetCopy\ Represents an action that seeks to a location (a.k.a. relative offset) in the target that has been produced up to this point and copies a number of bytes from that location to the target. These actions will have an additional property called offset which describes the amount to move the target relative offset by, this can be negative to move backwards.

Getting started

This module is available through the Node Package Manager (NPM):

npm install bps

Please Note: Versions of Node lower than v18.0.0 are not supported.

CLI tool

This package also provides a CLI tool to help verify and apply patches. This package will add bps to your path and can be used like so:

Usage: bps [options] [command]

A tool for creating and applying BPS patches.

Options:
  -V, --version                      output the version number
  -h, --help                         display help for command

Commands:
  verify <patch>                     verifies a patch file
  apply <patch> <source> <output>    applies a patch to a file
  create <source> <target> <output>  creates a patch from a source and a desired target.
  help [command]                     display help for command

Development

Building

You can build UMD and ESM versions of this package that are minified:

npm run build

Testing

This package also has a robust test suite:

npm test

This includes a code quality check using ESLint. Please refer to the .eslintrc files to familiar yourself with the rules.

License

This project is released under the MIT license.

Changelog

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

2.0.1 - 2024-02-25

Fixed

• The CLI tool now reports the correct version.

2.0.0 - 2024-02-24

Added

• Introduced the bps.build() function that enables you to build an instruction set from a source and a desired target.
• Introduced the bps.serialize() function that enables you to serialize an instruction set into a binary BPS buffer.
• Introduced the create command in the CLI tool that enables you to create a BPS patch file from a source file and a desired target file.

Changed

• The result of bps.parse() has been changed, it now has a different shape. Instead of this object structure:

  {
    sourceSize : 0,
    sourceChecksum : 0,
    targetSize : 0,
    targetChecksum : 0,
    actions : [],
    patchChecksum : 0
  }

  You will instead recieve an object with this structure:

  {
    instructions : {
      sourceSize : 0,
      sourceChecksum : 0,
      targetSize : 0,
      targetChecksum : 0,
      actions : []
    },
    checksum : 0
  }

• The bps.patch() function no longer takes the entire patch previously returned by bps.parse() but instead just the instruction set.

1.0.0 - 2024-02-02

The initial public release.