constructs

constructor

constructor(scope: Construct, id: string);

• Creates a new construct node.

  Parameter scope

  The scope in which to define this construct

  Parameter id

  The scoped construct ID. Must be unique amongst siblings. If the ID includes a path separator (/), then it will be replaced by double dash --.

property node

readonly node: Node;

• The tree node.

method isConstruct

static isConstruct: (x: any) => x is Construct;

• 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.

  Parameter x

  Any object

  Returns

  true if x is an object created from a class which extends Construct.

method toString

toString: () => string;

• Returns a string representation of this construct.

property dependencyRoots

abstract readonly dependencyRoots: IConstruct[];

• The set of constructs that form the root of this dependable

  All resources under all returned constructs are included in the ordering dependency.

method get

static get: (instance: IDependable) => Dependable;

• Return the matching Dependable for the given class instance.

  Deprecated

  use of

method implement

static implement: (instance: IDependable, trait: Dependable) => void;

• Turn any object into an IDependable.

method of

static of: (instance: IDependable) => Dependable;

• Return the matching Dependable for the given class instance.

constructor

constructor(...deps: IDependable[]);

method add

add: (...scopes: IDependable[]) => void;

• Add a construct to the dependency roots

constructor

constructor(host: Construct, scope: IConstruct, id: string);

property addr

readonly addr: string;

• Returns an opaque tree-unique address for this construct.

  Addresses are 42 characters hexadecimal strings. They begin with "c8" followed by 40 lowercase hexadecimal characters (0-9a-f).

  Addresses are calculated using a SHA-1 of the components of the construct path.

  To enable refactoring of construct trees, constructs with the ID Default will be excluded from the calculation. In those cases constructs in the same tree may have the same address.

  Example 1

  c83a2846e506bcc5f10682b564084bca2d275709ee

property children

readonly children: IConstruct[];

• All direct children of this construct.

property defaultChild

defaultChild: IConstruct;

• Returns the child construct that has the id Default or Resource". This is usually the construct that provides the bulk of the underlying functionality. Useful for modifications of the underlying construct that are not available at the higher levels.

  Returns

  a construct or undefined if there is no default child

  Throws

  if there is more than one child

property dependencies

readonly dependencies: IConstruct[];

• Return all dependencies registered on this node (non-recursive).

property id

readonly id: string;

• The id of this construct within the current scope.

  This is a scope-unique id. To obtain an app-unique id for this construct, use addr.

property locked

readonly locked: boolean;

• Returns true if this construct or the scopes in which it is defined are locked.

property metadata

readonly metadata: MetadataEntry[];

• An immutable array of metadata objects associated with this construct. This can be used, for example, to implement support for deprecation notices, source mapping, etc.

property path

readonly path: string;

• The full, absolute path of this construct in the tree.

  Components are separated by '/'.

property PATH_SEP

static readonly PATH_SEP: string;

• Separator used to delimit construct path components.

property root

readonly root: IConstruct;

• Returns the root of the construct tree.

  Returns

  The root of the construct tree.

property scope

readonly scope?: IConstruct;

• Returns the scope in which this construct is defined.

  The value is undefined at the root of the construct scope tree.

property scopes

readonly scopes: IConstruct[];

• All parent scopes of this construct.

  Returns

  a list of parent scopes. The last element in the list will always be the current construct and the first element will be the root of the tree.

method addDependency

addDependency: (...deps: IDependable[]) => void;

• Add an ordering dependency on another construct.

  An IDependable

method addMetadata

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

• 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. Note that construct metadata is not the same as CloudFormation resource metadata and is never written to the CloudFormation template. The metadata entries are written to the Cloud Assembly Manifest if the treeMetadata property is specified in the props of the App that contains this Construct.

  Parameter type

  a string denoting the type of metadata

  Parameter data

  the value of the metadata (can be a Token). If null/undefined, metadata will not be added.

  Parameter options

  options

method addValidation

addValidation: (validation: IValidation) => void;

• 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.

  Parameter validation

  The validation object

method findAll

findAll: (order?: ConstructOrder) => IConstruct[];

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

method findChild

findChild: (id: string) => IConstruct;

• Return a direct child by id

  Throws an error if the child is not found.

  Parameter id

  Identifier of direct child

  Returns

  Child with the given id.

method getAllContext

getAllContext: (defaults?: object) => any;

• 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.

  Parameter defaults

  Any keys to override the retrieved context

  Returns

  The context object or an empty object if there is discovered context

method getContext

getContext: (key: string) => any;

• 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.

  Parameter key

  The context key

  Returns

  The context value or throws error if there is no context value for this key

method lock

lock: () => void;

• 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.

method of

static of: (construct: IConstruct) => Node;

• Returns the node associated with a construct.

  Parameter construct

  the construct

  Deprecated

  use construct.node instead

method setContext

setContext: (key: string, value: any) => void;

• 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.

  Parameter key

  The context key

  Parameter value

  The context value

method tryFindChild

tryFindChild: (id: string) => IConstruct | undefined;

• Return a direct child by id, or undefined

  Parameter id

  Identifier of direct child

  Returns

  the child if found, or undefined

method tryGetContext

tryGetContext: (key: string) => any;

• Retrieves a value from tree context.

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

  Parameter key

  The context key

  Returns

  The context value or undefined if there is no context value for this key.

method tryRemoveChild

tryRemoveChild: (childName: string) => boolean;

• Remove the child with the given name, if present.

  Returns

  Whether a child with the given name was deleted.

method validate

validate: () => string[];

• Validates this construct.

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

  Returns

  an array of validation error messages associated with this construct.

constructor

constructor(id?: string);

• Creates a new root construct node.

  Parameter id

  The scoped construct ID. Must be unique amongst siblings. If the ID includes a path separator (/), then it will be replaced by double dash --.

property node

readonly node: Node;

• The tree node.

method validate

validate: () => string[];

• 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.

  Returns

  An array of validation error messages, or an empty array if there the construct is valid.

property data

readonly data: any;

• The data.

property trace

readonly trace?: string[];

• Stack trace at the point of adding the metadata.

  Only available if addMetadata() is called with stackTrace: true.

  - no trace information

property type

readonly type: string;

• The metadata entry type.

property stackTrace

readonly stackTrace?: boolean;

• Include stack trace with metadata entry. false

property traceFromFunction

readonly traceFromFunction?: any;

• A JavaScript function to begin tracing from.

  This option is ignored unless stackTrace is true.

  addMetadata()

member POSTORDER

POSTORDER = 1

• Depth-first, post-order (leaf nodes first)

member PREORDER

PREORDER = 0

• Depth-first, pre-order