feat(commands): add a class form built on defineCommand

Command(meta) returns a base class whose static definition is a real
defineCommand result: the handlers become methods, the instance is the
setup result, and the adapter still only ever sees definitions. The
definition is a static getter, so it resolves the subclass it is read
through and caches on that constructor.

Registration, the name-literal check and the extension manifest path
take either form. COMMAND_CONTEXT is promoted to nativescript/contracts,
which is what the base class reads in its field initializer.

Author: edusperoni

defining-commands.md

@@ -48,6 +48,10 @@ spread, so `{ ...baseDefinition, name: "widget|add2" }` is still recognised.
 `defineCommand` does not register anything by itself — see
 [Registering a definition](#registering-a-definition).
 
+A command may also be written as a class, with the handlers as methods — see
+[Class form](#class-form). It is sugar over `defineCommand`: everything below
+describes both.
+
 Validation happens where you can see it
 ---------------------------------------
 
@@ -518,6 +522,120 @@ Other flags
 Both are simply passed through to the command the CLI executes; omitting them
 leaves the CLI's defaults in place.
 
+Class form
+----------
+
+`Command(meta)` returns a base class to extend. It is sugar over
+`defineCommand` and nothing more: the class carries a `static definition` built
+by `defineCommand`, and that definition is the only thing the CLI ever
+executes.
+
+```ts
+import { Command, inject, stringOption } from "nativescript/contracts";
+
+export class PlatformCleanCommand extends Command({
+	name: "platform|clean",
+	description: "Removes and adds again the selected platform.",
+	options: { frameworkPath: stringOption() },
+	arguments: "any",
+}) {
+	private $platformCommandHelper = inject<IPlatformCommandHelper>(
+		"platformCommandHelper",
+	);
+	private $projectData = inject<IProjectData>("projectData");
+
+	constructor() {
+		super();
+		this.$projectData.initializeProjectData();
+	}
+
+	public async run(): Promise<void> {
+		await this.$platformCommandHelper.cleanPlatforms(
+			this.args,
+			this.$projectData,
+			this.options.frameworkPath,
+		);
+	}
+}
+```
+
+`meta` is the definition minus its handlers: `name`, `description`, `options`,
+`arguments`, `allowUnknownOptions`, `disableAnalytics` and `enableHooks`. The
+handlers are methods instead — `run` is required, and `canExecute`, `postRun`
+and `shortcuts` are optional, each with the same meaning and the same ordering
+as the fields of the same name. `postRun(result)` receives what `run` returned;
+`shortcuts()` returns the same table `shortcuts(ctx, setup)` does. A method the
+class does not declare is left out of the definition entirely, so a class
+without `postRun` gets no `postCommandAction`, exactly as an object without one
+does.
+
+**Which form to use.** The class form is for a single named command. When a
+function generates variants of one command — the `run|ios` / `run|vision`
+family, one definition per platform — the object form is what fits, because
+the thing being parameterized is a value and definitions are values.
+Registering the same class twice under two names is not the equivalent: the
+class is one definition.
+
+**The class is the setup.** One instance is constructed per invocation, as that
+invocation's `setup`, before `canExecute` runs. So field initializers and the
+constructor run inside the injection context: `inject()` in a field initializer
+resolves, and a constructor — optional, and if written it must call a bare
+`super()` — is where the work a legacy command did in its own constructor goes.
+Because construction is the setup, `inject()` is valid throughout it; after the
+first `await` inside a method, use `this.context.injector.get(token)` as
+[Injection, and the first `await`](#injection-and-the-first-await) describes.
+
+**`this.context`, `this.options` and `this.args`** are the same context the
+object form's handlers receive, typed from the `options` the meta declares:
+`this.options.frameworkPath` is `string | undefined` above, and a name the
+schema does not declare is a compile error. `this.context` also carries
+`params`, `injector` and `fail`.
+
+**Per-command providers see the invocation.** The context is provided to the
+invocation's own child injector under the `COMMAND_CONTEXT` token, which is how
+the base class reads it. A provider registered for one command — through the
+`providers` argument of `registerCommand` or `registerLazyCommand` — can inject
+it too, and resolves nothing outside a running invocation.
+
+**Share through functions, not base classes.** Two commands that need the same
+services share an `inject()`-based helper, not a common ancestor:
+
+```ts
+export function injectPlatformCommandServices() {
+	const projectData = inject(ProjectData);
+	projectData.initializeProjectData();
+	return { projectData, platformHelper: inject(PlatformCommandHelper) };
+}
+
+export class PlatformAddCommand extends Command({ name: "platform|add" }) {
+	private services = injectPlatformCommandServices();
+	// ...
+}
+```
+
+A helper composes — a command can call two of them — and it stays readable
+without the reader walking a chain of files. A base class between `Command()`
+and the command does not: it is the pattern the legacy `ICommand` hierarchy
+used, and untangling it is most of why this API exists.
+
+Registration takes the class itself; see
+[Registering a definition](#registering-a-definition):
+
+```ts
+registerBuiltInCommand<
+	typeof import("./commands/platform-clean").PlatformCleanCommand
+>(
+	"platform|clean",
+	() => require("./commands/platform-clean").PlatformCleanCommand,
+);
+```
+
+`isCommandClass(value)` is the exported check, and `Ctor.definition` is the
+definition the class stands for — derived once per class, and derived for the
+subclass rather than for the base `Command()` returned. A class that implements
+no `run`, or a class that did not come from `Command()`, is refused with the
+same message shape a bad object gets.
+
 Registering a definition
 ------------------------
 
@@ -533,6 +651,11 @@ registerCommand({
 });
 ```
 
+Every registration helper — `registerCommand`, `registerLazyCommand` and
+`registerBuiltInCommand` — takes a [class form](#class-form) command wherever
+it takes a definition, and reads the name it declares through its
+`static definition`.
+
 It takes either a `DefinedCommand` — the result of `defineCommand`, marker and
 all — or the definition itself, which it defines on your behalf, so registering
 a command is one call. Either way the definition is validated before it reaches

lib/common/define-command.ts

@@ -6,7 +6,9 @@
  * lib/common/services/command-definition-adapter.
  */
 
+import { COMMAND_CONTEXT } from "./contracts/command-context";
 import type { KeyShortcut } from "./contracts/key-shortcuts";
+import { inject } from "./di/inject";
 import type { Injector } from "./di/injector";
 
 /**
@@ -255,7 +257,10 @@ const OPTION_TYPES: CommandOptionType[] = [
 const ACCEPTED_FORM =
 	'defineCommand({ name: "widget|add", run(ctx) { ... } }) — with the ' +
 	"optional fields description, options, arguments, allowUnknownOptions, " +
-	"setup, canExecute, shortcuts, postRun, disableAnalytics and enableHooks.";
+	"setup, canExecute, shortcuts, postRun, disableAnalytics and enableHooks. " +
+	'Or the class form, class WidgetAdd extends Command({ name: "widget|add" }) ' +
+	"{ run() { ... } }, which declares the same fields except the handlers and " +
+	"implements run, and optionally canExecute, postRun and shortcuts, as methods.";
 
 const describeDefinition = (definition: any): string => {
 	const name = definition && definition.name;
@@ -556,12 +561,18 @@ export type CommandName = string | readonly string[];
  * be checked against them.
  */
 export type CommandNamesOf<TDefinition> = TDefinition extends {
-	name: infer TName;
+	definition: infer TClassDefinition;
 }
-	? TName extends readonly (infer TAlias)[]
-		? TAlias
-		: TName
-	: never;
+	? // A constructor's own `name` is Function.name, so the class form has to be
+		// read through its static definition before the `name` branch sees it.
+		CommandNamesOf<TClassDefinition>
+	: TDefinition extends {
+				name: infer TName;
+		  }
+		? TName extends readonly (infer TAlias)[]
+			? TAlias
+			: TName
+		: never;
 
 export function defineCommand<
 	TSchema extends CommandOptionsSchema = {},
@@ -583,3 +594,204 @@ export function isCommandDefinition(
 ): value is DefinedCommand<any, any, any> {
 	return !!value && (<any>value)[COMMAND_DEFINITION_MARKER] === true;
 }
+
+/**
+ * Marks a constructor produced by `Command()`. Same `Symbol.for` reasoning as
+ * COMMAND_DEFINITION_MARKER, and the same reason it is read rather than
+ * `instanceof`: an extension bundles its own copy of this module.
+ */
+export const COMMAND_CLASS_MARKER: unique symbol = Symbol.for(
+	"nativescript:cli:commandClass",
+);
+
+/** The meta `Command()` was called with, inherited by every subclass. */
+const COMMAND_CLASS_META = Symbol.for("nativescript:cli:commandClassMeta");
+
+/** Per-constructor cache of the derived definition; own-property only. */
+const COMMAND_CLASS_DEFINITION = Symbol.for(
+	"nativescript:command:classDefinition",
+);
+
+/**
+ * What the class form declares up front: a definition without the handlers,
+ * which the class supplies as methods instead.
+ */
+export type CommandMeta<
+	TName extends CommandName = CommandName,
+	TSchema extends CommandOptionsSchema = {},
+> = Omit<
+	CommandDefinition<TSchema, any, any>,
+	"name" | "setup" | "canExecute" | "run" | "postRun" | "shortcuts"
+> & { name: TName };
+
+/**
+ * The instance side of the class form. Exported because it names the base of
+ * every `Command()` class — a subclass's declaration emit refers to it — not
+ * because anything should extend it directly.
+ */
+export abstract class CommandBase<
+	TSchema extends CommandOptionsSchema = {},
+	TResult = void,
+> {
+	/**
+	 * The instance is built once per invocation, as that invocation's `setup`,
+	 * so the context captured here is the one its own run was handed.
+	 */
+	protected readonly context: CommandContext<TSchema> = inject(COMMAND_CONTEXT);
+
+	protected get options(): CommandOptionValues<TSchema> {
+		return this.context.options;
+	}
+
+	protected get args(): string[] {
+		return this.context.args;
+	}
+
+	abstract run(): Promise<TResult> | TResult;
+	canExecute?(): Promise<boolean> | boolean;
+	postRun?(result: Awaited<TResult>): Promise<void> | void;
+	shortcuts?(): KeyShortcut[];
+}
+
+/**
+ * The static side. An abstract construct signature, so the compiler still
+ * requires a subclass to implement `run`, and a named type, so declaration
+ * emit for `class X extends Command({ ... })` has something to refer to.
+ */
+export type CommandClass<
+	TName extends CommandName = CommandName,
+	TSchema extends CommandOptionsSchema = {},
+	TResult = void,
+> = (abstract new () => CommandBase<TSchema, TResult>) & {
+	readonly definition: NamedCommand<
+		TSchema,
+		TResult,
+		CommandBase<TSchema, TResult>,
+		TName
+	>;
+	readonly [COMMAND_CLASS_MARKER]: true;
+};
+
+/** Either accepted form of a command, as a registration site takes it. */
+export type RegisterableCommand =
+	DefinedCommand<any, any, any> | CommandClass<any, any, any>;
+
+export function isCommandClass(
+	value: any,
+): value is CommandClass<any, any, any> {
+	return (
+		typeof value === "function" && (<any>value)[COMMAND_CLASS_MARKER] === true
+	);
+}
+
+const buildClassDefinition = (ctor: any): DefinedCommand<any, any, any> => {
+	const meta = ctor[COMMAND_CLASS_META];
+	const prototype = ctor.prototype;
+	const implementsMethod = (method: string): boolean =>
+		typeof prototype[method] === "function";
+
+	if (!implementsMethod("run")) {
+		invalid(
+			meta,
+			`the class '${ctor.name || "<anonymous>"}' implements no 'run' method`,
+		);
+	}
+
+	// The instance IS the setup result, so every handler reaches it as the
+	// second argument the adapter already threads through.
+	const definition: any = {
+		...meta,
+		setup: () => new ctor(),
+		run: (context: any, instance: any) => instance.run(),
+	};
+
+	if (implementsMethod("canExecute")) {
+		definition.canExecute = (context: any, instance: any) =>
+			instance.canExecute();
+	}
+
+	if (implementsMethod("postRun")) {
+		definition.postRun = (context: any, result: any, instance: any) =>
+			instance.postRun(result);
+	}
+
+	if (implementsMethod("shortcuts")) {
+		definition.shortcuts = (context: any, instance: any) =>
+			instance.shortcuts();
+	}
+
+	return defineCommand(definition);
+};
+
+/**
+ * The definition a `Command()` class stands for, cached on the constructor it
+ * was read from. The cache entry is an own property so a class extending
+ * another command class never serves its parent's definition.
+ */
+export function classCommandDefinition(
+	ctor: any,
+): DefinedCommand<any, any, any> {
+	if (!isCommandClass(ctor)) {
+		throw new Error(
+			`${describeDefinition(ctor)} is not a command class: it did not come ` +
+				`from Command(). Accepted form: ${ACCEPTED_FORM}`,
+		);
+	}
+
+	const target: any = ctor;
+	if (Object.prototype.hasOwnProperty.call(target, COMMAND_CLASS_DEFINITION)) {
+		return target[COMMAND_CLASS_DEFINITION];
+	}
+
+	const definition = buildClassDefinition(target);
+	Object.defineProperty(target, COMMAND_CLASS_DEFINITION, {
+		value: definition,
+	});
+
+	return definition;
+}
+
+/** The definition behind either form, or null for anything else. */
+export function toCommandDefinition(
+	value: any,
+): DefinedCommand<any, any, any> | null {
+	if (isCommandClass(value)) {
+		return classCommandDefinition(value);
+	}
+
+	return isCommandDefinition(value) ? value : null;
+}
+
+/**
+ * The class authoring form: sugar over defineCommand, not a second execution
+ * path. The returned base carries a `definition` that reads the class it is
+ * accessed through, so the subclass — not this base — is what `setup`
+ * instantiates, and registration keeps taking definitions only.
+ *
+ *     export class PlatformClean extends Command({
+ *       name: "platform|clean",
+ *       options: { frameworkPath: stringOption() },
+ *     }) {
+ *       private $helper = inject<IPlatformCommandHelper>("platformCommandHelper");
+ *       run() { return this.$helper.clean(this.args, this.options.frameworkPath); }
+ *     }
+ */
+export function Command<
+	const TName extends CommandName,
+	TSchema extends CommandOptionsSchema = {},
+	TResult = void,
+>(meta: CommandMeta<TName, TSchema>): CommandClass<TName, TSchema, TResult> {
+	abstract class Base extends CommandBase<TSchema, TResult> {
+		// A getter, because `this` in a static accessor is the constructor the
+		// property was read through: that is the only hook that resolves the
+		// subclass without the subclass having to name itself.
+		static get definition(): DefinedCommand<any, any, any> {
+			return classCommandDefinition(this);
+		}
+	}
+
+	Object.defineProperty(Base, COMMAND_CLASS_MARKER, { value: true });
+	Object.defineProperty(Base, COMMAND_CLASS_META, { value: meta });
+
+	return <any>Base;
+}