2.3.1

changelog.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 2025-04-30 - 2.3.1 - fix(readme)
+Improve README documentation with detailed 'Why SmartExpect' benefits section
+
+- Added detailed 'Why SmartExpect' section outlining zero-config async support, modular footprint, enhanced messaging, rich built-in matchers, plugin extensibility, and TypeScript support
+- Clarified installation instructions regarding dependency setup
+- Updated changelog and commitinfo version to 2.3.1
+
+## 2025-04-30 - 2.3.1 - fix(readme)
+Improve README documentation with detailed 'Why SmartExpect' benefits section
+
+- Added a detailed section outlining zero-config async support, modular footprint, enhanced messaging, rich built-in matchers, plugin extensibility, and TypeScript support
+- Clarified installation instructions regarding dependency setup
+
+## 2025-04-30 - 2.3.0 - feat(object-matchers)
+Add object key matchers: toHaveKeys and toHaveOwnKeys; remove obsolete roadmap plan file
+
+- Implemented toHaveKeys matcher to check for both own and inherited properties
+- Implemented toHaveOwnKeys matcher to check for own properties only
+- Added tests for key matchers in test/test.keys.ts
+- Removed readme.plan.md as it is now obsolete
+
+## 2025-04-29 - 2.2.2 - fix(license-files)
+Remove legacy license file and add license.md to update file naming.
+
+- Removed the old 'license' file.
+- Added 'license.md' with updated file structure.
+
+## 2025-04-29 - 2.2.1 - fix(readme)
+Update usage examples and full matcher reference in README
+
+- Removed deprecated 'expectAsync' from import example
+- Fixed formatting in documentation
+- Added comprehensive full matcher reference section
+
+## 2025-04-29 - 2.2.0 - feat(generics)
+Improve assertion and matcher type definitions by adding execution mode generics for better async/sync support
+
+- Updated ts/index.ts to import and use TExecutionType in the expect function
+- Modified Assertion class to use a generic execution mode (M) for improved type inference
+- Revised all matcher namespaces (array, boolean, date, function, number, object, string, type) to accept the new generic parameter
+- Enhanced async/sync distinction for assertion methods like resolves and rejects
+
+## 2025-04-29 - 2.1.2 - fix(ts/index.ts)
+Remove deprecated expectAsync function and advise using .resolves/.rejects on expect for async assertions
+
+- Deleted the redundant expectAsync export in ts/index.ts
+- Users should now call expect(...).resolves or expect(...).rejects for asynchronous assertions
+
+## 2025-04-29 - 2.1.1 - fix(Assertion)
+Improve chainability by fixing return types in assertion methods
+
+- Update runCheck method to explicitly return the correct chainable type for both async and sync assertions
+- Ensure customAssertion propagates the chainable Assertion instance
+- Refactor internal promise handling for clarity and consistency
+
+## 2025-04-28 - 2.1.0 - feat(core)
+Add new matchers and improve negation messaging
+
+- Added expect.any() and expect.anything() matchers for enhanced object pattern matching
+- Introduced new number matchers: toBeNaN(), toBeFinite(), and toBeWithinRange()
+- Implemented alias toBeEmpty() for both string and array matchers
+- Enhanced function matchers with toThrowErrorMatching() and toThrowErrorWithMessage()
+- Improved negation messaging to provide clearer failure messages (e.g. 'Expected 5 not to be greater than 3')
+- Enhanced object assertions with a toHaveOwnProperty() shorthand that outputs unified diff-style messages
+
 ## 2025-04-28 - 2.0.1 - fix(assertion-matchers)
 Refactor matcher implementations to consistently use customAssertion for improved consistency and clarity.
 

license.md

@@ -1,4 +1,4 @@
-Copyright (c) 2022 Lossless GmbH (hello@lossless.com)
+Copyright (c) 2022 Task Venture Capital GmbH (hello@lossless.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartexpect",
-  "version": "2.0.1",
+  "version": "2.3.1",
   "private": false,
   "description": "A testing library to manage expectations in code, offering both synchronous and asynchronous assertion methods.",
   "main": "dist_ts/index.js",

readme.md

@@ -8,19 +8,29 @@ To install `@push.rocks/smartexpect`, use the following command in your terminal
 ```bash
 npm install @push.rocks/smartexpect --save
 ```
-
 This will add `@push.rocks/smartexpect` to your project's dependencies. Make sure you're inside your project directory before running this command.
 
+## Why SmartExpect?
+
+SmartExpect is designed to be a minimal, promise-first assertion library with clear, descriptive messaging and easy extensibility:
+
+- **Zero-config asynchronous support**: chain `.resolves` / `.rejects` directly off `expect()`, add timeouts with `.withTimeout(ms)`, and get clear errors if you mix sync matchers with non-Promises.
+- **Lean, modular footprint**: only depends on `fast-deep-equal`, `@push.rocks/smartpromise`, and `@push.rocks/smartdelay`; pure ESM, tree-shakable, works in Node & browser.
+- **Better out-of-the-box messaging**: automatic `.not` inversion (e.g. “Expected 5 not to be greater than 3”) and unified “Expected… / Received…” JSON diffs for object/array mismatches.
+- **Rich built-in matchers**: numbers (`toBeNaN`, `toBeWithinRange`), objects (`toHaveKeys`, `toHaveOwnKeys`, shorthand `toHaveOwnProperty`), strings/arrays (`toBeEmpty`, `toInclude`, `toHaveLength`), functions (`toThrowErrorMatching`, `toThrowErrorWithMessage`), dates, and more.
+- **Plugin-style extensibility**: add custom matchers with `expect.extend({ myMatcher })` without monkey-patching.
+- **First-class TypeScript support**: full `.d.ts` declarations, generic types for sync vs async chains, and autocomplete in editors.
+
 ## Usage
 
 `@push.rocks/smartexpect` is a TypeScript library designed to manage expectations in your code effectively, improving testing readability and maintainability. Below are various scenarios showcasing how to use this library effectively across both synchronous and asynchronous code paths.
 
 ### Getting Started
 
-First, import `@push.rocks/smartexpect` into your TypeScript file:
+ First, import `@push.rocks/smartexpect` into your TypeScript file:
 
 ```typescript
-import { expect, expectAsync } from '@push.rocks/smartexpect';
+import { expect } from '@push.rocks/smartexpect';
 ```
 
 ### Synchronous Expectations
@@ -254,6 +264,96 @@ expect(4).not.toBeOdd();
 - Matcher functions receive the value under test (`received`) plus any arguments.
 - Must return an object with `pass` (boolean) and `message` (string or function) for failure messages.
 
+### Full Matcher Reference
+
+Below is a comprehensive list of all matchers and utility functions available in `@push.rocks/smartexpect`.
+
+#### Modifiers and Utilities
+- `.not` Negates the next matcher in the chain.
+- `.resolves` Switches to async mode, expecting the promise to resolve.
+- `.rejects` Switches to async mode, expecting the promise to reject.
+- `.withTimeout(ms)` Sets a timeout (in milliseconds) for async assertions.
+- `.timeout(ms)` (deprecated) Alias for `.withTimeout(ms)`.
+- `.property(name)` Drill into a property of an object.
+- `.arrayItem(index)` Drill into an array element by index.
+- `.log()` Logs the current value and assertion path for debugging.
+- `.setFailMessage(message)` Override the failure message for the current assertion.
+- `.setSuccessMessage(message)` Override the success message for the current assertion.
+- `.customAssertion(fn, message)` Execute a custom assertion function with a message.
+- `expect.extend(matchers)` Register custom matchers globally.
+- `expect.any(constructor)` Matcher for values that are instances of the given constructor.
+- `expect.anything()` Matcher for any defined value (not null or undefined).
+
+#### Basic Matchers
+- `.toEqual(expected)` Deep (or strict for primitives) equality.
+- `.toBeTrue()` Value is strictly `true`.
+- `.toBeFalse()` Value is strictly `false`.
+- `.toBeTruthy()` Value is truthy.
+- `.toBeFalsy()` Value is falsy.
+- `.toBeNull()` Value is `null`.
+- `.toBeUndefined()` Value is `undefined`.
+- `.toBeNullOrUndefined()` Value is `null` or `undefined`.
+- `.toBeDefined()` Value is not `undefined`.
+
+#### Number Matchers
+- `.toBeGreaterThan(value)`
+- `.toBeLessThan(value)`
+- `.toBeGreaterThanOrEqual(value)`
+- `.toBeLessThanOrEqual(value)`
+- `.toBeCloseTo(value, precision?)`
+- `.toEqual(value)` Strict equality for numbers.
+- `.toBeNaN()`
+- `.toBeFinite()`
+- `.toBeWithinRange(min, max)`
+
+#### String Matchers
+- `.toStartWith(prefix)`
+- `.toEndWith(suffix)`
+- `.toInclude(substring)`
+- `.toMatch(regex)`
+- `.toBeOneOf(arrayOfValues)`
+- `.toHaveLength(length)`
+- `.toBeEmpty()` Alias for empty string.
+
+#### Array Matchers
+- `.toBeArray()`
+- `.toHaveLength(length)`
+- `.toContain(value)`
+- `.toContainEqual(value)`
+- `.toContainAll(arrayOfValues)`
+- `.toExclude(value)`
+- `.toBeEmptyArray()`
+- `.toBeEmpty()` Alias for empty array.
+- `.toHaveLengthGreaterThan(length)`
+- `.toHaveLengthLessThan(length)`
+
+#### Object Matchers
+- `.toEqual(expected)` Deep equality for objects.
+- `.toMatchObject(partialObject)` Partial deep matching (supports `expect.any` and `expect.anything`).
+- `.toBeInstanceOf(constructor)`
+- `.toHaveProperty(propertyName, value?)`
+- `.toHaveDeepProperty(pathArray)`
+- `.toHaveOwnProperty(propertyName, value?)`
+- `.toBeNull()`
+- `.toBeUndefined()`
+- `.toBeNullOrUndefined()`
+
+#### Function Matchers
+- `.toThrow(expectedError?)`
+- `.toThrowErrorMatching(regex)`
+- `.toThrowErrorWithMessage(message)`
+
+#### Date Matchers
+- `.toBeDate()`
+- `.toBeBeforeDate(date)`
+- `.toBeAfterDate(date)`
+
+#### Type Matchers
+- `.toBeTypeofString()`
+- `.toBeTypeofNumber()`
+- `.toBeTypeofBoolean()`
+- `.toBeTypeOf(typeName)`
+
 ## Best Practices
 
 - **Human-readable assertions**: The fluent API is designed to create tests that read like natural language sentences.

readme.plan.md

@@ -1,37 +0,0 @@
-# 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.

test/test.diffOutput.ts

@@ -0,0 +1,32 @@
+import { tap, expect as tExpect } from '@push.rocks/tapbundle';
+import * as smartexpect from '../dist_ts/index.js';
+
+tap.test('diff-like output for object.toEqual mismatch', async () => {
+  const a = { x: 1, y: 2 };
+  const b = { x: 1, y: 3 };
+  try {
+    smartexpect.expect(a).object.toEqual(b);
+    throw new Error('Assertion did not throw');
+  } catch (err: any) {
+    const msg: string = err.message;
+    tExpect(msg.includes('Expected objects to be deeply equal')).toBeTrue();
+    tExpect(msg.includes('Received:')).toBeTrue();
+    tExpect(msg.includes('"y": 2')).toBeTrue();
+  }
+});
+
+tap.test('diff-like output for array.toContainEqual mismatch', async () => {
+  const arr = [{ id: 1 }, { id: 2 }];
+  const item = { id: 3 };
+  try {
+    smartexpect.expect(arr).array.toContainEqual(item);
+    throw new Error('Assertion did not throw');
+  } catch (err: any) {
+    const msg: string = err.message;
+    tExpect(msg.includes('Expected array to contain equal to')).toBeTrue();
+    tExpect(msg.includes('Received:')).toBeTrue();
+    tExpect(msg.includes('"id": 1')).toBeTrue();
+  }
+});
+
+export default tap.start();

test/test.expectAny.ts

@@ -0,0 +1,38 @@
+import { tap } from '@push.rocks/tapbundle';
+import * as smartexpect from '../dist_ts/index.js';
+
+tap.test('expect.any and expect.anything basic usage', async () => {
+  const obj = { a: 1, b: 'two', d: new Date() };
+  // Using expect.any to match types
+  smartexpect.expect(obj).object.toMatchObject({
+    a: smartexpect.expect.any(Number),
+    b: smartexpect.expect.any(String),
+    d: smartexpect.expect.any(Date),
+  });
+  // Using expect.anything to match any defined value
+  smartexpect.expect(obj).object.toMatchObject({
+    a: smartexpect.expect.anything(),
+    b: smartexpect.expect.anything(),
+    d: smartexpect.expect.anything(),
+  });
+});
+
+tap.test('expect.any mismatch and anything null/undefined rejection', async () => {
+  const obj = { a: 1, b: null };
+  // Mismatch for expect.any
+  try {
+    smartexpect.expect(obj).object.toMatchObject({ a: smartexpect.expect.any(String) });
+    throw new Error('Expected mismatch for expect.any did not throw');
+  } catch (err) {
+    // success: thrown on mismatch
+  }
+  // anything should reject null or undefined
+  try {
+    smartexpect.expect(obj).object.toMatchObject({ b: smartexpect.expect.anything() });
+    throw new Error('Expected anything() to reject null or undefined');
+  } catch (err) {
+    // success: thrown on null
+  }
+});
+
+export default tap.start();

test/test.keys.ts

@@ -0,0 +1,51 @@
+import { tap, expect as tExpect } from '@push.rocks/tapbundle';
+import * as smartexpect from '../dist_ts/index.js';
+
+// Positive: toHaveKeys should match both own and inherited properties
+tap.test('toHaveKeys includes own and inherited properties', async () => {
+  class Parent { a = 1; }
+  class Child extends Parent { b = 2; }
+  const child = new Child();
+  smartexpect.expect(child).object.toHaveKeys(['a', 'b']);
+});
+
+// Positive: toHaveOwnKeys should match only own properties
+tap.test('toHaveOwnKeys includes only own properties', async () => {
+  class Parent { a = 1; }
+  class Child extends Parent { b = 2; }
+  const child = new Child();
+  smartexpect.expect(child).object.toHaveOwnKeys(['b']);
+});
+
+// Negative: toHaveKeys should fail if any key is missing
+tap.test('toHaveKeys fails when keys are missing', async () => {
+  const obj = { a: 1 };
+  try {
+    smartexpect.expect(obj).object.toHaveKeys(['a', 'b']);
+    throw new Error('Assertion did not throw');
+  } catch (err: any) {
+    tExpect(err.message.includes('Expected object to have keys')).toBeTrue();
+  }
+});
+
+// Negative: toHaveOwnKeys should fail when own keys are missing (inherited keys not counted)
+tap.test('toHaveOwnKeys fails when own keys are missing', async () => {
+  // 'a' is inherited via the prototype, not an own property
+  class Parent {}
+  Parent.prototype.a = 1;
+  class Child extends Parent {
+    constructor() {
+      super();
+      this.b = 2;
+    }
+  }
+  const child = new Child();
+  try {
+    smartexpect.expect(child).object.toHaveOwnKeys(['a', 'b']);
+    throw new Error('Assertion did not throw');
+  } catch (err: any) {
+    tExpect(err.message.includes('Expected object to have own keys')).toBeTrue();
+  }
+});
+
+export default tap.start();

test/test.negation.ts

@@ -0,0 +1,22 @@
+import { tap, expect as tExpect } from '@push.rocks/tapbundle';
+import * as smartexpect from '../dist_ts/index.js';
+
+tap.test('negation message for numeric matcher', async () => {
+  try {
+    smartexpect.expect(5).not.toBeGreaterThan(3);
+    throw new Error('Assertion did not throw');
+  } catch (err: any) {
+    tExpect(err.message).toEqual('Expected number not to be greater than 3');
+  }
+});
+
+tap.test('negation message for string matcher', async () => {
+  try {
+    smartexpect.expect('hello').not.string.toInclude('he');
+    throw new Error('Assertion did not throw');
+  } catch (err: any) {
+    tExpect(err.message).toEqual('Expected string not to include "he"');
+  }
+});
+
+export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartexpect',
-  version: '2.0.1',
+  version: '2.3.1',
   description: 'A testing library to manage expectations in code, offering both synchronous and asynchronous assertion methods.'
 }

ts/index.ts

@@ -1,4 +1,5 @@
-import { Assertion } from './smartexpect.classes.assertion.js';
+import { Assertion, AnyMatcher, AnythingMatcher } from './smartexpect.classes.assertion.js';
+import type { TExecutionType } from './types.js';
 // import type { TMatcher } from './smartexpect.classes.assertion.js'; // unused
 
 /**
@@ -12,32 +13,29 @@ import { Assertion } from './smartexpect.classes.assertion.js';
  * Entry point for assertions. 
  * Automatically detects Promises to support async assertions.
  */
-export function expect<T>(value: Promise<T>): Assertion<T>;
-export function expect<T>(value: T): Assertion<T>;
-export function expect<T>(value: any): Assertion<T> {
+export function expect<T>(value: Promise<T>): Assertion<T, 'async'>;
+export function expect<T>(value: T): Assertion<T, 'sync'>;
+export function expect<T>(value: any): Assertion<T, TExecutionType> {
   const isThenable = value != null && typeof (value as any).then === 'function';
   const mode: 'sync' | 'async' = isThenable ? 'async' : 'sync';
-  return new Assertion<T>(value, mode);
+  return new Assertion<T, TExecutionType>(value, mode);
 }
 /**
  * Register custom matchers.
  */
 export namespace expect {
   export const extend = Assertion.extend;
+  /**
+   * Matcher for a specific constructor. Passes if value is instance of given constructor.
+   */
+  export function any(constructor: any) {
+    return new AnyMatcher(constructor);
+  }
+  /**
+   * Matcher for any defined value (not null or undefined).
+   */
+  export function anything() {
+    return new AnythingMatcher();
+  }
 }
 
-/**
- * @deprecated Use `expect(...)` with `.resolves` or `.rejects` instead.
- */
-/**
- * @deprecated Use `expect(...)` with `.resolves` or `.rejects` instead.
- */
-/**
- * @deprecated Use `expect(...)` with `.resolves` or `.rejects` instead.
- */
-export const expectAsync = (baseArg: any) => {
-  // eslint-disable-next-line no-console
-  console.warn('[DEPRECATED] expectAsync() is deprecated. Use expect(...).resolves / .rejects');
-  return new Assertion<any>(baseArg, 'async');
-};
-

ts/namespaces/array.ts

@@ -1,11 +1,12 @@
 import { Assertion } from '../smartexpect.classes.assertion.js';
 import * as plugins from '../plugins.js';
+import type { TExecutionType } from '../types.js';
 
 /**
  * Namespace for array-specific matchers
  */
-export class ArrayMatchers<T> {
-  constructor(private assertion: Assertion<T[]>) {}
+export class ArrayMatchers<T, M extends TExecutionType> {
+  constructor(private assertion: Assertion<T[], M>) {}
 
   toBeArray() {
     return this.assertion.customAssertion(
@@ -31,7 +32,9 @@ export class ArrayMatchers<T> {
   toContainEqual(item: T) {
     return this.assertion.customAssertion(
       (value) => (value as T[]).some((e) => plugins.fastDeepEqual(e, item)),
-      `Expected array to contain equal to ${JSON.stringify(item)}`
+      (value) =>
+        `Expected array to contain equal to ${JSON.stringify(item)}` +
+        `\nReceived: ${JSON.stringify(value, null, 2)}`
     );
   }
 
@@ -55,6 +58,12 @@ export class ArrayMatchers<T> {
       `Expected array to be empty`
     );
   }
+  /**
+   * Alias for empty array check
+   */
+  toBeEmpty() {
+    return this.toBeEmptyArray();
+  }
 
   toHaveLengthGreaterThan(length: number) {
     return this.assertion.customAssertion(

ts/namespaces/boolean.ts

@@ -1,10 +1,11 @@
 import { Assertion } from '../smartexpect.classes.assertion.js';
+import type { TExecutionType } from '../types.js';
 
 /**
  * Namespace for boolean-specific matchers
  */
-export class BooleanMatchers {
-  constructor(private assertion: Assertion<boolean>) {}
+export class BooleanMatchers<M extends TExecutionType> {
+  constructor(private assertion: Assertion<boolean, M>) {}
 
   toBeTrue() {
     return this.assertion.customAssertion(

ts/namespaces/date.ts

@@ -1,10 +1,11 @@
 import { Assertion } from '../smartexpect.classes.assertion.js';
+import type { TExecutionType } from '../types.js';
 
 /**
  * Namespace for date-specific matchers
  */
-export class DateMatchers {
-  constructor(private assertion: Assertion<Date>) {}
+export class DateMatchers<M extends TExecutionType> {
+  constructor(private assertion: Assertion<Date, M>) {}
 
   toBeDate() {
     return this.assertion.customAssertion(

ts/namespaces/function.ts

@@ -1,10 +1,11 @@
 import { Assertion } from '../smartexpect.classes.assertion.js';
+import type { TExecutionType } from '../types.js';
 
 /**
  * Namespace for function-specific matchers
  */
-export class FunctionMatchers {
-  constructor(private assertion: Assertion<Function>) {}
+export class FunctionMatchers<M extends TExecutionType> {
+  constructor(private assertion: Assertion<Function, M>) {}
 
   toThrow(expectedError?: any) {
     return this.assertion.customAssertion(
@@ -26,4 +27,36 @@ export class FunctionMatchers {
       `Expected function to throw${expectedError ? ` ${expectedError}` : ''}`
     );
   }
+  /**
+   * Assert thrown error message matches the given regex
+   */
+  toThrowErrorMatching(regex: RegExp) {
+    return this.assertion.customAssertion(
+      (value) => {
+        try {
+          (value as Function)();
+        } catch (e: any) {
+          return regex.test(e && e.message);
+        }
+        return false;
+      },
+      `Expected function to throw error matching ${regex}`
+    );
+  }
+  /**
+   * Assert thrown error message equals the given string
+   */
+  toThrowErrorWithMessage(expectedMessage: string) {
+    return this.assertion.customAssertion(
+      (value) => {
+        try {
+          (value as Function)();
+        } catch (e: any) {
+          return e && e.message === expectedMessage;
+        }
+        return false;
+      },
+      `Expected function to throw error with message "${expectedMessage}"`
+    );
+  }
 }

ts/namespaces/number.ts

@@ -1,10 +1,11 @@
 import { Assertion } from '../smartexpect.classes.assertion.js';
+import type { TExecutionType } from '../types.js';
 
 /**
  * Namespace for number-specific matchers
  */
-export class NumberMatchers {
-  constructor(private assertion: Assertion<number>) {}
+export class NumberMatchers<M extends TExecutionType> {
+  constructor(private assertion: Assertion<number, M>) {}
 
   toBeGreaterThan(value: number) {
     return this.assertion.customAssertion(
@@ -53,4 +54,31 @@ export class NumberMatchers {
       `Expected number to equal ${value}`
     );
   }
+  /**
+   * Checks for NaN
+   */
+  toBeNaN() {
+    return this.assertion.customAssertion(
+      (v) => Number.isNaN(v as number),
+      `Expected number to be NaN`
+    );
+  }
+  /**
+   * Checks for finite number
+   */
+  toBeFinite() {
+    return this.assertion.customAssertion(
+      (v) => Number.isFinite(v as number),
+      `Expected number to be finite`
+    );
+  }
+  /**
+   * Checks if number is within inclusive range
+   */
+  toBeWithinRange(min: number, max: number) {
+    return this.assertion.customAssertion(
+      (v) => (v as number) >= min && (v as number) <= max,
+      `Expected number to be within range ${min} - ${max}`
+    );
+  }
 }

ts/namespaces/object.ts

@@ -1,30 +1,53 @@
-import { Assertion } from '../smartexpect.classes.assertion.js';
+import { Assertion, AnyMatcher, AnythingMatcher } from '../smartexpect.classes.assertion.js';
+import type { TExecutionType } from '../types.js';
 import * as plugins from '../plugins.js';
 
 /**
  * Namespace for object-specific matchers
  */
-export class ObjectMatchers<T extends object> {
-  constructor(private assertion: Assertion<T>) {}
+export class ObjectMatchers<T extends object, M extends TExecutionType> {
+  constructor(private assertion: Assertion<T, M>) {}
 
   toEqual(expected: any) {
     return this.assertion.customAssertion(
       (v) => plugins.fastDeepEqual(v, expected),
-      `Expected objects to be deeply equal to ${JSON.stringify(expected)}`
+      (v) =>
+        `Expected objects to be deeply equal to ${JSON.stringify(expected, null, 2)}` +
+        `\nReceived: ${JSON.stringify(v, null, 2)}`
     );
   }
 
   toMatchObject(expected: object) {
     return this.assertion.customAssertion(
       (v) => {
+        const obj = v as any;
         for (const key of Object.keys(expected)) {
-          if (!plugins.fastDeepEqual((v as any)[key], (expected as any)[key])) {
+          const expectedVal = (expected as any)[key];
+          const actualVal = obj[key];
+          if (expectedVal instanceof AnyMatcher) {
+            const ctor = expectedVal.expectedConstructor;
+            if (ctor === Number) {
+              if (typeof actualVal !== 'number') return false;
+            } else if (ctor === String) {
+              if (typeof actualVal !== 'string') return false;
+            } else if (ctor === Boolean) {
+              if (typeof actualVal !== 'boolean') return false;
+            } else {
+              if (!(actualVal instanceof ctor)) return false;
+            }
+          } else if (expectedVal instanceof AnythingMatcher) {
+            if (actualVal === null || actualVal === undefined) {
+              return false;
+            }
+          } else if (!plugins.fastDeepEqual(actualVal, expectedVal)) {
             return false;
           }
         }
         return true;
       },
-      `Expected object to match properties ${JSON.stringify(expected)}`
+      (v) =>
+        `Expected object to match properties ${JSON.stringify(expected, null, 2)}` +
+        `\nReceived: ${JSON.stringify(v, null, 2)}`
     );
   }
 
@@ -86,4 +109,51 @@ export class ObjectMatchers<T extends object> {
       `Expected value to be null or undefined`
     );
   }
+  /**
+   * Checks own property only (not inherited)
+   */
+  toHaveOwnProperty(property: string, value?: any) {
+    return this.assertion.customAssertion(
+      (v) => {
+        const obj = v as any;
+        if (!Object.prototype.hasOwnProperty.call(obj, property)) {
+          return false;
+        }
+        if (arguments.length === 2) {
+          return plugins.fastDeepEqual(obj[property], value);
+        }
+        return true;
+      },
+      (v) =>
+        `Expected object to have own property ${property}` +
+        (value !== undefined ? ` with value ${JSON.stringify(value)}` : ``) +
+        `\nReceived: ${JSON.stringify(v, null, 2)}`
+    );
+  }
+  
+  /**
+   * Assert object has the given keys (including inherited properties).
+   * @param keys Array of keys to check for presence.
+   */
+  public toHaveKeys(keys: string[]) {
+    return this.assertion.customAssertion(
+      (v) => keys.every((key) => key in (v as any)),
+      (v) =>
+        `Expected object to have keys ${JSON.stringify(keys)}` +
+        `\nReceived keys: ${JSON.stringify(Object.keys(v), null, 2)}`
+    );
+  }
+
+  /**
+   * Assert object has the given own keys (excluding inherited properties).
+   * @param keys Array of own keys to check.
+   */
+  public toHaveOwnKeys(keys: string[]) {
+    return this.assertion.customAssertion(
+      (v) => keys.every((key) => Object.prototype.hasOwnProperty.call(v as any, key)),
+      (v) =>
+        `Expected object to have own keys ${JSON.stringify(keys)}` +
+        `\nReceived own keys: ${JSON.stringify(Object.keys(v), null, 2)}`
+    );
+  }
 }

ts/namespaces/string.ts

@@ -1,10 +1,11 @@
 import { Assertion } from '../smartexpect.classes.assertion.js';
+import type { TExecutionType } from '../types.js';
 
 /**
  * Namespace for string-specific matchers
  */
-export class StringMatchers {
-  constructor(private assertion: Assertion<string>) {}
+export class StringMatchers<M extends TExecutionType> {
+  constructor(private assertion: Assertion<string, M>) {}
 
   toStartWith(prefix: string) {
     return this.assertion.customAssertion(
@@ -47,4 +48,13 @@ export class StringMatchers {
       `Expected string to have length ${length}`
     );
   }
+  /**
+   * Alias for empty string check
+   */
+  toBeEmpty() {
+    return this.assertion.customAssertion(
+      (value) => (value as string).length === 0,
+      `Expected string to be empty`
+    );
+  }
 }

ts/namespaces/type.ts

@@ -1,10 +1,11 @@
 import { Assertion } from '../smartexpect.classes.assertion.js';
+import type { TExecutionType } from '../types.js';
 
 /**
  * Namespace for type-based matchers
  */
-export class TypeMatchers {
-  constructor(private assertion: Assertion<any>) {}
+export class TypeMatchers<M extends TExecutionType> {
+  constructor(private assertion: Assertion<any, M>) {}
 
   toBeTypeofString() {
     return this.assertion.customAssertion(

ts/smartexpect.classes.assertion.ts

@@ -18,8 +18,16 @@ import type { TMatcher, TExecutionType } from './types.js';
 /**
  * Core assertion class. Generic over the current value type T.
  */
-export class Assertion<T = unknown> {
-  executionMode: TExecutionType;
+/**
+ * Internal matcher classes for expect.any and expect.anything
+ */
+export class AnyMatcher {
+  constructor(public expectedConstructor: any) {}
+}
+export class AnythingMatcher {}
+
+export class Assertion<T = unknown, M extends TExecutionType = 'sync'> {
+  executionMode: M;
   baseReference: any;
   propertyDrillDown: Array<string | number> = [];
 
@@ -33,8 +41,10 @@ export class Assertion<T = unknown> {
   private isResolves = false;
   private failMessage: string;
   private successMessage: string;
+  /** Computed negation failure message for the current assertion */
+  private negativeMessage: string;
 
-  constructor(baseReferenceArg: any, executionModeArg: TExecutionType) {
+  constructor(baseReferenceArg: any, executionModeArg: M) {
     this.baseReference = baseReferenceArg;
     this.executionMode = executionModeArg;
   }
@@ -131,6 +141,16 @@ export class Assertion<T = unknown> {
       .replace('{value}', formattedValue)
       .replace('{path}', drillDown || '');
   }
+  /**
+   * Compute a negated failure message by inserting 'not' into the positive message.
+   */
+  private computeNegationMessage(message: string): string {
+    const idx = message.indexOf(' to ');
+    if (idx !== -1) {
+      return message.slice(0, idx) + ' not' + message.slice(idx);
+    }
+    return 'Negated: ' + message;
+  }
 
   public get not() {
     this.notSetting = true;
@@ -139,20 +159,23 @@ export class Assertion<T = unknown> {
   /**
    * Assert that a Promise resolves.
    */
-  public get resolves(): this {
-    this.isResolves = true;
-    this.isRejects = false;
-    this.executionMode = 'async';
-    return this;
+  /**
+   * Switch to async (resolve) mode. Subsequent matchers return Promises.
+   */
+  public get resolves(): Assertion<T, 'async'> {
+    return new Assertion<T, 'async'>(this.baseReference, 'async');
   }
   /**
    * Assert that a Promise rejects.
    */
-  public get rejects(): this {
-    this.isRejects = true;
-    this.isResolves = false;
-    this.executionMode = 'async';
-    return this;
+  /**
+   * Switch to async (reject) mode. Subsequent matchers return Promises.
+   */
+  public get rejects(): Assertion<T, 'async'> {
+    const a = new Assertion<T, 'async'>(this.baseReference, 'async');
+    // mark to expect rejection
+    (a as any).isRejects = true;
+    return a;
   }
 
   /**
@@ -183,25 +206,29 @@ export class Assertion<T = unknown> {
     return this;
   }
 
-  private runCheck(checkFunction: () => any) {
+  // Internal check runner: returns Promise in async mode, else sync Assertion
+  // Internal check runner; returns Promise or this at runtime, but typed via customAssertion
+  private runCheck(checkFunction: () => any): any {
     const runDirectOrNegated = (checkFunction: () => any) => {
       if (!this.notSetting) {
         return checkFunction();
       } else {
         let isOk = false;
         try {
-          runDirectOrNegated(checkFunction());
+        // attempt positive assertion and expect it to throw
+        checkFunction();
         } catch (e) {
           isOk = true;
         }
         if (!isOk) {
-          throw new Error(this.failMessage || 'Negated assertion failed');
+          const msg = this.failMessage || this.negativeMessage || 'Negated assertion failed';
+          throw new Error(msg);
         }
       }
     };
 
     if (this.executionMode === 'async') {
-      const done = plugins.smartpromise.defer();
+      const done = plugins.smartpromise.defer<Assertion<T, M>>();
       const isThenable = this.baseReference && typeof (this.baseReference as any).then === 'function';
       if (!isThenable) {
         done.reject(new Error(`Expected a Promise but received: ${this.formatValue(this.baseReference)}`));
@@ -219,47 +246,59 @@ export class Assertion<T = unknown> {
           (res: any) => {
             done.reject(new Error(`Expected Promise to reject but it resolved with ${this.formatValue(res)}`));
           },
-          (err: any) => {
-            this.baseReference = err;
-            try {
-              const ret = runDirectOrNegated(checkFunction);
-              done.resolve(ret);
-            } catch (e: any) {
-              done.reject(e);
+            (err: any) => {
+              this.baseReference = err;
+              try {
+                runDirectOrNegated(checkFunction);
+                done.resolve(this);
+              } catch (e: any) {
+                done.reject(e);
+              }
             }
-          }
         );
       } else {
         (this.baseReference as Promise<any>).then(
-          (res: any) => {
-            this.baseReference = res;
-            try {
-              const ret = runDirectOrNegated(checkFunction);
-              done.resolve(ret);
-            } catch (e: any) {
-              done.reject(e);
-            }
-          },
+            (res: any) => {
+              this.baseReference = res;
+              try {
+                runDirectOrNegated(checkFunction);
+                done.resolve(this);
+              } catch (e: any) {
+                done.reject(e);
+              }
+            },
           (err: any) => {
             done.reject(err);
           }
         );
       }
-      return done.promise;
+      // return a promise resolving to this for chaining
+      return done.promise.then(() => this) as any;
     }
-    return runDirectOrNegated(checkFunction);
+    // sync: run and return this for chaining
+    runDirectOrNegated(checkFunction);
+    return this as any;
   }
 
+  /**
+   * Execute a custom assertion. Returns a Promise in async mode, else returns this.
+   */
   public customAssertion(
     assertionFunction: (value: any) => boolean,
-    errorMessage: string
-  ) {
+    errorMessage: string | ((value: any) => string)
+  ): M extends 'async' ? Promise<Assertion<T, M>> : Assertion<T, M> {
+    // Prepare negation message based on the positive error template, if static
+    if (typeof errorMessage === 'string') {
+      this.negativeMessage = this.computeNegationMessage(errorMessage);
+    }
     return this.runCheck(() => {
       const value = this.getObjectToTestReference();
       if (!assertionFunction(value)) {
-        throw new Error(this.failMessage || errorMessage);
+        const msg = this.failMessage
+          || (typeof errorMessage === 'function' ? errorMessage(value) : errorMessage);
+        throw new Error(msg);
       }
-    });
+    }) as any;
   }
 
   /**
@@ -267,9 +306,9 @@ export class Assertion<T = unknown> {
    * @param propertyName Name of the property to navigate into.
    * @returns Assertion of the property type.
    */
-  public property<K extends keyof NonNullable<T>>(propertyName: K): Assertion<NonNullable<T>[K]> {
+  public property<K extends keyof NonNullable<T>>(propertyName: K): Assertion<NonNullable<T>[K], M> {
     this.propertyDrillDown.push(propertyName as string);
-    return this as unknown as Assertion<NonNullable<T>[K]>;
+    return this as unknown as Assertion<NonNullable<T>[K], M>;
   }
 
   /**
@@ -277,9 +316,9 @@ export class Assertion<T = unknown> {
    * @param index Index of the array item.
    * @returns Assertion of the element type.
    */
-  public arrayItem(index: number): Assertion<T extends Array<infer U> ? U : unknown> {
+  public arrayItem(index: number): Assertion<T extends Array<infer U> ? U : unknown, M> {
     this.propertyDrillDown.push(index);
-    return this as unknown as Assertion<T extends Array<infer U> ? U : unknown>;
+    return this as unknown as Assertion<T extends Array<infer U> ? U : unknown, M>;
   }
 
   public log() {
@@ -331,37 +370,38 @@ export class Assertion<T = unknown> {
   public toBeTypeofBoolean() { return this.type.toBeTypeofBoolean(); }
   public toBeTypeOf(typeName: string) { return this.type.toBeTypeOf(typeName); }
   public toBeDefined() { return this.type.toBeDefined(); }
+  
   // Namespaced matcher accessors
   /** String-specific matchers */
-  public get string() {
-    return new StringMatchers(this as Assertion<string>);
+  public get string(): StringMatchers<M> {
+    return new StringMatchers<M>(this as Assertion<string, M>);
   }
   /** Array-specific matchers */
-  public get array() {
-    return new ArrayMatchers<any>(this as Assertion<any[]>);
+  public get array(): ArrayMatchers<any, M> {
+    return new ArrayMatchers<any, M>(this as Assertion<any[], M>);
   }
   /** Number-specific matchers */
-  public get number() {
-    return new NumberMatchers(this as Assertion<number>);
+  public get number(): NumberMatchers<M> {
+    return new NumberMatchers<M>(this as Assertion<number, M>);
   }
   /** Boolean-specific matchers */
-  public get boolean() {
-    return new BooleanMatchers(this as Assertion<boolean>);
+  public get boolean(): BooleanMatchers<M> {
+    return new BooleanMatchers<M>(this as Assertion<boolean, M>);
   }
   /** Object-specific matchers */
-  public get object() {
-    return new ObjectMatchers<any>(this as Assertion<object>);
+  public get object(): ObjectMatchers<any, M> {
+    return new ObjectMatchers<any, M>(this as Assertion<object, M>);
   }
   /** Function-specific matchers */
-  public get function() {
-    return new FunctionMatchers(this as Assertion<Function>);
+  public get function(): FunctionMatchers<M> {
+    return new FunctionMatchers<M>(this as Assertion<Function, M>);
   }
   /** Date-specific matchers */
-  public get date() {
-    return new DateMatchers(this as Assertion<Date>);
+  public get date(): DateMatchers<M> {
+    return new DateMatchers<M>(this as Assertion<Date, M>);
   }
   /** Type-based matchers */
-  public get type() {
-    return new TypeMatchers(this as Assertion<any>);
+  public get type(): TypeMatchers<M> {
+    return new TypeMatchers<M>(this as Assertion<any, M>);
   }
 }