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

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');
 };