constructs

README

Constructs

Software-defined persistent state

What are constructs?

Constructs are classes which define a "piece of system state". Constructs can be composed together to form higher-level building blocks which represent more complex state.

Constructs are often used to represent the desired state of cloud applications. For example, in the AWS CDK, which is used to define the desired state for AWS infrastructure using CloudFormation, the lowest-level construct represents a resource definition in a CloudFormation template. These resources are composed to represent higher-level logical units of a cloud application, etc.

Support policy

All maintained Node.js versions are supported by this package.

Contributing

This project has adopted the Amazon Open Source Code of Conduct.

We welcome community contributions and pull requests. See our contribution guide for more information on how to report issues, set up a development environment and submit code.

License

This project is distributed under the Apache License, Version 2.0.

Documentation

Overview

A programming model for software-defined state

Index

• func Construct_IsConstruct(x interface{}) *bool
• func Dependable_Implement(instance IDependable, trait Dependable)
• func NewConstruct_Override(c Construct, scope Construct, id *string)
• func NewDependable_Override(d Dependable)
• func NewDependencyGroup_Override(d DependencyGroup, deps ...IDependable)
• func NewNode_Override(n Node, host Construct, scope IConstruct, id *string)
• func NewRootConstruct_Override(r RootConstruct, id *string)
• func Node_PATH_SEP() *string
• func RootConstruct_IsConstruct(x interface{}) *bool
• type Construct
  • func NewConstruct(scope Construct, id *string) Construct
• type ConstructOrder
• type Dependable
  • func Dependable_Get(instance IDependable) Dependable
  • func Dependable_Of(instance IDependable) Dependable
• type DependencyGroup
  • func NewDependencyGroup(deps ...IDependable) DependencyGroup
• type IConstruct
• type IDependable
• type IValidation
• type MetadataEntry
• type MetadataOptions
• type Node
  • func NewNode(host Construct, scope IConstruct, id *string) Node
  • func Node_Of(construct IConstruct) Node
• type RootConstruct
  • func NewRootConstruct(id *string) RootConstruct

Functions

func Construct_IsConstruct

func Construct_IsConstruct(x interface{}) *bool

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.

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

func Dependable_Implement

func Dependable_Implement(instance IDependable, trait Dependable)

Turn any object into an IDependable.

func NewConstruct_Override

func NewConstruct_Override(c Construct, scope Construct, id *string)

Creates a new construct node.

func NewDependable_Override

func NewDependable_Override(d Dependable)

func NewDependencyGroup_Override

func NewDependencyGroup_Override(d DependencyGroup, deps ...IDependable)

func NewNode_Override

func NewNode_Override(n Node, host Construct, scope IConstruct, id *string)

func NewRootConstruct_Override

func NewRootConstruct_Override(r RootConstruct, id *string)

Creates a new root construct node.

func Node_PATH_SEP

func Node_PATH_SEP() *string

func RootConstruct_IsConstruct

func RootConstruct_IsConstruct(x interface{}) *bool

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.

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

Types

type Construct

type Construct interface {
	IConstruct
	// The tree node.
	Node() Node
	// Returns a string representation of this construct.
	ToString() *string
}

Represents the building block of the construct graph.

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

func NewConstruct

func NewConstruct(scope Construct, id *string) Construct

Creates a new construct node.

type ConstructOrder

type ConstructOrder string

In what order to return constructs.

const (
	// Depth-first, pre-order.
	ConstructOrder_PREORDER ConstructOrder = "PREORDER"
	// Depth-first, post-order (leaf nodes first).
	ConstructOrder_POSTORDER ConstructOrder = "POSTORDER"
)

type Dependable

type Dependable interface {
	// The set of constructs that form the root of this dependable.
	//
	// All resources under all returned constructs are included in the ordering
	// dependency.
	DependencyRoots() *[]IConstruct
}

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:

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

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

func Dependable_Get

func Dependable_Get(instance IDependable) Dependable

Return the matching Dependable for the given class instance. Deprecated: use `of`.

func Dependable_Of

func Dependable_Of(instance IDependable) Dependable

Return the matching Dependable for the given class instance.

type DependencyGroup

type DependencyGroup interface {
	IDependable
	// Add a construct to the dependency roots.
	Add(scopes ...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.

func NewDependencyGroup

func NewDependencyGroup(deps ...IDependable) DependencyGroup

type IConstruct

type IConstruct interface {
	IDependable
	// The tree node.
	Node() Node
}

Represents a construct.

type IDependable

type IDependable interface {
}

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.

type IValidation

type IValidation interface {
	// 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.
	Validate() *[]*string
}

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

type MetadataEntry

type MetadataEntry struct {
	// The data.
	Data interface{} `field:"required" json:"data" yaml:"data"`
	// The metadata entry type.
	Type *string `field:"required" json:"type" yaml:"type"`
	// Stack trace at the point of adding the metadata.
	//
	// Only available if `addMetadata()` is called with `stackTrace: true`.
	// Default: - no trace information.
	//
	Trace *[]*string `field:"optional" json:"trace" yaml:"trace"`
}

An entry in the construct metadata table.

type MetadataOptions

type MetadataOptions struct {
	// Include stack trace with metadata entry.
	// Default: false.
	//
	StackTrace *bool `field:"optional" json:"stackTrace" yaml:"stackTrace"`
	// A JavaScript function to begin tracing from.
	//
	// This option is ignored unless `stackTrace` is `true`.
	// Default: addMetadata().
	//
	TraceFromFunction interface{} `field:"optional" json:"traceFromFunction" yaml:"traceFromFunction"`
}

Options for `construct.addMetadata()`.

type Node

type Node interface {
	// 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:
	//   c83a2846e506bcc5f10682b564084bca2d275709ee
	//
	Addr() *string
	// All direct children of this construct.
	Children() *[]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.
	// Override the defaultChild property.
	//
	// This should only be used in the cases where the correct
	// default child is not named 'Resource' or 'Default' as it
	// should be.
	//
	// If you set this to undefined, the default behavior of finding
	// the child named 'Resource' or 'Default' will be used.
	//
	// Returns: a construct or undefined if there is no default child.
	DefaultChild() IConstruct
	SetDefaultChild(val IConstruct)
	// Return all dependencies registered on this node (non-recursive).
	Dependencies() *[]IConstruct
	// 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`.
	Id() *string
	// Returns true if this construct or the scopes in which it is defined are locked.
	Locked() *bool
	// 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.
	Metadata() *[]*MetadataEntry
	// The full, absolute path of this construct in the tree.
	//
	// Components are separated by '/'.
	Path() *string
	// Returns the root of the construct tree.
	//
	// Returns: The root of the construct tree.
	Root() IConstruct
	// Returns the scope in which this construct is defined.
	//
	// The value is `undefined` at the root of the construct scope tree.
	Scope() 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.
	Scopes() *[]IConstruct
	// Add an ordering dependency on another construct.
	//
	// An `IDependable`.
	AddDependency(deps ...IDependable)
	// 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.
	AddMetadata(type_ *string, data interface{}, options *MetadataOptions)
	// 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)
	// Return this construct and all of its children in the given order.
	FindAll(order ConstructOrder) *[]IConstruct
	// Return a direct child by id.
	//
	// Throws an error if the child is not found.
	//
	// Returns: Child with the given id.
	FindChild(id *string) IConstruct
	// 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.
	//
	// Returns: The context object or an empty object if there is discovered context.
	GetAllContext(defaults *map[string]interface{}) interface{}
	// 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.
	//
	// Returns: The context value or throws error if there is no context value for this key.
	GetContext(key *string) interface{}
	// 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()
	// 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 interface{})
	// Return a direct child by id, or undefined.
	//
	// Returns: the child if found, or undefined.
	TryFindChild(id *string) IConstruct
	// Retrieves a value from tree context.
	//
	// Context is usually initialized at the root, but can be overridden at any point in the tree.
	//
	// Returns: The context value or `undefined` if there is no context value for this key.
	TryGetContext(key *string) interface{}
	// Remove the child with the given name, if present.
	//
	// Returns: Whether a child with the given name was deleted.
	TryRemoveChild(childName *string) *bool
	// Validates this construct.
	//
	// Invokes the `validate()` method on all validations added through
	// `addValidation()`.
	//
	// Returns: an array of validation error messages associated with this
	// construct.
	Validate() *[]*string
}

Represents the construct node in the scope tree.

func NewNode

func NewNode(host Construct, scope IConstruct, id *string) Node

func Node_Of

func Node_Of(construct IConstruct) Node

Returns the node associated with a construct. Deprecated: use `construct.node` instead

type RootConstruct

type RootConstruct interface {
	Construct
	// The tree node.
	Node() Node
	// Returns a string representation of this construct.
	ToString() *string
}

Creates a new root construct node.

The root construct represents the top of the construct tree and is not contained within a parent scope itself. For root constructs, the id is optional.

func NewRootConstruct

func NewRootConstruct(id *string) RootConstruct

Creates a new root construct node.