terraconstructs 0.0.23 → 0.0.24

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

@@ -0,0 +1,536 @@
+import { dynamodbTable } from "@cdktf/provider-aws";
+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 * as cloudwatch from "../cloudwatch";
+import * as kms from "../encryption";
+import * as iam from "../iam";
+import * as kinesis from "../notify";
+/**
+ * Represents the table schema attributes.
+ */
+export interface SchemaOptions {
+    /**
+     * Partition key attribute definition.
+     */
+    readonly partitionKey: Attribute;
+    /**
+     * Sort key attribute definition.
+     *
+     * @default no sort key
+     */
+    readonly sortKey?: Attribute;
+}
+/**
+ * Type of compression to use for imported data.
+ */
+export declare enum InputCompressionType {
+    /**
+     * GZIP compression.
+     */
+    GZIP = "GZIP",
+    /**
+     * ZSTD compression.
+     */
+    ZSTD = "ZSTD",
+    /**
+     * No compression.
+     */
+    NONE = "NONE"
+}
+/**
+ * The options for imported source files in CSV format.
+ */
+export interface CsvOptions {
+    /**
+     * The delimiter used for separating items in the CSV file being imported.
+     *
+     * Valid delimiters are as follows:
+     * - comma (`,`)
+     * - tab (`\t`)
+     * - colon (`:`)
+     * - semicolon (`;`)
+     * - pipe (`|`)
+     * - space (` `)
+     *
+     * @default - use comma as a delimiter.
+     */
+    readonly delimiter?: string;
+    /**
+     * List of the headers used to specify a common header for all source CSV files being imported.
+     *
+     * **NOTE**: If this field is specified then the first line of each CSV file is treated as data instead of the header.
+     * If this field is not specified the the first line of each CSV file is treated as the header.
+     *
+     * @default - the first line of the CSV file is treated as the header
+     */
+    readonly headerList?: string[];
+}
+/**
+ * The format of the source data.
+ */
+export declare abstract class InputFormat {
+    /**
+     * DynamoDB JSON format.
+     */
+    static dynamoDBJson(): InputFormat;
+    /**
+     * Amazon Ion format.
+     */
+    static ion(): InputFormat;
+    /**
+     * CSV format.
+     */
+    static csv(options?: CsvOptions): InputFormat;
+    private static validCsvDelimiters;
+    private static readableValidCsvDelimiters;
+    /**
+     * @internal
+     */
+    abstract _render(): Pick<dynamodbTable.DynamodbTableImportTable, "inputFormat" | "inputFormatOptions">;
+}
+/**
+ *  Properties for importing data from the S3.
+ */
+export interface ImportSourceSpecification {
+    /**
+     * The compression type of the imported data.
+     *
+     * @default InputCompressionType.NONE
+     */
+    readonly compressionType?: InputCompressionType;
+    /**
+     * The format of the imported data.
+     */
+    readonly inputFormat: InputFormat;
+    /**
+     * The S3 bucket that is being imported from.
+     */
+    readonly bucket: storage.IBucket;
+    /**
+     * The account number of the S3 bucket that is being imported from.
+     *
+     * @default - no value
+     */
+    readonly bucketOwner?: string;
+    /**
+     * The key prefix shared by all S3 Objects that are being imported.
+     *
+     * @default - no value
+     */
+    readonly keyPrefix?: string;
+}
+/**
+ * The precision associated with the DynamoDB write timestamps that will be replicated to Kinesis.
+ * The default setting for record timestamp precision is microseconds. You can change this setting at any time.
+ * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-dynamodb-table-kinesisstreamspecification.html#aws-properties-dynamodb-table-kinesisstreamspecification-properties
+ */
+export declare enum ApproximateCreationDateTimePrecision {
+    /**
+     * Millisecond precision
+     */
+    MILLISECOND = "MILLISECOND",
+    /**
+     * Microsecond precision
+     */
+    MICROSECOND = "MICROSECOND"
+}
+export interface DynamodbTableReplica {
+    /** (Optional) ARN of the CMK that should be used for the AWS KMS encryption. This argument should only be used if the key is different from the default KMS-managed DynamoDB key, `alias/aws/dynamodb`. **Note:** This attribute will _not_ be populated with the ARN of _default_ keys. */
+    readonly encryptionKey?: kms.IKey;
+    /** (Optional) Whether to enable Point In Time Recovery for the replica. Default is `false`. */
+    readonly pointInTimeRecovery?: boolean;
+    /** (Optional) Whether to propagate the global table's tags to a replica. Default is `false`. Changes to tags only move in one direction: from global (source) to replica. In other words, tag drift on a replica will not trigger an update. Tag or replica changes on the global table, whether from drift or configuration changes, are propagated to replicas. Changing from `true` to `false` on a subsequent `apply` means replica tags are left as they were, unmanaged, not deleted. */
+    readonly propagateTags?: boolean;
+    /** (Required) Region name of the replica. */
+    readonly regionName: string;
+}
+/**
+ * Properties of a DynamoDB Table
+ *
+ * Use `TableProps` for all table properties
+ */
+export interface TableOptions extends SchemaOptions {
+    /**
+     * The read capacity for the table. Careful if you add Global Secondary Indexes, as
+     * those will share the table's provisioned throughput.
+     *
+     * Can only be provided if billingMode is Provisioned.
+     *
+     * @default 5
+     */
+    readonly readCapacity?: number;
+    /**
+     * The write capacity for the table. Careful if you add Global Secondary Indexes, as
+     * those will share the table's provisioned throughput.
+     *
+     * Can only be provided if billingMode is Provisioned.
+     *
+     * @default 5
+     */
+    readonly writeCapacity?: number;
+    /**
+     * The maximum read request units for the table. Careful if you add Global Secondary Indexes, as
+     * those will share the table's maximum on-demand throughput.
+     *
+     * Can only be provided if billingMode is PAY_PER_REQUEST.
+     *
+     * @default - on-demand throughput is disabled
+     */
+    readonly maxReadRequestUnits?: number;
+    /**
+     * The write request units for the table. Careful if you add Global Secondary Indexes, as
+     * those will share the table's maximum on-demand throughput.
+     *
+     * Can only be provided if billingMode is PAY_PER_REQUEST.
+     *
+     * @default - on-demand throughput is disabled
+     */
+    readonly maxWriteRequestUnits?: number;
+    /**
+     * Specify how you are charged for read and write throughput and how you manage capacity.
+     *
+     * @default PROVISIONED if `replicationRegions` is not specified, PAY_PER_REQUEST otherwise
+     */
+    readonly billingMode?: BillingMode;
+    /**
+     * Whether point-in-time recovery is enabled.
+     * @deprecated use `pointInTimeRecoverySpecification` instead
+     * @default false - point in time recovery is not enabled.
+     */
+    readonly pointInTimeRecovery?: boolean;
+    /**
+     * Whether point-in-time recovery is enabled.
+     *
+     * @default - point in time recovery is not enabled.
+     */
+    readonly pointInTimeRecoverySpecification?: PointInTimeRecoverySpecification;
+    /**
+     * Whether server-side encryption with an AWS managed customer master key is enabled.
+     *
+     * This property cannot be set if `encryption` and/or `encryptionKey` is set.
+     *
+     * @default - The table is encrypted with an encryption key managed by DynamoDB, and you are not charged any fee for using it.
+     *
+     * @deprecated This property is deprecated. In order to obtain the same behavior as
+     * enabling this, set the `encryption` property to `TableEncryption.AWS_MANAGED` instead.
+     */
+    readonly serverSideEncryption?: boolean;
+    /**
+     * Specify the table class.
+     * @default STANDARD
+     */
+    readonly tableClass?: TableClass;
+    /**
+     * Whether server-side encryption with an AWS managed customer master key is enabled.
+     *
+     * This property cannot be set if `serverSideEncryption` is set.
+     *
+     * @default - The table is encrypted with an encryption key managed by DynamoDB, and you are not charged any fee for using it.
+     */
+    readonly encryption?: TableEncryption;
+    /**
+     * External KMS key to use for table encryption.
+     *
+     * This property can only be set if `encryption` is set to `TableEncryption.CUSTOMER_MANAGED`.
+     *
+     * @default - If `encryption` is set to `TableEncryption.CUSTOMER_MANAGED` and this
+     * property is undefined, a new KMS key will be created and associated with this table.
+     * If `encryption` and this property are both undefined, then the table is encrypted with
+     * an encryption key managed by DynamoDB, and you are not charged any fee for using it.
+     */
+    readonly encryptionKey?: kms.IKey;
+    /**
+     * The name of TTL attribute.
+     * @default - TTL is disabled
+     */
+    readonly timeToLiveAttribute?: string;
+    /**
+     * When an item in the table is modified, StreamViewType determines what information
+     * is written to the stream for this table.
+     *
+     * @default - streams are disabled unless `replicationRegions` is specified
+     */
+    readonly stream?: StreamViewType;
+    /**
+     * Regions where replica tables will be created
+     *
+     * @deprecated use replicaSpecification instead
+     * @default - no replica tables are created
+     */
+    readonly replicationRegions?: string[];
+    /**
+     * The specification for replica tables.
+     */
+    readonly replicaSpecification?: DynamodbTableReplica[];
+    /**
+     * Whether CloudWatch contributor insights is enabled.
+     *
+     * @default false
+     */
+    readonly contributorInsightsEnabled?: boolean;
+    /**
+     * Enables deletion protection for the table.
+     *
+     * @default false
+     */
+    readonly deletionProtection?: boolean;
+    /**
+     * The properties of data being imported from the S3 bucket source to the table.
+     *
+     * @default - no data import from the S3 bucket
+     */
+    readonly importSource?: ImportSourceSpecification;
+    /**
+     * Resource policy to assign to table.
+     * Note: `aws_dynamodb_table` does not directly support a resource policy property.
+     * This policy would need to be managed and applied separately, e.g., via `aws_iam_policy` attached to principals.
+     * @default - No resource policy statement
+     */
+    readonly resourcePolicy?: iam.PolicyDocument;
+}
+/**
+ * Properties for a DynamoDB Table
+ */
+export interface TableProps extends TableOptions, AwsConstructProps {
+    /**
+     * Enforces a particular physical table name.
+     * @default <generated>
+     */
+    readonly tableName?: string;
+    /**
+     * Kinesis Data Stream to capture item-level changes for the table.
+     *
+     * @default - no Kinesis Data Stream
+     */
+    readonly kinesisStream?: kinesis.IStream;
+    /**
+     * Kinesis Data Stream approximate creation timestamp precision
+     *
+     * @default ApproximateCreationDateTimePrecision.MICROSECOND
+     */
+    readonly kinesisPrecisionTimestamp?: ApproximateCreationDateTimePrecision;
+}
+/**
+ * Properties for a global secondary index
+ */
+export interface GlobalSecondaryIndexProps extends SecondaryIndexProps, SchemaOptions {
+    /**
+     * The read capacity for the global secondary index.
+     *
+     * Can only be provided if table billingMode is Provisioned or undefined.
+     *
+     * @default 5
+     */
+    readonly readCapacity?: number;
+    /**
+     * The write capacity for the global secondary index.
+     *
+     * Can only be provided if table billingMode is Provisioned or undefined.
+     *
+     * @default 5
+     */
+    readonly writeCapacity?: number;
+    /**
+     * The maximum read request units for the global secondary index.
+     *
+     * Can only be provided if table billingMode is PAY_PER_REQUEST.
+     *
+     * @default - on-demand throughput is disabled
+     */
+    readonly maxReadRequestUnits?: number;
+    /**
+     * The maximum write request units for the global secondary index.
+     *
+     * Can only be provided if table billingMode is PAY_PER_REQUEST.
+     *
+     * @default - on-demand throughput is disabled
+     */
+    readonly maxWriteRequestUnits?: number;
+    /**
+     * Whether CloudWatch contributor insights is enabled for the specified global secondary index.
+     *
+     * @default false
+     */
+    readonly contributorInsightsEnabled?: boolean;
+}
+/**
+ * Reference to a dynamodb table.
+ */
+export interface TableAttributes {
+    /**
+     * The ARN of the dynamodb table.
+     * One of this, or `tableName`, is required.
+     *
+     * @default - no table arn
+     */
+    readonly tableArn?: string;
+    /**
+     * The table name of the dynamodb table.
+     * One of this, or `tableArn`, is required.
+     *
+     * @default - no table name
+     */
+    readonly tableName?: string;
+    /**
+     * The ARN of the table's stream.
+     *
+     * @default - no table stream
+     */
+    readonly tableStreamArn?: string;
+    /**
+     * KMS encryption key, if this table uses a customer-managed encryption key.
+     *
+     * @default - no key
+     */
+    readonly encryptionKey?: kms.IKey;
+    /**
+     * The name of the global indexes set for this Table.
+     * Note that you need to set either this property,
+     * or `localIndexes`,
+     * if you want methods like grantReadData()
+     * to grant permissions for indexes as well as the table itself.
+     *
+     * @default - no global indexes
+     */
+    readonly globalIndexes?: string[];
+    /**
+     * The name of the local indexes set for this Table.
+     * Note that you need to set either this property,
+     * or `globalIndexes`,
+     * if you want methods like grantReadData()
+     * to grant permissions for indexes as well as the table itself.
+     *
+     * @default - no local indexes
+     */
+    readonly localIndexes?: string[];
+    /**
+     * If set to true, grant methods always grant permissions for all indexes.
+     * If false is provided, grant methods grant the permissions
+     * only when `globalIndexes` or `localIndexes` is specified.
+     *
+     * @default - false
+     */
+    readonly grantIndexPermissions?: boolean;
+}
+export declare abstract class TableBase extends AwsConstructBase implements ITable, iam.IAwsConstructWithPolicy {
+    abstract readonly tableArn: string;
+    abstract readonly tableName: string;
+    abstract readonly tableStreamArn?: string;
+    abstract readonly encryptionKey?: kms.IKey;
+    abstract resourcePolicy?: iam.PolicyDocument;
+    protected readonly regionalArns: string[];
+    get outputs(): Record<string, any>;
+    grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
+    grantStream(grantee: iam.IGrantable, ...actions: string[]): iam.Grant;
+    grantReadData(grantee: iam.IGrantable): iam.Grant;
+    grantTableListStreams(grantee: iam.IGrantable): iam.Grant;
+    grantStreamRead(grantee: iam.IGrantable): iam.Grant;
+    grantWriteData(grantee: iam.IGrantable): iam.Grant;
+    grantReadWriteData(grantee: iam.IGrantable): iam.Grant;
+    grantFullAccess(grantee: iam.IGrantable): iam.Grant;
+    addToResourcePolicy(statement: iam.PolicyStatement): iam.AddToResourcePolicyResult;
+    metric(metricName: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    metricConsumedReadCapacityUnits(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    metricConsumedWriteCapacityUnits(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    /** @deprecated use `metricSystemErrorsForOperations`. */
+    metricSystemErrors(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    metricUserErrors(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    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;
+    metricSuccessfulRequestLatency(props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    metricThrottledRequestsForOperation(operation: string, props?: cloudwatch.MetricOptions): cloudwatch.Metric;
+    metricThrottledRequestsForOperations(props?: OperationsMetricOptions): cloudwatch.IMetric;
+    metricSystemErrorsForOperations(props?: SystemErrorsForOperationsMetricOptions): cloudwatch.IMetric;
+    private sumMetricsForOperations;
+    private createMetricsForOperations;
+    protected abstract get hasIndex(): boolean;
+    private combinedGrant;
+    private cannedMetric;
+}
+/**
+ * Provides a DynamoDB table.
+ */
+export declare class Table extends TableBase {
+    /**
+     * Permits an IAM Principal to list all DynamoDB Streams.
+     * @deprecated Use `#grantTableListStreams` for more granular permission
+     * @param grantee The principal (no-op if undefined)
+     */
+    static grantListStreams(grantee: iam.IGrantable): iam.Grant;
+    /**
+     * Creates a Table construct that represents an external table via table name.
+     *
+     * @param scope The parent creating construct (usually `this`).
+     * @param id The construct's name.
+     * @param tableName The table's name.
+     */
+    static fromTableName(scope: Construct, id: string, tableName: string): ITable;
+    /**
+     * Creates a Table construct that represents an external table via table arn.
+     *
+     * @param scope The parent creating construct (usually `this`).
+     * @param id The construct's name.
+     * @param tableArn The table's ARN.
+     */
+    static fromTableArn(scope: Construct, id: string, tableArn: string): ITable;
+    /**
+     * Creates a Table construct that represents an external table.
+     *
+     * @param scope The parent creating construct (usually `this`).
+     * @param id The construct's name.
+     * @param attrs A `TableAttributes` object.
+     */
+    static fromTableAttributes(scope: Construct, id: string, attrs: TableAttributes): ITable;
+    readonly encryptionKey?: kms.IKey;
+    /**
+     * Resource policy to assign to DynamoDB Table.
+     * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-dynamodb-table-resourcepolicy.html
+     * @default - No resource policy statements are added to the created table.
+     */
+    resourcePolicy?: iam.PolicyDocument;
+    readonly tableArn: string;
+    readonly tableName: string;
+    readonly tableStreamArn: string | undefined;
+    private readonly attributeDefinitionsInternal;
+    private readonly globalSecondaryIndexesInternal;
+    private readonly localSecondaryIndexesInternal;
+    private readonly secondaryIndexSchemas;
+    private readonly nonKeyAttributes;
+    private readonly tablePartitionKey;
+    private readonly tableSortKey?;
+    private readonly billingMode;
+    private readonly tableScaling;
+    private readonly indexScaling;
+    private readonly _resource;
+    private readonly _replicas;
+    constructor(scope: Construct, id: string, props: TableProps);
+    addGlobalSecondaryIndex(props: GlobalSecondaryIndexProps): void;
+    addLocalSecondaryIndex(props: LocalSecondaryIndexProps): void;
+    autoScaleReadCapacity(props: EnableScalingProps): IScalableTableAttribute;
+    autoScaleWriteCapacity(props: EnableScalingProps): IScalableTableAttribute;
+    autoScaleGlobalSecondaryIndexReadCapacity(indexName: string, props: EnableScalingProps): IScalableTableAttribute;
+    autoScaleGlobalSecondaryIndexWriteCapacity(indexName: string, props: EnableScalingProps): IScalableTableAttribute;
+    schema(indexName?: string): SchemaOptions;
+    private validateTable;
+    private validateProvisioning;
+    private validateProvisioningGSI;
+    private validateIndexName;
+    private validateNonKeyAttributes;
+    private renderPointInTimeRecovery;
+    private buildIndexProjection;
+    private addKey;
+    private registerAttribute;
+    /**
+     * Creates replica tables
+     *
+     * @param regions regions where to create tables
+     */
+    private renderReplicas;
+    protected get hasIndex(): boolean;
+    private parseEncryption;
+    private renderImportSourceSpecification;
+}