npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

dslib-core

v1.0.5

Published

A robust and efficient data structures library.

Downloads

254

Readme

dslib-core

npm version npm release date Build Status codecov License: MIT install size npm package minified size npm package minified gzipped size

A robust and efficient data structures library.

✨ Features

  • 🧰 Foundational: Growing collection of essential data structures
  • 🛡️ Reliable: Robust stability with 100% test coverage
  • High-Performance: Optimized for efficiency in demanding applications
  • ⛰️ Scalable: Adaptable for projects of any size
  • 🪶 Lightweight: Zero dependencies, keeping your project lean
  • 🔷 TypeScript Native: Full type safety and intelligent code completion

Table of Contents

💡 Why dslib-core?

dslib-core is your go-to toolkit for advanced data structures in TypeScript and JavaScript. It bridges the gap left by standard libraries, empowering developers with the tools they need for efficient data management and manipulation.

Whether you're building a complex algorithm or optimizing application performance, dslib-core provides the building blocks you need to succeed.

Note: Currently only compatible with ESM projects.

📦 Installation

Install the package via npm:

npm install dslib-core

🚀 Getting Started

Import using ESM syntax:

import { Queue } from 'dslib-core';

Quick start example:

const queue = new Queue<number>();
queue.enqueue(3);
console.log(queue.dequeue()); // Output: 3

🚧 Using dslib-core in CommonJS Projects

dslib-core is primarily designed for ESM (ECMAScript Module) environments. However, you can still use it in CommonJS projects with a few adjustments.

To use dslib-core in a CommonJS project, we suggest using a dynamic import() within an async IIFE (Immediately Invoked Function Expression). Here's an example:

// CommonJS project example
(async function () {
  const { Queue } = await import('dslib-core');

  // Your code here
  const queue = new Queue();
  queue.enqueue(1);
  console.log(queue.dequeue()); // Output: 1
})();

This approach allows you to use the ESM-native dslib-core package within your CommonJS environment while maintaining asynchronous module loading.

🏗️ Data Structures

🔄 Queue

Implemented using a circular buffer to ensure efficient enqueue and dequeue operations.

Features

  • Performance: Enqueue and dequeue operations with amortized O(1) complexity.
  • Dynamic Resizing: Automatically resizes to manage memory usage efficiently.
  • Iterable: Implements the Iterable interface, allowing you to use the queue with for...of loops, spread (...) syntax and other iterable contexts.
  • Enhanced Runtime Privacy: Leverages ES2022 private class fields (#) for robust encapsulation, ensuring data privacy during execution.
  • Type Safety: Fully typed for TypeScript, ensuring type safety and IntelliSense support.
  • Versatility: Suitable for handling numbers, strings, objects, and more.

Methods

  • enqueue(item: T): number
    • Adds an item to the back of the queue.
    • Time complexity: amortized O(1).
    • Parameters:
      • item: T - The item to add to the queue.
    • Returns: The new size of the queue.
  • dequeue(): T | undefined
    • Removes and returns the item at the front of the queue.
    • Time complexity: amortized O(1).
    • Returns: The item at the front of the queue, or undefined if the queue is empty.
  • peek(): T | undefined
    • Returns the item at the front without removing it.
    • Time complexity: guaranteed O(1).
    • Returns: The item at the front of the queue, or undefined if the queue is empty.
  • get(index: number): T | undefined
    • Retrieves the element at the specified index without removing it.
    • Time complexity: guaranteed O(1) for any index.
    • Parameters:
      • index: number - The zero-based index of the element to retrieve.
    • Returns: The item at the front of the queue, or undefined if the index is out of bounds.
  • size: number (Getter)
    • Returns the number of items in the queue.
  • internalSize: number (Getter)
    • Returns the internal capacity of the queue's buffer (useful for debugging or analysis).
  • clear(): void
    • Removes all items from the queue.
  • [Symbol.iterator](): Iterator<T>
    • Returns an iterator over the elements in the queue (allows for use with for...of loops and spread (...) syntax).
  • entries(): Iterator<[T, number]>
    • Returns an iterator over the elements in the queue along with their indices.
    • Yields: Tuples of [element, index].
  • toString(): string
    • Returns a string representation of the queue.
    • Format: Queue(size) { item1, item2, ... }
  • forEach(callbackFn: (value: T, index: number, queue: Queue<T>) => void): void
    • Executes a provided function once for each element in the queue.
    • Parameters:
      • callbackFn - Function to execute for each element, taking three arguments:
        • value: T - The current element being processed.
        • index: number - The index of the current element.
        • queue: Queue<T> - The queue object being traversed.

Example Usage

import { Queue } from 'dslib-core';

const queue = new Queue<string>();

queue.enqueue('first');
queue.enqueue('second');
queue.enqueue('third');

console.log(queue.peek()); // Output: 'first'
console.log(queue.get(1)); // Output: 'second'
console.log(queue.size); // Output: 3

queue.forEach((value, index) => {
  console.log(`Index ${index}: ${value}`);
});
// Output:
// Index 0: first
// Index 1: second
// Index 2: third

for (const item of queue) {
  console.log(item);
}
// Output:
// first
// second
// third

for (const [item, i] of queue.entries()) {
  console.log(`Index ${i}: ${item}`);
}
// Output:
// Index 0: first
// Index 1: second
// Index 2: third

const arr = [...queue];
console.log(arr.length); // Output: 3

console.log(queue.dequeue()); // Output: 'first'
console.log(queue.size); // Output: 2

console.log(queue.toString()); // Output: 'Queue(2) { 'second', 'third' }'

queue.clear();
console.log(queue.size); // Output: 0
console.log(queue.dequeue()); // Output: undefined

Performance

Performance: enqueue and dequeue methods offer performance comparable to the built-in array push and pop methods.

Benchmark Results:

┌─────────┬───────────┬──────────────┬────────────────────┬───────────┬──────────┐
│ (index) │ Task Name │ ops/sec      │ Average Time (ns)  │ Margin    │ Samples  │
├─────────┼───────────┼──────────────┼────────────────────┼───────────┼──────────┤
│ 0       │ 'enqueue' │ '27,675,706' │ 36.132772689503845 │ '±14.28%' │ 13838019 │
│ 1       │ 'push'    │ '26,611,405' │ 37.5778722674608   │ '±9.86%'  │ 13665449 │
└─────────┴───────────┴──────────────┴────────────────────┴───────────┴──────────┘
┌─────────┬───────────┬──────────────┬────────────────────┬──────────┬─────────┐
│ (index) │ Task Name │ ops/sec      │ Average Time (ns)  │ Margin   │ Samples │
├─────────┼───────────┼──────────────┼────────────────────┼──────────┼─────────┤
│ 0       │ 'pop'     │ '36,840,562' │ 27.143994127022697 │ '±0.93%' │ 7368113 │
│ 1       │ 'shift'   │ '797'        │ 1253180.9375000647 │ '±1.20%' │ 160     │
│ 2       │ 'dequeue' │ '33,964,152' │ 29.442807571542765 │ '±8.38%' │ 6792831 │
└─────────┴───────────┴──────────────┴────────────────────┴──────────┴─────────┘
  • The first table compares the performance of the built-in push method (on an empty array) and the enqueue method (on an empty Queue). Benchmarks tasks run sequentially for 500ms each.
  • The second table compares the performance of the built-in pop and shift methods, and the dequeue method. Each benchmark task starts with an array/queue (as applicable) of size 2^24 (approx. 16 million). Benchmarks tasks run sequentially for 200ms each.
  • Demonstrates similar efficiency to native array methods under high load, with a massive improvement over the buit-in shift method.

Note: The above benchmarks are run using items of type object in order to better simulate real-world scenarios. Using primitive data types like string or number would generally result in faster performance.

Benchmarks conducted on 10/21/2024 using tinybench on a MacBook Pro (M3 Pro) using the following versions:

> tsx --version

tsx v4.19.1
node v20.17.0

To benchmark with your setup, clone this repo and run:

npm install
npm run bench

🌟 Contributing

Contributions are welcome! If you have ideas, suggestions, or find any issues, please open an issue or submit a pull request.

Development Setup

Clone the repository:

git clone https://github.com/oliviacarlisle/dslib-core.git

Install dependencies:

cd dslib-core
npm install

Run tests:

npm test

⚖️ License

This project is licensed under the MIT License - see the LICENSE file for details.


Feel free to reach out if you have any questions or need assistance!