feat(commands): definition providers, multi providers and preconditions

A command definition and a Command() meta may carry `providers`, merged
into each invocation's child injector next to the context, so a command
declares what it needs instead of setting it up by hand.

The injector gains `multi: true`: every multi provider for a token
contributes to an array, in registration order, a token is either multi
or single, and a child's entries shadow the parent's array.

COMMAND_PRECONDITIONS is the first multi token: each entry is a check on
the environment a command runs in, run when the invocation opens, before
setup and before the arguments policy, in the invocation's injection
context. A throw fails the invocation, so being outside a project is
what a bad invocation reports first. canExecute keeps judging the
arguments.

Author: edusperoni

lib/common/contracts/command-preconditions.ts

@@ -0,0 +1,22 @@
+import { InjectionToken } from "../di/injection-token";
+import type { CommandContext } from "../define-command";
+
+/**
+ * A check on the environment a command runs in - a project to be inside, a
+ * platform to be added, an account to be logged into - as opposed to a check
+ * on its arguments, which is `canExecute`. It runs when the invocation opens,
+ * before `setup` and before the arguments policy, in the invocation's
+ * injection context, and a throw fails the invocation.
+ */
+export type CommandPrecondition = (
+	context: CommandContext<any>,
+) => void | Promise<void>;
+
+/**
+ * Multi token: each `{ provide: COMMAND_PRECONDITIONS, multi: true, ... }` in
+ * a command's `providers` contributes one precondition, and they run in the
+ * order they were declared.
+ */
+export const COMMAND_PRECONDITIONS = new InjectionToken<CommandPrecondition[]>(
+	"commandPreconditions",
+);

lib/common/contracts/index.ts

@@ -15,6 +15,8 @@ export type {
 	DeferredCommandResult,
 } from "./command-registry";
 export { COMMAND_CONTEXT } from "./command-context";
+export { COMMAND_PRECONDITIONS } from "./command-preconditions";
+export type { CommandPrecondition } from "./command-preconditions";
 export { CommandsService } from "./commands-service";
 export { ModuleRegistry } from "./module-registry";
 export { PublicApiBuilder } from "./public-api-builder";

lib/common/define-command.ts

@@ -10,6 +10,7 @@ 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";
+import type { Provider } from "./di/providers";
 
 /**
  * Symbol.for so that a definition produced by one copy of the CLI is still
@@ -159,6 +160,12 @@ export interface CommandDefinition<
 	allowUnknownOptions?: boolean;
 	disableAnalytics?: boolean;
 	enableHooks?: boolean;
+	/**
+	 * Providers added to each invocation's own injector, next to the context,
+	 * so a factory or class among them can inject the invocation. They are
+	 * built once per invocation, and `ctx.injector` resolves them.
+	 */
+	providers?: Provider[];
 	/**
 	 * Runs once per invocation, before `canExecute`, and its result is handed to
 	 * `canExecute`, `run` and `postRun`. Sugar: a command may ignore it and call
@@ -234,6 +241,7 @@ const DEFINITION_FIELDS = [
 	"canExecute",
 	"disableAnalytics",
 	"enableHooks",
+	"providers",
 	"setup",
 	"run",
 	"shortcuts",
@@ -268,7 +276,8 @@ 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. " +
+	"providers, 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.";
@@ -526,6 +535,23 @@ const validateDefinition = (definition: any): void => {
 		}
 	}
 
+	if (definition.providers !== undefined) {
+		const providers = definition.providers;
+		const wellFormed =
+			Array.isArray(providers) &&
+			providers.every(
+				(provider: any) =>
+					typeof provider === "function" ||
+					(isPlainObject(provider) && provider.provide !== undefined),
+			);
+		if (!wellFormed) {
+			invalid(
+				definition,
+				"'providers' must be an array of providers - classes, or objects with a 'provide' token",
+			);
+		}
+	}
+
 	if (definition.description !== undefined) {
 		if (typeof definition.description !== "string") {
 			invalid(definition, "'description' must be a string");

lib/common/di/injector.ts

@@ -24,7 +24,8 @@ export interface InjectOptions {
 	skipSelf?: boolean;
 }
 
-type ProviderKind = "value" | "class" | "factory" | "lazyClass" | "legacyClass";
+type ProviderKind =
+	"value" | "class" | "factory" | "lazyClass" | "legacyClass" | "multi";
 
 interface IProviderRecord {
 	displayName: string;
@@ -43,6 +44,8 @@ interface IProviderRecord {
 	/** Every produced instance is retained, transients included — dispose() walks them. */
 	instances: any[];
 	constructing: boolean;
+	/** One record per `multi` provider, in registration order. */
+	multiRecords?: IProviderRecord[];
 }
 
 // Shared across the whole injector tree so cycle reports show the full path
@@ -156,7 +159,29 @@ export class Injector {
 					constructing: false,
 				};
 			}
-			this.applyProvider(record, provider);
+			if ((<Provider>provider).multi) {
+				if (record.kind !== undefined && record.kind !== "multi") {
+					throw new Error(
+						`${record.displayName} is registered as a single provider; it cannot also take multi providers`,
+					);
+				}
+				const entry: IProviderRecord = {
+					displayName: record.displayName,
+					shared: true,
+					instances: [],
+					constructing: false,
+				};
+				this.applyProvider(entry, provider);
+				record.kind = "multi";
+				record.multiRecords = (record.multiRecords || []).concat(entry);
+			} else {
+				if (record.kind === "multi") {
+					throw new Error(
+						`${record.displayName} takes multi providers; a single provider cannot replace them`,
+					);
+				}
+				this.applyProvider(record, provider);
+			}
 			for (const key of keys) {
 				this.providers.set(key, record);
 			}
@@ -231,6 +256,11 @@ export class Injector {
 			disposeOne(this.instantiationOrder[i]);
 		}
 		for (const record of new Set(this.providers.values())) {
+			for (const entry of record.multiRecords || []) {
+				for (const instance of entry.instances) {
+					disposeOne(instance);
+				}
+			}
 			for (const instance of record.instances) {
 				disposeOne(instance);
 			}
@@ -329,6 +359,12 @@ export class Injector {
 			record.pendingLoader = undefined;
 		}
 
+		if (record.kind === "multi") {
+			return record.multiRecords.map((entry) =>
+				this.instantiate(entry, ctorArguments),
+			);
+		}
+
 		if (record.shared && record.instances.length) {
 			return record.instances[0];
 		}

lib/common/di/providers.ts

@@ -10,6 +10,13 @@ interface IBaseProvider<T> {
 	provide: ProviderToken<T>;
 	/** Defaults to true. `false` constructs a fresh instance per resolution. */
 	shared?: boolean;
+	/**
+	 * Contributes to an array under the token instead of replacing it: every
+	 * `multi` provider for one token is resolved, in registration order, and
+	 * `get(token)` returns the array. A token is either multi or single; the
+	 * entries of a child injector shadow the parent's whole array.
+	 */
+	multi?: boolean;
 }
 
 export interface IClassProvider<T> extends IBaseProvider<T> {

lib/common/services/command-definition-adapter.ts

@@ -6,6 +6,10 @@ import { Injector } from "../di/injector";
 import { IDictionary, IDashedOption, IErrors } from "../declarations";
 import { ICommand } from "../definitions/commands";
 import { COMMAND_CONTEXT } from "../contracts/command-context";
+import {
+	COMMAND_PRECONDITIONS,
+	CommandPrecondition,
+} from "../contracts/command-preconditions";
 import { CommandsService } from "../contracts/commands-service";
 import {
 	COMMAND_OWNER,
@@ -371,6 +375,16 @@ export function createCommandFromDefinition<
 		runResult?: Awaited<TResult>;
 	}
 
+	const runPreconditions = async (
+		preconditions: CommandPrecondition[],
+		context: CommandContext<TSchema>,
+		injector: Injector,
+	): Promise<void> => {
+		for (const precondition of preconditions) {
+			await runInInjectionContext(injector, () => precondition(context));
+		}
+	};
+
 	const startSetup = (
 		context: CommandContext<TSchema>,
 		injector: Injector,
@@ -403,6 +417,7 @@ export function createCommandFromDefinition<
 		// invocation; the price is one instance per invocation.
 		const injector = targetInjector.createChild([
 			{ provide: COMMAND_CONTEXT, useValue: context },
+			...(definition.providers || []),
 			...providers,
 		]);
 		context.injector = injector;
@@ -412,7 +427,16 @@ export function createCommandFromDefinition<
 			setup: undefined,
 			hasRun: false,
 		};
-		invocation.setup = startSetup(context, invocation.injector);
+		// Preconditions judge the environment and run ahead of setup and of the
+		// arguments policy, so being outside a project is what a bad invocation
+		// reports first. Without any, setup starts synchronously as before.
+		const preconditions =
+			injector.get(COMMAND_PRECONDITIONS, { optional: true }) || [];
+		invocation.setup = preconditions.length
+			? runPreconditions(preconditions, context, injector).then(() =>
+					startSetup(context, injector),
+				)
+			: startSetup(context, invocation.injector);
 		currentInvocation = invocation;
 
 		return invocation;

lib/contracts/index.ts

@@ -92,6 +92,8 @@ export type {
 // Promoted from the internal contracts index: the class form reads it in a
 // field initializer, and a per-command provider is written against it.
 export { COMMAND_CONTEXT } from "../common/contracts/command-context";
+export { COMMAND_PRECONDITIONS } from "../common/contracts/command-preconditions";
+export type { CommandPrecondition } from "../common/contracts/command-preconditions";
 // The in-process dispatcher a command or plugin runs or consults other
 // commands through.
 export { CommandsService } from "../common/contracts/commands-service";