@calcit/ternary-tree 0.0.24 → 0.0.26

package/.yarnrc.yml

@@ -0,0 +1,6 @@
+approvedGitRepositories:
+  - "**"
+
+enableScripts: true
+
+nodeLinker: node-modules

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/bench.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Micro-benchmark for ts-ternary-tree hot paths.
+ *
+ * Usage:
+ *   yarn bench
+ *
+ * Each bench() call runs the task for ~1 second and reports ops/sec.
+ * A higher number is better. Compare before/after code changes to judge
+ * whether an optimisation has real impact.
+ */
+export {};

package/lib/bench.mjs

@@ -0,0 +1,99 @@
+/**
+ * Micro-benchmark for ts-ternary-tree hot paths.
+ *
+ * Usage:
+ *   yarn bench
+ *
+ * Each bench() call runs the task for ~1 second and reports ops/sec.
+ * A higher number is better. Compare before/after code changes to judge
+ * whether an optimisation has real impact.
+ */
+import { initTernaryTreeList, listGet, assocList, dissocList, listToItems, concat, } from "./list.mjs";
+import { initTernaryTreeMapFromArray, assocMap, dissocMap, mapGetDefault, } from "./map.mjs";
+import { deepEqual, overwriteComparator } from "./utils.mjs";
+import { mergeValueHash, overwriteHashGenerator, valueHash } from "./types.mjs";
+overwriteComparator(deepEqual);
+overwriteHashGenerator((x) => mergeValueHash(10, valueHash(x)));
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function bench(label, fn, durationMs = 1000) {
+    // Warmup
+    for (let i = 0; i < 100; i++)
+        fn();
+    let ops = 0;
+    const start = Date.now();
+    while (Date.now() - start < durationMs) {
+        fn();
+        ops++;
+    }
+    const elapsed = Date.now() - start;
+    const opsPerSec = Math.round((ops / elapsed) * 1000);
+    console.log(`  ${label.padEnd(40)} ${opsPerSec.toLocaleString()} ops/sec`);
+}
+function section(title) {
+    console.log(`\n--- ${title} ---`);
+}
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+const SIZE_SMALL = 100;
+const SIZE_MEDIUM = 1000;
+const SIZE_LARGE = 10000;
+const arrSmall = Array.from({ length: SIZE_SMALL }, (_, i) => i);
+const arrMedium = Array.from({ length: SIZE_MEDIUM }, (_, i) => i);
+const arrLarge = Array.from({ length: SIZE_LARGE }, (_, i) => i);
+const listSmall = initTernaryTreeList(arrSmall);
+const listMedium = initTernaryTreeList(arrMedium);
+const listLarge = initTernaryTreeList(arrLarge);
+const mapMediumPairs = arrMedium.map((i) => [`k${i}`, i]);
+const mapMedium = initTernaryTreeMapFromArray(mapMediumPairs);
+// ---------------------------------------------------------------------------
+// List benchmarks
+// ---------------------------------------------------------------------------
+section("listGet (random access)");
+bench("listGet small  (n=100)   middle idx", () => listGet(listSmall, 50));
+bench("listGet medium (n=1k)   middle idx", () => listGet(listMedium, 500));
+bench("listGet large  (n=10k)  middle idx", () => listGet(listLarge, 5000));
+section("listToItems (full iteration)");
+bench("listToItems small  (n=100)", () => {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    for (const _ of listToItems(listSmall)) { /* consume */ }
+});
+bench("listToItems medium (n=1k)", () => {
+    for (const _ of listToItems(listMedium)) { /* consume */ }
+});
+bench("listToItems large  (n=10k)", () => {
+    for (const _ of listToItems(listLarge)) { /* consume */ }
+});
+section("assocList (element update)");
+bench("assocList small  (n=100)  idx=50", () => assocList(listSmall, 50, 999));
+bench("assocList medium (n=1k)   idx=500", () => assocList(listMedium, 500, 999));
+bench("assocList large  (n=10k)  idx=5000", () => assocList(listLarge, 5000, 999));
+section("dissocList (element remove)");
+bench("dissocList small  (n=100)  idx=50", () => dissocList(listSmall, 50));
+bench("dissocList medium (n=1k)   idx=500", () => dissocList(listMedium, 500));
+bench("dissocList large  (n=10k)  idx=5000", () => dissocList(listLarge, 5000));
+section("initTernaryTreeList (construction)");
+bench("init list small  (n=100)", () => initTernaryTreeList(arrSmall));
+bench("init list medium (n=1k)", () => initTernaryTreeList(arrMedium));
+bench("init list large  (n=10k)", () => initTernaryTreeList(arrLarge));
+section("concat");
+const half1 = initTernaryTreeList(arrMedium.slice(0, 500));
+const half2 = initTernaryTreeList(arrMedium.slice(500));
+bench("concat two halves (n=500 each)", () => concat(half1, half2));
+// ---------------------------------------------------------------------------
+// Map benchmarks
+// ---------------------------------------------------------------------------
+section("assocMap (key update/insert)");
+bench("assocMap medium (n=1k) existing key", () => assocMap(mapMedium, "k500", 9999));
+bench("assocMap medium (n=1k) new key", () => assocMap(mapMedium, "new-key", 9999));
+section("dissocMap (key remove)");
+bench("dissocMap medium (n=1k)", () => dissocMap(mapMedium, "k500"));
+section("mapGetDefault (lookup)");
+bench("mapGetDefault medium (n=1k) hit", () => mapGetDefault(mapMedium, "k500", -1));
+bench("mapGetDefault medium (n=1k) miss", () => mapGetDefault(mapMedium, "no-such-key", -1));
+section("initTernaryTreeMap (construction)");
+bench("init map small  (n=100)", () => initTernaryTreeMapFromArray(mapMediumPairs.slice(0, 100)));
+bench("init map medium (n=1k)", () => initTernaryTreeMapFromArray(mapMediumPairs));
+console.log("\nDone.");

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();

package/lib/list.d.mts

@@ -1,4 +1,5 @@
 import { TernaryTreeList } from "./types.mjs";
+export declare function enableStructureCheck(enabled?: boolean): void;
 export declare function getDepth<T>(tree: TernaryTreeList<T>): number;
 export declare function makeTernaryTreeList<T>(size: number, offset: number, xs: Array<TernaryTreeList<T>>): TernaryTreeList<T>;
 export declare function initTernaryTreeList<T>(xs: Array<T>): TernaryTreeList<T>;