FastDS

[![Github Build Status][github-image]][github-url]
[![NPM version][npm-image]][npm-url]
[![Downloads][downloads-image]][npm-url]
[![Coverage Status][codecov-image]][codecov-url]
[![Snyk][snyk-image]][snyk-url]

Fast, zero-dependency TypeScript data structures optimized for high-performance applications.

Features

- 🚀 High Performance - Up to 37% faster than popular alternatives
- 🔄 O(1) Operations - Constant time push, pop, shift, unshift operations
- 📦 Zero Dependencies - No external runtime dependencies
- 🔍 TypeScript Native - Full type safety and IntelliSense support
- 💾 Memory Efficient - Smart memory management with automatic cleanup
- 🎯 Production Ready - Battle-tested with 100% test coverage

Installation

``bash
npm install fastds


or

yarn add fastds

or

pnpm add fastds
`

Quick Start

`typescript
import { RingBuffer, BinarySearchArray } from 'fastds';

// Create a high-performance circular buffer
const buffer = new RingBuffer();
buffer.push(1).push(2).push(3);
console.log(buffer.shift()); // 1
console.log(buffer.pop()); // 3

// Create a sorted array with binary search
const sorted = new BinarySearchArray((a, b) => a - b);
sorted.insert(5);
sorted.insert(2);
sorted.insert(8);
console.log(sorted.indexOf(5)); // 1 (sorted: [2, 5, 8])
`

Data Structures

$3

A high-performance circular buffer (double-ended queue) with O(1) operations for both ends.

#### Why Use RingBuffer?

- Queue/Deque Operations: Perfect for FIFO/LIFO operations, message queues, and task scheduling
- Sliding Windows: Efficient for implementing sliding window algorithms
- Stream Buffers: Ideal for I/O operations, network buffers, and data streaming
- Performance Critical: When you need faster operations than JavaScript's native Array

#### Basic Usage

`typescript
import { RingBuffer } from 'fastds';

// Create with optional initial capacity
const buffer = new RingBuffer(100);

// Add elements
buffer.push('world'); // Add to end
buffer.unshift('hello'); // Add to beginning

// Remove elements
const first = buffer.shift(); // Remove from beginning: 'hello'
const last = buffer.pop(); // Remove from end: 'world'

// Peek without removing
buffer.push('a', 'b', 'c');
console.log(buffer.peekFirst()); // 'a'
console.log(buffer.peekLast()); // 'c'
console.log(buffer.peekAt(1)); // 'b'
`

#### Advanced Operations

`typescript
// Create from array
const numbers = RingBuffer.from([1, 2, 3, 4, 5]);

// Array-like operations
numbers.slice(1, 3); // [2, 3]
numbers.indexOf(3); // 2
numbers.has(4); // true
numbers.toArray(); // [1, 2, 3, 4, 5]

// Modify at index
numbers.setOne(2, 10); // Replace index 2 with 10
numbers.setOne(2, 20, true); // Insert 20 at index 2

// Remove elements
numbers.removeOne(1); // Remove element at index 1
numbers.removeFirst(10); // Remove first occurrence of 10
numbers.remove(0, 2); // Remove 2 elements starting at index 0

// Iteration
for (const value of numbers) {
console.log(value);
}

// Drain iterator (removes elements while iterating)
const drainIter = numbers.drain();
for (const value of drainIter) {
console.log(value); // Buffer becomes empty after iteration
}
`

#### Memory Management

`typescript
const buffer = new RingBuffer