Preserve type-guard narrowing in query functions

IA
6d ago
+107-2

Calls such as filter(isText, nodes).map(node => node.data) currently lose type-guard narrowing, so TypeScript rejects access to narrowed node properties; find(), findOne() and findAll() likewise discard predicate narrowing.

Add type predicate overloads that preserve the narrowed node result, alongside the existing boolean predicate signatures. Tests cover element/text guards, narrowed element types, boolean callbacks, recursion, and limits.

Validation: npm test passes all 94 tests plus ESLint, TypeScript and Biome checks; npm run build passes. The new type checks fail before the overloads are added. Transpiled runtime JavaScript is identical with comments removed.

AI assistance: OpenAI coding assistant (GPT-6).

Summary by CodeRabbit

  • New Features
    • Query results now retain more specific TypeScript types when you use type-guard predicates, making it easier to work safely with the matched nodes.
  • Tests
    • Added checks for type narrowing, recursive and non-recursive searches, result limits, and the types returned by boolean predicates.