BREAKING: remove '@aws-cdk/aws-custom-resources' (#513)

Since this package does not correspond to an AWS service,
it should not be named with an 'aws-' prefix.

Fixes #483.

packages/@aws-cdk/aws-cloudformation/README.md

@@ -1,2 +1,68 @@
 ## CDK Constructs for AWS CloudFormation
-This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.
+This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.
+
+### Custom Resources
+
+Custom Resources are CloudFormation resources that are implemented by
+arbitrary user code. They can do arbitrary lookups or modifications
+during a CloudFormation synthesis run.
+
+You will typically use Lambda to implement a Construct implemented as a
+Custom Resource (though SNS topics can be used as well). Your Lambda function
+will be sent a `CREATE`, `UPDATE` or `DELETE` message, depending on the
+CloudFormation life cycle, and can return any number of output values which
+will be available as attributes of your Construct. In turn, those can
+be used as input to other Constructs in your model.
+
+In general, consumers of your Construct will not need to care whether
+it is implemented in term of other CloudFormation resources or as a
+custom resource.
+
+Note: when implementing your Custom Resource using a Lambda, use
+a `SingletonLambda` so that even if your custom resource is instantiated
+multiple times, the Lambda will only get uploaded once.
+
+#### Example
+
+Sample of a Custom Resource that copies files into an S3 bucket during deployment
+(implementation of actual `copy.py` operation elided).
+
+```ts
+interface CopyOperationProps {
+    sourceBucket: IBucket;
+    targetBucket: IBucket;
+}
+
+class CopyOperation extends Construct {
+    constructor(parent: Construct, name: string, props: DemoResourceProps) {
+        super(parent, name);
+
+        const lambdaProvider = new SingletonLambda(this, 'Provider', {
+            uuid: 'f7d4f730-4ee1-11e8-9c2d-fa7ae01bbebc',
+            code: new LambdaInlineCode(resources['copy.py']),
+            handler: 'index.handler',
+            timeout: 60,
+            runtime: LambdaRuntime.Python3,
+        });
+
+        new CustomResource(this, 'Resource', {
+            lambdaProvider,
+            properties: {
+                sourceBucketArn: props.sourceBucket.bucketArn,
+                targetBucketArn: props.targetBucket.bucketArn,
+            }
+        });
+    }
+}
+```
+
+More examples are in the `example` directory, including an example of how to use
+the `cfnresponse` module that is provided for you by CloudFormation.
+
+#### References
+
+See the following section of the docs on details to write Custom Resources:
+
+* [Introduction](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html)
+* [Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref.html)
+* [Code Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-code.html)

packages/@aws-cdk/aws-custom-resources/lib/resource.ts → packages/@aws-cdk/aws-cloudformation/lib/custom-resource.ts

@@ -1,7 +1,7 @@
-import { cloudformation } from '@aws-cdk/aws-cloudformation';
 import lambda = require('@aws-cdk/aws-lambda');
 import sns = require('@aws-cdk/aws-sns');
 import cdk = require('@aws-cdk/cdk');
+import { cloudformation } from './cloudformation.generated';
 
 /**
  * Collection of arbitrary properties

packages/@aws-cdk/aws-cloudformation/lib/index.ts

@@ -1,2 +1,3 @@
 // AWS::CloudFormation CloudFormation Resources:
 export * from './cloudformation.generated';
+export * from './custom-resource';

packages/@aws-cdk/aws-cloudformation/package.json

@@ -48,11 +48,14 @@
   "devDependencies": {
     "@aws-cdk/assert": "^0.8.1",
     "cdk-build-tools": "^0.8.1",
+    "cdk-integ-tools": "^0.8.1",
     "cfn2ts": "^0.8.1",
     "pkglint": "^0.8.1"
   },
   "dependencies": {
-    "@aws-cdk/cdk": "^0.8.1"
+    "@aws-cdk/cdk": "^0.8.1",
+    "@aws-cdk/aws-lambda": "^0.8.1",
+    "@aws-cdk/aws-sns": "^0.8.1"
   },
   "homepage": "https://github.com/awslabs/aws-cdk"
 }

packages/@aws-cdk/aws-custom-resources/test/integ.trivial-lambda-resource.ts → packages/@aws-cdk/aws-cloudformation/test/integ.trivial-lambda-resource.ts

@@ -1,7 +1,7 @@
 import lambda = require('@aws-cdk/aws-lambda');
 import cdk = require('@aws-cdk/cdk');
 import fs = require('fs');
-import customResource = require('../lib');
+import cloudformation = require('../lib');
 
 interface DemoResourceProps {
     /**
@@ -21,8 +21,8 @@ class DemoResource extends cdk.Construct {
     constructor(parent: cdk.Construct, name: string, props: DemoResourceProps) {
         super(parent, name);
 
-        const resource = new customResource.CustomResource(this, 'Resource', {
-            lambdaProvider: new customResource.SingletonLambda(this, 'Singleton', {
+        const resource = new cloudformation.CustomResource(this, 'Resource', {
+            lambdaProvider: new lambda.SingletonLambda(this, 'Singleton', {
                 uuid: 'f7d4f730-4ee1-11e8-9c2d-fa7ae01bbebc',
                 // This makes the demo only work as top-level TypeScript program, but that's fine for now
                 code: new lambda.LambdaInlineCode(fs.readFileSync('integ.trivial-lambda-provider.py', { encoding: 'utf-8' })),

packages/@aws-cdk/aws-custom-resources/test/test.resource.ts → packages/@aws-cdk/aws-cloudformation/test/test.resource.ts

@@ -2,7 +2,7 @@ import { expect } from '@aws-cdk/assert';
 import lambda = require('@aws-cdk/aws-lambda');
 import cdk = require('@aws-cdk/cdk');
 import { Test } from 'nodeunit';
-import { CustomResource, SingletonLambda } from '../lib';
+import { CustomResource } from '../lib';
 
 // tslint:disable:object-literal-key-quotes
 
@@ -92,7 +92,7 @@ class TestCustomResource extends cdk.Construct {
   constructor(parent: cdk.Construct, name: string) {
     super(parent, name);
 
-    const singletonLambda = new SingletonLambda(this, 'Lambda', {
+    const singletonLambda = new lambda.SingletonLambda(this, 'Lambda', {
       uuid: 'TestCustomResourceProvider',
       code: new lambda.LambdaInlineCode('def hello(): pass'),
       runtime: lambda.LambdaRuntime.Python27,