appium 3.3.0 → 3.3.1

package/build/lib/extension/manifest.d.ts

@@ -1,147 +1,101 @@
+import _ from 'lodash';
+import type { ExtensionType } from '@appium/types';
+import type { ExtManifest, ExtPackageJson, ExtRecord, ManifestData } from 'appium/types';
+import { INSTALL_TYPE_DEV, INSTALL_TYPE_NPM } from './extension-config';
 /**
  * Handles reading & writing of extension config files.
  *
  * Only one instance of this class exists per value of `APPIUM_HOME`.
  */
-export class Manifest {
+export declare class Manifest {
+    #private;
     /**
-     * Returns a new or existing {@link Manifest} instance, based on the value of `appiumHome`.
+     * Returns the memoized manifest for an `APPIUM_HOME` directory (one instance per home).
      *
-     * Maintains one instance per value of `appiumHome`.
+     * @param appiumHome - `APPIUM_HOME` path used as the cache key
      */
     static getInstance: ((appiumHome: string) => Manifest) & _.MemoizedFunction;
+    private constructor();
+    /** `APPIUM_HOME` directory this manifest is tied to. */
+    get appiumHome(): string;
     /**
-     * Sets internal data to a fresh clone of {@link INITIAL_MANIFEST_DATA}
-     *
-     * Use {@link Manifest.getInstance} instead.
-     * @param {string} appiumHome
-     * @private
+     * Absolute path to the extension manifest file after {@link Manifest.read} or {@link Manifest.write} has resolved it.
+     * Before that, this is `undefined`.
      */
-    private constructor();
+    get manifestPath(): string | undefined;
+    /** Schema revision of the in-memory manifest data (from YAML `schemaRev`). */
+    get schemaRev(): number;
     /**
-     * Searches `APPIUM_HOME` for installed extensions and adds them to the manifest.
-     * @param {boolean} hasAppiumDependency - This affects whether or not the "dev" `InstallType` is used
-     * @returns {Promise<boolean>} `true` if any extensions were added, `false` otherwise.
+     * Returns the live installed-extension map for drivers or plugins (same object as stored in memory).
+     * Mutations affect the manifest until replaced by a new object (e.g. via `read()`); `setExtension` / `deleteExtension` update this record.
+     *
+     * @param extType - `"driver"` or `"plugin"`
      */
-    syncWithInstalledExtensions(hasAppiumDependency?: boolean): Promise<boolean>;
+    getExtensionData<ExtType extends ExtensionType>(extType: ExtType): ExtRecord<ExtType>;
     /**
-     * Returns `true` if driver with name `name` is registered.
-     * @param {string} name - Driver name
-     * @returns {boolean}
+     * Whether a driver with the given manifest key is present.
+     *
+     * @param name - Driver name as stored under `drivers` in the manifest
      */
     hasDriver(name: string): boolean;
     /**
-     * Returns `true` if plugin with name `name` is registered.
-     * @param {string} name - Plugin name
-     * @returns {boolean}
+     * Whether a plugin with the given manifest key is present.
+     *
+     * @param name - Plugin name as stored under `plugins` in the manifest
      */
     hasPlugin(name: string): boolean;
     /**
-     * Given a path to a `package.json`, add it as either a driver or plugin to the manifest.
+     * Loads manifest YAML from disk into memory, runs migration when needed, may sync with installed packages, and writes back if required.
+     * Concurrent calls while a read is in flight share the same in-flight work.
      *
-     * @template {ExtensionType} ExtType
-     * @param {ExtPackageJson<ExtType>} pkgJson
-     * @param {string} pkgPath
-     * @param {typeof INSTALL_TYPE_NPM | typeof INSTALL_TYPE_DEV} [installType]
-     * @returns {boolean} - `true` if this method did anything.
+     * @returns The parsed in-memory manifest data
      */
-    addExtensionFromPackage<ExtType extends ExtensionType>(pkgJson: ExtPackageJson<ExtType>, pkgPath: string, installType?: typeof INSTALL_TYPE_NPM | typeof INSTALL_TYPE_DEV): boolean;
+    read(): Promise<ManifestData>;
     /**
-     * Adds an extension to the manifest as was installed by the `appium` CLI.  The
-     * `extData`, `extType`, and `extName` have already been determined.
+     * Serializes the current in-memory manifest to the resolved manifest path.
+     * Concurrent calls while a write is in flight share the same in-flight work.
      *
-     * See {@link Manifest.addExtensionFromPackage} for adding an extension from an on-disk package.
-     * @template {ExtensionType} ExtType
-     * @param {ExtType} extType - `driver` or `plugin`
-     * @param {string} extName - Name of extension
-     * @param {ExtManifest<ExtType>} extData - Extension metadata
-     * @returns {ExtManifest<ExtType>} A clone of `extData`, potentially with a mutated `appiumVersion` field
-     */
-    setExtension<ExtType extends ExtensionType>(extType: ExtType, extName: string, extData: ExtManifest<ExtType>): ExtManifest<ExtType>;
-    /**
-     * Sets the schema revision
-     * @param {keyof import('./manifest-migrations').ManifestDataVersions} rev
-     */
-    setSchemaRev(rev: keyof import("./manifest-migrations").ManifestDataVersions): void;
-    /**
-     * Remove an extension from the manifest.
-     * @param {ExtensionType} extType
-     * @param {string} extName
+     * @returns `true` when the file was written successfully
      */
-    deleteExtension(extType: ExtensionType, extName: string): void;
-    /**
-     * Returns the `APPIUM_HOME` path
-     */
-    get appiumHome(): string;
+    write(): Promise<boolean>;
     /**
-     * Returns the path to the manifest file (`extensions.yaml`)
+     * Scans `APPIUM_HOME` (root and `node_modules`) for Appium extension packages and merges them into the manifest.
+     *
+     * @param hasAppiumDependency - When true and the root `package.json` depends on Appium, matching extensions use the `"dev"` install type
+     * @returns `true` if any extension entries changed, `false` otherwise
      */
-    get manifestPath(): string;
+    syncWithInstalledExtensions(hasAppiumDependency?: boolean): Promise<boolean>;
     /**
-     * Returns the schema rev of this manifest
+     * Builds manifest metadata from a `package.json` and registers it if it is a driver or plugin and the entry changed.
+     *
+     * @param pkgJson - Parsed extension `package.json`
+     * @param pkgPath - Path to that `package.json` (install path is derived from its directory)
+     * @param installType - How the package was discovered (`npm` vs `dev`)
+     * @returns `true` if the manifest was updated, `false` if unchanged or already matched
+     * @throws TypeError if the package is not a valid driver or plugin extension
      */
-    get schemaRev(): number;
+    addExtensionFromPackage(pkgJson: ExtPackageJson<ExtensionType>, pkgPath: string, installType?: typeof INSTALL_TYPE_NPM | typeof INSTALL_TYPE_DEV): boolean;
     /**
-     * Returns extension data for a particular type.
+     * Stores a deep-cloned copy of extension metadata under the given type and name.
      *
-     * @template {ExtensionType} ExtType
-     * @param {ExtType} extType
-     * @returns {Readonly<ExtRecord<ExtType>>}
+     * @param extType - `"driver"` or `"plugin"`
+     * @param extName - Manifest key for the extension
+     * @param extData - Full extension entry to persist in memory
+     * @returns The cloned data now held in the manifest
      */
-    getExtensionData<ExtType extends ExtensionType>(extType: ExtType): Readonly<ExtRecord<ExtType>>;
+    setExtension<ExtType extends ExtensionType>(extType: ExtType, extName: string, extData: ExtManifest<ExtType>): ExtManifest<ExtType>;
     /**
-     * Reads manifest from disk and _overwrites_ the internal data.
-     *
-     * If the manifest does not exist on disk, an
-     * {@link INITIAL_MANIFEST_DATA "empty"} manifest file will be created, as
-     * well as its directory if needed.
+     * Updates the in-memory manifest schema revision (typically during migration).
      *
-     * This will also, if necessary:
-     * 1. perform a migration of the manifest data
-     * 2. sync the manifest with extensions on-disk (kind of like "auto
-     *    discovery")
-     * 3. write the manifest to disk.
-     *
-     * Only one read operation can happen at a time.
-     *
-     * @returns {Promise<ManifestData>} The data
+     * @param rev - New `schemaRev` value
      */
-    read(): Promise<ManifestData>;
+    setSchemaRev(rev: number): void;
     /**
-     * Writes the data if it need s writing.
+     * Removes an extension entry from the manifest data in memory (does not write to disk by itself).
      *
-     * If the `schemaRev` prop needs updating, the file will be written.
-     *
-     * @todo If this becomes too much of a bottleneck, throttle it.
-     * @returns {Promise<boolean>} Whether the data was written
+     * @param extType - `"driver"` or `"plugin"`
+     * @param extName - Manifest key to remove
      */
-    write(): Promise<boolean>;
-    #private;
+    deleteExtension(extType: ExtensionType, extName: string): void;
 }
-/**
- * Type of the string referring to a driver (typically as a key or type string)
- */
-export type DriverType = import("@appium/types").DriverType;
-/**
- * Type of the string referring to a plugin (typically as a key or type string)
- */
-export type PluginType = import("@appium/types").PluginType;
-export type SyncWithInstalledExtensionsOpts = {
-    /**
-     * - Maximum depth to recurse into subdirectories
-     */
-    depthLimit?: number | undefined;
-};
-export type ManifestData = import("appium/types").ManifestData;
-export type InternalMetadata = import("appium/types").InternalMetadata;
-export type ExtPackageJson<ExtType extends ExtensionType> = import("appium/types").ExtPackageJson<ExtType>;
-export type ExtManifest<ExtType extends ExtensionType> = import("appium/types").ExtManifest<ExtType>;
-export type ExtRecord<ExtType extends ExtensionType> = import("appium/types").ExtRecord<ExtType>;
-/**
- * Either `driver` or `plugin` rn
- */
-export type ExtensionType = import("@appium/types").ExtensionType;
-import { INSTALL_TYPE_NPM } from './extension-config';
-import { INSTALL_TYPE_DEV } from './extension-config';
-import _ from 'lodash';
 //# sourceMappingURL=manifest.d.ts.map

package/build/lib/extension/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../lib/extension/manifest.js"],"names":[],"mappings":"AAmFA;;;;GAIG;AACH;IAwDE;;;;OAIG;IACH,kCAEa,MAAM,KACJ,QAAQ,uBAKrB;IAzBF;;;;;;OAMG;IACH,sBAGC;IAiBD;;;;OAIG;IACH,kDAHW,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,CA8C5B;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;OAQG;IACH,wBAN6B,OAAO,SAAtB,aAAc,WACjB,cAAc,CAAC,OAAO,CAAC,WACvB,MAAM,gBACN,OAAO,gBAAgB,GAAG,OAAO,gBAAgB,GAC/C,OAAO,CAkDnB;IAED;;;;;;;;;;OAUG;IACH,aAN6B,OAAO,SAAtB,aAAc,WACjB,OAAO,WACP,MAAM,WACN,WAAW,CAAC,OAAO,CAAC,GAClB,WAAW,CAAC,OAAO,CAAC,CAMhC;IAED;;;OAGG;IACH,kBAFW,MAAM,OAAO,uBAAuB,EAAE,oBAAoB,QAIpE;IAED;;;;OAIG;IACH,yBAHW,aAAa,WACb,MAAM,QAIhB;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,2BAEC;IAED;;OAEG;IACH,wBAEC;IAED;;;;;;OAMG;IACH,iBAJ6B,OAAO,SAAtB,aAAc,WACjB,OAAO,GACL,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAIxC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,QAFa,OAAO,CAAC,YAAY,CAAC,CA4EjC;IAyBD;;;;;;;OAOG;IACH,SAFa,OAAO,CAAC,OAAO,CAAC,CAiC5B;;CACF;;;;yBAIY,OAAO,eAAe,EAAE,UAAU;;;;yBAKlC,OAAO,eAAe,EAAE,UAAU;;;;;;;2BASlC,OAAO,cAAc,EAAE,YAAY;+BACnC,OAAO,cAAc,EAAE,gBAAgB;2BAIvB,OAAO,SAAtB,aAAc,IACf,OAAO,cAAc,EAAE,cAAc,CAAC,OAAO,CAAC;wBAI9B,OAAO,SAAtB,aAAc,IACf,OAAO,cAAc,EAAE,WAAW,CAAC,OAAO,CAAC;sBAI3B,OAAO,SAAtB,aAAc,IACf,OAAO,cAAc,EAAE,SAAS,CAAC,OAAO,CAAC;;;;4BAKzC,OAAO,eAAe,EAAE,aAAa;iCA1hBD,oBAAoB;iCAApB,oBAAoB;cAJvD,QAAQ"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../lib/extension/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,CAAC,MAAM,QAAQ,CAAC;AAGvB,OAAO,KAAK,EAAa,aAAa,EAAa,MAAM,eAAe,CAAC;AACzE,OAAO,KAAK,EAAC,WAAW,EAAE,cAAc,EAAE,SAAS,EAAoB,YAAY,EAAC,MAAM,cAAc,CAAC;AAEzG,OAAO,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAatE;;;;GAIG;AACH,qBAAa,QAAQ;;IACnB;;;;OAIG;IACH,MAAM,CAAC,WAAW,gBAA0B,MAAM,KAAG,QAAQ,uBAA8B;IAQ3F,OAAO;IAKP,wDAAwD;IACxD,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;OAGG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,SAAS,CAErC;IAED,8EAA8E;IAC9E,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;OAKG;IACH,gBAAgB,CAAC,OAAO,SAAS,aAAa,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC;IAKrF;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC;IAoDnC;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAiC/B;;;;;OAKG;IACG,2BAA2B,CAAC,mBAAmB,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAiChF;;;;;;;;OAQG;IACH,uBAAuB,CACrB,OAAO,EAAE,cAAc,CAAC,aAAa,CAAC,EACtC,OAAO,EAAE,MAAM,EACf,WAAW,GAAE,OAAO,gBAAgB,GAAG,OAAO,gBAAmC,GAChF,OAAO;IAyCV;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,SAAS,aAAa,EACxC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,GAC5B,WAAW,CAAC,OAAO,CAAC;IAUvB;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;CAwB/D"}