# Plan for Improving @push.rocks/smartexpect API

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

## Phase 1: Unify Sync + Async
- [x] Consolidate `expect` and `expectAsync` into a single `expect()` entry point.
- [x] Introduce `.resolves` and `.rejects` chainable helpers for Promises.
- [x] Deprecate `expectAsync`, provide migration guidance.

## Phase 2: Timeout Helper
- [x] Rename or wrap the existing `.timeout(ms)` to a more intuitive `.withTimeout(ms)`.

## Phase 3: Custom Matchers
- [x] 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.