data-structure-typed 2.5.0 → 2.5.1

package/docs-site-docusaurus/docs/guide/quick-start.md

@@ -0,0 +1,73 @@
+---
+description: "Get started with data-structure-typed in 30 seconds. Create trees, queues, and maps with a familiar JavaScript API."
+---
+
+# Quick Start
+
+## Leaderboard (Ranked Collections)
+
+```typescript
+import { RedBlackTree } from 'data-structure-typed';
+
+// Descending comparator — highest scores first
+const leaderboard = new RedBlackTree<number, string>([
+  [100, 'Alice'],
+  [85, 'Bob'],
+  [92, 'Charlie']
+], { comparator: (a, b) => b - a });
+
+// Top-2 via lazy iterator — O(2 log n), no full traversal
+const iter = leaderboard.entries();
+for (let i = 0; i < 2; i++) {
+  const { value: [score, player] } = iter.next();
+  console.log(`${score}: ${player}`);
+}
+// Output: 100: Alice → 92: Charlie
+
+// Update score — O(log n)
+leaderboard.delete(85);
+leaderboard.set(95, 'Bob');
+
+// Range query — players scoring 90~100, O(log n + k)
+const scores90to100 = leaderboard.rangeSearch([90, 100]);
+```
+
+## Task Queue (Scheduling)
+
+```typescript
+import { MinPriorityQueue } from 'data-structure-typed';
+
+const tasks = new MinPriorityQueue<{ task: string; priority: number }>(
+  [], { comparator: (a, b) => a.priority - b.priority }
+);
+
+tasks.add({ task: 'Send email', priority: 3 });
+tasks.add({ task: 'Fix critical bug', priority: 1 });
+tasks.add({ task: 'Update docs', priority: 2 });
+
+// Process in priority order
+while (!tasks.isEmpty()) {
+  const next = tasks.poll();
+  console.log(next?.task);
+}
+// Fix critical bug → Update docs → Send email
+```
+
+## Fast Autocomplete (Trie)
+
+```typescript
+import { Trie } from 'data-structure-typed';
+
+const trie = new Trie();
+trie.addMany(['apple', 'application', 'app', 'apex']);
+
+console.log(trie.getWords('app')); // ['app', 'apple', 'application']
+console.log(trie.hasPrefix('ap')); // true
+```
+
+## Next Steps
+
+- 📖 [Core Concepts](/guide/concepts) — understand the Big Three
+- 📋 [API Reference](/api/) — full method signatures and examples
+- 💡 [Real-World Examples](/guide/guides) — patterns for production
+- ⚡ [Performance](/guide/performance) — benchmarks and comparisons

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: 'A comprehensive TypeScript and JavaScript data structures library featuring production-ready implementations, zero dependencies, and an intuitive Array-like API.',
+        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`);