# API Reference ## Structs ### ApplyResourceTaggersProps Configuration for {@link ConstructResourceTagger.apply}. #### Initializer ```typescript import { ApplyResourceTaggersProps } from 'construct-resource-tagger' const applyResourceTaggersProps: ApplyResourceTaggersProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | scopes | constructs.IConstruct[] | Scopes that receive every tagger. | | taggers | ConstructResourceTagger[] | Aspects registered on each scope, in array order. | --- ##### `scopes`Required ```typescript public readonly scopes: IConstruct[]; ``` - *Type:* constructs.IConstruct[] Scopes that receive every tagger. Must contain at least one scope. --- ##### `taggers`Required ```typescript public readonly taggers: ConstructResourceTagger[]; ``` - *Type:* ConstructResourceTagger[] Aspects registered on each scope, in array order. A later tagger overwrites the same tag key when priorities are equal. Must contain at least one tagger. --- ### ConstructResourceTaggerProps Configuration for {@link ConstructResourceTagger}. #### Initializer ```typescript import { ConstructResourceTaggerProps } from 'construct-resource-tagger' const constructResourceTaggerProps: ConstructResourceTaggerProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | resourceTypes | string[] | CloudFormation type names of target L1 resources (for example, `CfnBucket.CFN_RESOURCE_TYPE_NAME`). Must contain at least one entry. | | tags | ConstructResourceTagValues \| {[ key: string ]: string} | Tag key-value pairs applied to each matching resource, or a function that returns them for that resource. | | overwrite | boolean | When `false`, tag keys that already exist on a resource are left unchanged and only missing keys are added. | | pathFilter | string | Optional construct path prefix matched at `/`-delimited segment boundaries. `"Prod"` matches `Stack/Prod` and `Stack/Prod/Bucket`, but not `Stack/NonProd`. | | pathMatcher | IPathMatcher | Optional matcher that decides whether a construct should be tagged. | | tagProps | aws-cdk-lib.TagProps | Options forwarded to {@link Tags.add} for each applied tag, such as `priority` and `applyToLaunchedInstances`. | --- ##### `resourceTypes`Required ```typescript public readonly resourceTypes: string[]; ``` - *Type:* string[] CloudFormation type names of target L1 resources (for example, `CfnBucket.CFN_RESOURCE_TYPE_NAME`). Must contain at least one entry. --- ##### `tags`Required ```typescript public readonly tags: ConstructResourceTagValues | {[ key: string ]: string}; ``` - *Type:* ConstructResourceTagValues | {[ key: string ]: string} Tag key-value pairs applied to each matching resource, or a function that returns them for that resource. The function runs once per L1 resource that passes the resource type and path filters. --- ##### `overwrite`Optional ```typescript public readonly overwrite: boolean; ``` - *Type:* boolean - *Default:* true When `false`, tag keys that already exist on a resource are left unchanged and only missing keys are added. --- ##### `pathFilter`Optional ```typescript public readonly pathFilter: string; ``` - *Type:* string Optional construct path prefix matched at `/`-delimited segment boundaries. `"Prod"` matches `Stack/Prod` and `Stack/Prod/Bucket`, but not `Stack/NonProd`. Cannot be combined with {@link pathMatcher}. > [PathMatcher.prefix](PathMatcher.prefix) --- ##### `pathMatcher`Optional ```typescript public readonly pathMatcher: IPathMatcher; ``` - *Type:* IPathMatcher Optional matcher that decides whether a construct should be tagged. Use {@link PathMatcher.pattern} for regular expressions, or implement {@link IPathMatcher} for a custom predicate. Cannot be combined with {@link pathFilter}. --- ##### `tagProps`Optional ```typescript public readonly tagProps: TagProps; ``` - *Type:* aws-cdk-lib.TagProps Options forwarded to {@link Tags.add} for each applied tag, such as `priority` and `applyToLaunchedInstances`. > [TagProps](TagProps) --- ### ConstructResourceTagValidatorProps Configuration for {@link ConstructResourceTagValidator}. #### Initializer ```typescript import { ConstructResourceTagValidatorProps } from 'construct-resource-tagger' const constructResourceTagValidatorProps: ConstructResourceTagValidatorProps = { ... } ``` #### Properties | **Name** | **Type** | **Description** | | --- | --- | --- | | requiredTagKeys | string[] | Tag keys that must be present on each matching L1 resource. | | resourceTypes | string[] | CloudFormation type names of target L1 resources (for example, `CfnBucket.CFN_RESOURCE_TYPE_NAME`). Must contain at least one entry. | | pathFilter | string | Optional construct path prefix matched at `/`-delimited segment boundaries. `"Prod"` matches `Stack/Prod` and `Stack/Prod/Bucket`, but not `Stack/NonProd`. | | pathMatcher | IPathMatcher | Optional matcher that decides whether a construct should be checked. | --- ##### `requiredTagKeys`Required ```typescript public readonly requiredTagKeys: string[]; ``` - *Type:* string[] Tag keys that must be present on each matching L1 resource. Values are not checked. Must contain at least one entry. --- ##### `resourceTypes`Required ```typescript public readonly resourceTypes: string[]; ``` - *Type:* string[] CloudFormation type names of target L1 resources (for example, `CfnBucket.CFN_RESOURCE_TYPE_NAME`). Must contain at least one entry. --- ##### `pathFilter`Optional ```typescript public readonly pathFilter: string; ``` - *Type:* string Optional construct path prefix matched at `/`-delimited segment boundaries. `"Prod"` matches `Stack/Prod` and `Stack/Prod/Bucket`, but not `Stack/NonProd`. Cannot be combined with {@link pathMatcher}. > [PathMatcher.prefix](PathMatcher.prefix) --- ##### `pathMatcher`Optional ```typescript public readonly pathMatcher: IPathMatcher; ``` - *Type:* IPathMatcher Optional matcher that decides whether a construct should be checked. Use {@link PathMatcher.pattern} for regular expressions, or implement {@link IPathMatcher} for a custom predicate. Cannot be combined with {@link pathFilter}. --- ### ConstructResourceTagValues Builds tag key-value pairs for one matching construct. Stack name, construct ID, and path are available on `node`. #### Initializer ```typescript import { ConstructResourceTagValues } from 'construct-resource-tagger' const constructResourceTagValues: ConstructResourceTagValues = { ... } ``` ## Classes ### ConstructResourceTagger - *Implements:* aws-cdk-lib.IAspect CDK aspect that applies tags to L1 resources matching configured CloudFormation resource types. Register with `Aspects.of(scope).add(new ConstructResourceTagger({ ... }))` to tag matching {@link CfnResource} instances during synthesis. {@link ConstructResourceTagger.apply} registers several taggers on one or more scopes. #### Initializers ```typescript import { ConstructResourceTagger } from 'construct-resource-tagger' new ConstructResourceTagger(props: ConstructResourceTaggerProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | props | ConstructResourceTaggerProps | - Resource types, tags, and optional filtering / TagProps options. | --- ##### `props`Required - *Type:* ConstructResourceTaggerProps Resource types, tags, and optional filtering / TagProps options. --- #### Methods | **Name** | **Description** | | --- | --- | | visit | Applies configured tags when `node` is an L1 resource whose CloudFormation type matches a configured resource type and optionally matches `pathFilter` or `pathMatcher`. | --- ##### `visit` ```typescript public visit(node: IConstruct): void ``` Applies configured tags when `node` is an L1 resource whose CloudFormation type matches a configured resource type and optionally matches `pathFilter` or `pathMatcher`. When `tags` is a function, it is called for that resource. Respects `overwrite` and forwards `tagProps` to {@link Tags.add}. ###### `node`Required - *Type:* constructs.IConstruct Construct visited during aspect traversal. --- #### Static Functions | **Name** | **Description** | | --- | --- | | apply | Registers each tagger on every scope, preserving tagger order. | --- ##### `apply` ```typescript import { ConstructResourceTagger } from 'construct-resource-tagger' ConstructResourceTagger.apply(props: ApplyResourceTaggersProps) ``` Registers each tagger on every scope, preserving tagger order. ###### `props`Required - *Type:* ApplyResourceTaggersProps Scopes and the taggers to register on each of them. --- ### ConstructResourceTagValidator - *Implements:* aws-cdk-lib.IAspect CDK aspect that reports missing required tag keys on matching L1 resources. Register with `Aspects.of(scope).add(new ConstructResourceTagValidator({ ... }))` after taggers when those taggers should satisfy the check. This aspect does not apply tags. A missing key, or tags that cannot be read, adds an error annotation and synthesis fails. #### Initializers ```typescript import { ConstructResourceTagValidator } from 'construct-resource-tagger' new ConstructResourceTagValidator(props: ConstructResourceTagValidatorProps) ``` | **Name** | **Type** | **Description** | | --- | --- | --- | | props | ConstructResourceTagValidatorProps | - Resource types, required tag keys, and optional path filters. | --- ##### `props`Required - *Type:* ConstructResourceTagValidatorProps Resource types, required tag keys, and optional path filters. --- #### Methods | **Name** | **Description** | | --- | --- | | visit | Reports missing required tag keys when `node` is an L1 resource whose CloudFormation type matches a configured resource type and optionally matches `pathFilter` or `pathMatcher`. | --- ##### `visit` ```typescript public visit(node: IConstruct): void ``` Reports missing required tag keys when `node` is an L1 resource whose CloudFormation type matches a configured resource type and optionally matches `pathFilter` or `pathMatcher`. Tags that cannot be read add an error annotation. Other constructs are left unchanged. ###### `node`Required - *Type:* constructs.IConstruct Construct visited during aspect traversal. --- ### PathMatcher - *Implements:* IPathMatcher Built-in {@link IPathMatcher} implementations for construct path matching. #### Methods | **Name** | **Description** | | --- | --- | | matches | Returns whether the aspect should act on `node`. | --- ##### `matches` ```typescript public matches(node: IConstruct): boolean ``` Returns whether the aspect should act on `node`. ###### `node`Required - *Type:* constructs.IConstruct Construct visited during aspect traversal. --- #### Static Functions | **Name** | **Description** | | --- | --- | | pattern | Match when the construct path matches a JavaScript regular expression. | | prefix | Match when `prefix` appears as a contiguous sequence of construct path segments. | --- ##### `pattern` ```typescript import { PathMatcher } from 'construct-resource-tagger' PathMatcher.pattern(pattern: string) ``` Match when the construct path matches a JavaScript regular expression. ###### `pattern`Required - *Type:* string Regular expression source tested against `node.path`. --- ##### `prefix` ```typescript import { PathMatcher } from 'construct-resource-tagger' PathMatcher.prefix(prefix: string) ``` Match when `prefix` appears as a contiguous sequence of construct path segments. `"Prod"` matches `Stack/Prod` and `Stack/Prod/Bucket`, but not `Stack/NonProd`. ###### `prefix`Required - *Type:* string Path segments to match (for example `Prod` or `App/Prod`). --- ## Protocols ### IPathMatcher - *Implemented By:* PathMatcher, IPathMatcher Decides whether a construct is selected based on its location in the construct tree. {@link ConstructResourceTagger } applies tags to a selected construct. {@link ConstructResourceTagValidator } checks required tag keys on a selected construct. #### Methods | **Name** | **Description** | | --- | --- | | matches | Returns whether the aspect should act on `node`. | --- ##### `matches` ```typescript public matches(node: IConstruct): boolean ``` Returns whether the aspect should act on `node`. ###### `node`Required - *Type:* constructs.IConstruct Construct visited during aspect traversal. ---