@appium/types - npm Package Compare versions

Comparing version 0.4.1 to 0.5.0

build/capabilities.d.ts

 import type { Capabilities as WdioCaps } from '@wdio/types';
+import { StringRecord, Constraint, Constraints } from '.';
+import { BaseDriverCapConstraints } from './constraints';
+export declare type StandardCapabilities = WdioCaps.Capabilities;
+export declare type W3C_APPIUM_PREFIX = 'appium';
 /**
- * The mask of a W3C-style namespaced capability proped name.
+ * Base capabilities as derived from {@linkcode BaseDriverCapConstraints}.
  */
-declare type Namespaced = `${string}:${string}`;
+export declare type BaseCapabilities = ConstraintsToCaps<BaseDriverCapConstraints>;
 /**
- * An object with keys conforming to {@linkcode Namespaced}.
+ * Like {@linkcode BaseCapabilities}, except all Appium-specific keys are namespaced.
  */
-declare type NamespacedRecord = Record<Namespaced, any>;
+export declare type BaseNSCapabilities = CapsToNSCaps<ConstraintsToCaps<BaseDriverCapConstraints>>;
 /**
- * An object with keys for strings.
+ * These may (or should) be reused by drivers.
  */
-declare type StringRecord = Record<string, any>;
+export declare type AppiumAndroidCapabilities = WdioCaps.AppiumAndroidCapabilities;
+export declare type AppiumIOSCapabilities = WdioCaps.AppiumIOSCapabilities;
+export declare type AppiumXCUICommandTimeouts = WdioCaps.AppiumXCUICommandTimeouts;
+export declare type AppiumXCUIProcessArguments = WdioCaps.AppiumXCUIProcessArguments;
+export declare type AppiumXCUISafariGlobalPreferences = WdioCaps.AppiumXCUISafariGlobalPreferences;
+export declare type AppiumXCUITestCapabilities = WdioCaps.AppiumXCUITestCapabilities;
 /**
- * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type, accepting additional optional caps.
- * All properties are optional.
+ * Given a {@linkcode Constraint} `C` and a type `T`, see if `inclusion`/`inclusionCaseInsensitive` is present, and create a union of its allowed literals; otherwise just use `T`.
  */
-declare type BaseCapabilities<OptionalCaps extends StringRecord = StringRecord> = Partial<WdioCaps.Capabilities & OptionalCaps>;
+declare type ConstraintChoice<C extends Constraint, T> = C['inclusionCaseInsensitive'] extends ReadonlyArray<T> ? AnyCase<C['inclusionCaseInsensitive'][number]> : C['inclusion'] extends ReadonlyArray<T> ? C['inclusion'][number] : T;
 /**
- * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type and wdio's {@linkcode WdioCaps.AppiumCapabilities} type, accepting additional optional caps.
+ * Given {@linkcode Constraint} `C`, determine the associated type of the capability.
  *
- * In practice, the properties `platformName` and `automationName` are required by Appium.
+ * Notes:
+ *
+ * - Only `number` and `string` values can have "choices" (`inclusion`/`inclusionCaseInesnsitive`) associated with them.
+ * - If `isArray` is `true`, the type is always of type `string[]`. If this is incorrect, then it will be `any[]`.
+ * - There is no way to express the shape of an object if `ifObject` is `true`.
  */
-export declare type Capabilities<OptionalCaps extends StringRecord = StringRecord> = BaseCapabilities<WdioCaps.AppiumCapabilities & OptionalCaps>;
+declare type ConstraintToCapKind<C extends Constraint> = C['isString'] extends true ? ConstraintChoice<C, string> : C['isNumber'] extends true ? ConstraintChoice<C, number> : C['isBoolean'] extends true ? boolean : C['isArray'] extends true ? string[] : C['isObject'] extends true ? object : any;
 /**
- * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type and wdio's {@linkcode WdioCaps.AppiumW3CCapabilities} type, accepting additional optional _namespaced_ caps.
+ * Given {@linkcode Constraint} `C`, determine if it is required or optional.
+ *
+ * In practice, _all_ capabilities are considered optional per types, but various errors might be thrown if some are not present.
  */
-export declare type AppiumW3CCapabilities<OptionalNamespacedCaps extends NamespacedRecord = NamespacedRecord> = BaseCapabilities<WdioCaps.AppiumW3CCapabilities & OptionalNamespacedCaps>;
+export declare type ConstraintToCap<C extends Constraint> = C['presence'] extends true | {
+    allowEmpty: boolean;
+} ? ConstraintToCapKind<C> : ConstraintToCapKind<C> | undefined;
 /**
- * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type and wdio's {@linkcode WdioCaps.AppiumW3Capabilities} type, accepting additional optional _namespaced_ caps, in W3C-compatible format (`alwaysMatch`/`firstMatch`).
- * In practice, the properties `appium:platformName` and `appium:automationName` are required by Appium _somewhere_ in this object; this cannot be expressed in TypeScript.
+ * Given `string` `T`, this is a case-insensitive version of `T`.
  */
-export declare type W3CCapabilities<OptionalNamespacedCaps extends NamespacedRecord = NamespacedRecord> = {
-    alwaysMatch: AppiumW3CCapabilities<OptionalNamespacedCaps>;
-    firstMatch: AppiumW3CCapabilities<OptionalNamespacedCaps>[];
+export declare 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>}` : '';
+/**
+ * Given {@linkcode StringRecord} `T` and namespace string `NS`, a type with the key names prefixed by `${NS}:` _except_ for standard capabilities.  `NS` defaults to `appium`.
+ *
+ * If `T` is already namespaced, well, it'll get _double_-namespaced.
+ */
+export declare type CapsToNSCaps<T extends StringRecord, NS extends string = W3C_APPIUM_PREFIX> = {
+    [K in keyof T as K extends keyof StandardCapabilities ? K : NamespacedString<K & string, NS>]: T[K];
 };
+export declare type NamespacedString<S extends string, NS extends string = W3C_APPIUM_PREFIX> = `${NS}:${S}`;
 /**
- * These may (or should) be reused by drivers.
+ * Converts {@linkcode Constraint} `C` to a {@linkcode Capabilities} object.
  */
-export declare type AppiumAndroidCapabilities = WdioCaps.AppiumAndroidCapabilities;
-export declare type AppiumIOSCapabilities = WdioCaps.AppiumIOSCapabilities;
-export declare type AppiumXCUICommandTimeouts = WdioCaps.AppiumXCUICommandTimeouts;
-export declare type AppiumXCUIProcessArguments = WdioCaps.AppiumXCUIProcessArguments;
-export declare type AppiumXCUISafariGlobalPreferences = WdioCaps.AppiumXCUISafariGlobalPreferences;
-export declare type AppiumXCUITestCapabilities = WdioCaps.AppiumXCUITestCapabilities;
+export declare type ConstraintsToCaps<C extends Constraints> = {
+    -readonly [K in keyof C]: ConstraintToCap<C[K]>;
+};
+/**
+ * Given some constraints, return the entire set of supported capabilities it supports (including whatever is in its desired caps).
+ *
+ * Does not contain {@linkcode BaseCapabilities}; see {@linkcode DriverCaps}.
+ */
+export declare type Capabilities<C extends Constraints = BaseDriverCapConstraints, Extra extends StringRecord | void = void> = Partial<ConstraintsToCaps<C> & Extra>;
+/**
+ * Like {@linkcode Capabilities}, except W3C-style.
+ *
+ * Does not contain {@linkcode BaseCapabilities}; see {@linkcode W3CDriverCaps}.
+ */
+export declare type W3CCapabilities<C extends Constraints = BaseDriverCapConstraints, Extra extends StringRecord | void = void> = {
+    alwaysMatch: NSCapabilities<C, Extra>;
+    firstMatch: NSCapabilities<C, Extra>[];
+};
+/**
+ * Namespaced caps (where appropriate).
+ *
+ * Does not contain {@linkcode BaseCapabilities}; see {@linkcode NSDriverCaps}.
+ */
+export declare type NSCapabilities<C extends Constraints = BaseDriverCapConstraints, Extra extends StringRecord | void = void, NS extends string = W3C_APPIUM_PREFIX> = Partial<CapsToNSCaps<ConstraintsToCaps<C> & Extra, NS>>;
+/**
+ * Capabilities for drivers extending `BaseDriver`.
+ *
+ * Includes {@linkcode BaseCapabilities}.
+ *
+ * @example
+ * ```ts
+ * class MyDriver extends BaseDriver {
+ *   async createSession (w3ccaps: W3CDriverCaps<MyDriverConstraints>, ...args: any[]) {
+ *     const [
+ *       sessionId: string,
+ *       caps: DriverCaps<MyDriverConstraints>
+ *     ] = await super.createSession(w3ccaps, ...args);
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare type DriverCaps<C extends Constraints, Extra extends StringRecord | void = void> = Capabilities<BaseDriverCapConstraints & C, Extra>;
+/**
+ * W3C-style capabilities for drivers extending `BaseDriver`.
+ *
+ * Includes {@linkcode BaseCapabilities}.
+ *
+ * @example
+ * ```ts
+ * class MyDriver extends BaseDriver {
+ *   async createSession (w3ccaps: W3CDriverCaps<MyDriverConstraints>, ...args: any[]) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare type W3CDriverCaps<C extends Constraints, Extra extends StringRecord | void = void> = W3CCapabilities<BaseDriverCapConstraints & C, Extra>;
+/**
+ * Namespaced capabilities for drivers extending `BaseDriver`.
+ *
+ * Includes {@linkcode BaseCapabilities}.
+ */
+export declare type NSDriverCaps<C extends Constraints, Extra extends StringRecord | void = void> = NSCapabilities<BaseDriverCapConstraints & C, Extra>;
 export {};
 //# sourceMappingURL=capabilities.d.ts.map

build/driver.d.ts

 /// <reference types="node" />
 import type { EventEmitter } from 'events';
 import { Element, ActionSequence } from './action';
-import { HTTPMethod, Capabilities, AppiumServer, UpdateServerCallback, Class, MethodMap, AppiumLogger } from '.';
-import { W3CCapabilities } from './capabilities';
+import { HTTPMethod, AppiumServer, UpdateServerCallback, Class, MethodMap, AppiumLogger, StringRecord, ConstraintsToCaps, BaseDriverCapConstraints, W3CCapabilities, Capabilities } from '.';
 import { ServerArgs } from './config';
@@ -32,3 +31,3 @@ export interface TimeoutCommands {
 export interface ExecuteCommands {
-    executeMethod(script: string, args: [Record<string, any>] | []): Promise<any>;
+    executeMethod(script: string, args: [StringRecord] | []): Promise<any>;
 }
@@ -43,8 +42,9 @@ export interface ExecuteMethodDef {
 export declare 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 declare type SingularSessionData = Capabilities & {
+export declare type SingularSessionData<C extends Constraints = BaseDriverCapConstraints, Extra extends StringRecord | void = void> = Capabilities<C, Extra> & {
     events?: EventHistory;
+    error?: string;
 };
@@ -73,7 +73,7 @@ export interface FindCommands {
 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> {
-    createSession(w3cCaps1: W3CCapabilities, w3cCaps2?: W3CCapabilities, w3cCaps?: W3CCapabilities, driverData?: DriverData[]): Promise<CreateResult>;
+export interface SessionHandler<CreateResult, DeleteResult, C extends Constraints = BaseDriverCapConstraints, Extra extends StringRecord | void = void> {
+    createSession(w3cCaps1: W3CCapabilities<C, Extra>, w3cCaps2?: W3CCapabilities<C, Extra>, w3cCaps?: W3CCapabilities<C, Extra>, driverData?: DriverData[]): Promise<CreateResult>;
     deleteSession(sessionId?: string, driverData?: DriverData[]): Promise<DeleteResult>;
@@ -99,16 +99,16 @@ }
 export interface Constraint {
-    presence?: boolean | {
+    readonly presence?: boolean | Readonly<{
         allowEmpty: boolean;
-    };
-    isString?: boolean;
-    isNumber?: boolean;
-    isBoolean?: boolean;
-    isObject?: boolean;
-    isArray?: boolean;
-    deprecated?: boolean;
-    inclusion?: any[];
-    inclusionCaseInsensitive?: any[];
+    }>;
+    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 declare type Constraints = Record<string, Constraint>;
-export interface DriverHelpers {
+export declare type Constraints = Readonly<Record<string, Constraint>>;
+export interface DriverHelpers<C extends Constraints> {
     configureApp: (app: string, supportedAppExtensions: string[]) => Promise<string>;
@@ -118,3 +118,3 @@ isPackageOrBundle: (app: string) => boolean;
     parseCapsArray: (cap: string | string[]) => string[];
-    generateDriverLogPrefix: (obj: Core, sessionId?: string) => string;
+    generateDriverLogPrefix: (obj: Core<C>, sessionId?: string) => string;
 }
@@ -201,11 +201,9 @@ export declare type SettingsUpdateListener<T extends Record<string, unknown> = Record<string, unknown>> = (prop: keyof T, newValue: unknown, curValue: unknown) => Promise<void>;
  */
-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;
@@ -241,3 +239,3 @@ relaxedSecurityEnabled: boolean;
     logEvent(eventName: string): void;
-    driverForSession(sessionId: string): Core | null;
+    driverForSession(sessionId: string): Core<C> | null;
 }
@@ -248,4 +246,4 @@ /**
  */
-export interface Driver extends SessionCommands, LogCommands, FindCommands, SettingsCommands, TimeoutCommands, EventCommands, SessionHandler<[string, any], void>, ExecuteCommands, Core {
-    cliArgs?: Record<string, any>;
+export interface Driver<C extends Constraints = BaseDriverCapConstraints, A extends StringRecord = StringRecord> extends SessionCommands, LogCommands, FindCommands, SettingsCommands, TimeoutCommands, EventCommands, SessionHandler<[string, any], void, C>, ExecuteCommands, Core {
+    cliArgs?: A;
     executeCommand(cmd: string, ...args: any[]): Promise<any>;
@@ -255,5 +253,7 @@ startUnexpectedShutdown(err?: Error): 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;
@@ -436,2 +436,6 @@ }
 export declare type DriverClass<D extends Driver = ExternalDriver, S extends DriverStatic = DriverStatic> = Class<D, S, [] | [Partial<ServerArgs>] | [Partial<ServerArgs>, boolean]>;
+export interface ExtraDriverOpts {
+    fastReset?: boolean;
+    skipUninstall?: boolean;
+}
 /**
@@ -442,3 +446,3 @@ * Options as passed into a driver constructor, which is just a union of {@linkcode ServerArgs} and {@linkcode Capabilities}.
  */
-export declare type DriverOpts = ServerArgs & Capabilities;
+export declare type DriverOpts<C extends Constraints = BaseDriverCapConstraints> = ServerArgs & ExtraDriverOpts & Partial<ConstraintsToCaps<C>>;
 export declare type DriverCommand<TArgs = any, TReturn = unknown> = (...args: TArgs[]) => Promise<TReturn>;
@@ -445,0 +449,0 @@ export declare type DriverCommands<TArgs = any, TReturn = unknown> = Record<string, DriverCommand<TArgs, TReturn>>;

build/index.d.ts

@@ -8,3 +8,2 @@ /// <reference types="node" />
 import { ServerArgs } from './config';
-import { Capabilities, W3CCapabilities } from './capabilities';
 import type { Express } from 'express';
@@ -16,6 +15,7 @@ import { ExternalDriver } from './driver';
 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 declare type StringRecord = Record<string, any>;
 /**
@@ -22,0 +22,0 @@ * A log prefix for {@linkcode AppiumLogger}

lib/capabilities.ts

 import type {Capabilities as WdioCaps} from '@wdio/types';
+import {StringRecord, Constraint, Constraints} from '.';
+import {BaseDriverCapConstraints} from './constraints';
 
+export type StandardCapabilities = WdioCaps.Capabilities;
+export type W3C_APPIUM_PREFIX = 'appium';
+
 /**
- * The mask of a W3C-style namespaced capability proped name.
+ * Base capabilities as derived from {@linkcode BaseDriverCapConstraints}.
  */
-type Namespaced = `${string}:${string}`;
+export type BaseCapabilities = ConstraintsToCaps<BaseDriverCapConstraints>;
 
 /**
- * An object with keys conforming to {@linkcode Namespaced}.
+ * Like {@linkcode BaseCapabilities}, except all Appium-specific keys are namespaced.
  */
-type NamespacedRecord = Record<Namespaced, any>;
+export type BaseNSCapabilities = CapsToNSCaps<ConstraintsToCaps<BaseDriverCapConstraints>>;
 
 /**
- * An object with keys for strings.
+ * These may (or should) be reused by drivers.
  */
-type StringRecord = Record<string, any>;
+export type AppiumAndroidCapabilities = WdioCaps.AppiumAndroidCapabilities;
+export type AppiumIOSCapabilities = WdioCaps.AppiumIOSCapabilities;
+export type AppiumXCUICommandTimeouts = WdioCaps.AppiumXCUICommandTimeouts;
+export type AppiumXCUIProcessArguments = WdioCaps.AppiumXCUIProcessArguments;
+export type AppiumXCUISafariGlobalPreferences = WdioCaps.AppiumXCUISafariGlobalPreferences;
+export type AppiumXCUITestCapabilities = WdioCaps.AppiumXCUITestCapabilities;
 
 /**
- * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type, accepting additional optional caps.
- * All properties are optional.
+ * Given a {@linkcode Constraint} `C` and a type `T`, see if `inclusion`/`inclusionCaseInsensitive` is present, and create a union of its allowed literals; otherwise just use `T`.
  */
-type BaseCapabilities<OptionalCaps extends StringRecord = StringRecord> = Partial<
-  WdioCaps.Capabilities & OptionalCaps
->;
+type ConstraintChoice<
+  C extends Constraint,
+  T
+> = C['inclusionCaseInsensitive'] extends ReadonlyArray<T>
+  ? AnyCase<C['inclusionCaseInsensitive'][number]>
+  : C['inclusion'] extends ReadonlyArray<T>
+  ? C['inclusion'][number]
+  : T;
 
 /**
- * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type and wdio's {@linkcode WdioCaps.AppiumCapabilities} type, accepting additional optional caps.
+ * Given {@linkcode Constraint} `C`, determine the associated type of the capability.
  *
- * In practice, the properties `platformName` and `automationName` are required by Appium.
+ * Notes:
+ *
+ * - Only `number` and `string` values can have "choices" (`inclusion`/`inclusionCaseInesnsitive`) associated with them.
+ * - If `isArray` is `true`, the type is always of type `string[]`. If this is incorrect, then it will be `any[]`.
+ * - There is no way to express the shape of an object if `ifObject` is `true`.
  */
-export type Capabilities<OptionalCaps extends StringRecord = StringRecord> = BaseCapabilities<
-  WdioCaps.AppiumCapabilities & OptionalCaps
->;
+type ConstraintToCapKind<C extends Constraint> = C['isString'] extends true
+  ? ConstraintChoice<C, string>
+  : C['isNumber'] extends true
+  ? ConstraintChoice<C, number>
+  : C['isBoolean'] extends true
+  ? boolean
+  : C['isArray'] extends true
+  ? string[]
+  : C['isObject'] extends true
+  ? object
+  : any;
 
 /**
- * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type and wdio's {@linkcode WdioCaps.AppiumW3CCapabilities} type, accepting additional optional _namespaced_ caps.
+ * Given {@linkcode Constraint} `C`, determine if it is required or optional.
+ *
+ * In practice, _all_ capabilities are considered optional per types, but various errors might be thrown if some are not present.
  */
-export type AppiumW3CCapabilities<
-  OptionalNamespacedCaps extends NamespacedRecord = NamespacedRecord
-> = BaseCapabilities<WdioCaps.AppiumW3CCapabilities & OptionalNamespacedCaps>;
+export type ConstraintToCap<C extends Constraint> = C['presence'] extends
+  | true
+  | {allowEmpty: boolean}
+  ? ConstraintToCapKind<C>
+  : ConstraintToCapKind<C> | undefined;
 
 /**
- * All known capabilities derived from wdio's {@linkcode WdioCaps.Capabilities Capabilities} type and wdio's {@linkcode WdioCaps.AppiumW3Capabilities} type, accepting additional optional _namespaced_ caps, in W3C-compatible format (`alwaysMatch`/`firstMatch`).
- * In practice, the properties `appium:platformName` and `appium:automationName` are required by Appium _somewhere_ in this object; this cannot be expressed in TypeScript.
+ * Given `string` `T`, this is a case-insensitive version of `T`.
  */
-export type W3CCapabilities<OptionalNamespacedCaps extends NamespacedRecord = NamespacedRecord> = {
-  alwaysMatch: AppiumW3CCapabilities<OptionalNamespacedCaps>;
-  firstMatch: AppiumW3CCapabilities<OptionalNamespacedCaps>[];
+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>}`
+  : '';
+
+/**
+ * Given {@linkcode StringRecord} `T` and namespace string `NS`, a type with the key names prefixed by `${NS}:` _except_ for standard capabilities.  `NS` defaults to `appium`.
+ *
+ * If `T` is already namespaced, well, it'll get _double_-namespaced.
+ */
+export type CapsToNSCaps<T extends StringRecord, NS extends string = W3C_APPIUM_PREFIX> = {
+  [K in keyof T as K extends keyof StandardCapabilities
+    ? K
+    : NamespacedString<K & string, NS>]: T[K];
 };
 
+export type NamespacedString<
+  S extends string,
+  NS extends string = W3C_APPIUM_PREFIX
+> = `${NS}:${S}`;
+
 /**
- * These may (or should) be reused by drivers.
+ * Converts {@linkcode Constraint} `C` to a {@linkcode Capabilities} object.
  */
-export type AppiumAndroidCapabilities = WdioCaps.AppiumAndroidCapabilities;
-export type AppiumIOSCapabilities = WdioCaps.AppiumIOSCapabilities;
-export type AppiumXCUICommandTimeouts = WdioCaps.AppiumXCUICommandTimeouts;
-export type AppiumXCUIProcessArguments = WdioCaps.AppiumXCUIProcessArguments;
-export type AppiumXCUISafariGlobalPreferences = WdioCaps.AppiumXCUISafariGlobalPreferences;
-export type AppiumXCUITestCapabilities = WdioCaps.AppiumXCUITestCapabilities;
+export type ConstraintsToCaps<C extends Constraints> = {
+  -readonly [K in keyof C]: ConstraintToCap<C[K]>;
+};
+
+/**
+ * Given some constraints, return the entire set of supported capabilities it supports (including whatever is in its desired caps).
+ *
+ * Does not contain {@linkcode BaseCapabilities}; see {@linkcode DriverCaps}.
+ */
+export type Capabilities<
+  C extends Constraints = BaseDriverCapConstraints,
+  Extra extends StringRecord | void = void
+> = Partial<ConstraintsToCaps<C> & Extra>;
+
+/**
+ * Like {@linkcode Capabilities}, except W3C-style.
+ *
+ * Does not contain {@linkcode BaseCapabilities}; see {@linkcode W3CDriverCaps}.
+ */
+export type W3CCapabilities<
+  C extends Constraints = BaseDriverCapConstraints,
+  Extra extends StringRecord | void = void
+> = {
+  alwaysMatch: NSCapabilities<C, Extra>;
+  firstMatch: NSCapabilities<C, Extra>[];
+};
+
+/**
+ * Namespaced caps (where appropriate).
+ *
+ * Does not contain {@linkcode BaseCapabilities}; see {@linkcode NSDriverCaps}.
+ */
+export type NSCapabilities<
+  C extends Constraints = BaseDriverCapConstraints,
+  Extra extends StringRecord | void = void,
+  NS extends string = W3C_APPIUM_PREFIX
+> = Partial<CapsToNSCaps<ConstraintsToCaps<C> & Extra, NS>>;
+
+/**
+ * Capabilities for drivers extending `BaseDriver`.
+ *
+ * Includes {@linkcode BaseCapabilities}.
+ *
+ * @example
+ * ```ts
+ * class MyDriver extends BaseDriver {
+ *   async createSession (w3ccaps: W3CDriverCaps<MyDriverConstraints>, ...args: any[]) {
+ *     const [
+ *       sessionId: string,
+ *       caps: DriverCaps<MyDriverConstraints>
+ *     ] = await super.createSession(w3ccaps, ...args);
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+
+export type DriverCaps<
+  C extends Constraints,
+  Extra extends StringRecord | void = void
+> = Capabilities<BaseDriverCapConstraints & C, Extra>;
+
+/**
+ * W3C-style capabilities for drivers extending `BaseDriver`.
+ *
+ * Includes {@linkcode BaseCapabilities}.
+ *
+ * @example
+ * ```ts
+ * class MyDriver extends BaseDriver {
+ *   async createSession (w3ccaps: W3CDriverCaps<MyDriverConstraints>, ...args: any[]) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export type W3CDriverCaps<
+  C extends Constraints,
+  Extra extends StringRecord | void = void
+> = W3CCapabilities<BaseDriverCapConstraints & C, Extra>;
+
+/**
+ * Namespaced capabilities for drivers extending `BaseDriver`.
+ *
+ * Includes {@linkcode BaseCapabilities}.
+ */
+export type NSDriverCaps<
+  C extends Constraints,
+  Extra extends StringRecord | void = void
+> = NSCapabilities<BaseDriverCapConstraints & C, Extra>;

lib/driver.ts

@@ -5,3 +5,2 @@ import type {EventEmitter} from 'events';
   HTTPMethod,
-  Capabilities,
   AppiumServer,
@@ -12,4 +11,8 @@ UpdateServerCallback,
   AppiumLogger,
+  StringRecord,
+  ConstraintsToCaps,
+  BaseDriverCapConstraints,
+  W3CCapabilities,
+  Capabilities,
 } from '.';
-import {W3CCapabilities} from './capabilities';
 import {ServerArgs} from './config';
@@ -51,20 +54,26 @@
 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};
 
@@ -112,11 +121,16 @@ export interface FindCommands {
 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[]
@@ -147,15 +161,15 @@ ): Promise<CreateResult>;
 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>;
@@ -165,3 +179,3 @@ isPackageOrBundle: (app: string) => boolean;
   parseCapsArray: (cap: string | string[]) => string[];
-  generateDriverLogPrefix: (obj: Core, sessionId?: string) => string;
+  generateDriverLogPrefix: (obj: Core<C>, sessionId?: string) => string;
 }
@@ -276,11 +290,9 @@
  */
-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;
@@ -316,3 +328,3 @@ relaxedSecurityEnabled: boolean;
   logEvent(eventName: string): void;
-  driverForSession(sessionId: string): Core | null;
+  driverForSession(sessionId: string): Core<C> | null;
 }
@@ -324,4 +336,6 @@
  */
-export interface Driver
-  extends SessionCommands,
+export interface Driver<
+  C extends Constraints = BaseDriverCapConstraints,
+  A extends StringRecord = StringRecord
+> extends SessionCommands,
     LogCommands,
@@ -332,6 +346,6 @@ FindCommands,
     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`.
@@ -342,5 +356,7 @@ executeCommand(cmd: string, ...args: any[]): Promise<any>;
   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;
@@ -595,2 +611,6 @@ }
 
+export interface ExtraDriverOpts {
+  fastReset?: boolean;
+  skipUninstall?: boolean;
+}
 /**
@@ -601,3 +621,5 @@ * Options as passed into a driver constructor, which is just a union of {@linkcode ServerArgs} and {@linkcode Capabilities}.
  */
-export type DriverOpts = ServerArgs & Capabilities;
+export type DriverOpts<C extends Constraints = BaseDriverCapConstraints> = ServerArgs &
+  ExtraDriverOpts &
+  Partial<ConstraintsToCaps<C>>;
 
@@ -604,0 +626,0 @@ export type DriverCommand<TArgs = any, TReturn = unknown> = (...args: TArgs[]) => Promise<TReturn>;

lib/index.ts

@@ -6,3 +6,2 @@ import type {Server as WSServer} from 'ws';
 import {ServerArgs} from './config';
-import {Capabilities, W3CCapabilities} from './capabilities';
 import type {Express} from 'express';
@@ -15,7 +14,9 @@ import {ExternalDriver} from './driver';
 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>;
+
 /**
@@ -68,11 +69,6 @@ * A log prefix for {@linkcode AppiumLogger}
   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>;
@@ -170,5 +166,8 @@ }
  */
-export type UpdateServerCallback = (expressApp: Express, httpServer: AppiumServer, cliArgs: ServerArgs) => Promise<void>;
+export type UpdateServerCallback = (
+  expressApp: Express,
+  httpServer: AppiumServer,
+  cliArgs: ServerArgs
+) => Promise<void>;
 
-
 /**
@@ -180,12 +179,21 @@ * Possible HTTP methods, as stolen from `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.json

 {
   "name": "@appium/types",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Various type declarations used across Appium",
@@ -26,2 +26,3 @@ "keywords": [
   ],
+  "main": "./build/index.js",
   "scripts": {
@@ -37,7 +38,7 @@ "build": "node ./scripts/generate-schema-types.js",
     "@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"
   },
@@ -51,3 +52,3 @@ "engines": {
   },
-  "gitHead": "c26af8f85230ac65cbc19f08f763942f74b0eb0c"
+  "gitHead": "f545a6cde58d83f3289072f8957468793947ba66"
 }

No alert changes

Improved metrics

Total package byte prevSize

156106

14.22%

Number of package files

35

45.83%

Lines of code

3002

20.9%

Dependency changes

• + Added

  @types/express@4.17.14
  (transitive)

• + Added

  @wdio/types@7.25.1
  (transitive)

• + Added

  type-fest@3.1.0
  (transitive)

• - Removed

  @types/express@4.17.13
  (transitive)

• - Removed

  @wdio/types@7.24.0
  (transitive)

• - Removed

  type-fest@2.19.0
  (transitive)

• Updated

  @types/express@4.17.14

• Updated

  @wdio/types@7.25.1

• Updated

  type-fest@3.1.0