BREAKING CHANGE(docs): Update documentation and examples to unify async and sync assertions, add custom matcher guides, and update package configuration

ts/00_commitinfo_data.ts

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

ts/index.ts

@@ -1,12 +1,43 @@
 import { Assertion } from './smartexpect.classes.assertion.js';
+// import type { TMatcher } from './smartexpect.classes.assertion.js'; // unused
 
-export const expect = (baseArg: any) => {
-  const assertion = new Assertion(baseArg, 'sync');
-  return assertion;
-};
+/**
+ * Primary entry point for assertions.
+ * Automatically detects Promises to support async assertions.
+ */
+/**
+ * The `expect` function interface. Supports custom matchers via .extend.
+ */
+/**
+ * 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> {
+  const isThenable = value != null && typeof (value as any).then === 'function';
+  const mode: 'sync' | 'async' = isThenable ? 'async' : 'sync';
+  return new Assertion<T>(value, mode);
+}
+/**
+ * Register custom matchers.
+ */
+export namespace expect {
+  export const extend = Assertion.extend;
+}
 
+/**
+ * @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) => {
-  const assertion = new Assertion(baseArg, 'async');
-  return assertion;
+  // 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

@@ -0,0 +1,44 @@
+import { Assertion } from '../smartexpect.classes.assertion.js';
+
+/**
+ * Namespace for array-specific matchers
+ */
+export class ArrayMatchers<T> {
+  constructor(private assertion: Assertion<T[]>) {}
+
+  toBeArray() {
+    return this.assertion.toBeArray();
+  }
+
+  toHaveLength(length: number) {
+    return this.assertion.toHaveLength(length);
+  }
+
+  toContain(item: T) {
+    return this.assertion.toContain(item);
+  }
+
+  toContainEqual(item: T) {
+    return this.assertion.toContainEqual(item);
+  }
+
+  toContainAll(items: T[]) {
+    return this.assertion.toContainAll(items);
+  }
+
+  toExclude(item: T) {
+    return this.assertion.toExclude(item);
+  }
+
+  toBeEmptyArray() {
+    return this.assertion.toBeEmptyArray();
+  }
+
+  toHaveLengthGreaterThan(length: number) {
+    return this.assertion.toHaveLengthGreaterThan(length);
+  }
+
+  toHaveLengthLessThan(length: number) {
+    return this.assertion.toHaveLengthLessThan(length);
+  }
+}

ts/namespaces/boolean.ts

@@ -0,0 +1,24 @@
+import { Assertion } from '../smartexpect.classes.assertion.js';
+
+/**
+ * Namespace for boolean-specific matchers
+ */
+export class BooleanMatchers {
+  constructor(private assertion: Assertion<boolean>) {}
+
+  toBeTrue() {
+    return this.assertion.toBeTrue();
+  }
+
+  toBeFalse() {
+    return this.assertion.toBeFalse();
+  }
+
+  toBeTruthy() {
+    return this.assertion.toBeTruthy();
+  }
+
+  toBeFalsy() {
+    return this.assertion.toBeFalsy();
+  }
+}

ts/namespaces/date.ts

@@ -0,0 +1,20 @@
+import { Assertion } from '../smartexpect.classes.assertion.js';
+
+/**
+ * Namespace for date-specific matchers
+ */
+export class DateMatchers {
+  constructor(private assertion: Assertion<Date>) {}
+
+  toBeDate() {
+    return this.assertion.toBeDate();
+  }
+
+  toBeBeforeDate(date: Date) {
+    return this.assertion.toBeBeforeDate(date);
+  }
+
+  toBeAfterDate(date: Date) {
+    return this.assertion.toBeAfterDate(date);
+  }
+}

ts/namespaces/function.ts

@@ -0,0 +1,12 @@
+import { Assertion } from '../smartexpect.classes.assertion.js';
+
+/**
+ * Namespace for function-specific matchers
+ */
+export class FunctionMatchers {
+  constructor(private assertion: Assertion<Function>) {}
+
+  toThrow(expectedError?: any) {
+    return this.assertion.toThrow(expectedError);
+  }
+}

ts/namespaces/index.ts

@@ -0,0 +1,8 @@
+export { StringMatchers } from './string.js';
+export { ArrayMatchers } from './array.js';
+export { NumberMatchers } from './number.js';
+export { BooleanMatchers } from './boolean.js';
+export { ObjectMatchers } from './object.js';
+export { FunctionMatchers } from './function.js';
+export { DateMatchers } from './date.js';
+export { TypeMatchers } from './type.js';

ts/namespaces/number.ts

@@ -0,0 +1,32 @@
+import { Assertion } from '../smartexpect.classes.assertion.js';
+
+/**
+ * Namespace for number-specific matchers
+ */
+export class NumberMatchers {
+  constructor(private assertion: Assertion<number>) {}
+
+  toBeGreaterThan(value: number) {
+    return this.assertion.toBeGreaterThan(value);
+  }
+
+  toBeLessThan(value: number) {
+    return this.assertion.toBeLessThan(value);
+  }
+
+  toBeGreaterThanOrEqual(value: number) {
+    return this.assertion.toBeGreaterThanOrEqual(value);
+  }
+
+  toBeLessThanOrEqual(value: number) {
+    return this.assertion.toBeLessThanOrEqual(value);
+  }
+
+  toBeCloseTo(value: number, precision?: number) {
+    return this.assertion.toBeCloseTo(value, precision);
+  }
+  /** Equality check for numbers */
+  toEqual(value: number) {
+    return this.assertion.toEqual(value);
+  }
+}

ts/namespaces/object.ts

@@ -0,0 +1,39 @@
+import { Assertion } from '../smartexpect.classes.assertion.js';
+
+/**
+ * Namespace for object-specific matchers
+ */
+export class ObjectMatchers<T extends object> {
+  constructor(private assertion: Assertion<T>) {}
+
+  toEqual(expected: any) {
+    return this.assertion.toEqual(expected);
+  }
+
+  toMatchObject(expected: object) {
+    return this.assertion.toMatchObject(expected);
+  }
+
+  toBeInstanceOf(constructor: any) {
+    return this.assertion.toBeInstanceOf(constructor);
+  }
+
+  toHaveProperty(property: string, value?: any) {
+    return this.assertion.toHaveProperty(property, value);
+  }
+
+  toHaveDeepProperty(path: string[]) {
+    return this.assertion.toHaveDeepProperty(path);
+  }
+  toBeNull() {
+    return this.assertion.toBeNull();
+  }
+
+  toBeUndefined() {
+    return this.assertion.toBeUndefined();
+  }
+
+  toBeNullOrUndefined() {
+    return this.assertion.toBeNullOrUndefined();
+  }
+}

ts/namespaces/string.ts

@@ -0,0 +1,32 @@
+import { Assertion } from '../smartexpect.classes.assertion.js';
+
+/**
+ * Namespace for string-specific matchers
+ */
+export class StringMatchers {
+  constructor(private assertion: Assertion<string>) {}
+
+  toStartWith(prefix: string) {
+    return this.assertion.toStartWith(prefix);
+  }
+
+  toEndWith(suffix: string) {
+    return this.assertion.toEndWith(suffix);
+  }
+
+  toInclude(substring: string) {
+    return this.assertion.toInclude(substring);
+  }
+
+  toMatch(regex: RegExp) {
+    return this.assertion.toMatch(regex);
+  }
+
+  toBeOneOf(values: string[]) {
+    return this.assertion.toBeOneOf(values);
+  }
+  /** Length check for strings */
+  toHaveLength(length: number) {
+    return this.assertion.toHaveLength(length);
+  }
+}

ts/namespaces/type.ts

@@ -0,0 +1,28 @@
+import { Assertion } from '../smartexpect.classes.assertion.js';
+
+/**
+ * Namespace for type-based matchers
+ */
+export class TypeMatchers {
+  constructor(private assertion: Assertion<any>) {}
+
+  toBeTypeofString() {
+    return this.assertion.toBeTypeofString();
+  }
+
+  toBeTypeofNumber() {
+    return this.assertion.toBeTypeofNumber();
+  }
+
+  toBeTypeofBoolean() {
+    return this.assertion.toBeTypeofBoolean();
+  }
+
+  toBeTypeOf(typeName: string) {
+    return this.assertion.toBeTypeOf(typeName);
+  }
+
+  toBeDefined() {
+    return this.assertion.toBeDefined();
+  }
+}

ts/plugins.ts

@@ -1,9 +1,7 @@
 import * as smartdelay from '@push.rocks/smartdelay';
 import * as smartpromise from '@push.rocks/smartpromise';
-
 export { smartdelay, smartpromise };
 
-// third party scope
+// third party utilities
 import fastDeepEqual from 'fast-deep-equal';
-
-export { fastDeepEqual };
+export { fastDeepEqual };

ts/smartexpect.classes.assertion.ts

@@ -1,14 +1,36 @@
-import * as plugins from './smartexpect.plugins.js';
+import * as plugins from './plugins.js';
+import {
+  StringMatchers,
+  ArrayMatchers,
+  NumberMatchers,
+  BooleanMatchers,
+  ObjectMatchers,
+  FunctionMatchers,
+  DateMatchers,
+  TypeMatchers,
+} from './namespaces/index.js';
+/**
+ * Definition of a custom matcher function.
+ * Should return an object with `pass` and optional `message`.
+ */
+import type { TMatcher, TExecutionType } from './types.js';
 
-export type TExecutionType = 'sync' | 'async';
-
-export class Assertion {
+/**
+ * Core assertion class. Generic over the current value type T.
+ */
+export class Assertion<T = unknown> {
   executionMode: TExecutionType;
   baseReference: any;
   propertyDrillDown: Array<string | number> = [];
 
   private notSetting = false;
   private timeoutSetting = 0;
+  /** Registry of user-defined custom matchers */
+  private static customMatchers: Record<string, TMatcher> = {};
+  /** Flag for Promise rejection assertions */
+  private isRejects = false;
+  /** Flag for Promise resolution assertions (default for async) */
+  private isResolves = false;
   private failMessage: string;
   private successMessage: string;
 
@@ -16,6 +38,32 @@ export class Assertion {
     this.baseReference = baseReferenceArg;
     this.executionMode = executionModeArg;
   }
+  /**
+   * Register custom matchers to be available on all assertions.
+   * @param matchers An object whose keys are matcher names and values are matcher functions.
+   */
+  public static extend(matchers: Record<string, TMatcher>): void {
+    for (const [name, fn] of Object.entries(matchers)) {
+      if ((Assertion.prototype as any)[name]) {
+        throw new Error(`Cannot extend. Matcher '${name}' already exists on Assertion.`);
+      }
+      // store in registry
+      Assertion.customMatchers[name] = fn;
+      // add method to prototype
+      (Assertion.prototype as any)[name] = function (...args: any[]) {
+        return this.runCheck(() => {
+          const received = this.getObjectToTestReference();
+          const result = fn(received, ...args);
+          const pass = result.pass;
+          const msg = result.message;
+          if (!pass) {
+            const message = typeof msg === 'function' ? msg() : msg;
+            throw new Error(message || `Custom matcher '${name}' failed`);
+          }
+        });
+      };
+    }
+  }
 
   private getObjectToTestReference() {
     let returnObjectToTestReference = this.baseReference;
@@ -88,8 +136,39 @@ export class Assertion {
     this.notSetting = true;
     return this;
   }
+  /**
+   * Assert that a Promise resolves.
+   */
+  public get resolves(): this {
+    this.isResolves = true;
+    this.isRejects = false;
+    this.executionMode = 'async';
+    return this;
+  }
+  /**
+   * Assert that a Promise rejects.
+   */
+  public get rejects(): this {
+    this.isRejects = true;
+    this.isResolves = false;
+    this.executionMode = 'async';
+    return this;
+  }
 
+  /**
+   * @deprecated use `.withTimeout(ms)` instead for clarity
+   * Set a timeout (in ms) for async assertions (Promise must settle before timeout).
+   */
   public timeout(millisArg: number) {
+    // eslint-disable-next-line no-console
+    console.warn('[DEPRECATED] .timeout() is deprecated. Use .withTimeout(ms)');
+    this.timeoutSetting = millisArg;
+    return this;
+  }
+  /**
+   * Set a timeout (in ms) for async assertions (Promise must settle before timeout).
+   */
+  public withTimeout(millisArg: number) {
     this.timeoutSetting = millisArg;
     return this;
   }
@@ -123,579 +202,52 @@ export class Assertion {
 
     if (this.executionMode === 'async') {
       const done = plugins.smartpromise.defer();
-      if (!(this.baseReference instanceof Promise)) {
+      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)}`));
-      } else {
-        if (this.timeoutSetting) {
-          plugins.smartdelay.delayFor(this.timeoutSetting).then(() => {
-            if (done.status === 'pending') {
-              done.reject(new Error(`Promise timed out after ${this.timeoutSetting}ms`));
-            }
-          });
-        }
-        this.baseReference.then((promiseResultArg: any) => {
-          this.baseReference = promiseResultArg;
-          done.resolve(runDirectOrNegated(checkFunction));
+        return done.promise;
+      }
+      if (this.timeoutSetting) {
+        plugins.smartdelay.delayFor(this.timeoutSetting).then(() => {
+          if (done.status === 'pending') {
+            done.reject(new Error(`Promise timed out after ${this.timeoutSetting}ms`));
+          }
         });
       }
+      if (this.isRejects) {
+        (this.baseReference as Promise<any>).then(
+          (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);
+            }
+          }
+        );
+      } 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);
+            }
+          },
+          (err: any) => {
+            done.reject(err);
+          }
+        );
+      }
       return done.promise;
-    } else {
-      return runDirectOrNegated(checkFunction);
     }
-  }
-
-  public toBeDefined() {
-    return this.runCheck(() => {
-      if (this.getObjectToTestReference() === undefined) {
-        throw new Error(
-          this.createErrorMessage('Expected value{path} to be defined, but got undefined')
-        );
-      }
-    });
-  }
-
-  public toBeTypeofString() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (typeof value !== 'string') {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be of type string, but got ${typeof value}`)
-        );
-      }
-    });
-  }
-
-  public toBeTypeofNumber() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (typeof value !== 'number') {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be of type number, but got ${typeof value}`)
-        );
-      }
-    });
-  }
-
-  public toBeTypeofBoolean() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (typeof value !== 'boolean') {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be of type boolean, but got ${typeof value}`)
-        );
-      }
-    });
-  }
-
-  public toBeTypeOf(expectedType: string) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const actualType = typeof value;
-      if (actualType !== expectedType) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be of type ${expectedType}, but got ${actualType}`)
-        );
-      }
-    });
-  }
-
-  public toEqual(comparisonObject: any) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = plugins.fastDeepEqual(value, comparisonObject);
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to equal ${this.formatValue(comparisonObject)}`)
-        );
-      }
-    });
-  }
-
-  public toMatch(comparisonObject: RegExp) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = comparisonObject.test(value);
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to match regex ${comparisonObject}`)
-        );
-      }
-    });
-  }
-
-  public toBeTrue() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = typeof value === 'boolean' && value === true;
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be true, but got ${this.formatValue(value)}`)
-        );
-      }
-    });
-  }
-
-  public toBeFalse() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = typeof value === 'boolean' && value === false;
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be false, but got ${this.formatValue(value)}`)
-        );
-      }
-    });
-  }
-
-  public toBeInstanceOf(classArg: any) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = value instanceof classArg;
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be an instance of ${classArg.name || 'provided class'}`)
-        );
-      }
-    });
-  }
-
-  public toHaveProperty(propertyArg: string, equalsArg?: any) {
-    return this.runCheck(() => {
-      const obj = this.getObjectToTestReference();
-      if (!obj || !(propertyArg in obj)) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to have property '${propertyArg}'`)
-        );
-      }
-      if (equalsArg !== undefined) {
-        if (obj[propertyArg] !== equalsArg) {
-          throw new Error(
-            this.createErrorMessage(
-              `Expected property '${propertyArg}' of value{path} to equal ${this.formatValue(equalsArg)}, but got ${this.formatValue(obj[propertyArg])}`
-            )
-          );
-        }
-      }
-    });
-  }
-
-  public toHaveDeepProperty(properties: string[]) {
-    return this.runCheck(() => {
-      let obj = this.getObjectToTestReference();
-      let currentPath = '';
-
-      for (const property of properties) {
-        if (currentPath) {
-          currentPath += `.${property}`;
-        } else {
-          currentPath = property;
-        }
-
-        if (!obj || !(property in obj)) {
-          throw new Error(
-            this.createErrorMessage(`Expected value{path} to have property at path '${currentPath}'`)
-          );
-        }
-        obj = obj[property];
-      }
-    });
-  }
-
-  public toBeGreaterThan(numberArg: number) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = value > numberArg;
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be greater than ${numberArg}, but got ${this.formatValue(value)}`)
-        );
-      }
-    });
-  }
-
-  public toBeLessThan(numberArg: number) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = value < numberArg;
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be less than ${numberArg}, but got ${this.formatValue(value)}`)
-        );
-      }
-    });
-  }
-
-  public toBeNull() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = value === null;
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be null, but got ${this.formatValue(value)}`)
-        );
-      }
-    });
-  }
-
-  public toBeUndefined() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = value === undefined;
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be undefined, but got ${this.formatValue(value)}`)
-        );
-      }
-    });
-  }
-
-  public toBeNullOrUndefined() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = value === null || value === undefined;
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be null or undefined, but got ${this.formatValue(value)}`)
-        );
-      }
-    });
-  }
-
-  // Array checks
-
-  public toContain(itemArg: any) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = Array.isArray(value) && value.includes(itemArg);
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected array{path} to contain ${this.formatValue(itemArg)}`)
-        );
-      }
-    });
-  }
-
-  public toBeEmptyArray() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (!Array.isArray(value)) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be an array, but got ${typeof value}`)
-        );
-      }
-      if (value.length !== 0) {
-        throw new Error(
-          this.createErrorMessage(`Expected array{path} to be empty, but it has ${value.length} elements`)
-        );
-      }
-    });
-  }
-
-  public toContainAll(values: any[]) {
-    return this.runCheck(() => {
-      const arr = this.getObjectToTestReference();
-      if (!Array.isArray(arr)) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be an array, but got ${typeof arr}`)
-        );
-      }
-      
-      const missing = values.filter(v => !arr.includes(v));
-      if (missing.length > 0) {
-        throw new Error(
-          this.createErrorMessage(`Expected array{path} to contain all values ${this.formatValue(values)}, but missing: ${this.formatValue(missing)}`)
-        );
-      }
-    });
-  }
-
-  public toExclude(value: any) {
-    return this.runCheck(() => {
-      const arr = this.getObjectToTestReference();
-      if (!Array.isArray(arr)) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be an array, but got ${typeof arr}`)
-        );
-      }
-      if (arr.includes(value)) {
-        throw new Error(
-          this.createErrorMessage(`Expected array{path} to exclude ${this.formatValue(value)}, but it was found`)
-        );
-      }
-    });
-  }
-
-  public toStartWith(itemArg: any) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = typeof value === 'string' && value.startsWith(itemArg);
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected string{path} to start with "${itemArg}", but got "${value}"`)
-        );
-      }
-    });
-  }
-
-  public toEndWith(itemArg: any) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = typeof value === 'string' && value.endsWith(itemArg);
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected string{path} to end with "${itemArg}", but got "${value}"`)
-        );
-      }
-    });
-  }
-
-  public toBeOneOf(values: any[]) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const result = values.includes(value);
-      if (!result) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be one of ${this.formatValue(values)}, but got ${this.formatValue(value)}`)
-        );
-      }
-    });
-  }
-
-  public toHaveLength(length: number) {
-    return this.runCheck(() => {
-      const obj = this.getObjectToTestReference();
-      if (typeof obj.length !== 'number') {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to have a length property, but it doesn't`)
-        );
-      }
-      if (obj.length !== length) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to have length ${length}, but got length ${obj.length}`)
-        );
-      }
-    });
-  }
-
-  public toBeCloseTo(value: number, precision = 2) {
-    return this.runCheck(() => {
-      const actual = this.getObjectToTestReference();
-      const difference = Math.abs(actual - value);
-      const epsilon = Math.pow(10, -precision) / 2;
-      if (difference > epsilon) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be close to ${value} (within ${epsilon}), but the difference was ${difference}`)
-        );
-      }
-    });
-  }
-
-  public toThrow(expectedError?: any) {
-    return this.runCheck(() => {
-      const fn = this.getObjectToTestReference();
-      if (typeof fn !== 'function') {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be a function, but got ${typeof fn}`)
-        );
-      }
-      
-      let thrown = false;
-      let error: any;
-      
-      try {
-        fn();
-      } catch (e) {
-        thrown = true;
-        error = e;
-        if (expectedError && !(e instanceof expectedError)) {
-          throw new Error(
-            this.createErrorMessage(`Expected function{path} to throw ${expectedError.name}, but it threw ${e.constructor.name}`)
-          );
-        }
-      }
-      
-      if (!thrown) {
-        throw new Error(
-          this.createErrorMessage(`Expected function{path} to throw, but it didn't throw any error`)
-        );
-      }
-    });
-  }
-
-  public toBeTruthy() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (!value) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be truthy, but got ${this.formatValue(value)}`)
-        );
-      }
-    });
-  }
-
-  public toBeFalsy() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (value) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be falsy, but got ${this.formatValue(value)}`)
-        );
-      }
-    });
-  }
-
-  public toBeGreaterThanOrEqual(numberArg: number) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (value < numberArg) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be greater than or equal to ${numberArg}, but got ${value}`)
-        );
-      }
-    });
-  }
-
-  public toBeLessThanOrEqual(numberArg: number) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (value > numberArg) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be less than or equal to ${numberArg}, but got ${value}`)
-        );
-      }
-    });
-  }
-
-  public toMatchObject(objectArg: object) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      const matchResult = plugins.fastDeepEqual(value, objectArg);
-      if (!matchResult) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to match ${this.formatValue(objectArg)}`)
-        );
-      }
-    });
-  }
-
-  public toContainEqual(value: any) {
-    return this.runCheck(() => {
-      const arr = this.getObjectToTestReference();
-      if (!Array.isArray(arr)) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be an array, but got ${typeof arr}`)
-        );
-      }
-      
-      const found = arr.some((item: any) => plugins.fastDeepEqual(item, value));
-      if (!found) {
-        throw new Error(
-          this.createErrorMessage(`Expected array{path} to contain an item equal to ${this.formatValue(value)}`)
-        );
-      }
-    });
-  }
-
-  public toBeArray() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (!Array.isArray(value)) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be an array, but got ${typeof value}`)
-        );
-      }
-    });
-  }
-
-  public toInclude(substring: string) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (typeof value !== 'string') {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be a string, but got ${typeof value}`)
-        );
-      }
-      if (!value.includes(substring)) {
-        throw new Error(
-          this.createErrorMessage(`Expected string{path} to include "${substring}", but it doesn't`)
-        );
-      }
-    });
-  }
-
-  public toHaveLengthGreaterThan(length: number) {
-    return this.runCheck(() => {
-      const obj = this.getObjectToTestReference();
-      if (typeof obj.length !== 'number') {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to have a length property, but it doesn't`)
-        );
-      }
-      if (obj.length <= length) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to have length greater than ${length}, but got length ${obj.length}`)
-        );
-      }
-    });
-  }
-
-  public toHaveLengthLessThan(length: number) {
-    return this.runCheck(() => {
-      const obj = this.getObjectToTestReference();
-      if (typeof obj.length !== 'number') {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to have a length property, but it doesn't`)
-        );
-      }
-      if (obj.length >= length) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to have length less than ${length}, but got length ${obj.length}`)
-        );
-      }
-    });
-  }
-
-  public toBeDate() {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (!(value instanceof Date)) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be a Date, but got ${value.constructor ? value.constructor.name : typeof value}`)
-        );
-      }
-    });
-  }
-
-  public toBeBeforeDate(date: Date) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (!(value instanceof Date)) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be a Date, but got ${value.constructor ? value.constructor.name : typeof value}`)
-        );
-      }
-      if (value >= date) {
-        throw new Error(
-          this.createErrorMessage(`Expected date{path} to be before ${date.toISOString()}, but got ${value.toISOString()}`)
-        );
-      }
-    });
-  }
-
-  public toBeAfterDate(date: Date) {
-    return this.runCheck(() => {
-      const value = this.getObjectToTestReference();
-      if (!(value instanceof Date)) {
-        throw new Error(
-          this.createErrorMessage(`Expected value{path} to be a Date, but got ${value.constructor ? value.constructor.name : typeof value}`)
-        );
-      }
-      if (value <= date) {
-        throw new Error(
-          this.createErrorMessage(`Expected date{path} to be after ${date.toISOString()}, but got ${value.toISOString()}`)
-        );
-      }
-    });
+    return runDirectOrNegated(checkFunction);
   }
 
   public customAssertion(
@@ -711,20 +263,23 @@ export class Assertion {
   }
 
   /**
-   * Drill into a property
+   * Drill into a property of an object.
+   * @param propertyName Name of the property to navigate into.
+   * @returns Assertion of the property type.
    */
-  public property(propertyNameArg: string) {
-    this.propertyDrillDown.push(propertyNameArg);
-    return this;
+  public property<K extends keyof NonNullable<T>>(propertyName: K): Assertion<NonNullable<T>[K]> {
+    this.propertyDrillDown.push(propertyName as string);
+    return this as unknown as Assertion<NonNullable<T>[K]>;
   }
 
   /**
-   * Drill into an array index
+   * Drill into an array element by index.
+   * @param index Index of the array item.
+   * @returns Assertion of the element type.
    */
-  public arrayItem(indexArg: number) {
-    // Save the number (instead of "[index]")
-    this.propertyDrillDown.push(indexArg);
-    return this;
+  public arrayItem(index: number): Assertion<T extends Array<infer U> ? U : unknown> {
+    this.propertyDrillDown.push(index);
+    return this as unknown as Assertion<T extends Array<infer U> ? U : unknown>;
   }
 
   public log() {
@@ -733,4 +288,37 @@ export class Assertion {
     console.log(`Path: ${this.formatDrillDown() || '(root)'}`);
     return this;
   }
+  // Namespaced matcher accessors
+  /** String-specific matchers */
+  public get string() {
+    return new StringMatchers(this as Assertion<string>);
+  }
+  /** Array-specific matchers */
+  public get array() {
+    return new ArrayMatchers<any>(this as Assertion<any[]>);
+  }
+  /** Number-specific matchers */
+  public get number() {
+    return new NumberMatchers(this as Assertion<number>);
+  }
+  /** Boolean-specific matchers */
+  public get boolean() {
+    return new BooleanMatchers(this as Assertion<boolean>);
+  }
+  /** Object-specific matchers */
+  public get object() {
+    return new ObjectMatchers<any>(this as Assertion<object>);
+  }
+  /** Function-specific matchers */
+  public get function() {
+    return new FunctionMatchers(this as Assertion<Function>);
+  }
+  /** Date-specific matchers */
+  public get date() {
+    return new DateMatchers(this as Assertion<Date>);
+  }
+  /** Type-based matchers */
+  public get type() {
+    return new TypeMatchers(this as Assertion<any>);
+  }
 }

ts/types.ts

@@ -0,0 +1,13 @@
+/**
+ * Common types for smartexpect
+ */
+/** Execution mode: sync or async */
+export type TExecutionType = 'sync' | 'async';
+/**
+ * Definition of a custom matcher function.
+ * Should return an object with `pass` and optional `message`.
+ */
+export type TMatcher = (
+  received: any,
+  ...args: any[]
+) => { pass: boolean; message?: string | (() => string) };