chore(plugins): Document & use TS type definition (#1915)

As proposed by @n1xx1 in #1778 (comment)

Co-authored-by: n1xx1 <[email protected]>

Author: fb55

.eslintrc.json

@@ -94,7 +94,6 @@
         "@typescript-eslint/prefer-string-starts-ends-with": 2,
         "@typescript-eslint/prefer-readonly": 2,
         "@typescript-eslint/prefer-includes": 2,
-        "@typescript-eslint/no-unnecessary-condition": 0, // TODO
         "@typescript-eslint/switch-exhaustiveness-check": 2,
         "@typescript-eslint/prefer-nullish-coalescing": 2,
 
@@ -105,8 +104,7 @@
       "files": "*.spec.ts",
       "extends": "plugin:jest/recommended",
       "rules": {
-        "@typescript-eslint/no-explicit-any": 0,
-        "@typescript-eslint/ban-ts-comment": 0
+        "@typescript-eslint/no-explicit-any": 0
       }
     }
   ]

Readme.md

@@ -246,6 +246,16 @@ $.prototype.logHtml = function () {
 $('body').logHtml(); // logs "Hello, <b>world</b>!" to the console
 ```
 
+If you're using TypeScript, you should also add a type definition for your new method:
+
+```ts
+declare module 'cheerio' {
+  interface Cheerio<T> {
+    logHtml(this: Cheerio<T>): void;
+  }
+}
+```
+
 ### The "DOM Node" object
 
 Cheerio collections are made up of objects that bear some resemblance to [browser-based DOM nodes](https://developer.mozilla.org/en-US/docs/Web/API/Node). You can expect them to define the following properties:

src/cheerio.spec.ts

@@ -6,6 +6,16 @@ import { Cheerio } from './cheerio';
 import type { Element } from 'domhandler';
 import type { CheerioOptions } from './options';
 
+declare module '.' {
+  interface Cheerio<T> {
+    myPlugin(...args: unknown[]): {
+      context: Cheerio<T>;
+      args: unknown[];
+    };
+    foo(): void;
+  }
+}
+
 // HTML
 const script = '<script src="script.js" type="text/javascript"></script>';
 const multiclass = '<p><a class="btn primary" href="#">Save</a></p>';
@@ -355,7 +365,6 @@ describe('cheerio', () => {
       it('should honor extensions defined on `prototype` property', () => {
         const $ = cheerio.load('<div>');
 
-        // @ts-ignore
         $.prototype.myPlugin = function (...args: unknown[]) {
           return {
             context: this,
@@ -365,17 +374,13 @@ describe('cheerio', () => {
 
         const $div = $('div');
 
-        // @ts-ignore
         expect(typeof $div.myPlugin).toBe('function');
-        // @ts-ignore
         expect($div.myPlugin().context).toBe($div);
-        // @ts-ignore
         expect($div.myPlugin(1, 2, 3).args).toStrictEqual([1, 2, 3]);
       });
 
       it('should honor extensions defined on `fn` property', () => {
         const $ = cheerio.load('<div>');
-        // @ts-ignore
         $.fn.myPlugin = function (...args: unknown[]) {
           return {
             context: this,
@@ -385,24 +390,19 @@ describe('cheerio', () => {
 
         const $div = $('div');
 
-        // @ts-ignore
         expect(typeof $div.myPlugin).toBe('function');
-        // @ts-ignore
         expect($div.myPlugin().context).toBe($div);
-        // @ts-ignore
         expect($div.myPlugin(1, 2, 3).args).toStrictEqual([1, 2, 3]);
       });
 
       it('should isolate extensions between loaded functions', () => {
         const $a = cheerio.load('<div>');
         const $b = cheerio.load('<div>');
 
-        // @ts-ignore
         $a.prototype.foo = function () {
           /* Ignore */
         };
 
-        // @ts-ignore
         expect($b('div').foo).toBeUndefined();
       });
     });