# cow-list

> Copy-on-write iterable list

Latest version **2.1.0** (published 2022-06-09) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install cow-list
pnpm add cow-list
yarn add cow-list
bun add cow-list
```

## Health

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

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2022-06-09 |
| First published | 2020-09-12 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^12.20.0 \|\| ^14.13.1 \|\| >=16.0.0 |
| Dependencies | 0 |
| Unpacked size | 61.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Victorien Elvinger |
| Maintainers | conaclos |
| Keywords | cow, list, rope, search, tree, versioning |

## Links

- npm: https://www.npmjs.com/package/cow-list
- Repository: https://github.com/Conaclos/cow-list
- Homepage: https://github.com/Conaclos/cow-list#readme
- Issues: https://github.com/Conaclos/cow-list/issues
- npm.io page: https://npm.io/package/cow-list

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 2.1.0 (latest) — 2022-06-09
- 2.0.0 — 2020-09-17
- 1.0.0 — 2020-09-12

## README

# Cow List 🐄🐄🐄

[![CI status][ci-img]][ci-url]
[![Coverage percentage][coveralls-img]][coveralls-url]
[![NPM version][npm-version-img]][npm-url]

_Cow List_ provides a [Copy-On-Write][cow] iterable list that supports logarithmic searches.
It provides also a mutable iterable List with versioning capabilities.

_Cow List_ naively supports lengthy values (objects with a length property). This makes _Cow List_ a perfect fit to implement a [rope][rope].

## Highlights

### Immutable or mutable

_Cow List_ provides immutable lists and mutable lists.
Immutable lists are well-suited for projects that embrace immutability and purity.
They use a [copy-on-write][cow] strategy to achieve better performances.
Mutable lists have versioning capabilities that enable to fork a the list into two independent mutable lists.
They are well-suited for projects that implements their own copy-on-write data structures.

### A building block

_Cow List_ implements a close to minimum set of features.
This makes _Cow List_ lightweight (2kB minified and gziped).
These features are carefully chosen for enabling the design of advanced data structures.
For instance, _Cow List_ enables to implement sorted lists and [ropes][rope].

### Lengthy values

_Cow List_ is aware of lengthy values (objects with a length property).
When you iterate over a list, you have access to the cumulated length (summary) of the traversed values.
This enables to efficiently implement a [rope][rope].

### Logarithmic searches

The main way to traverse a list is to get an iterator.
_Cow List_ enables to logarithmically chooses where to start the iteration.

## Getting started

Install [cow-list](#) as a dependency:

```sh
npm install cow-list
```

### Immutable list

```ts
import { CowList } from "cow-list"

let l = CowList.empty<string>()
l = l.inserted(0, "ab")
l = l.inserted(1, "c")
l = l.inserted(2, "d")
l = l.deleted(1)
l = l.replaced(1, "de")

for (const v of l) {
    console.log(v)
    // ab
    // de
}
```

### Mutable list

```ts
import { MutList } from "cow-list"

let l = MutList.empty<string>()
l.insert(0, "ab")
l.insert(1, "c")
l.insert(2, "d")
l.delet(1)
l.replac(1, "de")

for (const v of l) {
    console.log(v)
    // ab
    // de
}
```

## Advanced usages

Please take a look to the provided [examples](./src/examples/).

## FAQ

### Why did you design yet another list?

I wished to have a generic building block to implement [Dotted LogootSplit][dls].
Dotted LogootSplit is a new replicated data structure designed for collaborative editing.
The data structure combines a search tree and a rope.

### Which data structure is internally used?

For now, _Cow List_ uses a [partially persistent][pp] [AVL tree][avl].
This could change in the future in order to achieve better performances.

[ci-img]: https://flat.badgen.net/github/checks/Conaclos/cow-list/?label=CI
[ci-url]: https://github.com/Conaclos/cow-list/actions/workflows/ci.yml
[npm-version-img]: https://flat.badgen.net/npm/v/cow-list
[npm-url]: https://www.npmjs.com/package/cow-list
[coveralls-img]: https://flat.badgen.net/coveralls/c/github/Conaclos/cow-list
[coveralls-url]: https://coveralls.io/github/Conaclos/cow-list?branch=main
[cow]: https://en.wikipedia.org/wiki/Copy-on-write
[rope]: https://en.wikipedia.org/wiki/Rope_%28data_structure%29
[avl]: https://en.wikipedia.org/wiki/AVL_tree
[dls]: https://github.com/coast-team/dotted-logootsplit
[pp]: https://en.wikipedia.org/wiki/Persistent_data_structure

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