@aws-cdk/core/lib/construct.d.ts

AWS Cloud Development Kit Core Library

import cxapi = require('@aws-cdk/cx-api');
import { IAspect } from './aspect';
import { IDependable } from './dependency';
import { IResolvable } from './resolvable';
/**
 * Represents a construct.
 */
export interface IConstruct extends IDependable {
    /**
     * The construct node in the tree.
     */
    readonly node: ConstructNode;
}
/**
 * Represents the construct node in the scope tree.
 */
export declare class ConstructNode {
    private readonly host;
    /**
     * Separator used to delimit construct path components.
     */
    static readonly PATH_SEP = "/";
    /**
     * Synthesizes a CloudAssembly from a construct tree.
     * @param root The root of the construct tree.
     * @param options Synthesis options.
     */
    static synth(root: ConstructNode, options?: SynthesisOptions): cxapi.CloudAssembly;
    /**
     * Invokes "prepare" on all constructs (depth-first, post-order) in the tree under `node`.
     * @param node The root node
     */
    static prepare(node: ConstructNode): void;
    /**
     * Invokes "validate" on all constructs in the tree (depth-first, pre-order) and returns
     * the list of all errors. An empty list indicates that there are no errors.
     *
     * @param node The root node
     */
    static validate(node: ConstructNode): ValidationError[];
    /**
     * Returns the scope in which this construct is defined.
     *
     * The value is `undefined` at the root of the construct scope tree.
     */
    readonly scope?: IConstruct;
    /**
     * The id of this construct within the current scope.
     *
     * This is a a scope-unique id. To obtain an app-unique id for this construct, use `uniqueId`.
     */
    readonly id: string;
    private _locked;
    private readonly _aspects;
    private readonly _children;
    private readonly _context;
    private readonly _metadata;
    private readonly _references;
    private readonly _dependencies;
    private readonly invokedAspects;
    private _defaultChild;
    constructor(host: Construct, scope: IConstruct, id: string);
    /**
     * The full, absolute path of this construct in the tree.
     *
     * Components are separated by '/'.
     */
    readonly path: string;
    /**
     * A tree-global unique alphanumeric identifier for this construct.
     * Includes all components of the tree.
     */
    readonly uniqueId: string;
    /**
     * Return a direct child by id, or undefined
     *
     * @param id Identifier of direct child
     * @returns the child if found, or undefined
     */
    tryFindChild(id: string): IConstruct | undefined;
    /**
     * Return a direct child by id
     *
     * Throws an error if the child is not found.
     *
     * @param id Identifier of direct child
     * @returns Child with the given id.
     */
    findChild(id: string): IConstruct;
    /**
     * Returns the child construct that has the id `Default` or `Resource"`
     * @throws if there is more than one child
     * @returns a construct or undefined if there is no default child
     */
    /**
    * 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.
    */
    defaultChild: IConstruct | undefined;
    /**
     * All direct children of this construct.
     */
    readonly children: IConstruct[];
    /**
     * Return this construct and all of its children in the given order
     */
    findAll(order?: ConstructOrder): IConstruct[];
    /**
     * 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.
     * @param key The context key
     * @param value The context value
     */
    setContext(key: string, value: any): void;
    /**
     * Retrieves a value from tree context.
     *
     * Context is usually initialized at the root, but can be overridden at any point in the tree.
     *
     * @param key The context key
     * @returns The context value or `undefined` if there is no context value for thie key.
     */
    tryGetContext(key: string): any;
    /**
     * 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.
     */
    readonly metadata: cxapi.MetadataEntry[];
    /**
     * 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.
     *
     * @param type a string denoting the type of metadata
     * @param data the value of the metadata (can be a Token). If null/undefined, metadata will not be added.
     * @param from a function under which to restrict the metadata entry's stack trace (defaults to this.addMetadata)
     */
    addMetadata(type: string, data: any, from?: any): void;
    /**
     * Adds a { "aws:cdk:info": <message> } metadata entry to this construct.
     * The toolkit will display the info message when apps are synthesized.
     * @param message The info message.
     */
    addInfo(message: string): void;
    /**
     * Adds a { warning: <message> } metadata entry to this construct.
     * The toolkit will display the warning when an app is synthesized, or fail
     * if run in --strict mode.
     * @param message The warning message.
     */
    addWarning(message: string): void;
    /**
     * Adds an { error: <message> } metadata entry to this construct.
     * The toolkit will fail synthesis when errors are reported.
     * @param message The error message.
     */
    addError(message: string): void;
    /**
     * Applies the aspect to this Constructs node
     */
    applyAspect(aspect: IAspect): void;
    /**
     * 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.
     */
    readonly scopes: IConstruct[];
    /**
     * @returns The root of the construct tree.
     */
    readonly root: IConstruct;
    /**
     * Returns true if this construct or the scopes in which it is defined are
     * locked.
     */
    readonly locked: boolean;
    /**
     * Record a reference originating from this construct node
     */
    addReference(...refs: IResolvable[]): void;
    /**
     * Return all references originating from this node or any of its children
     */
    readonly references: OutgoingReference[];
    /**
     * Add an ordering dependency on another Construct.
     *
     * All constructs in the dependency's scope will be deployed before any
     * construct in this construct's scope.
     */
    addDependency(...dependencies: IDependable[]): void;
    /**
     * Return all dependencies registered on this node or any of its children
     */
    readonly dependencies: Dependency[];
    /**
     * Adds a child construct to this node.
     *
     * @param child The child construct
     * @param childName The type name of the child construct.
     * @returns The resolved path part name of the child
     */
    private addChild;
    /**
     * Triggers each aspect to invoke visit
     */
    private invokeAspects;
}
/**
 * Represents the building block of the construct graph.
 *
 * All constructs besides the root construct must be created within the scope of
 * another construct.
 */
export declare class Construct implements IConstruct {
    /**
     * Return whether the given object is a Construct
     */
    static isConstruct(x: any): x is Construct;
    /**
     * Construct tree node which offers APIs for interacting with the construct tree.
     */
    readonly node: ConstructNode;
    /**
     * Creates a new construct node.
     *
     * @param scope The scope in which to define this construct
     * @param 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 `--`.
     */
    constructor(scope: Construct, id: string);
    /**
     * Returns a string representation of this construct.
     */
    toString(): 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.
     */
    protected validate(): string[];
    /**
     * Perform final modifications before synthesis
     *
     * This method can be implemented by derived constructs in order to perform
     * final changes before synthesis. prepare() will be called after child
     * constructs have been prepared.
     *
     * This is an advanced framework feature. Only use this if you
     * understand the implications.
     */
    protected prepare(): void;
    /**
     * Allows this construct to emit artifacts into the cloud assembly during synthesis.
     *
     * This method is usually implemented by framework-level constructs such as `Stack` and `Asset`
     * as they participate in synthesizing the cloud assembly.
     *
     * @param session The synthesis session.
     */
    protected synthesize(session: ISynthesisSession): void;
}
/**
 * An error returned during the validation phase.
 */
export interface ValidationError {
    /**
     * The construct which emitted the error.
     */
    readonly source: Construct;
    /**
     * The error message.
     */
    readonly message: string;
}
/**
 * In what order to return constructs
 */
export declare enum ConstructOrder {
    /**
     * Depth-first, pre-order
     */
    PREORDER = 0,
    /**
     * Depth-first, post-order (leaf nodes first)
     */
    POSTORDER = 1
}
/**
 * A single dependency
 */
export interface Dependency {
    /**
     * Source the dependency
     */
    readonly source: IConstruct;
    /**
     * Target of the dependency
     */
    readonly target: IConstruct;
}
/**
 * Represents a reference that originates from a specific construct.
 */
export interface OutgoingReference {
    /**
     * The originating construct.
     */
    readonly source: IConstruct;
    /**
     * The reference.
     */
    readonly reference: Reference;
}
/**
 * Represents a single session of synthesis. Passed into `Construct.synthesize()` methods.
 */
export interface ISynthesisSession {
    /**
     * The cloud assembly being synthesized.
     */
    assembly: cxapi.CloudAssemblyBuilder;
}
/**
 * Options for synthesis.
 */
export interface SynthesisOptions extends cxapi.AssemblyBuildOptions {
    /**
     * The output directory into which to synthesize the cloud assembly.
     * @default - creates a temporary directory
     */
    readonly outdir?: string;
    /**
     * Whether synthesis should skip the validation phase.
     * @default false
     */
    readonly skipValidation?: boolean;
}
import { Reference } from './reference';