This pull request introduces significant improvements to query merging and logical operator handling, as well as code cleanup and test enhancements. The main focus is on normalizing and flattening nested logical query structures ($and, $or) to avoid unnecessary nesting, which simplifies downstream processing and results in more predictable query shapes. Additionally, the codebase is refactored for clarity, and tests are updated to cover new behaviors.

closes #40

Query normalization and logical operator flattening

• Added flattenAndBranches and flattenOrBranches utilities to recursively hoist nested $and and $or branches, ensuring logical operators do not nest within themselves and queries are represented in a canonical, flat form. [1] [2]
• Updated mergeQueryBodies to use flattenAndBranches when merging $and queries, preventing nested $and structures and ensuring flat, clean query ASTs.
• Updated the main mergeQuery function to normalize queries before merging by applying simplifyQuery, which drops redundant wrappers and hoists nested operators.

Code organization and exports

• Moved and renamed dedupeBranches to a more appropriate location, and updated imports throughout the codebase for consistency. [1] [2]
• Exported the new normalization utilities (dedupeBranches, flattenAndBranches, flattenOrBranches) from the common index for shared use.
• Added simplifyQuery to the utilities index for broader access.

Test coverage and behavioral improvements

• Enhanced and added tests to cover cases where nested logical operators are flattened, ensuring that query merging produces flat, predictable outputs without unnecessary nesting. [1] [2] [3] [4]
• Updated test cases for combining and intersecting queries to reflect the new flattening behavior, improving reliability and maintainability. [1] [2] [3]

Minor code cleanup

• Standardized import style and formatting in utility files for consistency. [1] [2] [3] [4] [5]
• Updated documentation references to include the new simplify-query utility.

These changes together make query merging more robust and maintainable, reduce the risk of deeply nested logical structures, and improve test coverage for edge cases.