Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jondubois/proper-skip-list

A fast skip list implementation which supports fetching and deleting multiple adjacent entries at a time.
https://github.com/jondubois/proper-skip-list

Last synced: 2 months ago
JSON representation

A fast skip list implementation which supports fetching and deleting multiple adjacent entries at a time.

Host: GitHub
URL: https://github.com/jondubois/proper-skip-list
Owner: jondubois
License: mit
Created: 2020-01-08T23:29:14.000Z (about 5 years ago)
Default Branch: master
Last Pushed: 2021-02-27T18:48:15.000Z (almost 4 years ago)
Last Synced: 2024-08-09T20:43:07.620Z (5 months ago)
Language: JavaScript
Homepage:
Size: 71.3 KB
Stars: 22
Watchers: 3
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# proper-skip-list
A fast skip list implementation which supports fetching and deleting multiple adjacent entries at a time.
It's ideal for efficiently storing and fetching ordered data.

## Installation

```bash
npm install proper-skip-list --save
```

## Performance

### Time complexity

Average case, relative to the total number of elements in the list:

- **upsert**: `O(log n)`
- **find**: `O(log n)`
- **has**: `O(log n)`
- **extract**: `O(log n)`
- **delete**: `O(log n)`
- **findEntries**: `O(log n)`
- **minKey**: `O(1)`
- **maxKey**: `O(1)`
- **minValue**: `O(1)`
- **maxValue**: `O(1)`
- **findEntriesFromMin**: `O(1)`
- **findEntriesFromMax**: `O(1)`
- **deleteRange**: `O(log n)`
- **clear**: `O(1)`
- **get length**: `O(1)`

Note that the **deleteRange** method is `O(log n)` relative to the number of elements in the list.
The time complexity relative to the number of elements which will be removed from the list is different and it varies depending on whether the `updateLength` constructor option is `true` or `false`. If `true`, time complexity is `O(n)`, if `false`, it is `O(1)`.

### Space complexity

- Average: `O(n)`
- Worst case: `O(n log n)`

The `stackUpProbability` option can be modified to optimize space usage and performance to suit more advanced use cases but it should be used cautiously.

## API

Keys can be of type `string` and/or `number`. Internally, different types are handled separately. All numbers have priority over strings.
If strings are used, the order is lexicographic.

### Constructor

```js
const ProperSkipList = require('proper-skip-list');

// Default options:
let skipList = new ProperSkipList();

// Or...

// Sample custom options:
let skipList = new ProperSkipList({
stackUpProbability: 0.5, // 0.25 by default
updateLength: false // true by default
});
```

- The `stackUpProbability` option is the probability of an entry stacking up a single level when it is inserted into the skip list.
- The `updateLength` option allows you to disable the `length` property of the skip list. Not updating the `length` of the skip list can make the `deleteRange` method faster for certain use cases which involve deleting large segments of the skip list in a single operation.

### Methods

- **`upsert(key, value)`**: Insert a value into the skip list at the specified key. If a value already exists at that key, it will be replaced.
- **`find(key)`**: Get the value stored at the specified key. This method returns `undefined` if a matching value is not found.
- **`has(key)`**: Check if an entry with the specified key exists.
- **`extract(key)`**: Remove a value at the specified key if it exits. This method returns the value or `undefined` if not found.
- **`delete(key)`**: Remove a value at the specified key if it exits. This method returns a boolean to indicate whether or not a value existed at that key.
- **`findEntries(fromKey)`**: Get iterators for entries starting at the specified key in ascending or descending order. The `fromKey` does not need to have an exact match in the list; this method can therefore be used to iterate over nearby keys. The return value is an object in the form `{matchingValue, asc, desc}`. If an exact match for `fromKey` was found, the `matchingValue` property will contain the value at that key, otherwise it will be `undefined`. The `asc` property is an `iterable` iterator which can be used to iterate over records in ascending order starting at `fromKey` (or the next highest value if no exact match is found). The `desc` property is an `iterable` iterator which can be used to iterate over records in descending order starting at `fromKey` (or the next lowest value if no exact match is found).
- **`findEntriesFromMin()`**: Iterate over entries in ascending order starting at the lowest key. This method returns an iterable iterator.
- **`findEntriesFromMax()`**: Iterate over entries in descending order starting at the highest key. This method returns an iterable iterator.
- **`minKey()`**: Get the lowest key in the list.
- **`maxKey()`**: Get the highest key in the list.
- **`minValue()`**: Get the value stored at the lowest key in the list.
- **`maxValue()`**: Get the value stored at the highest key in the list.
- **`deleteRange(fromKey, toKey, deleteLeft, deleteRight)`**: Delete multiple entries with a single operation. The `fromKey` argument specifies the starting key in the range does not need to have an exact match in the list. The `toKey` argument is the end key, it also does not need to have an exact match. The `deleteLeft` argument can be used to specify whether or not the value at `fromKey` should also be deleted if found. The `deleteRight` argument argument can be used to specify whether or not the value at `toKey` should also be deleted if found. By default, only the in-between values will be deleted. If `fromKey` is null, it will delete from the beginning of the skip list. If `fromKey` is null, it will delete until the end of the skip list.
- **`clear`**: Empty/reset the skip list.

### Properties

Note that most of these properties were intended to be read-only.

- **`length`**: The number of entries stored in the skip list. It will be `undefined` if the `updateLength` constructor option is `false`.
- **`stackUpProbability`**: The probability of an entry stacking up a single level when it is inserted into the skip list.
- **`updateLength`**: Whether or not the length property is being updated.
- **`head`**: The head group of the skip list which holds an array of head nodes. This can be used to traverse all layers of the skip list for more advanced use cases.
- **`tail`**: The tail group of the skip list which holds an array of tail nodes. This can be used to traverse all layers of the skip list for more advanced use cases.

### Iterators

Iterators returned by methods like `findEntries`, `findEntriesFromMin` and `findEntriesFromMax` are iterable and can be looped over like this (example):

```js
let {asc, desc} = this.findEntries(1234);
for (let [key, value, i] of asc) {

// ... Do something.

if (i > 100) break;
}
```

Alternatively, `asc.next()` could be called manually from inside a `while` loop.