feat(concepts): "scope" instead of "parent"

doc_source/concepts.md

@@ -1,15 +1,12 @@
 --------
 
- This documentation is for the developer preview release of the AWS CDK\. Do not use this version of the AWS CDK in production\. Subsequent releases of the AWS CDK will likely include breaking changes\. 
+ This documentation is for the developer preview release of the AWS CDK\. Do not use this version of the AWS CDK in production\. Subsequent releases of the AWS CDK will likely include breaking changes\.
 
 --------
 
 # AWS CDK Concepts<a name="concepts"></a>
 
-This topic describes some of the concepts \(the why and how\) behind the AWS CDK\. It also discusses the advantages of a AWS Construct Library over a low\-level CloudFormation Resource\.
+This topic describes some of the concepts \(the why and how\) behind the AWS CDK\. It also discusses the advantages of the AWS Construct Library over a low\-level CloudFormation Resource\.
 
-AWS CDK apps are represented as a hierarchal structure we call the *construct tree*\. Every node in the tree is a [Construct](https://awslabs.github.io/aws-cdk/refs/_aws-cdk_cdk.html#construct) object\. The root of an AWS CDK app is typically an [App](https://awslabs.github.io/aws-cdk/refs/_aws-cdk_cdk.html#app) construct\. Apps contain one or more [Stack](https://awslabs.github.io/aws-cdk/refs/_aws-cdk_cdk.html#@aws-cdk/cdk.Stack) constructs, which are deployable units of your app\.
+AWS CDK apps are composed of building blocks called [constructs](https://awslabs.github.io/aws-cdk/refs/_aws-cdk_cdk.html#construct), which are composed together to form [Stacks](https://awslabs.github.io/aws-cdk/refs/_aws-cdk_cdk.html#@aws-cdk/cdk.Stack) and [Apps](https://awslabs.github.io/aws-cdk/refs/_aws-cdk_cdk.html#app).
 
-This composition of constructs gives you the flexibility to architect your app, such as having a stack deployed in multiple regions\. Stacks represent a collection of AWS resources, either directly or indirectly through a child construct that itself represents an AWS resource, such as an Amazon SQS queue, an Amazon SNS topic, a Lambda function, or a DynamoDB table\.
-
-This composition of constructs also means you can easily create sharable constructs, and make changes to any construct and have those changes available to consumers as shared class libraries\.

doc_source/constructs.md

@@ -1,104 +1,100 @@
 --------
 
- This documentation is for the developer preview release of the AWS CDK\. Do not use this version of the AWS CDK in production\. Subsequent releases of the AWS CDK will likely include breaking changes\. 
+ This documentation is for the developer preview release of the AWS CDK\. Do not use this version of the AWS CDK in production\. Subsequent releases of the AWS CDK will likely include breaking changes\.
 
 --------
 
 # Constructs<a name="constructs"></a>
 
-Constructs are the building blocks of AWS CDK applications\. Constructs can have child constructs, which in turn can have child constructs, forming a hierarchical tree structure\.
+Constructs can be viewed as "cloud components". They can represent architectures of any complexity. They can represent a single resource, such as an Amazon S3 Bucket or an Amazon SNS Topic, reusable components such as a static website, a part of a specific application and up to complex multi-stack applications that span multiple accounts and region. Everything in the AWS CDK is a construct.
 
-The AWS CDK includes two different levels of constructs:
+This composition of constructs also means you can easily create sharable constructs, and make changes to any construct and have those changes available to consumers as shared class libraries\.
 
-CloudFormation Resource  
-These constructs are low\-level constructs that provide a direct, one\-to\-one, mapping to an AWS CloudFormation resource, as listed in the AWS CloudFormation topic [ AWS Resource Types Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html)\.   
-All CloudFormation Resource members are found in the `@aws-cdk/resources` package\.
+## The AWS Construct Library
 
-AWS Construct Library  
-These constructs have been handwritten by AWS and come with convenient defaults and additional knowledge about the inner workings of the AWS resources they represent\. In general, you will be able to express your intent without worrying about the details too much, and the correct resources will automatically be defined for you\.  
-AWS Construct Library members are found in the `@aws-cdk/aws-NAMESPACE` packages, where NAMESPACE is the short name for the associated service, such as SQS for the AWS Construct Library for the Amazon SQS service\. See the [Reference](https://awslabs.github.io/aws-cdk/reference.html#reference) section for descriptions of the AWS CDK packages and constructs\.
+The AWS CDK is shipped with a rich class library of constructs called the **AWS Construct Library**. This library consists of constructs that represent all the resources available on AWS.
+
+Each module in the AWS Construct Library includes two types of constructs for each resource: low-level and high-level.
+
+The low-level resources are automatically generated from the [AWS CloudFormation Resource Types Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html). Low-level constructs are named `CfnXyz` (where "Xyz" represents the name of the resource) and provide direct, one-to-one access to how a resource is synthesized in the CloudFormation template produced by your CDK app. Using low-level resources require explicit configuration of all resource properties, IAM policies and requires deep understanding of the details.
+
+High-level resources are hand-written by AWS and offer a rich, intent-based API for using AWS services. They offer the same functionality as the low-level resources but encode much of the details, boilerplate and glue-logic required in order to use AWS. High-level resources offer convenient defaults and additional knowledge about the inner workings of the AWS resources they represent\. In general, you will be able to express your intent without worrying about the details too much, and the correct resources and configuration will automatically be defined for you\.  
+
+Similarly to the AWS SDKs and AWS CloudFormation, the AWS Construct Library is organized into modules, one for each AWS service. For example, the `@aws-cdk/aws-ec2` module includes resources for EC2 instances, Auto Scaling Groups and VPCs, the aws-sns module includes resources such as Topic and Subscription, and so forth. See the [Reference](https://awslabs.github.io/aws-cdk/reference.html#reference) section for descriptions of the AWS CDK packages and constructs\.
+
+AWS Construct Library members are found in the `@aws-cdk/aws-NAMESPACE` packages, where NAMESPACE is the short name for the associated service, such as SQS for the AWS Construct Library for the Amazon SQS service\.
 
 ## Construct Structure<a name="constructs_structure"></a>
 
-The construct tree structure is a powerful design pattern for composing high\-level abstractions\. For example, you can define a `StorageLayer` construct that represents your application's storage layer and include all the AWS resources, such as DynamoDB tables and Amazon S3 buckets, needed to implement your storage layer in this construct\. When your higher\-level code uses this construct, it only needs to instantiate the `StorageLayer` construct\.
+Constructs are represented as normal classes in your code and are defined by instantiating an object of that class.
 
-When you initialize a construct, add the construct to the construct tree by specifying the parent construct as the first initializer parameter, an identifier for the construct as the second parameter, and a set of properties for the final parameter, as shown in the following example\.
+When constructs are initialized, they are always defined within the _**scope**_ of another construct and they always have an _**id**_ which must be unique within the same scope.
 
-```
-new SomeConstruct(parent, name[, props]);
+For example, here's how you would define an SNS Topic in your stack with default configuration:
+
+```ts
+new sns.Topic(this, 'MyTopic');
 ```
 
-In almost all cases, you should pass the keyword `this` for the `parent` argument, because you will generally initialize new constructs in the context of the parent construct\. Any descriptive string will do for the `name` argument, and an in\-line object for the set of properties\.
+The first argument to every construct is always the scope in which it is created, and will almost always be simply `this` because most constructs will be defined within the current scope.
 
-```
+Scopes enable constructs to be composed together to form higher-level abstractions by enabling the framework to group them together into logical units, allocate globally unique identifiers and allow them to consult __context information__ such as the region in which it is going to be deployed into, which AZs are available for my account, etc.
+
+In most cases, the construct initializer will have a third `props` argument that can be used to define the construct's initial configuration. For example:
+
+```ts
 new BeautifulConstruct(this, 'Foo', {
-    applicationName: 'myApp',
-    timeout: 300
+  favoriteColor: 'green',
+  timeout: 300
 });
 ```
 
-**Note**  
-Associating the construct to its parent as part of initialization is necessary because the construct occasionally needs contextual information from its parent, such as to which the region the stack is deployed\.
+The `construct.node` property can be used to interact with the construct's node representation:
 
-Use the following operations to inspect the construct tree\.
+* `construct.node.scope` The scope in which this construct was defined.
 
- aws\-cdk\.Construct\.parent   
-Gets the path of this construct from the root of the tree\.
+* `construct.node.id` Returns the "id" of the construct passed upon creation.
 
- aws\-cdk\.Construct\.getChildren   
-Gets an array of all of the contruct's children\.
+* `construct.node.uniqueId` Returns an app-wide unique safe ID of this construct. This ID encodes the construct's path into a human readable portion as well as a hash of the full path to ensure global uniqueness.
 
- aws\-cdk\.Construct\.getChild   
-Gets the child construct with the specified ID\.
+* `construct.node.path` Gets the path of this construct from the root of scope (the `App`)\.
 
- aws\-cdk\.Construct\.toTreeString\(\)   
-Gets a string representing the construct's tree\.
+## Construct IDs<a name="constructs_ids"></a>
 
-## Construct Names<a name="constructs_EVER"></a>
+Every construct in a CDK app must have an **id** unique within the scope in which the construct is defined. IDs are used to find constructs in the construct hierarchy, and to allocate logical IDs so that AWS CloudFormation can keep track of the generated resources\.
 
-Every construct in a CDK app must have a **name** unique among its siblings\. Names are used to track constructs in the construct hierarchy, and to allocate logical IDs so that AWS CloudFormation can keep track of the generated resources\.
-
-When a construct is created, its name is specified as the second initializer argument:
+When a construct is created, its ID is specified as the second initializer argument:
 
 ```
 const c1 = new MyBeautifulConstruct(this, 'OneBeautiful');
 const c2 = new MyBeautifulConstruct(this, 'TwoBeautiful');
-assert(c1.name === 'OneBeautiful');
-assert(c2.name === 'TwoBeautiful');
+assert(c1.node.id === 'OneBeautiful');
+assert(c2.node.id === 'TwoBeautiful');
 ```
 
-Use the `aws-cdk.Construct.path` property to get the path of this construct from the root of the tree\.
-
-Note that the name of a construct does not directly map onto the physical name of the resource when it is created\. If you want to give a physical name to a bucket or table, specify the physical name using use the appropriate property, such as `bucketName` or `tableName`, as shown in the following example:
+Note that the ID of a construct does not directly map onto the physical name of the resource when it is created\. If you want to give a physical name to a bucket or table, specify the physical name using use the appropriate property, such as `bucketName` or `tableName`, as shown in the following example:
 
 ```
-new Bucket(this, 'MyBucket', {
-    bucketName: 'physical-bucket-name'
+new s3.Bucket(this, 'MyBucket', {
+  bucketName: 'physical-bucket-name'
 });
 ```
 
-Avoid specifying physical names\. Instead, let AWS CloudFormation generate names for you\. Use attributes, such as `bucket.bucketName`, to discover the generated names\.
+In general it's recommended to avoid specifying physical names\. Instead, let AWS CloudFormation generate names for you\. Use attributes, such as `bucket.bucketName`, to discover the generated names\.
 
-When you synthesize an AWS CDK tree into an AWS CloudFormation template, the AWS CloudFormation logical ID for each resource in the template is allocated according to the path of that resource in the construct tree\. For more information, see [Logical IDs](logical_ids.md)\.
+When you synthesize an AWS CDK app into an AWS CloudFormation template, the AWS CloudFormation logical ID for each resource in the template is allocated according to the path of that resource in the scope hierarchy\. For more information, see [Logical IDs](logical_ids.md)\.
 
 ## Construct Properties<a name="constructs_properties"></a>
 
 Customize constructs by passing a property object as the third parameter \(*props*\)\. Every construct has its own set of parameters, defined as an interface\. You can pass a property object to your construct in two ways:
 
 ```
 // Inline (recommended)
-new Queue(this, 'MyQueue', {
+new sqs.Queue(this, 'MyQueue', {
   visibilityTimeout: 300
 });
-
-// Instantiate separate property object
-const props: QueueProps = {
-  visibilityTimeout: 300
-};
-
-new Queue(this, 'MyQueue', props);
 ```
 
 ## Construct Metadata<a name="constructs_metadata"></a>
 
-You can attach metadata to a construct using the `aws-cdk.Construct.addMetadata` operation\. Metadata entries automatically include the stack trace from which the metadata entry was added\. Therefore, at any level of a construct you can find the code location, even if metadata was created by a lower\-level library that you don't own\.
+You can attach metadata to a construct using the `aws-cdk.Construct.node.addMetadata` operation\. Metadata entries automatically include the stack trace from which the metadata entry was added to allow tracing back to your code, even if the entry was was defined by a lower\-level library that you don't own\.

doc_source/context.md

@@ -14,7 +14,7 @@ The AWS CDK currently supports the following context providers\.
 Use this provider to get the list of all supported availability zones in this environment\. For example, the following code iterates over all of the AZs in the current environment\.  
 
 ```
-// "this" refers to a parent Construct
+// "this" refers to a Construct scope
 const zones: string[] = new AvailabilityZoneProvider(this).availabilityZones;
 
 for (let zone of zones) {

doc_source/logical_ids.md

@@ -6,12 +6,12 @@
 
 # Logical IDs<a name="logical_ids"></a>
 
-When you synthesize a stack into an AWS CloudFormation template, the AWS CDK assigns a [ logical ID](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html), which must be unique within the template, to each resource in the stack\.
+When you synthesize a stack into an AWS CloudFormation template, the AWS CDK assigns a [logical ID](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html), which must be unique within the template, to each resource in the stack\.
 
 **Important**  
 When you update the template, AWS CloudFormation uses these logical IDs to plan the update and apply changes\. Therefore, logical IDs must remain "stable" across updates\. If you make a modification in your code that results in a change to a logical ID of a resource, AWS CloudFormation deletes the resource and creates a new resource when it updates the stack\.
 
-Each resource in the construct tree has a unique path that represents its location within the tree\. Since logical IDs can only use alphanumeric characters and cannot exceed 255 characters, the CDK is unable to simply use a delimited path as the logical ID\. Instead, logical IDs are allocated by concatenating a human\-friendly rendition from the path \(concatenation, de\-duplicate, trim\) with an eight\-character MD5 hash of the delimited path\. This final component is necessary since AWS CloudFormation logical IDs cannot include the delimiting slash character \(/\), so simply concatenating the component values does not work\. For example, concatenating the components of the path */a/b/c* produces **abc**, which is the same as concatenating the components of the path */ab/c*\.
+Each resource in your CDK app has a unique path that represents its location within the scope hierarchy\. Since logical IDs can only use alphanumeric characters and cannot exceed 255 characters, the CDK is unable to simply use a delimited path as the logical ID\. Instead, logical IDs are allocated by concatenating a human\-friendly rendition from the path \(concatenation, de\-duplicate, trim\) with an eight\-character MD5 hash of the delimited path\. This final component is necessary since AWS CloudFormation logical IDs cannot include the delimiting slash character \(/\), so simply concatenating the component values does not work\. For example, concatenating the components of the path */a/b/c* produces **abc**, which is the same as concatenating the components of the path */ab/c*\.
 
 ```
 VPCPrivateSubnet2RouteTable0A19E10E
@@ -29,7 +29,7 @@ Logical IDs are unique within the stack
 This is ensured by the MD5 component, which is based on the absolute path to the resource, which is unique within a stack\.
 
 Logical IDs remain unchanged across updates  
-This is true as long as their location within the construct tree doesn't change\.
+This is true as long as their location within the scope hierarchy doesn't change\.
 
 The AWS CDK applies some heuristics to improve the human\-friendliness of the prefix:
 + If a path component is **Default**, it is hidden completely from the logical ID computation\. You will generally want to use this if you create a new construct that wraps an existing one\. By naming the inner construct **Default**, you ensure that the logical identifiers of resources in already\-deployed copy of that construct do not change\.
@@ -43,8 +43,8 @@ The `aws-cdk.Stack.renameLogical` method can be used to explicitly assign logica
 
 ```
 class MyStack extends Stack {
-  constructor(parent: App, name: string, props: StackProps) {
-    super(parent, name);
+  constructor(scope: App, id: string, props: StackProps) {
+    super(scope, id);
 
     // note that renameLogical must be called /before/ defining the construct.
     // a good practice would be to always put these at the top of your stack initializer.

doc_source/passing_in_data.md

@@ -127,8 +127,8 @@ class HelloCdkStack extends cdk.Stack {
   // Property that defines the stack you are exporting from
   public readonly myBucketRefProps: s3.BucketRefProps;
 
-  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 mybucket = new s3.Bucket(this, "MyFirstBucket");
 
@@ -152,8 +152,8 @@ Create the second stack that gets a reference to the other bucket from the prope
 ```
 // The class for the other stack
 class MyCdkStack extends cdk.Stack {
-  constructor(parent: cdk.App, name: string, props: MyCdkStackProps) {
-    super(parent, name);
+  constructor(scope: cdk.App, id: string, props: MyCdkStackProps) {
+    super(scope, name);
 
     const myOtherBucket = s3.Bucket.import(this, "MyOtherBucket", props.theBucketRefProps);