https://github.com/conaclos/cow-list
Copy-On-Write iterable list
https://github.com/conaclos/cow-list
copy-on-write cow data-structure immutable iterable list mutable rope versioning
Last synced: 7 months ago
JSON representation
Copy-On-Write iterable list
- Host: GitHub
- URL: https://github.com/conaclos/cow-list
- Owner: Conaclos
- License: apache-2.0
- Created: 2020-09-12T16:51:25.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2022-08-17T13:52:38.000Z (almost 4 years ago)
- Last Synced: 2024-04-24T14:09:50.396Z (about 2 years ago)
- Topics: copy-on-write, cow, data-structure, immutable, iterable, list, mutable, rope, versioning
- Language: TypeScript
- Homepage:
- Size: 132 KB
- Stars: 4
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Cow List 🐄🐄🐄
[![CI status][ci-img]][ci]
[![Coverage percentage][coveralls-img]][coveralls]
[![NPM version][npm-version-img]][npm]
_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 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 (2 kB 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()
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()
l.insert(0, "ab")
l.insert(1, "c")
l.insert(2, "d")
l.delete(1)
l.replace(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 replicated data structure designed for collaborative editing.
The data structure combines a search tree and a rope.
### Internally used data structure
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]: https://github.com/Conaclos/cow-list/actions/workflows/ci.yml
[npm-version-img]: https://flat.badgen.net/npm/v/cow-list
[npm]: https://www.npmjs.com/package/cow-list
[coveralls-img]: https://flat.badgen.net/coveralls/c/github/Conaclos/cow-list
[coveralls]: 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