allow plugins to have useful constructors and access their own state

Author: ScriptSmith

plugins/plugin.ts

@@ -1,25 +1,32 @@
 import * as puppeteer from "puppeteer";
-import * as instamancer from "..";
-import {TFullApiPost, TPost, TSearchResult, TSinglePost} from "..";
+import {Instagram, TFullApiPost, TPost, TSearchResult, TSinglePost} from "..";
 
 export type DType = TPost | TSinglePost | TFullApiPost | TSearchResult;
 
-export interface IPlugin {
-    constructionEvent?(this: instamancer.Instagram<DType>): void;
+export interface IPluginContext<Plugin, PostType> {
+    plugin: Plugin;
+    state: Instagram<PostType>;
+}
+
+export interface IPlugin<PostType> {
+    constructionEvent?(this: IPluginContext<IPlugin<PostType>, PostType>): void;
 
     requestEvent?(
-        this: instamancer.Instagram<DType>,
+        this: IPluginContext<IPlugin<PostType>, PostType>,
         req: puppeteer.Request,
         overrides: puppeteer.Overrides,
     ): void;
 
     responseEvent?(
-        this: instamancer.Instagram<DType>,
+        this: IPluginContext<IPlugin<PostType>, PostType>,
         res: puppeteer.Response,
-        data: DType,
+        data: {[key: string]: any},
     ): void;
 
-    postPageEvent?(this: instamancer.Instagram<DType>, data: DType): void;
+    postPageEvent?(
+        this: IPluginContext<IPlugin<PostType>, PostType>,
+        data: PostType,
+    ): void;
 
-    graftingEvent?(this: instamancer.Instagram<DType>): void;
+    graftingEvent?(this: IPluginContext<IPlugin<PostType>, PostType>): void;
 }

plugins/plugins/largeFirst.ts

@@ -1,12 +1,13 @@
 import {Overrides, Request} from "puppeteer";
 import * as querystring from "querystring";
 import {format as urlFormat, parse as urlParse} from "url";
-import {Instagram} from "../../src/api/instagram";
-import {DType, IPlugin} from "../plugin";
+import {IPlugin, IPluginContext} from "../plugin";
 
-export class LargeFirst implements IPlugin {
-    public constructionEvent(this: Instagram<DType>): void {
-        this.jumpSize = 150;
+export class LargeFirst<PostType> implements IPlugin<PostType> {
+    public constructionEvent(
+        this: IPluginContext<IPlugin<PostType>, PostType>,
+    ): void {
+        this.state.jumpSize = 150;
     }
 
     public requestEvent(req: Request, overrides: Overrides): void {

src/api/api.ts

@@ -1,8 +1,13 @@
 import {Type} from "io-ts";
 import * as winston from "winston";
-import {IPlugin} from "../../plugins/plugin";
+import {DType, IPlugin} from "../../plugins";
 import {Instagram} from "./instagram";
-import {ISearchOptions, Search} from "./search";
+import {
+    ISearchOptions,
+    ISearchOptionsPlugins,
+    Search,
+    TSearchResult,
+} from "./search";
 import {
     FullApiPost,
     Post as PostValidator,
@@ -51,9 +56,6 @@ export interface IOptionsCommon {
 
     // Custom io-ts validator
     validator?: Type<unknown>;
-
-    // Custom plugins
-    plugins?: IPlugin[];
 }
 
 export interface IOptionsFullApi extends IOptionsCommon {
@@ -64,7 +66,19 @@ export interface IOptionsRegular extends IOptionsCommon {
     fullAPI?: false;
 }
 
-export type IOptions = IOptionsFullApi | IOptionsRegular;
+export interface IOptionsFullApiPlugins<PostType> extends IOptionsFullApi {
+    plugins?: Array<IPlugin<PostType>>;
+}
+
+export interface IOptionsRegularPlugins<PostType> extends IOptionsRegular {
+    plugins?: Array<IPlugin<PostType>>;
+}
+
+export type IOptions =
+    | IOptionsFullApi
+    | IOptionsRegular
+    | IOptionsFullApiPlugins<DType>
+    | IOptionsRegularPlugins<DType>;
 
 /**
  * An Instagram post API wrapper
@@ -104,19 +118,20 @@ export type InstagramFullPostClass = Hashtag<TFullApiPost> | User<TFullApiPost>;
 export function createApi(
     type: "search",
     query: string,
-    options?: ISearchOptions,
+    options?: ISearchOptions | ISearchOptionsPlugins<TSearchResult>,
 ): Search;
 export function createApi(type: "post", id: string[], options?: IOptions): Post;
 export function createApi(
     type: "hashtag" | "user",
     id: string,
-    options?: IOptionsRegular,
+    options?: IOptionsRegular | IOptionsRegularPlugins<InstagramPostClass>,
 ): InstagramPostClass;
 export function createApi(
     type: "hashtag" | "user",
     id: string,
-    options?: IOptionsFullApi,
+    options?: IOptionsFullApi | IOptionsFullApiPlugins<InstagramFullPostClass>,
 ): InstagramFullPostClass;
+
 export function createApi(
     type: "hashtag" | "user" | "post" | "search",
     id: string | string[],

src/api/instagram.ts

@@ -17,6 +17,7 @@ import {
 } from "puppeteer";
 import * as winston from "winston";
 import {IPlugin} from "../../plugins";
+import {IPluginContext} from "../../plugins/plugin";
 import {IOptions} from "./api";
 import {PostIdSet} from "./postIdSet";
 
@@ -191,7 +192,7 @@ export class Instagram<PostType> extends EventEmitter {
         this.executablePath = options.executablePath;
         this.validator = options.validator || validator;
 
-        this.addPlugins(options.plugins);
+        this.addPlugins(options["plugins"]);
         this.emit("construction");
     }
 
@@ -289,6 +290,13 @@ export class Instagram<PostType> extends EventEmitter {
         }
     }
 
+    /**
+     * Match the url to the url used in API requests
+     */
+    public matchURL(url: string) {
+        return url.startsWith(this.catchURL) && !url.includes("include_reel");
+    }
+
     /**
      * Close the page and browser
      */
@@ -461,13 +469,6 @@ export class Instagram<PostType> extends EventEmitter {
         }
     }
 
-    /**
-     * Match the url to the url used in API requests
-     */
-    protected matchURL(url: string) {
-        return url.startsWith(this.catchURL) && !url.includes("include_reel");
-    }
-
     /**
      * Open a post in a new page, then extract its metadata
      */
@@ -861,7 +862,7 @@ export class Instagram<PostType> extends EventEmitter {
         }
     }
 
-    private addPlugins(plugins: IPlugin[]) {
+    private addPlugins(plugins: Array<IPlugin<PostType>>) {
         if (!plugins) {
             return;
         }
@@ -878,7 +879,12 @@ export class Instagram<PostType> extends EventEmitter {
             for (const event of events) {
                 const pluginEvent = plugin[event + "Event"];
                 if (pluginEvent) {
-                    this.on(event, pluginEvent);
+                    const context: IPluginContext<typeof plugin, PostType> = {
+                        plugin,
+                        state: this,
+                    };
+
+                    this.on(event, pluginEvent.bind(context));
                 }
             }
         }

src/api/search.ts

@@ -1,5 +1,6 @@
 import * as t from "io-ts";
 import {excess} from "io-ts-excess";
+import {IPlugin} from "../../plugins";
 import {IOptions} from "./api";
 import {Instagram} from "./instagram";
 
@@ -82,10 +83,14 @@ export type ISearchOptions = Pick<
     >
 >;
 
+export interface ISearchOptionsPlugins<PostType> extends ISearchOptions {
+    plugins?: Array<IPlugin<PostType>>;
+}
+
 export class Search extends Instagram<TSearchResult> {
     public readonly catchURL = "https://www.instagram.com/web/";
     private searchResult: TSearchResult;
-    private searchQuery: string;
+    private readonly searchQuery: string;
 
     constructor(query: string, options: ISearchOptions = {}) {
         super(
@@ -118,7 +123,7 @@ export class Search extends Instagram<TSearchResult> {
         }
     }
 
-    protected matchURL(url: string) {
+    public matchURL(url: string) {
         return url.startsWith(this.catchURL);
     }
 

tests/test.spec.ts

@@ -1,8 +1,9 @@
 import * as t from "io-ts";
 import {Overrides, Request} from "puppeteer";
 import * as winston from "winston";
-import {createApi, DType, Instagram, IPlugin} from "..";
+import {createApi, IPlugin} from "..";
 import {plugins} from "..";
+import {IPluginContext} from "../plugins/plugin";
 import {IOptions, IOptionsFullApi} from "../src/api/api";
 import {FakePage, IFakePageOptions} from "./__fixtures__/FakePage";
 import {QuickGraft} from "./__fixtures__/QuickGraft";
@@ -531,14 +532,13 @@ describe("Search", () => {
 
     test("Search should fire only one network request", async () => {
         const searchRequestsSpy = jest.fn();
-        class RequestCounter implements IPlugin {
+        class RequestCounter<PostType> implements IPlugin<PostType> {
             public requestEvent(
-                this: Instagram<DType>,
+                this: IPluginContext<IPlugin<PostType>, PostType>,
                 req: Request,
                 overrides: Overrides,
             ): void {
-                // @ts-ignore
-                if (this.matchURL(req.url())) {
+                if (this.state.matchURL(req.url())) {
                     searchRequestsSpy();
                 }
             }