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 .toMatchObject(), .toMatchSnapshot(), expect.any(), expect.anything(), etc.

Phase 7: Error Messages & Diffs

• Integrate a diffing library for clear failure output with colorized diffs.

Phase 8: Nested Access Chaining

• Provide .at(path) or lens-based API for deep property assertions in one go.

Phase 9: Pluggable Reporters

• Allow consumers to swap output format: JSON, TAP, HTML, etc.

Phase 10: API Cleanup

• Audit and remove legacy aliases and redundant methods.
• Finalize deprecations and bump to a major version.