feat(validation): enhance tree data validation and type safety

- Add validateSerializedTree utility for robust data validation
- Improve error handling in fromJSON method
- Add comprehensive test suite for utility functions
- Fix type safety issues in test assertions
- Update version to 1.1.0

This commit improves the reliability and type safety of the library by adding
proper validation for serialized tree data and enhancing the test suite.

Author: Axefield

package.json

@@ -1,6 +1,6 @@
 {
   "name": "merkla",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A production-ready Merkle tree implementation in JavaScript",
   "main": "dist/merkla.js",
   "types": "dist/merkla.d.ts",

src/__tests__/index.test.ts

@@ -1,28 +1,191 @@
 import { describe, expect, it } from "@jest/globals";
-import { MerkleTree } from "../index";
+import { MerkleTree, MerkleTreeError, defaultHash } from "../index";
+import { Buffer } from "buffer";
 
 describe("MerkleTree", () => {
-  it("should create a new Merkle tree", () => {
-    const data = ["a", "b", "c", "d"];
-    const tree = new MerkleTree(data);
-    expect(tree).toBeDefined();
-    expect(tree.root).toBeDefined();
+  describe("Constructor", () => {
+    it("should create a tree with valid data", () => {
+      const data = ["a", "b", "c", "d"];
+      const tree = new MerkleTree(data);
+      expect(tree).toBeDefined();
+      expect(tree.root).toBeDefined();
+      expect(tree.leafCount).toBe(4);
+      expect(tree.depth).toBe(3);
+    });
+
+    it("should throw on empty array", () => {
+      expect(() => new MerkleTree([])).toThrow(MerkleTreeError);
+    });
+
+    it("should throw on invalid hash function", () => {
+      expect(() => new MerkleTree(["a"], "not a function" as any)).toThrow(MerkleTreeError);
+    });
+
+    it("should handle single leaf", () => {
+      const tree = new MerkleTree(["a"]);
+      expect(tree.leafCount).toBe(1);
+      expect(tree.depth).toBe(1);
+      expect(tree.root).toBeDefined();
+    });
+
+    it("should handle odd number of leaves", () => {
+      const tree = new MerkleTree(["a", "b", "c"]);
+      expect(tree.leafCount).toBe(3);
+      expect(tree.depth).toBe(3);
+    });
+
+    it("should handle large number of leaves", () => {
+      const data = Array.from({ length: 1000 }, (_, i) => `data${i}`);
+      const tree = new MerkleTree(data);
+      expect(tree.leafCount).toBe(1000);
+      expect(tree.depth).toBe(11); // log2(1000) rounded up
+    });
+
+    it("should handle Buffer inputs", () => {
+      const data = [Buffer.from("a"), Buffer.from("b")];
+      const tree = new MerkleTree(data);
+      expect(tree.leafCount).toBe(2);
+    });
+
+    it("should handle mixed string and Buffer inputs", () => {
+      const data = ["a", Buffer.from("b")];
+      const tree = new MerkleTree(data);
+      expect(tree.leafCount).toBe(2);
+    });
   });
 
-  it("should generate a valid proof", () => {
-    const data = ["a", "b", "c", "d"];
-    const tree = new MerkleTree(data);
-    const proof = tree.getProof(2); // Proof for 'c'
-    expect(proof).toBeDefined();
-    expect(Array.isArray(proof)).toBe(true);
+  describe("Tree Structure", () => {
+    it("should have correct tree levels", () => {
+      const tree = new MerkleTree(["a", "b", "c", "d"]);
+      expect(tree.tree.length).toBe(3); // 4 leaves -> 2 nodes -> 1 root
+      expect(tree.tree[0].length).toBe(4); // leaves
+      expect(tree.tree[1].length).toBe(2); // intermediate
+      expect(tree.tree[2].length).toBe(1); // root
+    });
+
+    it("should handle duplicate leaves", () => {
+      const tree = new MerkleTree(["a", "a", "a", "a"]);
+      const uniqueHashes = new Set(tree.getLeaves().map(h => h.toString("hex")));
+      expect(uniqueHashes.size).toBe(1);
+    });
   });
 
-  it("should verify a valid proof", () => {
-    const data = ["a", "b", "c", "d"];
-    const tree = new MerkleTree(data);
-    const proof = tree.getProof(2);
-    const leafHash = tree.getLeaf(2);
-    const isValid = MerkleTree.verifyProof(leafHash, proof, tree.root);
-    expect(isValid).toBe(true);
+  describe("Proof Generation", () => {
+    it("should generate valid proof for first leaf", () => {
+      const tree = new MerkleTree(["a", "b", "c", "d"]);
+      const proof = tree.getProof(0);
+      expect(proof.length).toBe(2);
+      expect(proof[0].position).toBe("right");
+    });
+
+    it("should generate valid proof for last leaf", () => {
+      const tree = new MerkleTree(["a", "b", "c", "d"]);
+      const proof = tree.getProof(3);
+      expect(proof.length).toBe(2);
+      expect(proof[0].position).toBe("left");
+    });
+
+    it("should throw on invalid index", () => {
+      const tree = new MerkleTree(["a", "b", "c", "d"]);
+      expect(() => tree.getProof(-1)).toThrow(MerkleTreeError);
+      expect(() => tree.getProof(4)).toThrow(MerkleTreeError);
+      expect(() => tree.getProof(1.5)).toThrow(MerkleTreeError);
+    });
+
+    it("should generate consistent proofs", () => {
+      const tree = new MerkleTree(["a", "b", "c", "d"]);
+      const proof1 = tree.getProof(1);
+      const proof2 = tree.getProof(1);
+      expect(proof1).toEqual(proof2);
+    });
+  });
+
+  describe("Proof Verification", () => {
+    it("should verify valid proof", () => {
+      const tree = new MerkleTree(["a", "b", "c", "d"]);
+      const proof = tree.getProof(2);
+      const leafHash = tree.getLeaf(2);
+      expect(MerkleTree.verifyProof(leafHash, proof, tree.root)).toBe(true);
+    });
+
+    it("should reject invalid proof", () => {
+      const tree = new MerkleTree(["a", "b", "c", "d"]);
+      const proof = tree.getProof(2);
+      const wrongLeafHash = tree.getLeaf(1);
+      expect(MerkleTree.verifyProof(wrongLeafHash, proof, tree.root)).toBe(false);
+    });
+
+    it("should throw on invalid proof format", () => {
+      const tree = new MerkleTree(["a", "b"]);
+      expect(() => MerkleTree.verifyProof(
+        tree.getLeaf(0),
+        [{ sibling: "invalid" as any, position: "right" }],
+        tree.root
+      )).toThrow(MerkleTreeError);
+    });
+  });
+
+  describe("Serialization", () => {
+    it("should serialize and deserialize correctly", () => {
+      const original = new MerkleTree(["a", "b", "c", "d"]);
+      const serialized = original.toJSON();
+      const reconstructed = MerkleTree.fromJSON(serialized);
+      
+      expect(reconstructed.root).toEqual(original.root);
+      expect(reconstructed.leafCount).toBe(original.leafCount);
+      expect(reconstructed.depth).toBe(original.depth);
+    });
+
+    it("should throw on invalid JSON", () => {
+      expect(() => MerkleTree.fromJSON("invalid json")).toThrow(MerkleTreeError);
+    });
+
+    it("should throw on malformed tree data", () => {
+      const invalidData = JSON.stringify({
+        leaves: ["invalid"],
+        tree: [["invalid"]]
+      });
+      expect(() => MerkleTree.fromJSON(invalidData)).toThrow(MerkleTreeError);
+    });
+  });
+
+  describe("Custom Hash Function", () => {
+    it("should work with custom hash function", () => {
+      const customHash = (data: Buffer) => Buffer.from("custom" + data.toString());
+      const tree = new MerkleTree(["a", "b"], customHash);
+      expect(tree.root).toBeDefined();
+    });
+
+    it("should maintain consistency with custom hash", () => {
+      const customHash = (data: Buffer) => Buffer.from("custom" + data.toString());
+      const tree1 = new MerkleTree(["a", "b"], customHash);
+      const tree2 = new MerkleTree(["a", "b"], customHash);
+      expect(tree1.root).toEqual(tree2.root);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle very long input strings", () => {
+      const longString = "a".repeat(10000);
+      const tree = new MerkleTree([longString]);
+      expect(tree.root).toBeDefined();
+    });
+
+    it("should handle special characters", () => {
+      const data = ["!@#$%^&*()", "你好世界", "🌍"];
+      const tree = new MerkleTree(data);
+      expect(tree.root).toBeDefined();
+    });
+
+    it("should handle empty strings", () => {
+      const tree = new MerkleTree(["", "b"]);
+      expect(tree.root).toBeDefined();
+    });
+
+    it("should handle repeated patterns", () => {
+      const data = Array(100).fill("a");
+      const tree = new MerkleTree(data);
+      expect(tree.root).toBeDefined();
+    });
   });
 });

src/__tests__/utils.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "@jest/globals";
+import { validateSerializedTree, toBuffer, createLeafNode, validateProof } from "../utils";
+import { defaultHash } from "../index";
+import { Buffer } from "buffer";
+import { MerkleNode, MerkleProof, SerializedTree } from "../types";
+
+describe("Utility Functions", () => {
+  describe("validateSerializedTree", () => {
+    it("should accept valid tree data", () => {
+      const validData: SerializedTree = {
+        leaves: ["a1b2c3", "d4e5f6"],
+        tree: [["a1b2c3", "d4e5f6"], ["abcdef"]]
+      };
+      expect(() => validateSerializedTree(validData)).not.toThrow();
+    });
+
+    it("should throw on non-array leaves", () => {
+      const invalidData = {
+        leaves: "not an array",
+        tree: [["a1b2c3"]]
+      };
+      expect(() => validateSerializedTree(invalidData as unknown as SerializedTree)).toThrow("Invalid tree structure");
+    });
+
+    it("should throw on non-array tree", () => {
+      const invalidData = {
+        leaves: ["a1b2c3"],
+        tree: "not an array"
+      };
+      expect(() => validateSerializedTree(invalidData as unknown as SerializedTree)).toThrow("Invalid tree structure");
+    });
+
+    it("should throw on invalid hex in leaves", () => {
+      const invalidData: SerializedTree = {
+        leaves: ["a1b2c3", "not hex"],
+        tree: [["a1b2c3", "d4e5f6"], ["abcdef"]]
+      };
+      expect(() => validateSerializedTree(invalidData)).toThrow("Invalid hex string in leaves array");
+    });
+
+    it("should throw on invalid hex in tree", () => {
+      const invalidData: SerializedTree = {
+        leaves: ["a1b2c3", "d4e5f6"],
+        tree: [["a1b2c3", "d4e5f6"], ["not hex"]]
+      };
+      expect(() => validateSerializedTree(invalidData)).toThrow("Invalid hex string in tree array");
+    });
+
+    it("should throw on non-array tree level", () => {
+      const invalidData = {
+        leaves: ["a1b2c3", "d4e5f6"],
+        tree: [["a1b2c3", "d4e5f6"], "not an array"]
+      };
+      expect(() => validateSerializedTree(invalidData as unknown as SerializedTree)).toThrow("Invalid hex string in tree array");
+    });
+
+    it("should handle empty arrays", () => {
+      const emptyData: SerializedTree = {
+        leaves: [],
+        tree: [[]]
+      };
+      expect(() => validateSerializedTree(emptyData)).not.toThrow();
+    });
+
+    it("should handle malformed tree structure", () => {
+      const malformedData = {
+        leaves: ["a1b2c3"],
+        tree: [["a1b2c3"], ["abcdef"], "not an array"]
+      };
+      expect(() => validateSerializedTree(malformedData as unknown as SerializedTree)).toThrow("Invalid hex string in tree array");
+    });
+  });
+
+  describe("toBuffer", () => {
+    it("should convert string to Buffer", () => {
+      const result = toBuffer("test");
+      expect(Buffer.isBuffer(result)).toBe(true);
+      expect(result.toString()).toBe("test");
+    });
+
+    it("should return Buffer unchanged", () => {
+      const buffer = Buffer.from("test");
+      const result = toBuffer(buffer);
+      expect(result).toBe(buffer);
+    });
+  });
+
+  describe("createLeafNode", () => {
+    it("should create node from string", () => {
+      const node = createLeafNode("test", defaultHash);
+      expect(node).toEqual({
+        hash: expect.any(Buffer)
+      });
+      expect(Buffer.isBuffer(node.hash)).toBe(true);
+    });
+
+    it("should create node from Buffer", () => {
+      const buffer = Buffer.from("test");
+      const node = createLeafNode(buffer, defaultHash);
+      expect(node).toEqual({
+        hash: expect.any(Buffer)
+      });
+      expect(Buffer.isBuffer(node.hash)).toBe(true);
+    });
+  });
+
+  describe("validateProof", () => {
+    it("should validate correct proof", () => {
+      const leafHash = defaultHash(Buffer.from("leaf"));
+      const siblingHash = defaultHash(Buffer.from("sibling"));
+      const rootHash = defaultHash(Buffer.concat([leafHash, siblingHash]));
+      
+      const proof: MerkleProof[] = [{
+        position: "right",
+        hash: siblingHash
+      }];
+
+      expect(validateProof(proof, leafHash, rootHash, defaultHash)).toBe(true);
+    });
+
+    it("should reject incorrect proof", () => {
+      const leafHash = defaultHash(Buffer.from("leaf"));
+      const wrongSiblingHash = defaultHash(Buffer.from("wrong"));
+      const rootHash = defaultHash(Buffer.from("correct root"));
+      
+      const proof: MerkleProof[] = [{
+        position: "right",
+        hash: wrongSiblingHash
+      }];
+
+      expect(validateProof(proof, leafHash, rootHash, defaultHash)).toBe(false);
+    });
+
+    it("should handle multiple proof steps", () => {
+      const leafHash = defaultHash(Buffer.from("leaf"));
+      const sibling1Hash = defaultHash(Buffer.from("sibling1"));
+      const sibling2Hash = defaultHash(Buffer.from("sibling2"));
+      
+      // Create a two-level proof
+      const intermediateHash = defaultHash(Buffer.concat([leafHash, sibling1Hash]));
+      const rootHash = defaultHash(Buffer.concat([intermediateHash, sibling2Hash]));
+      
+      const proof: MerkleProof[] = [
+        {
+          position: "right",
+          hash: sibling1Hash
+        },
+        {
+          position: "right",
+          hash: sibling2Hash
+        }
+      ];
+
+      expect(validateProof(proof, leafHash, rootHash, defaultHash)).toBe(true);
+    });
+  });
+});