# aws-cfn-custom-resource

> Library to help write AWS CloudFormation custom resources.

Latest version **2.0.1** (published 2015-12-16) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install aws-cfn-custom-resource
pnpm add aws-cfn-custom-resource
yarn add aws-cfn-custom-resource
bun add aws-cfn-custom-resource
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2015-12-16 |
| First published | 2015-09-21 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 0.8.0 |
| Dependencies | 5 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Bazaarvoice |
| Maintainers | bazaarvoice, dump247 |
| Keywords | aws, amazon, cloudformation |

## Links

- npm: https://www.npmjs.com/package/aws-cfn-custom-resource
- Repository: https://github.com/bazaarvoice/aws-cfn-custom-resource
- Issues: https://github.com/bazaarvoice/aws-cfn-custom-resource/issues
- npm.io page: https://npm.io/package/aws-cfn-custom-resource

## Dependencies (5)

- [q](https://npm.io/package/q.md) ^1.4.1
- [bunyan](https://npm.io/package/bunyan.md) ^1.5.1
- [lodash](https://npm.io/package/lodash.md) ^3.10.1
- [aws-sdk](https://npm.io/package/aws-sdk.md) ^2.1.50
- [randomstring](https://npm.io/package/randomstring.md) ^1.1.0

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 2.0.1 (latest) — 2015-12-16
- 2.0.0 — 2015-10-06
- 1.0.1 — 2015-09-21
- 1.0.0 — 2015-09-21

## README

# CloudFormation Custom Resource

A node.js library to help write CloudFormation custom resources.

# Usage

## Install

Install the module: `npm install aws-cfn-custom-resource --save`

Import the module: `var resource = require('aws-cfn-custom-resource');`

## Handler

Create a module for the main custom resource handler. This handler maps custom
resource type names to modules that process the events for that resource. This
is the handler that is provided to the lambda function that executes the custom
resource.

### Example

`resource.js`

```javascript
var resource = require('aws-cfn-custom-resource');

exports.handler = resource.handler({
  'Custom::MyCustomResource': function () { return require('./lib/my-custom-resource'); }
});
```

## Resource Module

Implement request handlers for a custom resource type.

The resource module must export three functions:

* handleDelete
* handleCreate
* handleUpdate

### Input

The single parameter to a handler is a `CloudFormationEvent`.

The event includes all the properties from a [custom resource request](http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/crpg-ref-requests.html),
plus some additional information detailed below.

<dl>
    <dt>stack.region</dt>
    <dd>
    <p>AWS region the stack that created the resource is located in.</p>
    </dd>

    <dt>stack.accountId</dt>
    <dd>
    <p>ID of the AWS account the stack that created the resource is located in.</p>
    </dd>

    <dt>stack.name</dt>
    <dd>
    <p>Name of the CloudFormation stack that the resource is a part of.</p>
    </dd>

    <dt>stack.arn</dt>
    <dd>
    <p>Full ARN of the CloudFormation stack that the resource is a part of. Alias for <em>StackId</em>.</p>
    </dd>
</dl>

### Output

A handler should return one of the following:

* undefined/null to indicate success
* an object with keys:
  * `physicalResourceId` - _optional_ - Identifier unique to the custom resource
    vendor. If not provided, a resource id is generated.
  * `data` - _optional_ - Custom resource provider-defined name-value pairs to send
    with the response. The values provided here can be accessed by name in
    the template with <a href="http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html">Fn::GetAtt</a>.
* a promise that results in one of the above values

A handler may also throw an error to indicate failure.

### AWS API

This library provides a helper for the AWS JavaScript SDK that converts SDK
functions from callback to promises.
The helper can make it easier to stub/mock AWS APIs in unit tests.

```javascript
var resource = require('aws-cfn-custom-resource');

exports.handleCreate = function (event) {
  var session = new resource.aws.Session();
  var ec2 = session.client('EC2');

  return ec2.describeInstances({InstanceIds: ['i-234232']})
  .then(function (result) {
    // do something magical
  });
};
```

### Example

`lib/my-custom-resource.js`

```javascript
exports.handleDelete = function (event) {
  // Return nothing and the custom resource responds with success.
  // Can also:
  //   throw new Error("some message");
  //   -- or
  //   var resource = require('aws-cfn-custom-resource');
  //   throw resource.newError("MyException", "some message");
  //   -- or
  //   return {physicalResourceId: "myResource"};

  // You can also do the following:
  //   throw "some message";
  // However, you will not get a stack trace in this case. It is recommended
  // to throw Error instead.
};

exports.handleUpdate = function (event) {
  // Async handlers should respond with a promise.
  var Q = require('q');
  var deferred = Q.defer();

  doSomethingAsync(function (err, result) {
    if (err) {
      deferred.reject(err);
    } else {
      deferred.resolve({
        physicalResourceId: 'SomeResourceId',
        data: {
          key1: "Value",
          key2: "Value2"
        }
      });
    }
  });

  return deferred.promise();
};

// Sometimes it makes sense to use the same implementation for create & update.
exports.handleCreate = exports.handleUpdate;
```

---
_Source: https://npm.io/package/aws-cfn-custom-resource · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._