cdktn 0.25.0-pre.38 → 0.25.0-pre.39

package/.jsii

@@ -1651,7 +1651,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 209
+        "line": 220
       },
       "name": "AssetPackaging",
       "properties": [
@@ -1664,7 +1664,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 218
+            "line": 229
           },
           "name": "DIRECTORY",
           "static": true,
@@ -1681,7 +1681,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 213
+            "line": 224
           },
           "name": "FILE",
           "static": true,
@@ -1698,7 +1698,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 223
+            "line": 234
           },
           "name": "ZIP",
           "static": true,
@@ -1713,9 +1713,9 @@
       "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`.",
+        "remarks": "The hash is available immediately after construction; the filesystem write\nis deferred to `stage()`, the one window where it is safe. Hashing is\ncached per synth (see {@link hashCachesByRoot}) so an asset referenced from\nseveral places is walked once. Without a bundler, `SOURCE` and `OUTPUT` both\nhash the source; with one they diverge, as `AssetStagingOptions.bundler`\ndescribes.",
         "stability": "experimental",
-        "summary": "Resolves an asset's identity (`SOURCE`/`OUTPUT`/`CUSTOM` hashing, with `exclude`/`extraHash`) and stages it to disk."
+        "summary": "Resolves an asset's identity and stages its content to disk."
       },
       "fqn": "cdktn.AssetStaging",
       "initializer": {
@@ -1724,7 +1724,7 @@
         },
         "locationInModule": {
           "filename": "src/asset-staging.ts",
-          "line": 125
+          "line": 220
         },
         "parameters": [
           {
@@ -1753,25 +1753,22 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/asset-staging.ts",
-        "line": 116
+        "line": 193
       },
       "methods": [
         {
           "docs": {
-            "remarks": "Called from the owning\nconstruct's `onSynthesize` hook, once the target path is known.",
+            "remarks": "Called from the owning construct's `onSynthesize` hook. Without a bundler\nthe source is packaged verbatim; with one, the bundler's output is, built\neagerly for `OUTPUT` hashing or deferred to here for `SOURCE`.",
             "stability": "experimental",
-            "summary": "Write the staged content to `targetPath`."
+            "summary": "Stage the asset's content to `targetPath`."
           },
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 219
+            "line": 420
           },
           "name": "stage",
           "parameters": [
             {
-              "docs": {
-                "summary": "- path the packaged result should be written to."
-              },
               "name": "targetPath",
               "type": {
                 "primitive": "string"
@@ -1791,7 +1788,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 123
+            "line": 218
           },
           "name": "assetHash",
           "overrides": "cdktn.IAsset",
@@ -1806,7 +1803,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 122
+            "line": 217
           },
           "name": "isDirectory",
           "type": {
@@ -1820,7 +1817,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 121
+            "line": 216
           },
           "name": "packaging",
           "type": {
@@ -1844,7 +1841,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/asset-staging.ts",
-        "line": 56
+        "line": 123
       },
       "name": "AssetStagingOptions",
       "properties": [
@@ -1858,7 +1855,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 68
+            "line": 135
           },
           "name": "packaging",
           "type": {
@@ -1875,13 +1872,50 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 61
+            "line": 128
           },
           "name": "sourcePath",
           "type": {
             "primitive": "string"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- the source is staged verbatim, with no build step",
+            "remarks": "Under the default `SOURCE` hashing the build is deferred to `stage()` and\nstays skippable; `OUTPUT` hashing builds eagerly at construction time to\nhash the artifact, forgoing skippability. A bundler always produces a\ndirectory, so single-file packaging (`AssetType.FILE`) is rejected.",
+            "stability": "experimental",
+            "summary": "A bundler that builds the source into an artifact before staging."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/asset-staging.ts",
+            "line": 172
+          },
+          "name": "bundler",
+          "optional": true,
+          "type": {
+            "fqn": "cdktn.IAssetBundler"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- the staging construct's own id",
+            "stability": "experimental",
+            "summary": "Identifier used in error messages, so they name the user-facing construct (e.g. the `TerraformAsset`) rather than this internal staging child."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/asset-staging.ts",
+            "line": 180
+          },
+          "name": "displayName",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -1893,7 +1927,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 77
+            "line": 144
           },
           "name": "exclude",
           "optional": true,
@@ -1916,7 +1950,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 93
+            "line": 160
           },
           "name": "extraHash",
           "optional": true,
@@ -1934,7 +1968,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/asset-staging.ts",
-            "line": 85
+            "line": 152
           },
           "name": "ignoreStrategy",
           "optional": true,
@@ -1954,7 +1988,7 @@
       "kind": "enum",
       "locationInModule": {
         "filename": "src/terraform-asset.ts",
-        "line": 63
+        "line": 76
       },
       "members": [
         {
@@ -3386,6 +3420,177 @@
       ],
       "symbolId": "src/complex-computed-list:BooleanMapMap"
     },
+    "cdktn.BundleOptions": {
+      "assembly": "cdktn",
+      "datatype": true,
+      "docs": {
+        "remarks": "A struct rather than positional parameters: adding a field is additive,\nadding a method parameter is not, and `bundle` is called through JSII where\nthat distinction is a breaking-change boundary.",
+        "stability": "experimental",
+        "summary": "Options handed to an {@link IAssetBundler} when it runs."
+      },
+      "fqn": "cdktn.BundleOptions",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/assets.ts",
+        "line": 246
+      },
+      "name": "BundleOptions",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "The bundler produces its output here (or in a subdirectory) and\nreturns the directory that holds the finished artifact — see\n{@link IAssetBundler.bundle}.",
+            "stability": "experimental",
+            "summary": "A scratch directory the bundler may write into, owned and created by the caller."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 263
+          },
+          "name": "outputDir",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Exclusions (`exclude` / `ignoreStrategy`) are already applied: when any\nare configured this points at a filtered copy, not the original tree, so\nthe bundler reads exactly the file set the asset hash was taken over.",
+            "stability": "experimental",
+            "summary": "Absolute path to the asset's source file or directory. The bundler reads from here and must not modify it."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 255
+          },
+          "name": "source",
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "src/assets:BundleOptions"
+    },
+    "cdktn.BundlerKey": {
+      "assembly": "cdktn",
+      "docs": {
+        "example": "const key = BundlerKey.of(\"docker\", image, command)\n  .withEnv({ NODE_ENV: nodeEnv })\n  .toString();",
+        "remarks": "A `bundlerKey` has to serialize everything that can move a build's output;\ndone ad hoc, every bundler invents its own delimiter and forgets an input\ndifferently. This gives the convention one implementation: parts are joined\nwith a separator that is escaped where it appears in a value, so distinct\ninputs can never collide into the same key (`[\"a:b\", \"c\"]` and\n`[\"a\", \"b:c\"]` stay different).",
+        "stability": "experimental",
+        "summary": "Builds an {@link IAssetBundler.bundlerKey} from an ordered set of parts."
+      },
+      "fqn": "cdktn.BundlerKey",
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/assets.ts",
+        "line": 333
+      },
+      "methods": [
+        {
+          "docs": {
+            "remarks": "Order is significant: it is part of what the key identifies.",
+            "stability": "experimental",
+            "summary": "Start a key from an ordered list of parts."
+          },
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 339
+          },
+          "name": "of",
+          "parameters": [
+            {
+              "name": "parts",
+              "type": {
+                "primitive": "string"
+              },
+              "variadic": true
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "cdktn.BundlerKey"
+            }
+          },
+          "static": true,
+          "variadic": true
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Append parts, returning a new key."
+          },
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 352
+          },
+          "name": "add",
+          "parameters": [
+            {
+              "name": "parts",
+              "type": {
+                "primitive": "string"
+              },
+              "variadic": true
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "cdktn.BundlerKey"
+            }
+          },
+          "variadic": true
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Render the collected parts to the string passed as `bundlerKey`."
+          },
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 370
+          },
+          "name": "toString",
+          "returns": {
+            "type": {
+              "primitive": "string"
+            }
+          }
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Append `key=value` parts for a record, sorted by key so the result does not depend on property order."
+          },
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 360
+          },
+          "name": "withEnv",
+          "parameters": [
+            {
+              "name": "entries",
+              "type": {
+                "collection": {
+                  "elementtype": {
+                    "primitive": "string"
+                  },
+                  "kind": "map"
+                }
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "fqn": "cdktn.BundlerKey"
+            }
+          }
+        }
+      ],
+      "name": "BundlerKey",
+      "symbolId": "src/assets:BundlerKey"
+    },
     "cdktn.CloudBackend": {
       "assembly": "cdktn",
       "base": "cdktn.TerraformBackend",
@@ -12080,6 +12285,71 @@
       ],
       "symbolId": "src/assets:IAsset"
     },
+    "cdktn.IAssetBundler": {
+      "assembly": "cdktn",
+      "docs": {
+        "remarks": "This is the extension point for asset bundling: core ships no bundler.\nDocker, esbuild, pip, `go build`, and similar are an open-ended set that\nis not cloud-specific, so each lives in its own package and implements this\none interface — the same way {@link IIgnoreStrategy} lets richer exclusion\nlive outside core without core taking on a glob parser. A third party\ndevelops a bundler by implementing this interface and publishing it as a\npackage; users pass an instance via the consuming construct's `bundler`\noption.\n\n`bundle` runs during the owning construct's `onSynthesize` hook and may\ntouch the filesystem. Deferring it there keeps it skippable when the asset's\nstack is not being synthesized, which holds as long as the hash is taken\nover the source rather than the built output.",
+        "stability": "experimental",
+        "summary": "Transforms a source tree into a built artifact. Runs at synth, before the output is packaged and staged."
+      },
+      "fqn": "cdktn.IAssetBundler",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/assets.ts",
+        "line": 284
+      },
+      "methods": [
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Implementations write into `options.outputDir` and return it or a\nsubdirectory, never writing back to `options.source`. The returned\ndirectory is then packaged as an unbundled source directory would be.\nReturning a file, or a path that does not exist, is rejected — the\ncontract is a directory, and packaging always treats the result as one.",
+            "stability": "experimental",
+            "summary": "Produce the artifact and return the directory holding it."
+          },
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 315
+          },
+          "name": "bundle",
+          "parameters": [
+            {
+              "name": "options",
+              "type": {
+                "fqn": "cdktn.BundleOptions"
+              }
+            }
+          ],
+          "returns": {
+            "type": {
+              "primitive": "string"
+            }
+          }
+        }
+      ],
+      "name": "IAssetBundler",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- the build does not contribute to the hash",
+            "remarks": "The source tree alone cannot see the build, so swapping a `node:18` base\nimage for `node:20` would otherwise leave identity unchanged. A value\ncapturing the build (e.g. `docker:<image>:<command>`) closes that gap.\n\nUnder `SOURCE` hashing this is the only channel by which the build reaches\nidentity, so it must serialize every input that can move the output —\nbase image, command, tool version, environment, arguments. Anything left\nout means a changed build silently reuses a stale artifact. {@link * BundlerKey} builds one from an ordered set of parts so the format is not\nreinvented per bundler.\n\nMirrors {@link IIgnoreStrategy.cacheKey}: omit it when the build cannot be\nsummarized as a string, and fall back to `extraHash`.",
+            "stability": "experimental",
+            "summary": "A value identifying the build, folded into the asset hash."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 304
+          },
+          "name": "bundlerKey",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "src/assets:IAssetBundler"
+    },
     "cdktn.IAssetPackaging": {
       "assembly": "cdktn",
       "docs": {
@@ -12098,18 +12368,15 @@
           "abstract": true,
           "docs": {
             "stability": "experimental",
-            "summary": "Perform the staging transformation, writing the packaged result to `options.target`."
+            "summary": "Write the packaged result to `options.target`."
           },
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 123
+            "line": 131
           },
           "name": "pack",
           "parameters": [
             {
-              "docs": {
-                "summary": "- see {@link PackOptions}."
-              },
               "name": "options",
               "type": {
                 "fqn": "cdktn.PackOptions"
@@ -12120,6 +12387,23 @@
       ],
       "name": "IAssetPackaging",
       "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Independent of `producesDirectory` and `omitsDirectoryEntries`, both of\nwhich describe the output: a `tar.gz` packaging takes a directory source\nyet emits a single file. Bundler output is always a directory, so a\npackaging that is `false` here cannot stage it.",
+            "stability": "experimental",
+            "summary": "Whether `pack` accepts a directory as its `source`."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/assets.ts",
+            "line": 113
+          },
+          "name": "acceptsDirectorySource",
+          "type": {
+            "primitive": "boolean"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -12146,7 +12430,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 116
+            "line": 126
           },
           "name": "omitsDirectoryEntries",
           "type": {
@@ -17293,7 +17577,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 133
+        "line": 141
       },
       "name": "PackOptions",
       "properties": [
@@ -17306,7 +17590,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 137
+            "line": 145
           },
           "name": "source",
           "type": {
@@ -17322,7 +17606,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 142
+            "line": 150
           },
           "name": "target",
           "type": {
@@ -17340,7 +17624,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 151
+            "line": 159
           },
           "name": "ignoreStrategy",
           "optional": true,
@@ -20459,7 +20743,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/assets.ts",
-        "line": 236
+        "line": 383
       },
       "name": "StagedAsset",
       "properties": [
@@ -20473,7 +20757,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 242
+            "line": 389
           },
           "name": "assetHash",
           "type": {
@@ -20490,7 +20774,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 255
+            "line": 402
           },
           "name": "isDirectory",
           "type": {
@@ -20506,7 +20790,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/assets.ts",
-            "line": 247
+            "line": 394
           },
           "name": "path",
           "type": {
@@ -21991,7 +22275,7 @@
         },
         "locationInModule": {
           "filename": "src/terraform-asset.ts",
-          "line": 104
+          "line": 117
         },
         "parameters": [
           {
@@ -22020,7 +22304,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/terraform-asset.ts",
-        "line": 87
+        "line": 100
       },
       "name": "TerraformAsset",
       "properties": [
@@ -22033,7 +22317,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 91
+            "line": 104
           },
           "name": "assetHash",
           "overrides": "cdktn.IAsset",
@@ -22049,7 +22333,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 191
+            "line": 205
           },
           "name": "fileName",
           "type": {
@@ -22064,7 +22348,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 178
+            "line": 192
           },
           "name": "path",
           "type": {
@@ -22077,7 +22361,7 @@
           },
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 93
+            "line": 106
           },
           "name": "type",
           "type": {
@@ -22097,7 +22381,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/terraform-asset.ts",
-        "line": 23
+        "line": 24
       },
       "name": "TerraformAssetConfig",
       "properties": [
@@ -22109,7 +22393,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 25
+            "line": 26
           },
           "name": "path",
           "type": {
@@ -22124,7 +22408,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 29
+            "line": 30
           },
           "name": "assetHash",
           "optional": true,
@@ -22136,7 +22420,7 @@
           "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` 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`.",
+            "remarks": "`SOURCE` (the default) hashes the source path. `CUSTOM` uses the\n`assetHash` value verbatim and requires it to be set. `OUTPUT` hashes the\nsource too, unless a `bundler` is set — then it hashes the bundler's\nbuilt output, which forces an eager build (see `bundler`).\n\nIf `assetHash` is set, this must be `undefined` or `AssetHashType.CUSTOM`.",
             "stability": "experimental",
             "summary": "How the `assetHash` is derived."
           },
@@ -22151,6 +22435,25 @@
             "fqn": "cdktn.AssetHashType"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- the source is staged verbatim, with no build step",
+            "remarks": "Core ships no bundler; implement `IAssetBundler` or use one from a bundler\npackage. Under the default `SOURCE` hashing the build is deferred to synth\nand stays skippable; `OUTPUT` hashing builds eagerly to hash the artifact.\n`AssetType.FILE` is rejected, since bundler output is always a directory.\nSee `AssetStagingOptions.bundler`.",
+            "stability": "experimental",
+            "summary": "A bundler that builds the source into an artifact before staging."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/terraform-asset.ts",
+            "line": 73
+          },
+          "name": "bundler",
+          "optional": true,
+          "type": {
+            "fqn": "cdktn.IAssetBundler"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -22201,7 +22504,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/terraform-asset.ts",
-            "line": 27
+            "line": 28
           },
           "name": "type",
           "optional": true,
@@ -32075,6 +32378,6 @@
       "symbolId": "src/testing/matchers:TerraformConstructor"
     }
   },
-  "version": "0.25.0-pre.38",
-  "fingerprint": "LjFkzc29xx+KpzHhre46HtYGzUkyDeaURcxkQT1pEo4="
+  "version": "0.25.0-pre.39",
+  "fingerprint": "Mm8DFV8p3EqPwv9VKU0HHSxr3LzTcN0VloMAb2Daxx0="
 }