add type for selector engine (#4174)

src/client/selectors.ts

@@ -17,12 +17,13 @@
 import { evaluationScript } from './clientHelper';
 import * as channels from '../protocol/channels';
 import { ChannelOwner } from './channelOwner';
+import { SelectorEngine } from './types';
 
 export class Selectors {
   private _channels = new Set<SelectorsOwner>();
   private _registrations: channels.SelectorsRegisterParams[] = [];
 
-  async register(name: string, script: string | Function | { path?: string, content?: string }, options: { contentScript?: boolean } = {}): Promise<void> {
+  async register(name: string, script: string | (() => SelectorEngine) | { path?: string, content?: string }, options: { contentScript?: boolean } = {}): Promise<void> {
     const source = await evaluationScript(script, undefined, false);
     const params = { ...options, name, source };
     for (const channel of this._channels)

src/client/types.ts

@@ -86,3 +86,19 @@ export type LaunchServerOptions = {
   port?: number,
   logger?: Logger,
 } & FirefoxUserPrefs;
+
+export type SelectorEngine = {
+  /**
+   * Creates a selector that matches given target when queried at the root.
+   * Can return undefined if unable to create one.
+   */
+  create(root: HTMLElement, target: HTMLElement): string | undefined;
+  /**
+   * Returns the first element matching given selector in the root's subtree.
+   */
+  query(root: HTMLElement, selector: string): HTMLElement | null;
+  /**
+   * Returns all elements matching given selector in the root's subtree.
+   */
+  queryAll(root: HTMLElement, selector: string): HTMLElement[];
+};