# append-tree

> Model a tree structure on top of an append-only log.

Latest version **2.4.4** (published 2018-06-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install append-tree
pnpm add append-tree
yarn add append-tree
bun add append-tree
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.4.4 |
| Published | 2018-06-06 |
| First published | 2017-01-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 8 |
| Unpacked size | 50.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 55 |
| Author | Mathias Buus |
| Maintainers | mafintosh, pfrazee |

## Links

- npm: https://www.npmjs.com/package/append-tree
- Repository: https://github.com/mafintosh/append-tree
- Issues: https://github.com/mafintosh/append-tree/issues
- npm.io page: https://npm.io/package/append-tree

## Dependencies (8)

- [from2](https://npm.io/package/from2.md) ^2.3.0
- [codecs](https://npm.io/package/codecs.md) ^1.2.0
- [varint](https://npm.io/package/varint.md) ^5.0.0
- [inherits](https://npm.io/package/inherits.md) ^2.0.3
- [mutexify](https://npm.io/package/mutexify.md) ^1.1.0
- [array-lru](https://npm.io/package/array-lru.md) ^1.1.1
- [process-nextick-args](https://npm.io/package/process-nextick-args.md) ^1.0.7
- [protocol-buffers-encodings](https://npm.io/package/protocol-buffers-encodings.md) ^1.1.0

## Recent versions

- 2.4.4 (latest) — 2018-06-06
- 2.4.3 — 2018-05-18
- 2.4.2 — 2018-05-18
- 2.4.1 — 2018-01-17
- 2.4.0 — 2017-11-14
- 2.3.6 — 2017-07-05
- 2.3.5 — 2017-05-29
- 2.3.4 — 2017-05-23
- 2.3.3 — 2017-05-23
- 2.3.2 — 2017-05-02
- 2.3.1 — 2017-04-29
- 2.3.0 — 2017-04-25
- 2.2.0 — 2017-04-20
- 2.1.0 — 2017-04-20
- 2.0.5 — 2017-03-18
- … 9 more at https://npm.io/package/append-tree/versions

## README

# append-tree

Model a tree structure on top of an append-only log.

```
npm install append-tree
```

[![Build Status](https://travis-ci.org/mafintosh/append-tree.svg?branch=master)](https://travis-ci.org/mafintosh/append-tree)

The data structure stores a small index for every entry in the log, meaning no external indexing is required to model the tree. Also means that you can perform fast lookups on sparsely replicated logs.

## Usage

``` js
var tree = require('append-tree')
var hypercore = require('hypercore')

var feed = hypercore('./my-tree')
var tr = tree(feed, {valueEncoding: 'utf-8'})

tr.put('/hello', 'world', function (err) {
  if (err) throw err

  tr.get('/hello', function (err, val) {
    if (err) throw err
    console.log(val) // <-- 'world'

    tr.list('/', function (err, list) {
      if (err) throw err
      console.log(list) // <-- ['hello']
    })
  })
})
```

## API

#### `var tr = tree(feed, [options])`

Create a new append tree.

First option should be a [hypercore](https://github.com/mafintosh/hypercore) feed (or any append-only log that supports `.append()` and `.length`).

Options include:

``` js
{
  valueEncoding: 'binary' | 'utf-8' | 'json' | anyAbstractEncoding
  offset: 0 // optional feed offset where the tree starts
  cache: true // use an LRU cache on tree entries
  cacheSize: 65536 // how many entries to use in the LRU cache
}
```

#### `tr.put(name, value, [callback])`

Insert a new node in the tree.

#### `tr.del(name, [callback])`

Delete a node from the tree.

#### `tr.get(name, [options], callback)`

Retrieve a value from the tree. Accepts the same options as [hypercore's get](https://github.com/mafintosh/hypercore#feedgetindex-options-callback) method.

#### `tr.list(name, [options], callback)`

List all immediate children of a node. Similar to doing a `readdir` in a file system. Accepts the same options as [hypercore's get](https://github.com/mafintosh/hypercore#feedgetindex-options-callback) method.

#### `tr.path(name, [options], callback)`

Will call the callback with a list of feed indexes needed to lookup the given name.
Useful if you are replicating the tree and want to avoid roundtrips. Accepts the same options as [hypercore's get](https://github.com/mafintosh/hypercore#feedgetindex-options-callback) method.

#### `var stream = tr.history([options])`

Create a history stream containing all the changes in the tree. Accepts the same options as [hypercore's createReadStream](https://github.com/mafintosh/hypercore#var-stream--feedcreatereadstreamoptions) method.

Each data event looks like this

``` js
{
  type: 'put' | 'del',
  version: 42, // version of the tree at this point in time
  name: '/foo',
  value: new Buffer('bar') // null if it is a del
}
```

#### `tr.version`

Number describing the current version of the tree.

Populated initially after `ready` event. Will be `-1` before.

#### `tr.on('ready', cb)`

Fired when the tree is ready and all properties have been populated.

#### `var oldTree = tr.checkout(version, [options])`

Checkout an old readonly version of the tree. `.get`, `.list` will return the same values as the tree did at the old version.
Accepts the same options as the tree constructor.

#### `var stream = tr.diff(checkout, [options])`

Diff a tree against another checkout of the tree.
Will emit the same data as the history stream but representing the diff from `tr` to `checkout`.

Accepts the same options as [hypercore's createReadStream](https://github.com/mafintosh/hypercore#var-stream--feedcreatereadstreamoptions) method.

## License

MIT

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