terraconstructs 0.2.1 → 0.2.2

package/lib/aws/storage/table.d.ts

@@ -3,7 +3,9 @@ import { Construct } from "constructs";
 import * as storage from ".";
 import { AwsConstructBase, AwsConstructProps } from "..";
 import { EnableScalingProps, IScalableTableAttribute } from "./scalable-attribute-api";
-import { OperationsMetricOptions, SystemErrorsForOperationsMetricOptions, Attribute, BillingMode, ITable, SecondaryIndexProps, TableClass, LocalSecondaryIndexProps, TableEncryption, StreamViewType, PointInTimeRecoverySpecification } from "./shared";
+import { OperationsMetricOptions, SystemErrorsForOperationsMetricOptions, Attribute, BillingMode, ITable, SecondaryIndexProps, TableClass, LocalSecondaryIndexProps, TableEncryption, StreamViewType, PointInTimeRecoverySpecification, WarmThroughput, ContributorInsightsSpecification } from "./shared";
+import { StreamGrants } from "./stream-grants";
+import { TableGrants } from "./table-grants";
 import * as cloudwatch from "../cloudwatch";
 import * as kms from "../encryption";
 import * as iam from "../iam";
@@ -84,9 +86,16 @@ export declare abstract class InputFormat {
      * CSV format.
      */
     static csv(options?: CsvOptions): InputFormat;
+    /**
+     * Valid CSV delimiters.
+     *
+     * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-dynamodb-table-csv.html#cfn-dynamodb-table-csv-delimiter
+     */
     private static validCsvDelimiters;
     private static readableValidCsvDelimiters;
     /**
+     * Render the input format and options.
+     *
      * @internal
      */
     abstract _render(): Pick<dynamodbTable.DynamodbTableImportTable, "inputFormat" | "inputFormatOptions">;
@@ -195,6 +204,13 @@ export interface TableOptions extends SchemaOptions {
      * @default PROVISIONED if `replicationRegions` is not specified, PAY_PER_REQUEST otherwise
      */
     readonly billingMode?: BillingMode;
+    /**
+     * Specify values to pre-warm you DynamoDB Table
+     * Warm Throughput feature is not available for Global Table replicas using the `Table` construct. To enable Warm Throughput, use the `TableV2` construct instead.
+     * @see http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-dynamodb-table.html#cfn-dynamodb-table-warmthroughput
+     * @default - warm throughput is not configured
+     */
+    readonly warmThroughput?: WarmThroughput;
     /**
      * Whether point-in-time recovery is enabled.
      * @deprecated use `pointInTimeRecoverySpecification` instead
@@ -202,7 +218,8 @@ export interface TableOptions extends SchemaOptions {
      */
     readonly pointInTimeRecovery?: boolean;
     /**
-     * Whether point-in-time recovery is enabled.
+     * Whether point-in-time recovery is enabled
+     * and recoveryPeriodInDays is set.
      *
      * @default - point in time recovery is not enabled.
      */
@@ -267,10 +284,15 @@ export interface TableOptions extends SchemaOptions {
     readonly replicaSpecification?: DynamodbTableReplica[];
     /**
      * Whether CloudWatch contributor insights is enabled.
-     *
+     * @deprecated use `contributorInsightsSpecification instead
      * @default false
      */
     readonly contributorInsightsEnabled?: boolean;
+    /**
+     * Whether CloudWatch contributor insights is enabled and what mode is selected
+     * @default - contributor insights is not enabled
+     */
+    readonly contributorInsightsSpecification?: ContributorInsightsSpecification;
     /**
      * Enables deletion protection for the table.
      *
@@ -350,11 +372,16 @@ export interface GlobalSecondaryIndexProps extends SecondaryIndexProps, SchemaOp
      */
     readonly maxWriteRequestUnits?: number;
     /**
-     * Whether CloudWatch contributor insights is enabled for the specified global secondary index.
+     * The warm throughput configuration for the global secondary index.
      *
-     * @default false
+     * @default - no warm throughput is configured
      */
-    readonly contributorInsightsEnabled?: boolean;
+    readonly warmThroughput?: WarmThroughput;
+    /**
+     * Whether CloudWatch contributor insights is enabled and what mode is selected
+     * @default - contributor insights is not enabled
+     */
+    readonly contributorInsightsSpecification?: ContributorInsightsSpecification;
 }
 /**
  * Reference to a dynamodb table.
@@ -419,36 +446,202 @@ export declare abstract class TableBase extends AwsConstructBase implements ITab
     abstract readonly tableArn: string;
     abstract readonly tableName: string;
     abstract readonly tableStreamArn?: string;
+    /**
+     * KMS encryption key, if this table uses a customer-managed encryption key.
+     */
     abstract readonly encryptionKey?: kms.IKey;
+    /**
+     * Resource policy to assign to table.
+     */
     abstract resourcePolicy?: iam.PolicyDocument;
+    /**
+     * Additional regions other than the main one that this table is replicated to
+     *
+     */
+    abstract readonly regions?: string[];
+    /**
+     * @deprecated This member is still filled but it is not read
+     */
     protected readonly regionalArns: string[];
+    grantOnKey(grantee: iam.IGrantable, ...actions: string[]): iam.GrantOnKeyResult;
     get outputs(): Record<string, any>;
+    /**
+     * Grant a predefined set of permissions on this Table.
+     */
+    get grants(): TableGrants;
+    /**
+     * Grant a predefined set of permissions on this Table's Stream, if present.
+     *
+     * Will throw if the Table has not been configured for streaming.
+     */
+    get streamGrants(): StreamGrants;
+    /**
+     * Adds a statement to the resource policy associated with this table.
+     */
+    abstract addToResourcePolicy(statement: iam.PolicyStatement): iam.AddToResourcePolicyResult;
+    /**
+     * Adds an IAM policy statement associated with this table to an IAM
+     * principal's policy.
+     *
+     * If `encryptionKey` is present, appropriate grants to the key needs to be added
+     * separately using the `table.encryptionKey.grant*` methods.
+     *
+     * @param grantee The principal (no-op if undefined)
+     * @param actions The set of actions to allow (i.e. "dynamodb:PutItem", "dynamodb:GetItem", ...)
+     */
     grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
+    /**
+     * Adds an IAM policy statement associated with this table's stream to an
+     * IAM principal's policy.
+     *
+     * If `encryptionKey` is present, appropriate grants to the key needs to be added
+     * separately using the `table.encryptionKey.grant*` methods.
+     *
+     * @param grantee The principal (no-op if undefined)
+     * @param actions The set of actions to allow (i.e. "dynamodb:DescribeStream", "dynamodb:GetRecords", ...)
+     */
     grantStream(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
+    /**
+     * Permits an IAM principal all data read operations from this table:
+     * BatchGetItem, GetRecords, GetShardIterator, Query, GetItem, Scan, DescribeTable.
+     *
+     * Appropriate grants will also be added to the customer-managed KMS key
+     * if one was configured.
+     *
+     * @param grantee The principal to grant access to
+     */
     grantReadData(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Permits an IAM Principal to list streams attached to current dynamodb table.
+     *
+     * @param grantee The principal (no-op if undefined)
+     */
     grantTableListStreams(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Permits an IAM principal all stream data read operations for this
+     * table's stream:
+     * DescribeStream, GetRecords, GetShardIterator, ListStreams.
+     *
+     * Appropriate grants will also be added to the customer-managed KMS key
+     * if one was configured.
+     *
+     * @param grantee The principal to grant access to
+     */
     grantStreamRead(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Permits an IAM principal all data write operations to this table:
+     * BatchWriteItem, PutItem, UpdateItem, DeleteItem, DescribeTable.
+     *
+     * Appropriate grants will also be added to the customer-managed KMS key
+     * if one was configured.
+     *
+     * @param grantee The principal to grant access to
+     */
     grantWriteData(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Permits an IAM principal to all data read/write operations to this table.
+     * BatchGetItem, GetRecords, GetShardIterator, Query, GetItem, Scan,
+     * BatchWriteItem, PutItem, UpdateItem, DeleteItem, DescribeTable
+     *
+     * Appropriate grants will also be added to the customer-managed KMS key
+     * if one was configured.
+     *
+     * @param grantee The principal to grant access to
+     */
     grantReadWriteData(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Permits all DynamoDB operations ("dynamodb:*") to an IAM principal.
+     *
+     * Appropriate grants will also be added to the customer-managed KMS key
+     * if one was configured.
+     *
+     * @param grantee The principal to grant access to
+     */
     grantFullAccess(grantee: iam.IGrantable): iam.Grant;
-    addToResourcePolicy(statement: iam.PolicyStatement): iam.AddToResourcePolicyResult;
     metric(metricName: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /**
+     * Metric for the consumed read capacity units this table
+     *
+     * By default, the metric will be calculated as a sum over a period of 5 minutes.
+     * You can customize this by using the `statistic` and `period` properties.
+     */
     metricConsumedReadCapacityUnits(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /**
+     * Metric for the consumed write capacity units this table
+     *
+     * By default, the metric will be calculated as a sum over a period of 5 minutes.
+     * You can customize this by using the `statistic` and `period` properties.
+     */
     metricConsumedWriteCapacityUnits(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
     /** @deprecated use `metricSystemErrorsForOperations`. */
     metricSystemErrors(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /**
+     * Metric for the user errors. Note that this metric reports user errors across all
+     * the tables in the account and region the table resides in.
+     *
+     * By default, the metric will be calculated as a sum over a period of 5 minutes.
+     * You can customize this by using the `statistic` and `period` properties.
+     */
     metricUserErrors(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /**
+     * Metric for the conditional check failed requests this table
+     *
+     * By default, the metric will be calculated as a sum over a period of 5 minutes.
+     * You can customize this by using the `statistic` and `period` properties.
+     */
     metricConditionalCheckFailedRequests(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
     /** @deprecated Do not use this function. It returns an invalid metric. Use `metricThrottledRequestsForOperation` instead. */
     metricThrottledRequests(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /**
+     * Metric for the successful request latency this table.
+     *
+     * By default, the metric will be calculated as an average over a period of 5 minutes.
+     * You can customize this by using the `statistic` and `period` properties.
+     */
     metricSuccessfulRequestLatency(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /**
+     * How many requests are throttled on this table, for the given operation
+     *
+     * Default: sum over 5 minutes
+     */
     metricThrottledRequestsForOperation(operation: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /**
+     * How many requests are throttled on this table.
+     *
+     * This will sum errors across all possible operations.
+     * Note that by default, each individual metric will be calculated as a sum over a period of 5 minutes.
+     * You can customize this by using the `statistic` and `period` properties.
+     */
     metricThrottledRequestsForOperations(props?: OperationsMetricOptions): cloudwatch.IMetric;
+    /**
+     * Metric for the system errors this table.
+     *
+     * This will sum errors across all possible operations.
+     * Note that by default, each individual metric will be calculated as a sum over a period of 5 minutes.
+     * You can customize this by using the `statistic` and `period` properties.
+     */
     metricSystemErrorsForOperations(props?: SystemErrorsForOperationsMetricOptions): cloudwatch.IMetric;
+    /**
+     * Create a math expression for operations.
+     *
+     * @param metricName The metric name.
+     * @param expressionLabel Label for expression
+     * @param props operation list
+     */
     private sumMetricsForOperations;
+    /**
+     * Create a map of metrics that can be used in a math expression.
+     *
+     * Using the return value of this function as the `usingMetrics` property in `cloudwatch.MathExpression` allows you to
+     * use the keys of this map as metric names inside you expression.
+     *
+     * @param metricName The metric name.
+     * @param operations The list of operations to create metrics for.
+     * @param props Properties for the individual metrics.
+     * @param metricNameMapper Mapper function to allow controlling the individual metric name per operation.
+     */
     private createMetricsForOperations;
     protected abstract get hasIndex(): boolean;
-    private combinedGrant;
     private cannedMetric;
 }
 /**
@@ -507,22 +700,88 @@ export declare class Table extends TableBase {
     private readonly indexScaling;
     private readonly _resource;
     private readonly _replicas;
+    readonly regions?: string[] | undefined;
     constructor(scope: Construct, id: string, props: TableProps);
+    /**
+     * Adds a statement to the resource policy associated with this table.
+     * A resource policy will be automatically created upon the first call to `addToResourcePolicy`.
+     *
+     * Note that this does not work with imported tables.
+     *
+     * @param statement The policy statement to add
+     */
+    addToResourcePolicy(statement: iam.PolicyStatement): iam.AddToResourcePolicyResult;
     addGlobalSecondaryIndex(props: GlobalSecondaryIndexProps): void;
+    /**
+     * Add a local secondary index of table.
+     *
+     * @param props the property of local secondary index
+     */
     addLocalSecondaryIndex(props: LocalSecondaryIndexProps): void;
+    /**
+     * Enable read capacity scaling for this table
+     *
+     * @returns An object to configure additional AutoScaling settings
+     */
     autoScaleReadCapacity(props: EnableScalingProps): IScalableTableAttribute;
+    /**
+     * Enable write capacity scaling for this table
+     *
+     * @returns An object to configure additional AutoScaling settings for this attribute
+     */
     autoScaleWriteCapacity(props: EnableScalingProps): IScalableTableAttribute;
+    /**
+     * Enable read capacity scaling for the given GSI
+     *
+     * @returns An object to configure additional AutoScaling settings for this attribute
+     */
     autoScaleGlobalSecondaryIndexReadCapacity(indexName: string, props: EnableScalingProps): IScalableTableAttribute;
+    /**
+     * Enable write capacity scaling for the given GSI
+     *
+     * @returns An object to configure additional AutoScaling settings for this attribute
+     */
     autoScaleGlobalSecondaryIndexWriteCapacity(indexName: string, props: EnableScalingProps): IScalableTableAttribute;
+    /**
+     * Get schema attributes of table or index.
+     *
+     * @returns Schema of table or index.
+     */
     schema(indexName?: string): SchemaOptions;
+    /**
+     * Validate the table construct.
+     *
+     * @returns an array of validation error message
+     */
     private validateTable;
+    /**
+     * Validate read and write capacity are not specified for on-demand tables (billing mode PAY_PER_REQUEST).
+     *
+     * @param props read and write capacity properties
+     */
     private validateProvisioning;
     private validateProvisioningGSI;
+    /**
+     * Validate index name to check if a duplicate name already exists.
+     *
+     * @param indexName a name of global or local secondary index
+     */
     private validateIndexName;
+    /**
+     * Validate non-key attributes by checking limits within secondary index, which may vary in future.
+     *
+     * @param nonKeyAttributes a list of non-key attribute names
+     */
     private validateNonKeyAttributes;
     private renderPointInTimeRecovery;
+    private renderContributorInsights;
     private buildIndexProjection;
     private addKey;
+    /**
+     * Register the key attribute of table or secondary index to assemble attribute definitions of TableResourceProps.
+     *
+     * @param attribute the key attribute of table or secondary index
+     */
     private registerAttribute;
     /**
      * Creates replica tables
@@ -530,7 +789,20 @@ export declare class Table extends TableBase {
      * @param regions regions where to create tables
      */
     private renderReplicas;
+    /**
+     * Whether this table has indexes
+     */
     protected get hasIndex(): boolean;
+    /**
+     * Set up key properties and return the Table encryption property from the
+     * user's configuration.
+     */
     private parseEncryption;
     private renderImportSourceSpecification;
+    /**
+     * Adds resource to the Terraform JSON output at Synth time.
+     *
+     * called by TerraformStack.prepareStack()
+     */
+    toTerraform(): any;
 }