@appium/types 0.4.1 → 0.5.0

package/lib/driver.ts

@@ -2,14 +2,17 @@ import type {EventEmitter} from 'events';
 import {Element, ActionSequence} from './action';
 import {
   HTTPMethod,
-  Capabilities,
   AppiumServer,
   UpdateServerCallback,
   Class,
   MethodMap,
   AppiumLogger,
+  StringRecord,
+  ConstraintsToCaps,
+  BaseDriverCapConstraints,
+  W3CCapabilities,
+  Capabilities,
 } from '.';
-import {W3CCapabilities} from './capabilities';
 import {ServerArgs} from './config';
 
 export interface TimeoutCommands {
@@ -46,24 +49,30 @@ export interface SessionCommands {
 }
 
 export interface ExecuteCommands {
-  executeMethod(script: string, args: [Record<string, any>]|[]): Promise<any>;
+  executeMethod(script: string, args: [StringRecord] | []): Promise<any>;
 }
 
 export interface ExecuteMethodDef {
-  command: string,
+  command: string;
   params?: {
-    required?: string[],
-    optional?: string[],
-  }
-};
+    required?: string[];
+    optional?: string[];
+  };
+}
 export type ExecuteMethodMap = Record<string, ExecuteMethodDef>;
 
-export interface MultiSessionData {
+export interface MultiSessionData<
+  C extends Constraints = BaseDriverCapConstraints,
+  Extra extends StringRecord | void = void
+> {
   id: string;
-  capabilities: Capabilities;
+  capabilities: Capabilities<C, Extra>;
 }
 
-export type SingularSessionData = Capabilities & {events?: EventHistory};
+export type SingularSessionData<
+  C extends Constraints = BaseDriverCapConstraints,
+  Extra extends StringRecord | void = void
+> = Capabilities<C, Extra> & {events?: EventHistory; error?: string};
 
 export interface FindCommands {
   findElement(strategy: string, selector: string): Promise<Element>;
@@ -106,15 +115,20 @@ export interface LogCommands {
 }
 
 export interface SettingsCommands {
-  updateSettings: (settings: Record<string, any>) => Promise<void>;
-  getSettings(): Promise<Record<string, any>>;
+  updateSettings: (settings: StringRecord) => Promise<void>;
+  getSettings(): Promise<StringRecord>;
 }
 
-export interface SessionHandler<CreateResult, DeleteResult> {
+export interface SessionHandler<
+  CreateResult,
+  DeleteResult,
+  C extends Constraints = BaseDriverCapConstraints,
+  Extra extends StringRecord | void = void
+> {
   createSession(
-    w3cCaps1: W3CCapabilities,
-    w3cCaps2?: W3CCapabilities,
-    w3cCaps?: W3CCapabilities,
+    w3cCaps1: W3CCapabilities<C, Extra>,
+    w3cCaps2?: W3CCapabilities<C, Extra>,
+    w3cCaps?: W3CCapabilities<C, Extra>,
     driverData?: DriverData[]
   ): Promise<CreateResult>;
 
@@ -140,24 +154,24 @@ export type DriverData = Record<string, unknown>;
  * }
  */
 export interface Constraint {
-  presence?: boolean | {allowEmpty: boolean};
-  isString?: boolean;
-  isNumber?: boolean;
-  isBoolean?: boolean;
-  isObject?: boolean;
-  isArray?: boolean;
-  deprecated?: boolean;
-  inclusion?: any[];
-  inclusionCaseInsensitive?: any[];
+  readonly presence?: boolean | Readonly<{allowEmpty: boolean}>;
+  readonly isString?: boolean;
+  readonly isNumber?: boolean;
+  readonly isBoolean?: boolean;
+  readonly isObject?: boolean;
+  readonly isArray?: boolean;
+  readonly deprecated?: boolean;
+  readonly inclusion?: Readonly<[any, ...any[]]>;
+  readonly inclusionCaseInsensitive?: Readonly<[any, ...any[]]>;
 }
-export type Constraints = Record<string, Constraint>;
+export type Constraints = Readonly<Record<string, Constraint>>;
 
-export interface DriverHelpers {
+export interface DriverHelpers<C extends Constraints> {
   configureApp: (app: string, supportedAppExtensions: string[]) => Promise<string>;
   isPackageOrBundle: (app: string) => boolean;
   duplicateKeys: <T>(input: T, firstKey: string, secondKey: string) => T;
   parseCapsArray: (cap: string | string[]) => string[];
-  generateDriverLogPrefix: (obj: Core, sessionId?: string) => string;
+  generateDriverLogPrefix: (obj: Core<C>, sessionId?: string) => string;
 }
 
 export type SettingsUpdateListener<T extends Record<string, unknown> = Record<string, unknown>> = (
@@ -267,15 +281,13 @@ export interface EventHistoryCommand {
  *
  * This should not be used directly by external code.
  */
-export interface Core {
+export interface Core<C extends Constraints = BaseDriverCapConstraints> {
   shouldValidateCaps: boolean;
   sessionId: string | null;
-  opts: DriverOpts;
+  opts: DriverOpts<C>;
   initialOpts: ServerArgs;
-  caps?: Capabilities;
-  originalCaps?: W3CCapabilities;
   protocol?: string;
-  helpers: DriverHelpers;
+  helpers: DriverHelpers<C>;
   basePath: string;
   relaxedSecurityEnabled: boolean;
   allowInsecure: string[];
@@ -306,32 +318,36 @@ export interface Core {
   getManagedDrivers(): Driver[];
   clearNewCommandTimeout(): Promise<void>;
   logEvent(eventName: string): void;
-  driverForSession(sessionId: string): Core | null;
+  driverForSession(sessionId: string): Core<C> | null;
 }
 
 /**
  * `BaseDriver` implements this.  It contains default behavior;
  * external drivers are expected to implement {@linkcode ExternalDriver} instead.
  */
-export interface Driver
-  extends SessionCommands,
+export interface Driver<
+  C extends Constraints = BaseDriverCapConstraints,
+  A extends StringRecord = StringRecord
+> extends SessionCommands,
     LogCommands,
     FindCommands,
     SettingsCommands,
     TimeoutCommands,
     EventCommands,
-    SessionHandler<[string, any], void>,
+    SessionHandler<[string, any], void, C>,
     ExecuteCommands,
     Core {
-  cliArgs?: Record<string, any>;
+  cliArgs?: A;
   // The following methods are implemented by `BaseDriver`.
   executeCommand(cmd: string, ...args: any[]): Promise<any>;
   startUnexpectedShutdown(err?: Error): Promise<void>;
   startNewCommandTimeout(): Promise<void>;
   reset(): Promise<void>;
-  desiredCapConstraints: Constraints;
-  validateDesiredCaps(caps: Capabilities): boolean;
-  logExtraCaps(caps: Capabilities): void;
+  caps?: Capabilities<C>;
+  originalCaps?: W3CCapabilities<C>;
+  desiredCapConstraints: C;
+  validateDesiredCaps(caps: Capabilities<C>): boolean;
+  logExtraCaps(caps: Capabilities<C>): void;
   assignServer?(server: AppiumServer, host: string, port: number, path: string): void;
 }
 
@@ -581,12 +597,18 @@ export type DriverClass<
   S extends DriverStatic = DriverStatic
 > = Class<D, S, [] | [Partial<ServerArgs>] | [Partial<ServerArgs>, boolean]>;
 
+export interface ExtraDriverOpts {
+  fastReset?: boolean;
+  skipUninstall?: boolean;
+}
 /**
  * Options as passed into a driver constructor, which is just a union of {@linkcode ServerArgs} and {@linkcode Capabilities}.
  *
  * The combination happens within Appium prior to calling the constructor.
  */
-export type DriverOpts = ServerArgs & Capabilities;
+export type DriverOpts<C extends Constraints = BaseDriverCapConstraints> = ServerArgs &
+  ExtraDriverOpts &
+  Partial<ConstraintsToCaps<C>>;
 
 export type DriverCommand<TArgs = any, TReturn = unknown> = (...args: TArgs[]) => Promise<TReturn>;
 

package/lib/index.ts

@@ -3,7 +3,6 @@ import type {Socket} from 'net';
 import type {Server} from 'http';
 import type {Class as _Class, ConditionalPick, MultidimensionalReadonlyArray} from 'type-fest';
 import {ServerArgs} from './config';
-import {Capabilities, W3CCapabilities} from './capabilities';
 import type {Express} from 'express';
 import {ExternalDriver} from './driver';
 import type {Logger} from 'npmlog';
@@ -11,10 +10,12 @@ import type {Logger} from 'npmlog';
 export * from './driver';
 export * from './action';
 export * from './plugin';
-export {AppiumW3CCapabilities} from './capabilities';
-export {AppiumConfig, NormalizedAppiumConfig} from './config';
+export * from './capabilities';
+export * from './constraints';
+export * from './config';
 export * from './appium-config';
-export {ServerArgs, Capabilities, W3CCapabilities};
+
+export type StringRecord = Record<string, any>;
 
 /**
  * A log prefix for {@linkcode AppiumLogger}
@@ -63,15 +64,10 @@ export type AppiumServer = Omit<Server, 'close'> & AppiumServerExtension;
 
 export interface AppiumServerExtension {
   close(): Promise<void>;
-  addWebSocketHandler(
-    handlerPathname: string,
-    handlerServer: WSServer
-  ): 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>>;
+  getWebSocketHandlers(keysFilter: string | null | undefined): Promise<Record<string, WSServer>>;
   webSocketsMapping: Record<string, WSServer>;
 }
 
@@ -164,8 +160,11 @@ export type ExtensionType = DriverType | PluginType;
  * @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: ServerArgs) => Promise<void>;
-
+export type UpdateServerCallback = (
+  expressApp: Express,
+  httpServer: AppiumServer,
+  cliArgs: ServerArgs
+) => Promise<void>;
 
 /**
  * Possible HTTP methods, as stolen from `axios`.
@@ -173,14 +172,23 @@ export type UpdateServerCallback = (expressApp: Express, httpServer: AppiumServe
  * @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';
-
+  | 'get'
+  | 'GET'
+  | 'delete'
+  | 'DELETE'
+  | 'head'
+  | 'HEAD'
+  | 'options'
+  | 'OPTIONS'
+  | 'post'
+  | 'POST'
+  | 'put'
+  | 'PUT'
+  | 'patch'
+  | 'PATCH'
+  | 'purge'
+  | 'PURGE'
+  | 'link'
+  | 'LINK'
+  | 'unlink'
+  | 'UNLINK';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/types",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Various type declarations used across Appium",
   "keywords": [
     "appium",
@@ -23,6 +23,7 @@
     "build",
     "lib"
   ],
+  "main": "./build/index.js",
   "scripts": {
     "build": "node ./scripts/generate-schema-types.js",
     "dev": "npm run build -- --watch",
@@ -33,11 +34,11 @@
   },
   "dependencies": {
     "@appium/schema": "^0.0.9",
-    "@types/express": "4.17.13",
+    "@types/express": "4.17.14",
     "@types/npmlog": "4.1.4",
     "@types/ws": "8.5.3",
-    "@wdio/types": "7.24.0",
-    "type-fest": "2.19.0"
+    "@wdio/types": "7.25.1",
+    "type-fest": "3.1.0"
   },
   "engines": {
     "node": ">=14",
@@ -46,5 +47,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "c26af8f85230ac65cbc19f08f763942f74b0eb0c"
+  "gitHead": "f545a6cde58d83f3289072f8957468793947ba66"
 }