cdktn 0.25.0-pre.26 → 0.25.0-pre.28

package/.jsii

@@ -1651,7 +1651,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 193
+        "line": 209
       },
       "name": "AssetPackaging",
       "properties": [
@@ -1664,7 +1664,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 202
+            "line": 218
           },
           "name": "DIRECTORY",
           "static": true,
@@ -1681,7 +1681,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 197
+            "line": 213
           },
           "name": "FILE",
           "static": true,
@@ -1698,7 +1698,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 207
+            "line": 223
           },
           "name": "ZIP",
           "static": true,
@@ -1709,6 +1709,242 @@
       ],
       "symbolId": "src/assets:AssetPackaging"
     },
+    "cdktn.AssetStaging": {
+      "assembly": "cdktn",
+      "base": "constructs.Construct",
+      "docs": {
+        "remarks": "Hashing happens eagerly in the constructor; staging the content to\n`targetPath` only happens when `stage()` is called, which callers do from\ntheir own `onSynthesize` hook. This keeps the filesystem side effect in the\none window where it is safe to run, and keeps this class skippable once a\nbundler is introduced.\n\n`SOURCE` and `OUTPUT` compute identically here: without a bundler, the\n\"output\" of an asset is its source verbatim. A future bundler changes what\n`OUTPUT` hashes, not this class.\n\nThe source-tree walk behind `SOURCE`/`OUTPUT` is cached per synth (see\n{@link hashCachesByRoot}), so referencing the same asset from more than one\nresource or stack hashes it once. `ASSET_HASH_SALT_CONTEXT_KEY` folds an\napp-wide value into every computed hash, for bulk cache-busting across an\nentire tree rather than one asset's `extraHash`.",
+        "stability": "experimental",
+        "summary": "Resolves an asset's identity (`SOURCE`/`OUTPUT`/`CUSTOM` hashing, with `exclude`/`extraHash`) and stages it to disk."
+      },
+      "fqn": "cdktn.AssetStaging",
+      "initializer": {
+        "docs": {
+          "stability": "experimental"
+        },
+        "locationInModule": {
+          "filename": "src/asset-staging.ts",
+          "line": 125
+        },
+        "parameters": [
+          {
+            "name": "scope",
+            "type": {
+              "fqn": "constructs.Construct"
+            }
+          },
+          {
+            "name": "id",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "name": "props",
+            "type": {
+              "fqn": "cdktn.AssetStagingOptions"
+            }
+          }
+        ]
+      },
+      "interfaces": [
+        "cdktn.IAsset"
+      ],
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/asset-staging.ts",
+        "line": 116
+      },
+      "methods": [
+        {
+          "docs": {
+            "remarks": "Called from the owning\nconstruct's `onSynthesize` hook, once the target path is known.",
+            "stability": "experimental",
+            "summary": "Write the staged content to `targetPath`."
+          },
+          "locationInModule": {
+            "filename": "src/asset-staging.ts",
+            "line": 219
+          },
+          "name": "stage",
+          "parameters": [
+            {
+              "docs": {
+                "summary": "- path the packaged result should be written to."
+              },
+              "name": "targetPath",
+              "type": {
+                "primitive": "string"
+              }
+            }
+          ]
+        }
+      ],
+      "name": "AssetStaging",
+      "properties": [
+        {
+          "docs": {
+            "remarks": "As this is a plain string, it\ncan be used in construct IDs in order to enforce creation of a new resource when the content\nhash has changed.",
+            "stability": "experimental",
+            "summary": "A hash of this asset, which is available at construction time."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/asset-staging.ts",
+            "line": 123
+          },
+          "name": "assetHash",
+          "overrides": "cdktn.IAsset",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/asset-staging.ts",
+            "line": 122
+          },
+          "name": "isDirectory",
+          "type": {
+            "primitive": "boolean"
+          }
+        },
+        {
+          "docs": {
+            "stability": "experimental"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/asset-staging.ts",
+            "line": 121
+          },
+          "name": "packaging",
+          "type": {
+            "fqn": "cdktn.IAssetPackaging"
+          }
+        }
+      ],
+      "symbolId": "src/asset-staging:AssetStaging"
+    },
+    "cdktn.AssetStagingOptions": {
+      "assembly": "cdktn",
+      "datatype": true,
+      "docs": {
+        "stability": "experimental",
+        "summary": "Options for {@link AssetStaging}."
+      },
+      "fqn": "cdktn.AssetStagingOptions",
+      "interfaces": [
+        "cdktn.AssetOptions"
+      ],
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/asset-staging.ts",
+        "line": 56
+      },
+      "name": "AssetStagingOptions",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "The caller decides this\n(e.g. from its own `AssetType`) — `AssetStaging` never infers or changes\nit based on `exclude`/`extraHash`.",
+            "stability": "experimental",
+            "summary": "How the staged result is produced and shaped."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/asset-staging.ts",
+            "line": 68
+          },
+          "name": "packaging",
+          "type": {
+            "fqn": "cdktn.IAssetPackaging"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Resolving a relative path\nagainst `cdktf.json` is the caller's responsibility.",
+            "stability": "experimental",
+            "summary": "Absolute path to the source file or directory."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/asset-staging.ts",
+            "line": 61
+          },
+          "name": "sourcePath",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- nothing is excluded",
+            "remarks": "Cannot be combined with\n`ignoreStrategy`, which replaces this matcher rather than layering on\ntop of it.",
+            "stability": "experimental",
+            "summary": "Paths to exclude, relative to `sourcePath`."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/asset-staging.ts",
+            "line": 77
+          },
+          "name": "exclude",
+          "optional": true,
+          "type": {
+            "collection": {
+              "elementtype": {
+                "primitive": "string"
+              },
+              "kind": "array"
+            }
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- no extra hash",
+            "stability": "experimental",
+            "summary": "Extra information to fold into the hash (e.g. build instructions and other inputs)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/asset-staging.ts",
+            "line": 93
+          },
+          "name": "extraHash",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- `exclude` is used with the built-in matcher",
+            "stability": "experimental",
+            "summary": "Exclusion matching, for callers that need `.gitignore` / `.dockerignore` parity rather than the built-in exact-path / suffix / directory matcher."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/asset-staging.ts",
+            "line": 85
+          },
+          "name": "ignoreStrategy",
+          "optional": true,
+          "type": {
+            "fqn": "cdktn.IIgnoreStrategy"
+          }
+        }
+      ],
+      "symbolId": "src/asset-staging:AssetStagingOptions"
+    },
     "cdktn.AssetType": {
       "assembly": "cdktn",
       "docs": {
@@ -1718,7 +1954,7 @@
       "kind": "enum",
       "locationInModule": {
         "filename": "src/terraform-asset.ts",
-        "line": 49
+        "line": 63
       },
       "members": [
         {
@@ -11866,7 +12102,7 @@
           },
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 110
+            "line": 123
           },
           "name": "pack",
           "parameters": [
@@ -11900,6 +12136,23 @@
             "primitive": "string"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "`hashPath`'s `archive` frame\nmust agree with this or the hash and the artifact describe different\nfile sets.\n\n`ZipPackaging` sets this because `archiveSync` never emits ZIP directory\nentries. A directory-producing packaging that mirrors the source tree\n(e.g. `DirectoryPackaging`) leaves this false, since its directories are\nreal entries on disk.",
+            "stability": "experimental",
+            "summary": "Whether `pack` emits an artifact with no directory entries of its own — only the ignore-strategy-aware source walk."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 116
+          },
+          "name": "omitsDirectoryEntries",
+          "type": {
+            "primitive": "boolean"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -17040,7 +17293,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 120
+        "line": 133
       },
       "name": "PackOptions",
       "properties": [
@@ -17053,7 +17306,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 124
+            "line": 137
           },
           "name": "source",
           "type": {
@@ -17069,7 +17322,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 129
+            "line": 142
           },
           "name": "target",
           "type": {
@@ -17087,7 +17340,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 138
+            "line": 151
           },
           "name": "ignoreStrategy",
           "optional": true,
@@ -20206,7 +20459,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 220
+        "line": 236
       },
       "name": "StagedAsset",
       "properties": [
@@ -20220,7 +20473,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 226
+            "line": 242
           },
           "name": "assetHash",
           "type": {
@@ -20237,7 +20490,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 239
+            "line": 255
           },
           "name": "isDirectory",
           "type": {
@@ -20253,7 +20506,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 231
+            "line": 247
           },
           "name": "path",
           "type": {
@@ -21738,7 +21991,7 @@
         },
         "locationInModule": {
           "filename": "src/terraform-asset.ts",
-          "line": 88
+          "line": 104
         },
         "parameters": [
           {
@@ -21767,7 +22020,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/terraform-asset.ts",
-        "line": 73
+        "line": 87
       },
       "name": "TerraformAsset",
       "properties": [
@@ -21780,7 +22033,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 77
+            "line": 91
           },
           "name": "assetHash",
           "overrides": "cdktn.IAsset",
@@ -21796,7 +22049,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 206
+            "line": 191
           },
           "name": "fileName",
           "type": {
@@ -21811,7 +22064,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 193
+            "line": 178
           },
           "name": "path",
           "type": {
@@ -21824,7 +22077,7 @@
           },
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 79
+            "line": 93
           },
           "name": "type",
           "type": {
@@ -21844,7 +22097,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/terraform-asset.ts",
-        "line": 27
+        "line": 23
       },
       "name": "TerraformAssetConfig",
       "properties": [
@@ -21856,7 +22109,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 29
+            "line": 25
           },
           "name": "path",
           "type": {
@@ -21871,7 +22124,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 33
+            "line": 29
           },
           "name": "assetHash",
           "optional": true,
@@ -21883,14 +22136,14 @@
           "abstract": true,
           "docs": {
             "default": "AssetHashType.SOURCE",
-            "remarks": "`SOURCE` (the default) hashes the source path. `CUSTOM` uses the\n`assetHash` value verbatim and requires it to be set. `OUTPUT` is not\nsupported yet — there is no bundling step to produce an output to hash —\nand throws if requested.\n\nIf `assetHash` is set, this must be `undefined` or `AssetHashType.CUSTOM`.",
+            "remarks": "`SOURCE` (the default) hashes the source path. `CUSTOM` uses the\n`assetHash` value verbatim and requires it to be set. `OUTPUT` also\nhashes the source path today — there is no bundling step yet, so the\n\"output\" of an asset is its source verbatim — but will hash the\nbundler's output once bundling is introduced.\n\nIf `assetHash` is set, this must be `undefined` or `AssetHashType.CUSTOM`.",
             "stability": "experimental",
             "summary": "How the `assetHash` is derived."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 46
+            "line": 43
           },
           "name": "assetHashType",
           "optional": true,
@@ -21898,6 +22151,48 @@
             "fqn": "cdktn.AssetHashType"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- nothing is excluded",
+            "remarks": "See\n`AssetStagingOptions.exclude` for the accepted forms. Both the computed\nhash and the staged/packed content honor the exclusion.",
+            "stability": "experimental",
+            "summary": "Paths to exclude from the asset, relative to `path`."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/terraform-asset.ts",
+            "line": 52
+          },
+          "name": "exclude",
+          "optional": true,
+          "type": {
+            "collection": {
+              "elementtype": {
+                "primitive": "string"
+              },
+              "kind": "array"
+            }
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- no extra hash",
+            "stability": "experimental",
+            "summary": "Extra information to fold into the hash (e.g. build instructions and other inputs)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/terraform-asset.ts",
+            "line": 60
+          },
+          "name": "extraHash",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -21906,7 +22201,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 31
+            "line": 27
           },
           "name": "type",
           "optional": true,
@@ -31780,6 +32075,6 @@
       "symbolId": "src/testing/matchers:TerraformConstructor"
     }
   },
-  "version": "0.25.0-pre.26",
-  "fingerprint": "zxbxP84zHSf7HLXFuqzS5VoroDpY4C8yyF3sdy8C8so="
+  "version": "0.25.0-pre.28",
+  "fingerprint": "8F6kUDC80Mk1XFsHM4hivho6OoXcWa8912NpmyqZuW0="
 }

package/lib/annotations.js

@@ -14,7 +14,7 @@ exports.DISABLE_STACK_TRACE_IN_METADATA = "@cdktf/disable_stack_trace_in_metadat
  */
 class Annotations {
     scope;
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.Annotations", version: "0.25.0-pre.26" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.Annotations", version: "0.25.0-pre.28" };
     /**
      * Returns the annotations API for a construct scope.
      * @param scope The scope

package/lib/app.js

@@ -51,7 +51,7 @@ exports.CONTEXT_ENV = "CDKTF_CONTEXT_JSON";
  * Represents a cdktn application.
  */
 class App extends constructs_1.Construct {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.App", version: "0.25.0-pre.26" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.App", version: "0.25.0-pre.28" };
     /**
      * The output directory into which resources will be synthesized.
      */

package/lib/aspect.js

@@ -8,7 +8,7 @@ const ASPECTS_SYMBOL = Symbol("cdktf-aspects");
  * synthesis.
  */
 class Aspects {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.Aspects", version: "0.25.0-pre.26" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.Aspects", version: "0.25.0-pre.28" };
     /**
      * Returns the `Aspects` object associated with a construct scope.
      * @param scope The scope for which these aspects will apply.

package/lib/asset-hash.js

@@ -51,7 +51,7 @@ const errors_1 = require("./errors");
  * staged copy; this is the identity half without the staging half.
  */
 class AssetHash {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.AssetHash", version: "0.25.0-pre.26" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "cdktn.AssetHash", version: "0.25.0-pre.28" };
     /**
      * Content hash of a file or directory, without staging it.
      *

package/lib/asset-staging.d.ts

@@ -0,0 +1,83 @@
+import { Construct } from "constructs";
+import { AssetOptions, IAsset, IAssetPackaging } from "./assets";
+import { IIgnoreStrategy } from "./ignore-strategy";
+/**
+ * Context key for a value folded into every computed asset hash in the
+ * construct tree, alongside `extraHash`. A bulk cache-busting escape hatch —
+ * `extraHash` is scoped to one asset, this is scoped to the whole app.
+ */
+export declare const ASSET_HASH_SALT_CONTEXT_KEY = "cdktn:assetHashSalt";
+/**
+ * Options for {@link AssetStaging}.
+ */
+export interface AssetStagingOptions extends AssetOptions {
+    /**
+     * Absolute path to the source file or directory. Resolving a relative path
+     * against `cdktf.json` is the caller's responsibility.
+     */
+    readonly sourcePath: string;
+    /**
+     * How the staged result is produced and shaped. The caller decides this
+     * (e.g. from its own `AssetType`) — `AssetStaging` never infers or changes
+     * it based on `exclude`/`extraHash`.
+     */
+    readonly packaging: IAssetPackaging;
+    /**
+     * Paths to exclude, relative to `sourcePath`. Cannot be combined with
+     * `ignoreStrategy`, which replaces this matcher rather than layering on
+     * top of it.
+     *
+     * @default - nothing is excluded
+     */
+    readonly exclude?: string[];
+    /**
+     * Exclusion matching, for callers that need `.gitignore` / `.dockerignore`
+     * parity rather than the built-in exact-path / suffix / directory matcher.
+     *
+     * @default - `exclude` is used with the built-in matcher
+     */
+    readonly ignoreStrategy?: IIgnoreStrategy;
+    /**
+     * Extra information to fold into the hash (e.g. build instructions and
+     * other inputs).
+     *
+     * @default - no extra hash
+     */
+    readonly extraHash?: string;
+}
+/**
+ * Resolves an asset's identity (`SOURCE`/`OUTPUT`/`CUSTOM` hashing, with
+ * `exclude`/`extraHash`) and stages it to disk.
+ *
+ * Hashing happens eagerly in the constructor; staging the content to
+ * `targetPath` only happens when `stage()` is called, which callers do from
+ * their own `onSynthesize` hook. This keeps the filesystem side effect in the
+ * one window where it is safe to run, and keeps this class skippable once a
+ * bundler is introduced.
+ *
+ * `SOURCE` and `OUTPUT` compute identically here: without a bundler, the
+ * "output" of an asset is its source verbatim. A future bundler changes what
+ * `OUTPUT` hashes, not this class.
+ *
+ * The source-tree walk behind `SOURCE`/`OUTPUT` is cached per synth (see
+ * {@link hashCachesByRoot}), so referencing the same asset from more than one
+ * resource or stack hashes it once. `ASSET_HASH_SALT_CONTEXT_KEY` folds an
+ * app-wide value into every computed hash, for bulk cache-busting across an
+ * entire tree rather than one asset's `extraHash`.
+ */
+export declare class AssetStaging extends Construct implements IAsset {
+    private readonly sourcePath;
+    private readonly ignoreStrategy;
+    private readonly hashCache;
+    readonly packaging: IAssetPackaging;
+    readonly isDirectory: boolean;
+    readonly assetHash: string;
+    constructor(scope: Construct, id: string, props: AssetStagingOptions);
+    private resolveAssetHash;
+    /**
+     * Write the staged content to `targetPath`. Called from the owning
+     * construct's `onSynthesize` hook, once the target path is known.
+     * @param targetPath - path the packaged result should be written to
+     */
+    stage(targetPath: string): void;
+}