UNPKG

@aws-cdk/core

Version:

AWS Cloud Development Kit Core Library

418 lines (417 loc) 14.4 kB
/** * Constructs compatibility layer. * * This file includes types that shadow types in the "constructs" module in * order to allow backwards-compatiblity in the AWS CDK v1.0 release line. * * There are pretty ugly hacks here, which mostly involve downcasting types to * adhere to legacy AWS CDK APIs. * * This file, in its entirety, is expected to be removed in v2.0. */ import * as cxapi from '@aws-cdk/cx-api'; import * as constructs from 'constructs'; import { IAspect } from './aspect'; import { IDependable } from './dependency'; /** * Represents a construct. */ export interface IConstruct extends constructs.IConstruct, IDependable { /** * The construct tree node for this construct. */ readonly node: ConstructNode; } /** * Represents a single session of synthesis. Passed into `Construct.synthesize()` methods. */ export interface ISynthesisSession { /** * The output directory for this synthesis session. */ outdir: string; /** * Cloud assembly builder. */ assembly: cxapi.CloudAssemblyBuilder; /** * Whether the stack should be validated after synthesis to check for error metadata * * @default - false */ validateOnSynth?: boolean; } /** * 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 extends constructs.Construct implements IConstruct { /** * Return whether the given object is a Construct */ static isConstruct(x: any): x is Construct; /** * The construct tree node associated with this construct. */ readonly node: ConstructNode; constructor(scope: constructs.Construct, id: 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 the construct is valid. */ protected onValidate(): 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 onPrepare(): 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 onSynthesize(session: constructs.ISynthesisSession): void; /** * 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 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; } /** * 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 } /** * Options for synthesis. * * @deprecated use `app.synth()` or `stage.synth()` instead */ 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; /** * Whether the stack should be validated after synthesis to check for error metadata * * @default - false */ readonly validateOnSynthesis?: boolean; } /** * Represents the construct node in the scope tree. */ export declare class ConstructNode { /** * Separator used to delimit construct path components. */ static readonly PATH_SEP = "/"; /** * Returns the wrapping `@aws-cdk/core.ConstructNode` instance from a `constructs.ConstructNode`. * * @internal */ static _unwrap(c: constructs.Node): ConstructNode; /** * Synthesizes a CloudAssembly from a construct tree. * @param node The root of the construct tree. * @param options Synthesis options. * @deprecated Use `app.synth()` or `stage.synth()` instead */ static synth(node: ConstructNode, options?: SynthesisOptions): cxapi.CloudAssembly; /** * Invokes "prepare" on all constructs (depth-first, post-order) in the tree under `node`. * @param node The root node * @deprecated Use `app.synth()` instead */ 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[]; /** * @internal */ readonly _actualNode: constructs.Node; /** * The Construct class that hosts this API. */ private readonly host; constructor(host: Construct, scope: IConstruct, id: string); /** * Returns the scope in which this construct is defined. * * The value is `undefined` at the root of the construct scope tree. */ get scope(): IConstruct | undefined; /** * 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`. */ get id(): string; /** * The full, absolute path of this construct in the tree. * * Components are separated by '/'. */ get path(): string; /** * A tree-global unique alphanumeric identifier for this construct. Includes * all components of the tree. * * @deprecated use `node.addr` to obtain a consistent 42 character address for * this node (see https://github.com/aws/constructs/pull/314). * Alternatively, to get a CloudFormation-compatible unique identifier, use * `Names.uniqueId()`. */ get uniqueId(): 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 value: `c83a2846e506bcc5f10682b564084bca2d275709ee` */ get addr(): 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"`. * 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. * * @throws if there is more than one child * @returns a construct or undefined if there is no default child */ get defaultChild(): IConstruct | undefined; /** * 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. */ set defaultChild(value: IConstruct | undefined); /** * All direct children of this construct. */ get 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 the key. */ tryGetContext(key: string): any; /** * DEPRECATED * @deprecated use `metadataEntry` */ get metadata(): cxapi.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. */ get metadataEntry(): constructs.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 fromFunction a function under which to restrict the metadata entry's stack trace (defaults to this.addMetadata) */ addMetadata(type: string, data: any, fromFunction?: any): void; /** * DEPRECATED: Adds a { "info": <message> } metadata entry to this construct. * The toolkit will display the info message when apps are synthesized. * @param message The info message. * @deprecated use `Annotations.of(construct).addInfo()` */ addInfo(message: string): void; /** * DEPRECATED: 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. * @deprecated use `Annotations.of(construct).addWarning()` */ addWarning(message: string): void; /** * DEPRECATED: Adds an { "error": <message> } metadata entry to this construct. * The toolkit will fail synthesis when errors are reported. * @param message The error message. * @deprecated use `Annotations.of(construct).addError()` */ addError(message: string): void; /** * DEPRECATED: Applies the aspect to this Constructs node * * @deprecated This API is going to be removed in the next major version of * the AWS CDK. Please use `Aspects.of(scope).add()` instead. */ applyAspect(aspect: IAspect): void; /** * Add a validator to this construct Node */ addValidation(validation: constructs.IValidation): 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. */ get scopes(): IConstruct[]; /** * @returns The root of the construct tree. */ get root(): IConstruct; /** * Returns true if this construct or the scopes in which it is defined are * locked. */ get locked(): boolean; /** * 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 */ get dependencies(): Dependency[]; /** * Remove the child with the given name, if present. * * @returns Whether a child with the given name was deleted. */ tryRemoveChild(childName: string): boolean; } /** * 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; } /** * A single dependency */ export interface Dependency { /** * Source the dependency */ readonly source: IConstruct; /** * Target of the dependency */ readonly target: IConstruct; }