data-structure-typed 2.2.2 → 2.2.4

package/src/data-structures/trie/trie.ts

@@ -112,53 +112,99 @@ export class TrieNode {
  * 10. IP Routing: Used in certain types of IP routing algorithms.
  * 11. Text Word Frequency Count: Counting and storing the frequency of words in a large amount of text data.
  * @example
- * // Autocomplete: Prefix validation and checking
- *     const autocomplete = new Trie<string>(['gmail.com', 'gmail.co.nz', 'gmail.co.jp', 'yahoo.com', 'outlook.com']);
+ * // basic Trie creation and add words
+ *  // Create a simple Trie with initial words
+ *     const trie = new Trie(['apple', 'app', 'apply']);
  *
- *     // Get all completions for a prefix
- *     const gmailCompletions = autocomplete.getWords('gmail');
- *     console.log(gmailCompletions); // ['gmail.com', 'gmail.co.nz', 'gmail.co.jp']
+ *     // Verify size
+ *     console.log(trie.size); // 3;
+ *
+ *     // Check if words exist
+ *     console.log(trie.has('apple')); // true;
+ *     console.log(trie.has('app')); // true;
+ *
+ *     // Add a new word
+ *     trie.add('application');
+ *     console.log(trie.size); // 4;
  * @example
- * // File System Path Operations
- *     const fileSystem = new Trie<string>([
- *       '/home/user/documents/file1.txt',
- *       '/home/user/documents/file2.txt',
- *       '/home/user/pictures/photo.jpg',
- *       '/home/user/pictures/vacation/',
- *       '/home/user/downloads'
- *     ]);
+ * // Trie getWords and prefix search
+ *  const trie = new Trie(['apple', 'app', 'apply', 'application', 'apricot']);
  *
- *     // Find common directory prefix
- *     console.log(fileSystem.getLongestCommonPrefix()); // '/home/user/'
+ *     // Get all words with prefix 'app'
+ *     const appWords = trie.getWords('app');
+ *     console.log(appWords); // contains 'app';
+ *     console.log(appWords); // contains 'apple';
+ *     console.log(appWords); // contains 'apply';
+ *     console.log(appWords); // contains 'application';
+ *     expect(appWords).not.toContain('apricot');
+ * @example
+ * // Trie isPrefix and isAbsolutePrefix checks
+ *  const trie = new Trie(['tree', 'trial', 'trick', 'trip', 'trie']);
  *
- *     // List all files in a directory
- *     const documentsFiles = fileSystem.getWords('/home/user/documents/');
- *     console.log(documentsFiles); // ['/home/user/documents/file1.txt', '/home/user/documents/file2.txt']
+ *     // Check if string is a prefix of any word
+ *     console.log(trie.hasPrefix('tri')); // true;
+ *     console.log(trie.hasPrefix('tr')); // true;
+ *     console.log(trie.hasPrefix('xyz')); // false;
+ *
+ *     // Check if string is an absolute prefix (not a complete word)
+ *     console.log(trie.hasPurePrefix('tri')); // true;
+ *     console.log(trie.hasPurePrefix('tree')); // false; // 'tree' is a complete word
+ *
+ *     // Verify size
+ *     console.log(trie.size); // 5;
  * @example
- * // Autocomplete: Basic word suggestions
- *     // Create a trie for autocomplete
- *     const autocomplete = new Trie<string>([
- *       'function',
- *       'functional',
- *       'functions',
- *       'class',
- *       'classes',
- *       'classical',
- *       'closure',
- *       'const',
- *       'constructor'
- *     ]);
+ * // Trie delete and iteration
+ *  const trie = new Trie(['car', 'card', 'care', 'careful', 'can', 'cat']);
+ *
+ *     // Delete a word
+ *     trie.delete('card');
+ *     console.log(trie.has('card')); // false;
+ *
+ *     // Word with same prefix still exists
+ *     console.log(trie.has('care')); // true;
  *
- *     // Test autocomplete with different prefixes
- *     console.log(autocomplete.getWords('fun')); // ['functional', 'functions', 'function']
- *     console.log(autocomplete.getWords('cla')); // ['classes', 'classical', 'class']
- *     console.log(autocomplete.getWords('con')); // ['constructor', 'const']
+ *     // Size decreased
+ *     console.log(trie.size); // 5;
  *
- *     // Test with non-matching prefix
- *     console.log(autocomplete.getWords('xyz')); // []
+ *     // Iterate through all words
+ *     const allWords = [...trie];
+ *     console.log(allWords.length); // 5;
+ * @example
+ * // Trie for autocomplete search index
+ *  // Trie is perfect for autocomplete: O(m + k) where m is prefix length, k is results
+ *     const searchIndex = new Trie(['typescript', 'javascript', 'python', 'java', 'rust', 'ruby', 'golang', 'kotlin']);
+ *
+ *     // User types 'j' - get all suggestions
+ *     const jResults = searchIndex.getWords('j');
+ *     console.log(jResults); // contains 'javascript';
+ *     console.log(jResults); // contains 'java';
+ *     console.log(jResults.length); // 2;
+ *
+ *     // User types 'ja' - get more specific suggestions
+ *     const jaResults = searchIndex.getWords('ja');
+ *     console.log(jaResults); // contains 'javascript';
+ *     console.log(jaResults); // contains 'java';
+ *     console.log(jaResults.length); // 2;
+ *
+ *     // User types 'jav' - even more specific
+ *     const javResults = searchIndex.getWords('jav');
+ *     console.log(javResults); // contains 'javascript';
+ *     console.log(javResults); // contains 'java';
+ *     console.log(javResults.length); // 2;
+ *
+ *     // Check for common prefix
+ *
+ *     console.log(searchIndex.hasCommonPrefix('ja')); // false; // Not all words start with 'ja'
+ *
+ *     // Total words in index
+ *     console.log(searchIndex.size); // 8;
+ *
+ *     // Get height (depth of tree)
+ *     const height = searchIndex.getHeight();
+ *     console.log(typeof height); // 'number';
  * @example
  * // Dictionary: Case-insensitive word lookup
- *     // Create a case-insensitive dictionary
+ *  // Create a case-insensitive dictionary
  *     const dictionary = new Trie<string>([], { caseSensitive: false });
  *
  *     // Add words with mixed casing
@@ -167,14 +213,30 @@ export class TrieNode {
  *     dictionary.add('JavaScript');
  *
  *     // Test lookups with different casings
- *     console.log(dictionary.has('hello')); // true
- *     console.log(dictionary.has('HELLO')); // true
- *     console.log(dictionary.has('Hello')); // true
- *     console.log(dictionary.has('javascript')); // true
- *     console.log(dictionary.has('JAVASCRIPT')); // true
+ *     console.log(dictionary.has('hello')); // true;
+ *     console.log(dictionary.has('HELLO')); // true;
+ *     console.log(dictionary.has('Hello')); // true;
+ *     console.log(dictionary.has('javascript')); // true;
+ *     console.log(dictionary.has('JAVASCRIPT')); // true;
+ * @example
+ * // File System Path Operations
+ *  const fileSystem = new Trie<string>([
+ *       '/home/user/documents/file1.txt',
+ *       '/home/user/documents/file2.txt',
+ *       '/home/user/pictures/photo.jpg',
+ *       '/home/user/pictures/vacation/',
+ *       '/home/user/downloads'
+ *     ]);
+ *
+ *     // Find common directory prefix
+ *     console.log(fileSystem.getLongestCommonPrefix()); // '/home/user/';
+ *
+ *     // List all files in a directory
+ *     const documentsFiles = fileSystem.getWords('/home/user/documents/');
+ *     console.log(documentsFiles); // ['/home/user/documents/file1.txt', '/home/user/documents/file2.txt'];
  * @example
  * // IP Address Routing Table
- *     // Add IP address prefixes and their corresponding routes
+ *  // Add IP address prefixes and their corresponding routes
  *     const routes = {
  *       '192.168.1': 'LAN_SUBNET_1',
  *       '192.168.2': 'LAN_SUBNET_2',
@@ -185,13 +247,13 @@ export class TrieNode {
  *     const ipRoutingTable = new Trie<string>(Object.keys(routes));
  *
  *     // Check IP address prefix matching
- *     console.log(ipRoutingTable.hasPrefix('192.168.1')); // true
- *     console.log(ipRoutingTable.hasPrefix('192.168.2')); // true
+ *     console.log(ipRoutingTable.hasPrefix('192.168.1')); // true;
+ *     console.log(ipRoutingTable.hasPrefix('192.168.2')); // true;
  *
  *     // Validate IP address belongs to subnet
  *     const ip = '192.168.1.100';
  *     const subnet = ip.split('.').slice(0, 3).join('.');
- *     console.log(ipRoutingTable.hasPrefix(subnet)); // true
+ *     console.log(ipRoutingTable.hasPrefix(subnet)); // true;
  */
 export class Trie<R = any> extends IterableElementBase<string, R> {
   /**

package/src/interfaces/binary-tree.ts

@@ -38,6 +38,8 @@ export interface IBinaryTree<K = any, V = any, R = any> {
 
   add(keyOrNodeOrEntryOrRawElement: BTNRep<K, V, BinaryTreeNode<K, V>>, value?: V, count?: number): boolean;
 
+  set(keyOrNodeOrEntryOrRawElement: BTNRep<K, V, BinaryTreeNode<K, V>>, value?: V, count?: number): boolean;
+
   // Accept raw R as well (when toEntryFn is configured)
   addMany(
     keysNodesEntriesOrRaws: Iterable<

package/src/types/data-structures/binary-tree/bst.ts

@@ -1,10 +1,10 @@
 import type { BinaryTreeOptions } from './binary-tree';
-import { Comparable } from '../../utils';
-import { OptValue } from '../../common';
+import type { Comparator, OptValue } from '../../common';
 
-export type BSTOptions<K, V, R> = Omit<BinaryTreeOptions<K, V, R>, 'isDuplicate'> & {
-  specifyComparable?: (key: K) => Comparable
-  isReverse?: boolean;
+type BSTBaseOptions<K, V, R> = Omit<BinaryTreeOptions<K, V, R>, 'isDuplicate'>;
+
+export type BSTOptions<K, V, R> = BSTBaseOptions<K, V, R> & {
+  comparator?: Comparator<K>;
 }
 
 export type BSTNOptKey<K> = K | undefined;

package/test/performance/benchmark-runner.ts

@@ -4,6 +4,7 @@ import * as fs from 'fs';
 import * as fastGlob from 'fast-glob';
 import { fork } from 'child_process';
 import { ConsoleColor, numberFix } from '../utils';
+import * as console from 'node:console';
 
 /**
  * Optimized benchmark runner
@@ -279,7 +280,7 @@ testFiles = sortByOrder(testFiles);
 if (flags.shuffle) shuffle(testFiles);
 
 const plannedCount = testFiles.length;
-const isIndividual = filters.length > 0;
+// const isIndividual = filters.length > 0;
 
 // ---------------- report utils (kept from original) ----------------
 const report: { [key: string]: any } = {};
@@ -309,19 +310,20 @@ function writeReportHTMLAndJSON(htmlTables: string) {
   ${htmlTables}
   </div></body></html>`;
 
-  if (!isIndividual) {
-    replaceMarkdownContent(
-      '[//]: # (No deletion!!! Start of Replace Section)',
-      '[//]: # (No deletion!!! End of Replace Section)',
-      htmlTables
-    );
-  }
+  // if (!isIndividual) {
+  replaceMarkdownContent(
+    '[//]: # (No deletion!!! Start of Replace Section)',
+    '[//]: # (No deletion!!! End of Replace Section)',
+    htmlTables
+  );
+  // }
   fs.writeFileSync(htmlFilePath, html);
   console.log(`Performance ${BOLD}${GREEN}report${END} file generated in file://${BOLD}${GREEN}${htmlFilePath}${END}`);
 }
 
 function replaceMarkdownContent(startMarker: string, endMarker: string, newText: string) {
-  const filePath = path.join(parentDirectory, 'README.md');
+  const filePath = path.join(parentDirectory, '/docs/PERFORMANCE.md');
+
   fs.readFile(filePath, 'utf8', (err, data) => {
     if (err) {
       console.error(`Unable to read ${filePath}:`, err);
@@ -330,10 +332,11 @@ function replaceMarkdownContent(startMarker: string, endMarker: string, newText:
     const startIndex = data.indexOf(startMarker);
     const endIndex = data.indexOf(endMarker);
     if (startIndex === -1 || endIndex === -1 || startIndex >= endIndex) {
-      console.warn('Markers not found or invalid range; skip README injection.');
+      console.warn('Markers not found or invalid range; skip PERFORMANCE injection.');
       return;
     }
-    const updatedMarkdown = data.slice(0, startIndex + startMarker.length) + '\n' + newText + data.slice(endIndex);
+    const updatedMarkdown =
+      data.slice(0, startIndex + startMarker.length) + '\n\n' + newText + '\n\n' + data.slice(endIndex);
     fs.writeFile(filePath, updatedMarkdown, 'utf8', err2 => {
       if (err2) console.error(`Unable to write to ${filePath}:`, err2);
       else console.log(`The content has been successfully replaced in file://${BOLD}${GREEN}${filePath}${END}`);

package/test/performance/data-structures/binary-tree/avl-tree.test.ts

@@ -8,13 +8,13 @@ const { HUNDRED_THOUSAND } = magnitude;
 const randomArray = getRandomIntArray(HUNDRED_THOUSAND, 0, HUNDRED_THOUSAND - 1, true);
 
 suite
-  .add(`${HUNDRED_THOUSAND.toLocaleString()} add randomly`, () => {
+  .add(`${HUNDRED_THOUSAND.toLocaleString()} set randomly`, () => {
     avlTree.clear();
-    for (let i = 0; i < randomArray.length; i++) avlTree.add(randomArray[i]);
+    for (let i = 0; i < randomArray.length; i++) avlTree.set(randomArray[i]);
   })
-  .add(`${HUNDRED_THOUSAND.toLocaleString()} add`, () => {
+  .add(`${HUNDRED_THOUSAND.toLocaleString()} set`, () => {
     avlTree.clear();
-    for (let i = 0; i < randomArray.length; i++) avlTree.add(i);
+    for (let i = 0; i < randomArray.length; i++) avlTree.set(i);
   })
   .add(`${HUNDRED_THOUSAND.toLocaleString()} get`, () => {
     for (let i = 0; i < randomArray.length; i++) avlTree.get(randomArray[i]);
@@ -26,14 +26,14 @@ suite
     const entries = [...avlTree];
     return entries.length === HUNDRED_THOUSAND;
   })
-  .add(`${HUNDRED_THOUSAND.toLocaleString()} add & delete orderly`, () => {
+  .add(`${HUNDRED_THOUSAND.toLocaleString()} set & delete orderly`, () => {
     avlTree.clear();
-    for (let i = 0; i < randomArray.length; i++) avlTree.add(i);
+    for (let i = 0; i < randomArray.length; i++) avlTree.set(i);
     for (let i = 0; i < randomArray.length; i++) avlTree.delete(i);
   })
-  .add(`${HUNDRED_THOUSAND.toLocaleString()} add & delete randomly`, () => {
+  .add(`${HUNDRED_THOUSAND.toLocaleString()} set & delete randomly`, () => {
     avlTree.clear();
-    for (let i = 0; i < randomArray.length; i++) avlTree.add(randomArray[i]);
+    for (let i = 0; i < randomArray.length; i++) avlTree.set(randomArray[i]);
     for (let i = 0; i < randomArray.length; i++) avlTree.delete(randomArray[i]);
   });
 

package/test/performance/data-structures/binary-tree/binary-tree-overall.test.ts

@@ -9,28 +9,28 @@ const { TEN_THOUSAND } = magnitude;
 const arr = getRandomIntArray(TEN_THOUSAND, 0, TEN_THOUSAND - 1, true);
 
 suite
-  .add(`${TEN_THOUSAND.toLocaleString()} RedBlackTree add randomly`, () => {
+  .add(`${TEN_THOUSAND.toLocaleString()} RedBlackTree set randomly`, () => {
     rbTree.clear();
-    for (let i = 0; i < arr.length; i++) rbTree.add(arr[i]);
+    for (let i = 0; i < arr.length; i++) rbTree.set(arr[i]);
   })
   .add(`${TEN_THOUSAND.toLocaleString()} RedBlackTree get randomly`, () => {
     for (let i = 0; i < arr.length; i++) rbTree.get(arr[i]);
   })
-  .add(`${TEN_THOUSAND.toLocaleString()} RedBlackTree add & delete randomly`, () => {
+  .add(`${TEN_THOUSAND.toLocaleString()} RedBlackTree set & delete randomly`, () => {
     rbTree.clear();
-    for (let i = 0; i < arr.length; i++) rbTree.add(arr[i]);
+    for (let i = 0; i < arr.length; i++) rbTree.set(arr[i]);
     for (let i = 0; i < arr.length; i++) rbTree.delete(arr[i]);
   })
-  .add(`${TEN_THOUSAND.toLocaleString()} AVLTree add randomly`, () => {
+  .add(`${TEN_THOUSAND.toLocaleString()} AVLTree set randomly`, () => {
     avlTree.clear();
-    for (let i = 0; i < arr.length; i++) avlTree.add(arr[i]);
+    for (let i = 0; i < arr.length; i++) avlTree.set(arr[i]);
   })
   .add(`${TEN_THOUSAND.toLocaleString()} AVLTree get randomly`, () => {
     for (let i = 0; i < arr.length; i++) avlTree.get(arr[i]);
   })
-  .add(`${TEN_THOUSAND.toLocaleString()} AVLTree add & delete randomly`, () => {
+  .add(`${TEN_THOUSAND.toLocaleString()} AVLTree set & delete randomly`, () => {
     avlTree.clear();
-    for (let i = 0; i < arr.length; i++) avlTree.add(arr[i]);
+    for (let i = 0; i < arr.length; i++) avlTree.set(arr[i]);
     for (let i = 0; i < arr.length; i++) avlTree.delete(arr[i]);
   });
 

package/test/performance/data-structures/binary-tree/binary-tree.test.ts

@@ -8,18 +8,18 @@ const { THOUSAND } = magnitude;
 const arr = getRandomIntArray(THOUSAND, 0, THOUSAND, true);
 
 suite
-  .add(`${THOUSAND.toLocaleString()} add randomly`, () => {
+  .add(`${THOUSAND.toLocaleString()} set randomly`, () => {
     biTree.clear();
-    for (let i = 0; i < arr.length; i++) biTree.add(arr[i]);
+    for (let i = 0; i < arr.length; i++) biTree.set(arr[i]);
   })
-  .add(`${THOUSAND.toLocaleString()} add & delete randomly`, () => {
+  .add(`${THOUSAND.toLocaleString()} set & delete randomly`, () => {
     biTree.clear();
-    for (let i = 0; i < arr.length; i++) biTree.add(arr[i]);
+    for (let i = 0; i < arr.length; i++) biTree.set(arr[i]);
     for (let i = 0; i < arr.length; i++) biTree.delete(arr[i]);
   })
-  .add(`${THOUSAND.toLocaleString()} addMany`, () => {
+  .add(`${THOUSAND.toLocaleString()} setMany`, () => {
     biTree.clear();
-    biTree.addMany(arr);
+    biTree.setMany(arr);
   })
   .add(`${THOUSAND.toLocaleString()} get`, () => {
     for (let i = 0; i < arr.length; i++) biTree.get(arr[i]);

package/test/performance/data-structures/binary-tree/bst.test.ts

@@ -8,18 +8,18 @@ const { TEN_THOUSAND } = magnitude;
 const arr = getRandomIntArray(TEN_THOUSAND, 0, TEN_THOUSAND, true);
 
 suite
-  .add(`${TEN_THOUSAND.toLocaleString()} add randomly`, () => {
+  .add(`${TEN_THOUSAND.toLocaleString()} set randomly`, () => {
     bst.clear();
-    for (let i = 0; i < arr.length; i++) bst.add(arr[i]);
+    for (let i = 0; i < arr.length; i++) bst.set(arr[i]);
   })
-  .add(`${TEN_THOUSAND.toLocaleString()} add & delete randomly`, () => {
+  .add(`${TEN_THOUSAND.toLocaleString()} set & delete randomly`, () => {
     bst.clear();
     for (let i = 0; i < arr.length; i++) bst.add(arr[i]);
     for (let i = 0; i < arr.length; i++) bst.delete(arr[i]);
   })
-  .add(`${TEN_THOUSAND.toLocaleString()} addMany`, () => {
+  .add(`${TEN_THOUSAND.toLocaleString()} setMany`, () => {
     bst.clear();
-    bst.addMany(arr);
+    bst.setMany(arr);
   })
   .add(`${TEN_THOUSAND.toLocaleString()} get`, () => {
     for (let i = 0; i < arr.length; i++) bst.get(arr[i]);

package/test/performance/data-structures/binary-tree/red-black-tree.test.ts

@@ -12,13 +12,13 @@ const randomArray = getRandomIntArray(MILLION, 0, MILLION - 1, true);
 const cOrderedMap = new OrderedMap<number, number>();
 
 suite
-  // .add(`${MILLION.toLocaleString()} add randomly`, () => {
+  // .add(`${MILLION.toLocaleString()} set randomly`, () => {
   //   rbTree.clear();
-  //   for (let i = 0; i < randomArray.length; i++) rbTree.add(randomArray[i]);
+  //   for (let i = 0; i < randomArray.length; i++) rbTree.set(randomArray[i]);
   // })
-  .add(`${MILLION.toLocaleString()} add`, () => {
+  .add(`${MILLION.toLocaleString()} set`, () => {
     rbTree.clear();
-    for (let i = 0; i < randomArray.length; i++) rbTree.add(i);
+    for (let i = 0; i < randomArray.length; i++) rbTree.set(i);
   })
   .add(`${MILLION.toLocaleString()} get`, () => {
     for (let i = 0; i < randomArray.length; i++) rbTree.get(randomArray[i]);
@@ -37,23 +37,23 @@ suite
     const entries = [...rbTree];
     return entries.length === MILLION;
   });
-// .add(`${MILLION.toLocaleString()} add & delete orderly`, () => {
+// .add(`${MILLION.toLocaleString()} set & delete orderly`, () => {
 //   rbTree.clear();
-//   for (let i = 0; i < randomArray.length; i++) rbTree.add(i);
+//   for (let i = 0; i < randomArray.length; i++) rbTree.set(i);
 //   for (let i = 0; i < randomArray.length; i++) rbTree.delete(i);
 // })
-// .add(`${MILLION.toLocaleString()} add & delete randomly`, () => {
+// .add(`${MILLION.toLocaleString()} set & delete randomly`, () => {
 //   rbTree.clear();
-//   for (let i = 0; i < randomArray.length; i++) rbTree.add(randomArray[i]);
+//   for (let i = 0; i < randomArray.length; i++) rbTree.set(randomArray[i]);
 //   for (let i = 0; i < randomArray.length; i++) rbTree.delete(randomArray[i]);
 // });
 
 if (true) {
   suite
-    .add(`CPT ${MILLION.toLocaleString()} add`, () => {
+    .add(`Competitor ${MILLION.toLocaleString()} set`, () => {
       for (let i = 0; i < randomArray.length; i++) cOrderedMap.setElement(randomArray[i], randomArray[i]);
     })
-    .add(`CPT ${MILLION.toLocaleString()} add`, () => {
+    .add(`Competitor ${MILLION.toLocaleString()} get`, () => {
       for (let i = 0; i < randomArray.length; i++) cOrderedMap.getElementByKey(randomArray[i]);
     });
 }

package/test/performance/reportor.ts

@@ -174,7 +174,8 @@ const composeReport = () => {
 };
 
 function replaceMarkdownContent(startMarker: string, endMarker: string, newText: string) {
-  const filePath = path.join(parentDirectory, 'README.md'); // Path to README.md file
+  const filePath = path.join(parentDirectory, '/docs/PERFORMANCE.md'); // Path to PERFORMANCE.md file
+  console.log(`Replacing ${filePath}`);
   fs.readFile(filePath, 'utf8', (err, data) => {
     if (err) {
       console.error(`Unable to read ${filePath}:`, err);

package/test/performance/single-suite-runner.ts

@@ -52,10 +52,13 @@ if (!file) {
       const benchmarks = this.map((benchmark: any) => {
         runTime += benchmark.times.elapsed;
         return {
-          'test name': benchmark.name,
-          'time taken (ms)': numberFix(benchmark.times.period * 1000, 2),
-          'sample mean (secs)': numberFix(benchmark.stats.mean, 2),
-          'sample deviation': numberFix(benchmark.stats.deviation, 2)
+          'Test Case': benchmark.name,
+          'Latency Avg (ms)': numberFix(benchmark.stats.mean * 1000, 2), // Average time
+          'Min (ms)': numberFix(Math.min(...benchmark.stats.sample) * 1000, 2),
+          'Max (ms)': numberFix(Math.max(...benchmark.stats.sample) * 1000, 2),
+          Stability: `±${numberFix(benchmark.stats.rme, 2)}%` // Relative error (better to understand than deviation)
+          // 'Samples': benchmark.stats.sample.length,                           // Number of samples
+          // 'Ops/Sec': Math.round(benchmark.hz).toLocaleString(),               // Operations per second
         };
       });
       runTime = Number(runTime.toFixed(2));

package/test/unit/data-structures/binary-tree/avl-tree-counter.test.ts

@@ -739,7 +739,7 @@ describe('AVLTreeCounter toEntryFn', () => {
           { obj: { id: 5 } }
         ])
     ).toThrowError(
-      `When comparing object types, a custom specifyComparable must be defined in the constructor's options.`
+      `When comparing object type keys, a custom comparator must be provided in the constructor's options!`
     );
   });
 
@@ -747,7 +747,7 @@ describe('AVLTreeCounter toEntryFn', () => {
     const avlCounter = new AVLTreeCounter<{ obj: { id: number } }, number>(
       [{ obj: { id: 1 } }, { obj: { id: 2 } }, { obj: { id: 3 } }, { obj: { id: 4 } }, { obj: { id: 5 } }],
       {
-        specifyComparable: key => key.obj.id
+        comparator: (a, b) => a.obj.id - b.obj.id,
       }
     );
 

package/test/unit/data-structures/binary-tree/avl-tree.test.ts

@@ -544,6 +544,104 @@ describe('AVLTree iterative methods not map mode', () => {
 });
 
 describe('classic use', () => {
+  it('@example basic AVLTree creation and add operation', () => {
+    // Create a simple AVLTree with initial values
+    const tree = new AVLTree([5, 2, 8, 1, 9]);
+
+    tree.print();
+    //   _2___
+    //  /     \
+    //  1    _8_
+    //      /   \
+    //      5   9
+
+    // Verify the tree maintains sorted order
+    expect([...tree.keys()]).toEqual([1, 2, 5, 8, 9]);
+
+    // Check size
+    expect(tree.size).toBe(5);
+
+    // Add a new element
+    tree.add(3);
+    expect(tree.size).toBe(6);
+    expect([...tree.keys()]).toEqual([1, 2, 3, 5, 8, 9]);
+  });
+
+  it('@example AVLTree has and get operations', () => {
+    const tree = new AVLTree<number>([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
+
+    // Check if element exists
+    expect(tree.has(6)).toBe(true);
+    expect(tree.has(99)).toBe(false);
+
+    // Get node by key
+    const node = tree.getNode(6);
+    expect(node?.key).toBe(6);
+
+    // Verify tree is balanced
+    expect(tree.isAVLBalanced()).toBe(true);
+  });
+
+  it('@example AVLTree delete and balance verification', () => {
+    const tree = new AVLTree([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
+
+    // Delete an element
+    tree.delete(10);
+    expect(tree.has(10)).toBe(false);
+
+    // Tree should remain balanced after deletion
+    expect(tree.isAVLBalanced()).toBe(true);
+
+    // Size decreased
+    expect(tree.size).toBe(15);
+
+    // Remaining elements are still sorted
+    const keys = [...tree.keys()];
+    expect(keys).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 12, 13, 14, 15, 16]);
+  });
+
+  it('@example AVLTree for university ranking system with strict balance', () => {
+    interface University {
+      name: string;
+      rank: number;
+      students: number;
+    }
+
+    // AVLTree provides highest search efficiency with strict balance
+    // (every node's left/right subtrees differ by at most 1 in height)
+    const universityTree = new AVLTree<number, University>([
+      [1, { name: 'MIT', rank: 1, students: 1200 }],
+      [5, { name: 'Stanford', rank: 5, students: 1800 }],
+      [3, { name: 'Harvard', rank: 3, students: 2300 }],
+      [2, { name: 'Caltech', rank: 2, students: 400 }],
+      [4, { name: 'CMU', rank: 4, students: 1500 }]
+    ]);
+
+    // Quick lookup by rank
+    const mit = universityTree.get(1);
+    expect(mit?.name).toBe('MIT');
+
+    const cmulevel = universityTree.getHeight(4);
+    expect(typeof cmulevel).toBe('number');
+
+    // Tree maintains strict balance during insertions and deletions
+    expect(universityTree.isAVLBalanced()).toBe(true);
+
+    // Add more universities
+    universityTree.add(6, { name: 'Oxford', rank: 6, students: 2000 });
+    expect(universityTree.isAVLBalanced()).toBe(true);
+
+    // Delete and verify balance is maintained
+    universityTree.delete(2);
+    expect(universityTree.has(2)).toBe(false);
+    expect(universityTree.isAVLBalanced()).toBe(true);
+
+    // Get all remaining universities in rank order
+    const remainingRanks = [...universityTree.keys()];
+    expect(remainingRanks).toEqual([1, 3, 4, 5, 6]);
+    expect(universityTree.size).toBe(5);
+  });
+
   // Test case for finding elements in a given range
   it('@example Find elements in a range', () => {
     // In interval queries, AVL trees, with their strictly balanced structure and lower height, offer better query efficiency, making them ideal for frequent and high-performance interval queries. In contrast, Red-Black trees, with lower update costs, are more suitable for scenarios involving frequent insertions and deletions where the requirements for interval queries are less demanding.
@@ -609,4 +707,23 @@ describe('classic use', () => {
       { minute: 15, temperature: 58.6 }
     ]);
   });
+
+  it('AVLTree tree height and getLeftMost', () => {
+    const tree = new AVLTree([5, 2, 8, 1, 9, 3, 7]);
+
+    // Get tree height
+    const height = tree.getHeight();
+    expect(typeof height).toBe('number');
+
+    // Get height of specific node
+    const heightOf5 = tree.getHeight(5);
+    expect(typeof heightOf5).toBe('number');
+
+    // Find leftmost (smallest) element
+    const min = tree.getLeftMost();
+    expect(min).toBe(1);
+
+    // Verify tree is balanced
+    expect(tree.isAVLBalanced()).toBe(true);
+  });
 });