Skip to content

Latest commit

 

History

History
1159 lines (694 loc) · 41.8 KB

API.md

File metadata and controls

1159 lines (694 loc) · 41.8 KB
Raw

API Reference

Constructs

Construct

Represents the building block of the construct graph.

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

Initializers 

import { Construct } from 'constructs'

new Construct(scope: Construct, id: string)
Name Type Description
scope Construct The scope in which to define this construct.
id string The scoped construct ID.
scopeRequired

The scope in which to define this construct.

idRequired
  • Type: string

The scoped construct ID.

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

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { Construct } from 'constructs'

Construct.isConstruct(x: any)

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.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node Node The tree node.
nodeRequired 
public readonly node: Node;

The tree node.

RootConstruct

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.

Initializers 

import { RootConstruct } from 'constructs'

new RootConstruct(id?: string)
Name Type Description
id string The scoped construct ID.
idOptional
  • Type: string

The scoped construct ID.

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

Methods

Name Description
toString Returns a string representation of this construct.
toString 
public toString(): string

Returns a string representation of this construct.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isConstruct 
import { RootConstruct } from 'constructs'

RootConstruct.isConstruct(x: any)

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.

xRequired
  • Type: any

Any object.

Properties

Name Type Description
node Node The tree node.
nodeRequired 
public readonly node: Node;

The tree node.

Structs

MetadataEntry

An entry in the construct metadata table.

Initializer 

import { MetadataEntry } from 'constructs'

const metadataEntry: MetadataEntry = { ... }

Properties

Name Type Description
data any The data.
type string The metadata entry type.
trace string[] Stack trace at the point of adding the metadata.
dataRequired 
public readonly data: any;
  • Type: any

The data.

typeRequired 
public readonly type: string;
  • Type: string

The metadata entry type.

traceOptional 
public readonly trace: string[];
  • Type: string[]
  • Default: no trace information

Stack trace at the point of adding the metadata.

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

MetadataOptions

Options for construct.addMetadata().

Initializer 

import { MetadataOptions } from 'constructs'

const metadataOptions: MetadataOptions = { ... }

Properties

Name Type Description
stackTrace boolean Include stack trace with metadata entry.
traceFromFunction any A JavaScript function to begin tracing from.
stackTraceOptional 
public readonly stackTrace: boolean;
  • Type: boolean
  • Default: false

Include stack trace with metadata entry.

traceFromFunctionOptional 
public readonly traceFromFunction: any;
  • Type: any
  • Default: addMetadata()

A JavaScript function to begin tracing from.

This option is ignored unless stackTrace is true.

Classes

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

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

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

Initializers 

import { Dependable } from 'constructs'

new Dependable()
Name Type Description

Static Functions

Name Description
get Return the matching Dependable for the given class instance.
implement Turn any object into an IDependable.
of Return the matching Dependable for the given class instance.
get 
import { Dependable } from 'constructs'

Dependable.get(instance: IDependable)

Return the matching Dependable for the given class instance.

instanceRequired
implement 
import { Dependable } from 'constructs'

Dependable.implement(instance: IDependable, trait: Dependable)

Turn any object into an IDependable.

instanceRequired
traitRequired
of 
import { Dependable } from 'constructs'

Dependable.of(instance: IDependable)

Return the matching Dependable for the given class instance.

instanceRequired

Properties

Name Type Description
dependencyRoots IConstruct[] The set of constructs that form the root of this dependable.
dependencyRootsRequired 
public 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.

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.

Initializers 

import { DependencyGroup } from 'constructs'

new DependencyGroup(deps: ...IDependable[])
Name Type Description
deps ...IDependable[] No description.
depsRequired

Methods

Name Description
add Add a construct to the dependency roots.
add 
public add(scopes: ...IDependable[]): void

Add a construct to the dependency roots.

scopesRequired

Node

Represents the construct node in the scope tree.

Initializers 

import { Node } from 'constructs'

new Node(host: Construct, scope: IConstruct, id: string)
Name Type Description
host Construct No description.
scope IConstruct No description.
id string No description.
hostRequired
scopeRequired
idRequired
  • Type: string

Methods

Name Description
addDependency Add an ordering dependency on another construct.
addMetadata Adds a metadata entry to this construct.
addValidation Adds a validation to this construct.
findAll Return this construct and all of its children in the given order.
findChild Return a direct child by id.
getAllContext Retrieves the all context of a node from tree context.
getContext Retrieves a value from tree context if present. Otherwise, would throw an error.
lock Locks this construct from allowing more children to be added.
setContext This can be used to set contextual values.
tryFindChild Return a direct child by id, or undefined.
tryGetContext Retrieves a value from tree context.
tryRemoveChild Remove the child with the given name, if present.
validate Validates this construct.
addDependency 
public addDependency(deps: ...IDependable[]): void

Add an ordering dependency on another construct.

An IDependable

depsRequired
addMetadata 
public 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.

typeRequired
  • Type: string

a string denoting the type of metadata.

dataRequired
  • Type: any

the value of the metadata (can be a Token).

If null/undefined, metadata will not be added.

optionsOptional

options.

addValidation 
public 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.

validationRequired

The validation object.

findAll 
public findAll(order?: ConstructOrder): IConstruct[]

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

orderOptional
findChild 
public findChild(id: string): IConstruct

Return a direct child by id.

Throws an error if the child is not found.

idRequired
  • Type: string

Identifier of direct child.

getAllContext 
public 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.

defaultsOptional
  • Type: object

Any keys to override the retrieved context.

getContext 
public 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.

keyRequired
  • Type: string

The context key.

lock 
public 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.

setContext 
public 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.

keyRequired
  • Type: string

The context key.

valueRequired
  • Type: any

The context value.

tryFindChild 
public tryFindChild(id: string): IConstruct

Return a direct child by id, or undefined.

idRequired
  • Type: string

Identifier of direct child.

tryGetContext 
public 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.

keyRequired
  • Type: string

The context key.

tryRemoveChild 
public tryRemoveChild(childName: string): boolean

Remove the child with the given name, if present.

childNameRequired
  • Type: string
validate 
public validate(): string[]

Validates this construct.

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

Static Functions

Name Description
of Returns the node associated with a construct.
of 
import { Node } from 'constructs'

Node.of(construct: IConstruct)

Returns the node associated with a construct.

constructRequired

the construct.

Properties

Name Type Description
addr string Returns an opaque tree-unique address for this construct.
children IConstruct[] All direct children of this construct.
dependencies 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 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 IConstruct[] All parent scopes of this construct.
scope IConstruct Returns the scope in which this construct is defined.
defaultChild IConstruct Returns the child construct that has the id Default or Resource".
addrRequired 
public readonly addr: string;
  • Type: 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

c83a2846e506bcc5f10682b564084bca2d275709ee
childrenRequired 
public readonly children: IConstruct[];

All direct children of this construct.

dependenciesRequired 
public readonly dependencies: IConstruct[];

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

idRequired 
public readonly id: string;
  • Type: 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.

lockedRequired 
public readonly locked: boolean;
  • Type: boolean

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

metadataRequired 
public 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.

pathRequired 
public readonly path: string;
  • Type: string

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

Components are separated by '/'.

rootRequired 
public readonly root: IConstruct;

Returns the root of the construct tree.

scopesRequired 
public readonly scopes: IConstruct[];

All parent scopes of this construct.

scopeOptional 
public readonly scope: IConstruct;

Returns the scope in which this construct is defined.

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

defaultChildOptional 
public readonly 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. 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.

Constants

Name Type Description
PATH_SEP string Separator used to delimit construct path components.
PATH_SEPRequired 
public readonly PATH_SEP: string;
  • Type: string

Separator used to delimit construct path components.

Protocols

IConstruct

  • Extends: IDependable

  • Implemented By: Construct, RootConstruct, cdklabs-projen-project-types.yarn.CdkLabsMonorepo, cdklabs-projen-project-types.yarn.Monorepo, cdklabs-projen-project-types.yarn.MonorepoRelease, cdklabs-projen-project-types.yarn.TypeScriptWorkspace, cdklabs-projen-project-types.yarn.WorkspaceRelease, cdklabs-projen-project-types.CdkConstructLibrary, cdklabs-projen-project-types.CdkJsiiProject, cdklabs-projen-project-types.CdkTypeScriptProject, cdklabs-projen-project-types.CdklabsConstructLibrary, cdklabs-projen-project-types.CdklabsJsiiProject, cdklabs-projen-project-types.CdklabsTypeScriptProject, cdklabs-projen-project-types.Rosetta, projen.awscdk.AutoDiscover, projen.awscdk.AwsCdkConstructLibrary, projen.awscdk.AwsCdkDeps, projen.awscdk.AwsCdkDepsJava, projen.awscdk.AwsCdkDepsJs, projen.awscdk.AwsCdkDepsPy, projen.awscdk.AwsCdkJavaApp, projen.awscdk.AwsCdkPythonApp, projen.awscdk.AwsCdkTypeScriptApp, projen.awscdk.CdkConfig, projen.awscdk.CdkTasks, projen.awscdk.ConstructLibraryAws, projen.awscdk.EdgeLambdaAutoDiscover, projen.awscdk.IntegrationTest, projen.awscdk.IntegrationTestAutoDiscover, projen.awscdk.LambdaAutoDiscover, projen.awscdk.LambdaExtension, projen.awscdk.LambdaExtensionAutoDiscover, projen.awscdk.LambdaFunction, projen.build.BuildWorkflow, projen.cdk.AutoDiscoverBase, projen.cdk.ConstructLibrary, projen.cdk.IntegrationTestAutoDiscoverBase, projen.cdk.IntegrationTestBase, projen.cdk.JsiiDocgen, projen.cdk.JsiiProject, projen.cdk8s.AutoDiscover, projen.cdk8s.Cdk8sDeps, projen.cdk8s.Cdk8sDepsPy, projen.cdk8s.Cdk8sPythonApp, projen.cdk8s.Cdk8sTypeScriptApp, projen.cdk8s.ConstructLibraryCdk8s, projen.cdk8s.IntegrationTest, projen.cdk8s.IntegrationTestAutoDiscover, projen.cdktf.ConstructLibraryCdktf, projen.circleci.Circleci, projen.github.AutoApprove, projen.github.AutoMerge, projen.github.AutoQueue, projen.github.Dependabot, projen.github.GitHub, projen.github.GitHubProject, projen.github.GithubWorkflow, projen.github.MergeQueue, projen.github.Mergify, projen.github.PullRequestBackport, projen.github.PullRequestLint, projen.github.PullRequestTemplate, projen.github.Stale, projen.github.TaskWorkflow, projen.github.TaskWorkflowJob, projen.gitlab.CiConfiguration, projen.gitlab.GitlabConfiguration, projen.gitlab.NestedConfiguration, projen.java.JavaProject, projen.java.Junit, projen.java.MavenCompile, projen.java.MavenPackaging, projen.java.MavenSample, projen.java.Pom, projen.java.Projenrc, projen.javascript.Bundler, projen.javascript.Eslint, projen.javascript.Jest, projen.javascript.LicenseChecker, projen.javascript.NodePackage, projen.javascript.NodeProject, projen.javascript.NpmConfig, projen.javascript.Prettier, projen.javascript.Projenrc, projen.javascript.TypescriptConfig, projen.javascript.UpgradeDependencies, projen.javascript.Yarnrc, projen.python.Pip, projen.python.Poetry, projen.python.PoetryPyproject, projen.python.Projenrc, projen.python.Pytest, projen.python.PytestSample, projen.python.PythonProject, projen.python.PythonSample, projen.python.RequirementsFile, projen.python.SetupPy, projen.python.Setuptools, projen.python.Venv, projen.release.Publisher, projen.release.Release, projen.typescript.Projenrc, projen.typescript.ProjenrcTs, projen.typescript.TypeScriptAppProject, projen.typescript.TypeScriptLibraryProject, projen.typescript.TypeScriptProject, projen.vscode.DevContainer, projen.vscode.VsCode, projen.vscode.VsCodeLaunchConfig, projen.vscode.VsCodeRecommendedExtensions, projen.vscode.VsCodeSettings, projen.web.NextComponent, projen.web.NextJsProject, projen.web.NextJsTypeScriptProject, projen.web.ReactComponent, projen.web.ReactProject, projen.web.ReactTypeDef, projen.web.ReactTypeScriptProject, projen.Component, projen.Dependencies, projen.DockerCompose, projen.FileBase, projen.GitAttributesFile, projen.Gitpod, projen.IgnoreFile, projen.IniFile, projen.JsonFile, projen.License, projen.Logger, projen.Makefile, projen.ObjectFile, projen.Project, projen.ProjectBuild, projen.ProjectTree, projen.Projenrc, projen.ProjenrcFile, projen.ProjenrcJson, projen.Renovatebot, projen.SampleDir, projen.SampleFile, projen.SampleReadme, projen.SourceCode, projen.Tasks, projen.TextFile, projen.TomlFile, projen.Version, projen.XmlFile, projen.YamlFile, IConstruct

Represents a construct.

Properties

Name Type Description
node Node The tree node.
nodeRequired 
public readonly node: Node;

The tree node.

IDependable

  • Implemented By: Construct, DependencyGroup, RootConstruct, cdklabs-projen-project-types.yarn.CdkLabsMonorepo, cdklabs-projen-project-types.yarn.Monorepo, cdklabs-projen-project-types.yarn.MonorepoRelease, cdklabs-projen-project-types.yarn.TypeScriptWorkspace, cdklabs-projen-project-types.yarn.WorkspaceRelease, cdklabs-projen-project-types.CdkConstructLibrary, cdklabs-projen-project-types.CdkJsiiProject, cdklabs-projen-project-types.CdkTypeScriptProject, cdklabs-projen-project-types.CdklabsConstructLibrary, cdklabs-projen-project-types.CdklabsJsiiProject, cdklabs-projen-project-types.CdklabsTypeScriptProject, cdklabs-projen-project-types.Rosetta, projen.awscdk.AutoDiscover, projen.awscdk.AwsCdkConstructLibrary, projen.awscdk.AwsCdkDeps, projen.awscdk.AwsCdkDepsJava, projen.awscdk.AwsCdkDepsJs, projen.awscdk.AwsCdkDepsPy, projen.awscdk.AwsCdkJavaApp, projen.awscdk.AwsCdkPythonApp, projen.awscdk.AwsCdkTypeScriptApp, projen.awscdk.CdkConfig, projen.awscdk.CdkTasks, projen.awscdk.ConstructLibraryAws, projen.awscdk.EdgeLambdaAutoDiscover, projen.awscdk.IntegrationTest, projen.awscdk.IntegrationTestAutoDiscover, projen.awscdk.LambdaAutoDiscover, projen.awscdk.LambdaExtension, projen.awscdk.LambdaExtensionAutoDiscover, projen.awscdk.LambdaFunction, projen.build.BuildWorkflow, projen.cdk.AutoDiscoverBase, projen.cdk.ConstructLibrary, projen.cdk.IntegrationTestAutoDiscoverBase, projen.cdk.IntegrationTestBase, projen.cdk.JsiiDocgen, projen.cdk.JsiiProject, projen.cdk8s.AutoDiscover, projen.cdk8s.Cdk8sDeps, projen.cdk8s.Cdk8sDepsPy, projen.cdk8s.Cdk8sPythonApp, projen.cdk8s.Cdk8sTypeScriptApp, projen.cdk8s.ConstructLibraryCdk8s, projen.cdk8s.IntegrationTest, projen.cdk8s.IntegrationTestAutoDiscover, projen.cdktf.ConstructLibraryCdktf, projen.circleci.Circleci, projen.github.AutoApprove, projen.github.AutoMerge, projen.github.AutoQueue, projen.github.Dependabot, projen.github.GitHub, projen.github.GitHubProject, projen.github.GithubWorkflow, projen.github.MergeQueue, projen.github.Mergify, projen.github.PullRequestBackport, projen.github.PullRequestLint, projen.github.PullRequestTemplate, projen.github.Stale, projen.github.TaskWorkflow, projen.github.TaskWorkflowJob, projen.gitlab.CiConfiguration, projen.gitlab.GitlabConfiguration, projen.gitlab.NestedConfiguration, projen.java.JavaProject, projen.java.Junit, projen.java.MavenCompile, projen.java.MavenPackaging, projen.java.MavenSample, projen.java.Pom, projen.java.Projenrc, projen.javascript.Bundler, projen.javascript.Eslint, projen.javascript.Jest, projen.javascript.LicenseChecker, projen.javascript.NodePackage, projen.javascript.NodeProject, projen.javascript.NpmConfig, projen.javascript.Prettier, projen.javascript.Projenrc, projen.javascript.TypescriptConfig, projen.javascript.UpgradeDependencies, projen.javascript.Yarnrc, projen.python.Pip, projen.python.Poetry, projen.python.PoetryPyproject, projen.python.Projenrc, projen.python.Pytest, projen.python.PytestSample, projen.python.PythonProject, projen.python.PythonSample, projen.python.RequirementsFile, projen.python.SetupPy, projen.python.Setuptools, projen.python.Venv, projen.release.Publisher, projen.release.Release, projen.typescript.Projenrc, projen.typescript.ProjenrcTs, projen.typescript.TypeScriptAppProject, projen.typescript.TypeScriptLibraryProject, projen.typescript.TypeScriptProject, projen.vscode.DevContainer, projen.vscode.VsCode, projen.vscode.VsCodeLaunchConfig, projen.vscode.VsCodeRecommendedExtensions, projen.vscode.VsCodeSettings, projen.web.NextComponent, projen.web.NextJsProject, projen.web.NextJsTypeScriptProject, projen.web.ReactComponent, projen.web.ReactProject, projen.web.ReactTypeDef, projen.web.ReactTypeScriptProject, projen.Component, projen.Dependencies, projen.DockerCompose, projen.FileBase, projen.GitAttributesFile, projen.Gitpod, projen.IgnoreFile, projen.IniFile, projen.JsonFile, projen.License, projen.Logger, projen.Makefile, projen.ObjectFile, projen.Project, projen.ProjectBuild, projen.ProjectTree, projen.Projenrc, projen.ProjenrcFile, projen.ProjenrcJson, projen.Renovatebot, projen.SampleDir, projen.SampleFile, projen.SampleReadme, projen.SourceCode, projen.Tasks, projen.TextFile, projen.TomlFile, projen.Version, projen.XmlFile, projen.YamlFile, IConstruct, 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.

IValidation

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

Methods

Name Description
validate Validate the current construct.
validate 
public 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.

Enums

ConstructOrder

In what order to return constructs.

Members

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

Depth-first, pre-order.

POSTORDER

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