@calcit/ternary-tree 0.0.24 → 0.0.25

package/README.md

@@ -40,7 +40,7 @@ function sameMapShape<K, T>(xs: TernaryTreeMap<K, T>, ys: TernaryTreeMap<K, T>):
 
 List functions:
 
-```ts
+````ts
 function makeTernaryTreeList<T>(size: number, offset: number, xs: /* var */ Array<TernaryTreeList<T>>): TernaryTreeList<T>;
 function initTernaryTreeList<T>(xs: Array<T>): TernaryTreeList<T>;
 function initEmptyTernaryTreeList<T>(): TernaryTreeList<T>;
@@ -75,9 +75,29 @@ function sameListShape<T>(xs: TernaryTreeList<T>, ys: TernaryTreeList<T>): boole
 function getDepth<T>(tree: TernaryTreeList<T>): number;
 function listToString<T>(tree: TernaryTreeList<T>): string;
 function formatListInline<T>(tree: TernaryTreeList<T>): string;
-function checkListStructure<T>(tree: TernaryTreeList<T>): boolean;
+function checkList
+
+### Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Build TypeScript
+yarn build
+
+# Run all tests
+yarn test
+
+# Run specific test suites
+yarn test:list    # List-related tests only
+yarn test:map     # Map-related tests only
+````
+
+For detailed testing information, see [TESTING.md](./TESTING.md).Structure<T>(tree: TernaryTreeList<T>): boolean;
 function forceListInplaceBalancing<T>(tree: TernaryTreeList<T>): void;
-```
+
+````
 
 To overwrite internals behaviors:
 
@@ -85,7 +105,7 @@ To overwrite internals behaviors:
 overwriteHashGenerator(f);
 
 overwriteComparator(f);
-```
+````
 
 ### License
 

package/TESTING.md

@@ -0,0 +1,155 @@
+# Testing Guide
+
+## Overview
+
+This project uses a custom lightweight testing framework that provides colored output, test organization, and detailed error reporting.
+
+## Running Tests
+
+### Basic Commands
+
+```bash
+# Build and run all tests
+yarn test
+
+# Only compile (useful for checking TypeScript errors)
+yarn build
+
+# Run tests manually after building
+node lib/test.mjs
+```
+
+### Selective Testing
+
+```bash
+# Run only list tests (any test with "list" in the name)
+yarn test:list
+
+# Run only map tests (any test with "map" in the name)
+yarn test:map
+
+# Use environment variable for custom filtering
+TARGET=specific-test-name yarn test
+```
+
+## Test Framework Features
+
+### Test Organization
+
+- **Test Suites**: Use `describe()` to group related tests
+- **Individual Tests**: Use `test()` for specific test cases
+- **Colored Output**: Green ✓ for passing tests, red ✗ for failing tests
+- **Timing**: Shows execution time for each test
+
+### Assertion Functions
+
+#### Basic Assertions
+
+```typescript
+check(condition: boolean, message?: string)
+```
+
+#### Equality Checks
+
+```typescript
+checkEqual<T>(actual: T, expected: T, message?: string)
+checkDeepEqual<T>(actual: T, expected: T, message?: string)
+```
+
+#### Array Comparisons
+
+```typescript
+checkArrayEqual<T>(actual: Array<T>, expected: Array<T>, message?: string)
+arrayEqual<T>(xs: Array<T>, ys: Array<T>): boolean
+```
+
+#### Exception Testing
+
+```typescript
+checkThrows(fn: () => void, message?: string)
+```
+
+#### Debug Utilities
+
+```typescript
+justDisplay(actual: any, expected: any)  // For comparing values visually
+```
+
+### Example Test Structure
+
+```typescript
+import { describe, test, check, checkEqual, checkArrayEqual } from "./test-utils.mjs";
+
+export function runMyTests() {
+  describe("My Component Tests", () => {
+    test("should do something basic", () => {
+      const result = myFunction();
+      check(result !== null, "Result should not be null");
+      checkEqual(result.status, "success");
+    });
+
+    test("should handle arrays correctly", () => {
+      const actual = [1, 2, 3];
+      const expected = [1, 2, 3];
+      checkArrayEqual(actual, expected);
+    });
+
+    test("should throw on invalid input", () => {
+      checkThrows(() => {
+        myFunction(null);
+      }, "Should throw on null input");
+    });
+  });
+}
+```
+
+## Test Output
+
+The framework provides:
+
+- **Suite Organization**: Clear grouping with cyan headers
+- **Individual Results**: Green checkmarks for passing tests
+- **Timing Information**: Execution time for each test
+- **Error Details**: Clear error messages with stack traces
+- **Summary Statistics**: Total tests, passed, failed counts
+- **Exit Codes**: Non-zero exit code on test failures
+
+## Current Test Coverage
+
+### TernaryTreeList Tests (15 tests)
+
+- Initialization and basic operations
+- List insertions and modifications
+- Concatenation and merging
+- Equality checking and comparison
+- Balancing and structure integrity
+- Iteration and traversal
+- Slicing and reversal
+- Index finding and mapping
+- Stress testing
+
+### TernaryTreeMap Tests (12 tests)
+
+- Map initialization and creation
+- Association and containment checking
+- Structure integrity validation
+- Dissociation operations
+- Array conversion and iteration
+- Equality and shape comparison
+- Map merging with various strategies
+- Value mapping transformations
+- Large dataset handling
+
+## Adding New Tests
+
+1. Create test functions in existing or new test files
+2. Use the `describe()` and `test()` structure
+3. Import and call your test function in `test.mts`
+4. Use appropriate assertion functions for validation
+5. Run `yarn test` to verify everything works
+
+## Performance Considerations
+
+- Tests include timing information to identify slow operations
+- Stress tests (like concat loop test) help identify performance regressions
+- Structure integrity checks validate the internal tree consistency

package/lib/benchmark.d.mts

@@ -0,0 +1 @@
+export {};

package/lib/benchmark.mjs

@@ -0,0 +1,67 @@
+// Performance comparison script
+import { initTernaryTreeMap, initTernaryTreeMapFromArray, contains, mapGetDefault, toPairsArray, } from "./map.mjs";
+function createTestData(size) {
+    const data = [];
+    for (let i = 0; i < size; i++) {
+        data.push([i, `value_${i}`]);
+    }
+    return data;
+}
+function measureTime(fn, iterations = 1) {
+    const start = performance.now();
+    for (let i = 0; i < iterations; i++) {
+        fn();
+    }
+    const end = performance.now();
+    return (end - start) / iterations;
+}
+function runComparison() {
+    console.log("=== Performance Optimization Results ===\n");
+    const sizes = [1000, 5000, 10000];
+    const iterations = 5; // Run multiple times for more accurate results
+    for (const size of sizes) {
+        console.log(`--- ${size} elements (averaged over ${iterations} runs) ---`);
+        const testData = createTestData(size);
+        const mapData = new Map(testData);
+        // Test initTernaryTreeMapFromArray performance
+        const arrayTime = measureTime(() => {
+            return initTernaryTreeMapFromArray(testData);
+        }, iterations);
+        const mapTime = measureTime(() => {
+            return initTernaryTreeMap(mapData);
+        }, iterations);
+        console.log(`initTernaryTreeMapFromArray: ${arrayTime.toFixed(2)}ms`);
+        console.log(`initTernaryTreeMap: ${mapTime.toFixed(2)}ms`);
+        // Create tree for lookup tests
+        const tree = initTernaryTreeMapFromArray(testData);
+        // Test lookup performance
+        const lookupKeys = testData.slice(0, 100).map(([k]) => k);
+        const lookupTime = measureTime(() => {
+            for (const key of lookupKeys) {
+                contains(tree, key);
+                mapGetDefault(tree, key, "default");
+            }
+        }, iterations);
+        console.log(`Lookups (100 operations): ${lookupTime.toFixed(2)}ms`);
+        // Test toPairsArray performance
+        const toPairsTime = measureTime(() => {
+            return toPairsArray(tree);
+        }, iterations);
+        console.log(`toPairsArray: ${toPairsTime.toFixed(2)}ms`);
+        console.log(`Array/Map init ratio: ${(arrayTime / mapTime).toFixed(2)}x`);
+        console.log("");
+    }
+    // Stress test
+    console.log("=== Stress Test ===");
+    const largeData = createTestData(50000);
+    const stressTime = measureTime(() => {
+        const tree = initTernaryTreeMapFromArray(largeData);
+        // Test some operations
+        for (let i = 0; i < 1000; i++) {
+            contains(tree, i);
+        }
+        return tree;
+    });
+    console.log(`Stress test (50k elements + 1k lookups): ${stressTime.toFixed(2)}ms`);
+}
+runComparison();