fhf-linkedlist
Version:
The fhf-linkedlist library is a high-performance JavaScript implementation of a linked list, leveraging WebAssembly for efficient memory management and fast execution. It provides an easy-to-use API for common linked list operations such as appending, pus
328 lines (209 loc) • 5.53 kB
Markdown
<center>
<h1>⚙️ FHF-LinkedList</h1>
<img src="logo.png" alt="FHF LinkedList Logo" width="160"/>
</center>
## Overview
`fhf-linkedlist` is a high-performance, WebAssembly-powered implementation of a **Linked List** data structure.
It blends JavaScript simplicity with native-speed operations through WASM, ideal for handling large or performance-critical data.
## Table of Contents
1. [Installation](#installation)
2. [Getting Started](#getting-started)
3. [Class: `LinkedList`](#class-linkedlist)
- [Core Methods](#core-methods)
- [Utility Methods](#utility-methods)
- [Iteration and Functional Methods](#iteration-and-functional-methods)
- [Advanced Operations](#advanced-operations)
4. [Memory Management](#memory-management)
5. [WebAssembly Integration](#webassembly-integration)
6. [Examples](#examples)
7. [License](#license)
---
## Installation
Install via npm:
```bash
npm install fhf-linkedlist
```
---
## Getting Started
A quick example to get you started:
```js
import LinkedList from "fhf-linkedlist";
(async () => {
const list = new LinkedList([1, 2, 3]);
await list.append(4);
list.display(); // Outputs: 1 -> 2 -> 3 -> 4
})();
```
---
## Class: `LinkedList`
### Core Methods
#### `append(data)`
Adds a new element to the **end** of the list.
```js
await list.append(5);
```
#### `push(data)`
Adds a new element to the **beginning** of the list.
```js
await list.push(0);
```
#### `insert(index, data)`
Inserts a new node at a specific position.
```js
await list.insert(2, 99);
```
#### `deleteNode(index)`
Removes the node at the given index.
```js
await list.deleteNode(1);
```
#### `get(index)`
Returns the value at the specified index.
```js
const value = await list.get(2);
```
#### `length()`
Returns the total number of nodes in the list.
```js
const len = await list.length();
```
#### `reverse()`
Reverses the entire list.
```js
await list.reverse();
```
#### `free()`
Frees all memory associated with the list.
```js
await list.free();
```
---
### Utility Methods
#### `display()`
Prints the list to the console.
```js
await list.display(); // e.g. 1 -> 2 -> 3
```
#### `toArray()`
Returns the list contents as a JavaScript array.
```js
const arr = await list.toArray();
```
#### `toString()`
Returns a human-readable string representation.
```js
const str = await list.toString();
```
#### `indexOf(value)`
Returns the index of the first occurrence of a value.
```js
const idx = await list.indexOf(10);
```
#### `find(predicate)`
Returns the first value that matches a condition.
```js
const found = await list.find((v) => v > 5);
```
#### `findIndex(predicate)`
Returns the index of the first element matching the predicate.
```js
const idx = await list.findIndex((v) => v === 42);
```
#### `includes(value)`
Checks if a value exists in the list.
```js
const hasValue = await list.includes(3);
```
#### `clear()`
Removes all nodes (same as `free()`).
```js
await list.clear();
```
---
### Iteration and Functional Methods
#### `forEach(callback)`
Executes a function for each value in the list.
```js
await list.forEach((v) => console.log(v));
```
#### `map(callback)`
Applies a function to each element and returns a new array.
```js
const doubled = await list.map((v) => v * 2);
```
#### `filter(callback)`
Filters values based on a condition and returns a new array.
```js
const even = await list.filter((v) => v % 2 === 0);
```
#### `some(callback)`
Returns `true` if **any** value matches the condition.
```js
const hasLarge = await list.some((v) => v > 10);
```
#### `every(callback)`
Returns `true` if **all** values satisfy the condition.
```js
const allPositive = await list.every((v) => v > 0);
```
---
### Advanced Operations
#### `pop()`
Removes and returns the **last** element.
```js
const last = await list.pop();
```
#### `shift()`
Removes and returns the **first** element.
```js
const first = await list.shift();
```
#### `concat(otherList)`
Appends another LinkedList to the current one.
```js
await list.concat(otherList);
```
#### `clone()`
Creates a new LinkedList instance with the same elements.
```js
const newList = await list.clone();
```
---
## Memory Management
This library uses **WebAssembly memory** for efficient allocation, pointer manipulation, and node traversal.
The memory is initialized with defined bounds and automatically expanded when needed for large datasets.
---
## WebAssembly Integration
The linked list core (append, push, delete, reverse, etc.) is written in low-level C/C++ and compiled via **Emscripten** to WebAssembly.
The JavaScript wrapper handles convenience methods and async synchronization with the WASM instance.
---
## Examples
### Appending & Displaying
```js
import LinkedList from "fhf-linkedlist";
(async () => {
const list = new LinkedList([1, 2]);
await list.append(3);
await list.push(0);
list.display(); // Outputs: 0 -> 1 -> 2 -> 3
})();
```
### Reversing & Filtering
```js
const list = new LinkedList([1, 2, 3, 4]);
await list.reverse();
console.log(await list.toString()); // 4 -> 3 -> 2 -> 1
console.log(await list.filter((v) => v % 2 === 0)); // [4, 2]
```
### Concatenation & Cloning
```js
const list1 = new LinkedList([1, 2]);
const list2 = new LinkedList([3, 4]);
await list1.concat(list2);
list1.display(); // 1 -> 2 -> 3 -> 4
const copy = await list1.clone();
copy.display(); // 1 -> 2 -> 3 -> 4
```
---
## License
MIT © 2025 — [FHF Dev Team](https://github.com/80mahd08)