@appium/types 0.10.1 → 0.10.2

package/lib/capabilities.ts

@@ -1,6 +1,7 @@
-import {StandardCapabilities} from './standard-caps';
-import {StringRecord, Constraint, Constraints} from '.';
 import {BaseDriverCapConstraints} from './constraints';
+import {Constraint, Constraints} from './driver';
+import {StandardCapabilities} from './standard-caps';
+import {AnyCase, StringRecord} from './util';
 
 export {StandardCapabilities};
 
@@ -9,20 +10,23 @@ export type W3C_APPIUM_PREFIX = 'appium';
 /**
  * Base capabilities as derived from {@linkcode BaseDriverCapConstraints}.
  */
-export type BaseCapabilities = ConstraintsToCaps<BaseDriverCapConstraints>;
+export type BaseCapabilities = Capabilities<BaseDriverCapConstraints>;
 
 /**
  * Like {@linkcode BaseCapabilities}, except all Appium-specific keys are namespaced.
  */
-export type BaseNSCapabilities = CapsToNSCaps<ConstraintsToCaps<BaseDriverCapConstraints>>;
+export type BaseNSCapabilities = NSCapabilities<BaseDriverCapConstraints>;
+
+/**
+ * Like {@linkcode NSBaseCapabilities}, except W3C-style.
+ * @see {@linkcode W3CCapabilities}
+ */
+export type BaseW3CCapabilities = W3CCapabilities<BaseDriverCapConstraints>;
 
 /**
  * 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 ConstraintChoice<
-  C extends Constraint,
-  T
-> = C['inclusionCaseInsensitive'] extends ReadonlyArray<T>
+export type ConstraintChoice<C extends Constraint, T> = C['inclusionCaseInsensitive'] extends T[]
   ? AnyCase<C['inclusionCaseInsensitive'][number]>
   : C['inclusion'] extends ReadonlyArray<T>
   ? C['inclusion'][number]
@@ -37,7 +41,7 @@ type ConstraintChoice<
  * - 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`.
  */
-type ConstraintToCapKind<C extends Constraint> = C['isString'] extends true
+export type ConstraintToCapKind<C extends Constraint> = C['isString'] extends true
   ? ConstraintChoice<C, string>
   : C['isNumber'] extends true
   ? ConstraintChoice<C, number>
@@ -47,7 +51,7 @@ type ConstraintToCapKind<C extends Constraint> = C['isString'] extends true
   ? string[]
   : C['isObject'] extends true
   ? object
-  : any;
+  : unknown;
 
 /**
  * Given {@linkcode Constraint} `C`, determine if it is required or optional.
@@ -60,17 +64,6 @@ export type ConstraintToCap<C extends Constraint> = C['presence'] extends
   ? ConstraintToCapKind<C>
   : ConstraintToCapKind<C> | undefined;
 
-/**
- * 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>}`
-  : '';
-
 /**
  * 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`.
  *
@@ -82,6 +75,10 @@ export type CapsToNSCaps<T extends StringRecord, NS extends string = W3C_APPIUM_
     : NamespacedString<K & string, NS>]: T[K];
 };
 
+/**
+ * A namespaced string of the format `<NS>:<S>` where `NS` defaults to the value of
+ * {@linkcode W3C_APPIUM_PREFIX} and `S` is a string.
+ */
 export type NamespacedString<
   S extends string,
   NS extends string = W3C_APPIUM_PREFIX
@@ -89,6 +86,7 @@ export type NamespacedString<
 
 /**
  * Converts {@linkcode Constraint} `C` to a {@linkcode Capabilities} object.
+ * @privateRemarks I would like to figure out how to simplify this type
  */
 export type ConstraintsToCaps<C extends Constraints> = {
   -readonly [K in keyof C]: ConstraintToCap<C[K]>;
@@ -99,34 +97,26 @@ export type ConstraintsToCaps<C extends Constraints> = {
  *
  * Does not contain {@linkcode BaseCapabilities}; see {@linkcode DriverCaps}.
  */
-export type Capabilities<
-  C extends Constraints = BaseDriverCapConstraints,
-  Extra extends StringRecord | void = void
-> = Partial<ConstraintsToCaps<C> & Extra>;
+export type Capabilities<C extends Constraints> = ConstraintsToCaps<C>;
 
 /**
  * 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>[];
-};
+export interface W3CCapabilities<C extends Constraints> {
+  alwaysMatch: NSCapabilities<C>;
+  firstMatch: NSCapabilities<C>[];
+}
 
 /**
  * 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>>;
+export type NSCapabilities<C extends Constraints, NS extends string = W3C_APPIUM_PREFIX> = Partial<
+  CapsToNSCaps<ConstraintsToCaps<C>, NS>
+>;
 
 /**
  * Capabilities for drivers extending `BaseDriver`.
@@ -135,7 +125,7 @@ export type NSCapabilities<
  *
  * @example
  * ```ts
- * class MyDriver extends BaseDriver {
+ * class MyDriver extends BaseDriver<MyDriverConstraints> {
  *   async createSession (w3ccaps: W3CDriverCaps<MyDriverConstraints>, ...args: any[]) {
  *     const [
  *       sessionId: string,
@@ -147,36 +137,33 @@ export type NSCapabilities<
  * ```
  */
 
-export type DriverCaps<
-  C extends Constraints,
-  Extra extends StringRecord | void = void
-> = Capabilities<BaseDriverCapConstraints & C, Extra>;
+/**
+ * Normalized capabilities for drivers extending `BaseDriver`.
+ * Includes {@linkcode BaseCapabilities}.
+ */
+export type DriverCaps<C extends Constraints = Constraints> = BaseCapabilities & Capabilities<C>;
 
 /**
  * W3C-style capabilities for drivers extending `BaseDriver`.
  *
- * Includes {@linkcode BaseCapabilities}.
+ * Includes {@linkcode BaseW3CCapabilities}.
  *
  * @example
  * ```ts
- * class MyDriver extends BaseDriver {
+ * class MyDriver extends BaseDriver<MyDriverConstraints> {
  *   async createSession (w3ccaps: W3CDriverCaps<MyDriverConstraints>, ...args: any[]) {
  *     // ...
  *   }
  * }
  * ```
  */
-export type W3CDriverCaps<
-  C extends Constraints,
-  Extra extends StringRecord | void = void
-> = W3CCapabilities<BaseDriverCapConstraints & C, Extra>;
+export type W3CDriverCaps<C extends Constraints = Constraints> = BaseW3CCapabilities &
+  W3CCapabilities<C>;
 
 /**
  * Namespaced capabilities for drivers extending `BaseDriver`.
  *
- * Includes {@linkcode BaseCapabilities}.
+ * Includes {@linkcode BaseNSCapabilities}.
  */
-export type NSDriverCaps<
-  C extends Constraints,
-  Extra extends StringRecord | void = void
-> = NSCapabilities<BaseDriverCapConstraints & C, Extra>;
+export type NSDriverCaps<C extends Constraints = Constraints> = BaseNSCapabilities &
+  NSCapabilities<C>;

package/lib/command.ts

@@ -1,6 +1,7 @@
 import {ConditionalPick, MultidimensionalReadonlyArray} from 'type-fest';
 import {Driver, DriverCommand} from './driver';
 import {Plugin, PluginCommand} from './plugin';
+import {StringRecord} from './util';
 
 /**
  * Defines the shape of a payload for a {@linkcode MethodDef}.
@@ -15,17 +16,30 @@ export interface PayloadParams {
 }
 /**
  * A mapping of URL paths to HTTP methods to either a {@linkcode DriverMethodDef} or {@linkcode PluginMethodDef}.
+ *
+ * Extensions can define new methods for the Appium server to map to command names, of the same
+ * format as used in Appium's `routes.js`.
+ *
+ * @example
+ * ```js
+ * {
+ *   '/session/:sessionId/new_method': {
+ *     GET: {command: 'getNewThing'},
+ *     POST: {command: 'setNewThing', payloadParams: {required: ['someParam']}}
+ *   }
+ * }
+ * ```
  */
-export type MethodMap<T extends Plugin | Driver> = T extends Plugin
+export type MethodMap<T extends Plugin | Driver<any>> = T extends Plugin
   ? Readonly<PluginMethodMap<T>>
-  : T extends Driver
+  : T extends Driver<any>
   ? Readonly<DriverMethodMap<T>>
   : never;
 
 /**
  * A {@linkcode MethodMap} for a {@linkcode Driver}.
  */
-export interface DriverMethodMap<T extends Driver> {
+export interface DriverMethodMap<T extends Driver<any>> {
   [key: string]: {
     GET?: DriverMethodDef<T>;
     POST?: DriverMethodDef<T>;
@@ -50,11 +64,17 @@ export interface BaseMethodDef {
 /**
  * A definition of an exposed API command in a {@linkcode Driver}.
  */
-export interface DriverMethodDef<T extends Driver> extends BaseMethodDef {
+export interface DriverMethodDef<T extends Driver, D extends boolean = boolean>
+  extends BaseMethodDef {
   /**
    * Name of the command.
    */
-  readonly command?: keyof ConditionalPick<Required<T>, DriverCommand>;
+  readonly command?: D extends true ? string : keyof ConditionalPick<Required<T>, DriverCommand>;
+
+  /**
+   * If this is `true`, we do not validate `command`, because it may not exist in `ExternalDriver`.
+   */
+  readonly deprecated?: D;
 }
 
 /**
@@ -98,7 +118,7 @@ export interface BaseExecuteMethodDef {
 /**
  * A definition of an execute method in a {@linkcode Driver}.
  */
-export interface DriverExecuteMethodDef<T extends Driver> extends BaseExecuteMethodDef {
+export interface DriverExecuteMethodDef<T extends Driver<any>> extends BaseExecuteMethodDef {
   command: keyof ConditionalPick<T, DriverCommand>;
 }
 
@@ -112,8 +132,8 @@ export interface PluginExecuteMethodDef<T extends Plugin> extends BaseExecuteMet
 /**
  * Definition of an execute method (which overloads the behavior of the `execute` command) in a {@linkcode Driver} or {@linkcode Plugin}.
  */
-export type ExecuteMethodMap<T extends Plugin | Driver> = T extends Plugin
-  ? Readonly<Record<string, PluginExecuteMethodDef<T>>>
-  : T extends Driver
-  ? Readonly<Record<string, DriverExecuteMethodDef<T>>>
+export type ExecuteMethodMap<T extends Plugin | Driver<any>> = T extends Plugin
+  ? Readonly<StringRecord<PluginExecuteMethodDef<T>>>
+  : T extends Driver<any>
+  ? Readonly<StringRecord<DriverExecuteMethodDef<T>>>
   : never;

package/lib/config.ts

@@ -1,5 +1,6 @@
 import type {AppiumConfigJsonSchema} from '@appium/schema';
 import {AppiumConfiguration, ServerConfig} from './appium-config';
+import {Associated, KebabToCamel} from './util';
 
 /**
  * The Appium configuration as it would be in a user-provided configuration file.
@@ -9,7 +10,7 @@ export type AppiumConfig = Partial<AppiumConfiguration>;
 /**
  * Derive the "constant" type of the server properties from the schema.
  */
-type AppiumServerJsonSchema = typeof AppiumConfigJsonSchema['properties']['server']['properties'];
+type AppiumServerJsonSchema = (typeof AppiumConfigJsonSchema)['properties']['server']['properties'];
 
 /**
  * This type associates the types generated from the schema ({@linkcode AppiumConfiguration})
@@ -61,41 +62,6 @@ type KeyOrDefaultForProp<Prop extends keyof ServerConfigMapping> =
 export type ServerArgs = {
   [Prop in keyof ServerConfigMapping as SetKeyForProp<Prop>]: KeyOrDefaultForProp<Prop>;
 };
-// begin utils
-
-/**
- * Converts a kebab-cased string into a camel-cased string.
- */
-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.
- */
-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.
- */
-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).
- */
-type Associated<A extends object, B extends {[key in keyof Required<A>]: unknown}> = {
-  [Prop in keyof Required<A>]: B[Prop];
-};
-
-// end utils
 
 // begin conditionals
 

package/lib/{constraints.js → constraints.ts}

@@ -1,4 +1,6 @@
-export const BASE_DESIRED_CAP_CONSTRAINTS = /** @type {const} */ ({
+import {Constraints} from './driver';
+
+export const BASE_DESIRED_CAP_CONSTRAINTS = {
   platformName: {
     presence: true,
     isString: true,
@@ -51,8 +53,6 @@ export const BASE_DESIRED_CAP_CONSTRAINTS = /** @type {const} */ ({
   printPageSourceOnFindFailure: {
     isBoolean: true,
   },
-});
+} as const satisfies Constraints;
 
-/**
- * @typedef {typeof BASE_DESIRED_CAP_CONSTRAINTS} BaseDriverCapConstraints
- */
+export type BaseDriverCapConstraints = typeof BASE_DESIRED_CAP_CONSTRAINTS;