fix(typedoc-plugin-appium): fix external driver conversion
also rename template
MODIFY
packages/typedoc-plugin-appium/lib/converter/converter.ts
packages/typedoc-plugin-appium/lib/converter/converter.ts
@@ -22,7 +22,8 @@ import {
isExecMethodDefReflection,
isHTTPMethodDeclarationReflection,
isMethodMapDeclarationReflection,
- isParamsArray,
+ isMethodDefParamNamesDeclarationReflection,
+ isExecMethodDefParamsPropDeclarationReflection,
isReflectionWithReflectedType,
isRoutePropDeclarationReflection,
} from '../guards';
@@ -38,7 +39,9 @@ import {
import {
BaseDriverDeclarationReflection,
DeclarationReflectionWithReflectedType,
+ ExecMethodDeclarationReflection,
Guard,
+ MethodDefParamsPropDeclarationReflection,
} from './types';
/**
@@ -165,12 +168,16 @@ export class CommandConverter {
#convertCommandParams(
propName: typeof NAME_OPTIONAL | typeof NAME_REQUIRED,
- refl?: DeclarationReflectionWithReflectedType
+ refl?: MethodDefParamsPropDeclarationReflection
): string[] {
if (!refl) {
return [];
}
- const props = findChildByNameAndGuard(refl, propName, isParamsArray);
+ const props = findChildByNameAndGuard(
+ refl,
+ propName,
+ isMethodDefParamNamesDeclarationReflection
+ );
const names = props?.type.target.elements.map((el: LiteralType) => String(el.value)) ?? [];
return names.filter((name) => {
if (!name) {
@@ -186,12 +193,9 @@ export class CommandConverter {
* @param refl A class which may contain an `executeMethodMap` static property
* @returns List of "execute commands", if any
*/
- #convertExecuteMethodMap(refl: DeclarationReflectionWithReflectedType): ExecMethodDataSet {
- const executeMethodMap = findChildByNameAndGuard(
- refl,
- NAME_EXECUTE_METHOD_MAP,
- isExecMethodDefReflection
- );
+ #convertExecuteMethodMap(refl: DeclarationReflection): ExecMethodDataSet {
+ const executeMethodMap = findChildByGuard(refl, isExecMethodDefReflection);
+
const commandRefs: ExecMethodDataSet = new Set();
if (!executeMethodMap) {
// no execute commands in this class
@@ -202,11 +206,7 @@ export class CommandConverter {
for (const newMethodProp of newMethodProps) {
const {comment, originalName: script} = newMethodProp;
- const commandProp = findChildByNameAndGuard(
- newMethodProp,
- NAME_COMMAND,
- isCommandPropDeclarationReflection
- );
+ const commandProp = findChildByGuard(newMethodProp, isCommandPropDeclarationReflection);
if (!commandProp) {
// this is unusual
@@ -228,10 +228,9 @@ export class CommandConverter {
}
const command = String(commandProp.type.value);
- const paramsProp = findChildByNameAndGuard(
+ const paramsProp = findChildByGuard(
newMethodProp,
- NAME_PARAMS,
- isReflectionWithReflectedType
+ isExecMethodDefParamsPropDeclarationReflection
);
const requiredParams = this.#convertRequiredCommandParams(paramsProp);
const optionalParams = this.#convertOptionalCommandParams(paramsProp);
@@ -289,11 +288,7 @@ export class CommandConverter {
for (const httpMethodProp of httpMethodProps) {
const {comment, originalName: httpMethod} = httpMethodProp;
- const commandProp = findChildByNameAndGuard(
- httpMethodProp,
- NAME_COMMAND,
- isCommandPropDeclarationReflection
- );
+ const commandProp = findChildByGuard(httpMethodProp, isCommandPropDeclarationReflection);
// commandProp is optional.
if (!commandProp) {
@@ -306,10 +301,9 @@ export class CommandConverter {
}
const command = String(commandProp.type.value);
- const payloadParamsProp = findChildByNameAndGuard(
+ const payloadParamsProp = findChildByGuard(
httpMethodProp,
- NAME_PAYLOAD_PARAMS,
- isReflectionWithReflectedType
+ isExecMethodDefParamsPropDeclarationReflection
);
const requiredParams = this.#convertRequiredCommandParams(payloadParamsProp);
const optionalParams = this.#convertOptionalCommandParams(payloadParamsProp);
@@ -341,11 +335,7 @@ export class CommandConverter {
let routes: RouteMap = new Map();
let executeMethods: ExecMethodDataSet = new Set();
- const classReflections = parent
- .getChildrenByKind(ReflectionKind.Class)
- .filter((child) =>
- isReflectionWithReflectedType(child)
- ) as DeclarationReflectionWithReflectedType[];
+ const classReflections = parent.getChildrenByKind(ReflectionKind.Class);
for (const classRefl of classReflections) {
this.#log.verbose('Converting class %s', classRefl.name);
@@ -370,7 +360,9 @@ export class CommandConverter {
* @param methodDefRefl - Reflection of a method definition
* @returns List of optional parameters
*/
- #convertOptionalCommandParams(methodDefRefl?: DeclarationReflectionWithReflectedType): string[] {
+ #convertOptionalCommandParams(
+ methodDefRefl?: MethodDefParamsPropDeclarationReflection
+ ): string[] {
return this.#convertCommandParams(NAME_OPTIONAL, methodDefRefl);
}
@@ -379,7 +371,9 @@ export class CommandConverter {
* @param methodDefRefl - Reflection of a method definition
* @returns List of required parameters
*/
- #convertRequiredCommandParams(methodDefRefl?: DeclarationReflectionWithReflectedType): string[] {
+ #convertRequiredCommandParams(
+ methodDefRefl?: MethodDefParamsPropDeclarationReflection
+ ): string[] {
return this.#convertCommandParams(NAME_REQUIRED, methodDefRefl);
}
}
@@ -402,12 +396,34 @@ export function convertCommands(ctx: Context, log: AppiumPluginLogger): ModuleCo
* @returns Child if found, `undefined` otherwise
* @internal
*/
-function findChildByNameAndGuard<T extends DeclarationReflection>(
- refl: DeclarationReflectionWithReflectedType,
+function findChildByNameAndGuard<T extends DeclarationReflection, G extends DeclarationReflection>(
+ refl: T,
name: string,
- guard: Guard<T>
-): T | undefined {
- return refl.type.declaration.children?.find((child) => child.name === name && guard(child)) as T;
+ guard: Guard<G>
+): G | undefined {
+ return (
+ isReflectionWithReflectedType(refl)
+ ? refl.type.declaration.children?.find((child) => child.name === name && guard(child))
+ : refl.children?.find((child) => child.name === name && guard(child))
+ ) as G | undefined;
+}
+
+/**
+ * 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<T extends DeclarationReflection, G extends DeclarationReflection>(
+ refl: T,
+ guard: Guard<G>
+): G | undefined {
+ return (
+ isReflectionWithReflectedType(refl)
+ ? refl.type.declaration.children?.find(guard)
+ : refl.children?.find(guard)
+ ) as G | undefined;
}
/**
@@ -417,13 +433,15 @@ function findChildByNameAndGuard<T extends DeclarationReflection>(
* @returns Filtered children, if any
* @internal
*/
-function filterChildrenByKind(
- refl: DeclarationReflectionWithReflectedType,
+function filterChildrenByKind<T extends DeclarationReflection>(
+ refl: T,
kind: ReflectionKind
-): DeclarationReflectionWithReflectedType[] {
- return (refl.type.declaration.children?.filter(
- (child) => isReflectionWithReflectedType(child) && child.kindOf(kind)
- ) ?? []) as DeclarationReflectionWithReflectedType[];
+): DeclarationReflection[] {
+ return (
+ (isReflectionWithReflectedType(refl)
+ ? refl.type.declaration.getChildrenByKind(kind)
+ : refl.getChildrenByKind(kind)) ?? ([] as DeclarationReflection[])
+ );
}
/**
@@ -433,9 +451,13 @@ function filterChildrenByKind(
* @returns Filtered children, if any
* @internal
*/
-function filterChildrenByGuard<T extends DeclarationReflection>(
- refl: DeclarationReflectionWithReflectedType,
- guard: Guard<T>
-): T[] {
- return refl.type.declaration.children?.filter(guard) ?? [];
+function filterChildrenByGuard<T extends DeclarationReflection, G extends DeclarationReflection>(
+ refl: T,
+ guard: Guard<G>
+): G[] {
+ return (
+ (isReflectionWithReflectedType(refl)
+ ? refl.type.declaration.children?.filter(guard)
+ : refl.children?.filter(guard)) ?? ([] as G[])
+ );
}

MODIFY
packages/typedoc-plugin-appium/lib/converter/types.ts
packages/typedoc-plugin-appium/lib/converter/types.ts
-import {Merge} from 'type-fest';
import {
DeclarationReflection,
LiteralType,
+ ReflectionFlags,
ReflectionKind,
ReflectionType,
SomeType,
@@ -9,26 +9,28 @@ import {
TypeOperatorType,
} from 'typedoc';
import {AllowedHttpMethod} from '../model';
-import {NAME_BUILTIN_COMMAND_MODULE, NAME_METHOD_MAP, NAME_NEW_METHOD_MAP} from './converter';
+import {
+ NAME_BUILTIN_COMMAND_MODULE,
+ NAME_EXECUTE_METHOD_MAP,
+ NAME_METHOD_MAP,
+ NAME_NEW_METHOD_MAP,
+ NAME_PARAMS,
+} from './converter';
/**
* Type corresponding to a reflection of a {@linkcode @appium/types#MethodMap}
*/
-export type MethodMapDeclarationReflection = Merge<
- DeclarationReflectionWithReflectedType,
- {name: typeof NAME_METHOD_MAP | typeof NAME_NEW_METHOD_MAP}
->;
+export type MethodMapDeclarationReflection = DeclarationReflectionWithReflectedType & {
+ name: typeof NAME_METHOD_MAP | typeof NAME_NEW_METHOD_MAP;
+};
/**
* Type corresponding to a reflection of {@linkcode @appium/base-driver}
*/
-export type BaseDriverDeclarationReflection = Merge<
- DeclarationReflection,
- {
+export type BaseDriverDeclarationReflection = DeclarationReflection & {
name: typeof NAME_BUILTIN_COMMAND_MODULE;
kind: ReflectionKind.Module;
- }
->;
+};
/**
* Utility to narrow a declaration reflection to a specific `SomeType`
@@ -36,37 +38,35 @@ export type BaseDriverDeclarationReflection = Merge<
type WithSomeType<
T extends SomeType,
R extends DeclarationReflection = DeclarationReflection
-> = Merge<R, {type: T}>;
+> = R & {type: T};
/**
* Utility; a TupleType with literal elements
*/
-type TupleTypeWithLiteralElements = Merge<TupleType, {elements: LiteralType[]}>;
+type TupleTypeWithLiteralElements = TupleType & {elements: LiteralType[]};
/**
* Type for the parameters of a command definition or execute method definition.
*
* Node that merging `TypeOperatorType` won't work because it will no longer satisfy `SomeType`, because `SomeType` is a finite collection.
*/
-export type MethodDefParamsDeclarationReflection = WithSomeType<
+export type MethodDefParamNamesDeclarationReflection = WithSomeType<
TypeOperatorType & {operator: 'readonly'; target: TupleTypeWithLiteralElements}
>;
/**
* Narrows a declaration reflection to one having a reflection type and a property kind. Generic
*/
-export type PropDeclarationReflection = Merge<
- DeclarationReflectionWithReflectedType,
- {kind: ReflectionKind.Property}
->;
+export type PropDeclarationReflection = DeclarationReflectionWithReflectedType & {
+ kind: ReflectionKind.Property;
+};
/**
* A type corresponding to the HTTP method of a route, which is a property off of the object with the route name in a `MethodMap`
*/
-export type HTTPMethodDeclarationReflection = Merge<
- PropDeclarationReflection,
- {originalName: AllowedHttpMethod}
->;
+export type HTTPMethodDeclarationReflection = PropDeclarationReflection & {
+ originalName: AllowedHttpMethod;
+};
/**
* A declaration reflection having a reflection type. Generic
@@ -82,3 +82,26 @@ export type CommandPropDeclarationReflection = WithSomeType<LiteralType>;
* A generic type guard
*/
export type Guard<T> = (value: any) => value is T;
+
+/**
+ * Type corresponding to an execute method map
+ */
+export type ExecMethodDeclarationReflection = DeclarationReflectionWithReflectedType & {
+ name: typeof NAME_EXECUTE_METHOD_MAP;
+ flags: ReflectionFlags & {isStatic: true};
+};
+
+/**
+ * Type corresponding to the `params` prop of a `MethodDef`
+ */
+export type MethodDefParamsPropDeclarationReflection = DeclarationReflectionWithReflectedType & {
+ name: typeof NAME_PARAMS;
+};
+
+/**
+ * Type corresponding to the `payloadParams` prop of an `ExecMethodDef`
+ */
+export type ExecMethodDefParamsPropDeclarationReflection =
+ DeclarationReflectionWithReflectedType & {
+ name: typeof NAME_PARAMS;
+ };

MODIFY
packages/typedoc-plugin-appium/lib/guards.ts
packages/typedoc-plugin-appium/lib/guards.ts
@@ -14,18 +14,24 @@ import {
} from 'typedoc';
import {
NAME_BUILTIN_COMMAND_MODULE,
+ NAME_COMMAND,
NAME_EXECUTE_METHOD_MAP,
NAME_METHOD_MAP,
NAME_NEW_METHOD_MAP,
+ NAME_PARAMS,
+ NAME_PAYLOAD_PARAMS,
} from './converter';
import {
BaseDriverDeclarationReflection,
CommandPropDeclarationReflection,
DeclarationReflectionWithReflectedType,
+ ExecMethodDeclarationReflection,
HTTPMethodDeclarationReflection,
- MethodDefParamsDeclarationReflection,
+ MethodDefParamNamesDeclarationReflection,
MethodMapDeclarationReflection,
+ MethodDefParamsPropDeclarationReflection,
PropDeclarationReflection,
+ ExecMethodDefParamsPropDeclarationReflection,
} from './converter/types';
import {AllowedHttpMethod, ExecMethodData} from './model';
@@ -83,12 +89,7 @@ export function isTupleType(value: any): value is TupleType {
* the `executeMethodMap` static property of an extension class.
* @param value any
*/
-export function isExecMethodDefReflection(
- value: any
-): value is DeclarationReflectionWithReflectedType & {
- name: typeof NAME_EXECUTE_METHOD_MAP;
- flags: {isStatic: true};
-} {
+export function isExecMethodDefReflection(value: any): value is ExecMethodDeclarationReflection {
return (
isReflectionWithReflectedType(value) &&
value.name === NAME_EXECUTE_METHOD_MAP &&
@@ -97,10 +98,12 @@ export function isExecMethodDefReflection(
}
/**
- * Type guard for a {@linkcode MethodDefParamsDeclarationReflection} corresponding to a list of required or optional parameters within a command or execute method definition.
+ * 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
*/
-export function isParamsArray(value: any): value is MethodDefParamsDeclarationReflection {
+export function isMethodDefParamNamesDeclarationReflection(
+ value: any
+): value is MethodDefParamNamesDeclarationReflection {
return (
isDeclarationReflection(value) &&
isTypeOperatorType(value.type) &&
@@ -193,7 +196,7 @@ export function isAllowedHTTPMethod(value: any): value is AllowedHttpMethod {
export function isCommandPropDeclarationReflection(
value: any
): value is CommandPropDeclarationReflection {
- return isDeclarationReflection(value) && isLiteralType(value.type);
+ return isDeclarationReflection(value) && isLiteralType(value.type) && value.name === NAME_COMMAND;
}
/**
@@ -203,3 +206,23 @@ export function isCommandPropDeclarationReflection(
export function isExecMethodData(value: any): value is ExecMethodData {
return value && typeof value === 'object' && value.script;
}
+
+/**
+ * Type guard for a {@linkcode MethodDefParamsPropDeclarationReflection} corresponding to the `params` prop of a `MethodDef`
+ * @param value any value
+ */
+export function isMethodDefParamsPropDeclarationReflection(
+ value: any
+): value is MethodDefParamsPropDeclarationReflection {
+ return isReflectionWithReflectedType(value) && value.name === NAME_PARAMS;
+}
+
+/**
+ * Type guard for a {@linkcode ExecMethodDefParamsPropDeclarationReflection} corresponding to the `payloadParams` prop of an `ExecuteMethodDef`.
+ * @param value any value
+ */
+export function isExecMethodDefParamsPropDeclarationReflection(
+ value: any
+): value is ExecMethodDefParamsPropDeclarationReflection {
+ return isReflectionWithReflectedType(value) && value.name === NAME_PAYLOAD_PARAMS;
+}

MODIFY
packages/typedoc-plugin-appium/lib/theme/template.ts
packages/typedoc-plugin-appium/lib/theme/template.ts
@@ -28,7 +28,7 @@ const PARTIALS_PATH = path.join(RESOURCES_PATH, 'partials');
*/
enum AppiumThemePartial {
command = 'command.hbs',
- executeMethod = 'execute-command.hbs',
+ executeMethod = 'execute-method.hbs',
}
/**

RENAME
packages/typedoc-plugin-appium/resources/partials/execute-command.hbs
packages/typedoc-plugin-appium/resources/partials/execute-method.hbs
fix(typedoc-plugin-appium): fix external driver conversion
also rename template