@appium/typedoc-plugin-appium
Version:
TypeDoc plugin for Appium & its extensions
256 lines • 10.3 kB
JavaScript
;
/**
* Utilities for the various converters.
* @module
*/
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.cloneCallSignatureReflection = exports.createNewParamRefls = exports.cloneTypeParameterReflection = exports.cloneParameterReflection = exports.convertRequiredCommandParams = exports.convertCommandParams = exports.convertOptionalCommandParams = exports.findCommandMethodsInReflection = exports.filterChildrenByKind = exports.findChildByNameAndGuard = exports.findChildByGuard = exports.filterChildrenByGuard = exports.findParentReflectionByName = void 0;
const lodash_1 = __importDefault(require("lodash"));
const typedoc_1 = require("typedoc");
const guards_1 = require("../guards");
const comment_1 = require("./comment");
const external_1 = require("./external");
function findParentReflectionByName(project, name) {
return project.name === name ? project : project.getChildByName(name);
}
exports.findParentReflectionByName = findParentReflectionByName;
/**
* Filters children by a type guard
* @param refl - Reflection to check
* @param guard - Type guard function
* @returns Filtered children, if any
* @internal
*/
function filterChildrenByGuard(refl, guard) {
return (((0, guards_1.isReflectionWithReflectedType)(refl)
? refl.type.declaration.children?.filter(guard)
: refl.children?.filter(guard)) ?? []);
}
exports.filterChildrenByGuard = filterChildrenByGuard;
/**
* Finds a child of a reflection by type guard
* @param refl - Reflection to check
* @param guard - Guard function to check child
* @returns Child if found, `undefined` otherwise
* @internal
*/
function findChildByGuard(refl, guard) {
return ((0, guards_1.isReflectionWithReflectedType)(refl)
? refl.type.declaration.children?.find(guard)
: refl.children?.find(guard));
}
exports.findChildByGuard = findChildByGuard;
/**
* Finds a child of a reflection by name and type guard
* @param refl - Reflection to check
* @param name - Name of child
* @param guard - Guard function to check child
* @returns Child if found, `undefined` otherwise
* @internal
*/
function findChildByNameAndGuard(refl, name, guard) {
const predicate = (child) => child.name === name && guard(child);
return ((0, guards_1.isReflectionWithReflectedType)(refl)
? refl.type.declaration.children?.find(predicate)
: refl.children?.find(predicate));
}
exports.findChildByNameAndGuard = findChildByNameAndGuard;
/**
* Filters children of a reflection by kind and whether they are of type {@linkcode DeclarationReflectionWithReflectedType}
* @param refl - Reflection to check
* @param kind - Kind of child
* @returns Filtered children, if any
* @internal
*/
function filterChildrenByKind(refl, kind) {
return (((0, guards_1.isReflectionWithReflectedType)(refl)
? refl.type.declaration.getChildrenByKind(kind)
: refl.getChildrenByKind(kind)) ?? []);
}
exports.filterChildrenByKind = filterChildrenByKind;
/**
* Finds _all_ async command methods in a class or interface
* @param refl Class reflection
* @returns Map of method names to method reflections
*/
function findCommandMethodsInReflection(refl) {
return new Map(filterChildrenByGuard(refl, guards_1.isCommandMethodDeclarationReflection).map((method) => [
method.name,
method,
]));
}
exports.findCommandMethodsInReflection = findCommandMethodsInReflection;
/**
* Finds "optional" params in a method definition
* @param methodDefRefl - Reflection of a method definition
* @returns List of optional parameters
* @internal
*/
function convertOptionalCommandParams(methodDefRefl) {
return convertCommandParams(external_1.NAME_OPTIONAL, methodDefRefl);
}
exports.convertOptionalCommandParams = convertOptionalCommandParams;
/**
* Finds names of parameters of a command in a method def
* @param propName Either required or optional params
* @param refl Parent reflection (`params` prop of method def)
* @returns List of parameter names
* @internal
*/
function convertCommandParams(propName, refl) {
if (!refl) {
return [];
}
const props = findChildByNameAndGuard(refl, propName, guards_1.isMethodDefParamNamesDeclarationReflection);
if (!props) {
return [];
}
return props.type.target.elements.reduce((names, el) => {
const stringValue = String(el.value);
if (stringValue) {
names.push(stringValue);
}
return names;
}, []);
}
exports.convertCommandParams = convertCommandParams;
/**
* Finds "required" params in a method definition
* @param methodDefRefl - Reflection of a method definition
* @returns List of required parameters
* @internal
*/
function convertRequiredCommandParams(methodDefRefl) {
return convertCommandParams(external_1.NAME_REQUIRED, methodDefRefl);
}
exports.convertRequiredCommandParams = convertRequiredCommandParams;
/**
* List of fields to shallow copy from a `ParameterReflection` to a clone
* @internal
*/
const PARAMETER_REFLECTION_CLONE_FIELDS = [
'anchor',
'cssClasses',
'defaultValue',
'hasOwnDocument',
'label',
'originalName',
'sources',
'type',
'url',
];
/**
* Clones a `ParameterReflection`.
*
* @privateRemarks I think.
* @param pRefl A `ParameterReflection`
* @param param Desired name of parameter
* @param parent Custom signature reflection
* @param knownMethods Builtin methods for aggregating comments
* @param optional If the parameter is considered "optional"
* @returns A new `ParameterReflection` based on the first
*/
function cloneParameterReflection(pRefl, param, parent, knownMethods, optional = false) {
const newPRefl = new typedoc_1.ParameterReflection(param, typedoc_1.ReflectionKind.Parameter, parent);
lodash_1.default.assign(newPRefl, lodash_1.default.pick(pRefl, PARAMETER_REFLECTION_CLONE_FIELDS));
// attempt to derive param comments. these are "summary" comments only,
// so we do not need to worry about combining block/summary comments like with methods.
newPRefl.comment = (0, comment_1.deriveComment)({
refl: pRefl,
knownMethods,
comment: pRefl.comment,
})?.comment;
// there doesn't seem to be a straightforward way to clone flags.
newPRefl.flags = new typedoc_1.ReflectionFlags(...pRefl.flags);
newPRefl.flags.setFlag(typedoc_1.ReflectionFlag.Optional, optional);
return newPRefl;
}
exports.cloneParameterReflection = cloneParameterReflection;
/**
* Clones a type parameter reflection
* @param tPRefl Type parameter reflection
* @param parentRefl Parent
* @returns A clone of the original type parameter reflection
*/
function cloneTypeParameterReflection(tPRefl, parentRefl) {
return new typedoc_1.TypeParameterReflection(tPRefl.name, tPRefl.type, tPRefl.default, parentRefl, tPRefl.varianceModifier);
}
exports.cloneTypeParameterReflection = cloneTypeParameterReflection;
/**
* List of fields to shallow copy from a `SignatureReflection` to a clone
* @internal
*/
const SIGNATURE_REFLECTION_CLONE_FIELDS = [
'anchor',
'comment',
'flags',
'hasOwnDocument',
'implementationOf',
'inheritedFrom',
'kindString',
'label',
'originalName',
'overwrites',
'parameters',
'sources',
'typeParameters',
'url',
];
/**
* This loops over a list of command parameter names as defined in the method/execute map and attempts
* to create a new `ParameterReflection` for each, based on the given data.
*
* Because the command param names are essentially properties of a JSON object and the
* `ParameterReflection` instances represent the arguments of a method, we must match them by
* index. In JS, optional arguments cannot become before required arguments in a function
* signature, so we can do those first. If there are _more_ method arguments than command param
* names, we toss them out, because they may not be part of the public API.
* @param sig Signature reflection
* @param opts Options
* @returns List of refls with names matching `commandParams`, throwing out any extra refls
*/
function createNewParamRefls(sig, opts = {}) {
const { builtinMethods = new Map(), commandParams = [], isOptional, isPluginCommand } = opts;
if (!sig.parameters?.length) {
// this should not happen, I think?
return [];
}
// a plugin command's method has two leading args we don't need
const newParamRefls = [];
const pRefls = isPluginCommand ? sig.parameters.slice(2) : sig.parameters;
for (const [idx, param] of commandParams.entries()) {
const pRefl = pRefls[idx];
if (pRefl) {
const newPRefl = cloneParameterReflection(pRefl, param, sig, builtinMethods, isOptional);
newParamRefls.push(newPRefl);
}
}
return newParamRefls;
}
exports.createNewParamRefls = createNewParamRefls;
/**
* Clones a `CallSignatureReflection` with a new parent and type.
*
* This does a "deep" clone inasmuch as it clones any associated `ParameterReflection` and
* `TypeParameterReflection` instances.
*
* @privateRemarks I'm not sure this is sufficient.
* @param sig A `CallSignatureReflection` to clone
* @param parent The desired parent of the new `CallSignatureReflection`
* @param type The desired type of the new `CallSignatureReflection`; if not provided, the original type
* will be used
* @returns A clone of `sig` with the given parent and type
*/
function cloneCallSignatureReflection(sig, parent, type) {
const newSig = new typedoc_1.SignatureReflection(sig.name, typedoc_1.ReflectionKind.CallSignature, parent);
return lodash_1.default.assign(newSig, lodash_1.default.pick(sig, SIGNATURE_REFLECTION_CLONE_FIELDS), {
parameters: lodash_1.default.map(sig.parameters, (p) => cloneParameterReflection(p, p.name, newSig)),
typeParameters: lodash_1.default.map(sig.typeParameters, (tP) => cloneTypeParameterReflection(tP, newSig)),
type: type ?? sig.type,
});
}
exports.cloneCallSignatureReflection = cloneCallSignatureReflection;
//# sourceMappingURL=utils.js.map