data-structure-typed 2.5.0 → 2.5.2

package/docs-site-docusaurus/docs/guide/use-cases/treemap-javascript.md

@@ -0,0 +1,151 @@
+---
+title: TreeMap and TreeSet in JavaScript — The Missing Collections
+description: JavaScript doesn't have TreeMap or TreeSet. Here's how to get sorted maps, ordered sets, floor/ceiling lookups, and range queries in TypeScript/JavaScript.
+keywords: [treemap javascript, treeset javascript, sorted map typescript, ordered set javascript, java treemap equivalent, sorted collection]
+sidebar_label: TreeMap / TreeSet
+---
+
+# TreeMap and TreeSet in JavaScript
+
+Java has `TreeMap` and `TreeSet`. C++ has `std::map` and `std::set`. Python has `SortedDict` and `SortedSet`. JavaScript has... nothing built-in for sorted collections.
+
+`Map` and `Set` in JavaScript are **hash-based** — they don't maintain sorted order and don't support range queries, floor/ceiling, or ordered iteration by key.
+
+## The Problem
+
+```typescript
+// ❌ Native Map — no sorted iteration, no range queries
+const map = new Map<number, string>();
+map.set(3, 'c');
+map.set(1, 'a');
+map.set(2, 'b');
+[...map.keys()]; // [3, 1, 2] — insertion order, NOT sorted
+
+// ❌ To find "largest key ≤ 2.5" you'd need to sort all keys first
+const keys = [...map.keys()].sort((a, b) => a - b);
+// Then binary search... every time. O(n log n).
+```
+
+## The Solution
+
+```typescript
+import { TreeMap } from 'data-structure-typed';
+
+const map = new TreeMap<number, string>();
+map.set(3, 'c');
+map.set(1, 'a');
+map.set(2, 'b');
+
+// ✅ Sorted iteration
+[...map.keys()]; // [1, 2, 3]
+
+// ✅ NavigableMap operations — O(log n)
+map.floor(2.5);    // [2, 'b'] — largest key ≤ 2.5
+map.ceiling(1.5);  // [2, 'b'] — smallest key ≥ 1.5
+map.higher(2);     // [3, 'c'] — smallest key > 2
+map.lower(2);      // [1, 'a'] — largest key < 2
+
+// ✅ Range queries
+map.rangeSearch([1, 2]); // [[1, 'a'], [2, 'b']]
+```
+
+## TreeSet — Sorted Set
+
+```typescript
+import { TreeSet } from 'data-structure-typed';
+
+const set = new TreeSet<number>([5, 3, 8, 1, 4]);
+
+[...set]; // [1, 3, 4, 5, 8] — always sorted
+
+set.floor(4.5);   // 4
+set.ceiling(3.5); // 4
+set.higher(5);    // 8
+set.lower(3);     // 1
+
+// First and last
+set.first(); // 1
+set.last();  // 8
+```
+
+## Order-Statistic Operations
+
+Need to know "what's the 3rd element?" or "what rank is this key?"
+
+```typescript
+import { TreeMap } from 'data-structure-typed';
+
+const scores = new TreeMap<number, string>(
+  [[100, 'Alice'], [250, 'Bob'], [180, 'Charlie']],
+  { enableOrderStatistic: true }
+);
+
+scores.getByRank(0); // [100, 'Alice'] — first in tree order
+scores.getByRank(2); // [250, 'Bob'] — third in tree order
+scores.getRank(180); // 1 — Charlie is at position 1
+scores.rangeByRank(0, 1); // [[100, 'Alice'], [180, 'Charlie']]
+```
+
+## Map vs TreeMap — When to Use Which
+
+| Feature | Map | TreeMap |
+|---------|-----|---------|
+| Sorted iteration | ❌ | ✅ |
+| floor / ceiling | ❌ | ✅ |
+| Range queries | ❌ | ✅ |
+| getRank / getByRank | ❌ | ✅ |
+| Insert / lookup | O(1) avg | O(log n) |
+| Memory | Lower | Higher |
+
+**Use Map** when you only need key-value lookup and don't care about order.
+
+**Use TreeMap** when you need sorted keys, range queries, floor/ceiling, or rank operations.
+
+## Real-World Use Cases
+
+### Price book (financial trading)
+```typescript
+const orderBook = new TreeMap<number, number>(); // price → quantity
+orderBook.set(100.5, 200);
+orderBook.set(101.0, 150);
+orderBook.set(99.5, 300);
+
+// Best bid (highest price)
+orderBook.last(); // [101.0, 150]
+// All orders between $100 and $101
+orderBook.rangeSearch([100, 101]); // [[100.5, 200], [101.0, 150]]
+```
+
+### Time-series data
+```typescript
+const events = new TreeMap<number, string>(); // timestamp → event
+events.set(1000, 'start');
+events.set(2000, 'checkpoint');
+events.set(3000, 'end');
+
+// What happened at or before t=2500?
+events.floor(2500); // [2000, 'checkpoint']
+```
+
+### Leaderboard
+```typescript
+const leaderboard = new TreeMap<number, string>(
+  [[100, 'Alice'], [250, 'Bob'], [180, 'Charlie']],
+  { comparator: (a, b) => b - a, enableOrderStatistic: true }
+);
+
+// Top 3
+leaderboard.rangeByRank(0, 2);
+// [[250, 'Bob'], [180, 'Charlie'], [100, 'Alice']]
+```
+
+## Complexity
+
+| Operation | TreeMap | Sorted Array | Native Map |
+|-----------|---------|-------------|------------|
+| Insert | O(log n) | O(n) | O(1) avg |
+| Delete | O(log n) | O(n) | O(1) avg |
+| Lookup | O(log n) | O(log n) | O(1) avg |
+| Floor/Ceiling | O(log n) | O(log n) | ❌ |
+| Sorted iteration | O(n) | O(n) | ❌ |
+| Range query | O(log n + k) | O(log n + k) | ❌ |

package/docs-site-docusaurus/docusaurus.config.ts

@@ -0,0 +1,159 @@
+import {themes as prismThemes} from 'prism-react-renderer';
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'data-structure-typed',
+  tagline: 'Advanced JavaScript/TypeScript data structures that feel like arrays.',
+  favicon: 'img/favicon.png',
+  url: 'https://data-structure-typed-docs.vercel.app',
+  baseUrl: '/',
+  organizationName: 'zrwusa',
+  projectName: 'data-structure-typed',
+  onBrokenLinks: 'warn',
+  onBrokenMarkdownLinks: 'warn',
+
+  markdown: {
+    format: 'md',
+  },
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  headTags: [
+    {
+      tagName: 'meta',
+      attributes: {
+        name: 'algolia-site-verification',
+        content: '3BBF0EECA7FC2D22',
+      },
+    },
+    {
+      tagName: 'meta',
+      attributes: {
+        name: 'google-site-verification',
+        content: 'w6GgmRPPZZtNCDgG46ooge-oljMn_cm4-FCaRHoSYrQ',
+      },
+    },
+    {
+      tagName: 'meta',
+      attributes: {
+        name: 'keywords',
+        content: 'data structures, TypeScript, JavaScript, RedBlackTree, HashMap, Trie, Heap, PriorityQueue, Deque, Graph, BST, AVL Tree, zero-dependency, tree-shaking',
+      },
+    },
+    {
+      tagName: 'script',
+      attributes: {
+        type: 'application/ld+json',
+      },
+      innerHTML: JSON.stringify({
+        '@context': 'https://schema.org',
+        '@type': 'SoftwareSourceCode',
+        name: 'data-structure-typed',
+        description: 'Production-ready TypeScript data structures library — Heap, Priority Queue, TreeMap, TreeSet, Red-Black Tree, Trie, Graph, Deque, SkipList. Zero dependencies, type-safe, with getRank/getByRank/rangeByRank support.',
+        url: 'https://data-structure-typed-docs.vercel.app',
+        codeRepository: 'https://github.com/zrwusa/data-structure-typed',
+        programmingLanguage: ['TypeScript', 'JavaScript'],
+        license: 'https://opensource.org/licenses/MIT',
+        author: {
+          '@type': 'Person',
+          name: 'Pablo Zeng',
+          url: 'https://github.com/zrwusa',
+        },
+      }),
+    },
+  ],
+
+  plugins: [],
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          editUrl: 'https://github.com/zrwusa/data-structure-typed/edit/main/docs-site-docusaurus/',
+          remarkPlugins: [],
+          rehypePlugins: [],
+        },
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    image: 'img/og-image.png',
+    metadata: [
+      {name: 'og:image:width', content: '1200'},
+      {name: 'og:image:height', content: '630'},
+    ],
+    navbar: {
+      title: 'data-structure-typed',
+      logo: {
+        alt: 'data-structure-typed logo',
+        src: 'img/logo.png',
+        width: 32,
+        height: 32,
+      },
+      items: [
+        {type: 'docSidebar', sidebarId: 'guideSidebar', position: 'left', label: 'Guide'},
+        {to: '/docs/api/', label: 'API', position: 'left'},
+        {
+          href: 'https://github.com/zrwusa/data-structure-typed',
+          label: 'GitHub',
+          position: 'right',
+        },
+        {
+          href: 'https://www.npmjs.com/package/data-structure-typed',
+          label: 'npm',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'Docs',
+          items: [
+            {label: 'Installation', to: '/docs/guide/installation'},
+            {label: 'Quick Start', to: '/docs/guide/quick-start'},
+            {label: 'API Reference', to: '/docs/api/'},
+          ],
+        },
+        {
+          title: 'More',
+          items: [
+            {label: 'GitHub', href: 'https://github.com/zrwusa/data-structure-typed'},
+            {label: 'npm', href: 'https://www.npmjs.com/package/data-structure-typed'},
+            {label: 'Changelog', href: 'https://github.com/zrwusa/data-structure-typed/blob/main/CHANGELOG.md'},
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} Pablo Zeng. Built with Docusaurus.`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+    algolia: {
+      appId: '2CK3V43PRR',
+      apiKey: 'ab7ce559e3114987b4f26430427409ae',
+      indexName: 'data-structure-typed-docs-crawler',
+      contextualSearch: false,
+      searchPagePath: 'search',
+      searchParameters: {
+        hitsPerPage: 30,
+        distinct: false,
+      },
+      maxResultsPerGroup: 20,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;

package/docs-site-docusaurus/fix-mdx-generics.mjs

@@ -0,0 +1,75 @@
+/**
+ * Fix TypeScript generics <T> in TypeDoc markdown for MDX compatibility.
+ * Converts bare < > in non-fenced-code, non-backtick content to HTML entities.
+ */
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+
+function walk(dir) {
+  const results = [];
+  for (const f of readdirSync(dir)) {
+    const full = join(dir, f);
+    if (statSync(full).isDirectory()) results.push(...walk(full));
+    else if (full.endsWith('.md')) results.push(full);
+  }
+  return results;
+}
+
+function fixFile(content) {
+  // Split into fenced code blocks vs non-code sections
+  // Use a state machine that properly tracks ``` fences
+  const result = [];
+  const lines = content.split('\n');
+  let inFence = false;
+  let fenceChar = '';
+  let changed = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Detect fence start/end
+    const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      if (!inFence) {
+        inFence = true;
+        fenceChar = fenceMatch[1][0];
+      } else if (trimmed.startsWith(fenceChar.repeat(3))) {
+        inFence = false;
+      }
+      result.push(line);
+      continue;
+    }
+
+    if (inFence) {
+      result.push(line);
+      continue;
+    }
+
+    // Outside code blocks: escape generics outside of inline backticks
+    const parts = line.split(/(`[^`]*`)/);
+    const newParts = parts.map((part, i) => {
+      if (i % 2 !== 0) return part; // inside backtick
+      // Escape < ... > that look like TypeScript generics
+      return part.replace(/<([A-Za-z][^>]*)>/g, (m, inner) => {
+        changed = true;
+        return `&lt;${inner}&gt;`;
+      });
+    });
+    result.push(newParts.join(''));
+  }
+
+  return { content: result.join('\n'), changed };
+}
+
+const files = walk('docs/api');
+let count = 0;
+
+for (const f of files) {
+  const original = readFileSync(f, 'utf8');
+  const { content, changed } = fixFile(original);
+  if (changed) {
+    writeFileSync(f, content);
+    count++;
+  }
+}
+
+console.log(`✅ Fixed generics in ${count}/${files.length} files`);