IoHelper

Author: mrgrain

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/index.ts

@@ -1,4 +1,4 @@
-export * from './action-aware';
+export * from './io-helper';
 export * from './level-priority';
 export * from './message-maker';
 export * from './types';

…lpers/src/api/io/private/action-aware.ts …-helpers/src/api/io/private/io-helper.tspackages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/action-aware.ts renamed to packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/io-helper.ts packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/action-aware.ts renamed to packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/io-helper.ts

@@ -8,19 +8,20 @@ export type ActionLessMessage<T> = Omit<IoMessage<T>, 'action'>;
 export type ActionLessRequest<T, U> = Omit<IoRequest<T, U>, 'action'>;
 
 /**
- * Helper type for IoHosts that are action aware
+ * Helper for IO messaging.
+ *
+ * Wraps a client provided IoHost and provides additional features & services to toolkit internal classes.
  */
-export interface ActionAwareIoHost extends IIoHost {
+export interface IoHelper extends IIoHost {
   action: ToolkitAction;
   notify<T>(msg: ActionLessMessage<T>): Promise<void>;
   requestResponse<T, U>(msg: ActionLessRequest<T, U>): Promise<U>;
 }
 
 /**
- * An IoHost wrapper that adds the given action to an actionless message before
- * sending the message to the given IoHost
+ * Wraps an IoHost and creates an IoHelper from it
  */
-export function withAction(ioHost: IIoHost, action: ToolkitAction): ActionAwareIoHost {
+export function asIoHelper(ioHost: IIoHost, action: ToolkitAction): IoHelper {
   return {
     action,
     notify: async <T>(msg: Omit<IoMessage<T>, 'action'>) => {

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/message-maker.ts

@@ -1,5 +1,5 @@
 import type { IoMessageCode, IoMessageLevel } from '../io-message';
-import type { ActionLessMessage, ActionLessRequest } from './action-aware';
+import type { ActionLessMessage, ActionLessRequest } from './io-helper';
 
 /**
  * Information for each IO Message Code.

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/private/context-aware-source.ts

@@ -3,7 +3,7 @@ import type * as cxapi from '@aws-cdk/cx-api';
 import type { ToolkitServices } from '../../../toolkit/private';
 import { type Context, contextproviders, PROJECT_CONTEXT } from '../../aws-cdk';
 import { CODES } from '../../io/private';
-import type { ActionAwareIoHost } from '../../shared-private';
+import type { IoHelper } from '../../shared-private';
 import { ToolkitError } from '../../shared-public';
 import type { ICloudAssemblySource } from '../types';
 
@@ -43,7 +43,7 @@ export class ContextAwareCloudAssembly implements ICloudAssemblySource {
   private canLookup: boolean;
   private context: Context;
   private contextFile: string;
-  private ioHost: ActionAwareIoHost;
+  private ioHost: IoHelper;
 
   constructor(private readonly source: ICloudAssemblySource, private readonly props: ContextAwareCloudAssemblyProps) {
     this.canLookup = props.lookups ?? true;

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/private/prepare-source.ts

@@ -9,7 +9,7 @@ import { prepareDefaultEnvironment as oldPrepare, prepareContext, spaceAvailable
 import { splitBySize } from '../../../private/util';
 import type { ToolkitServices } from '../../../toolkit/private';
 import { CODES } from '../../io/private';
-import type { ActionAwareIoHost } from '../../shared-private';
+import type { IoHelper } from '../../shared-private';
 import { ToolkitError } from '../../shared-public';
 import type { AppSynthOptions, LoadAssemblyOptions } from '../source-builder';
 
@@ -130,7 +130,7 @@ export async function withContext<T>(
  *
  * @param assembly the assembly to check
  */
-export async function checkContextOverflowSupport(assembly: cxapi.CloudAssembly, ioHost: ActionAwareIoHost): Promise<void> {
+export async function checkContextOverflowSupport(assembly: cxapi.CloudAssembly, ioHost: IoHelper): Promise<void> {
   const tree = loadTree(assembly);
   const frameworkDoesNotSupportContextOverflow = some(tree, node => {
     const fqn = node.constructInfo?.fqn;
@@ -149,7 +149,7 @@ export async function checkContextOverflowSupport(assembly: cxapi.CloudAssembly,
 /**
  * Safely create an assembly from a cloud assembly directory
  */
-export async function assemblyFromDirectory(assemblyDir: string, ioHost: ActionAwareIoHost, loadOptions: LoadAssemblyOptions = {}) {
+export async function assemblyFromDirectory(assemblyDir: string, ioHost: IoHelper, loadOptions: LoadAssemblyOptions = {}) {
   try {
     const assembly = new cxapi.CloudAssembly(assemblyDir, {
       skipVersionCheck: !(loadOptions.checkVersion ?? true),

packages/@aws-cdk/toolkit-lib/lib/api/io/private/sdk-logger.ts

@@ -3,7 +3,7 @@ import { inspect } from 'util';
 import type { Logger } from '@smithy/types';
 import { CODES } from './codes';
 import { replacerBufferWithInfo } from '../../../private/util';
-import type { ActionAwareIoHost } from '../../shared-private';
+import type { IoHelper } from '../../shared-private';
 
 /**
  * An SDK logging trace.
@@ -27,7 +27,7 @@ export interface SdkTrace {
   readonly content: any;
 }
 
-export function asSdkLogger(ioHost: ActionAwareIoHost): Logger {
+export function asSdkLogger(ioHost: IoHelper): Logger {
   return new class implements Logger {
     // This is too much detail for our logs
     public trace(..._content: any[]) {

packages/@aws-cdk/toolkit-lib/lib/api/io/private/timer.ts

@@ -1,7 +1,7 @@
 import { format } from 'util';
 import { CODES } from './codes';
 import { formatTime } from '../../../private/util';
-import type { ActionAwareIoHost } from '../../shared-private';
+import type { IoHelper } from '../../shared-private';
 
 /**
  * Helper class to measure the time of code.
@@ -37,7 +37,7 @@ export class Timer {
    * Ends the current timer as a specified timing and notifies the IoHost.
    * @returns the elapsed time
    */
-  public async endAs(ioHost: ActionAwareIoHost, type: 'synth' | 'deploy' | 'rollback' | 'destroy' | 'bootstrap') {
+  public async endAs(ioHost: IoHelper, type: 'synth' | 'deploy' | 'rollback' | 'destroy' | 'bootstrap') {
     const duration = this.end();
     await ioHost.notify(timerMessage(type, duration));
     return duration;

packages/@aws-cdk/toolkit-lib/lib/toolkit/private/index.ts

@@ -2,14 +2,14 @@
 import type { SdkProvider } from '../../api/aws-cdk';
 import type { ICloudAssemblySource } from '../../api/cloud-assembly';
 import { CachedCloudAssemblySource, StackAssembly } from '../../api/cloud-assembly/private';
-import type { ActionAwareIoHost } from '../../api/shared-private';
+import type { IoHelper } from '../../api/shared-private';
 
 /**
  * Helper struct to pass internal services around.
  */
 export interface ToolkitServices {
   sdkProvider: SdkProvider;
-  ioHost: ActionAwareIoHost;
+  ioHost: IoHelper;
 }
 
 /**

packages/@aws-cdk/toolkit-lib/lib/toolkit/toolkit.ts

@@ -26,8 +26,8 @@ import type { StackAssembly } from '../api/cloud-assembly/private';
 import { ALL_STACKS, CloudAssemblySourceBuilder, IdentityCloudAssemblySource } from '../api/cloud-assembly/private';
 import type { IIoHost, IoMessageLevel } from '../api/io';
 import { Timer, CODES, asSdkLogger, withoutColor, withoutEmojis, withTrimmedWhitespace } from '../api/io/private';
-import type { ActionAwareIoHost } from '../api/shared-private';
-import { withAction } from '../api/shared-private';
+import type { IoHelper } from '../api/shared-private';
+import { asIoHelper } from '../api/shared-private';
 import type { ToolkitAction } from '../api/shared-public';
 import { ToolkitError } from '../api/shared-public';
 import { obscureTemplate, serializeStructure, validateSnsTopicArn, formatTime, formatErrorMessage } from '../private/util';
@@ -130,7 +130,7 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
     if (!this._sdkProvider) {
       this._sdkProvider = await SdkProvider.withAwsCliCompatibleDefaults({
         ...this.props.sdkConfig,
-        logger: asSdkLogger(withAction(this.ioHost, action)),
+        logger: asSdkLogger(asIoHelper(this.ioHost, action)),
       });
     }
 
@@ -142,7 +142,7 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
    */
   protected override async sourceBuilderServices(): Promise<ToolkitServices> {
     return {
-      ioHost: withAction(this.ioHost, 'assembly'),
+      ioHost: asIoHelper(this.ioHost, 'assembly'),
       sdkProvider: await this.sdkProvider('assembly'),
     };
   }
@@ -151,7 +151,7 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
    * Bootstrap Action
    */
   public async bootstrap(environments: BootstrapEnvironments, options: BootstrapOptions): Promise<void> {
-    const ioHost = withAction(this.ioHost, 'bootstrap');
+    const ioHost = asIoHelper(this.ioHost, 'bootstrap');
     const bootstrapEnvironments = await environments.getEnvironments();
     const source = options.source ?? BootstrapSource.default();
     const parameters = options.parameters;
@@ -197,7 +197,7 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
    * Synth Action
    */
   public async synth(cx: ICloudAssemblySource, options: SynthOptions = {}): Promise<ICloudAssemblySource> {
-    const ioHost = withAction(this.ioHost, 'synth');
+    const ioHost = asIoHelper(this.ioHost, 'synth');
     const synthTimer = Timer.start();
     const assembly = await assemblyFromSource(cx);
     const stacks = assembly.selectStacksV2(options.stacks ?? ALL_STACKS);
@@ -242,7 +242,7 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
    * List selected stacks and their dependencies
    */
   public async list(cx: ICloudAssemblySource, options: ListOptions = {}): Promise<StackDetails[]> {
-    const ioHost = withAction(this.ioHost, 'list');
+    const ioHost = asIoHelper(this.ioHost, 'list');
     const synthTimer = Timer.start();
     const assembly = await assemblyFromSource(cx);
     const stackCollection = await assembly.selectStacksV2(options.stacks ?? ALL_STACKS);
@@ -269,7 +269,7 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
    * Helper to allow deploy being called as part of the watch action.
    */
   private async _deploy(assembly: StackAssembly, action: 'deploy' | 'watch', options: ExtendedDeployOptions = {}) {
-    const ioHost = withAction(this.ioHost, action);
+    const ioHost = asIoHelper(this.ioHost, action);
     const synthTimer = Timer.start();
     const stackCollection = assembly.selectStacksV2(options.stacks ?? ALL_STACKS);
     await this.validateStacksMetadata(stackCollection, ioHost);
@@ -571,7 +571,7 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
    */
   public async watch(cx: ICloudAssemblySource, options: WatchOptions): Promise<void> {
     const assembly = await assemblyFromSource(cx, false);
-    const ioHost = withAction(this.ioHost, 'watch');
+    const ioHost = asIoHelper(this.ioHost, 'watch');
     const rootDir = options.watchDir ?? process.cwd();
 
     if (options.include === undefined && options.exclude === undefined) {
@@ -694,7 +694,7 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
    * Helper to allow rollback being called as part of the deploy or watch action.
    */
   private async _rollback(assembly: StackAssembly, action: 'rollback' | 'deploy' | 'watch', options: RollbackOptions): Promise<void> {
-    const ioHost = withAction(this.ioHost, action);
+    const ioHost = asIoHelper(this.ioHost, action);
     const synthTimer = Timer.start();
     const stacks = assembly.selectStacksV2(options.stacks);
     await this.validateStacksMetadata(stacks, ioHost);
@@ -752,7 +752,7 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
    * Helper to allow destroy being called as part of the deploy action.
    */
   private async _destroy(assembly: StackAssembly, action: 'deploy' | 'destroy', options: DestroyOptions): Promise<void> {
-    const ioHost = withAction(this.ioHost, action);
+    const ioHost = asIoHelper(this.ioHost, action);
     const synthTimer = Timer.start();
     // The stacks will have been ordered for deployment, so reverse them for deletion.
     const stacks = await assembly.selectStacksV2(options.stacks).reversed();
@@ -794,7 +794,7 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
   /**
    * Validate the stacks for errors and warnings according to the CLI's current settings
    */
-  private async validateStacksMetadata(stacks: StackCollection, ioHost: ActionAwareIoHost) {
+  private async validateStacksMetadata(stacks: StackCollection, ioHost: IoHelper) {
     const builder = (level: IoMessageLevel) => {
       switch (level) {
         case 'error': return CODES.CDK_ASSEMBLY_E9999;

packages/aws-cdk/lib/api/resource-import/importer.ts

@@ -5,7 +5,7 @@ import * as cxapi from '@aws-cdk/cx-api';
 import * as chalk from 'chalk';
 import * as fs from 'fs-extra';
 import * as promptly from 'promptly';
-import { ActionAwareIoHost, withAction } from '../../../../@aws-cdk/tmp-toolkit-helpers/src/api/io/private';
+import { IoHelper, asIoHelper } from '../../../../@aws-cdk/tmp-toolkit-helpers/src/api/io/private';
 import { error, info, warn } from '../../cli/messages';
 import type { IIoHost, IoMessaging } from '../../toolkit/cli-io-host';
 import { ToolkitError } from '../../toolkit/error';
@@ -103,15 +103,15 @@ export class ResourceImporter {
 
   private readonly stack: cxapi.CloudFormationStackArtifact;
   private readonly cfn: Deployments;
-  private readonly ioHost: ActionAwareIoHost;
+  private readonly ioHost: IoHelper;
 
   constructor(
     stack: cxapi.CloudFormationStackArtifact,
     props: ResourceImporterProps,
   ) {
     this.stack = stack;
     this.cfn = props.deployments;
-    this.ioHost = withAction(props.ioHost, props.action as any);
+    this.ioHost = asIoHelper(props.ioHost, props.action as any);
   }
 
   /**