{"id":28092577,"url":"https://github.com/oliviacarlisle/dslib-core","last_synced_at":"2026-02-10T04:31:25.488Z","repository":{"id":258761604,"uuid":"867870327","full_name":"oliviacarlisle/dslib-core","owner":"oliviacarlisle","description":"JavaScript's missing data structures library.","archived":false,"fork":false,"pushed_at":"2025-01-07T19:19:14.000Z","size":200,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-22T16:54:11.966Z","etag":null,"topics":["data-structures","dequeue","enqueue","fifo","javascript","queue","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/dslib-core","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oliviacarlisle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-10-04T22:27:05.000Z","updated_at":"2025-05-24T16:14:20.000Z","dependencies_parsed_at":"2025-05-13T13:27:53.424Z","dependency_job_id":"6d73e130-b034-48db-bbdb-d00276e0af24","html_url":"https://github.com/oliviacarlisle/dslib-core","commit_stats":null,"previous_names":["oliviacarlisle/ts-data-structures","oliviacarlisle/core-dslib","oliviacarlisle/dslib-core"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/oliviacarlisle/dslib-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliviacarlisle%2Fdslib-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliviacarlisle%2Fdslib-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliviacarlisle%2Fdslib-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliviacarlisle%2Fdslib-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oliviacarlisle","download_url":"https://codeload.github.com/oliviacarlisle/dslib-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oliviacarlisle%2Fdslib-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29290990,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-10T03:42:42.660Z","status":"ssl_error","status_checked_at":"2026-02-10T03:42:41.897Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-structures","dequeue","enqueue","fifo","javascript","queue","typescript"],"created_at":"2025-05-13T13:21:00.753Z","updated_at":"2026-02-10T04:31:25.449Z","avatar_url":"https://github.com/oliviacarlisle.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dslib-core\n\n[![npm version](https://img.shields.io/npm/v/dslib-core.svg)](https://www.npmjs.com/package/dslib-core)\n[![npm release date](https://img.shields.io/github/release-date/oliviacarlisle/dslib-core)](https://www.npmjs.com/package/dslib-core)\n[![Build Status](https://github.com/oliviacarlisle/dslib-core/actions/workflows/ci.yml/badge.svg)](https://github.com/oliviacarlisle/dslib-core/actions/)\n[![codecov](https://codecov.io/gh/oliviacarlisle/dslib-core/graph/badge.svg?token=SVPFWK8OW9)](https://codecov.io/gh/oliviacarlisle/dslib-core)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![install size](https://packagephobia.com/badge?p=dslib-core)](https://packagephobia.com/result?p=dslib-core)\n[![npm package minified size](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fdeno.bundlejs.com%2F%3Fq%3Ddslib-core\u0026query=size.uncompressedSize\u0026label=minified%20size)](https://bundlejs.com/?q=dslib-core)\n[![npm package minified gzipped size](https://img.shields.io/bundlejs/size/dslib-core)](https://bundlejs.com/?q=dslib-core)\n\nA robust and efficient data structures library.\n\n## ✨ Features\n\n- 🧰 **Foundational**: Growing collection of essential data structures\n- 🛡️ **Reliable**: Robust stability with 100% test coverage\n- ⚡ **High-Performance**: Optimized for efficiency in demanding applications\n- ⛰️ **Scalable**: Adaptable for projects of any size\n- 🪶 **Lightweight**: Zero dependencies, keeping your project lean\n- 🔷 **TypeScript Native**: Full type safety and intelligent code completion\n\n## Table of Contents\n\n- [💡 Why dslib-core?](#-why-dslib-core)\n- [📦 Installation](#-installation)\n- [🚀 Getting Started](#-getting-started)\n- [🏗️ Data Structures](#%EF%B8%8F-data-structures)\n  - [🔄 Queue](#-queue)\n- [🌟 Contributing](#-contributing)\n- [⚖️ License](#%EF%B8%8F-license)\n\n## 💡 Why dslib-core?\n\n`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.\n\nWhether you're building a complex algorithm or optimizing application performance, `dslib-core` provides the building blocks you need to succeed.\n\n\u003e **Note:** Currently only compatible with ESM projects.\n\n## 📦 Installation\n\nInstall the package via npm:\n\n```bash\nnpm install dslib-core\n```\n\n## 🚀 Getting Started\n\nImport using ESM syntax:\n\n```typescript\nimport { Queue } from 'dslib-core';\n```\n\nQuick start example:\n\n```typescript\nconst queue = new Queue\u003cnumber\u003e();\nqueue.enqueue(3);\nconsole.log(queue.dequeue()); // Output: 3\n```\n\n### 🚧 Using `dslib-core` in CommonJS Projects\n\n`dslib-core` is primarily designed for ESM (ECMAScript Module) environments. However, you can still use it in CommonJS projects with a few adjustments.\n\nTo 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:\n\n```typescript\n// CommonJS project example\n(async function () {\n  const { Queue } = await import('dslib-core');\n\n  // Your code here\n  const queue = new Queue();\n  queue.enqueue(1);\n  console.log(queue.dequeue()); // Output: 1\n})();\n```\n\nThis approach allows you to use the ESM-native `dslib-core` package within your CommonJS environment while maintaining asynchronous module loading.\n\n## 🏗️ Data Structures\n\n### 🔄 Queue\n\nImplemented using a circular buffer to ensure efficient enqueue and dequeue operations.\n\n#### Features\n\n- **Performance:** Enqueue and dequeue operations with amortized O(1) complexity.\n- **Dynamic Resizing:** Automatically resizes to manage memory usage efficiently.\n- **Iterable**: Implements the `Iterable` interface, allowing you to use the queue with `for...of` loops, spread (`...`) syntax and other iterable contexts.\n- **Enhanced Runtime Privacy**: Leverages ES2022 private class fields (`#`) for robust encapsulation, ensuring data privacy during execution.\n- **Type Safety:** Fully typed for TypeScript, ensuring type safety and IntelliSense support.\n- **Versatility:** Suitable for handling numbers, strings, objects, and more.\n\n#### Methods\n\n- `enqueue(item: T): number`\n  - Adds an item to the back of the queue.\n  - **Time complexity:** amortized O(1).\n  - **Parameters:**\n    - `item: T` - The item to add to the queue.\n  - **Returns**: The new size of the queue.\n- `dequeue(): T | undefined`\n  - Removes and returns the item at the front of the queue.\n  - **Time complexity:** amortized O(1).\n  - **Returns**: The item at the front of the queue, or `undefined` if the queue is empty.\n- `peek(): T | undefined`\n  - Returns the item at the front without removing it.\n  - **Time complexity:** guaranteed O(1).\n  - **Returns:** The item at the front of the queue, or `undefined` if the queue is empty.\n- `get(index: number): T | undefined`\n  - Retrieves the element at the specified index without removing it.\n  - **Time complexity:** guaranteed O(1) for any index.\n  - **Parameters:**\n    - `index: number` - The zero-based index of the element to retrieve.\n  - **Returns:** The item at the front of the queue, or `undefined` if the index is out of bounds.\n- `size: number` _(Getter)_\n  - Returns the number of items in the queue.\n- `internalSize: number` _(Getter)_\n  - Returns the internal capacity of the queue's buffer (useful for debugging or analysis).\n- `clear(): void`\n  - Removes all items from the queue.\n- `[Symbol.iterator](): Iterator\u003cT\u003e`\n  - Returns an iterator over the elements in the queue (allows for use with `for...of` loops and spread (`...`) syntax).\n- `entries(): Iterator\u003c[T, number]\u003e`\n  - Returns an iterator over the elements in the queue along with their indices.\n  - **Yields:** Tuples of `[element, index]`.\n- `toString(): string`\n  - Returns a string representation of the queue.\n  - **Format:** `Queue(size) { item1, item2, ... }`\n- `forEach(callbackFn: (value: T, index: number, queue: Queue\u003cT\u003e) =\u003e void): void`\n  - Executes a provided function once for each element in the queue.\n  - **Parameters:**\n    - `callbackFn` - Function to execute for each element, taking three arguments:\n      - `value: T` - The current element being processed.\n      - `index: number` - The index of the current element.\n      - `queue: Queue\u003cT\u003e` - The queue object being traversed.\n\n#### Example Usage\n\n```typescript\nimport { Queue } from 'dslib-core';\n\nconst queue = new Queue\u003cstring\u003e();\n\nqueue.enqueue('first');\nqueue.enqueue('second');\nqueue.enqueue('third');\n\nconsole.log(queue.peek()); // Output: 'first'\nconsole.log(queue.get(1)); // Output: 'second'\nconsole.log(queue.size); // Output: 3\n\nqueue.forEach((value, index) =\u003e {\n  console.log(`Index ${index}: ${value}`);\n});\n// Output:\n// Index 0: first\n// Index 1: second\n// Index 2: third\n\nfor (const item of queue) {\n  console.log(item);\n}\n// Output:\n// first\n// second\n// third\n\nfor (const [item, i] of queue.entries()) {\n  console.log(`Index ${i}: ${item}`);\n}\n// Output:\n// Index 0: first\n// Index 1: second\n// Index 2: third\n\nconst arr = [...queue];\nconsole.log(arr.length); // Output: 3\n\nconsole.log(queue.dequeue()); // Output: 'first'\nconsole.log(queue.size); // Output: 2\n\nconsole.log(queue.toString()); // Output: 'Queue(2) { 'second', 'third' }'\n\nqueue.clear();\nconsole.log(queue.size); // Output: 0\nconsole.log(queue.dequeue()); // Output: undefined\n```\n\n#### Performance\n\n**Performance:** `enqueue` and `dequeue` methods offer performance comparable to the built-in array `push` and `pop` methods.\n\n**Benchmark Results:**\n\n```bash\n┌─────────┬───────────┬──────────────┬────────────────────┬───────────┬──────────┐\n│ (index) │ Task Name │ ops/sec      │ Average Time (ns)  │ Margin    │ Samples  │\n├─────────┼───────────┼──────────────┼────────────────────┼───────────┼──────────┤\n│ 0       │ 'enqueue' │ '27,675,706' │ 36.132772689503845 │ '±14.28%' │ 13838019 │\n│ 1       │ 'push'    │ '26,611,405' │ 37.5778722674608   │ '±9.86%'  │ 13665449 │\n└─────────┴───────────┴──────────────┴────────────────────┴───────────┴──────────┘\n┌─────────┬───────────┬──────────────┬────────────────────┬──────────┬─────────┐\n│ (index) │ Task Name │ ops/sec      │ Average Time (ns)  │ Margin   │ Samples │\n├─────────┼───────────┼──────────────┼────────────────────┼──────────┼─────────┤\n│ 0       │ 'pop'     │ '36,840,562' │ 27.143994127022697 │ '±0.93%' │ 7368113 │\n│ 1       │ 'shift'   │ '797'        │ 1253180.9375000647 │ '±1.20%' │ 160     │\n│ 2       │ 'dequeue' │ '33,964,152' │ 29.442807571542765 │ '±8.38%' │ 6792831 │\n└─────────┴───────────┴──────────────┴────────────────────┴──────────┴─────────┘\n```\n\n- 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.\n- 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.\n- Demonstrates similar efficiency to native array methods under high load, with a massive improvement over the buit-in `shift` method.\n\n\u003e **_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.\n\n_Benchmarks conducted on 10/21/2024 using `tinybench` on a MacBook Pro (M3 Pro) using the following versions:_\n\n```bash\n\u003e tsx --version\n\ntsx v4.19.1\nnode v20.17.0\n```\n\nTo benchmark with your setup, clone this repo and run:\n\n```bash\nnpm install\nnpm run bench\n```\n\n## 🌟 Contributing\n\nContributions are welcome! If you have ideas, suggestions, or find any issues, please open an [issue](https://github.com/oliviacarlisle/dslib-core/issues) or submit a [pull request](https://github.com/oliviacarlisle/dslib-core/pulls).\n\n### Development Setup\n\nClone the repository:\n\n```bash\ngit clone https://github.com/oliviacarlisle/dslib-core.git\n```\n\nInstall dependencies:\n\n```bash\ncd dslib-core\nnpm install\n```\n\nRun tests:\n\n```bash\nnpm test\n```\n\n## ⚖️ License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n_Feel free to reach out if you have any questions or need assistance!_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foliviacarlisle%2Fdslib-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foliviacarlisle%2Fdslib-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foliviacarlisle%2Fdslib-core/lists"}