fix(types): separate the type of opts from initialOpts

A thing we know about the `opts` object passed in to a driver constructor is that it does _not_ contain caps.  This value is retained in `this.initialOpts`.  Upon session creation, it _does_ contain caps.

This adds a new type, `InitialOpts`, which is the first parameter to a driver.  In the future, it may accept a type argument, as currently any extension-specific options (defined via schema in `package.json`) are not typed.

Because `DriverOpts` is a superset of `InitialOpts`, this should not be a breaking change.

packages/base-driver/lib/basedriver/core.js

@@ -38,7 +38,7 @@ class DriverCore {
   opts;
 
   /**
-   * @type {import('@appium/types').DriverOpts<C>}
+   * @type {import('@appium/types').InitialOpts}
    */
   initialOpts;
 
@@ -121,14 +121,14 @@ class DriverCore {
   settings;
 
   /**
-   * @param {DriverOpts<C>} opts
+   * @param {InitialOpts} opts
    * @param {boolean} [shouldValidateCaps]
    */
-  constructor(opts = /** @type {DriverOpts<C>} */ ({}), shouldValidateCaps = true) {
+  constructor(opts = /** @type {InitialOpts} */ ({}), shouldValidateCaps = true) {
     this._log = logger.getLogger(helpers.generateDriverLogPrefix(this));
 
     // setup state
-    this.opts = opts;
+    this.opts = /** @type {DriverOpts<C>} */ (opts);
 
     // use a custom tmp dir to avoid losing data and app when computer is
     // restarted
@@ -441,6 +441,7 @@ export {DriverCore};
  * @typedef {import('@appium/types').AppiumLogger} AppiumLogger
  * @typedef {import('@appium/types').StringRecord} StringRecord
  * @typedef {import('@appium/types').BaseDriverCapConstraints} BaseDriverCapConstraints
+ * @typedef {import('@appium/types').InitialOpts} InitialOpts
  */
 
 /**

packages/base-driver/lib/basedriver/driver.ts

@@ -1,28 +1,28 @@
-import {validateCaps, processCapabilities} from './capabilities';
-import {DriverCore} from './core';
 import {util} from '@appium/support';
+import {
+  BASE_DESIRED_CAP_CONSTRAINTS,
+  type AppiumServer,
+  type BaseDriverCapConstraints,
+  type Capabilities,
+  type Constraints,
+  type DefaultCreateSessionResult,
+  type Driver,
+  type DriverCaps,
+  type DriverData,
+  type DriverOpts,
+  type MultiSessionData,
+  type ServerArgs,
+  type StringRecord,
+  type W3CDriverCaps,
+  type InitialOpts,
+} from '@appium/types';
 import B from 'bluebird';
 import _ from 'lodash';
 import {fixCaps, isW3cCaps} from '../helpers/capabilities';
 import {DELETE_SESSION_COMMAND, determineProtocol, errors} from '../protocol';
+import {processCapabilities, validateCaps} from './capabilities';
+import {DriverCore} from './core';
 import helpers from './helpers';
-import {
-  AppiumServer,
-  BaseDriverCapConstraints,
-  BASE_DESIRED_CAP_CONSTRAINTS,
-  Capabilities,
-  Constraints,
-  DefaultCreateSessionResult,
-  Driver,
-  DriverCaps,
-  DriverData,
-  DriverOpts,
-  MultiSessionData,
-  ServerArgs,
-  SingularSessionData,
-  StringRecord,
-  W3CDriverCaps,
-} from '@appium/types';
 
 const EVENT_SESSION_INIT = 'newSessionRequested';
 const EVENT_SESSION_START = 'newSessionStarted';
@@ -43,13 +43,12 @@ export class BaseDriver<
   caps: DriverCaps<C>;
   originalCaps: W3CDriverCaps<C>;
   desiredCapConstraints: C;
-  opts: DriverOpts<C>;
   server?: AppiumServer;
   serverHost?: string;
   serverPort?: number;
   serverPath?: string;
 
-  constructor(opts: DriverOpts<C>, shouldValidateCaps = true) {
+  constructor(opts: InitialOpts, shouldValidateCaps = true) {
     super(opts, shouldValidateCaps);
 
     this.caps = {} as DriverCaps<C>;
@@ -62,7 +61,7 @@ export class BaseDriver<
    *
    * Subclasses _shouldn't_ need to use this. If you need to use this, please create
    * an issue:
-   * @see https://github.com/appium/appium/issues/new
+   * @see {@link https://github.com/appium/appium/issues/new}
    */
   protected get _desiredCapConstraints(): Readonly<BaseDriverCapConstraints & C> {
     return Object.freeze(_.merge({}, BASE_DESIRED_CAP_CONSTRAINTS, this.desiredCapConstraints));

packages/fake-driver/lib/driver.js

@@ -55,7 +55,7 @@ export class FakeDriver extends BaseDriver {
   elMap;
 
   constructor(
-    opts = /** @type {import('@appium/types').DriverOpts<FakeDriverConstraints>} */ ({}),
+    opts = /** @type {import('@appium/types').InitialOpts} */ ({}),
     shouldValidateCaps = true
   ) {
     super(opts, shouldValidateCaps);

packages/types/lib/driver.ts

@@ -1,13 +1,13 @@
-import type {EventEmitter} from 'events';
-import {Entries} from 'type-fest';
-import {ActionSequence} from './action';
-import {Capabilities, DriverCaps, W3CCapabilities, W3CDriverCaps} from './capabilities';
-import {ExecuteMethodMap, MethodMap} from './command';
-import {ServerArgs} from './config';
-import {HTTPHeaders, HTTPMethod} from './http';
-import {AppiumLogger} from './logger';
-import {AppiumServer, UpdateServerCallback} from './server';
-import {Class, StringRecord, Element} from './util';
+import type {EventEmitter} from 'node:events';
+import type {Merge} from 'type-fest';
+import type {ActionSequence} from './action';
+import type {Capabilities, DriverCaps, W3CCapabilities, W3CDriverCaps} from './capabilities';
+import type {ExecuteMethodMap, MethodMap} from './command';
+import type {ServerArgs} from './config';
+import type {HTTPHeaders, HTTPMethod} from './http';
+import type {AppiumLogger} from './logger';
+import type {AppiumServer, UpdateServerCallback} from './server';
+import type {Class, Element, StringRecord} from './util';
 
 /**
  * Interface implemented by the `DeviceSettings` class in `@appium/base-driver`
@@ -577,7 +577,7 @@ export interface Core<C extends Constraints, Settings extends StringRecord = Str
   shouldValidateCaps: boolean;
   sessionId: string | null;
   opts: DriverOpts<C>;
-  initialOpts: Partial<DriverOpts<C>>;
+  initialOpts: InitialOpts;
   protocol?: string;
   helpers: DriverHelpers;
   basePath: string;
@@ -2009,11 +2009,14 @@ export interface ExtraDriverOpts {
   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.
+ * Options as set within {@linkcode ExternalDriver.createSession}, which is a union of {@linkcode InitialOpts} and {@linkcode DriverCaps}.
+ */
+export type DriverOpts<C extends Constraints> = InitialOpts & DriverCaps<C>;
+
+/**
+ * Options as provided to the {@linkcode Driver} constructor.
  */
-export type DriverOpts<C extends Constraints> = ServerArgs & ExtraDriverOpts & DriverCaps<C>;
+export type InitialOpts = Merge<ServerArgs, ExtraDriverOpts>;
 
 /**
  * An instance method of a driver class, whose name may be referenced by {@linkcode MethodDef.command}, and serves as an Appium command.