feat: Add It.is matcher

Related to #252.

README.md

@@ -264,6 +264,7 @@ console.log(instance(fn)(
 ```
 
 Available matchers:
+- `is` - uses `Object.is` for comparison,
 - `isAny` - matches anything,
 - `isNumber` - matches any number,
 - `isString` - matches any string, can search for substrings and patterns,
@@ -314,15 +315,15 @@ You can override the default matcher that will be used when setting expectations
 ```ts
 import { mock, when, instance, It, setDefaults } from 'strong-mock';
 
-// Set the default matcher to use strict equality.
+// Use strict equality instead of deep equality.
 setDefaults({
-  matcher: (x) => It.matches((y) => y === x)
+  matcher: It.is
 })
 
-const fn = mock<(x: { foo: string }) => boolean>();
-when(fn({ foo: "bar" })).thenReturn(true);
+const fn = mock<(x: number[]) => boolean>();
+when(fn([1, 2, 3])).thenReturn(true);
 
-instance(fn)({ foo: "bar" }); // throws because different objects
+instance(fn)([1, 2, 3]); // throws because different arrays
 ```
 
 ## FAQ

src/expectation/matcher.spec.ts

@@ -91,6 +91,47 @@ describe('It', () => {
     });
   });
 
+  describe('is', () => {
+    it('should compare primitives', () => {
+      expect(It.is(42).matches(42)).toBeTruthy();
+      expect(It.is(42).matches(0)).toBeFalsy();
+      expect(It.is('foo').matches('foo')).toBeTruthy();
+      expect(It.is('foo').matches('bar')).toBeFalsy();
+      expect(It.is(true).matches(true)).toBeTruthy();
+      expect(It.is(true).matches(false)).toBeFalsy();
+    });
+
+    it('should compare arrays by reference', () => {
+      const arr = [1, 2, 3];
+      expect(It.is(arr).matches(arr)).toBeTruthy();
+      expect(It.is(arr).matches([1, 2, 3])).toBeFalsy();
+    });
+
+    it('should compare objects by reference', () => {
+      const obj = { foo: 'bar' };
+      expect(It.is(obj).matches(obj)).toBeTruthy();
+      expect(It.is(obj).matches({ foo: 'bar' })).toBeFalsy();
+    });
+
+    it('should compare +0 and -0', () => {
+      expect(It.is(+0).matches(-0)).toBeFalsy();
+      expect(It.is(-0).matches(-0)).toBeTruthy();
+    });
+
+    it('should compare NaN', () => {
+      expect(It.is(NaN).matches(0 / 0)).toBeTruthy();
+      expect(It.is(NaN).matches(Number.NaN)).toBeTruthy();
+    });
+
+    it('should pretty print', () => {
+      expectAnsilessEqual(It.is(23).toJSON(), '23');
+      expectAnsilessEqual(
+        It.is({ foo: { bar: [1, 2, 3] } }).toJSON(),
+        '{"foo": {"bar": [1, 2, 3]}}'
+      );
+    });
+  });
+
   describe('isAny', () => {
     it('should match null', () => {
       expect(It.isAny().matches(null)).toBeTruthy();

src/expectation/matcher.ts

@@ -292,11 +292,27 @@ const willCapture = <T = unknown>(
   return matcher as any;
 };
 
+/**
+ * Compare values using `Object.is`.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
+ */
+const is = <T = unknown>(expected: T): TypeMatcher<T> => {
+  const matcher: Matcher = {
+    __isMatcher: true,
+    matches: (actual) => Object.is(actual, expected),
+    toJSON: () => `${printExpected(expected)}`,
+  };
+
+  return matcher as any;
+};
+
 /**
  * Contains argument matchers that can be used to ignore arguments in an
  * expectation or to match complex arguments.
  */
 export const It = {
+  is,
   isAny,
   matches,
   isObject,