feat: construct base class changes (breaking) (#1444)

- Rename "parent" to "scope" in all construct initializers and imports (fixes #1431)
- Group all members (besides `validate`) under a `node` property so they don't pollute the surface area of derived classes (fixes #1441)
- Define `IConstruct` and have all `IXxx` extend it
- Normalize construct ID to `id` across the board (fixes #189)

BREAKING CHANGE: Multiple breaking changes:

  - All the APIs of `cdk.Construct` are now available under `construct.node` (e.g. instead of `construct.path` use `construct.node.path`. See #1441 for details.
  - Construct `parent` was renamed to `scope`. See #1431 for more details.
  - First argument of `codepipeline.CrossRegionScaffoldStack` is now required.
  - `IPipeline.uniqueId` removed and can now be accessed via `pipeline.node.uniqueId`.

examples/cdk-examples-typescript/advanced-usage/index.ts

@@ -10,8 +10,8 @@ import cdk = require('@aws-cdk/cdk');
  * This stack demonstrates the use of the IAM policy library shipped with the CDK.
  */
 class PolicyExample extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     // here's how to create an IAM Role with an assume policy for the Lambda
     // service principal.
@@ -38,8 +38,8 @@ class PolicyExample extends cdk.Stack {
  * the AZ list and the AMI IDs are different.
  */
 class EnvContextExample extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     // get the list of AZs for the current region/account
     const azs = new cdk.AvailabilityZoneProvider(this).availabilityZones;
@@ -68,8 +68,8 @@ class EnvContextExample extends cdk.Stack {
  * into your CDK stack and then add constructs and resources programmatically to it.
  */
 class IncludeExample extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     // so you have an existing template...
     // you can also load it from a file:
@@ -89,14 +89,14 @@ class IncludeExample extends cdk.Stack {
     new cdk.Include(this, 'Include', { template });
 
     // add constructs (and resources) programmatically
-    new EnvContextExample(parent, 'Example');
+    new EnvContextExample(scope, 'Example');
     new sqs.CfnQueue(this, 'CDKQueue', {});
   }
 }
 
 class NestedStackExample extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     // pick up to 3 AZs from environment.
     const azs = new cdk.AvailabilityZoneProvider(this).availabilityZones.slice(0, 3);
@@ -122,8 +122,8 @@ class NestedStackExample extends cdk.Stack {
  * It also demonstrates how to modify resource options such as metadata
  */
 class ResourceReferencesExample extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     const topic = new sns.CfnTopic(this, 'Topic', {});
     const queue = new sqs.CfnQueue(this, 'Queue', {});
@@ -145,8 +145,8 @@ class ResourceReferencesExample extends cdk.Stack {
  * Demonstrates how to use CloudFormation parameters, outputs, pseudo parameters and intrinsic functions.
  */
 class CloudFormationExample extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     // parameters are constructs that synthesize into the template's "Parameters" section
     const param = new cdk.Parameter(this, 'MyTemplateParameter', {

examples/cdk-examples-typescript/bucket-import-export/index.ts

@@ -9,8 +9,8 @@ import cdk = require('@aws-cdk/cdk');
 class Producer extends cdk.Stack {
   public readonly myBucketRef: s3.BucketImportProps;
 
-  constructor(parent: cdk.App, name: string) {
-    super(parent, name);
+  constructor(scope: cdk.App, id: string) {
+    super(scope, id);
 
     const bucket = new s3.Bucket(this, 'MyBucket');
     this.myBucketRef = bucket.export();
@@ -22,8 +22,8 @@ interface ConsumerConstructProps {
 }
 
 class ConsumerConstruct extends cdk.Construct {
-  constructor(parent: cdk.Construct, name: string, props: ConsumerConstructProps) {
-    super(parent, name);
+  constructor(scope: cdk.Construct, id: string, props: ConsumerConstructProps) {
+    super(scope, id);
 
     props.bucket.addToResourcePolicy(new iam.PolicyStatement().addAction('*'));
   }
@@ -39,8 +39,8 @@ interface ConsumerProps {
 }
 
 class Consumer extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props: ConsumerProps) {
-    super(parent, name);
+  constructor(scope: cdk.App, id: string, props: ConsumerProps) {
+    super(scope, id);
 
     const user = new iam.User(this, 'MyUser');
     const userBucket = s3.Bucket.import(this, 'ImportBucket', props.userBucketRef);

examples/cdk-examples-typescript/chat-app/cognito-chat-room-pool.ts

@@ -2,8 +2,8 @@ import cognito = require('@aws-cdk/aws-cognito');
 import cdk = require('@aws-cdk/cdk');
 
 export class CognitoChatRoomPool extends cdk.Construct {
-  constructor(parent: cdk.Construct, name: string) {
-    super(parent, name);
+  constructor(scope: cdk.Construct, id: string) {
+    super(scope, id);
 
     // Create chat room user pool
     const chatPool = new cognito.CfnUserPool(this, 'UserPool', {

examples/cdk-examples-typescript/chat-app/dynamodb-posts-table.ts

@@ -2,8 +2,8 @@ import dynamodb = require('@aws-cdk/aws-dynamodb');
 import cdk = require('@aws-cdk/cdk');
 
 export class DynamoPostsTable extends cdk.Construct {
-  constructor(parent: cdk.Construct, name: string) {
-    super(parent, name);
+  constructor(scope: cdk.Construct, id: string) {
+    super(scope, id);
 
     const table = new dynamodb.Table(this, 'Table', {
       readCapacity: 5, writeCapacity: 5

examples/cdk-examples-typescript/chat-app/index.ts

@@ -5,8 +5,8 @@ import { CognitoChatRoomPool } from './cognito-chat-room-pool';
 import { DynamoPostsTable } from './dynamodb-posts-table';
 
 class MyStack extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     new DynamoPostsTable(this, 'Posts');
 
@@ -77,8 +77,8 @@ interface ChatAppFuncProps {
  * Extend Function as all of the Chat app functions have these common props.
  */
 class ChatAppFunction extends lambda.Function {
-  constructor(parent: cdk.Construct, name: string, props: ChatAppFuncProps) {
-    super(parent, name, {
+  constructor(scope: cdk.Construct, id: string, props: ChatAppFuncProps) {
+    super(scope, id, {
       code: new lambda.S3Code(props.bucket, props.zipFile),
       runtime: lambda.Runtime.NodeJS610,
       handler: 'index.handler'

examples/cdk-examples-typescript/cloudformation/index.ts

@@ -2,8 +2,8 @@ import sqs = require('@aws-cdk/aws-sqs');
 import cdk = require('@aws-cdk/cdk');
 
 class CloudFormationExample extends cdk.Stack {
-  constructor(parent: cdk.App) {
-    super(parent);
+  constructor(scope: cdk.App) {
+    super(scope);
 
     new sqs.CfnQueue(this, 'MyQueue', {
       visibilityTimeout: 300

examples/cdk-examples-typescript/custom-resource/index.ts

@@ -20,8 +20,8 @@ class DemoResource extends cdk.Construct implements cdk.IDependable {
   public readonly dependencyElements: cdk.IDependable[];
   public readonly response: string;
 
-  constructor(parent: cdk.Construct, name: string, props: DemoResourceProps) {
-    super(parent, name);
+  constructor(scope: cdk.Construct, id: string, props: DemoResourceProps) {
+    super(scope, id);
 
     const resource = new CustomResource(this, 'Resource', {
       lambdaProvider: new lambda.SingletonFunction(this, 'Singleton', {
@@ -44,8 +44,8 @@ class DemoResource extends cdk.Construct implements cdk.IDependable {
  * A stack that only sets up the CustomResource and shows how to get an attribute from it
  */
 class SucceedingStack extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     const resource = new DemoResource(this, 'DemoResource', {
       message: 'CustomResource says hello',
@@ -63,8 +63,8 @@ class SucceedingStack extends cdk.Stack {
  * A stack that sets up a failing CustomResource creation
  */
 class FailCreationStack extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     new DemoResource(this, 'DemoResource', {
       message: 'CustomResource is silent',
@@ -78,8 +78,8 @@ class FailCreationStack extends cdk.Stack {
  * done properly.
  */
 class FailAfterCreatingStack extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     const resource = new DemoResource(this, 'DemoResource', {
       message: 'CustomResource says hello',

examples/cdk-examples-typescript/ec2/index.ts

@@ -4,8 +4,8 @@ import elb = require('@aws-cdk/aws-elasticloadbalancing');
 import cdk = require('@aws-cdk/cdk');
 
 class AppWithVpc extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     const vpc = new ec2.VpcNetwork(this, 'MyVpc');
 
@@ -30,8 +30,8 @@ interface MyAppProps extends cdk.StackProps {
 }
 
 class MyApp extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props: MyAppProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props: MyAppProps) {
+    super(scope, id, props);
 
     const vpc = ec2.VpcNetwork.import(this, 'VPC', props.infra.vpc);
 
@@ -54,8 +54,8 @@ class MyApp extends cdk.Stack {
 class CommonInfrastructure extends cdk.Stack {
   public vpc: ec2.VpcNetworkImportProps;
 
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     const vpc = new ec2.VpcNetwork(this, 'VPC');
     this.vpc = vpc.export();

examples/cdk-examples-typescript/hello-cdk-ecs/index.ts

@@ -4,8 +4,8 @@ import ecs = require('@aws-cdk/aws-ecs');
 import cdk = require('@aws-cdk/cdk');
 
 class BonjourECS extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     // For better iteration speed, it might make sense to put this VPC into
     // a separate stack and import it here. We then have two stacks to

examples/cdk-examples-typescript/hello-cdk-fargate/index.ts

@@ -3,8 +3,8 @@ import ecs = require('@aws-cdk/aws-ecs');
 import cdk = require('@aws-cdk/cdk');
 
 class BonjourFargate extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     // Create VPC and Fargate Cluster
     // NOTE: Limit AZs to avoid reaching resource quotas

examples/cdk-examples-typescript/hello-cdk/index.ts

@@ -2,8 +2,8 @@ import dynamodb = require('@aws-cdk/aws-dynamodb');
 import cdk = require('@aws-cdk/cdk');
 
 class HelloCDK extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props?: cdk.StackProps) {
-    super(parent, name, props);
+  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
+    super(scope, id, props);
 
     const table = new dynamodb.Table(this, 'Table', {
       readCapacity: 1,

examples/cdk-examples-typescript/resource-overrides/index.ts

@@ -5,8 +5,8 @@ import cdk = require('@aws-cdk/cdk');
 import assert = require('assert');
 
 class ResourceOverridesExample extends cdk.Stack {
-    constructor(parent: cdk.App, id: string) {
-        super(parent, id);
+    constructor(scope: cdk.App, id: string) {
+        super(scope, id);
 
         const otherBucket = new s3.Bucket(this, 'Other');
 
@@ -15,25 +15,23 @@ class ResourceOverridesExample extends cdk.Stack {
             encryption: s3.BucketEncryption.KmsManaged
         });
 
-        const bucketResource2 = bucket.findChild('Resource') as s3.CfnBucket;
+        const bucketResource2 = bucket.node.findChild('Resource') as s3.CfnBucket;
         bucketResource2.addPropertyOverride('BucketEncryption.ServerSideEncryptionConfiguration.0.EncryptEverythingAndAlways', true);
         bucketResource2.addPropertyDeletionOverride('BucketEncryption.ServerSideEncryptionConfiguration.0.ServerSideEncryptionByDefault');
 
-        return;
-
         //
         // Accessing the L1 bucket resource from an L2 bucket
         //
 
-        const bucketResource = bucket.findChild('Resource') as s3.CfnBucket;
-        const anotherWay = bucket.children.find(c => (c as cdk.Resource).resourceType === 'AWS::S3::Bucket') as s3.CfnBucket;
+        const bucketResource = bucket.node.findChild('Resource') as s3.CfnBucket;
+        const anotherWay = bucket.node.children.find(c => (c as cdk.Resource).resourceType === 'AWS::S3::Bucket') as s3.CfnBucket;
         assert.equal(bucketResource, anotherWay);
 
         //
         // This is how to specify resource options such as dependencies, metadata, update policy
         //
 
-        bucketResource.addDependency(otherBucket.findChild('Resource') as cdk.Resource);
+        bucketResource.addDependency(otherBucket.node.findChild('Resource') as cdk.Resource);
         bucketResource.options.metadata = { MetadataKey: 'MetadataValue' };
         bucketResource.options.updatePolicy = {
             autoScalingRollingUpdate: {
@@ -108,7 +106,7 @@ class ResourceOverridesExample extends cdk.Stack {
         // need to consule the codebase or use the `.map.find` method above
         //
 
-        const lc = asg.findChild('LaunchConfig') as autoscaling.CfnLaunchConfiguration;
+        const lc = asg.node.findChild('LaunchConfig') as autoscaling.CfnLaunchConfiguration;
         lc.addPropertyOverride('Foo.Bar', 'Hello');
     }
 }

examples/cdk-examples-typescript/sns-sqs/index.ts

@@ -4,8 +4,8 @@ import sqs = require('@aws-cdk/aws-sqs');
 import cdk = require('@aws-cdk/cdk');
 
 class ACL extends cdk.Stack {
-  constructor(parent: cdk.App, name: string) {
-    super(parent, name);
+  constructor(scope: cdk.App, id: string) {
+    super(scope, id);
 
     const topic = new sns.Topic(this, 'MyTopic');
     const queue = new sqs.Queue(this, 'MyQueue', {
@@ -17,8 +17,8 @@ class ACL extends cdk.Stack {
 }
 
 class CFN extends cdk.Stack {
-  constructor(parent: cdk.App, name: string) {
-    super(parent, name);
+  constructor(scope: cdk.App, id: string) {
+    super(scope, id);
 
     const topic = new sns.CfnTopic(this, 'MyTopic');
     const queue = new sqs.CfnQueue(this, 'MyQueue');

packages/@aws-cdk/alexa-ask/.npmignore

@@ -15,3 +15,7 @@ dist
 .LAST_BUILD
 .LAST_PACKAGE
 .jsii
+
+
+# Include .jsii
+!.jsii

packages/@aws-cdk/app-delivery/lib/pipeline-deploy-stack-action.ts

@@ -101,8 +101,8 @@ export class PipelineDeployStackAction extends cdk.Construct {
 
   private readonly stack: cdk.Stack;
 
-  constructor(parent: cdk.Construct, id: string, props: PipelineDeployStackActionProps) {
-    super(parent, id);
+  constructor(scope: cdk.Construct, id: string, props: PipelineDeployStackActionProps) {
+    super(scope, id);
 
     if (!cdk.environmentEquals(props.stack.env, cdk.Stack.find(this).env)) {
       // FIXME: Add the necessary to extend to stacks in a different account
@@ -142,7 +142,7 @@ export class PipelineDeployStackAction extends cdk.Construct {
 
   public validate(): string[] {
     const result = super.validate();
-    const assets = this.stack.metadata.filter(md => md.type === cxapi.ASSET_METADATA);
+    const assets = this.stack.node.metadata.filter(md => md.type === cxapi.ASSET_METADATA);
     if (assets.length > 0) {
       // FIXME: Implement the necessary actions to publish assets
       result.push(`Cannot deploy the stack ${this.stack.name} because it references ${assets.length} asset(s)`);

packages/@aws-cdk/app-delivery/test/test.pipeline-deploy-stack-action.ts

@@ -272,7 +272,7 @@ export = nodeunit.testCase({
             adminPermissions: false,
           });
           for (let i = 0 ; i < assetCount ; i++) {
-            deployedStack.addMetadata(cxapi.ASSET_METADATA, {});
+            deployedStack.node.addMetadata(cxapi.ASSET_METADATA, {});
           }
           test.deepEqual(action.validate(),
             [`Cannot deploy the stack DeployedStack because it references ${assetCount} asset(s)`]);
@@ -286,8 +286,8 @@ export = nodeunit.testCase({
 class FakeAction extends api.Action {
   public readonly outputArtifact: api.Artifact;
 
-  constructor(parent: cdk.Construct, id: string, pipeline: code.Pipeline) {
-    super(parent, id, {
+  constructor(scope: cdk.Construct, id: string, pipeline: code.Pipeline) {
+    super(scope, id, {
       artifactBounds: api.defaultBounds(),
       category: api.ActionCategory.Test,
       provider: 'Test',