@appium/typedoc-plugin-appium/build/lib/guards.js

TypeDoc plugin for Appium & its extensions

"use strict";
/**
 * A bunch of type guards. Because here is a place to put all of them.
 * @module
 */
Object.defineProperty(exports, "__esModule", { value: true });
exports.isParameterReflection = exports.isBasePluginConstructorDeclarationReflection = exports.isConstructorDeclarationReflection = exports.isCallSignatureReflectionWithArity = exports.isCallSignatureReflection = exports.isClassDeclarationReflection = exports.isCommandMethodDeclarationReflection = exports.isExternalDriverDeclarationReflection = exports.isInterfaceDeclarationReflection = exports.isExecMethodDefParamsPropDeclarationReflection = exports.isMethodDefParamsPropDeclarationReflection = exports.isExecMethodData = exports.isCommandPropDeclarationReflection = exports.isAllowedHTTPMethod = exports.isHTTPMethodDeclarationReflection = exports.isReflectionWithReflectedType = exports.isMethodMapDeclarationReflection = exports.isPropertyKind = exports.isBaseDriverDeclarationReflection = exports.isRoutePropDeclarationReflection = exports.isMethodDefParamNamesDeclarationReflection = exports.isExecMethodDefReflection = exports.isTupleType = exports.isLiteralType = exports.isTypeOperatorType = exports.isReflectionType = exports.isAppiumTypesReflection = exports.isParentReflection = exports.isDeclarationReflection = void 0;
const typedoc_1 = require("typedoc");
const converter_1 = require("./converter");
/**
 * Set of HTTP methods allowed by WebDriver; see {@linkcode AllowedHttpMethod}
 */
const ALLOWED_HTTP_METHODS = new Set([
    'GET',
    'POST',
    'DELETE',
]);
/**
 * Type guard for {@linkcode DeclarationReflection}
 * @param value any value
 */
function isDeclarationReflection(value) {
    return value instanceof typedoc_1.DeclarationReflection;
}
exports.isDeclarationReflection = isDeclarationReflection;
function isParentReflection(value) {
    return (value && (value instanceof typedoc_1.DeclarationReflection || value.isProject()));
}
exports.isParentReflection = isParentReflection;
function isAppiumTypesReflection(value) {
    return isParentReflection(value) && value.name === converter_1.NAME_TYPES_MODULE;
}
exports.isAppiumTypesReflection = isAppiumTypesReflection;
/**
 * Type guard for {@linkcode ReflectionType}
 * @param value any value
 */
function isReflectionType(value) {
    return value instanceof typedoc_1.ReflectionType;
}
exports.isReflectionType = isReflectionType;
/**
 * Type guard for {@linkcode TypeOperatorType}
 * @param value any value
 */
function isTypeOperatorType(value) {
    return value instanceof typedoc_1.TypeOperatorType;
}
exports.isTypeOperatorType = isTypeOperatorType;
/**
 * Type guard for {@linkcode LiteralType}
 * @param value any value
 */
function isLiteralType(value) {
    return value instanceof typedoc_1.LiteralType;
}
exports.isLiteralType = isLiteralType;
/**
 * Type guard for {@linkcode TupleType}
 * @param value any value
 */
function isTupleType(value) {
    return value instanceof typedoc_1.TupleType;
}
exports.isTupleType = isTupleType;
/**
 * Type guard for a {@linkcode DeclarationReflectionWithReflectedType} corresponding to
 * the `executeMethodMap` static property of an extension class.
 * @param value any
 */
function isExecMethodDefReflection(value) {
    return (isReflectionWithReflectedType(value) &&
        value.name === converter_1.NAME_EXECUTE_METHOD_MAP &&
        value.flags.isStatic);
}
exports.isExecMethodDefReflection = isExecMethodDefReflection;
/**
 * Type guard for a {@linkcode MethodDefParamNamesDeclarationReflection} corresponding to a list of required or optional parameters within a command or execute method definition.
 * @param value any value
 */
function isMethodDefParamNamesDeclarationReflection(value) {
    return (isDeclarationReflection(value) &&
        value.kindOf(typedoc_1.ReflectionKind.Property) &&
        isTypeOperatorType(value.type) &&
        isTupleType(value.type.target) &&
        value.type.target.elements.every(isLiteralType));
}
exports.isMethodDefParamNamesDeclarationReflection = isMethodDefParamNamesDeclarationReflection;
/**
 * Type guard for a {@linkcode PropDeclarationReflection} corresponding to some property of a constant object.
 * @param value any value
 */
function isRoutePropDeclarationReflection(value) {
    return isReflectionWithReflectedType(value) && isPropertyKind(value);
}
exports.isRoutePropDeclarationReflection = isRoutePropDeclarationReflection;
/**
 * Type guard for a {@linkcode BaseDriverDeclarationReflection} corresponding to the `@appium/base-driver` module (_not_ the class).
 * @param value any value
 */
function isBaseDriverDeclarationReflection(value) {
    return (isParentReflection(value) &&
        value.name === converter_1.NAME_BUILTIN_COMMAND_MODULE &&
        value.kindOf(typedoc_1.ReflectionKind.Module | typedoc_1.ReflectionKind.Project));
}
exports.isBaseDriverDeclarationReflection = isBaseDriverDeclarationReflection;
/**
 * Type guard for a property of an object (a {@linkcode Reflection} having kind {@linkcode ReflectionKind.Property}).
 * @param value any value
 */
function isPropertyKind(value) {
    return value instanceof typedoc_1.Reflection && value.kindOf(typedoc_1.ReflectionKind.Property);
}
exports.isPropertyKind = isPropertyKind;
/**
 * Type guard for a {@linkcode MethodMapDeclarationReflection} corresponding to the `newMethodMap` static property of an extension class _or_ the `METHOD_MAP` export within `@appium/base-driver`.
 *
 * Note that the type does not care about the `isStatic` flag, but this guard does.
 * @param value any value
 */
function isMethodMapDeclarationReflection(value) {
    return (isReflectionWithReflectedType(value) &&
        ((value.name === converter_1.NAME_NEW_METHOD_MAP && value.flags.isStatic) || value.name === converter_1.NAME_METHOD_MAP));
}
exports.isMethodMapDeclarationReflection = isMethodMapDeclarationReflection;
/**
 * Type guard for a {@linkcode DeclarationReflectionWithReflectedType} a declaration reflection having a reflection type.
 *
 * I don't know what that means, exactly, but there it is.
 * @param value any value
 */
function isReflectionWithReflectedType(value) {
    return isDeclarationReflection(value) && isReflectionType(value.type);
}
exports.isReflectionWithReflectedType = isReflectionWithReflectedType;
function isHTTPMethodDeclarationReflection(value) {
    return (isReflectionWithReflectedType(value) && isPropertyKind(value) && isAllowedHTTPMethod(value.name));
}
exports.isHTTPMethodDeclarationReflection = isHTTPMethodDeclarationReflection;
/**
 * Type guard for an {@linkcode AllowedHttpMethod}
 *
 * @param value any value
 */
function isAllowedHTTPMethod(value) {
    return ALLOWED_HTTP_METHODS.has(value);
}
exports.isAllowedHTTPMethod = isAllowedHTTPMethod;
/**
 * Type guard for a {@linkcode CommandPropDeclarationReflection} corresponding to the `command` property of a {@linkcode @appium/types#MethodDef} object contained within a {@linkcode @appium/types#MethodMap}.
 * @param value any value
 */
function isCommandPropDeclarationReflection(value) {
    return isDeclarationReflection(value) && isLiteralType(value.type) && value.name === converter_1.NAME_COMMAND;
}
exports.isCommandPropDeclarationReflection = isCommandPropDeclarationReflection;
/**
 * Type guard for a {@linkcode ExecMethodData} derived from a {@linkcode @appium/types#ExecuteMethodMap} object.
 * @param value any value
 */
function isExecMethodData(value) {
    return value && typeof value === 'object' && value.script;
}
exports.isExecMethodData = isExecMethodData;
/**
 * Type guard for a {@linkcode MethodDefParamsPropDeclarationReflection} corresponding to the `params` prop of a `MethodDef`
 * @param value any value
 */
function isMethodDefParamsPropDeclarationReflection(value) {
    return isReflectionWithReflectedType(value) && value.name === converter_1.NAME_PAYLOAD_PARAMS;
}
exports.isMethodDefParamsPropDeclarationReflection = isMethodDefParamsPropDeclarationReflection;
/**
 * Type guard for a {@linkcode ExecMethodDefParamsPropDeclarationReflection} corresponding to the `payloadParams` prop of an `ExecuteMethodDef`.
 * @param value any value
 */
function isExecMethodDefParamsPropDeclarationReflection(value) {
    return isReflectionWithReflectedType(value) && value.name === converter_1.NAME_PARAMS;
}
exports.isExecMethodDefParamsPropDeclarationReflection = isExecMethodDefParamsPropDeclarationReflection;
/**
 * Type guard for a {@linkcode InterfaceDeclarationReflection} corresponding to a TS interface.
 * @param value any value
 */
function isInterfaceDeclarationReflection(value) {
    return isDeclarationReflection(value) && value.kindOf(typedoc_1.ReflectionKind.Interface);
}
exports.isInterfaceDeclarationReflection = isInterfaceDeclarationReflection;
/**
 * Type guard for a {@linkcode ExternalDriverDeclarationReflection} which is the `ExternalDriver`
 * interface defined in `@appium/types`.
 * @param value any value
 */
function isExternalDriverDeclarationReflection(value) {
    return isInterfaceDeclarationReflection(value) && value.name === converter_1.NAME_EXTERNAL_DRIVER;
}
exports.isExternalDriverDeclarationReflection = isExternalDriverDeclarationReflection;
/**
 * Type guard for an {@linkcode CommandMethodDeclarationReflection}, which is _potentially_ a method
 * for a command.  Not all async methods in driver classes are mapped to commands, of course!
 *
 * A command method cannot be static, but it can be an actual (async) function or a reference to an
 * (async) function; just depends how the code is written.  Either way, this asserts there's a
 * call signature returning a `Promise`.
 * @param value
 */
function isCommandMethodDeclarationReflection(value) {
    if (!isDeclarationReflection(value) ||
        !value.kindOf(typedoc_1.ReflectionKind.Method | typedoc_1.ReflectionKind.Property) ||
        value.flags.isStatic) {
        return false;
    }
    const signatures = isReflectionType(value.type)
        ? value.type.declaration.getAllSignatures()
        : value.getAllSignatures();
    return Boolean(signatures?.find((sig) => sig.type instanceof typedoc_1.ReferenceType && sig.type.name === 'Promise'));
}
exports.isCommandMethodDeclarationReflection = isCommandMethodDeclarationReflection;
/**
 * Type guard for a {@linkcode ClassDeclarationReflection} which is just a {@linkcode DeclarationReflection}
 * with a `kind` of {@linkcode ReflectionKind.Class}.
 * @param value any value
 */
function isClassDeclarationReflection(value) {
    return Boolean(isDeclarationReflection(value) && value.kindOf(typedoc_1.ReflectionKind.Class));
}
exports.isClassDeclarationReflection = isClassDeclarationReflection;
/**
 * Type guard for a {@linkcode CallSignatureReflection} which is just a
 * {@linkcode SignatureReflection} with kind {@linkcode ReflectionKind.CallSignature}.
 * @param value any value
 */
function isCallSignatureReflection(value) {
    return Boolean(value instanceof typedoc_1.SignatureReflection && value.kindOf(typedoc_1.ReflectionKind.CallSignature));
}
exports.isCallSignatureReflection = isCallSignatureReflection;
/**
 * Type guard for a {@linkcode CallSignatureReflectionWithArity}, which is a
 * {@linkcode CallSignatureReflection} with an arity greater than zero.
 * @param value any value
 */
function isCallSignatureReflectionWithArity(value) {
    return Boolean(isCallSignatureReflection(value) && value.parameters?.length);
}
exports.isCallSignatureReflectionWithArity = isCallSignatureReflectionWithArity;
/**
 * Guard for {@linkcode ConstructorDeclarationReflection}
 * @param value any
 */
function isConstructorDeclarationReflection(value) {
    return isDeclarationReflection(value) && value.kindOf(typedoc_1.ReflectionKind.Constructor);
}
exports.isConstructorDeclarationReflection = isConstructorDeclarationReflection;
/**
 * Guard for the constructor of a class extending `BasePlugin`
 * @param value
 */
function isBasePluginConstructorDeclarationReflection(value) {
    if (!(isDeclarationReflection(value) && value.kindOf(typedoc_1.ReflectionKind.Constructor))) {
        return false;
    }
    const ref = value.inheritedFrom instanceof typedoc_1.ReferenceType
        ? value.inheritedFrom
        : value.overwrites instanceof typedoc_1.ReferenceType
            ? value.overwrites
            : undefined;
    return ref?.name === `${converter_1.NAME_BASE_PLUGIN}.constructor`;
}
exports.isBasePluginConstructorDeclarationReflection = isBasePluginConstructorDeclarationReflection;
/**
 * Guard for {@linkcode ParameterReflection}
 * @param value any
 */
function isParameterReflection(value) {
    return value instanceof typedoc_1.ParameterReflection;
}
exports.isParameterReflection = isParameterReflection;
//# sourceMappingURL=guards.js.map