• Version 10.3.0
  • Published
  • 160 kB
  • No dependencies
  • Apache-2.0 license


npm i constructs
yarn add constructs
pnpm add constructs


A programming model for software-defined state



class Construct

class Construct implements IConstruct {}
  • Represents the building block of the construct graph.

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


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


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

method toString

toString: () => string;
  • Returns a string representation of this construct.

class Dependable

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

    Example 1

    // Usage const roots = Dependable.of(construct).dependencyRoots;

    // Definition Dependable.implement(construct, { dependencyRoots: [construct], });


    • @experimental

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.


    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.

class DependencyGroup

class DependencyGroup implements IDependable {}
  • 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.


    • @experimental


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

    method add

    add: (...scopes: IDependable[]) => void;
    • Add a construct to the dependency roots

    class Node

    class Node {}
    • Represents the construct node in the scope tree.


    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 refactorings 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 addreess.

        Example 1


      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.


        a construct or undefined if there is no default child


        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.


        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.


        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.

        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


      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


        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


        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


        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


        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


        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


        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.


        Whether a child with the given name was deleted.


        • @experimental

      method validate

      validate: () => string[];
      • Validates this construct.

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


        an array of validation error messages associated with this construct.


      interface IConstruct

      interface IConstruct extends IDependable {}
      • Represents a construct.

      property node

      readonly node: Node;
      • The tree node.

      interface IDependable

      interface IDependable {}
      • 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

      interface IValidation {}
      • Implement this interface in order for the construct to be able to validate itself.

      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.


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

      interface MetadataEntry

      interface MetadataEntry {}
      • An entry in the construct metadata table.

      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.

      interface MetadataOptions

      interface MetadataOptions {}
      • Options for construct.addMetadata().

      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.



      enum ConstructOrder

      enum ConstructOrder {
      PREORDER = 0,
      POSTORDER = 1,
      • In what order to return constructs

      member POSTORDER

      POSTORDER = 1
      • Depth-first, post-order (leaf nodes first)

      member PREORDER

      PREORDER = 0
      • Depth-first, pre-order

      Package Files (4)

      Dependencies (0)

      No dependencies.

      Dev Dependencies (22)

      Peer Dependencies (0)

      No peer dependencies.


      To add a badge like this badgeto your package's README, use the codes available below.

      You may also use to create a custom badge linking to

      • Markdown
      • HTML
        <a href=""><img src="" alt=""></a>