API.md

API Reference

Classes

Name	Description
Construct	Represents the building block of the construct graph.
Dependable	Trait for IDependable.
DependencyGroup	A set of constructs to be used as a dependable.
Node	Represents the construct node in the scope tree.

Structs

Name	Description
MetadataEntry	An entry in the construct metadata table.
MetadataOptions	Options for construct.addMetadata().

Interfaces

Name	Description
IConstruct	Represents a construct.
IDependable	Trait marker for classes that can be depended upon.
IValidation	Implement this interface in order for the construct to be able to validate itself.

Enums

Name	Description
ConstructOrder	In what order to return constructs.

class Construct

Represents the building block of the construct graph.

All constructs besides the root construct must be created within the scope of another construct.

Implements: IConstruct, IDependable

Initializer

Creates a new construct node.

new Construct(scope: Construct, id: string)

• scope (Construct) The scope in which to define this construct.
• id (string) The scoped construct ID.

Properties

Name	Type	Description
node	Node	The tree node.

Methods

toString()

Returns a string representation of this construct.

toString(): string

Returns:

• string

static isConstruct(x)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

static isConstruct(x: any): boolean

• x (any) Any object.

Returns:

• boolean

class Dependable 🔹

Trait for IDependable.

Traits are interfaces that are privately implemented by objects. Instead of showing up in the public interface of a class, they need to be queried explicitly. This is used to implement certain framework features that are not intended to be used by Construct consumers, and so should be hidden from accidental use.

Initializer

new Dependable()

Properties

Name	Type	Description
dependencyRoots🔹	Array<IConstruct>	The set of constructs that form the root of this dependable.

Methods

static get(instance)⚠️

Return the matching Dependable for the given class instance.

static get(instance: IDependable): Dependable

• instance (IDependable) No description

Returns:

• Dependable

static implement(instance, trait)🔹

Turn any object into an IDependable.

static implement(instance: IDependable, trait: Dependable): void

• instance (IDependable) No description
• trait (Dependable) No description

static of(instance)🔹

Return the matching Dependable for the given class instance.

static of(instance: IDependable): Dependable

• instance (IDependable) No description

Returns:

• Dependable

class DependencyGroup 🔹

A set of constructs to be used as a dependable.

This class can be used when a set of constructs which are disjoint in the construct tree needs to be combined to be used as a single dependable.

Implements: IDependable

Initializer

new DependencyGroup(...deps: IDependable[])

• deps (IDependable) No description

Methods

add(...scopes)🔹

Add a construct to the dependency roots.

add(...scopes: IDependable[]): void

• scopes (IDependable) No description

class Node

Represents the construct node in the scope tree.

Initializer

new Node(host: Construct, scope: IConstruct, id: string)

• host (Construct) No description
• scope (IConstruct) No description
• id (string) No description

Properties

Name	Type	Description
addr	string	Returns an opaque tree-unique address for this construct.
children	Array<IConstruct>	All direct children of this construct.
dependencies	Array<IConstruct>	Return all dependencies registered on this node (non-recursive).
id	string	The id of this construct within the current scope.
locked	boolean	Returns true if this construct or the scopes in which it is defined are locked.
metadata	Array<MetadataEntry>	An immutable array of metadata objects associated with this construct.
path	string	The full, absolute path of this construct in the tree.
root	IConstruct	Returns the root of the construct tree.
scopes	Array<IConstruct>	All parent scopes of this construct.
defaultChild?	IConstruct	Returns the child construct that has the id Default or Resource". Optional
scope?	IConstruct	Returns the scope in which this construct is defined. Optional
static PATH_SEP	string	Separator used to delimit construct path components.

Methods

addDependency(...deps)

Add an ordering dependency on another construct.

An IDependable

addDependency(...deps: IDependable[]): void

• deps (IDependable) No description

addMetadata(type, data, options?)

Adds a metadata entry to this construct.

Entries are arbitrary values and will also include a stack trace to allow tracing back to the code location for when the entry was added. It can be used, for example, to include source mapping in CloudFormation templates to improve diagnostics.

addMetadata(type: string, data: any, options?: MetadataOptions): void

• type (string) a string denoting the type of metadata.
• data (any) the value of the metadata (can be a Token).
• options (MetadataOptions) options.
  • stackTrace (boolean) Include stack trace with metadata entry. Default: false
  • traceFromFunction (any) A JavaScript function to begin tracing from. Default: addMetadata()

addValidation(validation)

Adds a validation to this construct.

When node.validate() is called, the validate() method will be called on all validations and all errors will be returned.

addValidation(validation: IValidation): void

• validation (IValidation) The validation object.

findAll(order?)

Return this construct and all of its children in the given order.

findAll(order?: ConstructOrder): Array<IConstruct>

• order (ConstructOrder) No description

Returns:

• Array<IConstruct>

findChild(id)

Return a direct child by id.

Throws an error if the child is not found.

findChild(id: string): IConstruct

• id (string) Identifier of direct child.

Returns:

• IConstruct

getAllContext(defaults?)

Retrieves the all context of a node from tree context.

Context is usually initialized at the root, but can be overridden at any point in the tree.

getAllContext(defaults?: json): any

• defaults (json) Any keys to override the retrieved context.

Returns:

• any

getContext(key)

Retrieves a value from tree context if present. Otherwise, would throw an error.

Context is usually initialized at the root, but can be overridden at any point in the tree.

getContext(key: string): any

• key (string) The context key.

Returns:

• any

lock()

Locks this construct from allowing more children to be added.

After this call, no more children can be added to this construct or to any children.

lock(): void

setContext(key, value)

This can be used to set contextual values.

Context must be set before any children are added, since children may consult context info during construction. If the key already exists, it will be overridden.

setContext(key: string, value: any): void

• key (string) The context key.
• value (any) The context value.

tryFindChild(id)

Return a direct child by id, or undefined.

tryFindChild(id: string): IConstruct

• id (string) Identifier of direct child.

Returns:

• IConstruct

tryGetContext(key)

Retrieves a value from tree context.

Context is usually initialized at the root, but can be overridden at any point in the tree.

tryGetContext(key: string): any

• key (string) The context key.

Returns:

• any

tryRemoveChild(childName)🔹

Remove the child with the given name, if present.

tryRemoveChild(childName: string): boolean

• childName (string) No description

Returns:

• boolean

validate()

Validates this construct.

Invokes the validate() method on all validations added through addValidation().

validate(): Array<string>

Returns:

• Array

static of(construct)⚠️

Returns the node associated with a construct.

static of(construct: IConstruct): Node

• construct (IConstruct) the construct.

Returns:

• Node

interface IConstruct

Implemented by: Construct Obtainable from: Node.findChild(), Node.tryFindChild()

Represents a construct.

Properties

Name	Type	Description
node	Node	The tree node.

interface IDependable

Implemented by: Construct, DependencyGroup

Trait marker for classes that can be depended upon.

The presence of this interface indicates that an object has an IDependable implementation.

This interface can be used to take an (ordering) dependency on a set of constructs. An ordering dependency implies that the resources represented by those constructs are deployed before the resources depending ON them are deployed.

interface IValidation

Implement this interface in order for the construct to be able to validate itself.

Methods

validate()

Validate the current construct.

This method can be implemented by derived constructs in order to perform validation logic. It is called on all constructs before synthesis.

validate(): Array<string>

Returns:

• Array

struct MetadataEntry

An entry in the construct metadata table.

Name	Type	Description
data	any	The data.
type	string	The metadata entry type.
trace?	Array	Stack trace at the point of adding the metadata. Default: no trace information

struct MetadataOptions

Options for construct.addMetadata().

Name	Type	Description
stackTrace?	boolean	Include stack trace with metadata entry. Default: false
traceFromFunction?	any	A JavaScript function to begin tracing from. Default: addMetadata()

enum ConstructOrder

In what order to return constructs.

Name	Description
PREORDER	Depth-first, pre-order.
POSTORDER	Depth-first, post-order (leaf nodes first).