@aws-cdk/toolkit-lib 0.1.8 → 0.3.0

package/lib/toolkit/toolkit.d.ts

@@ -1,14 +1,17 @@
-import type { ToolkitServices } from './private';
+import type { TemplateDiff } from '@aws-cdk/cloudformation-diff';
+import type { DeployResult, DestroyResult, RollbackResult } from './types';
 import type { BootstrapEnvironments, BootstrapOptions, BootstrapResult } from '../actions/bootstrap';
 import { type DeployOptions } from '../actions/deploy';
 import { type DestroyOptions } from '../actions/destroy';
 import type { DiffOptions } from '../actions/diff';
 import { type ListOptions } from '../actions/list';
+import type { RefactorOptions } from '../actions/refactor';
 import { type RollbackOptions } from '../actions/rollback';
 import { type SynthOptions } from '../actions/synth';
 import type { WatchOptions } from '../actions/watch';
 import { type SdkConfig } from '../api/aws-auth';
 import type { ICloudAssemblySource } from '../api/cloud-assembly';
+import { CachedCloudAssembly } from '../api/cloud-assembly';
 import { CloudAssemblySourceBuilder } from '../api/cloud-assembly/private';
 import type { IIoHost } from '../api/io';
 import type { StackDetails } from '../api/shared-public';
@@ -16,13 +19,13 @@ export interface ToolkitOptions {
     /**
      * The IoHost implementation, handling the inline interactions between the Toolkit and an integration.
      */
-    ioHost?: IIoHost;
+    readonly ioHost?: IIoHost;
     /**
      * Allow emojis in messages sent to the IoHost.
      *
      * @default true
      */
-    emojis?: boolean;
+    readonly emojis?: boolean;
     /**
      * Whether to allow ANSI colors and formatting in IoHost messages.
      * Setting this value to `false` enforces that no color or style shows up
@@ -31,28 +34,28 @@ export interface ToolkitOptions {
      *
      * @default - detects color from the TTY status of the IoHost
      */
-    color?: boolean;
+    readonly color?: boolean;
     /**
      * Configuration options for the SDK.
      */
-    sdkConfig?: SdkConfig;
+    readonly sdkConfig?: SdkConfig;
     /**
      * Name of the toolkit stack to be used.
      *
      * @default "CDKToolkit"
      */
-    toolkitStackName?: string;
+    readonly toolkitStackName?: string;
     /**
      * Fail Cloud Assemblies
      *
      * @default "error"
      */
-    assemblyFailureAt?: 'error' | 'warn' | 'none';
+    readonly assemblyFailureAt?: 'error' | 'warn' | 'none';
 }
 /**
  * The AWS CDK Programmatic Toolkit
  */
-export declare class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposable {
+export declare class Toolkit extends CloudAssemblySourceBuilder {
     private readonly props;
     /**
      * The toolkit stack name used for bootstrapping resources.
@@ -62,30 +65,28 @@ export declare class Toolkit extends CloudAssemblySourceBuilder implements Async
      * The IoHost of this Toolkit
      */
     readonly ioHost: IIoHost;
-    private _sdkProvider?;
-    constructor(props?: ToolkitOptions);
-    dispose(): Promise<void>;
-    [Symbol.asyncDispose](): Promise<void>;
     /**
-     * Access to the AWS SDK
+     * Cache of the internal SDK Provider instance
      */
-    private sdkProvider;
-    /**
-     * Helper to provide the CloudAssemblySourceBuilder with required toolkit services
-     */
-    protected sourceBuilderServices(): Promise<ToolkitServices>;
+    private sdkProviderCache?;
+    constructor(props?: ToolkitOptions);
     /**
      * Bootstrap Action
      */
     bootstrap(environments: BootstrapEnvironments, options: BootstrapOptions): Promise<BootstrapResult>;
     /**
      * Synth Action
+     *
+     * The caller assumes ownership of the `CachedCloudAssembly` and is responsible for calling `dispose()` on
+     * it after use.
      */
-    synth(cx: ICloudAssemblySource, options?: SynthOptions): Promise<ICloudAssemblySource>;
+    synth(cx: ICloudAssemblySource, options?: SynthOptions): Promise<CachedCloudAssembly>;
     /**
      * Diff Action
      */
-    diff(cx: ICloudAssemblySource, options: DiffOptions): Promise<void>;
+    diff(cx: ICloudAssemblySource, options: DiffOptions): Promise<{
+        [name: string]: TemplateDiff;
+    }>;
     /**
      * List Action
      *
@@ -97,7 +98,7 @@ export declare class Toolkit extends CloudAssemblySourceBuilder implements Async
      *
      * Deploys the selected stacks into an AWS account
      */
-    deploy(cx: ICloudAssemblySource, options?: DeployOptions): Promise<void>;
+    deploy(cx: ICloudAssemblySource, options?: DeployOptions): Promise<DeployResult>;
     /**
      * Helper to allow deploy being called as part of the watch action.
      */
@@ -105,26 +106,33 @@ export declare class Toolkit extends CloudAssemblySourceBuilder implements Async
     /**
      * Watch Action
      *
-     * Continuously observe project files and deploy the selected stacks automatically when changes are detected.
-     * Implies hotswap deployments.
+     * Continuously observe project files and deploy the selected stacks
+     * automatically when changes are detected.  Implies hotswap deployments.
+     *
+     * This function returns immediately, starting a watcher in the background.
      */
-    watch(cx: ICloudAssemblySource, options: WatchOptions): Promise<void>;
+    watch(cx: ICloudAssemblySource, options: WatchOptions): Promise<IWatcher>;
     /**
      * Rollback Action
      *
      * Rolls back the selected stacks.
      */
-    rollback(cx: ICloudAssemblySource, options: RollbackOptions): Promise<void>;
+    rollback(cx: ICloudAssemblySource, options: RollbackOptions): Promise<RollbackResult>;
     /**
      * Helper to allow rollback being called as part of the deploy or watch action.
      */
     private _rollback;
+    /**
+     * Refactor Action. Moves resources from one location (stack + logical ID) to another.
+     */
+    refactor(cx: ICloudAssemblySource, options?: RefactorOptions): Promise<void>;
+    private _refactor;
     /**
      * Destroy Action
      *
      * Destroys the selected Stacks.
      */
-    destroy(cx: ICloudAssemblySource, options: DestroyOptions): Promise<void>;
+    destroy(cx: ICloudAssemblySource, options: DestroyOptions): Promise<DestroyResult>;
     /**
      * Helper to allow destroy being called as part of the deploy action.
      */
@@ -139,3 +147,23 @@ export declare class Toolkit extends CloudAssemblySourceBuilder implements Async
     private deploymentsForAction;
     private invokeDeployFromWatch;
 }
+/**
+ * The result of a `cdk.watch()` operation.
+ */
+export interface IWatcher extends AsyncDisposable {
+    /**
+     * Stop the watcher and wait for the current watch iteration to complete.
+     *
+     * An alias for `[Symbol.asyncDispose]`, as a more readable alternative for
+     * environments that don't support the Disposable APIs yet.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Wait for the watcher to stop.
+     *
+     * The watcher will only stop if `dispose()` or `[Symbol.asyncDispose]()` are called.
+     *
+     * If neither of those is called, awaiting this promise will wait forever.
+     */
+    waitForEnd(): Promise<void>;
+}