Skip to content

Latest commit

 

History

History
543 lines (299 loc) · 13.9 KB

API.md

File metadata and controls

543 lines (299 loc) · 13.9 KB

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

Returns:

static implement(instance, trait)🔹

Turn any object into an IDependable.

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

static of(instance)🔹

Return the matching Dependable for the given class instance.

static of(instance: IDependable): Dependable

Returns:

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[])

Methods

add(...scopes)🔹

Add a construct to the dependency roots.

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

class Node

Represents the construct node in the scope tree.

Initializer

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

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

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

findAll(order?)

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

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

Returns:

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:

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:

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

Returns:

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