# 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.
---