@appium/types 0.10.0 → 0.10.2

package/lib/http.ts

@@ -0,0 +1,31 @@
+/**
+ * An object of HTTP headers.
+ */
+export type HTTPHeaders = Record<string, string | string[] | number | boolean | null>;
+
+/**
+ * Possible HTTP methods, as stolen from `axios`.
+ *
+ * @see https://npm.im/axios
+ */
+export type HTTPMethod =
+  | 'get'
+  | 'GET'
+  | 'delete'
+  | 'DELETE'
+  | 'head'
+  | 'HEAD'
+  | 'options'
+  | 'OPTIONS'
+  | 'post'
+  | 'POST'
+  | 'put'
+  | 'PUT'
+  | 'patch'
+  | 'PATCH'
+  | 'purge'
+  | 'PURGE'
+  | 'link'
+  | 'LINK'
+  | 'unlink'
+  | 'UNLINK';

package/lib/index.ts

@@ -1,220 +1,12 @@
-import type {Express} from 'express';
-import type {Server} from 'http';
-import type {Socket} from 'net';
-import type {Logger} from 'npmlog';
-import type {Class as _Class, ConditionalPick, MultidimensionalReadonlyArray} from 'type-fest';
-import type {Server as WSServer} from 'ws';
-import {ServerArgs} from './config';
-import {Driver} from './driver';
-import {Plugin, PluginCommand} from './plugin';
-
+export * from './command';
 export * from './action';
 export * from './appium-config';
 export * from './capabilities';
 export * from './config';
-export {BASE_DESIRED_CAP_CONSTRAINTS} from './constraints';
-export type {BaseDriverCapConstraints} from './constraints';
+export * from './constraints';
 export * from './driver';
 export * from './plugin';
-
-/**
- * Utility type for a object with string-only props
- */
-export type StringRecord = Record<string, any>;
-
-/**
- * A log prefix for {@linkcode AppiumLogger}
- *
- * If a function, the function will return the prefix.  Log messages will be prefixed with this value.
- */
-export type AppiumLoggerPrefix = string | (() => string);
-
-/**
- * Possible "log levels" for {@linkcode AppiumLogger}.
- *
- * Extracted from `npmlog`.
- */
-export type AppiumLoggerLevel = 'silly' | 'verbose' | 'debug' | 'info' | 'http' | 'warn' | 'error';
-
-/**
- * Describes the `npmlog`-based internal logger.
- *
- * @see https://npm.im/npmlog
- */
-export interface AppiumLogger {
-  /**
-   * Returns the underlying `npmlog` {@link Logger}.
-   */
-  unwrap(): Logger;
-  level: AppiumLoggerLevel;
-  levels: AppiumLoggerLevel[];
-  /**
-   * Log prefix, if applicable.
-   */
-  prefix?: AppiumLoggerPrefix;
-  debug(...args: any[]): void;
-  info(...args: any[]): void;
-  warn(...args: any[]): void;
-  error(...args: any[]): void;
-  verbose(...args: any[]): void;
-  silly(...args: any[]): void;
-  http(...args: any[]): void;
-  errorAndThrow(...args: any[]): never;
-}
-
-/**
- * Appium's slightly-modified {@linkcode Server http.Server}.
- */
-export type AppiumServer = Omit<Server, 'close'> & AppiumServerExtension;
-
-export interface AppiumServerExtension {
-  close(): Promise<void>;
-  addWebSocketHandler(handlerPathname: string, handlerServer: WSServer): Promise<void>;
-  removeWebSocketHandler(handlerPathname: string): Promise<boolean>;
-  removeAllWebSocketHandlers(): Promise<boolean>;
-  getWebSocketHandlers(keysFilter: string | null | undefined): Promise<Record<string, WSServer>>;
-  webSocketsMapping: Record<string, WSServer>;
-}
-
-export interface AppiumServerSocket extends Socket {
-  _openReqCount: number;
-}
-
-/**
- * The definition of an extension method, which will be provided via Appium's API.
- *
- */
-export interface MethodDef<Ext extends Plugin | Driver> {
-  /**
-   * Name of the command.
-   */
-  readonly command?: keyof ConditionalPick<
-    Required<Ext>,
-    Ext extends Plugin ? PluginCommand : Ext extends Driver ? DriverCommand : never
-  >;
-  /**
-   * If true, this `Method` will never proxy.
-   */
-  readonly neverProxy?: boolean;
-  /**
-   * Specifies shape of payload
-   */
-  readonly payloadParams?: PayloadParams;
-}
-
-export interface ExecuteMethodDef<Ext extends Driver | Plugin> {
-  command: keyof ConditionalPick<
-    Required<Ext>,
-    Ext extends Plugin ? PluginCommand : Ext extends Driver ? DriverCommand : never
-  >;
-  params?: {
-    required?: ReadonlyArray<string>;
-    optional?: ReadonlyArray<string>;
-  };
-}
-export type ExecuteMethodMap<Ext extends Driver | Plugin> = Readonly<
-  Record<string, Readonly<ExecuteMethodDef<Ext>>>
->;
-
-/**
- * An instance method of a driver class, whose name may be referenced by {@linkcode MethodDef.command}, and serves as an Appium command.
- *
- * Note that this signature differs from a `PluginCommand`.
- */
-export type DriverCommand<TArgs = any, TRetval = unknown> = (...args: TArgs[]) => Promise<TRetval>;
-
-/**
- * Defines the shape of a payload for a {@linkcode MethodDef}.
- */
-export interface PayloadParams {
-  wrap?: string;
-  unwrap?: string;
-  required?: ReadonlyArray<string> | MultidimensionalReadonlyArray<string, 2>;
-  optional?: ReadonlyArray<string> | MultidimensionalReadonlyArray<string, 2>;
-  validate?: (obj: any, protocol: string) => boolean | string | undefined;
-  makeArgs?: (obj: any) => any;
-}
-/**
- * A mapping of URL paths to HTTP methods to {@linkcode MethodDef}s.
- */
-export type MethodMap<Ext extends Plugin | Driver> = Readonly<
-  Record<
-    string,
-    {
-      GET?: MethodDef<Ext>;
-      POST?: MethodDef<Ext>;
-      DELETE?: MethodDef<Ext>;
-    }
-  >
->;
-
-/**
- * Wraps {@linkcode _Class `type-fest`'s `Class`} to include static members.
- */
-export type Class<
-  Proto,
-  StaticMembers extends object = {},
-  Args extends unknown[] = any[]
-> = _Class<Proto, Args> & StaticMembers;
-
-/**
- * The string referring to a "driver"-type extension
- */
-export type DriverType = 'driver';
-
-/**
- * The string referring to a "plugin"-type extension
- *
- */
-export type PluginType = 'plugin';
-
-/**
- * The strings referring to all extension types.
- */
-export type ExtensionType = DriverType | PluginType;
-
-/**
- * Optionally updates an Appium express app and http server, by calling
- * methods that may mutate those objects. For example, you could call:
- *
- * `expressApp.get('/foo', handler)`
- *
- * In order to add a new route to Appium with this plugin. Or, you could add
- * new listeners to the httpServer object.
- *
- * @param expressApp - the Express 'app' object used by Appium for route handling
- * @param httpServer - the node HTTP server that hosts the app
- * @param cliArgs - Arguments from config files, CLI, etc.
- */
-export type UpdateServerCallback = (
-  expressApp: Express,
-  httpServer: AppiumServer,
-  cliArgs: Partial<ServerArgs>
-) => Promise<void>;
-
-/**
- * Possible HTTP methods, as stolen from `axios`.
- *
- * @see https://npm.im/axios
- */
-export type HTTPMethod =
-  | 'get'
-  | 'GET'
-  | 'delete'
-  | 'DELETE'
-  | 'head'
-  | 'HEAD'
-  | 'options'
-  | 'OPTIONS'
-  | 'post'
-  | 'POST'
-  | 'put'
-  | 'PUT'
-  | 'patch'
-  | 'PATCH'
-  | 'purge'
-  | 'PURGE'
-  | 'link'
-  | 'LINK'
-  | 'unlink'
-  | 'UNLINK';
+export * from './http';
+export * from './util';
+export * from './server';
+export * from './logger';

package/lib/logger.ts

@@ -0,0 +1,41 @@
+import type {Logger} from 'npmlog';
+
+/**
+ * A log prefix for {@linkcode AppiumLogger}
+ *
+ * If a function, the function will return the prefix.  Log messages will be prefixed with this value.
+ */
+export type AppiumLoggerPrefix = string | (() => string);
+
+/**
+ * Possible "log levels" for {@linkcode AppiumLogger}.
+ *
+ * Extracted from `npmlog`.
+ */
+export type AppiumLoggerLevel = 'silly' | 'verbose' | 'debug' | 'info' | 'http' | 'warn' | 'error';
+
+/**
+ * Describes the `npmlog`-based internal logger.
+ *
+ * @see https://npm.im/npmlog
+ */
+export interface AppiumLogger {
+  /**
+   * Returns the underlying `npmlog` {@link Logger}.
+   */
+  unwrap(): Logger;
+  level: AppiumLoggerLevel;
+  levels: AppiumLoggerLevel[];
+  /**
+   * Log prefix, if applicable.
+   */
+  prefix?: AppiumLoggerPrefix;
+  debug(...args: any[]): void;
+  info(...args: any[]): void;
+  warn(...args: any[]): void;
+  error(...args: any[]): void;
+  verbose(...args: any[]): void;
+  silly(...args: any[]): void;
+  http(...args: any[]): void;
+  errorAndThrow(...args: any[]): never;
+}

package/lib/plugin.ts

@@ -1,5 +1,9 @@
-import {AppiumLogger, Class, ExecuteMethodMap, MethodMap, UpdateServerCallback} from '.';
-import {ExternalDriver} from './driver';
+import {AsyncReturnType} from 'type-fest';
+import {ExecuteMethodMap, MethodMap} from './command';
+import {DriverCommand, ExternalDriver} from './driver';
+import {AppiumLogger} from './logger';
+import {UpdateServerCallback} from './server';
+import {Class, StringRecord} from './util';
 
 /**
  * The interface describing the constructor and static properties of a Plugin.
@@ -24,6 +28,33 @@ export interface PluginStatic<P extends Plugin> {
   executeMethodMap?: ExecuteMethodMap<P>;
 }
 
+/**
+ * This utility type can presently be used by Plugin authors to mark a method in their plugin as one
+ * which overrides a method in a Driver.
+ * @privateRemarks This would work well as a decorator. May want to accept a type arg for `Driver`
+ * and use a string method name to lookup the method instead.
+ * @example
+ *
+ * class MyPlugin extends BasePlugin implements Plugin {
+ *   public getPageSource: DriverCommandToPluginCommand<
+ *     ExternalDriver['getPageSource'], // method to override
+ *     [flag: boolean], // new arguments; defaults to the args of the method
+ *     string|Buffer, // new return type; defaults to the async return type of the method
+ *     string // async return type of `next()`
+ *   > = async function (next, driver, flag = boolean) {
+ *     const source = await next();
+ *     return flag ? source : Buffer.from(source);
+ *   }
+ * }
+ *
+ */
+export type DriverCommandToPluginCommand<
+  DC extends DriverCommand,
+  TArgs extends readonly any[] = Parameters<DC>,
+  TReturn = AsyncReturnType<DC>,
+  NextRetval = unknown
+> = PluginCommand<ExternalDriver, TArgs, TReturn, NextRetval>;
+
 /**
  * An instance of a "plugin" extension.
  *
@@ -69,7 +100,7 @@ export interface Plugin {
  * `driver._eventHistory.commands.push({cmd: cmdName, startTime, endTime})` --
  * after running plugin logic
  */
-export type NextPluginCallback = () => Promise<void>;
+export type NextPluginCallback<T = unknown> = () => Promise<T>;
 
 /**
  * Implementation of a command within a plugin
@@ -79,8 +110,9 @@ export type NextPluginCallback = () => Promise<void>;
 export type PluginCommand<
   D extends ExternalDriver = ExternalDriver,
   TArgs extends readonly any[] = any[],
-  TReturn = any
-> = (next: NextPluginCallback, driver: D, ...args: TArgs) => Promise<TReturn>;
+  TReturn = unknown,
+  NextReturn = unknown
+> = (next: NextPluginCallback<NextReturn>, driver: D, ...args: TArgs) => Promise<TReturn>;
 
 /**
  * Mainly for internal use.
@@ -90,5 +122,5 @@ export type PluginCommand<
 export type PluginClass<P extends Plugin = Plugin> = Class<
   P,
   PluginStatic<P>,
-  [pluginName: string, cliArgs: Record<string, unknown>]
+  [pluginName: string, cliArgs: StringRecord<unknown>]
 >;

package/lib/server.ts

@@ -0,0 +1,73 @@
+import type {Express} from 'express';
+import type {Server as WSServer} from 'ws';
+import type {Server as HTTPServer} from 'node:http';
+import type {Socket} from 'node:net';
+import {ServerArgs} from './config';
+
+/**
+ * Appium's slightly-modified {@linkcode HTTPServer http.Server}.
+ */
+export type AppiumServer = Omit<HTTPServer, 'close'> & AppiumServerExtension;
+
+export interface AppiumServerExtension {
+  close(): Promise<void>;
+  /**
+   * Adds websocket handler to an {@linkcode AppiumServer}.
+   * @param handlerPathname - Web socket endpoint path starting with a single slash character. It is recommended to always prepend `/ws` to all web socket pathnames.
+   * @param handlerServer - WebSocket server instance. See https://github.com/websockets/ws/pull/885 for more details on how to configure the handler properly.
+   */
+  addWebSocketHandler(
+    this: AppiumServer,
+    handlerPathname: string,
+    handlerServer: WSServer
+  ): Promise<void>;
+  /**
+   * Removes existing WebSocket handler from the server instance.
+   *
+   * The call is ignored if the given `handlerPathname` handler is not present in the handlers list.
+   * @param handlerPathname - WebSocket endpoint path
+   * @returns `true` if the `handlerPathname` was found and deleted; `false` otherwise.
+   */
+  removeWebSocketHandler(this: AppiumServer, handlerPathname: string): Promise<boolean>;
+  /**
+   * Removes all existing WebSocket handlers from the server instance.
+   * @returns `true` if at least one handler was deleted; `false` otherwise.
+   */
+  removeAllWebSocketHandlers(this: AppiumServer): Promise<boolean>;
+  /**
+   * Returns web socket handlers registered for the given server
+   * instance.
+   * @param keysFilter - Only include pathnames with given value if set. All pairs will be included by default.
+   * @returns Pathnames to WS server instances mapping matching the search criteria, if any found.
+   */
+  getWebSocketHandlers(
+    this: AppiumServer,
+    keysFilter?: string | null
+  ): Promise<Record<string, WSServer>>;
+  webSocketsMapping: Record<string, WSServer>;
+}
+
+export interface AppiumServerSocket extends Socket {
+  _openReqCount: number;
+}
+
+export {WSServer};
+
+/**
+ * Optionally updates an Appium express app and http server, by calling
+ * methods that may mutate those objects. For example, you could call:
+ *
+ * `expressApp.get('/foo', handler)`
+ *
+ * In order to add a new route to Appium with this plugin. Or, you could add
+ * new listeners to the httpServer object.
+ *
+ * @param expressApp - the Express 'app' object used by Appium for route handling
+ * @param httpServer - the node HTTP server that hosts the app
+ * @param cliArgs - Arguments from config files, CLI, etc.
+ */
+export type UpdateServerCallback = (
+  expressApp: Express,
+  httpServer: AppiumServer,
+  cliArgs: Partial<ServerArgs>
+) => Promise<void>;

package/lib/util.ts

@@ -0,0 +1,74 @@
+import type {Class as _Class} from 'type-fest';
+
+/**
+ * Utility type for a object with string-only props
+ */
+export type StringRecord<T = any> = Record<string, T>;
+
+/**
+ * Wraps {@linkcode _Class `type-fest`'s `Class`} to include static members.
+ */
+export type Class<
+  Proto,
+  StaticMembers extends object = object,
+  Args extends unknown[] = any[]
+> = _Class<Proto, Args> & StaticMembers;
+
+/**
+ * The string referring to a "driver"-type extension
+ */
+export type DriverType = 'driver';
+
+/**
+ * The string referring to a "plugin"-type extension
+ *
+ */
+export type PluginType = 'plugin';
+
+/**
+ * The strings referring to all extension types.
+ */
+export type ExtensionType = DriverType | PluginType;
+
+/**
+ * Converts a kebab-cased string into a camel-cased string.
+ */
+export type KebabToCamel<S extends string> = S extends `${infer P1}-${infer P2}${infer P3}`
+  ? `${Lowercase<P1>}${Uppercase<P2>}${KebabToCamel<P3>}`
+  : Lowercase<S>;
+
+/**
+ * Converts an object with kebab-cased keys into camel-cased keys.
+ */
+export type ObjectToCamel<T> = {
+  [K in keyof T as KebabToCamel<string & K>]: T[K] extends Record<string, any>
+    ? KeysToCamelCase<T[K]>
+    : T[K];
+};
+
+/**
+ * Converts an object or array to have camel-cased keys.
+ */
+export type KeysToCamelCase<T> = {
+  [K in keyof T as KebabToCamel<string & K>]: T[K] extends Array<any>
+    ? KeysToCamelCase<T[K][number]>[]
+    : ObjectToCamel<T[K]>;
+};
+
+/**
+ * Object `B` has all the keys as object `A` (even if those keys in `A` are otherwise optional).
+ */
+export type Associated<A extends object, B extends {[key in keyof Required<A>]: unknown}> = {
+  [Prop in keyof Required<A>]: B[Prop];
+};
+
+/**
+ * Given `string` `T`, this is a case-insensitive version of `T`.
+ */
+export type AnyCase<T extends string> = string extends T
+  ? string
+  : T extends `${infer F1}${infer F2}${infer R}`
+  ? `${Uppercase<F1> | Lowercase<F1>}${Uppercase<F2> | Lowercase<F2>}${AnyCase<R>}`
+  : T extends `${infer F}${infer R}`
+  ? `${Uppercase<F> | Lowercase<F>}${AnyCase<R>}`
+  : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/types",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Various type declarations used across Appium",
   "keywords": [
     "automation",
@@ -34,15 +34,16 @@
   "scripts": {
     "build": "node ./scripts/generate-schema-types.js",
     "clean": "git checkout -- ./types/lib/appium-config.ts || true",
-    "test:smoke": "node ./index.js"
+    "test:smoke": "node ./index.js",
+    "test:types": "tsd"
   },
   "dependencies": {
-    "@appium/schema": "^0.2.5",
+    "@appium/schema": "^0.2.6",
     "@appium/tsconfig": "^0.2.4",
     "@types/express": "4.17.17",
     "@types/npmlog": "4.1.4",
     "@types/ws": "8.5.4",
-    "type-fest": "3.6.0"
+    "type-fest": "3.7.1"
   },
   "engines": {
     "node": "^14.17.0 || ^16.13.0 || >=18.0.0",
@@ -51,7 +52,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7b4935632222123a4fa7422461f6312f1f0dfbe4",
+  "gitHead": "d514ebdd7ebd27bb236509d0a3d580f0f18a34e5",
   "typedoc": {
     "entryPoint": "./lib/index.ts"
   }