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

readme.md

@@ -53,10 +53,10 @@ expect('hithere').toMatch(/hi/);
 
 ### Asynchronous Expectations
 
-For asynchronous operations, use `expectAsync` to return a promise:
+For asynchronous code, use the same `expect` function with the `.resolves` or `.rejects` modifier:
 
 ```typescript
-import { expectAsync } from '@push.rocks/smartexpect';
+import { expect } from '@push.rocks/smartexpect';
 
 const asyncStringFetcher = async (): Promise<string> => {
   return 'async string';
@@ -64,8 +64,8 @@ const asyncStringFetcher = async (): Promise<string> => {
 
 const asyncTest = async () => {
   // Add a timeout to prevent hanging tests
-  await expectAsync(asyncStringFetcher()).timeout(5000).toBeTypeofString();
-  await expectAsync(asyncStringFetcher()).toEqual('async string');
+  await expect(asyncStringFetcher()).resolves.withTimeout(5000).type.toBeTypeofString();
+  await expect(asyncStringFetcher()).resolves.toEqual('async string');
 };
 
 asyncTest();
@@ -230,6 +230,30 @@ expect(user.age)
   .toBeGreaterThanOrEqual(18);
 ```
 
+### Custom Matchers
+
+You can define your own matchers via `expect.extend()`:
+
+```typescript
+expect.extend({
+  toBeOdd(received: number) {
+    const pass = received % 2 === 1;
+    return {
+      pass,
+      message: () =>
+        `Expected ${received} ${pass ? 'not ' : ''}to be odd`,
+    };
+  },
+});
+
+// Then use your custom matcher in tests:
+expect(3).toBeOdd();
+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.
+
 ## Best Practices
 
 - **Human-readable assertions**: The fluent API is designed to create tests that read like natural language sentences.