382 lines
13 KiB
TypeScript
382 lines
13 KiB
TypeScript
import type { IDependable } from './dependency';
|
|
import type { MetadataEntry } from './metadata';
|
|
import type { IMixin } from './mixin';
|
|
/**
|
|
* Represents a construct.
|
|
*/
|
|
export interface IConstruct extends IDependable {
|
|
/**
|
|
* The tree node.
|
|
*/
|
|
readonly node: Node;
|
|
/**
|
|
* Applies one or more mixins to this construct.
|
|
*
|
|
* Mixins are applied in order. The list of constructs is captured at the
|
|
* start of the call, so constructs added by a mixin will not be visited.
|
|
*
|
|
* @param mixins The mixins to apply
|
|
* @returns This construct for chaining
|
|
*/
|
|
with(...mixins: IMixin[]): IConstruct;
|
|
}
|
|
/**
|
|
* Represents the construct node in the scope tree.
|
|
*/
|
|
export declare class Node {
|
|
private readonly host;
|
|
/**
|
|
* Separator used to delimit construct path components.
|
|
*/
|
|
static readonly PATH_SEP = "/";
|
|
/**
|
|
* Returns the node associated with a construct.
|
|
* @param construct the construct
|
|
*
|
|
* @deprecated use `construct.node` instead
|
|
*/
|
|
static of(construct: IConstruct): Node;
|
|
/**
|
|
* 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 scope-unique id. To obtain an app-unique id for this construct, use `addr`.
|
|
*/
|
|
readonly id: string;
|
|
private _locked;
|
|
private _children;
|
|
private _context;
|
|
private _metadata;
|
|
private _dependencies;
|
|
private _defaultChild;
|
|
private _validations;
|
|
private _addr?;
|
|
constructor(host: Construct, scope: IConstruct, id: string);
|
|
/**
|
|
* The full, absolute path of this construct in the tree.
|
|
*
|
|
* Components are separated by '/'.
|
|
*/
|
|
get path(): 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
|
|
*/
|
|
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 if present. Otherwise, would throw an error.
|
|
*
|
|
* 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 throws error if there is no context value for this key
|
|
*/
|
|
getContext(key: string): 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.
|
|
*
|
|
* @param defaults Any keys to override the retrieved context
|
|
* @returns The context object or an empty object if there is discovered context
|
|
*/
|
|
getAllContext(defaults?: object): any;
|
|
/**
|
|
* 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 this 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.
|
|
*/
|
|
get metadata(): 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.
|
|
* 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.
|
|
*
|
|
* @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 options options
|
|
*/
|
|
addMetadata(type: string, data: any, options?: MetadataOptions): 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.
|
|
* @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.
|
|
*
|
|
* An `IDependable`
|
|
*/
|
|
addDependency(...deps: IDependable[]): void;
|
|
/**
|
|
* Return all dependencies registered on this node (non-recursive).
|
|
*/
|
|
get dependencies(): IConstruct[];
|
|
/**
|
|
* Remove the child with the given name, if present.
|
|
*
|
|
* @returns Whether a child with the given name was deleted.
|
|
*/
|
|
tryRemoveChild(childName: string): boolean;
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param validation The validation object
|
|
*/
|
|
addValidation(validation: IValidation): void;
|
|
/**
|
|
* 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[];
|
|
/**
|
|
* 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;
|
|
/**
|
|
* Applies one or more mixins to this construct.
|
|
*
|
|
* Mixins are applied in order. The list of constructs is captured at the
|
|
* start of the call, so constructs added by a mixin will not be visited.
|
|
* Use multiple `with()` calls if subsequent mixins should apply to added
|
|
* constructs.
|
|
*
|
|
* @param mixins The mixins to apply
|
|
* @returns This construct for chaining
|
|
*/
|
|
with(...mixins: IMixin[]): IConstruct;
|
|
/**
|
|
* 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;
|
|
}
|
|
/**
|
|
* 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 {
|
|
/**
|
|
* 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`.
|
|
* @param x Any object
|
|
*/
|
|
static isConstruct(x: any): x is Construct;
|
|
/**
|
|
* The tree node.
|
|
*/
|
|
readonly node: Node;
|
|
/**
|
|
* 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);
|
|
/**
|
|
* Applies one or more mixins to this construct.
|
|
*
|
|
* Mixins are applied in order. The list of constructs is captured at the
|
|
* start of the call, so constructs added by a mixin will not be visited.
|
|
* Use multiple `with()` calls if subsequent mixins should apply to added
|
|
* constructs.
|
|
*
|
|
* @param mixins The mixins to apply
|
|
* @returns This construct for chaining
|
|
*/
|
|
with(...mixins: IMixin[]): IConstruct;
|
|
/**
|
|
* Returns a string representation of this construct.
|
|
*/
|
|
toString(): string;
|
|
}
|
|
/**
|
|
* Implement this interface in order for the construct to be able to validate itself.
|
|
*/
|
|
export interface IValidation {
|
|
/**
|
|
* 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[];
|
|
}
|
|
/**
|
|
* 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 `construct.addMetadata()`.
|
|
*/
|
|
export interface MetadataOptions {
|
|
/**
|
|
* Include stack trace with metadata entry.
|
|
* @default false
|
|
*/
|
|
readonly stackTrace?: boolean;
|
|
/**
|
|
* A JavaScript function to begin tracing from.
|
|
*
|
|
* This option is ignored unless `stackTrace` is `true`.
|
|
*
|
|
* @default addMetadata()
|
|
*/
|
|
readonly traceFromFunction?: any;
|
|
/**
|
|
* The actual stack trace to be added to the metadata. If this
|
|
* parameter is passed, the stackTrace parameter is ignored.
|
|
*/
|
|
readonly stackTraceOverride?: 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.
|
|
*/
|
|
export declare class RootConstruct extends Construct {
|
|
/**
|
|
* Creates a new root construct node.
|
|
*
|
|
* @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(id?: string);
|
|
}
|