appium 2.0.0-beta.8 → 2.0.0-rc.1

package/build/lib/schema/cli-transformers.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformers = void 0;
+const argparse_1 = require("argparse");
+const fs_1 = require("fs");
+const lodash_1 = __importDefault(require("lodash"));
+/**
+ * This module provides custom keywords for Appium schemas, as well as
+ * "transformers" (see `argTransformers` below).
+ *
+ * Custom keywords are just properties that will appear in a schema (e.g.,
+ * `appium-config-schema.js`) beyond what the JSON Schema spec offers.  These
+ * are usable by extensions, as well.
+ */
+/**
+ * Splits a CSV string into an array
+ * @param {string} value
+ * @returns {string[]}
+ */
+function parseCsvLine(value) {
+    return value
+        .split(',')
+        .map((v) => v.trim())
+        .filter(Boolean);
+}
+/**
+ * Split a file by newline then calls {@link parseCsvLine} on each line.
+ * @param {string} value
+ * @returns {string[]}
+ */
+function parseCsvFile(value) {
+    return value
+        .split(/\r?\n/)
+        .map((v) => v.trim())
+        .filter(Boolean)
+        .flatMap(parseCsvLine);
+}
+/**
+ * Namespace containing _transformers_ for CLI arguments.  "Validators" and
+ * "formatters" do not actually modify the value, but these do.
+ *
+ * Use case is for when the config file can accept e.g., a `string[]`, but the
+ * CLI can only take a `string` (as `argparse` seems to be limited in that
+ * fashion; it also cannot understand an argument having multiple types).
+ *
+ * For example, the `csv` transform takes a `string` and returns a `string[]` by
+ * splitting it by comma--_or_ if that `string` happens to be a
+ * filepath--reading the file as a `.csv`.
+ *
+ * This contains some copy-pasted code from `lib/cli/parser-helpers.js`, which was
+ * obliterated.
+ */
+exports.transformers = {
+    /**
+     * Given a CSV-style string or pathname, parse it into an array.
+     * The file can also be split on newlines.
+     * @param {string} csvOrPath
+     * @returns {string[]}
+     */
+    csv: (csvOrPath) => {
+        let csv = csvOrPath;
+        let loadedFromFile = false;
+        // since this value could be a single string (no commas) _or_ a pathname, we will need
+        // to attempt to parse it as a file _first_.
+        if ((0, fs_1.existsSync)(csvOrPath)) {
+            try {
+                csv = (0, fs_1.readFileSync)(csvOrPath, 'utf8');
+            }
+            catch (err) {
+                throw new argparse_1.ArgumentTypeError(`Could not read file '${csvOrPath}': ${err.message}`);
+            }
+            loadedFromFile = true;
+        }
+        try {
+            return loadedFromFile ? parseCsvFile(csv) : parseCsvLine(csv);
+        }
+        catch (err) {
+            const msg = loadedFromFile
+                ? `The provided value of '${csvOrPath}' must be a valid CSV`
+                : `Must be a comma-delimited string, e.g., "foo,bar,baz"`;
+            throw new TypeError(`${msg}. Original error: ${err.message}`);
+        }
+    },
+    /**
+     * Parse a string which could be a path to a JSON file or a JSON string.
+     * @param {string} jsonOrPath
+     * @returns {object}
+     */
+    json: (jsonOrPath) => {
+        let json = jsonOrPath;
+        let loadedFromFile = false;
+        if ((0, fs_1.existsSync)(jsonOrPath)) {
+            try {
+                // use synchronous file access, as `argparse` provides no way of either
+                // awaiting or using callbacks. This step happens in startup, in what is
+                // effectively command-line code, so nothing is blocked in terms of
+                // sessions, so holding up the event loop does not incur the usual
+                // drawbacks.
+                json = (0, fs_1.readFileSync)(jsonOrPath, 'utf8');
+            }
+            catch (err) {
+                throw new argparse_1.ArgumentTypeError(`Could not read file '${jsonOrPath}': ${err.message}`);
+            }
+            loadedFromFile = true;
+        }
+        try {
+            const result = JSON.parse(json);
+            if (!lodash_1.default.isPlainObject(result)) {
+                throw new Error(`'${lodash_1.default.truncate(result, { length: 100 })}' is not an object`);
+            }
+            return result;
+        }
+        catch (e) {
+            const msg = loadedFromFile
+                ? `The provided value of '${jsonOrPath}' must be a valid JSON`
+                : `The provided value must be a valid JSON`;
+            throw new TypeError(`${msg}. Original error: ${e.message}`);
+        }
+    },
+};
+//# sourceMappingURL=cli-transformers.js.map

package/build/lib/schema/cli-transformers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-transformers.js","sourceRoot":"","sources":["../../../lib/schema/cli-transformers.js"],"names":[],"mappings":";;;;;;AAAA,uCAA2C;AAC3C,2BAA4C;AAC5C,oDAAuB;AAEvB;;;;;;;GAOG;AAEH;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAK;IACzB,OAAO,KAAK;SACT,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAK;IACzB,OAAO,KAAK;SACT,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC;SACf,OAAO,CAAC,YAAY,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACU,QAAA,YAAY,GAAG;IAC1B;;;;;OAKG;IACH,GAAG,EAAE,CAAC,SAAS,EAAE,EAAE;QACjB,IAAI,GAAG,GAAG,SAAS,CAAC;QACpB,IAAI,cAAc,GAAG,KAAK,CAAC;QAC3B,sFAAsF;QACtF,4CAA4C;QAC5C,IAAI,IAAA,eAAU,EAAC,SAAS,CAAC,EAAE;YACzB,IAAI;gBACF,GAAG,GAAG,IAAA,iBAAY,EAAC,SAAS,EAAE,MAAM,CAAC,CAAC;aACvC;YAAC,OAAO,GAAG,EAAE;gBACZ,MAAM,IAAI,4BAAiB,CAAC,wBAAwB,SAAS,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;aACnF;YACD,cAAc,GAAG,IAAI,CAAC;SACvB;QAED,IAAI;YACF,OAAO,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;SAC/D;QAAC,OAAO,GAAG,EAAE;YACZ,MAAM,GAAG,GAAG,cAAc;gBACxB,CAAC,CAAC,0BAA0B,SAAS,uBAAuB;gBAC5D,CAAC,CAAC,uDAAuD,CAAC;YAC5D,MAAM,IAAI,SAAS,CAAC,GAAG,GAAG,qBAAqB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;SAC/D;IACH,CAAC;IAED;;;;OAIG;IACH,IAAI,EAAE,CAAC,UAAU,EAAE,EAAE;QACnB,IAAI,IAAI,GAAG,UAAU,CAAC;QACtB,IAAI,cAAc,GAAG,KAAK,CAAC;QAC3B,IAAI,IAAA,eAAU,EAAC,UAAU,CAAC,EAAE;YAC1B,IAAI;gBACF,uEAAuE;gBACvE,wEAAwE;gBACxE,mEAAmE;gBACnE,kEAAkE;gBAClE,aAAa;gBACb,IAAI,GAAG,IAAA,iBAAY,EAAC,UAAU,EAAE,MAAM,CAAC,CAAC;aACzC;YAAC,OAAO,GAAG,EAAE;gBACZ,MAAM,IAAI,4BAAiB,CAAC,wBAAwB,UAAU,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;aACpF;YACD,cAAc,GAAG,IAAI,CAAC;SACvB;QACD,IAAI;YACF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,CAAC,gBAAC,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE;gBAC5B,MAAM,IAAI,KAAK,CAAC,IAAI,gBAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAC,MAAM,EAAE,GAAG,EAAC,CAAC,oBAAoB,CAAC,CAAC;aAC5E;YACD,OAAO,MAAM,CAAC;SACf;QAAC,OAAO,CAAC,EAAE;YACV,MAAM,GAAG,GAAG,cAAc;gBACxB,CAAC,CAAC,0BAA0B,UAAU,wBAAwB;gBAC9D,CAAC,CAAC,yCAAyC,CAAC;YAC9C,MAAM,IAAI,SAAS,CAAC,GAAG,GAAG,qBAAqB,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;SAC7D;IACH,CAAC;CACF,CAAC"}

package/build/lib/schema/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./schema";
+export * from "./cli-args";
+//# sourceMappingURL=index.d.ts.map

package/build/lib/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/schema/index.js"],"names":[],"mappings":""}

package/build/lib/schema/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./schema"), exports);
+__exportStar(require("./cli-args"), exports);
+//# sourceMappingURL=index.js.map

package/build/lib/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/schema/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,6CAA2B"}

package/build/lib/schema/keywords.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Collection of keyword definitions to add to the singleton `Ajv` instance.
+ * @type {Record<string,KeywordDefinition>}
+ */
+export const keywords: Record<string, KeywordDefinition>;
+/**
+ * These are the valid values for the `appiumCliTransformer` keyword.
+ * Unfortunately, TS cannot infer this in a JS context.  In TS, we'd use
+ * `as const` when defining `argTransformers`, then get `keyof typeof argTransformers`. alas.
+ */
+export type AppiumCliTransformerName = 'csv' | 'json';
+/**
+ * These are the custom keywords that Appium recognizes.
+ */
+export type AppiumJSONSchemaKeywords = {
+    appiumCliDest?: string | undefined;
+    appiumCliDescription?: string | undefined;
+    appiumCliAliases?: string[] | undefined;
+    appiumCliIgnored?: boolean | undefined;
+    appiumCliTransformer?: AppiumCliTransformerName | undefined;
+    appiumDeprecated?: boolean | undefined;
+};
+export type KeywordDefinition = import('ajv').KeywordDefinition;
+//# sourceMappingURL=keywords.d.ts.map

package/build/lib/schema/keywords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keywords.d.ts","sourceRoot":"","sources":["../../../lib/schema/keywords.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,uBAFU,OAAO,MAAM,EAAC,iBAAiB,CAAC,CA4GxC;;;;;;uCAMW,KAAK,GAAC,MAAM;;;;;;;;;;;;gCAgBZ,OAAO,KAAK,EAAE,iBAAiB"}

package/build/lib/schema/keywords.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keywords = void 0;
+const cli_transformers_1 = require("./cli-transformers");
+/**
+ * Collection of keyword definitions to add to the singleton `Ajv` instance.
+ * @type {Record<string,KeywordDefinition>}
+ */
+exports.keywords = {
+    /**
+     * Keyword to provide a list of command alias names for the CLI.
+     *
+     * If defined, there must be at least one item in the array and it must be non-empty.
+     * All items in the array must be unique.
+     *
+     * @todo Avoid alias collisions!
+     * @type {KeywordDefinition}
+     * @example
+     * {appiumCliAliases: ['B', 'bobby', 'robert']}
+     */
+    appiumCliAliases: {
+        keyword: 'appiumCliAliases',
+        metaSchema: {
+            type: 'array',
+            items: {
+                type: 'string',
+                minLength: 1,
+            },
+            minItems: 1,
+            uniqueItems: true,
+            description: 'List of aliases for the argument. Aliases shorter than three (3) characters will be prefixed with a single dash; otherwise two (2).',
+        },
+    },
+    /**
+     * Keyword to provide the name of the property in the destination (parsed
+     * args) object. By default, this value will be whatever the property name is,
+     * but camel-cased. If a flag needs something _other_ than just camel-casing,
+     * use this.
+     * @type {KeywordDefinition}
+     * @example
+     * // for prop 'no-color'
+     * {appiumCliDest: 'NOCOLOR'} // value will be stored as property `NOCOLOR` instead of `noColor`
+     */
+    appiumCliDest: {
+        keyword: 'appiumCliDest',
+        metaSchema: {
+            type: 'string',
+            minLength: 1,
+            description: 'Name of the associated property in the parsed CLI arguments object',
+        },
+    },
+    /**
+     * CLI-specific description of the property.  Sometimes the allowed type can
+     * be different enough on the CLI that providing a description written for a
+     * config file context wouldn't make sense.
+     * @type {KeywordDefinition}
+     * @example
+     * {appiumCliDescription: 'This is a comma-delimited string, but in the config file it is an array'}
+     */
+    appiumCliDescription: {
+        keyword: 'appiumCliDescription',
+        schemaType: 'string',
+        metaSchema: {
+            type: 'string',
+            minLength: 1,
+            description: 'Description to provide in the --help text of the CLI. Overrides `description`',
+        },
+    },
+    /**
+     * Transformers for CLI args. These usually take strings then do something with them, like
+     * read a file or parse further.
+     * @type {KeywordDefinition}
+     */
+    appiumCliTransformer: {
+        keyword: 'appiumCliTransformer',
+        metaSchema: {
+            type: 'string',
+            enum: Object.keys(cli_transformers_1.transformers),
+            description: 'The name of a custom transformer to run against the value as provided via the CLI.',
+        },
+    },
+    /**
+     * Flag to tell Appium to _not_ provide this property as a CLI argument.
+     * @type {KeywordDefinition}
+     */
+    appiumCliIgnored: {
+        keyword: 'appiumCliIgnored',
+        metaSchema: {
+            type: 'boolean',
+            description: 'If `true`, Appium will not provide this property as a CLI argument. This is NOT the same as a "hidden" argument.',
+            enum: [true],
+        },
+    },
+    /**
+     * Mark this property as deprecated.
+     * @type {KeywordDefinition}
+     */
+    appiumDeprecated: {
+        keyword: 'appiumDeprecated',
+        metaSchema: {
+            type: 'boolean',
+            description: 'If `true`, this property will be displayed as "deprecated" to the user',
+            enum: [true],
+            $comment: 'JSON schema draft-2019-09 keyword `deprecated` serves the same purpose. This keyword should itself be deprecated if we move to draft-2019-09!',
+        },
+    },
+};
+/**
+ * These are the valid values for the `appiumCliTransformer` keyword.
+ * Unfortunately, TS cannot infer this in a JS context.  In TS, we'd use
+ * `as const` when defining `argTransformers`, then get `keyof typeof argTransformers`. alas.
+ * @typedef {'csv'|'json'} AppiumCliTransformerName
+ */
+/**
+ * These are the custom keywords that Appium recognizes.
+ *
+ * @typedef AppiumJSONSchemaKeywords
+ * @property {string} [appiumCliDest]
+ * @property {string} [appiumCliDescription]
+ * @property {string[]} [appiumCliAliases]
+ * @property {boolean} [appiumCliIgnored]
+ * @property {AppiumCliTransformerName} [appiumCliTransformer]
+ * @property {boolean} [appiumDeprecated]
+ */
+/**
+ * @typedef {import('ajv').KeywordDefinition} KeywordDefinition
+ */
+//# sourceMappingURL=keywords.js.map

package/build/lib/schema/keywords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keywords.js","sourceRoot":"","sources":["../../../lib/schema/keywords.js"],"names":[],"mappings":";;;AAAA,yDAAgD;AAEhD;;;GAGG;AACU,QAAA,QAAQ,GAAG;IACtB;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE;QAChB,OAAO,EAAE,kBAAkB;QAC3B,UAAU,EAAE;YACV,IAAI,EAAE,OAAO;YACb,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,SAAS,EAAE,CAAC;aACb;YACD,QAAQ,EAAE,CAAC;YACX,WAAW,EAAE,IAAI;YACjB,WAAW,EACT,qIAAqI;SACxI;KACF;IACD;;;;;;;;;OASG;IACH,aAAa,EAAE;QACb,OAAO,EAAE,eAAe;QACxB,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,CAAC;YACZ,WAAW,EAAE,oEAAoE;SAClF;KACF;IAED;;;;;;;OAOG;IACH,oBAAoB,EAAE;QACpB,OAAO,EAAE,sBAAsB;QAC/B,UAAU,EAAE,QAAQ;QACpB,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,CAAC;YACZ,WAAW,EAAE,+EAA+E;SAC7F;KACF;IAED;;;;OAIG;IACH,oBAAoB,EAAE;QACpB,OAAO,EAAE,sBAAsB;QAC/B,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,+BAAY,CAAC;YAC/B,WAAW,EACT,oFAAoF;SACvF;KACF;IAED;;;OAGG;IACH,gBAAgB,EAAE;QAChB,OAAO,EAAE,kBAAkB;QAC3B,UAAU,EAAE;YACV,IAAI,EAAE,SAAS;YACf,WAAW,EACT,kHAAkH;YACpH,IAAI,EAAE,CAAC,IAAI,CAAC;SACb;KACF;IAED;;;OAGG;IACH,gBAAgB,EAAE;QAChB,OAAO,EAAE,kBAAkB;QAC3B,UAAU,EAAE;YACV,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,wEAAwE;YACrF,IAAI,EAAE,CAAC,IAAI,CAAC;YACZ,QAAQ,EACN,+IAA+I;SAClJ;KACF;CACF,CAAC;AAEF;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AAEH;;GAEG"}

package/build/lib/schema/schema.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Key/value pairs go in... but they don't come out.
+ *
+ * @template K,V
+ * @extends {Map<K,V>}
+ */
+export class RoachHotelMap<K, V> extends Map<K, V> {
+    constructor();
+    constructor(entries?: readonly (readonly [K, V])[] | null | undefined);
+    constructor();
+    constructor(iterable?: Iterable<readonly [K, V]> | null | undefined);
+}
+/**
+ * Extensions that an extension schema file can have.
+ */
+export const ALLOWED_SCHEMA_EXTENSIONS: Readonly<Set<AllowedSchemaExtension>>;
+/**
+ * Thrown when the {@link AppiumSchema} instance has not yet been finalized, but
+ * the method called requires it.
+ */
+export class SchemaFinalizationError extends Error {
+    constructor();
+    /**
+     * @type {Readonly<string>}
+     */
+    code: Readonly<string>;
+}
+/**
+ * Thrown when a "unique" schema ID conflicts with an existing schema ID.
+ *
+ * This is likely going to be caused by attempting to register the same schema twice.
+ */
+export class SchemaNameConflictError extends Error {
+    /**
+     * @param {ExtensionType} extType
+     * @param {string} extName
+     */
+    constructor(extType: ExtensionType, extName: string);
+    /**
+     * @type {Readonly<string>}
+     */
+    code: Readonly<string>;
+    /**
+     * @type {Readonly<{extType: ExtensionType, extName: string}>}
+     */
+    data: Readonly<{
+        extType: ExtensionType;
+        extName: string;
+    }>;
+}
+/**
+ * Thrown when a schema ID was expected, but it doesn't exist on the {@link Ajv} instance.
+ */
+export class SchemaUnknownSchemaError extends ReferenceError {
+    /**
+     * @param {string} schemaId
+     */
+    constructor(schemaId: string);
+    /**
+     * @type {Readonly<string>}
+     */
+    code: Readonly<string>;
+    /**
+     * @type {Readonly<{schemaId: string}>}
+     */
+    data: Readonly<{
+        schemaId: string;
+    }>;
+}
+/**
+ * Thrown when a schema is provided, but it's of an unsupported type.
+ *
+ * "Valid" schemas which are unsupported include boolean schemas and async schemas
+ * (having a `true` `$async` property).
+ */
+export class SchemaUnsupportedSchemaError extends TypeError {
+    /**
+     * @param {any} schema
+     * @param {ExtensionType} extType
+     * @param {string} extName
+     */
+    constructor(schema: any, extType: ExtensionType, extName: string);
+    /**
+     * @type {Readonly<string>}
+     */
+    code: Readonly<string>;
+    /**
+     * @type {Readonly<{schema: any, extType: ExtensionType, extName: string}>}
+     */
+    data: Readonly<{
+        schema: any;
+        extType: ExtensionType;
+        extName: string;
+    }>;
+}
+/**
+ * Registers a schema from an extension.
+ *
+ * This is "fail-fast" in that the schema will immediately be validated against JSON schema draft-07 _or_ whatever the value of the schema's `$schema` prop is.
+ *
+ * Does _not_ add the schema to the `ajv` instance (this is done by {@link AppiumSchema.finalize}).
+ * @param {ExtensionType} extType - Extension type
+ * @param {string} extName - Unique extension name for `type`
+ * @param {SchemaObject} schema - Schema object
+ * @throws {SchemaNameConflictError} If the schema is an invalid
+ * @returns {void}
+ */
+export function registerSchema(extType: ExtensionType, extName: string, schema: SchemaObject): void;
+export function getAllArgSpecs(): RoachHotelMap<string, ArgSpec<any>>;
+/**
+ * Returns a {@link ArgSpec} for the given argument name.
+ * @param {string} name - CLI argument name
+ * @param {ExtensionType} [extType] - Extension type
+ * @param {string} [extName] - Extension name
+ * @returns {ArgSpec|undefined} ArgSpec or `undefined` if not found
+ */
+export function getArgSpec(name: string, extType?: import("@appium/types").ExtensionType | undefined, extName?: string | undefined): ArgSpec<any> | undefined;
+/**
+ * Returns `true` if the instance knows about an argument by the given `name`.
+ * @param {string} name - CLI argument name
+ * @param {ExtensionType} [extType] - Extension type
+ * @param {string} [extName] - Extension name
+ * @returns {boolean} `true` if such an {@link ArgSpec} exists
+ */
+export function hasArgSpec(name: string, extType?: import("@appium/types").ExtensionType | undefined, extName?: string | undefined): boolean;
+/**
+ * Return `true` if {@link AppiumSchema.finalize finalize} has been called
+ * successfully and {@link AppiumSchema.reset reset} has not been called since.
+ * @returns {boolean} If finalized
+ */
+export function isFinalized(): boolean;
+/**
+ * Call this when no more schemas will be registered.
+ *
+ * This does three things:
+ * 1. It combines all schemas from extensions into the Appium config schema,
+ *    then adds the result to the `Ajv` instance.
+ * 2. It adds schemas for _each_ argument/property for validation purposes.
+ *    The CLI uses these schemas to validate specific arguments.
+ * 3. The schemas are validated against JSON schema draft-07 (which is the
+ *    only one supported at this time)
+ *
+ * Any method in this instance that needs to interact with the `Ajv` instance
+ * will throw if this method has not been called.
+ *
+ * If the instance has already been finalized, this is a no-op.
+ * @public
+ * @throws {Error} If the schema is not valid
+ * @returns {Readonly<Record<string,StrictSchemaObject>>} Record of schema IDs to full schema objects
+ */
+export function finalizeSchema(): Readonly<Record<string, StrictSchemaObject>>;
+/**
+ * Resets this instance to its original state.
+ *
+ * - Removes all added schemas from the `Ajv` instance
+ * - Resets the map of {@link ArgSpec ArgSpecs}
+ * - Resets the map of registered schemas
+ * - Sets the {@link AppiumSchema._finalized _finalized} flag to `false`
+ *
+ * If you need to call {@link AppiumSchema.finalize} again, you'll want to call this first.
+ * @returns {void}
+ */
+export function resetSchema(): void;
+/**
+ * Given an object, validates it against the Appium config schema.
+ * If errors occur, the returned array will be non-empty.
+ * @param {any} value - The value (hopefully an object) to validate against the schema
+ * @param {string} [ref] - Schema ID or ref.
+ * @public
+ * @returns {import('ajv').ErrorObject[]} Array of errors, if any.
+ */
+export function validate(value: any, ref?: string | undefined): import('ajv').ErrorObject[];
+/**
+ * Retrieves the schema itself
+ * @public
+ * @param {string} [ref] - Schema ID
+ * @throws If the schema has not yet been finalized
+ * @returns {SchemaObject}
+ */
+export function getSchema(ref?: string | undefined): SchemaObject;
+/**
+ * Flatten schema into an array of `SchemaObject`s and associated
+ * {@link ArgSpec ArgSpecs}.
+ *
+ * Converts nested extension schemas to keys based on the extension type and
+ * name. Used when translating to `argparse` options or getting the list of
+ * default values (see {@link AppiumSchema.getDefaults}) for CLI or otherwise.
+ *
+ * The return value is an intermediate reprsentation used by `cli-args`
+ * module's `toParserArgs`, which converts the finalized schema to parameters
+ * used by `argparse`.
+ * @throws If {@link AppiumSchema.finalize} has not been called yet.
+ * @returns {FlattenedSchema}
+ */
+export function flattenSchema(): FlattenedSchema;
+/**
+ * Returns a `Record` of argument "dest" strings to default values.
+ *
+ * The "dest" string is the property name in object returned by
+ * `argparse.ArgumentParser['parse_args']`.
+ * @template {boolean|undefined} Flattened
+ * @param {Flattened} [flatten=true] - If `true`, flattens the returned object
+ * using "keypath"-style keys of the format `<extType>.<extName>.<argName>`.
+ * Otherwise, returns a nested object using `extType` and `extName` as
+ * properties. Base arguments (server arguments) are always at the top level.
+ * @returns {DefaultValues<Flattened>}
+ */
+export function getDefaultsForSchema<Flattened extends boolean | undefined>(flatten?: Flattened | undefined): DefaultValues<Flattened>;
+/**
+ * Returns a flattened Record of defaults for a specific extension. Keys will
+ * be of format `<argName>`.
+ * @param {ExtensionType} extType - Extension type
+ * @param {string} extName - Extension name
+ * @returns {Record<string,ArgSpecDefaultValue>}
+ */
+export function getDefaultsForExtension(extType: ExtensionType, extName: string): Record<string, ArgSpecDefaultValue>;
+/**
+ * Returns `true` if `filename`'s file extension is allowed (in {@link ALLOWED_SCHEMA_EXTENSIONS}).
+ * @param {import('type-fest').LiteralUnion<AllowedSchemaExtension, string>} filename
+ * @returns {boolean}
+ */
+export function isAllowedSchemaFileExtension(filename: import('type-fest').LiteralUnion<AllowedSchemaExtension, string>): boolean;
+/**
+ * Appium only supports schemas that are plain objects; not arrays.
+ */
+export type SchemaObject = import("ajv").SchemaObject & {
+    [key: number]: never;
+};
+export type ExtensionType = import('@appium/types').ExtensionType;
+/**
+ * An object having property `additionalProperties: false`
+ */
+export type StrictProp = {
+    additionalProperties: false;
+};
+/**
+ * A {@link SchemaObject } with `additionalProperties: false`
+ */
+export type StrictSchemaObject = SchemaObject & StrictProp;
+/**
+ * A list of schemas associated with properties and their corresponding {@link ArgSpec } objects.
+ *
+ * Intermediate data structure used when converting the entire schema down to CLI arguments.
+ */
+export type FlattenedSchema = {
+    schema: SchemaObject;
+    argSpec: ArgSpec<any>;
+}[];
+export type ArgSpecDefaultValue = ArgSpec<any>['defaultValue'];
+/**
+ * e.g. `{driver: {foo: 'bar'}}` where `foo` is the arg name and `bar` is the default value.
+ */
+export type NestedArgSpecDefaultValue = Record<string, Record<string, ArgSpecDefaultValue>>;
+/**
+ * Helper type for the return value of {@link AppiumSchema.getDefaults }
+ */
+export type DefaultValues<Flattened extends boolean | undefined> = Record<string, Flattened extends true ? ArgSpecDefaultValue : ArgSpecDefaultValue | NestedArgSpecDefaultValue>;
+export type AllowedSchemaExtension = '.json' | '.js' | '.cjs';
+import { ArgSpec } from "./arg-spec";
+//# sourceMappingURL=schema.d.ts.map

package/build/lib/schema/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../lib/schema/schema.js"],"names":[],"mappings":"AASA;;;;;GAKG;AACH;IAyE2B,cAE1B;IAAE,uEAAyE;IA+E9C,cAEpB;IAAA,qEACP;CAtIF;AAED;;GAEG;AACH,8EAEE;AAyfF;;;GAGG;AACH;IAME,cAEC;IAPD;;OAEG;IACH,MAFU,SAAS,MAAM,CAAC,CAEa;CAKxC;AAED;;;;GAIG;AACH;IAWE;;;OAGG;IACH,qBAHW,aAAa,WACb,MAAM,EAKhB;IAjBD;;OAEG;IACH,MAFU,SAAS,MAAM,CAAC,CAEc;IAExC;;OAEG;IACH,MAFU,SAAS;QAAC,OAAO,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC,CAExD;CAUN;AAED;;GAEG;AACH;IAWE;;OAEG;IACH,sBAFW,MAAM,EAKhB;IAhBD;;OAEG;IACH,MAFU,SAAS,MAAM,CAAC,CAEe;IAEzC;;OAEG;IACH,MAFU,SAAS;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC,CAEjC;CASN;AAED;;;;;GAKG;AACH;IAWE;;;;OAIG;IACH,oBAJW,GAAG,WACH,aAAa,WACb,MAAM,EAyBhB;IAtCD;;OAEG;IACH,MAFU,SAAS,MAAM,CAAC,CAEmB;IAE7C;;OAEG;IACH,MAFU,SAAS;QAAC,MAAM,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC,CAErE;CA+BN;AA5WC;;;;;;;;;;;GAWG;AACH,wCANW,aAAa,WACb,MAAM,UACN,YAAY,GAEV,IAAI,CAmBhB;AAzKD,sEAEC;AAyKD;;;;;;GAMG;AACH,iCALW,MAAM,8FAGJ,eAAQ,SAAS,CAI7B;AAED;;;;;;GAMG;AACH,iCALW,MAAM,8FAGJ,OAAO,CAInB;AAxMD;;;;GAIG;AACH,+BAFa,OAAO,CAInB;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,kCAFa,SAAS,OAAO,MAAM,EAAC,kBAAkB,CAAC,CAAC,CAsEvD;AAuBD;;;;;;;;;;GAUG;AACH,+BAFa,IAAI,CAehB;AA8ND;;;;;;;GAOG;AACH,gCALW,GAAG,6BAGD,OAAO,KAAK,EAAE,WAAW,EAAE,CAKvC;AAxCD;;;;;;GAMG;AACH,qDAFa,YAAY,CAIxB;AAjFD;;;;;;;;;;;;;GAaG;AACH,iDAwDC;AAxID;;;;;;;;;;;GAWG;AACH,uIA8BC;AAED;;;;;;GAMG;AACH,iDAJW,aAAa,WACb,MAAM,GACJ,OAAO,MAAM,EAAC,mBAAmB,CAAC,CAe9C;AAoHD;;;;GAIG;AACH,uDAHW,OAAO,WAAW,EAAE,YAAY,CAAC,sBAAsB,EAAE,MAAM,CAAC,GAC9D,OAAO,CAMnB;;;;;;;4BAoJU,OAAO,eAAe,EAAE,aAAa;;;;;0BAMpC,KAAK;;;;;iCAKN,YAAY,GAAG,UAAU;;;;;;8BAOxB;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,OAAO,eAAS;CAAC,EAAE;kCAI3C,aAAQ,cAAc,CAAC;;;;wCAKvB,OAAO,MAAM,EAAC,OAAO,MAAM,EAAC,mBAAmB,CAAC,CAAC;;;;mEAMjD,OAAO,MAAM,EAAC,SAAS,SAAS,IAAI,GAAG,mBAAmB,GAAG,mBAAmB,GAAG,yBAAyB,CAAC;qCAI7G,OAAO,GAAC,KAAK,GAAC,MAAM"}