@aws-cdk/toolkit-lib 0.1.7 → 0.2.0

package/lib/toolkit/toolkit.d.ts

@@ -1,7 +1,8 @@
-import type { ToolkitServices } from './private';
+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 RollbackOptions } from '../actions/rollback';
 import { type SynthOptions } from '../actions/synth';
@@ -15,13 +16,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
@@ -30,28 +31,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.
@@ -61,18 +62,11 @@ 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
      */
@@ -81,6 +75,10 @@ export declare class Toolkit extends CloudAssemblySourceBuilder implements Async
      * Synth Action
      */
     synth(cx: ICloudAssemblySource, options?: SynthOptions): Promise<ICloudAssemblySource>;
+    /**
+     * Diff Action
+     */
+    diff(cx: ICloudAssemblySource, options: DiffOptions): Promise<void>;
     /**
      * List Action
      *
@@ -92,7 +90,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.
      */
@@ -100,16 +98,18 @@ 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.
      */
@@ -119,7 +119,7 @@ export declare class Toolkit extends CloudAssemblySourceBuilder implements Async
      *
      * 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.
      */
@@ -134,3 +134,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>;
+}