data-structure-typed 2.2.2 → 2.2.4

package/SPONSOR.zh-CN.md

@@ -0,0 +1,62 @@
+# 关于我
+
+我是一名拥有超过 15 年专业经验的资深软件开发工程师。毕业以来，我曾在不同行业的各类软件公司磨练技艺，并为多个知名平台做出过贡献。
+
+我将自己描述为一个带有完美主义倾向的技术狂热者。我对技术本质的深入钻研和严肃的态度，有时会让我看起来像个“严厉的老板”——这一特质有时会让我的家人感到既敬畏又好笑。然而，我的人生态度是建立在宽广胸怀之上的，关键词是爱、忠诚和对美的欣赏。我也非常享受探索不同地区的文化差异，并且内心深处其实藏着一点艺术天分。
+
+# 项目背后的故事
+
+我最近移居马来西亚，初衷是为了给女儿提供更全面、正规的教育。作为 MM2H（10年长期居留签证）持有者，我受到限制，无法受雇于当地的马来西亚公司。
+
+我没有将其视为限制，而是将其视为一个机会。出于对编程的终身热爱，并认识到 JavaScript/TypeScript 生态系统中存在一个关键缺口——缺乏标准化的、高性能的数据结构库——我踏上了构建 `data-structure-typed` 的旅程。
+
+# 项目概览：`data-structure-typed`
+
+## 终极目标
+
+**无缝集成到 JavaScript 和 TypeScript 的标准库中。**
+
+## 解决实际痛点
+
+### 1. 提升性能
+- **Queue（队列）& Deque（双端队列）**：开发者经常使用 JavaScript 数组来模拟队列。然而，`Array.shift()` 的时间复杂度是 **O(n)**。我们实现了时间复杂度为 **O(1)** 的 Queue 和 Deque 结构，为大数据集提供了巨大的性能提升。
+- **HashMap（哈希映射）**：JavaScript 内置的 `Map` 技术上是 `LinkedHashMap`，因为它维护插入顺序。这带来了额外开销。我们实现了一个纯粹的 **HashMap**，优先考虑原始性能而非顺序。
+
+### 2. 为 JS/TS 引入缺失的结构
+- **Heap（堆）/ Priority Queue（优先队列）**：对于高效算法至关重要，堆支持 O(log n) 的插入/删除和 O(1) 的极值访问。这些在其他语言中是标准的，但在 JS 原生中缺失。
+- **Red-Black Tree（红黑树）**：数据库和系统设计中的主打结构，红黑树在平衡二叉搜索树中提供了查找、插入和删除性能之间的最佳平衡。
+
+## 核心优势
+
+### 🚀 卓越性能
+我们的基准测试显示，`data-structure-typed` 的实现通常超过原生 JS 结构（如 `Queue` 对比 `Array`），并与 C++ 或 Java 等语言的标准库相当。我们正在持续优化复杂的结构，如 `Graph`（图）和 `AVL Tree`（AVL 树）。
+
+### ⚡ 统一且标准化的 API
+1.  **标准命名**：我们在所有数据结构中实现了标准方法（`forEach`, `filter`, `map`, `reduce`, `find`, `clear` 等）以保持一致性。
+2.  **符合 ES6 规范**：我们使用生成器来实现 `[Symbol.iterator]`, `keys()`, `values()`, 和 `entries()`。这允许惰性求值并在遍历期间提供更好的控制。
+3.  **可预测的接口**：
+    - **构造函数**：始终接受 `(data, configuration)`。
+    - **返回类型**：像 `add()` 这样的方法始终返回布尔值以指示成功。
+    - **可迭代**：在数据结构之间无缝转换（例如，从数组初始化树）。
+
+有关技术规范、基准测试和 API 文档，请访问：
+- [GitHub 仓库](https://github.com/zrwusa/data-structure-typed)
+- [在线文档](https://data-structure-typed-docs.vercel.app/)
+
+# 社区与影响
+
+该项目在开源社区中正获得越来越多的关注：
+- ![NPM Downloads](https://img.shields.io/npm/dm/data-structure-typed)
+- ![GitHub Stars](https://img.shields.io/github/stars/zrwusa/data-structure-typed)
+- ![Contributors](https://img.shields.io/github/contributors/zrwusa/data-structure-typed)
+
+# 为什么赞助？
+
+从严格的软件工程标准来看，我认为 `data-structure-typed` 目前已完成了 **75%**。
+
+您的赞助不仅仅是捐赠；它是对 JavaScript 生态系统的投资。它将使我能够：
+1.  **加速开发**：迅速将项目推进到 **95% 的完成度**，完善边缘情况和文档。
+2.  **维持维护**：支持我的家庭，使我能够全职投入这项开源工作。
+3.  **实现标准化**：帮助推动该库成为全球 TS/JS 开发者的事实标准。
+
+感谢您支持开源和高性能软件工程！

package/SPONSOR_POLISHED.md

@@ -0,0 +1,62 @@
+# About Me
+
+I am a seasoned software development engineer with over 15 years of professional experience. Since graduating, I have honed my expertise across various software companies and diverse industries, contributing to several prominent platforms.
+
+I describe myself as a technology enthusiast with a perfectionist streak. My deep focus on the essence of technical problems and my serious demeanor can sometimes make me appear as a "stern boss"—a trait that my family occasionally finds amusingly intense. However, my outlook on life is grounded in broad-mindedness, defined by love, loyalty, and an appreciation for beauty. I find great joy in exploring cultural differences across regions and harbor a hidden artistic flair.
+
+# The Story Behind the Project
+
+My recent relocation to Malaysia was driven by a desire to provide my daughter with a comprehensive, formal education. As a holder of the MM2H (10-year residency) visa, I am restricted from seeking employment with local Malaysian companies. 
+
+Rather than seeing this as a limitation, I viewed it as an opportunity. Fueled by my lifelong passion for programming and recognizing a critical gap in the JavaScript/TypeScript ecosystem—the absence of a standardized, high-performance data structures library—I embarked on the journey to build `data-structure-typed`.
+
+# Project Overview: `data-structure-typed`
+
+## Ultimate Goal
+
+**To seamlessly integrate into the standard library of JavaScript and TypeScript.**
+
+## Solving Real Pain Points
+
+### 1. Enhancing Performance
+- **Queue & Deque**: Developers often resort to using JavaScript Arrays to simulate Queues. However, `Array.shift()` has a time complexity of **O(n)**. We have implemented Queue and Deque structures with **O(1)** time complexity, offering massive performance gains for large datasets.
+- **HashMap**: The built-in JavaScript `Map` is technically a `LinkedHashMap` because it maintains insertion order. This comes with overhead. We have implemented a pure **HashMap** that prioritizes raw performance over ordering.
+
+### 2. Bringing Missing Structures to JS/TS
+- **Heap / Priority Queue**: Essential for efficient algorithms, Heaps support O(log n) insertion/deletion and O(1) access to min/max values. These are standard in other languages but missing natively in JS.
+- **Red-Black Tree**: A staple in database and system design, the Red-Black Tree offers the best balance between lookup, insertion, and deletion performance among balanced binary search trees.
+
+## Key Advantages
+
+### 🚀 Superior Performance
+Our benchmarks show that `data-structure-typed` implementations often surpass native JS structures (like `Queue` vs `Array`) and are comparable to standard libraries in languages like C++ or Java. We are continuously refining complex structures like `Graph` and `AVL Tree`.
+
+### ⚡ Uniform & Standardized API
+1.  **Standard Naming**: We implement standard methods (`forEach`, `filter`, `map`, `reduce`, `find`, `clear`, etc.) across all data structures for consistency.
+2.  **ES6 Compliance**: We use generators for `[Symbol.iterator]`, `keys()`, `values()`, and `entries()`. This allows for lazy evaluation and better control during traversal.
+3.  **Predictable Interfaces**: 
+    - **Constructors**: Always accept `(data, configuration)`.
+    - **Return Types**: Methods like `add()` consistently return booleans to indicate success.
+    - **Iterables**: Seamlessly convert between data structures (e.g., initialize a Tree from an Array).
+
+For technical specifications, benchmarks, and API documentation, please visit:
+- [GitHub Repository](https://github.com/zrwusa/data-structure-typed)
+- [Documentation](https://data-structure-typed-docs.vercel.app/)
+
+# Community & Impact
+
+The project is gaining traction in the open-source community:
+- ![NPM Downloads](https://img.shields.io/npm/dm/data-structure-typed)
+- ![GitHub Stars](https://img.shields.io/github/stars/zrwusa/data-structure-typed)
+- ![Contributors](https://img.shields.io/github/contributors/zrwusa/data-structure-typed)
+
+# Why Sponsor?
+
+From a strict software engineering perspective, I consider `data-structure-typed` to be **75% complete**. 
+
+Your sponsorship is not just a donation; it is an investment in the JavaScript ecosystem. It will allow me to:
+1.  **Accelerate Development**: Swiftly bring the project to **95% completion**, polishing edge cases and documentation.
+2.  **Sustain Maintenance**: Support my family while I dedicate full-time effort to this open-source work.
+3.  **Achieve Standardization**: Help push this library closer to becoming a de-facto standard for TS/JS developers worldwide.
+
+Thank you for supporting open source and high-performance software engineering!

package/benchmark/report.html

@@ -10,5 +10,5 @@
     .content table tr:nth-child(odd) { background:#fff; }
   </style></head><body><div class="content">
   <div class="json-to-html-title">Benchmark Report</div>
-  <h2>red-black-tree</h2><table><thead><tr><th>test name</th><th>time taken (ms)</th><th>sample mean (secs)</th><th>sample deviation</th></tr></thead><tbody><tr><td>1,000,000 add</td><td>410.34</td><td>0.41</td><td>0.01</td></tr><tr><td>1,000,000 get</td><td>5.20</td><td>0.01</td><td>8.16e-5</td></tr><tr><td>1,000,000 iterator</td><td>154.25</td><td>0.15</td><td>0.02</td></tr><tr><td>CPT 1,000,000 add</td><td>656.43</td><td>0.66</td><td>0.00</td></tr><tr><td>CPT 1,000,000 add</td><td>684.17</td><td>0.68</td><td>0.01</td></tr></tbody></table><h2>queue</h2><table><thead><tr><th>test name</th><th>time taken (ms)</th><th>sample mean (secs)</th><th>sample deviation</th></tr></thead><tbody><tr><td>1,000,000 push</td><td>26.97</td><td>0.03</td><td>0.00</td></tr><tr><td>100,000 push & shift</td><td>2.87</td><td>0.00</td><td>2.71e-4</td></tr><tr><td>Native JS Array 100,000 push & shift</td><td>1120.94</td><td>1.12</td><td>0.20</td></tr></tbody></table><h2>deque</h2><table><thead><tr><th>test name</th><th>time taken (ms)</th><th>sample mean (secs)</th><th>sample deviation</th></tr></thead><tbody><tr><td>1,000,000 push</td><td>8.75</td><td>0.01</td><td>6.99e-4</td></tr><tr><td>1,000,000 push & pop</td><td>12.95</td><td>0.01</td><td>4.21e-4</td></tr><tr><td>1,000,000 push & shift</td><td>13.73</td><td>0.01</td><td>4.53e-4</td></tr><tr><td>100,000 push & shift</td><td>1.36</td><td>0.00</td><td>5.42e-5</td></tr><tr><td>Native JS Array 100,000 push & shift</td><td>1167.06</td><td>1.17</td><td>0.26</td></tr><tr><td>100,000 unshift & shift</td><td>1.31</td><td>0.00</td><td>4.73e-5</td></tr><tr><td>Native JS Array 100,000 unshift & shift</td><td>1911.47</td><td>1.91</td><td>0.02</td></tr></tbody></table><h2>heap</h2><table><thead><tr><th>test name</th><th>time taken (ms)</th><th>sample mean (secs)</th><th>sample deviation</th></tr></thead><tbody><tr><td>100,000 add</td><td>4.60</td><td>0.00</td><td>1.07e-4</td></tr><tr><td>100,000 add & poll</td><td>16.96</td><td>0.02</td><td>3.45e-4</td></tr></tbody></table><h2>avl-tree</h2><table><thead><tr><th>test name</th><th>time taken (ms)</th><th>sample mean (secs)</th><th>sample deviation</th></tr></thead><tbody><tr><td>100,000 add randomly</td><td>324.51</td><td>0.32</td><td>0.01</td></tr><tr><td>100,000 add</td><td>299.76</td><td>0.30</td><td>0.02</td></tr><tr><td>100,000 get</td><td>0.26</td><td>2.58e-4</td><td>3.65e-6</td></tr><tr><td>100,000 getNode</td><td>169.33</td><td>0.17</td><td>0.00</td></tr><tr><td>100,000 iterator</td><td>14.43</td><td>0.01</td><td>0.00</td></tr><tr><td>100,000 add & delete orderly</td><td>434.44</td><td>0.43</td><td>0.01</td></tr><tr><td>100,000 add & delete randomly</td><td>541.78</td><td>0.54</td><td>0.01</td></tr></tbody></table><h2>hash-map</h2><table><thead><tr><th>test name</th><th>time taken (ms)</th><th>sample mean (secs)</th><th>sample deviation</th></tr></thead><tbody><tr><td>1,000,000 set</td><td>43.23</td><td>0.04</td><td>0.01</td></tr><tr><td>Native JS Map 1,000,000 set</td><td>147.12</td><td>0.15</td><td>0.01</td></tr><tr><td>Native JS Set 1,000,000 add</td><td>116.18</td><td>0.12</td><td>0.01</td></tr><tr><td>1,000,000 set & get</td><td>46.39</td><td>0.05</td><td>0.01</td></tr><tr><td>Native JS Map 1,000,000 set & get</td><td>196.92</td><td>0.20</td><td>0.01</td></tr><tr><td>Native JS Set 1,000,000 add & has</td><td>163.92</td><td>0.16</td><td>0.01</td></tr><tr><td>1,000,000 ObjKey set & get</td><td>243.36</td><td>0.24</td><td>0.03</td></tr><tr><td>Native JS Map 1,000,000 ObjKey set & get</td><td>211.66</td><td>0.21</td><td>0.02</td></tr><tr><td>Native JS Set 1,000,000 ObjKey add & has</td><td>196.57</td><td>0.20</td><td>0.01</td></tr></tbody></table><h2>directed-graph</h2><table><thead><tr><th>test name</th><th>time taken (ms)</th><th>sample mean (secs)</th><th>sample deviation</th></tr></thead><tbody><tr><td>1,000 addVertex</td><td>0.05</td><td>4.60e-5</td><td>6.59e-7</td></tr><tr><td>1,000 addEdge</td><td>3.02</td><td>0.00</td><td>2.85e-4</td></tr><tr><td>1,000 getVertex</td><td>0.04</td><td>3.77e-5</td><td>4.66e-7</td></tr><tr><td>1,000 getEdge</td><td>41.48</td><td>0.04</td><td>0.01</td></tr><tr><td>tarjan</td><td>240.33</td><td>0.24</td><td>0.01</td></tr><tr><td>topologicalSort</td><td>195.62</td><td>0.20</td><td>0.01</td></tr></tbody></table><h2>trie</h2><table><thead><tr><th>test name</th><th>time taken (ms)</th><th>sample mean (secs)</th><th>sample deviation</th></tr></thead><tbody><tr><td>100,000 push</td><td>27.15</td><td>0.03</td><td>6.61e-4</td></tr><tr><td>100,000 getWords</td><td>41.18</td><td>0.04</td><td>0.00</td></tr></tbody></table><h2>stack</h2><table><thead><tr><th>test name</th><th>time taken (ms)</th><th>sample mean (secs)</th><th>sample deviation</th></tr></thead><tbody><tr><td>1,000,000 push</td><td>25.21</td><td>0.03</td><td>0.00</td></tr><tr><td>1,000,000 push & pop</td><td>29.12</td><td>0.03</td><td>0.00</td></tr></tbody></table>
+  <h2>red-black-tree</h2><table><thead><tr><th>Test Case</th><th>Latency Avg (ms)</th><th>Min (ms)</th><th>Max (ms)</th><th>Stability</th></tr></thead><tbody><tr><td>1,000,000 set</td><td>508.80</td><td>407.39</td><td>735.02</td><td>±16.47%</td></tr><tr><td>1,000,000 get</td><td>3.60</td><td>2.59</td><td>10.73</td><td>±12.76%</td></tr><tr><td>1,000,000 iterator</td><td>181.28</td><td>131.67</td><td>399.35</td><td>±21.13%</td></tr><tr><td>Competitor 1,000,000 set</td><td>657.36</td><td>646.08</td><td>668.05</td><td>±0.94%</td></tr><tr><td>Competitor 1,000,000 get</td><td>707.92</td><td>661.39</td><td>774.77</td><td>±4.43%</td></tr></tbody></table><h2>queue</h2><table><thead><tr><th>Test Case</th><th>Latency Avg (ms)</th><th>Min (ms)</th><th>Max (ms)</th><th>Stability</th></tr></thead><tbody><tr><td>1,000,000 push</td><td>26.83</td><td>21.26</td><td>67.52</td><td>±7.94%</td></tr><tr><td>100,000 push & shift</td><td>2.71</td><td>2.40</td><td>3.56</td><td>±1.99%</td></tr><tr><td>Native JS Array 100,000 push & shift</td><td>1214.60</td><td>1060.42</td><td>1423.06</td><td>±10.02%</td></tr></tbody></table><h2>deque</h2><table><thead><tr><th>Test Case</th><th>Latency Avg (ms)</th><th>Min (ms)</th><th>Max (ms)</th><th>Stability</th></tr></thead><tbody><tr><td>1,000,000 push</td><td>8.85</td><td>8.48</td><td>9.64</td><td>±0.50%</td></tr><tr><td>1,000,000 push & pop</td><td>13.52</td><td>13.02</td><td>14.76</td><td>±0.54%</td></tr><tr><td>1,000,000 push & shift</td><td>14.08</td><td>13.62</td><td>15.34</td><td>±0.51%</td></tr><tr><td>100,000 push & shift</td><td>1.35</td><td>1.31</td><td>1.44</td><td>±0.33%</td></tr><tr><td>Native JS Array 100,000 push & shift</td><td>1429.15</td><td>944.17</td><td>1975.05</td><td>±26.96%</td></tr><tr><td>100,000 unshift & shift</td><td>1.29</td><td>1.25</td><td>1.54</td><td>±0.68%</td></tr><tr><td>Native JS Array 100,000 unshift & shift</td><td>2200.25</td><td>1844.73</td><td>2839.30</td><td>±17.78%</td></tr></tbody></table><h2>heap</h2><table><thead><tr><th>Test Case</th><th>Latency Avg (ms)</th><th>Min (ms)</th><th>Max (ms)</th><th>Stability</th></tr></thead><tbody><tr><td>100,000 add</td><td>4.70</td><td>4.36</td><td>5.15</td><td>±0.81%</td></tr><tr><td>100,000 add & poll</td><td>17.31</td><td>16.65</td><td>18.67</td><td>±0.57%</td></tr></tbody></table><h2>avl-tree</h2><table><thead><tr><th>Test Case</th><th>Latency Avg (ms)</th><th>Min (ms)</th><th>Max (ms)</th><th>Stability</th></tr></thead><tbody><tr><td>100,000 set randomly</td><td>354.58</td><td>320.37</td><td>396.77</td><td>±5.90%</td></tr><tr><td>100,000 set</td><td>310.29</td><td>294.79</td><td>362.25</td><td>±4.57%</td></tr><tr><td>100,000 get</td><td>0.26</td><td>0.25</td><td>0.29</td><td>±0.44%</td></tr><tr><td>100,000 getNode</td><td>199.21</td><td>170.37</td><td>228.69</td><td>±4.40%</td></tr><tr><td>100,000 iterator</td><td>15.41</td><td>13.39</td><td>29.67</td><td>±4.05%</td></tr><tr><td>100,000 set & delete orderly</td><td>436.63</td><td>426.38</td><td>457.78</td><td>±1.52%</td></tr><tr><td>100,000 set & delete randomly</td><td>526.98</td><td>512.67</td><td>544.63</td><td>±1.87%</td></tr></tbody></table><h2>hash-map</h2><table><thead><tr><th>Test Case</th><th>Latency Avg (ms)</th><th>Min (ms)</th><th>Max (ms)</th><th>Stability</th></tr></thead><tbody><tr><td>1,000,000 set</td><td>40.68</td><td>33.35</td><td>59.21</td><td>±4.69%</td></tr><tr><td>Native JS Map 1,000,000 set</td><td>144.13</td><td>131.77</td><td>167.71</td><td>±3.43%</td></tr><tr><td>Native JS Set 1,000,000 add</td><td>112.65</td><td>104.13</td><td>148.36</td><td>±4.84%</td></tr><tr><td>1,000,000 set & get</td><td>45.40</td><td>36.83</td><td>57.24</td><td>±4.56%</td></tr><tr><td>Native JS Map 1,000,000 set & get</td><td>195.80</td><td>184.61</td><td>220.64</td><td>±3.12%</td></tr><tr><td>Native JS Set 1,000,000 add & has</td><td>159.47</td><td>148.45</td><td>196.09</td><td>±4.13%</td></tr><tr><td>1,000,000 ObjKey set & get</td><td>239.09</td><td>210.63</td><td>272.97</td><td>±5.14%</td></tr><tr><td>Native JS Map 1,000,000 ObjKey set & get</td><td>207.48</td><td>181.81</td><td>240.56</td><td>±5.90%</td></tr><tr><td>Native JS Set 1,000,000 ObjKey add & has</td><td>188.86</td><td>162.40</td><td>246.83</td><td>±8.41%</td></tr></tbody></table><h2>directed-graph</h2><table><thead><tr><th>Test Case</th><th>Latency Avg (ms)</th><th>Min (ms)</th><th>Max (ms)</th><th>Stability</th></tr></thead><tbody><tr><td>1,000 addVertex</td><td>0.05</td><td>0.04</td><td>0.05</td><td>±0.37%</td></tr><tr><td>1,000 addEdge</td><td>3.00</td><td>2.78</td><td>5.35</td><td>±2.48%</td></tr><tr><td>1,000 getVertex</td><td>0.04</td><td>0.04</td><td>0.04</td><td>±0.52%</td></tr><tr><td>1,000 getEdge</td><td>44.78</td><td>40.89</td><td>97.02</td><td>±5.62%</td></tr><tr><td>tarjan</td><td>241.55</td><td>235.87</td><td>269.07</td><td>±1.82%</td></tr><tr><td>topologicalSort</td><td>200.74</td><td>197.47</td><td>219.65</td><td>±1.30%</td></tr></tbody></table><h2>trie</h2><table><thead><tr><th>Test Case</th><th>Latency Avg (ms)</th><th>Min (ms)</th><th>Max (ms)</th><th>Stability</th></tr></thead><tbody><tr><td>100,000 push</td><td>27.66</td><td>25.13</td><td>37.31</td><td>±1.98%</td></tr><tr><td>100,000 getWords</td><td>64.62</td><td>37.66</td><td>288.42</td><td>±29.56%</td></tr></tbody></table><h2>stack</h2><table><thead><tr><th>Test Case</th><th>Latency Avg (ms)</th><th>Min (ms)</th><th>Max (ms)</th><th>Stability</th></tr></thead><tbody><tr><td>1,000,000 push</td><td>26.57</td><td>22.36</td><td>33.50</td><td>±3.44%</td></tr><tr><td>1,000,000 push & pop</td><td>30.30</td><td>25.14</td><td>55.18</td><td>±4.78%</td></tr></tbody></table>
   </div></body></html>