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
- [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
- [x] 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