smartexpect/readme.plan.md

Plan for Improving @push.rocks/smartexpect API

This document captures the roadmap for evolving the expect / expectAsync API.

Phase 1: Unify Sync + Async

• Consolidate expect and expectAsync into a single expect() entry point.
• Introduce .resolves and .rejects chainable helpers for Promises.
• Deprecate expectAsync, provide migration guidance.

Phase 2: Timeout Helper

• Rename or wrap the existing .timeout(ms) to a more intuitive .withTimeout(ms).

Phase 3: Custom Matchers

• Implement expect.extend() API for user-defined matchers.

Phase 4: TypeScript Typings

• Enhance generic matcher types to infer narrow types after .property() / .arrayItem().
• Provide matcher overloads for primitive categories (string, number, array, etc.).

Phase 5: Namespaced Matchers

• Group matchers under .string, .array, .number, etc. for discoverability.

Phase 6: Jest-Style Convenience

• Add expect.any() and expect.anything() matchers for use in .toMatchObject() patterns (Snapshot matchers still TBD)

The next items to tackle:

3. Improve negation (.not) messaging

   • Today .not simply flips pass/fail, but the failure message isn’t very descriptive. We should capture positive/negative message templates so e.g.

     expect(5).not.toBeGreaterThan(3) emits: "Expected 5 not to be greater than 3"

4. Richer error output for objects/arrays

   • Integrate a diff library (or extend fast-deep-equal) to show unified diffs between expected and actual values

5. More built-in matchers

   • toBeNaN(), toBeFinite()
   • toBeWithinRange(min, max)
   • toHaveKeys(...), toHaveOwnKeys(...)
   • toThrowErrorMatching(/regex/), toThrowErrorWithMessage('…')
   • string/array: toBeEmpty() alias
   • object: toHaveOwnProperty() shorthand

6. TypeScript-friendliness

   • Enhance .d.ts so editors autocomplete namespace methods (e.g. expect(x).string.)
   • Statically type matcher arguments to catch wrong types at compile time

7. Async assertions and timeouts improvements

   • Support .not.resolves, .rejects.toThrow()
   • Provide clearer timeout errors (e.g. "Expected promise to resolve within …")

8. Plugin/extension API

   • Formalize Assertion.extend() plugin API for shipping matcher bundles