chore(plugins): Document & use TS type definition

.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();
  });
  });