# fossil-delta

> Fossil SCM delta compression

Latest version **2.0.0** (published 2024-04-06) · BSD license · 0 weekly downloads

## Install

```sh
npm install fossil-delta
pnpm add fossil-delta
yarn add fossil-delta
bun add fossil-delta
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2024-04-06 |
| First published | 2014-08-16 |
| Weekly downloads | 0 |
| License | BSD |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 38.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 74 |
| Author | Dmitry Chestnykh |
| Maintainers | dchest |
| Keywords | delta, compression, encoding |

## Links

- npm: https://www.npmjs.com/package/fossil-delta
- Repository: https://github.com/dchest/fossil-delta-js
- Homepage: https://github.com/dchest/fossil-delta-js#readme
- Issues: https://github.com/dchest/fossil-delta-js/issues
- npm.io page: https://npm.io/package/fossil-delta

## Alternatives

- [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads
- [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads
- [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads
- [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K weekly downloads
- [datasets-fi-postalcodes](https://npm.io/package/datasets-fi-postalcodes.md) — 1.1K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2024-04-06
- 1.0.2 — 2018-03-12
- 1.0.1 — 2017-10-26
- 1.0.0 — 2017-10-26
- 0.2.5 — 2014-09-30
- 0.2.4 — 2014-09-26
- 0.2.3 — 2014-09-26
- 0.2.2 — 2014-09-22
- 0.2.1 — 2014-09-22
- 0.2.0 — 2014-08-17
- 0.1.2 — 2014-08-16
- 0.1.0 — 2014-08-16

## README

Fossil SCM delta compression algorithm
======================================

The cool thing about it is that plain text inputs generate plain text deltas
(binary inputs, of course, may generate binary deltas).

* [Format](http://www.fossil-scm.org/index.html/doc/tip/www/delta_format.wiki)
* [Algorithm](http://www.fossil-scm.org/index.html/doc/tip/www/delta_encoder_algorithm.wiki)
* [Original implementation](http://www.fossil-scm.org/index.html/artifact/d1b0598adcd650b3551f63b17dfc864e73775c3d)
* [Demo](https://dchest.github.io/fossil-delta-js/)

Installation
------------

    $ npm install fossil-delta

Usage
-----

```javascript
import { createDelta, applyDelta } from 'fossil-delta';
```

### createDelta(source, target)

Returns a delta from source to target.

`source` and `target` must be a `Uint8Array` or an `Array` of bytes.
The same type will be returned.

### applyDelta(origin, delta[, opts])

Returns the target by applying the delta to the origin.

`origin` and `delta` must be a `Uint8Array` or an `Array` of bytes.
The same type will be returned.

Throws an error if the delta fails to apply (e.g., if it is corrupted).

Optional argument `opts` can be:

```javascript
{
    verifyChecksum: false
}
```

to disable checksum verification (which is enabled by default.)

### getDeltaTargetSize(delta)

Returns the size of the target for this delta.

Throws an error if it cannot read the size from the delta.


## Strings

A nice property of the Fossil Delta Encoding is that it produces pure plain text deltas
if the source and target are plain text.

To simplify working with plain text strings, the library provides the following convenience functions,
which automatically encode and decode strings using `TextEncoder` and `TextDecoder` before processing:

* `createStringDelta(source: string, target: string): string`
* `applyStringDelta(origin: string, delta: string, [, opts]): string`
* `getStringDeltaTargetSize(delta: string): number`

Note that `getStringDeltaTargetSize()` will return the size of the target string in UTF-8 bytes,
not characters (that is, it's not always equal to `string` length of the resulting target).


Development
-----------

I develop with Bun.

To build the library, run:

    $ bun run build

npm, yarn will also work for building.

To run tests, run:

    $ bun test


Migration from v1.x.x
---------------------

fossil-delta.js is now an ES module and there is no minified version included.

API renames:

- `create` -> `createDelta`
- `apply` -> `applyDelta`
- `outputSize` -> `getDeltaTargetSize`

Important: `createDelta` and `applyDelta` now return the same type as the input (`Uint8Array` if given `Uint8Array`, `Array` if given `Array`), instead of always returning an `Array`.

---
_Source: https://npm.io/package/fossil-delta · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
