@appium/types - npm Package Compare versions

Comparing version 0.5.0 to 0.6.0

lib/appium-config.ts

@@ -53,5 +53,19 @@ /* tslint:disable */
 /**
+ * Log filtering rule
+ */
+export type LogFilter = {
+  /**
+   * Replacement string for matched text
+   */
+  replacer?: string;
+  /**
+   * Matching flags; see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#advanced_searching_with_flags
+   */
+  flags?: string;
+  [k: string]: unknown;
+} & (LogFilterText | LogFilterRegex);
+/**
  * One or more log filtering rules
  */
-export type LogFiltersConfig = string[];
+export type LogFiltersConfig = LogFilter[];
 /**
@@ -138,2 +152,6 @@ * Log level (console[:file])
 export interface AppiumConfiguration {
+  /**
+   * The JSON schema for this file
+   */
+  $schema?: string;
   server?: ServerConfig;
@@ -189,2 +207,22 @@ }
 /**
+ * Log filter with plain text
+ */
+export interface LogFilterText {
+  /**
+   * Text to match
+   */
+  text: string;
+  [k: string]: unknown;
+}
+/**
+ * Log filter with regular expression
+ */
+export interface LogFilterRegex {
+  /**
+   * Regex pattern to match
+   */
+  pattern: string;
+  [k: string]: unknown;
+}
+/**
  * Path to configuration JSON file to register Appium as a node with Selenium Grid 3; otherwise the configuration itself
@@ -191,0 +229,0 @@ */

lib/driver.ts

@@ -17,4 +17,5 @@ import type {EventEmitter} from 'events';
 import {ServerArgs} from './config';
+import {AsyncReturnType, ConditionalPick} from 'type-fest';
 
-export interface TimeoutCommands {
+export interface ITimeoutCommands {
   timeouts(
@@ -42,3 +43,3 @@ type: string,
 
-export interface EventCommands {
+export interface IEventCommands {
   logCustomEvent(vendor: string, event: string): Promise<void>;
@@ -48,3 +49,3 @@ getLogEvents(type?: string | string[]): Promise<EventHistory | Record<string, number>>;
 
-export interface SessionCommands {
+export interface ISessionCommands {
   getSessions(): Promise<MultiSessionData[]>;
@@ -54,15 +55,14 @@ getSession(): Promise<SingularSessionData>;
 
-export interface ExecuteCommands {
+export interface IExecuteCommands {
   executeMethod(script: string, args: [StringRecord] | []): Promise<any>;
 }
 
-export interface ExecuteMethodDef {
-  command: string;
+export interface ExecuteMethodDef<D> {
+  command: keyof ConditionalPick<Required<D>, DriverCommand>;
   params?: {
-    required?: string[];
-    optional?: string[];
+    required?: ReadonlyArray<string>;
+    optional?: ReadonlyArray<string>;
   };
 }
-export type ExecuteMethodMap = Record<string, ExecuteMethodDef>;
-
+export type ExecuteMethodMap<D> = Readonly<Record<string, Readonly<ExecuteMethodDef<D>>>>;
 export interface MultiSessionData<
@@ -81,3 +81,3 @@ C extends Constraints = BaseDriverCapConstraints,
 
-export interface FindCommands {
+export interface IFindCommands<Ctx = any> {
   findElement(strategy: string, selector: string): Promise<Element>;
@@ -96,3 +96,3 @@ findElements(strategy: string, selector: string): Promise<Element[]>;
     mult: Mult,
-    context?: string
+    context?: Ctx
   ): Promise<Mult extends true ? Element[] : Element>;
@@ -104,3 +104,3 @@
     mult: Mult,
-    context?: string
+    context?: Ctx
   ): Promise<Mult extends true ? Element[] : Element>;
@@ -111,16 +111,53 @@
 
-export interface LogCommands {
-  supportedLogTypes: Record<string, LogType<Driver>>;
-  getLogTypes(): Promise<string[]>;
+export interface ILogCommands<C extends Constraints> {
   /**
-   * Gets logs
+   * Definition of the available log types
+   */
+  supportedLogTypes: Readonly<LogDefRecord<C>>;
+
+  /**
+   * Get available log types as a list of strings
+   */
+  getLogTypes(): Promise<(keyof ILogCommands<C>['supportedLogTypes'])[]>;
+
+  /**
+   * Get the log for a given log type.
    *
-   * TODO: `logType` should be a key in `supportedLogTypes`, and the return value of this function
-   * should be the associated `LogType` object's `LogEntry` parameterized type.
-   * @param logType - Name/key of log type as defined in {@linkcode LogCommands.supportedLogTypes}.
+   * @param logType - Name/key of log type as defined in {@linkcode ILogCommands.supportedLogTypes}.
    */
-  getLog(logType: string): Promise<any[]>;
+  getLog(
+    logType: keyof ILogCommands<C>['supportedLogTypes']
+  ): Promise<
+    AsyncReturnType<
+      ILogCommands<C>['supportedLogTypes'][keyof ILogCommands<C>['supportedLogTypes']]['getter']
+    >
+  >;
 }
 
-export interface SettingsCommands {
+/**
+ * A record of {@linkcode LogDef} objects, keyed by the log type name.
+ * Used in {@linkcode ILogCommands.supportedLogTypes}
+ */
+export type LogDefRecord<C extends Constraints> = Record<string, LogDef<C>>;
+
+/**
+ * A definition of a log type
+ */
+export interface LogDef<C extends Constraints, T = unknown> {
+  /**
+   * Description of the log type.
+   *
+   * The only place this is used is in error messages if the client provides an invalid log type
+   * via {@linkcode ILogCommands.getLog}.
+   */
+  description: string;
+  /**
+   * Returns all the log data for the given type
+   *
+   * This implementation *should* drain, truncate or otherwise reset the log buffer.
+   */
+  getter: (driver: Driver<C>) => Promise<T[]>;
+}
+
+export interface ISettingsCommands {
   updateSettings: (settings: StringRecord) => Promise<void>;
@@ -196,7 +233,2 @@ getSettings(): Promise<StringRecord>;
 
-export interface LogType<TDriver, LogEntry = string> {
-  description: string;
-  getter: (driver: TDriver) => Promise<LogEntry[]>;
-}
-
 // WebDriver
@@ -256,3 +288,3 @@
   longitude: number;
-  altitude: number;
+  altitude?: number;
 }
@@ -337,16 +369,21 @@
  * external drivers are expected to implement {@linkcode ExternalDriver} instead.
+ *
+ * `C` should be the constraints of the driver.
+ * `CArgs` would be the shape of `cliArgs`.
+ * `Ctx` would be the type of the element context (e.g., string, dictionary of some sort, etc.)
  */
 export interface Driver<
   C extends Constraints = BaseDriverCapConstraints,
-  A extends StringRecord = StringRecord
-> extends SessionCommands,
-    LogCommands,
-    FindCommands,
-    SettingsCommands,
-    TimeoutCommands,
-    EventCommands,
+  CArgs extends StringRecord = StringRecord,
+  Ctx = any
+> extends ISessionCommands,
+    ILogCommands<C>,
+    IFindCommands<Ctx>,
+    ISettingsCommands,
+    ITimeoutCommands,
+    IEventCommands,
+    IExecuteCommands,
     SessionHandler<[string, any], void, C>,
-    ExecuteCommands,
     Core {
-  cliArgs?: A;
+  cliArgs: CArgs;
   // The following methods are implemented by `BaseDriver`.
@@ -369,8 +406,9 @@ executeCommand(cmd: string, ...args: any[]): Promise<any>;
  */
-export interface ExternalDriver extends Driver {
+export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints>
+  extends Driver<C> {
   // The following properties are assigned by appium */
-  server: AppiumServer;
-  serverHost: string;
-  serverPort: number;
-  serverPath: string;
+  server?: AppiumServer;
+  serverHost?: string;
+  serverPort?: number;
+  serverPath?: string;
 
@@ -586,4 +624,3 @@ // WebDriver
   setUserAuthVerified?(isUserVerified: boolean): Promise<void>;
-
-  proxyCommand?(url: string, method: HTTPMethod, body?: string): Promise<unknown>;
+  proxyCommand?<T = any>(url: string, method: HTTPMethod, body?: string): Promise<T>;
 }
@@ -596,7 +633,7 @@
  */
-export interface DriverStatic {
+export interface DriverStatic<D extends Driver> {
   baseVersion: string;
   updateServer?: UpdateServerCallback;
-  newMethodMap?: MethodMap<ExternalDriver>;
-  executeMethodMap: ExecuteMethodMap;
+  newMethodMap?: MethodMap<D>;
+  executeMethodMap?: ExecuteMethodMap<D>;
 }
@@ -609,6 +646,7 @@
  */
-export type DriverClass<
-  D extends Driver = ExternalDriver,
-  S extends DriverStatic = DriverStatic
-> = Class<D, S, [] | [Partial<ServerArgs>] | [Partial<ServerArgs>, boolean]>;
+export type DriverClass<D extends Driver = ExternalDriver> = Class<
+  D,
+  DriverStatic<D>,
+  [] | [Partial<ServerArgs>] | [Partial<ServerArgs>, boolean]
+>;
 
@@ -615,0 +653,0 @@ export interface ExtraDriverOpts {

lib/index.ts

@@ -1,18 +0,21 @@
-import type {Server as WSServer} from 'ws';
+import type {Express} from 'express';
+import type {Server} from 'http';
 import type {Socket} from 'net';
-import type {Server} from 'http';
+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 type {Express} from 'express';
-import {ExternalDriver} from './driver';
-import type {Logger} from 'npmlog';
 
-export * from './driver';
 export * from './action';
-export * from './plugin';
+export * from './appium-config';
 export * from './capabilities';
-export * from './constraints';
 export * from './config';
-export * from './appium-config';
+export {BASE_DESIRED_CAP_CONSTRAINTS} from './constraints';
+export type {BaseDriverCapConstraints} from './constraints';
+export * from './driver';
+export * from './plugin';
 
+/**
+ * Utility type for a object with string-only props
+ */
 export type StringRecord = Record<string, any>;
@@ -82,19 +85,19 @@
  */
-export interface Method<T> {
+export interface MethodDef<Ext> {
   /**
    * Name of the command.
    */
-  command?: keyof ConditionalPick<Required<T>, DriverCommand>;
+  readonly command?: keyof ConditionalPick<Required<Ext>, DriverCommand>;
   /**
    * If true, this `Method` will never proxy.
    */
-  neverProxy?: boolean;
+  readonly neverProxy?: boolean;
   /**
    * Specifies shape of payload
    */
-  payloadParams?: PayloadParams;
+  readonly payloadParams?: PayloadParams;
 }
 
 /**
- * An instance method of a driver class, whose name may be referenced by {@linkcode Method.command}, and serves as an Appium command.
+ * An instance method of a driver class, whose name may be referenced by {@linkcode MethodDef.command}, and serves as an Appium command.
  *
@@ -106,3 +109,3 @@ * Note that this signature differs from a `PluginCommand`.
 /**
- * Defines the shape of a payload for a {@linkcode Method}.
+ * Defines the shape of a payload for a {@linkcode MethodDef}.
  */
@@ -112,4 +115,4 @@ export interface PayloadParams {
   unwrap?: string;
-  required?: Readonly<string[]> | MultidimensionalReadonlyArray<string, 2>;
-  optional?: Readonly<string[]> | MultidimensionalReadonlyArray<string, 2>;
+  required?: ReadonlyArray<string> | MultidimensionalReadonlyArray<string, 2>;
+  optional?: ReadonlyArray<string> | MultidimensionalReadonlyArray<string, 2>;
   validate?: (obj: any, protocol: string) => boolean | string | undefined;
@@ -119,9 +122,13 @@ makeArgs?: (obj: any) => any;
 /**
- * A mapping of URL paths to HTTP methods to {@linkcode Method}s.
- *
- * @todo Should use {@linkcode HTTPMethod} here
+ * A mapping of URL paths to HTTP methods to {@linkcode MethodDef}s.
  */
-export type MethodMap<Extension = ExternalDriver> = Record<
-  string,
-  Record<string, Method<Extension & ExternalDriver>>
+export type MethodMap<Ext = any> = Readonly<
+  Record<
+    string,
+    {
+      GET?: MethodDef<Ext>;
+      POST?: MethodDef<Ext>;
+      DELETE?: MethodDef<Ext>;
+    }
+  >
 >;
@@ -170,3 +177,3 @@
   httpServer: AppiumServer,
-  cliArgs: ServerArgs
+  cliArgs: Partial<ServerArgs>
 ) => Promise<void>;
@@ -173,0 +180,0 @@

lib/plugin.ts

@@ -7,3 +7,3 @@ import {MethodMap, UpdateServerCallback, Class, AppiumLogger, PluginType} from '.';
  */
-export interface PluginStatic<T extends Plugin = Plugin> {
+export interface PluginStatic<P extends Plugin> {
   /**
@@ -24,3 +24,3 @@ * Allows a plugin to modify the Appium server instance.
    */
-  newMethodMap?: MethodMap<T>;
+  newMethodMap?: MethodMap<P>;
 }
@@ -94,2 +94,6 @@
  */
-export type PluginClass = Class<Plugin, PluginStatic, [string, Record<string, unknown>]>;
+export type PluginClass<P extends Plugin = Plugin> = Class<
+  P,
+  PluginStatic<P>,
+  [string, Record<string, unknown>]
+>;

package.json

 {
   "name": "@appium/types",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Various type declarations used across Appium",
   "keywords": [
-    "appium",
-    "typescript",
-    "types"
+    "automation",
+    "javascript",
+    "selenium",
+    "webdriver",
+    "ios",
+    "android",
+    "firefoxos",
+    "testing"
   ],
@@ -21,26 +26,23 @@ "homepage": "https://appium.io",
   "author": "https://github.com/appium",
-  "types": "./build/index.d.ts",
+  "types": "./build/lib/index.d.ts",
   "files": [
     "build",
-    "lib"
+    "lib",
+    "index.js"
   ],
-  "main": "./build/index.js",
   "scripts": {
     "build": "node ./scripts/generate-schema-types.js",
-    "dev": "npm run build -- --watch",
-    "fix": "npm run lint -- --fix",
-    "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
-    "prepare": "npm run build",
-    "test:smoke": "echo 'No smoke test for this package'"
+    "clean": "git checkout -- ./types/lib/appium-config.ts || true",
+    "test:smoke": "node ./index.js"
   },
   "dependencies": {
-    "@appium/schema": "^0.0.9",
+    "@appium/schema": "^0.1.0",
     "@types/express": "4.17.14",
     "@types/npmlog": "4.1.4",
     "@types/ws": "8.5.3",
-    "@wdio/types": "7.25.1",
-    "type-fest": "3.1.0"
+    "@wdio/types": "7.26.0",
+    "type-fest": "3.3.0"
   },
   "engines": {
-    "node": ">=14",
+    "node": "^14.17.0 || ^16.13.0 || >=18.0.0",
     "npm": ">=8"
@@ -51,3 +53,6 @@ },
   },
-  "gitHead": "f545a6cde58d83f3289072f8957468793947ba66"
+  "gitHead": "0823f0b60e40395cd1dc3b72cfa3c0092bc81302",
+  "typedoc": {
+    "entryPoint": "./lib/index.ts"
+  }
 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

202725

increased by29.86%

Number of package files

45

increased by28.57%

Lines of code

3184

increased by6.06%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Added@appium/schema@0.1.0(transitive)

• + Added@wdio/types@7.26.0(transitive)

• + Addedtype-fest@3.3.0(transitive)

• - Removed@appium/schema@0.0.9(transitive)

• - Removed@wdio/types@7.25.1(transitive)

• - Removedtype-fest@3.1.0(transitive)

• Updated@appium/schema@^0.1.0

• Updated@wdio/types@7.26.0

• Updatedtype-fest@3.3.0