documentation(code completion): mention that the narrow methods help …

…with code completion

.vscode/settings.json

@@ -45,6 +45,7 @@
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
 
+  "testExplorer.useNativeTesting": true,
   "mochaExplorer.files": ["lib/tests/**/*.ts"],
   "mochaExplorer.require": ["ts-node/register"],
 

README.md

@@ -22,6 +22,8 @@ As hinted above, **Chai TS** has been created with Chai's `expect` interface in
 
 A `narrow*` assertion performs the same equality test as its counterparts (so `narrowEq` behaves like `eq`), while validating if the type of its argument can be assigned to the type of the tested value - the "tested value" is typically the argument passed to the `expect` method.
 
+A side benefit of using the `narrow*` assertion methods, in particular the ones for logical equality (like `narrowEql`), is that they may simplify implementing tests because they enable code completion when writing the expected value.
+
 Valid: (the tests pass and the code compiles)
 
 ```typescript

lib/src/chai-ts-as-promised.ts

@@ -74,10 +74,15 @@ declare global {
        * type of the tested value - i.e., if the expected value can be assigned to a variable
        * that has the type of the tested value.
        *
+       * Besides testing the type, this method simplifies implementing tests because it enables
+       * code completion when writing the expected value.
+       *
        * @example
        * await expect(Promise.resolve([1, 2, 3])).to.eventually.be.narrowEql([1, 2, 3]);
        * await expect(Promise.resolve([1, 2, 3] as unknown[])).to.eventually.be.narrowEql([1, 2, 3]);
        * await expect(Promise.resolve([1, 2, 3]) as Promise<unknown[]>).to.eventually.be.narrowEql([1, 2, 3]);
+       * await expect(Promise.resolve({ a: 1, b: true, c: 'value' }))
+       *   .to.eventually.be.narrowEql({ a: 1, b: true, c: 'value' });
        */
       narrowEql: NarrowPromisedEqual<Awaited<A>>;
 
@@ -86,10 +91,15 @@ declare global {
        * type of the tested value - i.e., if the expected value can be assigned to a variable
        * that has the type of the tested value.
        *
+       * Besides testing the type, this method simplifies implementing tests because it enables
+       * code completion when writing the expected value.
+       *
        * @example
        * await expect(Promise.resolve([1, 2, 3])).to.eventually.be.narrowEqls([1, 2, 3]);
        * await expect(Promise.resolve([1, 2, 3] as unknown[])).to.eventually.be.narrowEqls([1, 2, 3]);
        * await expect(Promise.resolve([1, 2, 3]) as Promise<unknown[]>).to.eventually.be.narrowEqls([1, 2, 3]);
+       * await expect(Promise.resolve({ a: 1, b: true, c: 'value' }))
+       *   .to.eventually.be.narrowEqls({ a: 1, b: true, c: 'value' });
        */
       narrowEqls: NarrowPromisedEqual<Awaited<A>>;
 

lib/src/chai-ts.ts

@@ -52,9 +52,13 @@ declare global {
        * type of the tested value - i.e., if the expected value can be assigned to a variable
        * that has the type of the tested value.
        *
+       * Besides testing the type, this method simplifies implementing tests because it enables
+       * code completion when writing the expected value.
+       *
        * @example
        * expect([1, 2, 3]).narrowEql([1, 2, 3]);
        * expect([1, 2, 3] as unknown[]).to.narrowEql([1, 2, 3]);
+       * expect({ a: 1, b: true, c: 'value' }).narrowEqls({ a: 1, b: true, c: 'value' });
        */
       narrowEql: NarrowEqual<A>;
 
@@ -63,9 +67,13 @@ declare global {
        * type of the tested value - i.e., if the expected value can be assigned to a variable
        * that has the type of the tested value.
        *
+       * Besides testing the type, this method simplifies implementing tests because it enables
+       * code completion when writing the expected value.
+       *
        * @example
        * expect([1, 2, 3]).narrowEqls([1, 2, 3]);
        * expect([1, 2, 3] as unknown[]).to.narrowEqls([1, 2, 3]);
+       * expect({ a: 1, b: true, c: 'value' }).narrowEqls({ a: 1, b: true, c: 'value' });
        */
       narrowEqls: NarrowEqual<A>;
 

lib/tests/chai-ts-as-promised.test.ts

@@ -41,12 +41,24 @@ describe('chai-ts-as-promised', () => {
       await expect(Promise.resolve([1, 2, 3])).to.eventually.be.narrowEql([1, 2, 3]);
       await expect(Promise.resolve([1, 2, 3] as unknown[])).to.eventually.be.narrowEql([1, 2, 3]);
       await expect(Promise.resolve([1, 2, 3]) as Promise<unknown[]>).to.eventually.be.narrowEql([1, 2, 3]);
+
+      await expect(Promise.resolve({ a: 1, b: true, c: 'value' })).to.eventually.be.narrowEql({
+        a: 1,
+        b: true,
+        c: 'value',
+      });
     });
 
     it('narrowEqls', async () => {
       await expect(Promise.resolve([1, 2, 3])).to.eventually.be.narrowEqls([1, 2, 3]);
       await expect(Promise.resolve([1, 2, 3] as unknown[])).to.eventually.be.narrowEqls([1, 2, 3]);
       await expect(Promise.resolve([1, 2, 3]) as Promise<unknown[]>).to.eventually.be.narrowEqls([1, 2, 3]);
+
+      await expect(Promise.resolve({ a: 1, b: true, c: 'value' })).to.eventually.be.narrowEqls({
+        a: 1,
+        b: true,
+        c: 'value',
+      });
     });
 
     it('narrowEqual', async () => {

lib/tests/chai-ts.test.ts

@@ -95,11 +95,13 @@ describe('chai-ts', () => {
     it('narrowEql', () => {
       expect([1, 2, 3]).narrowEql([1, 2, 3]);
       expect([1, 2, 3] as unknown[]).to.narrowEql([1, 2, 3]);
+      expect({ a: 1, b: true, c: 'value' }).narrowEql({ a: 1, b: true, c: 'value' });
     });
 
     it('narrowEqls', () => {
       expect([1, 2, 3]).narrowEqls([1, 2, 3]);
       expect([1, 2, 3] as unknown[]).to.narrowEqls([1, 2, 3]);
+      expect({ a: 1, b: true, c: 'value' }).narrowEqls({ a: 1, b: true, c: 'value' });
     });
 
     it('narrowEqual', () => {