changelog.md

@@ -1,73 +1,5 @@
 # Changelog
 
-## 2025-05-01 - 2.4.2 - fix(cleanup)
-Remove unused scratch files
-
-- Deleted scratch-alias.js, scratch-alias2.js, scratch-alias3.js, scratch-alias4.js, scratch-alias5.js, and scratch.js
-- Clean up temporary alias and scratch test files
-
-## 2025-04-30 - 2.4.1 - fix(Assertion)
-Improve toHaveProperty alias by forwarding arguments correctly for intuitive object property assertions
-
-- Updated the toHaveProperty method in the Assertion class to check the number of arguments and call the appropriate object matcher
-- Added several scratch alias files to demonstrate and test the alias usage
-- Enhanced test cases in test/propertypath to cover alias behavior
-
-## 2025-04-30 - 2.4.0 - feat(object)
-add toHaveOwnProperty method and improve property-path matching in object assertions
-
-- Added 'toHaveOwnProperty' as a direct method on Assertion to check for own properties
-- Enhanced property path evaluation in 'toHaveProperty' to handle nested keys more robustly
-- Renamed test file to maintain consistent naming for expect.any tests
-- Introduced scratch.js for manual testing and debugging of property matchers
-
-## 2025-04-30 - 2.3.3 - fix(tests)
-Fix test file naming inconsistencies
-
-- Rename 'test/test.diffOutput.ts' to 'test/test.diffoutput.ts' to standardize filename casing
-- Rename 'test/test.propertyPath.ts' to 'test/test.propertypath.ts' for consistent file naming
-
-## 2025-04-30 - 2.3.2 - fix(object)
-Update toHaveProperty matcher to support nested property paths using dot notation
-
-- Changed toHaveProperty implementation to split property strings on '.' and traverse nested objects
-- Fixed value comparison for nested properties by comparing the final drilled value instead of direct property access
-- Added tests for nested property access in test/propertyPath.ts
-
-## 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
 

license

@@ -1,4 +1,4 @@
-Copyright (c) 2022 Task Venture Capital GmbH (hello@lossless.com)
+Copyright (c) 2022 Lossless 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.4.2",
+  "version": "2.2.0",
   "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,29 +8,19 @@ 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 } from '@push.rocks/smartexpect';
+import { expect, expectAsync } from '@push.rocks/smartexpect';
 ```
 
 ### Synchronous Expectations
@@ -264,96 +254,6 @@ 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

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

test/test.keys.ts

@@ -1,51 +0,0 @@
-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.propertypath.ts

@@ -1,17 +0,0 @@
-import { tap, expect as tExpect } from '@push.rocks/tapbundle';
-import * as smartexpect from '../dist_ts/index.js';
-
-tap.test('toHaveProperty nested path via dot notation', async () => {
-  const testObject = { level1: { level2: { level3: 'value' }},  publicTest: 'hi' };
-
-  smartexpect.expect(testObject).object.toHaveProperty('publicTest');
-  smartexpect.expect(testObject).toHaveProperty('publicTest');
-  // Existence check
-  smartexpect.expect(testObject).object.toHaveProperty('level1.level2.level3');
-  // Value check
-  smartexpect.expect(testObject).object.toHaveProperty('level1.level2.level3', 'value');
-  // Negation for missing deep property
-  smartexpect.expect(testObject).not.object.toHaveProperty('level1.level2.missing');
-});
-
-export default tap.start();

ts/00_commitinfo_data.ts

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

ts/namespaces/object.ts

@@ -62,24 +62,11 @@ export class ObjectMatchers<T extends object, M extends TExecutionType> {
     return this.assertion.customAssertion(
       (v) => {
         const obj = v as any;
-        // first check for a literal property (including inherited)
-        if (property in obj) {
-          if (arguments.length === 2) {
-            return plugins.fastDeepEqual(obj[property], value);
-          }
-          return true;
-        }
-        // no direct key, try nested path via dot notation
-        const path = property.split('.');
-        let current = obj;
-        for (const key of path) {
-          if (current == null || !(key in current)) {
+        if (!(property in obj)) {
           return false;
         }
-          current = (current as any)[key];
-        }
         if (arguments.length === 2) {
-          return plugins.fastDeepEqual(current, value);
+          return plugins.fastDeepEqual(obj[property], value);
         }
         return true;
       },
@@ -143,30 +130,4 @@ export class ObjectMatchers<T extends object, M extends TExecutionType> {
         `\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/smartexpect.classes.assertion.ts

@@ -355,14 +355,7 @@ export class Assertion<T = unknown, M extends TExecutionType = 'sync'> {
   public toInclude(substring: string) { return this.string.toInclude(substring); }
   public toMatch(regex: RegExp) { return this.string.toMatch(regex); }
   public toBeOneOf(values: any[]) { return this.string.toBeOneOf(values as string[]); }
-  public toHaveProperty(property: string, value?: any) {
-    // Forward only provided arguments to object matcher to preserve argument count
-    if (arguments.length === 2) {
-      return this.object.toHaveProperty(property, value);
-    }
-    return this.object.toHaveProperty(property);
-  }
-  public toHaveOwnProperty(property: string, value?: any) { return this.object.toHaveOwnProperty(property, value); }
+  public toHaveProperty(property: string, value?: any) { return this.object.toHaveProperty(property, value); }
   public toMatchObject(expected: object) { return this.object.toMatchObject(expected); }
   public toBeInstanceOf(constructor: any) { return this.object.toBeInstanceOf(constructor); }
   public toHaveDeepProperty(path: string[]) { return this.object.toHaveDeepProperty(path); }