@appium/types 0.2.3 → 0.3.0

package/lib/plugin.ts

@@ -0,0 +1,92 @@
+import {MethodMap, UpdateServerCallback, Class, AppiumLogger} from '.';
+import {Driver, ExternalDriver} from './driver';
+
+/**
+ * The interface describing the constructor and static properties of a Plugin.
+ */
+export interface PluginStatic<T extends Plugin = Plugin> {
+  /**
+   * Allows a plugin to modify the Appium server instance.
+   */
+  updateServer?: UpdateServerCallback;
+  /**
+   * Plugins can define new methods for the Appium server to map to command names, of the same
+   * format as used in Appium's `routes.js`, for example, this would be a valid `newMethodMap`:
+   * @example
+   * {
+   *   '/session/:sessionId/new_method': {
+   *     GET: {command: 'getNewThing'},
+   *     POST: {command: 'setNewThing', payloadParams: {required: ['someParam']}}
+   *   }
+   * }
+   */
+  newMethodMap?: MethodMap<T>;
+}
+
+/**
+ * An instance of a "plugin" extension.
+ *
+ * Likewise, the `prototype` of a {@link PluginClass `Plugin` class}.
+ */
+export interface Plugin {
+  /**
+   * Name of the plugin.  Derived from the metadata.
+   */
+  name: string;
+  /**
+   * A logger with prefix identifying the plugin
+   */
+  logger: AppiumLogger;
+  /**
+   * CLI args for this plugin (if any are accepted and provided).
+   */
+  cliArgs: Record<string, any>;
+  /**
+   * Listener for unexpected server shutdown, which allows a plugin to do cleanup or take custom actions.
+   */
+  onUnexpectedShutdown?: (driver: Driver, cause: Error | string) => Promise<void>;
+  /**
+   * Handle an Appium command, optionally running and using or throwing away the value of the
+   * original Appium behavior (or the behavior of the next plugin in a plugin chain).
+   */
+  handle?: (
+    next: NextPluginCallback,
+    driver: Driver,
+    cmdName: string,
+    ...args: any[]
+  ) => Promise<void>;
+}
+
+/**
+ * A reference to an async function which encapsulates what would normally
+ * happen if this plugin were not handling a command. Used by {@link PluginInterface.handle}.
+ *
+ * Given `next()` is a `NextPluginCallback`: if this is the only plugin
+ * handling the command, `await next()` would therefore trigger the normal
+ * handling logic in the driver which is in use. If another plugin is
+ * registered, it would run *that* plugin's `handle` method and return the
+ * result for use here. Note that if this plugin does *not* call `await next()`,
+ * then the normal command logic will not be run, and this plugin is responsible
+ * for managing new command timeouts and command logging, for example:
+ * `driver.stopNewCommandTimeout()` -- before running plugin logic
+ * `driver.startNewCommandTimeout()` -- after running plugin logic
+ * `driver._eventHistory.commands.push({cmd: cmdName, startTime, endTime}) --
+ * after running plugin logic
+ */
+export type NextPluginCallback = () => Promise<void>;
+
+/**
+ * Implementation of a command within a plugin
+ */
+export type PluginCommand<TArgs = any> = (
+  next: NextPluginCallback,
+  driver: ExternalDriver,
+  ...args: TArgs[]
+) => Promise<void>;
+
+/**
+ * Mainly for internal use.
+ *
+ * The third parameter is the possible constructor signatures for the plugin class.
+ */
+export type PluginClass = Class<Plugin, PluginStatic, [string, Record<string, unknown>]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/types",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Various type declarations used across Appium",
   "keywords": [
     "appium",
@@ -18,6 +18,7 @@
   },
   "license": "Apache-2.0",
   "author": "https://github.com/appium",
+  "types": "./build/index.d.ts",
   "files": [
     "build",
     "lib"
@@ -26,18 +27,23 @@
     "build": "node ./scripts/generate-schema-types.js",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
-    "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore ."
+    "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
+    "prepare": "npm run build",
+    "test:smoke": "echo 'No smoke test for this package'"
+  },
+  "dependencies": {
+    "@appium/schema": "^0.0.8",
+    "@types/express": "4.17.13",
+    "@types/npmlog": "4.1.4",
+    "@wdio/types": "7.20.7",
+    "type-fest": "2.17.0"
   },
   "engines": {
-    "node": ">=12",
+    "node": ">=14",
     "npm": ">=6"
   },
-  "types": "./build/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "5482c921bc187ed8807922c00bd2355585f4971a",
-  "dependencies": {
-    "@appium/schema": "^0.0.5"
-  }
+  "gitHead": "f6e6d7234e7fe92f989f4e37a71007044985dedf"
 }